1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
# incbin
Include binary files in your C/C++ applications with ease
## Example
```c
#include "incbin.h"
INCBIN(Icon, "icon.png");
// This translation unit now has three symbols
// const unsigned char gIconData[];
// const unsigned char *const gIconEnd; // a marker to the end, take the address to get the ending pointer
// const unsigned int gIconSize;
// Reference in other translation units like this
INCBIN_EXTERN(Icon);
// This translation unit now has three extern symbols
// Use `extern "C"` in case of writing C++ code
// extern const unsigned char gIconData[];
// extern const unsigned char *const gIconEnd; // a marker to the end, take the address to get the ending pointer
// extern const unsigned int gIconSize;
```
## Portability
Known to work on the following compilers
* GCC
* Clang
* PathScale
* Intel
* Solaris & Sun Studio
* Green Hills
* SNC (ProDG)
* Diab C++ (WindRiver)
* XCode
* ArmCC
* RealView
* ImageCraft
* Stratus VOS C
* TinyCC
* cparser & libfirm
* LCC
* MSVC _See MSVC below_
If your compiler is not listed, as long as it supports GCC inline assembler,
this should work.
## MISRA
INCBIN can be used in MISRA C setting. However it should be independently
checked due to its use of inline assembly to achieve what it does. Independent
verification of the header has been done several times based on commit:
7e327a28ba5467c4202ec37874beca7084e4b08c
## Alignment
The data included by this tool will be aligned on the architectures word
boundary unless some variant of SIMD is detected, then it's aligned on a byte
boundary that respects SIMD convention just in case your binary data may be used
in vectorized code. The table of the alignments for SIMD this header recognizes
is as follows:
SIMD | Alignment
-------------------------------------- | ---------
SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 | 16
Neon | 16
AVX, AVX2 | 32
AVX512 | 64
## Prefix
By default, `incbin.h` emits symbols with a `g` prefix. This can be adjusted by
defining `INCBIN_PREFIX` before including `incbin.h` with a desired prefix. For
instance
```c
#define INCBIN_PREFIX g_
#include "incbin.h"
INCBIN(test, "test.txt");
// This translation unit now has three symbols
// const unsigned char g_testData[];
// const unsigned char *const g_testEnd;
// const unsigned int g_testSize;
```
You can also choose to have no prefix by defining the prefix with nothing, for
example:
```c
#define INCBIN_PREFIX
#include "incbin.h"
INCBIN(test, "test.txt");
// This translation unit now has three symbols
// const unsigned char testData[];
// const unsigned char *const testEnd;
// const unsigned int testSize;
```
## Style
By default, `incbin.h` emits symbols with `CamelCase` style. This can be
adjusted by defining `INCBIN_STYLE` before including `incbin.h` to change the
style. There are two possible styles to choose from
* INCBIN_STYLE_CAMEL (CamelCase)
* INCBIN_STYLE_SNAKE (snake_case)
For instance:
```c
#define INCBIN_STYLE INCBIN_STYLE_SNAKE
#include "incbin.h"
INCBIN(test, "test.txt");
// This translation unit now has three symbols
// const unsigned char gtest_data[];
// const unsigned char *const gtest_end;
// const unsigned int gtest_size;
```
Combining both the style and prefix allows for you to adjust `incbin.h` to suite
your existing style and practices.
## Overriding Linker Output section
By default, `incbin.h` emits into the read-only linker output section used on
the detected platform. If you need to override this for whatever reason, you can
manually specify the linker output section.
For example, to emit data into program memory for
[esp8266/Arduino](github.com/esp8266/Arduino):
```c
#define INCBIN_OUTPUT_SECTION ".irom.text"
#include "incbin.h"
INCBIN(Foo, "foo.txt");
// Data is emitted into program memory that never gets copied to RAM
```
## Explanation
`INCBIN` is a macro which uses the inline assembler provided by almost all
compilers to include binary files. It achieves this by utilizing the `.incbin`
directive of the inline assembler. It then uses the assembler to calculate the
size of the included binary and exports two global symbols that can be
externally referenced in other translation units which contain the data and size
of the included binary data respectively.
## MSVC
Supporting MSVC is slightly harder as MSVC lacks an inline assembler which can
include data. To support this we ship a tool which can process source files
containing `INCBIN` macro usage and generate an external source file containing
the data of all of them combined. This file is named `data.c` by default. Just
include it into your build and use the `incbin.h` to reference data as needed.
It's suggested you integrate this tool as part of your projects's pre-build
events so that this can be automated. A more comprehensive list of options for
this tool can be viewed by invoking the tool with `-help`
If you're using a custom prefix, be sure to specify the prefix on the command
line with `-p <prefix>` so that everything matches up; similarly, if you're
using a custom style, be sure to specify the style on the command line with `-S
<style>` as well.
## Miscellaneous
Documentation for the API is provided by the header using Doxygen notation. For
licensing information see UNLICENSE.
|
