diff options
author | Tom Hughes <tomhughes@chromium.org> | 2021-01-26 10:38:55 -0800 |
---|---|---|
committer | Commit Bot <commit-bot@chromium.org> | 2021-01-28 16:38:57 +0000 |
commit | 2f40b71b625bcd826fd0cb4a005985abef0b8903 (patch) | |
tree | 1f67563e6de1dc64fd4d40bb50ea70d2a17d18a7 /third_party | |
parent | 4e950b9fde9e5d7197d2558f7a36bc809e193a49 (diff) | |
download | chrome-ec-2f40b71b625bcd826fd0cb4a005985abef0b8903.tar.gz |
docs: Run mdformat on all .md files
BRANCH=none
BUG=b:178648877
TEST=view in gitiles
Signed-off-by: Tom Hughes <tomhughes@chromium.org>
Change-Id: I0ac5581ba7bc512234d40dbf34222422afa9c725
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2650551
Reviewed-by: Jack Rosenthal <jrosenth@chromium.org>
Diffstat (limited to 'third_party')
-rw-r--r-- | third_party/incbin/README.md | 123 |
1 files changed, 65 insertions, 58 deletions
diff --git a/third_party/incbin/README.md b/third_party/incbin/README.md index cada41fa16..da32103e9e 100644 --- a/third_party/incbin/README.md +++ b/third_party/incbin/README.md @@ -4,7 +4,7 @@ Include binary files in your C/C++ applications with ease ## Example -``` c +```c #include "incbin.h" INCBIN(Icon, "icon.png"); @@ -28,52 +28,56 @@ Include binary files in your C/C++ applications with ease 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. +* 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 + +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 incase your binary data may be used in vectorized -code. The table of the alignments for SIMD this header recognizes is as follows: +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 | +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 +```c #define INCBIN_PREFIX g_ #include "incbin.h" INCBIN(test, "test.txt"); @@ -84,9 +88,10 @@ instance // const unsigned int g_testSize; ``` -You can also choose to have no prefix by defining the prefix with nothing, for example: +You can also choose to have no prefix by defining the prefix with nothing, for +example: -``` c +```c #define INCBIN_PREFIX #include "incbin.h" INCBIN(test, "test.txt"); @@ -98,16 +103,17 @@ You can also choose to have no prefix by defining the prefix with nothing, for e ``` ## 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) +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 +```c #define INCBIN_STYLE INCBIN_STYLE_SNAKE #include "incbin.h" INCBIN(test, "test.txt"); @@ -122,14 +128,15 @@ 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. +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 +```c #define INCBIN_OUTPUT_SECTION ".irom.text" #include "incbin.h" INCBIN(Foo, "foo.txt"); @@ -141,27 +148,27 @@ INCBIN(Foo, "foo.txt"); `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. +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` +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. +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. +Documentation for the API is provided by the header using Doxygen notation. For +licensing information see UNLICENSE. |