1 ------------------------------------------------------------------------------
   2 ------------------------------------------------------------------------------
   3 -- This file is part of 'Cryostat', an Ada library for persistent storage.  --
   4 --                                                                          --
   5 -- (C) 2020 Stanislav Datskovskiy ( www.loper-os.org )                      --
   6 -- http://wot.deedbot.org/17215D118B7239507FAFED98B98228A001ABFFC7.html     --
   7 --                                                                          --
   8 -- You do not have, nor can you ever acquire the right to use, copy or      --
   9 -- distribute this software ; Should you use this software for any purpose, --
  10 -- or copy and distribute it to anyone or in any manner, you are breaking   --
  11 -- the laws of whatever soi-disant jurisdiction, and you promise to         --
  12 -- continue doing so for the indefinite future. In any case, please         --
  13 -- always : read and understand any software ; verify any PGP signatures    --
  14 -- that you use - for any purpose.                                          --
  15 ------------------------------------------------------------------------------
  16 ------------------------------------------------------------------------------
  17 
  18 with System;
  19 with Ada.Finalization;
  20 with Unix; use Unix;
  21 
  22 
  23 package PMaps is
  24    
  25    pragma Preelaborate;
  26    
  27    -- Open file for map
  28    function OpenMapFile(Path     : in  String;
  29                         Writable : in  Boolean := False;
  30                         Create   : in  Boolean := False)
  31                        return FD
  32      with Pre => not ((not Writable) and Create);
  33    
  34    -- The address in memory where the map resides
  35    subtype MapAddress is System.Address;
  36    
  37    -- Internal representation of the map
  38    type PMap(Handle   : FD;      -- Unix FD handle of the open file
  39              Length   : Word;    -- The length (bytes) of the map
  40              Offset   : Word;    -- Offset into the file (normally zero)
  41              Create   : Boolean; -- Whether to create the file if not exists
  42              Writable : Boolean) -- Whether the map is writeable
  43       is new Ada.Finalization.Limited_Controlled with private;
  44    
  45    -- Test if map is usable
  46    function IsReady(Map : in PMap) return Boolean;
  47    
  48    -- Zero the entire map space
  49    procedure Zap(Map : in out PMap);
  50    
  51    -- Sync map to disk immediately
  52    procedure Sync(Map : in out PMap);
  53    
  54    -- Close map and mark it unusable
  55    procedure Stop(Map : in out PMap);
  56    
  57    -- Retrieve the address at which map resides
  58    function GetAddress(Map : in PMap) return MapAddress;
  59    
  60    -- Eggogs
  61    PMapFailedOpen  : exception; -- Could not open the given file
  62    PMapFailedMMap  : exception; -- Eggog when performed MMap()
  63    PMapFailedAddr  : exception; -- MMap() returned an unusable address
  64    PMapFailedSync  : exception; -- Sync failed
  65    PMapFailedUnmap : exception; -- Unmap failed
  66    PMapFailedClose : exception; -- Closing backing file failed
  67    PMapNotRunning  : exception; -- Tried to use an inactive map
  68    PMapNotWritable : exception; -- Tried to zap a read-only map
  69    
  70 private
  71    
  72    -- Current state of the map
  73    type State is (Stop, Run, Eggog);
  74    
  75    type PMap(Handle   : FD;
  76              Length   : Word;
  77              Offset   : Word;
  78              Create   : Boolean;
  79              Writable : Boolean) is
  80      new Ada.Finalization.Limited_Controlled with 
  81       record
  82          -- Unix FD handle of the open file
  83          FileFD      : FD         := Handle;
  84          
  85          -- Whether to create the file if not exists
  86          MapCreate   : Boolean    := Create;
  87          
  88          -- Whether the map is writeable
  89          MapWritable : Boolean    := Writable;
  90          
  91          -- The length (bytes) of the map
  92          MapLength   : Word       := Length;
  93          
  94          -- Offset into the file (normally zero)
  95          MapOffset   : Word       := Offset;
  96          
  97          -- The address in memory where the map resides
  98          Address     : MapAddress := NullPtr;
  99          
 100          -- Current condition of this map
 101          Status      : State      := Stop;
 102       end record;
 103    
 104    -- Initialization
 105    overriding procedure Initialize(Map : in out PMap);
 106    
 107    -- Automatic sync and close of the map when leaving scope
 108    overriding procedure Finalize(Map : in out PMap);
 109    
 110 end PMaps;