obj.h 15.1 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
// All Micro Python objects are at least this type
// It must be of pointer size

typedef machine_ptr_t mp_obj_t;
typedef machine_const_ptr_t mp_const_obj_t;

// Integers that fit in a pointer have this type
// (do we need to expose this in the public API?)

typedef machine_int_t mp_small_int_t;

// The machine floating-point type used for float and complex numbers
13
14

#if MICROPY_ENABLE_FLOAT
15
typedef machine_float_t mp_float_t;
16
17
#endif

18
19
// Anything that wants to be a Micro Python object must have
// mp_obj_base_t as its first member (except NULL and small ints)
20

ian-v's avatar
ian-v committed
21
struct _mp_obj_type_t;
22
struct _mp_obj_base_t {
ian-v's avatar
ian-v committed
23
    const struct _mp_obj_type_t *type;
24
};
ian-v's avatar
ian-v committed
25
typedef struct _mp_obj_base_t mp_obj_base_t;
26
27
28
29
30
31

// The NULL object is used to indicate the absence of an object
// It *cannot* be used when an mp_obj_t is expected, except where explicitly allowed

#define MP_OBJ_NULL ((mp_obj_t)NULL)

32
33
34
35
// These macros check for small int, qstr or object, and access small int and qstr values
//  - xxxx...xxx1: a small int, bits 1 and above are the value
//  - xxxx...xx10: a qstr, bits 2 and above are the value
//  - xxxx...xx00: a pointer to an mp_obj_base_t
36

37
38
// In SMALL_INT, next-to-highest bits is used as sign, so both must match for value in range
#define MP_OBJ_FITS_SMALL_INT(n) ((((n) ^ ((n) << 1)) & WORD_MSBIT_HIGH) == 0)
39
#define MP_OBJ_IS_SMALL_INT(o) ((((mp_small_int_t)(o)) & 1) != 0)
40
41
42
43
#define MP_OBJ_IS_QSTR(o) ((((mp_small_int_t)(o)) & 3) == 2)
#define MP_OBJ_IS_OBJ(o) ((((mp_small_int_t)(o)) & 3) == 0)
#define MP_OBJ_IS_TYPE(o, t) (MP_OBJ_IS_OBJ(o) && (((mp_obj_base_t*)(o))->type == (t)))

44
#define MP_OBJ_SMALL_INT_VALUE(o) (((mp_small_int_t)(o)) >> 1)
45
46
47
48
#define MP_OBJ_NEW_SMALL_INT(small_int) ((mp_obj_t)(((small_int) << 1) | 1))

#define MP_OBJ_QSTR_VALUE(o) (((mp_small_int_t)(o)) >> 2)
#define MP_OBJ_NEW_QSTR(qstr) ((mp_obj_t)((((machine_uint_t)qstr) << 2) | 2))
49
50
51
52
53

// These macros are used to declare and define constant function objects
// You can put "static" in front of the definitions to make them local

#define MP_DECLARE_CONST_FUN_OBJ(obj_name) extern const mp_obj_fun_native_t obj_name
54

55
56
57
58
59
60
61
#define MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, is_kw, n_args_min, n_args_max, fun_name) const mp_obj_fun_native_t obj_name = {{&fun_native_type}, is_kw, n_args_min, n_args_max, (void *)fun_name}
#define MP_DEFINE_CONST_FUN_OBJ_0(obj_name, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, false, 0, 0, (mp_fun_0_t)fun_name)
#define MP_DEFINE_CONST_FUN_OBJ_1(obj_name, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, false, 1, 1, (mp_fun_1_t)fun_name)
#define MP_DEFINE_CONST_FUN_OBJ_2(obj_name, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, false, 2, 2, (mp_fun_2_t)fun_name)
#define MP_DEFINE_CONST_FUN_OBJ_3(obj_name, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, false, 3, 3, (mp_fun_3_t)fun_name)
#define MP_DEFINE_CONST_FUN_OBJ_VAR(obj_name, n_args_min, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, false, n_args_min, (~((machine_uint_t)0)), (mp_fun_var_t)fun_name)
#define MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(obj_name, n_args_min, n_args_max, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, false, n_args_min, n_args_max, (mp_fun_var_t)fun_name)
62
#define MP_DEFINE_CONST_FUN_OBJ_KW(obj_name, n_args_min, fun_name) MP_DEFINE_CONST_FUN_OBJ_VOID_PTR(obj_name, true, n_args_min, (~((machine_uint_t)0)), (mp_fun_kw_t)fun_name)
63

64
65
66
67
68
69
70
71
72
// These macros are used to declare and define constant staticmethond and classmethod objects
// You can put "static" in front of the definitions to make them local

#define MP_DECLARE_CONST_STATICMETHOD_OBJ(obj_name) extern const mp_obj_staticmethod_t obj_name
#define MP_DECLARE_CONST_CLASSMETHOD_OBJ(obj_name) extern const mp_obj_classmethod_t obj_name

#define MP_DEFINE_CONST_STATICMETHOD_OBJ(obj_name, fun_name) const mp_obj_staticmethod_t obj_name = {{&mp_type_staticmethod}, fun_name}
#define MP_DEFINE_CONST_CLASSMETHOD_OBJ(obj_name, fun_name) const mp_obj_classmethod_t obj_name = {{&mp_type_classmethod}, fun_name}

73
74
// Need to declare this here so we are not dependent on map.h
struct _mp_map_t;
75
76
struct _mp_map_elem_t;
enum _mp_map_lookup_kind_t;
77
78
79
80
81
82

// Type definitions for methods

typedef mp_obj_t (*mp_fun_0_t)(void);
typedef mp_obj_t (*mp_fun_1_t)(mp_obj_t);
typedef mp_obj_t (*mp_fun_2_t)(mp_obj_t, mp_obj_t);
83
typedef mp_obj_t (*mp_fun_3_t)(mp_obj_t, mp_obj_t, mp_obj_t);
84
typedef mp_obj_t (*mp_fun_t)(void);
85
typedef mp_obj_t (*mp_fun_var_t)(uint n, const mp_obj_t *);
86
typedef mp_obj_t (*mp_fun_kw_t)(uint n, const mp_obj_t *, struct _mp_map_t *);
87

88
89
90
91
92
typedef enum {
    PRINT_STR, PRINT_REPR
} mp_print_kind_t;

typedef void (*mp_print_fun_t)(void (*print)(void *env, const char *fmt, ...), void *env, mp_obj_t o, mp_print_kind_t kind);
93
94
typedef mp_obj_t (*mp_make_new_fun_t)(mp_obj_t type_in, uint n_args, uint n_kw, const mp_obj_t *args);
typedef mp_obj_t (*mp_call_fun_t)(mp_obj_t fun, uint n_args, uint n_kw, const mp_obj_t *args);
95
96
typedef mp_obj_t (*mp_unary_op_fun_t)(int op, mp_obj_t);
typedef mp_obj_t (*mp_binary_op_fun_t)(int op, mp_obj_t, mp_obj_t);
97
typedef void (*mp_load_attr_fun_t)(mp_obj_t self_in, qstr attr, mp_obj_t *dest); // for fail, do nothing; for attr, dest[0] = value; for method, dest[0] = method, dest[1] = self
98
typedef bool (*mp_store_attr_fun_t)(mp_obj_t self_in, qstr attr, mp_obj_t value); // return true if store succeeded
99
typedef bool (*mp_store_item_fun_t)(mp_obj_t self_in, mp_obj_t index, mp_obj_t value); // return true if store succeeded
100
101

typedef struct _mp_method_t {
102
    const char *name;
103
104
105
    mp_const_obj_t fun;
} mp_method_t;

106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
// Buffer protocol
typedef struct _buffer_info_t {
    // if we'd bother to support various versions of structure
    // (with different number of fields), we can distinguish
    // them with ver = sizeof(struct). Cons: overkill for *micro*?
    //int ver; // ?

    void *buf;
    machine_int_t len;

    // Rationale: have array.array and have SIMD operations on them
    // Cons: users can pass item size to processing functions themselves,
    // though that's not "plug&play"
    // int itemsize;

    // Rationale: to load arbitrary-sized sprites directly to LCD
    // Cons: a bit adhoc usecase
    // int stride;
} buffer_info_t;
#define BUFFER_READ  (1)
#define BUFFER_WRITE (2)
#define BUFFER_RW (BUFFER_READ | BUFFER_WRITE)
typedef struct _mp_buffer_p_t {
    machine_int_t (*get_buffer)(mp_obj_t obj, buffer_info_t *bufinfo, int flags);
} mp_buffer_p_t;

// Stream protocol
typedef struct _mp_stream_p_t {
    // On error, functions should return -1 and fill in *errcode (values are
    // implementation-dependent, but will be exposed to user, e.g. via exception).
    machine_int_t (*read)(mp_obj_t obj, void *buf, machine_uint_t size, int *errcode);
    machine_int_t (*write)(mp_obj_t obj, const void *buf, machine_uint_t size, int *errcode);
    // add seek() ?
} mp_stream_p_t;

141
142
143
144
struct _mp_obj_type_t {
    mp_obj_base_t base;
    const char *name;
    mp_print_fun_t print;
145
    mp_make_new_fun_t make_new;     // to make an instance of the type
146

147
    mp_call_fun_t call;
148
149
150
151
152
153
    mp_unary_op_fun_t unary_op;     // can return NULL if op not supported
    mp_binary_op_fun_t binary_op;   // can return NULL if op not supported

    mp_fun_1_t getiter;
    mp_fun_1_t iternext;

154
155
156
157
158
159
    // Alternatively, pointer(s) to interfaces to save space
    // in mp_obj_type_t at the expense of extra pointer and extra dereference
    // when actually used.
    mp_buffer_p_t buffer_p;
    mp_stream_p_t stream_p;

ian-v's avatar
ian-v committed
160
    const mp_method_t *methods;
161

162
163
    mp_load_attr_fun_t load_attr;
    mp_store_attr_fun_t store_attr;
164
165
166
    // Implements container[index] = val; note that load_item is implemented
    // by binary_op(RT_BINARY_OP_SUBSCR)
    mp_store_item_fun_t store_item;
167
168
169
170

    // these are for dynamically created types (classes)
    mp_obj_t bases_tuple;
    mp_obj_t locals_dict;
171

172
173
174
175
    /*
    What we might need to add here:

    store_subscr    list dict
176

177
178
179
180
181
182
183
184
185
186
187
    len             str tuple list map
    abs             float complex
    hash            bool int none str
    equal           int str
    less            int
    get_array_n     tuple list

    unpack seq      list tuple
    */
};

ian-v's avatar
ian-v committed
188
typedef struct _mp_obj_type_t mp_obj_type_t;
189
190
191
192
193
194
195

// Constant objects, globally accessible

extern const mp_obj_type_t mp_const_type;
extern const mp_obj_t mp_const_none;
extern const mp_obj_t mp_const_false;
extern const mp_obj_t mp_const_true;
196
extern const mp_obj_t mp_const_empty_tuple;
Damien George's avatar
Damien George committed
197
extern const mp_obj_t mp_const_ellipsis;
198
199
200
201
extern const mp_obj_t mp_const_stop_iteration; // special object indicating end of iteration (not StopIteration exception!)

// General API for objects

202
mp_obj_t mp_obj_new_type(qstr name, mp_obj_t bases_tuple, mp_obj_t locals_dict);
203
204
mp_obj_t mp_obj_new_none(void);
mp_obj_t mp_obj_new_bool(bool value);
Damien George's avatar
Damien George committed
205
mp_obj_t mp_obj_new_cell(mp_obj_t obj);
206
mp_obj_t mp_obj_new_int(machine_int_t value);
207
208
mp_obj_t mp_obj_new_int_from_uint(machine_uint_t value);
mp_obj_t mp_obj_new_int_from_long_str(const char *s);
209
mp_obj_t mp_obj_new_str(qstr qstr);
210
#if MICROPY_ENABLE_FLOAT
211
212
mp_obj_t mp_obj_new_float(mp_float_t val);
mp_obj_t mp_obj_new_complex(mp_float_t real, mp_float_t imag);
213
#endif
214
215
216
217
mp_obj_t mp_obj_new_exception(qstr id);
mp_obj_t mp_obj_new_exception_msg(qstr id, const char *msg);
mp_obj_t mp_obj_new_exception_msg_1_arg(qstr id, const char *fmt, const char *a1);
mp_obj_t mp_obj_new_exception_msg_2_args(qstr id, const char *fmt, const char *a1, const char *a2);
218
mp_obj_t mp_obj_new_exception_msg_varg(qstr id, const char *fmt, ...); // counts args by number of % symbols in fmt, excluding %%; can only handle void* sizes (ie no float/double!)
219
220
221
222
mp_obj_t mp_obj_new_range(int start, int stop, int step);
mp_obj_t mp_obj_new_range_iterator(int cur, int stop, int step);
mp_obj_t mp_obj_new_fun_bc(int n_args, uint n_state, const byte *code);
mp_obj_t mp_obj_new_fun_asm(uint n_args, void *fun);
Damien George's avatar
Damien George committed
223
mp_obj_t mp_obj_new_gen_wrap(uint n_locals, uint n_stack, mp_obj_t fun);
224
mp_obj_t mp_obj_new_gen_instance(const byte *bytecode, uint n_state, int n_args, const mp_obj_t *args);
225
mp_obj_t mp_obj_new_closure(mp_obj_t fun, mp_obj_t closure_tuple);
226
mp_obj_t mp_obj_new_tuple(uint n, const mp_obj_t *items);
227
228
229
mp_obj_t mp_obj_new_list(uint n, mp_obj_t *items);
mp_obj_t mp_obj_new_dict(int n_args);
mp_obj_t mp_obj_new_set(int n_args, mp_obj_t *items);
230
mp_obj_t mp_obj_new_slice(mp_obj_t start, mp_obj_t stop, mp_obj_t step);
231
mp_obj_t mp_obj_new_bound_meth(mp_obj_t meth, mp_obj_t self);
232
mp_obj_t mp_obj_new_module(qstr module_name);
233

Damien George's avatar
Damien George committed
234
mp_obj_t mp_obj_get_type(mp_obj_t o_in);
235
const char *mp_obj_get_type_str(mp_obj_t o_in);
236

237
238
void mp_obj_print_helper(void (*print)(void *env, const char *fmt, ...), void *env, mp_obj_t o_in, mp_print_kind_t kind);
void mp_obj_print(mp_obj_t o, mp_print_kind_t kind);
239
void mp_obj_print_exception(mp_obj_t exc);
240

241
242
243
244
bool mp_obj_is_callable(mp_obj_t o_in);
machine_int_t mp_obj_hash(mp_obj_t o_in);
bool mp_obj_equal(mp_obj_t o1, mp_obj_t o2);
bool mp_obj_less(mp_obj_t o1, mp_obj_t o2);
245

246
machine_int_t mp_obj_get_int(mp_obj_t arg);
247
#if MICROPY_ENABLE_FLOAT
248
249
mp_float_t mp_obj_get_float(mp_obj_t self_in);
void mp_obj_get_complex(mp_obj_t self_in, mp_float_t *real, mp_float_t *imag);
250
#endif
251
252
253
qstr mp_obj_get_qstr(mp_obj_t arg);
mp_obj_t *mp_obj_get_array_fixed_n(mp_obj_t o, machine_int_t n);
uint mp_get_index(const mp_obj_type_t *type, machine_uint_t len, mp_obj_t index);
254
mp_obj_t mp_obj_len_maybe(mp_obj_t o_in); /* may return NULL */
255
256
257
258
259
260

// none
extern const mp_obj_type_t none_type;

// bool
extern const mp_obj_type_t bool_type;
John R. Lenton's avatar
John R. Lenton committed
261
#define MP_BOOL(x) (x ? mp_const_true : mp_const_false)
262
263
264
265
266

// cell
mp_obj_t mp_obj_cell_get(mp_obj_t self_in);
void mp_obj_cell_set(mp_obj_t self_in, mp_obj_t obj);

267
268
// int
extern const mp_obj_type_t int_type;
269
270
271
272
// For long int, returns value truncated to machine_int_t
machine_int_t mp_obj_int_get(mp_obj_t self_in);
// Will rains exception if value doesn't fit into machine_int_t
machine_int_t mp_obj_int_get_checked(mp_obj_t self_in);
273

274
275
276
// exception
extern const mp_obj_type_t exception_type;
qstr mp_obj_exception_get_type(mp_obj_t self_in);
277
278
void mp_obj_exception_add_traceback(mp_obj_t self_in, qstr file, machine_uint_t line, qstr block);
void mp_obj_exception_get_traceback(mp_obj_t self_in, machine_uint_t *n, machine_uint_t **values);
279

280
281
282
// str
extern const mp_obj_type_t str_type;
qstr mp_obj_str_get(mp_obj_t self_in);
283
void mp_obj_str_print_qstr(void (*print)(void *env, const char *fmt, ...), void *env, qstr q, mp_print_kind_t kind);
284
285
286
287
288

#if MICROPY_ENABLE_FLOAT
// float
extern const mp_obj_type_t float_type;
mp_float_t mp_obj_float_get(mp_obj_t self_in);
289
mp_obj_t mp_obj_float_binary_op(int op, mp_float_t lhs_val, mp_obj_t rhs);
290
291
292
293

// complex
extern const mp_obj_type_t complex_type;
void mp_obj_complex_get(mp_obj_t self_in, mp_float_t *real, mp_float_t *imag);
294
mp_obj_t mp_obj_complex_binary_op(int op, mp_float_t lhs_real, mp_float_t lhs_imag, mp_obj_t rhs_in);
295
296
297
298
299
#endif

// tuple
extern const mp_obj_type_t tuple_type;
void mp_obj_tuple_get(mp_obj_t self_in, uint *len, mp_obj_t **items);
John R. Lenton's avatar
John R. Lenton committed
300
void mp_obj_tuple_del(mp_obj_t self_in);
301
302
303
304
305
306

// list
extern const mp_obj_type_t list_type;
mp_obj_t mp_obj_list_append(mp_obj_t self_in, mp_obj_t arg);
void mp_obj_list_get(mp_obj_t self_in, uint *len, mp_obj_t **items);
void mp_obj_list_store(mp_obj_t self_in, mp_obj_t index, mp_obj_t value);
307
mp_obj_t mp_obj_list_sort(uint n_args, const mp_obj_t *args, struct _mp_map_t *kwargs);
308

John R. Lenton's avatar
John R. Lenton committed
309
310
311
// map (the python builtin, not the dict implementation detail)
extern const mp_obj_type_t map_type;

John R. Lenton's avatar
John R. Lenton committed
312
313
314
// enumerate
extern const mp_obj_type_t enumerate_type;

John R. Lenton's avatar
John R. Lenton committed
315
316
317
// filter
extern const mp_obj_type_t filter_type;

318
319
// dict
extern const mp_obj_type_t dict_type;
320
uint mp_obj_dict_len(mp_obj_t self_in);
321
mp_obj_t mp_obj_dict_store(mp_obj_t self_in, mp_obj_t key, mp_obj_t value);
322
struct _mp_map_t *mp_obj_dict_get_map(mp_obj_t self_in);
323
324

// set
325
extern const mp_obj_type_t set_type;
326
327
void mp_obj_set_store(mp_obj_t self_in, mp_obj_t item);

328
329
330
331
// slice
extern const mp_obj_type_t slice_type;
void mp_obj_slice_get(mp_obj_t self_in, machine_int_t *start, machine_int_t *stop, machine_int_t *step);

John R. Lenton's avatar
John R. Lenton committed
332
333
334
// zip
extern const mp_obj_type_t zip_type;

335
336
// array
extern const mp_obj_type_t array_type;
John R. Lenton's avatar
John R. Lenton committed
337

338
// functions
339
typedef struct _mp_obj_fun_native_t { // need this so we can define const objects (to go in ROM)
340
    mp_obj_base_t base;
341
342
    bool is_kw : 1;
    machine_uint_t n_args_min : (sizeof(machine_uint_t) - 1); // inclusive
343
344
    machine_uint_t n_args_max; // inclusive
    void *fun;
345
346
347
    // TODO add mp_map_t *globals
    // for const function objects, make an empty, const map
    // such functions won't be able to access the global scope, but that's probably okay
348
} mp_obj_fun_native_t;
349

350
351
352
353
354
355
356
extern const mp_obj_type_t fun_native_type;
extern const mp_obj_type_t fun_bc_type;
void mp_obj_fun_bc_get(mp_obj_t self_in, int *n_args, uint *n_state, const byte **code);

// generator
extern const mp_obj_type_t gen_instance_type;

357
358
359
// module
extern const mp_obj_type_t module_type;
mp_obj_t mp_obj_new_module(qstr module_name);
360
mp_obj_t mp_obj_module_get(qstr module_name);
361
struct _mp_map_t *mp_obj_module_get_globals(mp_obj_t self_in);
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376

// staticmethod and classmethod types; defined here so we can make const versions

extern const mp_obj_type_t mp_type_staticmethod;
extern const mp_obj_type_t mp_type_classmethod;

typedef struct _mp_obj_staticmethod_t {
    mp_obj_base_t base;
    mp_obj_t fun;
} mp_obj_staticmethod_t;

typedef struct _mp_obj_classmethod_t {
    mp_obj_base_t base;
    mp_obj_t fun;
} mp_obj_classmethod_t;