muapi.h 11.3 KB
Newer Older
1 2 3 4 5 6 7
#ifndef __MUAPI_H__
#define __MUAPI_H__

#ifdef __cplusplus
extern "C" {
#endif

Kunshan Wang's avatar
Kunshan Wang committed
8 9
#include <stdint.h>

Kunshan Wang's avatar
Kunshan Wang committed
10 11 12 13 14 15 16 17 18
// MuValue and MuXxxValue type are opaque handles to values in the Mu type
// system.
//
// The actual values are held by MuCtx. MuValue opaquely refers to one such
// value. Copies of MuValue values refer to the same value. A MuValue instance
// can only be used in the MuCtx holding it.
//
// Values of subtypes can be cast to MuValue and back using the type cast
// expression in C, similar to casting one pointer to another.
Kunshan Wang's avatar
Kunshan Wang committed
19 20 21 22 23 24 25 26
typedef void *MuValue;              // Any Mu value
typedef void *MuIntValue;           // int<n>
typedef void *MuFloatValue;         // float
typedef void *MuDoubleValue;        // double
typedef void *MuRefValue;           // ref<T>
typedef void *MuIRefValue;          // iref<T>
typedef void *MuStructValue;        // struct<...>
typedef void *MuArrayValue;         // array<T l>
27
typedef void *MuVectorValue;        // vector<T l>
Kunshan Wang's avatar
Kunshan Wang committed
28 29 30
typedef void *MuFuncRefValue;       // funcref<sig>
typedef void *MuThreadRefValue;     // threadref
typedef void *MuStackRefValue;      // stackref
31
typedef void *MuFCRefValue;         // framecursorref
Kunshan Wang's avatar
Kunshan Wang committed
32 33 34
typedef void *MuTagRef64Value;      // tagref64
typedef void *MuUPtrValue;          // uptr
typedef void *MuUFPValue;           // ufuncptr
Kunshan Wang's avatar
Kunshan Wang committed
35 36

// Identifiers and names of Mu
Kunshan Wang's avatar
Kunshan Wang committed
37 38 39
typedef uint32_t MuID;
typedef char *MuName;

Kunshan Wang's avatar
Kunshan Wang committed
40 41 42 43 44
// Convenient types for the void* type and the void(*)() type in C
typedef void *MuCPtr;
typedef void (*MuCFP)();

// Result of a trap handler
Kunshan Wang's avatar
Kunshan Wang committed
45
typedef int MuTrapHandlerResult;
Kunshan Wang's avatar
Kunshan Wang committed
46 47
// Used by new_thread
typedef int MuHowToResume;
Kunshan Wang's avatar
Kunshan Wang committed
48 49

#define MU_THREAD_EXIT          0x00
Kunshan Wang's avatar
Kunshan Wang committed
50
#define MU_REBIND_PASS_VALUES   0x01
51
#define MU_REBIND_THROW_EXC     0x02
Kunshan Wang's avatar
Kunshan Wang committed
52

Kunshan Wang's avatar
Kunshan Wang committed
53 54 55 56
// Declare the types here because they are used in the following signatures.
typedef struct MuVM MuVM;
typedef struct MuCtx MuCtx;

Kunshan Wang's avatar
Kunshan Wang committed
57
// Signature of the trap handler
Kunshan Wang's avatar
Kunshan Wang committed
58 59
typedef void (*MuTrapHandler)(MuCtx *ctx, MuThreadRefValue thread,
        MuStackRefValue stack, int wpid, MuTrapHandlerResult *result,
60
        MuStackRefValue *new_stack, MuValue *values, int *nvalues,
Kunshan Wang's avatar
Kunshan Wang committed
61
        MuRefValue *exception,
Kunshan Wang's avatar
Kunshan Wang committed
62
        MuCPtr userdata);
Kunshan Wang's avatar
Kunshan Wang committed
63

Kunshan Wang's avatar
Kunshan Wang committed
64
// Memory orders
Kunshan Wang's avatar
Kunshan Wang committed
65 66 67 68 69 70 71 72 73 74
typedef int MuMemOrd;

#define MU_NOT_ATOMIC  0x00
#define MU_RELAXED     0x01
#define MU_CONSUME     0x02
#define MU_ACQUIRE     0x03
#define MU_RELEASE     0x04
#define MU_ACQ_REL     0x05
#define MU_SEQ_CST     0x06

Kunshan Wang's avatar
Kunshan Wang committed
75
// Operations for the atomicrmw API function
Kunshan Wang's avatar
Kunshan Wang committed
76 77 78 79 80 81 82 83 84 85 86 87 88 89
typedef int MuAtomicRMWOp;

#define MU_XCHG        0x00
#define MU_ADD         0x01
#define MU_SUB         0x02
#define MU_AND         0x03
#define MU_NAND        0x04
#define MU_OR          0x05
#define MU_XOR         0x06
#define MU_MAX         0x07
#define MU_MIN         0x08
#define MU_UMAX        0x09
#define MU_UMIN        0x0A

Kunshan Wang's avatar
Kunshan Wang committed
90
// Calling conventions.
Kunshan Wang's avatar
Kunshan Wang committed
91
typedef int MuCallConv;
Kunshan Wang's avatar
Kunshan Wang committed
92 93 94 95 96 97 98 99 100 101 102

#define MU_DEFUALT     0x00
// Concrete Mu implementations may define more calling conventions.

// NOTE: MuVM and MuCtx are structures with many function pointers. This
// approach loosens the coupling between the client module and the Mu
// implementation.  At compile time, the client does not need to link against
// any dynamic libraries. At run time, more than one Mu implementations can be
// used by the same client.

// A handle and method lists of a micro VM
Kunshan Wang's avatar
Kunshan Wang committed
103
struct MuVM {
Kunshan Wang's avatar
Kunshan Wang committed
104 105 106
    void *header;   // Refer to internal stuff

    // Create context
Kunshan Wang's avatar
Kunshan Wang committed
107
    MuCtx*  (*new_context)(MuVM *mvm);
Kunshan Wang's avatar
Kunshan Wang committed
108 109
    
    // Convert between IDs and names
Kunshan Wang's avatar
Kunshan Wang committed
110
    MuID    (*id_of  )(MuVM *mvm, MuName name);
Kunshan Wang's avatar
Kunshan Wang committed
111
    MuName  (*name_of)(MuVM *mvm, MuID id);
Kunshan Wang's avatar
Kunshan Wang committed
112 113

    // Set handlers
Kunshan Wang's avatar
Kunshan Wang committed
114
    void    (*set_trap_handler      )(MuVM *mvm, MuTrapHandler trap_handler, MuCPtr userdata);
Kunshan Wang's avatar
Kunshan Wang committed
115 116
};

Kunshan Wang's avatar
Kunshan Wang committed
117 118 119 120 121
// A local context. It can only be used by one thread at a time. It holds many
// states which are typically held by a Mu thread, such as object references,
// local heap allocation pool, and an object-pinning set. It also holds many Mu
// values and expose them to the client as opaque handles (MuValue and its
// subtypes).
Kunshan Wang's avatar
Kunshan Wang committed
122
struct MuCtx {
Kunshan Wang's avatar
Kunshan Wang committed
123 124 125
    void *header;   // Refer to internal stuff

    // Convert between IDs and names
Kunshan Wang's avatar
Kunshan Wang committed
126
    MuID        (*id_of  )(MuCtx *ctx, MuName name);
Kunshan Wang's avatar
Kunshan Wang committed
127
    MuName      (*name_of)(MuCtx *ctx, MuID id);
Kunshan Wang's avatar
Kunshan Wang committed
128 129

    // Close the current context, releasing all resources
Kunshan Wang's avatar
Kunshan Wang committed
130
    void        (*close_context)(MuCtx *ctx);
Kunshan Wang's avatar
Kunshan Wang committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146

    // Load bundles and HAIL scripts
    void        (*load_bundle)(MuCtx *ctx, char *buf, int sz);
    void        (*load_hail  )(MuCtx *ctx, char *buf, int sz);

    // Convert from C values to Mu values
    MuIntValue      (*handle_from_int8  )(MuCtx *ctx, int8_t   num, int len);
    MuIntValue      (*handle_from_uint8 )(MuCtx *ctx, uint8_t  num, int len);
    MuIntValue      (*handle_from_int16 )(MuCtx *ctx, int16_t  num, int len);
    MuIntValue      (*handle_from_uint16)(MuCtx *ctx, uint16_t num, int len);
    MuIntValue      (*handle_from_int32 )(MuCtx *ctx, int32_t  num, int len);
    MuIntValue      (*handle_from_uint32)(MuCtx *ctx, uint32_t num, int len);
    MuIntValue      (*handle_from_int64 )(MuCtx *ctx, int64_t  num, int len);
    MuIntValue      (*handle_from_uint64)(MuCtx *ctx, uint64_t num, int len);
    MuFloatValue    (*handle_from_float )(MuCtx *ctx, float    num);
    MuDoubleValue   (*handle_from_double)(MuCtx *ctx, double   num);
Kunshan Wang's avatar
Kunshan Wang committed
147 148
    MuUPtrValue     (*handle_from_ptr   )(MuCtx *ctx, MuID mu_type, MuCPtr ptr);
    MuUFPValue      (*handle_from_fp    )(MuCtx *ctx, MuID mu_type, MuCFP fp);
Kunshan Wang's avatar
Kunshan Wang committed
149 150 151 152 153 154 155 156 157 158 159 160

    // Convert from Mu values to C values
    int8_t      (*handle_to_sint8 )(MuCtx *ctx, MuIntValue    opnd);
    uint8_t     (*handle_to_uint8 )(MuCtx *ctx, MuIntValue    opnd);
    int16_t     (*handle_to_sint16)(MuCtx *ctx, MuIntValue    opnd);
    uint16_t    (*handle_to_uint16)(MuCtx *ctx, MuIntValue    opnd);
    int32_t     (*handle_to_sint32)(MuCtx *ctx, MuIntValue    opnd);
    uint32_t    (*handle_to_uint32)(MuCtx *ctx, MuIntValue    opnd);
    int64_t     (*handle_to_sint64)(MuCtx *ctx, MuIntValue    opnd);
    uint64_t    (*handle_to_uint64)(MuCtx *ctx, MuIntValue    opnd);
    float       (*handle_to_float )(MuCtx *ctx, MuFloatValue  opnd);
    double      (*handle_to_double)(MuCtx *ctx, MuDoubleValue opnd);
Kunshan Wang's avatar
Kunshan Wang committed
161 162
    MuCPtr      (*handle_to_ptr   )(MuCtx *ctx, MuUPtrValue   opnd);
    MuCFP       (*handle_to_fp    )(MuCtx *ctx, MuUFPValue    opnd);
Kunshan Wang's avatar
Kunshan Wang committed
163 164

    // Make MuValue instances from Mu global SSA variables
Kunshan Wang's avatar
Kunshan Wang committed
165 166 167 168
    MuValue         (*handle_from_const )(MuCtx *ctx, MuID id);
    MuIRefValue     (*handle_from_global)(MuCtx *ctx, MuID id);
    MuFuncRefValue  (*handle_from_func  )(MuCtx *ctx, MuID id);
    MuValue         (*handle_from_expose)(MuCtx *ctx, MuID id);
Kunshan Wang's avatar
Kunshan Wang committed
169 170 171 172 173

    // Delete the value held by the MuCtx, making it unusable, but freeing up
    // the resource.
    void        (*delete_value)(MuCtx *ctx, MuValue opnd);

174 175 176 177 178 179
    // Compare reference or general reference types.
    // EQ. Available for ref, iref, funcref, threadref and stackref.
    int         (*ref_eq )(MuCtx *ctx, MuValue lhs,     MuValue rhs);
    // ULT. Available for iref only.
    int         (*ref_ult)(MuCtx *ctx, MuIRefValue lhs, MuIRefValue rhs);

Kunshan Wang's avatar
Kunshan Wang committed
180 181 182 183
    // Manipulate Mu values of the struct<...> type
    MuValue     (*extract_value)(MuCtx *ctx, MuStructValue str, int index);
    MuValue     (*insert_value )(MuCtx *ctx, MuStructValue str, int index, MuValue newval);

184 185 186 187 188
    // Manipulate Mu values of the array or vector type
    // str can be MuArrayValue or MuVectorValue
    MuValue     (*extract_element)(MuCtx *ctx, MuValue str, MuIntValue index);
    MuValue     (*insert_element )(MuCtx *ctx, MuValue str, MuIntValue index, MuValue newval);

Kunshan Wang's avatar
Kunshan Wang committed
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
    // Heap allocation
    MuRefValue  (*new_fixed )(MuCtx *ctx, MuID mu_type);
    MuRefValue  (*new_hybrid)(MuCtx *ctx, MuID mu_type, MuIntValue length);

    // Change the T or sig in ref<T>, iref<T> or func<sig>
    MuValue     (*refcast)(MuCtx *ctx, MuValue opnd, MuID new_type);

    // Memory addressing
    MuIRefValue     (*get_iref           )(MuCtx *ctx, MuRefValue opnd);
    MuIRefValue     (*get_field_iref     )(MuCtx *ctx, MuIRefValue opnd, int field);
    MuIRefValue     (*get_elem_iref      )(MuCtx *ctx, MuIRefValue opnd, MuIntValue index);
    MuIRefValue     (*shift_iref         )(MuCtx *ctx, MuIRefValue opnd, MuIntValue offset);
    MuIRefValue     (*get_var_part_iref  )(MuCtx *ctx, MuIRefValue opnd);

    // Memory accessing
    MuValue     (*load     )(MuCtx *ctx, MuMemOrd ord, MuIRefValue loc);
    void        (*store    )(MuCtx *ctx, MuMemOrd ord, MuIRefValue loc, MuValue newval);
    MuValue     (*cmpxchg  )(MuCtx *ctx, MuMemOrd ord_succ, MuMemOrd ord_fail,
                        int weak, MuIRefValue loc, MuValue expected, MuValue desired,
Kunshan Wang's avatar
Kunshan Wang committed
208
                        int *is_succ);
Kunshan Wang's avatar
Kunshan Wang committed
209
    MuValue     (*atomicrmw)(MuCtx *ctx, MuMemOrd ord, MuAtomicRMWOp op,
Kunshan Wang's avatar
Kunshan Wang committed
210
                        MuIRefValue loc, MuValue opnd);
Kunshan Wang's avatar
Kunshan Wang committed
211 212
    void        (*fence    )(MuCtx *ctx, MuMemOrd ord);

Kunshan Wang's avatar
Kunshan Wang committed
213
    // Thread and stack creation and stack destruction
Kunshan Wang's avatar
Kunshan Wang committed
214 215 216
    MuStackRefValue     (*new_stack )(MuCtx *ctx, MuFuncRefValue func);
    MuThreadRefValue    (*new_thread)(MuCtx *ctx, MuStackRefValue stack,
                            MuHowToResume *htr, MuValue *vals, int nvals, MuRefValue *exc);
Kunshan Wang's avatar
Kunshan Wang committed
217
    void                (*kill_stack)(MuCtx *ctx, MuStackRefValue stack);
Kunshan Wang's avatar
Kunshan Wang committed
218

219 220 221 222 223 224
    // Frame cursor operations
    MuFCRefValue    (*new_cursor  )(MuCtx *ctx, MuStackRefValue stack);
    void            (*next_frame  )(MuCtx *ctx, MuFCRefValue cursor);
    MuFCRefValue    (*copy_cursor )(MuCtx *ctx, MuFCRefValue cursor);
    void            (*close_cursor)(MuCtx *ctx, MuFCRefValue cursor);

Kunshan Wang's avatar
Kunshan Wang committed
225
    // Stack introspection
226 227 228 229
    MuID        (*cur_func       )(MuCtx *ctx, MuFCRefValue cursor);
    MuID        (*cur_func_ver   )(MuCtx *ctx, MuFCRefValue cursor);
    MuID        (*cur_inst       )(MuCtx *ctx, MuFCRefValue cursor);
    void        (*dump_keepalives)(MuCtx *ctx, MuFCRefValue cursor, MuValue *results);
Kunshan Wang's avatar
Kunshan Wang committed
230
    
Kunshan Wang's avatar
Kunshan Wang committed
231
    // On-stack replacement
232 233
    void        (*pop_frames_to)(MuCtx *ctx, MuFCRefValue cursor);
    void        (*push_frame   )(MuCtx *ctx, MuStackRefValue stack, MuFuncRefValue func);
Kunshan Wang's avatar
Kunshan Wang committed
234 235 236 237 238 239 240 241 242 243 244 245 246 247

    // 64-bit tagged reference operations
    int             (*tr64_is_fp   )(MuCtx *ctx, MuTagRef64Value value);
    int             (*tr64_is_int  )(MuCtx *ctx, MuTagRef64Value value);
    int             (*tr64_is_ref  )(MuCtx *ctx, MuTagRef64Value value);
    MuDoubleValue   (*tr64_to_fp   )(MuCtx *ctx, MuTagRef64Value value);
    MuIntValue      (*tr64_to_int  )(MuCtx *ctx, MuTagRef64Value value);
    MuRefValue      (*tr64_to_ref  )(MuCtx *ctx, MuTagRef64Value value);
    MuIntValue      (*tr64_to_tag  )(MuCtx *ctx, MuTagRef64Value value);
    MuTagRef64Value (*tr64_from_fp )(MuCtx *ctx, MuDoubleValue value);
    MuTagRef64Value (*tr64_from_int)(MuCtx *ctx, MuIntValue value);
    MuTagRef64Value (*tr64_from_ref)(MuCtx *ctx, MuRefValue ref, MuIntValue tag);

    // Watchpoint operations
Kunshan Wang's avatar
Kunshan Wang committed
248 249 250
    void        (*enable_watchpoint )(MuCtx *ctx, int wpid);
    void        (*disable_watchpoint)(MuCtx *ctx, int wpid);

Kunshan Wang's avatar
Kunshan Wang committed
251
    // Mu memory pinning, usually object pinning
Kunshan Wang's avatar
Kunshan Wang committed
252
    MuUPtrValue (*pin  )(MuCtx *ctx, MuValue loc);      // loc is either MuRefValue or MuIRefValue
Kunshan Wang's avatar
Kunshan Wang committed
253
    void        (*unpin)(MuCtx *ctx, MuValue loc);      // loc is either MuRefValue or MuIRefValue
Kunshan Wang's avatar
Kunshan Wang committed
254

Kunshan Wang's avatar
Kunshan Wang committed
255
    // Expose Mu functions as native callable things, usually function pointers
Kunshan Wang's avatar
Kunshan Wang committed
256
    MuValue     (*expose  )(MuCtx *ctx, MuFuncRefValue func, MuCallConv call_conv, MuIntValue cookie);
Kunshan Wang's avatar
Kunshan Wang committed
257
    void        (*unexpose)(MuCtx *ctx, MuCallConv call_conv, MuValue value);
Kunshan Wang's avatar
Kunshan Wang committed
258 259
};

260 261 262 263 264
#ifdef __cplusplus
}
#endif

#endif // __MUAPI_H__