Add first draft of marshalling spec

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

// System exceptions
//
// These are all of the exceptions that derive from SystemException, 
// which can implicitly be thrown from any method.
//
// Common fields:
//   exp: explanation string, may be NULL
//   param: index (starting from 0) of the parameter which is causing
//          the problem, or -1 if unspecified.  This should only be
//          specified for parameters of IDL methods; if thrown from a
//          language function/method which does not know the relevant
//          parameter in the IDL method, it should use an explanation
//          string instead (and not use the index of its own parameter).

namespace Exceptions;

// The base Exception struct; all exceptions derive from this.
struct Exception virtual {
        guid: "D88F50D2-2877-11DA-84AD-00112431A05E";

        // The previous exception frame (i.e. that which threw this one),
        // or null for the original exception frame.  Linkage shall be
        // preserved whenever an exception is either propagated or
        // raised within an exception handling block.
           
        Exception prev;

        // Object and method of the thrower of this frame, if it was rethrown
        // due to crossing an IDL method boundary.  Otherwise, both fields are
        // null.
           
        Object object;
//      Method method; // Fix throw_idl when this is uncommented.
        
        // Language and machine specific information about whence an exception
        // was thrown.
        
        ExceptionOriginInfo origin;
};

struct ExceptionOriginInfo virtual {
        guid: "DBCF8333-2877-11DA-B66E-00112431A05E";
};

// This struct, or one derived from it, shall be used for an
// exception's origin field if it is from native code (and
// thus can refer to instructions by machine address).
   
struct NativeCodeExceptionOriginInfo : ExceptionOriginInfo {
        guid: "E1B3FAC6-2877-11DA-8493-00112431A05E";

        // Address of the faulting or throwing instruction
        ulong pc;
};

namespace Std;

struct SystemException : Exception {
        guid: "E5204D31-2877-11DA-A833-00112431A05E";
        
        bitfield Flags:32 {
                // Exception was thrown by the kernel.  This bit is stripped when
                // the exception passes through the ORB.  It can be used to verify
                // that MemoryFault and similar exceptions refer to an actual fault
                // of the current address space when deciding whether to abort the
                // process.

                Kernel,
                
                // Exception was generated automatically by the ORB, rather than
                // thrown by a method.  Some types of exceptions have fixed
                // explanation string formats (and possibly other field usages) for
                // ORB generated exceptions, but a free form explanation field for
                // method-thrown exceptions.
                
                ORB
        } flags;
};


// The MemoryFault exception indicates that the throwing method
// attempted to perform an invalid memory access, and the MemoryFault
// trap was not handled by the faulting process.

struct MemoryFault : SystemException {
        guid: "EAA266EC-2877-11DA-9C5D-00112431A05E";

        // Address that the method tried to access
        ulong addr;             

        // Address of the faulting instruction, 0 if from kernel
        ulong pc;

        // Process of faulting method
        Proc.Process proc;

        // Architecture specific data
        ArchMemoryFault arch;   

        enum Type {
                // The fault occured on a memory load
                Load,
                
                // The fault occured on a memory store
                Store,
                
                // The fault occured on an instruction fetch
                IFetch
        } type;
        
        enum Cause {
                // The faulting address was not mapped
                Unmapped,       
                
                // The requested operation was prohibited
                Protected,      
                
                // An I/O error occured accessing a memory mapped region, or an
                // uncorrectable memory error was encountered.
                IOError,
        };
};

struct ArchMemoryFault virtual
{
        guid: "EF25EED2-2877-11DA-83EF-00112431A05E";
};

// The OutOfMemory exception indicates that insufficient physical memory
// is available to perform the requested operation, including implicit
// allocations of memory such as memory mapped accesses, shared copy on
// write regions, and zero pages (though implicit allocation failures
// cannot happen unless overcommit is enabled).  This exception is only
// thrown after a System.Traps.ReduceMemoryUsage trap has been delivered
// and failed to free sufficient memory.

struct OutOfMemory : SystemException {
        guid: "F21A198C-2877-11DA-92DB-00112431A05E";
};

// Like OutOfMemory, but indicates that disk space, virtual
// address space, etc. has been exhausted.

struct OutOfSpace : SystemException {
        guid: "6267B5C2-D2E4-11DA-831C-00112431A05E";
        char[] exp immutable;
};

// Like OutOfSpace, but indicates that a specific requested resource
// (such as an IRQ number or network port) is already in use.  Use
// OutOfSpace instead for resources that are allocated rather than
// claimed.

struct ResourceBusy : SystemException {
        guid: "0EFB88FC-2878-11DA-AEB9-00112431A05E";
        
        int param;  // Index of parameter with problem, or -1 if
                    // unspecified, or if not due to a bad param.
        char[] exp immutable;
};

/* The InstrFault exception indicates that the throwing method tried
   to execute an invalid or privileged instruction, and the
   InstrFault trap was not handled by the faulting process. */

struct InstrFault : SystemException {
        guid: "F5CAE5F8-2877-11DA-BB6C-00112431A05E";

        // Address of the faulting instruction
        ulong pc;

        // Process of faulting method
        Proc.Process proc;

        // Architecture specific data
        ArchInstrFault arch;
};

struct ArchInstrFault virtual
{
        guid: "F9CE2A55-2877-11DA-9C92-00112431A05E";
};

struct Token {
};

// The TokenFault exception indicates that the caller does not
// currently have the necessary token to complete the requested method.

struct TokenFault : SystemException {
        guid: "011B018D-2878-11DA-9F80-00112431A05E";

        Token token;     // Token that is required but not present

        enum Type {
                Thrown,      // The TokenFault was explicitly thrown by a 
                             // called method
                Call,        // The token was required for a method call
                Open,        // The token was required to obtain a handle on
                             // the object
        } type;

        bitfield Flags:32 {
                restartable:1   // The method may be restarted if the requested
                                // token is acquired.  Any TokenFaults with this
                                // flag set are handled in a transparent manner,
                                // by either acquiring the token and retrying or
                                // clearing the bit and propagating.  Any method
                                // that throws a restartable TokenFault must
                                // be cleanly restartable with no side effects.
        };

        // For Call and Open, this is the object associated with the prohibited
        // operation.  Explicitly thrown token faults may optionally use this
        // field.
        
        Object object;

        // For Call, this is the method that could not be called.  Explicitly
        // thrown token faults may optionally use this field.

//      Method method; // Fix throw_idl when this is uncommented.

        char[] exp immutable;
};

// InvalidArgument may be thrown when an argument or combination
// of arguments is invalid.

struct InvalidArgument : SystemException {
        guid: "04865176-2878-11DA-9F87-00112431A05E";

        int param;  // Index of problematic parameter, counting from 0,
                    // or -1 if not specified.
        char[] exp immutable;
};

// GeneralFailure, as the name implies, is a general purpose exception
// to indicate failure conditions not covered by existing exceptions.
// It is generally preferable to define a specific exception for
// forseeable causes of failure.

struct GeneralFailure : SystemException {
        guid: "094C37A1-2878-11DA-914D-00112431A05E";
        
        char[] exp immutable;
};

// InvalidState is thrown when a method is called on an object which
// is not in a state in which the operation is meaningful.

struct InvalidState : SystemException {
        guid: "0C361FFF-2878-11DA-ABC1-00112431A05E";
        
        char[] exp immutable;
};


struct OperationNotSupported : SystemException {
        guid: "119C274E-2878-11DA-B3B2-00112431A05E";
        
        char[] exp immutable;
};

// InvalidReference is thrown when a method is called on a reference
// that no longer points to a valid object, or if such a dangling
// reference is found in the method's parameters.

struct InvalidReference : SystemException {
        guid: "16E5E64F-2878-11DA-916E-00112431A05E";

        int param;  // Index of parameter with problem, or -1 if the method
                    // was invoked on a dangling reference.  If the invalid
                    // reference is in the object's internal state, then
                    // InvalidState should be thrown instead.
                           
        char[] exp immutable; 
                    // When thrown by the ORB, NULL if param is -1 or if the
                    // dangling reference was passed directly as a parameter. 
                    // If, however, the dangling reference was in a struct,
                    // this provides the path to the bad parameter (e.g. if
                    // the third parameter of a method is a struct with a
                    // member "foo", and "foo" is a struct with a member
                    // "bar", and bar is a dangling object reference, exp will
                    // contain "foo.bar").
                    //
                    // When not thrown by the ORB, this is a free form
                    // explanation field (and may be NULL).
};

// Thrown when more references are attempted to be dropped than exist.
// "refs" is the number of references, and "released" is the number
// of releases asked for.

struct RefCountException : SystemException {
        guid: "1EEDC277-9D71-415E-AA8D-19C52FDB72F2";
        
        int refs, released;
};