osevm_lib.h

Go to the documentation of this file.

/*
  Copyright (c) 2019-23 John MacCallum Permission is hereby
  granted, free of charge, to any person obtaining a copy of this
  software and associated documentation files (the "Software"), to
  deal in the Software without restriction, including without
  limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and
  to permit persons to whom the Software is furnished to do so,
  subject to the following conditions:
 
  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.
 
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  OTHER DEALINGS IN THE SOFTWARE.
*/
 
#ifndef OSEVM_LIB_H
#define OSEVM_LIB_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define OSEVM_WRAP_DECL(name)           \
    void osevm_##name(ose_bundle bundle);
 
/* The wrappers below clear the child's errno before doing anything.
 
   errno on /_s is a return channel for one call: cleared on entry, its value
   afterwards means "this call failed". Without the clear, a value left there
   by anything earlier is indistinguishable from one this operation set, and
   gets charged to whichever instruction runs next -- the "every instruction
   leaves residue" bug. A host that calls
   ose_drop() on an empty stack during setup is enough to trigger it, and the
   diagnostic then lands on the first instruction of the first program.
 
   Nothing is lost by discarding it. Each wrapper propagates its own failure
   to `bundle` before returning, and the clear only touches the child, so
   errors still accumulate on the VM within an instruction. What goes away is
   a stale value that nobody was ever going to attribute correctly. */
 
#define OSEVM_WRAP_DEFN(name)                   \
    void osevm_##name(ose_bundle bundle)    \
    {                                           \
        ose_bundle vm_s = OSEVM_STACK(bundle);  \
        enum ose_errno e = OSE_ERR_NONE;        \
        ose_errno_set(vm_s, OSE_ERR_NONE);      \
        ose_##name(vm_s);                       \
        if((e = ose_errno_get(vm_s)))           \
        {                                       \
            ose_errno_set(bundle, e);           \
            ose_errno_set(vm_s, OSE_ERR_NONE);  \
        }                                       \
    }
 
#define OSEVM_WRAP_DEFPRED(name)                \
    void osevm_##name(ose_bundle bundle)   \
    {                                           \
        ose_bundle vm_s = OSEVM_STACK(bundle);  \
        int32_t i;                              \
        ose_errno_set(vm_s, OSE_ERR_NONE);      \
        i = ose_popInt32(vm_s);                 \
        enum ose_errno e = OSE_ERR_NONE;        \
        if((e = ose_errno_get(vm_s)))           \
        {                                       \
            ose_errno_set(bundle, e);           \
            ose_errno_set(vm_s, OSE_ERR_NONE);  \
        }                                       \
        bool r = ose_##name(i);                 \
        ose_pushInt32(vm_s, r == true ? 1 : 0); \
    }
 
 
/* A frame is one element of the dump.
 *
 * One element, one ose_spaceAvailable(), one answer -- which is the
 * invariant osevm_return() needs and cannot otherwise assume. Built instead
 * from four appends, a frame can be written in part: ose_copyBundle() asks
 * ose_incSize(), is refused when the register is full, and returns without
 * writing. With /_d nearly full the small environment marker fits and goes
 * in while input, stack and control do not, leaving a frame with one element
 * where it should have four. osevm_return() then pops four, takes the
 * missing three out of the frames underneath, and the dump's structure is
 * gone with nothing able to tell that it happened.
 *
 * An empty register is omitted. Three of a frame's four are usually empty
 * bundles at 16 bytes plus a 4-byte prefix; over 5,000 frames of a recursion
 * that came to 7% of frame bytes, against the 20 bytes this shape's wrapper
 * adds to an average frame of 769 -- about 5% of the dump given back. Which
 * registers are carried is recorded in the frame bundle's timetag, where a
 * bundle header already spends eight bytes that nothing in this path reads.
 * A layer above this one keeps its own markers in the same eight bytes, for
 * the same reason, and neither reads the other's: a frame's timetag belongs
 * to the dump, and the dump belongs here.
 *
 *     [int32 size]["#bundle\0"][int32 magic][int32 mask][the carried ones]
 *
 * A register that is not carried is restored empty, which is exactly what
 * restoring an empty saved copy did before: the shape changed and the
 * semantics did not.
 *
 * There is no compatibility story for frames written in the older shape.
 * The magic is what makes an old machine a crash with a name on it rather
 * than a silent misread.
 */
#define OSEVM_FRAME_MAGIC 0x2346524D /* "#FRM" */
enum
{
    OSEVM_FRAME_INPUT   = 1,
    OSEVM_FRAME_ENV     = 2,
    OSEVM_FRAME_STACK   = 4,
    OSEVM_FRAME_CONTROL = 8,
    /* The stack below its topmost element, which is the stack the callee
       does not get: the element on top is the body about to run, and a
       caller that saves the whole stack gets it handed back on top of
       whatever the body left. #osevm_exec1 says this by saving no stack at
       all, because it has already moved that element into the input. An
       interpreting client whose own exec has work to interleave saves the
       rest, and has to say which rest. */
    OSEVM_FRAME_STACK_BELOW = 16
};
 
int osevm_pushFrame(ose_bundle osevm,
                    int32_t which,
                    const char * const env,
                    int32_t envlen);
 
void osevm_exec1(ose_bundle osevm);
 
void osevm_exec2(ose_bundle osevm);
 
void osevm_exec3(ose_bundle osevm);
 
void osevm_call(ose_bundle osevm);
 
void osevm_exec(ose_bundle osevm);
 
void osevm_if(ose_bundle osevm);
 
void osevm_dotimes(ose_bundle osevm);
 
void osevm_copyRegisterToElem(ose_bundle osevm);
void osevm_appendElemToRegister(ose_bundle osevm);
void osevm_replaceRegisterWithElem(ose_bundle osevm);
void osevm_moveElemToRegister(ose_bundle osevm);
void osevm_copyElemToRegister(ose_bundle osevm);
void osevm_apply(ose_bundle osevm);
void osevm_map(ose_bundle osevm);
void osevm_return(ose_bundle osevm);
 
void osevm_version(ose_bundle osevm);
void osevm_assignStackToEnv_impl(ose_bundle osevm,
                               ose_bundle env,
                               int replace,
                               int new_msg_first,
                               char bundle_typetag);
void osevm_assignStackToEnv(ose_bundle osevm);
void osevm_lookupInEnv_impl(ose_bundle osevm);
void osevm_lookupInEnv(ose_bundle osevm);
void osevm_plookupInEnv_impl(ose_bundle osevm);
void osevm_plookupInEnv(ose_bundle osevm);
void osevm_funcall(ose_bundle osevm);
void osevm_makeRegister(ose_bundle osevm);
void osevm_quote(ose_bundle bundle);
 
OSEVM_WRAP_DECL(toType)
OSEVM_WRAP_DECL(toInt32)
OSEVM_WRAP_DECL(toFloat)
OSEVM_WRAP_DECL(toString)
OSEVM_WRAP_DECL(toBlob)
OSEVM_WRAP_DECL(appendByte)
#ifdef OSE_PROVIDE_TYPE_SYMBOL
OSEVM_WRAP_DECL(toSymbol)
#endif
#ifdef OSE_PROVIDE_TYPE_DOUBLE
OSEVM_WRAP_DECL(toDouble)
#endif
#ifdef OSE_PROVIDE_TYPE_INT8
OSEVM_WRAP_DECL(toInt8)
#endif
#ifdef OSE_PROVIDE_TYPE_UINT8
OSEVM_WRAP_DECL(toUInt8)
#endif
#ifdef OSE_PROVIDE_TYPE_INT16
OSEVM_WRAP_DECL(toInt16)
#endif
#ifdef OSE_PROVIDE_TYPE_UINT16
OSEVM_WRAP_DECL(toUInt16)
#endif
#ifdef OSE_PROVIDE_TYPE_UINT32
OSEVM_WRAP_DECL(toUInt32)
#endif
#ifdef OSE_PROVIDE_TYPE_INT64
OSEVM_WRAP_DECL(toInt64)
#endif
#ifdef OSE_PROVIDE_TYPE_UINT64
OSEVM_WRAP_DECL(toUInt64)
#endif
#ifdef OSE_PROVIDE_TYPE_TIMETAG
OSEVM_WRAP_DECL(toTimetag)
#endif
#ifdef OSE_PROVIDE_TYPE_TRUE
OSEVM_WRAP_DECL(toTrue)
#endif
#ifdef OSE_PROVIDE_TYPE_FALSE
OSEVM_WRAP_DECL(toFalse)
#endif
#ifdef OSE_PROVIDE_TYPE_NIL
OSEVM_WRAP_DECL(toNil)
#endif
#ifdef OSE_PROVIDE_TYPE_INFINITUM
OSEVM_WRAP_DECL(toInfinitum)
#endif
 
enum ose_errno osevm_resolveWildPtr(ose_bundle osevm);
 
#ifdef __cplusplus
}
#endif
 
#endif