GitLab will continue to be upgraded from 11.4.5-ce.0 on November 25th 2019 at 4.00pm (AEDT) to 5.00pm (AEDT) due to Critical Security Patch Availability. During the update, GitLab and Mattermost services will not be available.

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
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,
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
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
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
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);
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);
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
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);
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
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
256
    MuValue     (*expose  )(MuCtx *ctx, MuFuncRefValue func, MuCallConv call_conv, MuIntValue cookie);
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__