ose_context.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 OSE_CONTEXT_H
#define OSE_CONTEXT_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include <inttypes.h>
#include "ose.h"
 
#define OSE_CONTEXT_ALIGNMENT 4
 
/* The cache holds OSE_CONTEXT_NUM_CACHE_ITEMS pointers -- 56 bytes with its
 * header. The remainder of OSE_CONTEXT_CACHE_SIZE is headroom, and it is not
 * free: it is paid per context message, and a machine with an inner carries
 * about a dozen of them. At a 256-byte cache that came to 332 bytes of
 * overhead per context, 260 of it this blob.
 *
 * It cannot be sized per context without giving up compile-time register
 * offsets: ose_vm.h derives OSEVM_INPUT_CONTEXT_MESSAGE_OFFSET and its four
 * siblings from OSE_CONTEXT_BUNDLE_OFFSET, which is a constant only because
 * this is. So it is sized per build, where a host that knows its own
 * constraints can answer -- an MCU differently from a laptop.
 *
 * On AVR a pointer is two bytes, so the three items fit in 36 and the
 * default is exactly that: the 28 bytes of headroom are paid by every
 * register on a part with 8 KB of RAM. A size too small for the items is
 * refused when ose_context.c compiles. */
#ifdef OSE_CONF_CONTEXT_CACHE_SIZE
#define OSE_CONTEXT_CACHE_SIZE OSE_CONF_CONTEXT_CACHE_SIZE
#elif defined(__AVR__)
#define OSE_CONTEXT_CACHE_SIZE 36
#else
#define OSE_CONTEXT_CACHE_SIZE 64
#endif
#define OSE_CONTEXT_NUM_CACHE_ITEMS 3
#define OSE_CONTEXT_CACHE_TYPETAG_STRLEN 8
 
#define OSE_CONTEXT_BUNDLE_SIZE_OFFSET -4
#define OSE_CONTEXT_TOTAL_SIZE_OFFSET -8
#define OSE_CONTEXT_PARENT_BUNDLE_OFFSET_OFFSET -12
#define OSE_CONTEXT_STATUS_OFFSET -16
#define OSE_CONTEXT_MEMUSAGE_OFFSET -20
#define OSE_CONTEXT_CHANGED_OFFSET -24
/* The context message's typetags are ",bbbiiiiibb": a cache blob, then two
 * blobs that are unused. An empty blob is exactly the four bytes of its own
 * size word, and an int32 is four bytes too, so spelling the second as `i`
 * changes the typetag string and nothing else -- same offsets, same
 * OSE_CONTEXT_BUNDLE_OFFSET, same padded typetag length. -32 remains unused.
 *
 * libose stores this word and does not read it. No bit is named here, which
 * is the split ose_vm.h keeps for declarations: ose manipulates, and its
 * clients interpret. A register that must not travel, or one destroyed when
 * its machine goes idle, are facts about saving and driving, and libose does
 * neither, so it has no way to be right about them. Whichever client saves
 * and drives names the bits. */
#define OSE_CONTEXT_FLAGS_OFFSET -28
#define OSE_CONTEXT_CACHE_OFFSET -(36 + OSE_CONTEXT_CACHE_SIZE)
 
void ose_context_set_status(ose_bundle b, int32_t s);
int32_t ose_context_get_status(ose_bundle b);
void ose_context_set_changed(ose_bundle b);
uint32_t ose_context_get_version(ose_bundle b);
void ose_context_set_flags(ose_bundle b, int32_t flags);
int32_t ose_context_get_flags(ose_bundle b);
/* void ose_context_set_cachefns(ose_bundle B, */
/*                               int32_t (*getFirstOffsetForMatch)(ose_bundle, */
/*                                                                 const char * const, */
/*                                                                 void**), */
/*                               void *userdata); */
void ose_context_cache_set(ose_bundle B,
                           int32_t o,
                           void *i);
void ose_context_cache_setGetFirstOffsetForMatchFn(ose_bundle B,
                                                   int32_t (*getFirstOffsetForMatch)(ose_bundle,
                                                                                     const char * const,
                                                                                     void**));
void ose_context_cache_setUserdata(ose_bundle B,
                                   void *userdata);
 
/* The pair to ose_context_cache_setUserdata(). A cache owner that keeps a
   sized allocation here needs to read the pointer back in order to report
   how much of it is in use. */
void *ose_context_cache_getUserdata(ose_bundle B);
void ose_context_cache_setTypeBundle(ose_bundle B,
                                     ose_bundle tx);
int32_t ose_context_getFirstOffsetForMatch(ose_bundle B,
                                           const char * const address);
ose_bundle ose_getTypeBundle(ose_constbundle bundle);
 
#ifdef OSE_MEMPROFILE
int32_t ose_get_memusage(ose_bundle b);
void ose_reset_memusage(ose_bundle b);
#else
#define ose_get_memusage(b) do{}while(0)
#define ose_reset_memusage(b) do{}while(0)
#endif
 
 
 
#define OSE_CONTEXT_MESSAGE_TYPETAGS ",bbiiiiiibb"
 
#define OSE_CONTEXT_MESSAGE_TYPETAGS_PLEN 12
 
#define OSE_CONTEXT_BUNDLE_OFFSET                               \
    (4          /* size */                                      \
     + 4            /* padded address len */                    \
     + 12            /* padded typetag str */                   \
     + OSE_SIZEWORD_LEN_ + OSE_CONTEXT_CACHE_SIZE           /* blob - cache */ \
     + 4            /* blob - unused */                         \
     + 4            /* int - flags */                           \
     + 4            /* int - changed */                         \
     + 4            /* int - memusage */                        \
     + 4            /* int - status */                          \
     + 4            /* int - offset to bundle */                \
     + 4            /* int - total size */                      \
     + 4)           /* blob size */
 
 
 
 
int32_t ose_readSize(ose_constbundle bundle);
 
 
 
 
#define OSE_CONTEXT_MESSAGE_OVERHEAD                \
    (OSE_CONTEXT_BUNDLE_OFFSET                      \
     + OSE_BUNDLE_HEADER_LEN_   /* bundle header */ \
     + 4)           /* blob size */
 
 
 
 
#define OSE_CONTEXT_STATUS_MESSAGE_SIZE 16
 
 
 
 
#define OSE_CONTEXT_TYPE_MESSAGE_SIZE 1024
 
 
 
 
#define OSE_CONTEXT_MAX_OVERHEAD                \
    ((OSE_CONTEXT_ALIGNMENT)                    \
     + OSE_BUNDLE_HEADER_LEN_                   \
     + OSE_CONTEXT_MESSAGE_OVERHEAD             \
     + OSE_CONTEXT_STATUS_MESSAGE_SIZE          \
     + OSE_CONTEXT_MESSAGE_OVERHEAD             \
     + OSE_CONTEXT_MESSAGE_OVERHEAD             \
     + OSE_CONTEXT_TYPE_MESSAGE_SIZE)
 
 
 
 
int32_t ose_init(ose_bundle bundle,
                 int32_t size,
                 const char * const address);
 
 
 
 
 
int32_t ose_pushContextMessage(ose_bundle bundle,
                               int32_t size,
                               const char * const address);
void ose_dropContextMessage(ose_bundle bundle);
 
/* Which registers a machine has, and where they sit, is its root bundle's
 * own version (ose_context_get_version()): making or dropping a register
 * moves it, and a machine built again in the same bytes goes on from the
 * version the last one reached. Nothing counts changes across machines;
 * libose keeps no state outside a bundle. */
 
 
 
 
 
int32_t ose_spaceAvailable(ose_constbundle bundle);
 
 
 
 
int32_t ose_getContextMessageOffset(ose_bundle bundle,
                                    const char * const address);
 
 
 
 
 
ose_bundle ose_enterBundleAtOffset(ose_bundle bundle,
                                   int32_t offset);
 
 
 
 
ose_bundle ose_enter(ose_bundle bundle,
                     const char * const address);
 
 
 
 
 
ose_bundle ose_exit(ose_constbundle bundle);
 
 
 
 
 
int ose_addToSize(ose_bundle bundle, int32_t amt);
int ose_incSize(ose_bundle bundle, int32_t amt);
int ose_decSize(ose_bundle bundle, int32_t amt);
 
 
 
 
 
/* void ose_copyBundleElemToDest(ose_bundle src, ose_bundle dest); */
 
 
 
 
 
/* void ose_copyBundleElemToDestAddr(ose_bundle src, const char * const dest_addr); */
 
 
 
 
 
/* void ose_moveBundleElemToDest(ose_bundle src, ose_bundle dest); */
 
 
 
 
 
/* void ose_moveBundleElemToDestAddr(ose_bundle src, */
/*                                   const char * const dest_addr); */
 
 
 
 
 
/* void ose_replaceBundleElemInDest(ose_bundle src, ose_bundle dest); */
 
 
 
 
 
/* void ose_replaceBundleElemInDestAddr(ose_bundle src, */
/*                                      const char * const dest_addr); */
 
 
 
 
 
void ose_copyBundle(ose_constbundle src, ose_bundle dest);
 
 
 
 
 
void ose_appendBundle(ose_bundle src, ose_bundle dest);
 
 
 
 
void ose_replaceBundle(ose_bundle src, ose_bundle dest);
void ose_copyElemAtOffset(int32_t srcoffset,
                          ose_constbundle src,
                          ose_bundle dest);
#define ose_copyElem(src, dest)                             \
    ose_copyElemAtOffset(ose_getLastBundleElemOffset(src),  \
                         src, dest)
#define ose_moveElem(src, dest)                         \
    {                                                   \
        int32_t o = ose_getLastBundleElemOffset(src);   \
        ose_copyElemAtOffset(o, src, dest);             \
        ose_dropAtOffset(src, o);                       \
    }
 
 
 
 
int32_t ose_routeElemAtOffset(int32_t srcoffset,
                              ose_constbundle src,
                              int32_t prefixlen,
                              ose_bundle dest);
 
 
 
 
 
ose_bundle ose_newBundleFromCBytes(int32_t nbytes, char *bytes);
ose_bundle ose_newBundleFromZeroedCBytes(int32_t nbytes, char *bytes);
 
 
 
 
#define OSE_REGISTER_ADDRESS_LEN 3
 
 
 
 
int32_t ose_addressToRegister(ose_bundle osevm,
                              const char * const address,
                              ose_bundle *reg,
                              const char **rest);
 
#ifdef __cplusplus
}
#endif
 
 
 
/* INLINE IN A RELEASE BUILD: ose_readSize.
 
   They are the most called functions in the VM and do almost nothing, and a
   call into another file cannot be inlined without link-time optimisation --
   which a host built as several libraries cannot have across them. Measured
   on one host's heaviest message path, seven of these inline took 20.7 to
   15.7 us; the whole of LTO took it to 13.2.
 
   The functions are still defined and exported, for anything that takes
   their address or calls them from another language. A debug build calls
   them, and gets their asserts. OSE_INLINE_ACCESSORS_OFF turns this off. */
#if !defined(OSE_CONF_DEBUG) && !defined(OSE_INLINE_ACCESSORS_OFF)
static inline int32_t ose_readSize_inline(ose_constbundle b)
{ return ose_ntohl(*((const int32_t *)(ose_getBundlePtr(b) + OSE_CONTEXT_BUNDLE_SIZE_OFFSET))); }
#define ose_readSize(b) ose_readSize_inline(b)
#endif
 
#endif