v1.1.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Groups Pages
abi/types.h
1 /* -*- mode: C; c-basic-offset: 4; intent-tabs-mode: nil -*-
2  *
3  * This file is part of the public interface to the Sifteo SDK.
4  * Copyright <c> 2012 Sifteo, Inc. All rights reserved.
5  */
6 
7 #ifndef _SIFTEO_ABI_TYPES_H
8 #define _SIFTEO_ABI_TYPES_H
9 
10 #ifdef NOT_USERSPACE
11 # include <stdint.h>
12 #endif
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /*
19  * Standard integer types. This is a subset of what's in stdint.h,
20  * but we define them ourselves since system headers are not available.
21  *
22  * If we're doing a non-userspace build, however, these are pulled in
23  * from stdint.h above.
24  */
25 
26 #ifndef NOT_USERSPACE
27  typedef signed char int8_t;
28  typedef unsigned char uint8_t;
29  typedef signed short int16_t;
30  typedef unsigned short uint16_t;
31  typedef signed int int32_t;
32  typedef unsigned int uint32_t;
33  typedef signed long long int64_t;
34  typedef unsigned long long uint64_t;
35  typedef signed long intptr_t;
36  typedef unsigned long uintptr_t;
37 #endif
38 
39 // We can use 'bool' even in pure C code.
40 #ifndef __cplusplus
41  typedef uint8_t bool;
42 #endif
43 
44 /*
45  * Basic data types which are valid across the user/system boundary.
46  */
47 
48 #define _SYS_NUM_CUBE_SLOTS 24 // Total supported cube slots
49 #define _SYS_CUBE_ID_INVALID 0xFF // Reserved _SYSCubeID value
50 #define _SYS_BATTERY_MAX 0x10000 // Battery levels are 16.16 fixed point
51 
52 typedef uint8_t _SYSCubeID; // Cube slot index
53 typedef uint8_t _SYSNeighborID; // Neighbored object ID (superset of _SYSCubeID)
54 typedef int8_t _SYSSideID; // Cube side index
55 typedef uint32_t _SYSCubeIDVector; // One bit for each cube slot, MSB-first
56 typedef uint8_t _SYSAssetSlot; // Ordinal for one of the game's asset slots
57 
58 /*
59  * Small vector types
60  */
61 
62 struct _SYSInt2 {
63  int32_t x, y;
64 };
65 
66 struct _SYSInt3 {
67  int32_t x, y, z;
68 };
69 
70 union _SYSByte4 {
71  struct {
72  int8_t x, y, z, w;
73  };
74  uint32_t value;
75 };
76 
77 /*
78  * Neighbors
79  */
80 
81 #define _SYS_NEIGHBOR_TYPE_MASK 0xE0 // Mask for neighbor type bits
82 #define _SYS_NEIGHBOR_ID_MASK 0x1F // Mask for neighbor ID bits
83 
84 #define _SYS_NEIGHBOR_CUBE 0x00 // Neighbored to normal cube
85 #define _SYS_NEIGHBOR_BASE 0x20 // Neighbored to base
86 
87 #define _SYS_NEIGHBOR_NONE 0xFF // No neighbor
88 
89 union _SYSNeighborState {
90  uint32_t value;
91  _SYSNeighborID sides[4];
92 };
93 
94 /*
95  * Motion reporting
96  */
97 
98 #define _SYS_MOTION_MAX_ENTRIES 256 // Max size of motion buffer
99 #define _SYS_MOTION_TIMESTAMP_NS 250000 // Nanoseconds per timestamp unit (0.25 ms)
100 #define _SYS_MOTION_TIMESTAMP_HZ 4000 // Reciprocal of _SYS_MOTION_TIMESTAMP_NS
101 
102 struct _SYSMotionBufferHeader {
103  uint8_t tail;
104  uint8_t last;
105  uint8_t rate;
106  uint8_t reserved;
107  /*
108  * Followed by variable-size array of _SYSByte4.
109  *
110  * The 'w' field is used for a timestamp, encoded as a (delta - 1) since
111  * the last mesurement, in units of _SYS_MOTION_TIMESTAMP_NS. This means
112  * the maximum representable delta is exactly 64 milliseconds. Deltas of
113  * longer than this will be represented by duplicating samples in the buffer.
114  */
115 };
116 
117 struct _SYSMotionBuffer {
118  struct _SYSMotionBufferHeader header;
119  union _SYSByte4 samples[_SYS_MOTION_MAX_ENTRIES];
120 };
121 
122 struct _SYSMotionMedianAxis {
123  int8_t median;
124  int8_t minimum;
125  int8_t maximum;
126 };
127 
128 struct _SYSMotionMedian {
129  struct _SYSMotionMedianAxis axes[3];
130 };
131 
132 /*
133  * Type bits, for use in the 'tag' for the low-level _SYS_log() handler.
134  * Normally these don't need to be used in usermode code, they're inserted
135  * automatically by slinky when expanding _SYS_lti_log().
136  */
137 
138 #define _SYS_LOGTYPE_FMT 0 // param = strtab offest
139 #define _SYS_LOGTYPE_STRING 1 // param = 0, v1 = ptr
140 #define _SYS_LOGTYPE_HEXDUMP 2 // param = length, v1 = ptr
141 #define _SYS_LOGTYPE_SCRIPT 3 // param = script type
142 
143 #define _SYS_SCRIPT_NONE 0 // Normal logging
144 #define _SYS_SCRIPT_LUA 1 // Built-in Lua interpreter
145 
146 /*
147  * Internal state of the Pseudorandom Number Generator, maintained in user RAM.
148  */
149 
150 struct _SYSPseudoRandomState {
151  uint32_t a, b, c, d;
152 };
153 
154 /*
155  * Versioning.
156  *
157  * SYS_FEATUREs is a mask of features supported by the current version of the OS.
158  *
159  * NB: be sure to add any new features to _SYS_FEATURE_ALL.
160  */
161 
162 #define _SYS_OS_VERSION_MASK 0xffffff
163 #define _SYS_HW_VERSION_SHIFT 24
164 
165 // defaults for earlier OS versions that don't support _SYS_version()
166 #define _SYS_OS_VERSION_NONE 0x00
167 
168 #define _SYS_HW_VERSION_NONE 0x00
169 #define _SYS_HW_VERSION_GEN_2 0x02
170 #define _SYS_HW_VERSION_GEN_2_5 0x04
171 
172 #define _SYS_FEATURE_SYS_VERSION (1 << 0)
173 #define _SYS_FEATURE_BLUETOOTH (1 << 1)
174 #define _SYS_FEATURE_ALL (_SYS_FEATURE_SYS_VERSION | _SYS_FEATURE_BLUETOOTH)
175 
176 /*
177  * Hardware IDs are 64-bit numbers that uniquely identify a
178  * particular cube. A valid HWIDs never contains 0xFF bytes.
179  */
180 
181 #define _SYS_HWID_BYTES 8
182 #define _SYS_HWID_BITS 64
183 #define _SYS_INVALID_HWID ((uint64_t)-1)
184 
185 /*
186  * Filesystem
187  */
188 
189 #define _SYS_FS_VOL_GAME 0x4d47
190 #define _SYS_FS_VOL_LAUNCHER 0x4e4c
191 
192 #define _SYS_FS_MAX_OBJECT_KEYS 256
193 #define _SYS_FS_MAX_OBJECT_SIZE 4080
194 
195 // Opaque nonzero ID for a filesystem volume
196 typedef uint32_t _SYSVolumeHandle;
197 
198 // Application-defined ID for a key in our key/value object store
199 typedef uint8_t _SYSObjectKey;
200 
201 struct _SYSFilesystemInfo {
202  uint32_t unitSize; // Size of allocation unit, in bytes
203  uint32_t totalUnits; // Total number of allocation units on device
204  uint32_t freeUnits; // Number of free or immediately-recyclable units
205  uint32_t systemUnits; // Used by system data (cube pairing data, asset cache)
206  uint32_t launcherElfUnits; // Used by launcher ELF volumes
207  uint32_t launcherObjUnits; // Used by StoredObjects owned by launcher
208  uint32_t gameElfUnits; // Used by game ELF volumes
209  uint32_t gameObjUnits; // Used by StoredObjects owned by games
210  uint32_t selfElfUnits; // Used by the currently executing volume (may overlap with above)
211  uint32_t selfObjUnits; // StoredObjects owned by the currently executing volume (may overlap with above)
212 };
213 
214 
215 /*
216  * I/O (common)
217  */
218 
219 struct _SYSIoQueueHeader {
220  uint8_t head;
221  uint8_t tail;
222  uint8_t last;
223  uint8_t reserved;
224  // Followed by variable-size array of _SYS***Packet
225 };
226 
227 
228 /*
229  * Bluetooth
230  */
231 
232 #define _SYS_BT_PACKET_BYTES 19
233 #define _SYS_BT_MAX_QUEUED_PACKETS 256
234 
235 struct _SYSBluetoothPacket {
236  uint8_t length;
237  uint8_t type;
238  uint8_t bytes[_SYS_BT_PACKET_BYTES];
239 };
240 
241 struct _SYSBluetoothQueueHeader {
242  uint8_t head;
243  uint8_t tail;
244  uint8_t last;
245  uint8_t reserved;
246  // Followed by variable-size array of _SYSBluetoothPacket
247 };
248 
249 struct _SYSBluetoothQueue {
250  struct _SYSBluetoothQueueHeader header;
251  struct _SYSBluetoothPacket packets[_SYS_BT_MAX_QUEUED_PACKETS];
252 };
253 
254 struct _SYSBluetoothCounters {
255  uint32_t rxPackets;
256  uint32_t txPackets;
257  uint32_t rxBytes;
258  uint32_t txBytes;
259  uint32_t rxUserDropped;
260 };
261 
262 /*
263  * USB
264  */
265 
266 #define _SYS_USB_PACKET_BYTES 60
267 #define _SYS_USB_MAX_QUEUED_PACKETS 80
268 
269 struct _SYSUsbPacket {
270  uint8_t length;
271  uint8_t reserved0;
272  uint16_t reserved1;
273  uint32_t type;
274  uint8_t bytes[_SYS_USB_PACKET_BYTES];
275 };
276 
277 struct _SYSUsbQueue {
278  struct _SYSIoQueueHeader header;
279  struct _SYSUsbPacket packets[_SYS_USB_MAX_QUEUED_PACKETS];
280 };
281 
282 struct _SYSUsbCounters {
283  uint32_t rxPackets;
284  uint32_t txPackets;
285  uint32_t rxBytes;
286  uint32_t txBytes;
287  uint32_t rxUserDropped;
288 };
289 
290 /*
291  * RFC4122 compatible UUIDs.
292  *
293  * These are used in game metadata, to uniquely identify a particular
294  * binary. They are stored in network byte order, with field names compatible
295  * with RFC4122.
296  */
297 
298 struct _SYSUUID {
299  union {
300  struct {
301  uint32_t time_low;
302  uint16_t time_mid;
303  uint16_t time_hi_and_version;
304  uint8_t clk_seq_hi_res;
305  uint8_t clk_seq_low;
306  uint8_t node[6];
307  };
308  uint8_t bytes[16];
309  uint16_t hwords[8];
310  uint32_t words[4];
311  };
312 };
313 
314 /*
315  * System error codes, returned by some syscalls:
316  * - _SYS_fs_objectRead
317  * - _SYS_fs_objectWrite
318  *
319  * Where possible, these numbers line up with standard POSIX errno values.
320  */
321 
322 #define _SYS_ENOENT -2 // No such object found
323 #define _SYS_EFAULT -14 // Bad address
324 #define _SYS_EINVAL -22 // Invalid argument
325 #define _SYS_ENOSPC -28 // No space left on device
326 
327 /*
328  * Flags for _SYS_shutdown()
329  */
330 
331 #define _SYS_SHUTDOWN_WITH_UI (1 << 0) // Present shutdown user interface, allow cancellation
332 
333 
334 #ifdef __cplusplus
335 } // extern "C"
336 #endif
337 
338 #endif