b0: bl_validation: Add RST docs for bl_validation

Also fix doxygen text and tagging inside bl_validation.h

Signed-off-by: Øyvind Rønningstad <[email protected]>

Author: oyvindronningstad

include/bl_validation.h

@@ -7,32 +7,22 @@
 #ifndef BL_VALIDATION_H__
 #define BL_VALIDATION_H__
 
-/*
- * The FW package will consist of (firmware | (padding) | validation_info),
- * where the firmware contains the firmware_info at a predefined location. The
- * padding is present if the validation_info needs alignment. The
- * validation_info is not directly referenced from the firmware_info since the
- * validation_info doesn't actually have to be placed after the firmware.
- */
+#ifdef __cplusplus
+extern "C" {
+#endif
 
 #include <stdbool.h>
 #include <fw_info.h>
 
+/** @defgroup bl_validation Bootloader firmware validation
+ * @{
+ */
+
 /* EXT_API ID for the bl_validate_firmware EXT_API. */
 #define BL_VALIDATE_FW_EXT_API_ID 0x1101
 
-EXT_API_FUNCTION(bool, bl_validate_firmware, u32_t fw_dst_address,
-					u32_t fw_src_address);
-
-struct bl_validate_fw_ext_api {
-	struct fw_info_ext_api header;
-	struct {
-		bl_validate_firmware_t bl_validate_firmware;
-	} ext_api;
-};
-
 
-/** Function for validating firmware in place.
+/** Function for validating firmware.
  *
  * @details This will run a series of checks on the fw_info contents, then
  *          locate the validation info and check the signature of the image.
@@ -54,7 +44,30 @@ typedef
 bool (*bl_validate_firmware_t)(u32_t fw_dst_address, u32_t fw_src_address);
 
 
+/** Function for validating firmware in place.
+ *
+ * @note This function is only available to the bootloader.
+ *
+ * @details See @ref bl_validate_firmware for more details.
+ */
 bool bl_validate_firmware_local(u32_t fw_address,
 				const struct fw_info *fwinfo);
 
+
+/**
+ * @brief Structure describing the BL_VALIDATE_FW EXT_API.
+ */
+struct bl_validate_fw_ext_api {
+	struct fw_info_ext_api header;
+	struct {
+		bl_validate_firmware_t bl_validate_firmware;
+	} ext_api;
+};
+
+  /** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* BL_VALIDATION_H__ */

include/bl_validation.rst

@@ -0,0 +1,28 @@
+.. _doc_bl_validation:
+
+Bootloader firmware validation
+##############################
+
+The bootloader firmware validation library provides the function that the :ref:`bootloader` uses to validate a firmware image before booting it.
+
+The API is public because applications that are booted by the immutable bootloader can call the function from this library via the bootloader's code, through external APIs.
+See :ref:`doc_fw_info_ext_api` for more information.
+Using this mechanism can be useful when the application receives a DFU package and wants to determine whether it will be accepted by the bootloader.
+
+Validation
+**********
+
+The :cpp:func:`bl_validate_firmware` function validates the following information:
+
+* The digest and the signature of the whole image (see :cpp:func:`bl_root_of_trust_verify`)
+* The fields of the ``fw_info`` struct that is part of the firmware image (see :ref:`doc_fw_info`)
+
+API documentation
+*****************
+
+| Header file: :file:`include/bl_validation.h`
+| Source files: :file:`subsys/bootloader/bl_validation/`
+
+.. doxygengroup:: bl_validation
+   :project: nrf
+   :members: