v1.1.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Groups Pages
elf.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_ELF_H
8 #define _SIFTEO_ABI_ELF_H
9 
10 #include <sifteo/abi/types.h>
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 
17 /*
18  * ELF binary format.
19  *
20  * Loadable programs in this system are standard ELF binaries, however their
21  * instruction set is a special restricted subset of Thumb-2 as defined by the
22  * Sifteo Virtual Machine.
23  *
24  * In addition to standard read-only data, read-write data, and BSS segments,
25  * we support a special metadata segment. This contains a key-value dictionary
26  * of metadata records.
27  *
28  * The contents of the metadata segment is structured as first an array of
29  * key/size words, then a stream of variable-size values. The values must be
30  * aligned according to their natural ABI alignment, and they must not cross
31  * a memory page boundary. Each key occurs at most once in this table; multiple
32  * values with the same key are concatenated by the linker.
33  *
34  * The last _SYSMetadataKey has the MSB set in its 'stride' value.
35  *
36  * Strings are zero-terminated. Additional padding bytes may appear after
37  * any value.
38  */
39 
40 // SVM-specific program header types
41 #define _SYS_ELF_PT_METADATA 0x7000f001 // Metadata key/value dictionary
42 #define _SYS_ELF_PT_LOAD_FASTLZ 0x7000f002 // PT_LOAD, with FastLZ (Level 1) compression
43 
44 struct _SYSMetadataKey {
45  uint16_t stride; // Byte offset from this value to the next
46  uint16_t key; // _SYS_METADATA_*
47 };
48 
49 // Maximum size for a single metadata value
50 #define _SYS_MAX_METADATA_ITEM_BYTES 0x100
51 
52 // System Metadata keys
53 #define _SYS_METADATA_NONE 0x0000 // Ignored. (padding)
54 #define _SYS_METADATA_UUID 0x0001 // Binary UUID for this specific build
55 #define _SYS_METADATA_BOOT_ASSET 0x0002 // Array of _SYSMetadataBootAsset
56 #define _SYS_METADATA_TITLE_STR 0x0003 // Human readable game title string
57 #define _SYS_METADATA_PACKAGE_STR 0x0004 // DNS-style package string
58 #define _SYS_METADATA_VERSION_STR 0x0005 // Version string
59 #define _SYS_METADATA_ICON_96x96 0x0006 // _SYSMetadataImage
60 #define _SYS_METADATA_NUM_ASLOTS 0x0007 // uint8_t, count of required AssetSlots
61 #define _SYS_METADATA_CUBE_RANGE 0x0008 // _SYSMetadataCubeRange
62 #define _SYS_METADATA_MIN_OS_VERSION 0x0009 // uint32_t minimum OS version required
63 #define _SYS_METADATA_IS_DEMO_OF_STR 0x000a // DNS-style string of the full version of this demo app
64 
65 struct _SYSMetadataBootAsset {
66  uint32_t pHdr; // Virtual address for _SYSAssetGroupHeader
67  _SYSAssetSlot slot; // Asset group slot to load this into
68  uint8_t reserved[3]; // Must be zero;
69 };
70 
71 struct _SYSMetadataCubeRange {
72  uint8_t minCubes;
73  uint8_t maxCubes;
74 };
75 
76 struct _SYSMetadataImage {
77  uint8_t width;
78  uint8_t height;
79  uint8_t frames;
80  uint8_t format;
81  uint32_t groupHdr;
82  uint32_t pData;
83 };
84 
85 /*
86  * Entry point. Our standard entry point is main(), with no arguments
87  * or return values, declared using C linkage.
88  */
89 
90 #ifndef NOT_USERSPACE
91 void main(void);
92 #endif
93 
94 /*
95  * Link-time intrinsics.
96  *
97  * These functions are replaced during link-time optimization.
98  *
99  * Logging supports many standard printf() format specifiers,
100  * as documented in sifteo/macros.h
101  *
102  * To work around limitations in C variadic functions, _SYS_lti_metadata()
103  * supports a format string which specifies what data type each argument
104  * should be cast to. Data types here automatically imply ABI-compatible
105  * alignment and padding:
106  *
107  * "b" = int8_t
108  * "B" = uint8_t
109  * "h" = int16_t
110  * "H" = uint16_t
111  * "i" = int32_t
112  * "I" = uint32_t
113  * "s" = String (NUL terminator is *not* automatically added)
114  *
115  * Counters:
116  * This is a mechanism for generating monotonic unique IDs at link-time.
117  * Every _SYS_lti_counter() call with the same 'name' will return a
118  * different value, starting with zero. Values are assigned in order of
119  * decreasing priority.
120  *
121  * UUIDs:
122  * We support link-time generation of standard UUIDs. For every unique
123  * 'key', the linker will generate a different UUID. Since a full UUID
124  * is too large to return directly, it is accessed as a group of four
125  * little-endian 32-bit words, using values of 'index' from 0 to 3.
126  *
127  * Static initializers:
128  * In global varaibles which aren't themselves constant but which were
129  * initialized to a constant, _SYS_lti_initializer() can be used to retrieve
130  * that initializer value at link-time. If 'require' is 'true', the value
131  * must be resolveable to a constant static initializer of a link error
132  * will result. If 'require' is false, we return the static initializer if
133  * possible, or pass through 'value' without modification if not.
134  */
135 
136 unsigned _SYS_lti_isDebug();
137 void _SYS_lti_abort(bool enable, const char *message);
138 void _SYS_lti_log(const char *fmt, ...);
139 void _SYS_lti_metadata(uint16_t key, const char *fmt, ...);
140 unsigned _SYS_lti_counter(const char *name, int priority);
141 uint32_t _SYS_lti_uuid(unsigned key, unsigned index);
142 const void *_SYS_lti_initializer(const void *value, bool require);
143 bool _SYS_lti_isConstant(unsigned value);
144 
145 
146 #ifdef __cplusplus
147 } // extern "C"
148 #endif
149 
150 #endif