summaryrefslogtreecommitdiff
path: root/third_party/incbin/README.md
diff options
context:
space:
mode:
authorJack Rosenthal <jrosenth@chromium.org>2021-11-04 12:11:58 -0600
committerCommit Bot <commit-bot@chromium.org>2021-11-05 04:22:34 +0000
commit252457d4b21f46889eebad61d4c0a65331919cec (patch)
tree01856c4d31d710b20e85a74c8d7b5836e35c3b98 /third_party/incbin/README.md
parent08f5a1e6fc2c9467230444ac9b582dcf4d9f0068 (diff)
downloadchrome-ec-stabilize-14526.57.B-ish.tar.gz
In the interest of making long-term branch maintenance incur as little technical debt on us as possible, we should not maintain any files on the branch we are not actually using. This has the added effect of making it extremely clear when merging CLs from the main branch when changes have the possibility to affect us. The follow-on CL adds a convenience script to actually pull updates from the main branch and generate a CL for the update. BUG=b:204206272 BRANCH=ish TEST=make BOARD=arcada_ish && make BOARD=drallion_ish Signed-off-by: Jack Rosenthal <jrosenth@chromium.org> Change-Id: I17e4694c38219b5a0823e0a3e55a28d1348f4b18 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3262038 Reviewed-by: Jett Rink <jettrink@chromium.org> Reviewed-by: Tom Hughes <tomhughes@chromium.org>
Diffstat (limited to 'third_party/incbin/README.md')
-rw-r--r--third_party/incbin/README.md174
1 files changed, 0 insertions, 174 deletions
diff --git a/third_party/incbin/README.md b/third_party/incbin/README.md
deleted file mode 100644
index da32103e9e..0000000000
--- a/third_party/incbin/README.md
+++ /dev/null
@@ -1,174 +0,0 @@
-# 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.