1 /*
2  * Copyright (c) 2022-2024 Libre Solar Technologies GmbH
3  * Copyright (c) 2022-2024 tado GmbH
4  *
5  * SPDX-License-Identifier: Apache-2.0
6  */
7 
8 #ifndef ZEPHYR_SUBSYS_LORAWAN_SERVICES_FRAG_FLASH_H_
9 #define ZEPHYR_SUBSYS_LORAWAN_SERVICES_FRAG_FLASH_H_
10 
11 #include <stdint.h>
12 
13 /**
14  * Initialize flash driver and prepare partition for new firmware image.
15  *
16  * This function mass-erases the flash partition and may take a while to return.
17  *
18  * @param frag_size Fragment size used for this session
19  *
20  * @returns 0 for success, otherwise negative error code
21  */
22 int frag_flash_init(uint32_t frag_size);
23 
24 /**
25  * Write received data fragment to flash.
26  *
27  * This function is called by FragDecoder from LoRaMAC-node stack.
28  *
29  * @param addr Flash address relative to start of slot
30  * @param data Data buffer
31  * @param size Number of bytes in the buffer
32  *
33  * @returns 0 for success, otherwise negative error code
34  */
35 int8_t frag_flash_write(uint32_t addr, uint8_t *data, uint32_t size);
36 
37 /**
38  * Read back data from flash.
39  *
40  * This function is called by FragDecoder from LoRaMAC-node stack.
41  *
42  * @param addr Flash address relative to start of slot
43  * @param data Data buffer
44  * @param size Number of bytes in the buffer
45  *
46  * @returns 0 for success, otherwise negative error code
47  */
48 int8_t frag_flash_read(uint32_t addr, uint8_t *data, uint32_t size);
49 
50 /**
51  * Start caching fragments in RAM.
52  *
53  * Coded/redundant fragments may be overwritten with future fragments,
54  * so we have to cache them in RAM instead of flash.
55  *
56  * This function must be called once all uncoded fragments have been received.
57  */
58 void frag_flash_use_cache(void);
59 
60 /**
61  * Finalize flashing after sufficient fragments have been received.
62  *
63  * This call will also write cached fragments to flash.
64  *
65  * After this call the new firmware is ready to be checked and booted.
66  */
67 void frag_flash_finish(void);
68 
69 #endif /* ZEPHYR_SUBSYS_LORAWAN_SERVICES_FRAG_FLASH_H_ */
70