From 41e1c436e57d2a42caebea4bb15ba381dcc58c40 Mon Sep 17 00:00:00 2001 From: Yonatan Schachter Date: Wed, 20 Dec 2023 19:10:27 +0200 Subject: [PATCH] doc: bindesc: Add documentation for bindesc read Added documentation for reading binary descriptors. Signed-off-by: Yonatan Schachter --- doc/services/binary_descriptors/index.rst | 43 +++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/doc/services/binary_descriptors/index.rst b/doc/services/binary_descriptors/index.rst index dab7ee61b11..d25e5b69344 100644 --- a/doc/services/binary_descriptors/index.rst +++ b/doc/services/binary_descriptors/index.rst @@ -113,6 +113,47 @@ name is the Kconfig name (with ``CONFIG_BINDESC_`` removed) in lower case. For e ``CONFIG_BINDESC_KERNEL_VERSION_STRING`` creates a descriptor that can be accessed using ``BINDESC_GET_STR(kernel_version_string)``. +Reading Descriptors +=================== +It's also possible to read and parse binary descriptors from an application. +This can be useful both for an image trying to read its own descriptors, and for +an image trying to read another image's descriptors. Reading can be performed through +one of three backends: + + #. RAM - assuming the descriptors have been copied to RAM (e.g. by a bootloader), they + can be read from the buffer they reside in. + + #. Memory mapped flash - If the flash where the image to be read resides in flash and is + accessible through the program's address space, it can be read directly from flash. + This option uses the least amount of RAM, but will not work if the flash is not memory mapped, + and is not recommended to read a bootloader's descriptors for security concerns. + + #. Flash - Using an internal buffer, the descriptors are read one by one using the flash API, + and given to the user while they're in the buffer. + +To enable reading descriptors, enable :kconfig:option:`CONFIG_BINDESC_READ`. The three backends are +enabled by these Kconfig symbols, respectively: :kconfig:option:`CONFIG_BINDESC_READ_RAM`, +:kconfig:option:`CONFIG_BINDESC_READ_MEMORY_MAPPED_FLASH`, and :kconfig:option:`CONFIG_BINDESC_READ_FLASH`. + +To read the descriptors, a handle to the descriptors should first be initialized: + +.. code-block:: c + + struct bindesc_handle handle; + + /* Assume buffer holds a copy of the descriptors */ + bindesc_open_ram(&handle, buffer); + +The ``bindesc_open_*`` functions are the only functions concerned with the backend used. +The rest of the API is agnostic to where the data is. After the handle has been initialized, +it can be used with the rest of the API: + +.. code-block:: c + + char *version; + bindesc_find_str(&handle, BINDESC_ID_KERNEL_VERSION_STRING, &version); + printk("Kernel version: %s\n", version); + west bindesc tool ================= ``west`` is able to parse and display binary descriptors from a given executable image. @@ -123,3 +164,5 @@ API Reference ************* .. doxygengroup:: bindesc_define + +.. doxygengroup:: bindesc_read