Part 1
요약·해설
16-bit tag와 length, native-endian value, 32-bit alignment와 standard ID range를 설명합니다.
Magic · TLV · End tag
User 0x000-0x7ff
west bindesc
Part 2
접을 수 있는 영어 원문 전체
영어 원문 전체 펼치기
F19DE34E494DBF0B8D8F55E78BC9C1B1E4F2CD15AB1F9F6ED9E74B32F501CCB4
.. _binary_descriptors:
Binary Descriptors
##################
Binary Descriptors are constant data objects storing information about the binary executable.
Unlike "regular" constants, binary descriptors are linked to a known offset in the binary, making
them accessible to other programs, such as a different image running on the same device or a host tool.
A few examples of constants that would make useful binary descriptors are: kernel version, app version,
build time, compiler version, environment variables, compiling host name, etc.
Binary descriptors are created by using the ``DEFINE_BINDESC_*`` macros. For example:
.. code-block:: c
#include <zephyr/bindesc.h>
BINDESC_STR_DEFINE(my_string, 2, "Hello world!"); // Unique ID is 2
``my_string`` could then be accessed using:
.. code-block:: c
printk("my_string: %s\n", BINDESC_GET_STR(my_string));
But it could also be retrieved by ``west bindesc``:
.. code-block:: bash
$ west bindesc custom_search STR 2 build/zephyr/zephyr.bin
"Hello world!"
Internals
*********
Binary descriptors are implemented with a TLV (tag, length, value) header linked
to a known offset in the binary image. This offset may vary between architectures,
but generally the descriptors are linked as close to the beginning of the image as
possible. In architectures where the image must begin with a vector table (such as
ARM), the descriptors are linked right after the vector table. The reset vector points
to the beginning of the text section, which is after the descriptors. In architectures
where the image must begin with executable code (e.g. x86), a jump instruction is injected at
the beginning of the image, in order to skip over the binary descriptors, which are right
after the jump instruction.
Each tag is a 16 bit unsigned integer, where the most significant nibble (4 bits) is the type
(currently uint, string or bytes), and the rest is the ID. The ID is globally unique to each
descriptor. For example, the ID of the app version string is ``0x800``, and a string
is denoted by 0x1, making the app version tag ``0x1800``. The length is a 16 bit
number equal to the length of the data in bytes. The data is the actual descriptor
value. All binary descriptor numbers (magic, tags, uints) are laid out in memory
in the endianness native to the SoC. ``west bindesc`` assumes little endian by default,
so if the image belongs to a big endian SoC, the appropriate flag should be given to the
tool.
The binary descriptor header starts with the magic number ``0xb9863e5a7ea46046``. It's followed
by the TLVs, and ends with the ``DESCRIPTORS_END`` (``0xffff``) tag. The tags are
always aligned to 32 bits. If the value of the previous descriptor had a non-aligned
length, zero padding will be added to ensure that the current tag is aligned.
Putting it all together, here is what the example above would look like in memory
(of a little endian SoC):
.. code-block::
46 60 a4 7e 5a 3e 86 b9 02 10 0d 00 48 65 6c 6c 6f 20 77 6f 72 6c 64 21 00 00 00 00 ff ff
| magic | tag |length| H e l l o w o r l d ! | pad | end |
Usage
*****
Binary descriptors are always created by the ``BINDESC_*_DEFINE`` macros. As shown in
the example above, a descriptor can be generated from any string or integer, with any
ID. However, it is recommended to comply with the standard tags defined in
``include/zephyr/bindesc.h``, as that would have the following benefits:
1. The ``west bindesc`` tool would be able to recognize what the descriptor means and
print a meaningful tag
2. It would enforce consistency between various apps from various sources
3. It allows upstream-ability of descriptor generation (see Standard Descriptors)
To define a descriptor with a standard tag, just use the tags included from ``bindesc.h``:
.. code-block:: c
#include <zephyr/bindesc.h>
BINDESC_STR_DEFINE(app_version, BINDESC_ID_APP_VERSION_STRING, "1.2.3");
Standard Descriptors
====================
Some descriptors might be trivial to implement, and could therefore be implemented
in a standard way in upstream Zephyr. These could then be enabled via Kconfig, instead
of requiring every user to reimplement them. These include build times, kernel version,
and host info. For example, to add the build date and time as a string, the following
configs should be enabled:
.. code-block:: kconfig
# Enable binary descriptors
CONFIG_BINDESC=y
# Enable definition of binary descriptors
CONFIG_BINDESC_DEFINE=y
# Enable default build time binary descriptors
CONFIG_BINDESC_DEFINE_BUILD_TIME=y
CONFIG_BINDESC_BUILD_DATE_TIME_STRING=y
To avoid collisions with user defined descriptors, the standard descriptors were allotted
the range between ``0x800-0xfff``. This leaves ``0x000-0x7ff`` to users.
For more information read the ``help`` sections of these Kconfig symbols.
By convention, each Kconfig symbol corresponds to a binary descriptor whose
name is the Kconfig name (with ``CONFIG_BINDESC_`` removed) in lower case. For example,
``CONFIG_BINDESC_KERNEL_VERSION_STRING`` creates a descriptor that can be
accessed using ``BINDESC_GET_STR(kernel_version_string)``.
west bindesc tool
=================
``west`` is able to parse and display binary descriptors from a given executable image.
For more information refer to ``west bindesc --help`` or the :ref:`documentation<west-bindesc>`.
API Reference
*************
.. doxygengroup:: bindesc_define
Part 3
한국어 전문 번역
Binary Descriptor는 binary executable에 관한 정보를 저장하는 constant data object입니다. 일반 constant와 달리 binary 안의 알려진 offset에 link되므로, 같은 device에서 실행되는 다른 image나 host tool 같은 외부 program도 접근할 수 있습니다. Kernel version, application version, build time, compiler version, environment variable, compile host name 등이 유용한 descriptor 예입니다.
Binary descriptor는 DEFINE_BINDESC_* macro로 만듭니다. 예를 들면 다음과 같습니다.
#include <zephyr/bindesc.h>
BINDESC_STR_DEFINE(my_string, 2, "Hello world!"); // Unique ID is 2
그 뒤 my_string은 다음처럼 접근할 수 있습니다.
printk("my_string: %s\n", BINDESC_GET_STR(my_string));
또는 west bindesc로도 가져올 수 있습니다.
$ west bindesc custom_search STR 2 build/zephyr/zephyr.bin
"Hello world!"
내부 구조
Binary descriptor는 binary image의 알려진 offset에 link되는 TLV(tag, length, value) header로 구현됩니다. Offset은 architecture에 따라 달라질 수 있지만 일반적으로 image 시작 지점에 최대한 가깝게 배치합니다. ARM처럼 image가 vector table로 시작해야 하는 architecture에서는 descriptor를 vector table 바로 뒤에 link합니다. Reset vector는 descriptor 뒤에 있는 text section 시작점을 가리킵니다. x86처럼 image가 executable code로 시작해야 하는 architecture에서는 image 시작에 jump instruction을 넣어, jump 바로 뒤의 descriptor 영역을 건너뜁니다.
각 tag는 16-bit unsigned integer입니다. 최상위 nibble 4-bit가 type이며 현재 uint, string, bytes를 나타내고, 나머지 bit가 ID입니다. ID는 descriptor마다 global unique합니다. 예를 들어 application version string ID는 0x800이고 string type은 0x1이므로 application version tag는 0x1800입니다. Length는 data byte 길이와 같은 16-bit number이며 data가 실제 descriptor value입니다. Magic, tag, uint 등 모든 binary descriptor number는 SoC native endianness로 memory에 놓입니다. west bindesc는 기본적으로 little endian을 가정하므로 big-endian SoC image라면 알맞은 flag를 전달해야 합니다.
Binary descriptor header는 magic number 0xb9863e5a7ea46046로 시작합니다. 이어서 TLV가 오고 DESCRIPTORS_END, 즉 0xffff tag로 끝납니다. Tag는 항상 32-bit boundary에 align됩니다. 앞 descriptor value 길이가 align되지 않으면 현재 tag를 맞추기 위해 zero padding을 추가합니다.
앞 예제를 little-endian SoC memory에 배치하면 다음과 같습니다.
46 60 a4 7e 5a 3e 86 b9 02 10 0d 00 48 65 6c 6c 6f 20 77 6f 72 6c 64 21 00 00 00 00 ff ff
| magic | tag |length| H e l l o w o r l d ! | pad | end |
사용법
Binary descriptor는 항상 BINDESC_*_DEFINE macro로 만듭니다. 앞 예제처럼 임의 string이나 integer와 ID로 descriptor를 생성할 수 있지만, include/zephyr/bindesc.h의 standard tag를 따르는 것이 좋습니다.
west bindesc가 descriptor 의미를 인식하고 의미 있는 tag를 출력할 수 있습니다.- 출처가 다른 여러 application 사이에서 일관성을 강제할 수 있습니다.
- Descriptor 생성을 upstream Zephyr에 포함할 수 있습니다.
Standard tag descriptor를 정의하려면 bindesc.h의 tag를 사용합니다.
#include <zephyr/bindesc.h>
BINDESC_STR_DEFINE(app_version, BINDESC_ID_APP_VERSION_STRING, "1.2.3");
Standard Descriptor
구현이 단순한 descriptor는 upstream Zephyr에서 standard 방식으로 제공할 수 있습니다. 그러면 모든 user가 다시 구현하는 대신 Kconfig로 enable할 수 있습니다. Build time, kernel version, host information 등이 해당합니다. Build date와 time을 string으로 추가하려면 다음 configuration을 enable합니다.
# Enable binary descriptors
CONFIG_BINDESC=y
# Enable definition of binary descriptors
CONFIG_BINDESC_DEFINE=y
# Enable default build time binary descriptors
CONFIG_BINDESC_DEFINE_BUILD_TIME=y
CONFIG_BINDESC_BUILD_DATE_TIME_STRING=y
User-defined descriptor와 충돌하지 않도록 standard descriptor에는 0x800-0xfff 범위를 할당했고, user는 0x000-0x7ff를 사용합니다. 자세한 내용은 각 Kconfig symbol의 help를 확인합니다. Convention상 각 Kconfig symbol은 CONFIG_BINDESC_를 제거하고 lower case로 바꾼 이름의 binary descriptor에 대응합니다. 예를 들어 CONFIG_BINDESC_KERNEL_VERSION_STRING은 BINDESC_GET_STR(kernel_version_string)으로 접근할 descriptor를 생성합니다.
west bindesc tool
west는 주어진 executable image에서 binary descriptor를 parse하고 표시할 수 있습니다. 자세한 사용법은 west bindesc --help 또는 west 관련 문서를 참고합니다.
API Reference
원문의 Doxygen group bindesc_define에는 binary descriptor 정의 macro와 관련 API가 수록됩니다.
Source
출처
영어 원문에는 문단, 문서 지시문, 표, 코드, 코드 심벌, 경로를 그대로 보존했습니다.