Add first draft of marshalling spec

[polintos/scott/priv.git] / idl / addrspace.idl

// AddrSpace
//
// These are the interfaces through which operations are performed on
// virtual and physical address spaces.
//
 
namespace Mem;

// There are two main kinds of mappable objects:
// 1. Objects that can be mapped directly into physical address space. 
//    This includes memory, device I/O, nested AddrSpaces, etc.  Objects
//    with this capability implement the Mappable interface.
// 2. Objects that are mapped by copying the content into RAM
//    (disks, remote objects, dynamically generated data, etc.)
//    These objects implement the Cacheable interface.
//  
// Type #1 is simple; all it needs to do is translate mappable offsets
// into physical.  Type #2 requires an intervening Cache to manage the
// backing RAM store.  Memory-like type #1 objects should also implement
// Cacheable so that they can be used remotely.
//
// Address spaces may be stacked, such that (for example) a debugger maps
// an application which maps a file which maps a filesystem which maps a
// RAID volume which maps several physical disks; only the disks would be
// represented by Caches, everything else by AddrSpaces.  Changes at any
// level immediately (well, before the operation finishes) propagate up
// to the page tables higher levels, and clone() will work at any level
// (and can make either the old or new address space the anonymous-
// memory-using "shadow" object).  Stacked address spaces can also be
// used to implement access control.

struct Region inline {
        // Both bounds are inclusive
        ulong start, end;
};

struct RegionWithOffset inline : Region {
        ulong offset;
};

bitfield AccessFlags:3 {
        // Allow reads to this page.  On some platforms, this is assumed
        // if writes are allowed, due to hardware limitations.
        Read,
                
        // Allow writes to this page.
        Write,
        
        // Allow execution of code from this page.  On some platforms,
        // this is assumed if reads are allowed, due to hardware
        // limitations.
        Exec
};

interface BlockObject {
        guid: "4425AF91-52BE-11DA-BD60-000A95BB581A";

        // Returns the current size in blocks of the object.

        get_size(ulong size out);
        
        // Returns the object's block size in bytes.  Requests to map, read,
        // write, etc. this object must be done with this granularity.  The
        // block size must be a power of two.
        
        get_block_size(ulong block_size out);
};
   
// Finer grained mapping than the block size may be done via the virtual
// address space, but the AddrSpace will always request object->physical
// mappings that are a multiple of the block size.

interface Mappable : BlockObject {
        guid: "B8E7A0DF-EAB6-11D9-BEFB-000A95BB581A";
        
};

interface Cacheable : BlockObject {
        guid: "BB4C729D-EAB6-11D9-ADA2-000A95BB581A";

        // Add the pages in the specified region to the specified cache.
        // The start and end of the region will be aligned to the larger
        // of the page size and the block size.

        fill(Cache cache, Region region) async;
};

// This is the Mappable used to map a Cacheable object.  
// Calling get_subspace on a Cache returns a pure Mappable; holders of
// such a reference alone can only map it, not add or remove pages or
// change its cacheable.

interface Cache : Mappable {
        guid: "BD9A04F5-EAB6-11D9-A420-000A95BB581A";

        // Get and set the object mapped through this Cache.  Any other
        // methods when obj is null (or never set) throw an InvalidState
        // exception.  Calling set_cacheable while this Cache has any
        // current mappings throws an InvalidState exception.

        set_cacheable(Cacheable obj);
        get_cacheable(Cacheable obj out);
        
        // Add one or more pages to the cache.  Addr must be page-aligned, and
        // the size of buf must be a multiple of the page size.
        
        fill(ulong addr, octet[] buf push) async;
        
        // Add one or more zero-filled pages to the cache.  The region must
        // start and end on a page boundary.
        
        fill_zero(Region region) async;
        
        // Remove one or more pages from the cache.  The region must start and
        // end on a page boundary.  It is not an error to remove pages that are
        // not in the cache.
        
        remove(Region region);
        
        // Wait until all of the pages in the region have been added to the
        // cache.  It is the caller's responsibility to ensure that the adding
        // has been requested, and that blocking will not cause a deadlock. 
        // If there are multiple pages in the region, it is as if this method
        // were called sequentially on each page; the kernel will not check
        // whether previously checked pages have been removed while waiting
        // for later pages.
        
        block_on_region(Region region);
        
        // Like block_on_region, but returning a blocker suitable for use
        // with Thread.block_multi.
        
        region_blocker(Region region, Proc.Blocker blocker out);
};

bitfield AllocFlags {
        Zero,          // Zero out any freshly allocated memory.

        Insecure,      // It is not necessary to zero out the page after it
                       // is freed, unless the next allocator requests it.

        Commit,        // Commit the allocation to actual memory or
                       // swap, failing if this cannot be done.

        Lock,          // Only allocate actual memory, and lock it against
                       // swapping.  Fails if not enough actual RAM is
                       // available (either in general or in the caller's
                       // locked RAM quota).  If Lock is set, Commit is
                       // ignored.
        
        NoZeroLocal,   // Accept secure pages from the current address
                       // space without first zeroing.  Ignored if Zero is
                       // specified.  Overmap should be set to None when
                       // this is used, and every byte should be
                       // overwritten before data in any such pages is
                       // passed to another address space.

        Paranoid,      // Zero pages even when going to a NoZeroLocal allocator
                       // in the current address space.  Use this for pages which
                       // are particularly likely to contain sensitive data.
};

bitfield MapFlags {
        Fixed,         // Fail if the exact starting address is unavailable. 
                       // Otherwise, if the supplied starting address
                       // unavailable, the address space manager allocates a
                       // free region and returns it in "start".  If this
                       // behavior is explicitly desired (as it ususally is),
                       // "start" should contain all bits set, which is always
                       // invalid.  For non-process (stacked) address spaces,
                       // this flag is treated as always set.
        
        Replace,       // Atomically replace any existing mapping with the new
                       // mapping, rather than fail.  This flag is only
                       // meaningful if Fixed is set.

        CopyOnWrite,   // Share the mapped object only until it is written to;
                       // then, before the write takes place, copy the object. 
                       // It is undefined whether this mapping will receive
                       // the copy or the original.

        Snapshot,      // The mapped object will also be made CopyOnWrite, so
                       // that any writes to the mapped page via any mapping
                       // will cause a fault.  Thus, after the snapshot, the
                       // only changes that will be visible will be through
                       // the new mapping.  This is ideal for things like fork()
                       // and file versioning, and is used by AddrSpace.clone().
                       //
                       // If not set, then only the new mapping will be
                       // CopyOnWrite, so if another mapping updates the page
                       // before a write occurs through this mapping (thus
                       // breaking CopyOnWrite), the change will be visible in
                       // the new mapping.  This is ideal for private
                       // mappings, where all that is desired is that the new
                       // mapping cannot change the underlying object (while
                       // keeping the mapping writeable).
                       //
                       // Ignored if CopyOnWrite is not set.

        AccessFlags access:3,
                       // These are the requested read/write/execute
                       // permissions on the mapping.  A missing permission (or
                       // unmapped page) at any level in an address space stack
                       // will cause a MemoryFault, even if the page is mapped
                       // with the needed permissions at the top level.  The
                       // map() call will not fail due to such a condition.

        enum OverMap:2 {
                None,       // Never map non-argument memory to a callee's address
                            // space.

                ReadOnly,   // Allow read-only mappings of non-argument data within
                            // the same page as an argument into the callee's
                            // address space.

                ReadWrite   // Allow all mappings of non-argument data within the
                            // same page as an argument into the callee's address
                            // space.
        } overmap
};

interface AddrSpace {
        guid: "BF9D2070-EAB6-11D9-A2D2-000A95BB581A";

        const ulong unspecified_start = 0xffffffffffffffff;
        
        // Return the mappable associated with this address space, which can
        // be used to allow another address space to stack with this one.
        // The mappable handle only allows pages to be mapped; it does not
        // allow any changes to the mappings, nor can a handle to the AddrSpace
        // be obtained from it.  This method must always return the same
        // Mappable object when called on the same AddrSpace.
        
        get_mappable(Mappable ma out);
        
        // Create a new AddrSpace that is a copy-on-write clone of this AddrSpace.
        // This method is used to implement fork() and in-memory file versioning,
        // and could also be used to assist garbage collection and other purposes.
        //
        // By default, the old address space continues to be backed by
        // whatever Mappables were in use, and pages in the new address space
        // are backed by anonymous memory when a page in either is written to. 
        // If flags.Reverse is true, though, this is reversed, which is useful
        // when versioning a file to make the new version the one that gets
        // stored to disk.
        //
        // The upstream address space is also marked as copy-on

        clone(AddrSpace addrspace out, CloneFlags flags);
        
        bitfield CloneFlags {
                Reverse
        };
        
        // Mappable must be implemented by the local kernel, and must hold
        // read/write/exec permissions appropriate for the MapFlags given.
        
        map(Mappable ma, Region region, ulong vstart inout, MapFlags flags);
        unmap(Region region);

        // Set the flags on all pages in the region.  CopyOnWrite can be
        // set, but not cleared, using this method.  Fixed is ignored.

        set_mapflags(Region region, MapFlags flags);
        
        // Returns the flags on the given region, if all pages have the
        // same flags (except for CopyOnWrite, which is not returned by
        // this method, as it can be asynchronously cleared).
        
        get_mapflags(Region region, MapFlags flags out, bool all_same out);
        
        // Returns the Mappable that covers the specified range, and the offset
        // into the Mappable that corresponds to the first page in the region. 
        // If any pages within the range are not mapped, or if more than one
        // Mappable is mapped within the region, or if the offsets into the
        // Mappable are not contiguous, then NULL is returned in ma.
        //
        // This is used to implement mremap().
        
        get_mapping(Region region, Mappable ma out, ulong offset out);

        // Returns the minimum page size (and thus mapping size/alignment)
        // supported in this address space.  An attempt to create a mapping
        // that violates this will result in an InvalidArgument exception.

        get_page_size(uint page_size out);

        // Returns the minimum alignment supported for mapping requests;
        // (vstart % min_align) must equal (region.start % min_align).  This
        // is at least the minimum page size, but may be more on certain
        // hardware, such as virtually-indexed-physically-tagged caches, where
        // larger alignment is needed to ensure the absence of cache aliases. 
        // An attempt to create a mapping that violates this will result in an
        // InvalidArgument exception.
        
        get_min_align(uint min_align out);
};

interface AllocHandle {
        guid: "CB029266-EAB6-11D9-BCA0-000A95BB581A";

        get_regions(Region[] regions out);
        
        // Free a portion of an allocation.  To free all of an allocation,
        // simply release all references to the handle.  Each region shall
        // start and end on block size boundaries.  Throws OperationNotSupported
        // if the allocator does not support partial frees.
        
        free(Region[] regions);
};

interface Allocator {
        guid: "CCF5D83C-EAB6-11D9-8BB7-000A95BB581A";

        const ulong unspecified_start = 0xffffffffffffffff;

        bitfield AllocFlags {
                // If set, fail if the exact starting address is unavailable (or if
                // the allocator does not support caller-supplied starting
                // addresses).
                //
                // Otherwise, if the supplied starting address unavailable, the
                // allocator allocates a free region and returns it in "start".  If
                // this behavior is explicitly desired (as it ususally is), "start"
                // should be set to unspecified_start, which is always invalid. 
                // Using unspecified_start may be faster than specifying other
                // invalid addresses (as the allocator can check for this value
                // rather than checking address availability), and zero should not
                // be used for this purpose as it may be a valid address.
                
                Fixed
        };

        alloc(ulong start inout, ulong len, AllocFlags flags,
              AllocHandle handle out);
};

interface GenericAllocator : Allocator {
        guid: "D033DD3A-EAB6-11D9-96E4-000A95BB581A";

        // Set the minimal block size used by the allocator.
        // This can only be done before any alloc() or
        // add_regions() calls; an InvalidState exception may
        // be thrown otherwise.
        
        set_block_size(ulong block_size);
        
        // Make one or more regions available for allocations.
        // The regions may not overlap each other or any existing
        // regions (whether or not allocated).  Regions may not
        // be removed once added using this interface; allocators
        // may optionally provide a mechanism for doing so.
        
        add_regions(Region[] regions);
};