Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2017 Nordic Semiconductor ASA
       3             :  * Copyright (c) 2017 Linaro Limited
       4             :  *
       5             :  * SPDX-License-Identifier: Apache-2.0
       6             :  */
       7             : 
       8             : /**
       9             :  * @file
      10             :  * @brief Flash image header file
      11             :  *
      12             :  * This header file declares prototypes for the flash image APIs used for DFU.
      13             :  */
      14             : 
      15             : #ifndef ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_
      16             : #define ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_
      17             : 
      18             : #include <zephyr/storage/stream_flash.h>
      19             : 
      20             : /**
      21             :  * @brief Abstraction layer to write firmware images to flash
      22             :  *
      23             :  * @defgroup flash_img_api Flash image API
      24             :  * @ingroup os_services
      25             :  * @{
      26             :  */
      27             : 
      28             : #ifdef __cplusplus
      29             : extern "C" {
      30             : #endif
      31             : 
      32           0 : struct flash_img_context {
      33           0 :         uint8_t buf[CONFIG_IMG_BLOCK_BUF_SIZE];
      34           0 :         const struct flash_area *flash_area;
      35           0 :         struct stream_flash_ctx stream;
      36             : };
      37             : 
      38             : /**
      39             :  * @brief Structure for verify flash region integrity
      40             :  *
      41             :  * Match vector length is fixed and depends on size from hash algorithm used
      42             :  * to verify flash integrity.  The current available algorithm is SHA-256.
      43             :  */
      44           1 : struct flash_img_check {
      45           0 :         const uint8_t *match;           /** Match vector data */
      46           1 :         size_t clen;                    /** Content to be compared */
      47             : };
      48             : 
      49             : /**
      50             :  * @brief Initialize context needed for writing the image to the flash.
      51             :  *
      52             :  * @param ctx     context to be initialized
      53             :  * @param area_id flash area id of partition where the image should be written
      54             :  *
      55             :  * @return  0 on success, negative errno code on fail
      56             :  */
      57           1 : int flash_img_init_id(struct flash_img_context *ctx, uint8_t area_id);
      58             : 
      59             : /**
      60             :  * @brief Initialize context needed for writing the image to the flash.
      61             :  *
      62             :  * @param ctx context to be initialized
      63             :  *
      64             :  * @return  0 on success, negative errno code on fail
      65             :  */
      66           1 : int flash_img_init(struct flash_img_context *ctx);
      67             : 
      68             : /**
      69             :  * @brief Read number of bytes of the image written to the flash.
      70             :  *
      71             :  * @param ctx context
      72             :  *
      73             :  * @return Number of bytes written to the image flash.
      74             :  */
      75           1 : size_t flash_img_bytes_written(struct flash_img_context *ctx);
      76             : 
      77             : /**
      78             :  * @brief  Process input buffers to be written to the image slot 1. flash
      79             :  * memory in single blocks. Will store remainder between calls.
      80             :  *
      81             :  * A final call to this function with flush set to true
      82             :  * will write out the remaining block buffer to flash. Since flash is written to
      83             :  * in blocks, the contents of flash from the last byte written up to the next
      84             :  * multiple of CONFIG_IMG_BLOCK_BUF_SIZE is padded with 0xff.
      85             :  *
      86             :  * @param ctx context
      87             :  * @param data data to write
      88             :  * @param len Number of bytes to write
      89             :  * @param flush when true this forces any buffered
      90             :  * data to be written to flash
      91             :  *
      92             :  * @return  0 on success, negative errno code on fail
      93             :  */
      94           1 : int flash_img_buffered_write(struct flash_img_context *ctx, const uint8_t *data,
      95             :                     size_t len, bool flush);
      96             : 
      97             : /**
      98             :  * @brief  Verify flash memory length bytes integrity from a flash area. The
      99             :  * start point is indicated by an offset value.
     100             :  *
     101             :  * The function is enabled via CONFIG_IMG_ENABLE_IMAGE_CHECK Kconfig options.
     102             :  *
     103             :  * @param[in] ctx context.
     104             :  * @param[in] fic flash img check data.
     105             :  * @param[in] area_id flash area id of partition where the image should be
     106             :  * verified.
     107             :  *
     108             :  * @return  0 on success, negative errno code on fail
     109             :  */
     110           1 : int flash_img_check(struct flash_img_context *ctx,
     111             :                     const struct flash_img_check *fic,
     112             :                     uint8_t area_id);
     113             : 
     114             : #ifdef __cplusplus
     115             : }
     116             : #endif
     117             : 
     118             : /**
     119             :  * @}
     120             :  */
     121             : 
     122             : #endif  /* ZEPHYR_INCLUDE_DFU_FLASH_IMG_H_ */