doc: bindesc: Add documentation for bindesc read

Added documentation for reading binary descriptors.

Signed-off-by: Yonatan Schachter <[email protected]>

Author: yonsch

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