Add first draft of marshalling spec

[polintos/scott/priv.git] / idlcomp / compileddef.h

#ifndef IDLC_COMPILEDDEFS_H
#define IDLC_COMPILEDDEFS_H

#include <stdint.h>

#if !defined(BITFIELD_LE) && !defined(BITFIELD_BE)
#error Please define your bitfield endianness (BITFIELD_LE or BITFIELD_BE).
#endif

// This is the compiled representation of definitions when stored on
// a legacy filesystem (as opposed to native object storage). 
// Normally, a standard encoding would be used to map objects to
// directories and files; however, such encodings cannot be used
// before they exist.  This special mapping allows the system to be
// bootstrapped from a legacy system.
//
// As this is a transitional representation, and IDL management is
// not performance critical, emphasis has been placed on simplicity
// rather than efficiency.  In particular, I don't want to write
// throw-away code to compensate for most filesystems' inability to
// deal with small files efficiently, nor do I want to muck around
// with storing the compiled definitions in textual form (thus
// needing to parse them *again*; I want to keep that out of the
// ORB).  Dot files and directories are used rather than the more
// straightforward way of keeping the namespace under its own member
// in order to make the compiled definitions easier to browse with
// normal utilities (in the final system, you'll be able to use a
// custom view that arranges it however you want; however, Unix
// doesn't have custom filesystem views).
//
// I have tried to make the definitions close to what could be
// emitted by an IDL compiler, minus the hierarchical relationship
// (which won't exist on a legacy filesystem).  These definitions
// require C++ (plus C99 stdint.h); C will choke on the assumed
// struct namespace behavior (among other things).
//
// Each definition is represented by a directory.  If the definition is
// for a non-generic namespace (i.e. it is for a struct, interface,
// bitfield, etc.), the definition itself is placed in a file called
// ".self" inside the directory.  The file contains a CompiledDefHeader
// struct followed by the appropriate type-specific struct.
//
// The non-dotted contents of the directory are the contents of the
// definition's namespace, if any.  Anonymous types are given the
// name "_anon_<unique>", where <unique> is an arbitrary non-conflicting
// name.
// 
// A compiled definition file may be either big or little endian; if
// magic_reversed is found, then all integers in the file must be
// reversed prior to usage.
//
// Bitfields, on the other hand, must be arranged in a little endian
// format (i.e. the first field gets the least significant bits; the byte
// order of the containing integer is the same as for non-bitfield
// integers).  Bitfields generated by idlc will contain padding and
// reversed members if the target has big-endian bitfields.

struct CompiledDefHeader {
        static const uint32_t magic_normal = 0x2d29c8a9;
        static const uint32_t magic_reversed = 0xa9c8292d;

        uint32_t magic;        // magic_normal or magic_reversed

        enum Type {
                NameSpace,
                BasicType,
                Datum,
                Interface,
                Method,
                Param,
                Struct,
                Enum,
                BitField,
                Alias,
                TypeDef
        };
        
        // One of the above types; the enum isn't used directly, as the
        // size is not guaranteed.
        int32_t type;
};

struct CompiledNameSpace {
        // The length of the string in bytes (not characters), excluding
        // the null terminator.

        int32_t length;
        
        // The fully qualified name of the namespace follows, as a
        // null-terminated UTF-8 string.  This allows the namespace
        // to be mounted by merely supplying its filesystem path,
        // without having to specify the mount point.
};

// This struct does not appear standalone, but is included in various
// structs that can refer to arrays.
struct CompiledArray {
        // Inclusive lower and upper bounds of the array.  If the
        // array has no upper bound, [1] should be -1.  If the array
        // has no lower bound, [0] should be 0.  If this is not an
        // array, both should be 0.
        
        int64_t bounds[2];
};

struct CompiledBasicType {
        // Size of the type, as follows:
        //   Byte: 8
        //   Short: 16
        //   Int: 32
        //   Long: 64
        //   FShort: 32
        //   FLong: 64
        //   Bool: 0 (actual size is implementation defined)
        //
        // Other sizes may be used within bitfields (up to a max of 64 bits).

        int32_t bits;

        // Unsigned, Float, and Bool are mutually exclusive.

        union Flags {
                struct Field {
#ifdef BITFIELD_LE
                        unsigned int Unsigned:1;
                        unsigned int Float:1;
                        unsigned int Bool:1;
                        unsigned int TypeDef:1;
#else
                        unsigned int _pad:28;

                        unsigned int TypeDef:1;
                        unsigned int Bool:1;
                        unsigned int Float:1;
                        unsigned int Unsigned:1;
#endif
                } field;

                uint32_t raw;
                
                struct init {
                        static const uint32_t Unsigned = 1 << 0;
                        static const uint32_t Float = 1 << 1;
                        static const uint32_t Bool = 1 << 2;
                        static const uint32_t TypeDef = 1 << 3;
                };
        } flags;
        
        uint64_t guid[2];
        
        CompiledArray array;
};


struct CompiledAlias {
        // The length of the string in bytes (not characters), excluding
        // the null terminator.

        int32_t length;
        
        // The name of the aliased symbol follows, as a null-terminated
        // UTF-8 string.  This will be the final symbol, and not an alias.
};

// A CompiledDatum is used for data fields in a structure, bitfield, or
// enumeration.

struct CompiledDatum {
        // This is a description of the datum's type, if it is not a named type.
        // This is ignored (except the array part) if "type" is non-empty.

        CompiledBasicType basictype;
        
        // Const value(s); cast to the appropriate type.  For Bool, cast to
        // Byte; 0 is false, 1 is true.  Extend all types to 64-bits.
        // ucon is also used for bitfield element sizes.

        union {
                int64_t icon;
                uint64_t ucon;
                double fcon;
                char data[8];
        };

        // Const can only be used for basic types (both named and unnamed);
        // Immutable is used for non-initialized const fields.  Invalid is
        // only used internally by idlc; it is reserved in the file format.
        
        union Flags {
                struct Field {
#ifdef BITFIELD_LE
                        unsigned int Const:1;
                        unsigned int Invalid:1;
                        unsigned int Inline:1;
                        unsigned int Immutable:1;
#else
                        unsigned int _pad:28;

                        unsigned int Immutable:1;
                        unsigned int Inline:1;
                        unsigned int Invalid:1;
                        unsigned int Const:1;
#endif
                } field;

                uint32_t raw;

                struct init {
                        static const uint32_t Const = 1 << 0;
                        static const uint32_t Invalid = 1 << 1;
                        static const uint32_t Inline = 1 << 2;
                        static const uint32_t Immutable = 1 << 3;
                };
        } flags;

        // If it's a named type, this points to the type.
        CompiledAlias type;
};

// Methods, member types, member constants, etc. go in the namespace. 
// Methods are ordered; all others are unordered. 

struct CompiledInterface {
        int32_t num_methods;
        int32_t num_supers;
        
        uint64_t guid[2];
        
        // An array of num_methods + num_supers length of CompiledAliases
        // representing methods in declared order follows, and then
        // superclasses in declared order, follows.  The names of metods shall
        // consist only of the final component, with no namespaces prepended. 
        // The names of superclasses are fully namespace-qualified.  Each
        // CompiledAlias shall begin on a 4-byte boundary.
};

// Parameters go in the namespace, and are ordered according to the
// list contained in this struct.  Exceptions thrown are unordered
// Aliases in a subdirectory called ".exceptions", with arbitrary
// names.

struct CompiledMethod {
        union Flags {
                struct Field {
#ifdef BITFIELD_LE
                        unsigned int Async:1;
#else
                        unsigned int _pad:31;

                        unsigned int Async:1;
#endif
                } field;

                uint32_t raw;

                struct init {
                        static const uint32_t Async = 1 << 0;
                };
        } flags;

        int32_t num_entries;
        
        // An array of num_entries length of CompiledAliases representing
        // parameters in declared order follows.  Each name shall be as in
        // CompiledInterface, without namespace qualification.
};

// A param isn't a namespace; however, it is a directory.  In addition to
// the ".self" file, the directory contains a "type" Alias file.
struct CompiledParam {
        // This is a description of the parameter's type, if it is not a
        // named type.  This is ignored (except the array part) if "type"
        // is non-empty.

        CompiledBasicType basictype;

        union Flags {
                struct Field {
#ifdef BITFIELD_LE
                        unsigned int In:1;
                        unsigned int Out:1;
                        
                        unsigned int Shared:1;
                        unsigned int Push:1;
                        unsigned int Inline:1;
                        unsigned int Immutable:1;
#else
                        unsigned int _pad:26;

                        unsigned int Immutable:1;
                        unsigned int Inline:1;
                        unsigned int Push:1;
                        unsigned int Shared:1;

                        unsigned int Out:1;
                        unsigned int In:1;
#endif
                } field;
                
                uint32_t raw;

                struct init {
                        static const uint32_t In = 1 << 0;
                        static const uint32_t Out = 1 << 1;
                        static const uint32_t Shared = 1 << 2;
                        static const uint32_t Push = 1 << 3;
                        static const uint32_t Inline = 1 << 4;
                        static const uint32_t Immutable = 1 << 5;
                };
        } flags;

        
        // If it's a named type, this points to the type.
        CompiledAlias type;
};

// Fields, member types, member constants, etc. go in the namespace. 
// All but fields are unordered.

struct CompiledStruct {
        union Flags {
                struct Field {
#ifdef BITFIELD_LE
                        // Struct has a superstruct.

                        unsigned int Super:1;

                        // Struct has run-time type information.  This requires that
                        // Super be set.

                        unsigned int Virtual:1;
                        
                        // Struct defaults to "inline" when declared in a struct.
                        // This is mandatory for anonymous structs.
                        
                        unsigned int Inline:1;
#else
                        unsigned int _pad:29;

                        unsigned int Inline:1;
                        unsigned int Virtual:1;
                        unsigned int Super:1;
#endif
                } field;
                
                uint32_t raw;

                struct init {
                        static const uint32_t Super = 1 << 0;
                        static const uint32_t Virtual = 1 << 1;
                        static const uint32_t Inline = 1 << 2;
                };
        } flags;

        int32_t num_entries;

        uint64_t guid[2];
        
        // An array of num_entries length of CompiledAliases representing
        // fields in declared order follows.  Each name shall be as in
        // CompiledMethod.  If the Super flag is set, then another
        // fully-qualified CompiledAlias is placed at the end of the array.
};

// Enum entries are unsigned BasicDatums of the specified size.

struct CompiledEnum {
        // Size of enumeration type
        int32_t bits;
        
        int32_t num_entries;
        
        uint64_t guid[2];

        // An array of num_entries length of CompiledAliases representing
        // values in declared order follows.  Each name shall be as in
        // CompiledMethod.
};

// BitField fields are unsigned BasicDatums and Enum Datums of
// arbitrary size, which must add up to at most "bits".

struct CompiledBitField {
        // Width of bitfield
        int32_t bits;
        
        int32_t num_entries;

        uint64_t guid[2];

        // An array of num_entries length of CompiledAliases representing
        // fields in declared order follows.  Each name shall be as in
        // CompiledMethod.
};

#endif