1 // Copyright 2015-2020 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 /** 16 * @file 17 * @brief Core dump checksum interface. 18 * 19 * This file contains all the functions required by the core dump component to 20 * calculate checksums for data to write (or already written) on the flash. 21 * Currently, both CRC32 and SHA256 are supported, but this interface is 22 * implementation independent. 23 */ 24 25 #ifndef CORE_DUMP_CHECKSUM_H_ 26 #define CORE_DUMP_CHECKSUM_H_ 27 28 #include <stdint.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /** 35 * @brief Maximum possible length for a checksum (regardless of the 36 * implentation). This can be modified in the future if a new implementation 37 * requires a larger size. 38 */ 39 #define COREDUMP_CHECKSUM_MAX_LEN 32 40 41 /** 42 * @brief Type describing a checksum context. It is an abstract type as it is 43 * implementation independent, it is defined in the C source counterpart. 44 */ 45 typedef struct core_dump_checksum_ctx core_dump_checksum_ctx; 46 47 /** 48 * @brief Type returned by `esp_core_dump_checksum_finish()`. It describes a 49 * checksum as an array of bytes. It can also be provided to `esp_core_dump_print_checksum()`. 50 */ 51 typedef uint8_t* core_dump_checksum_bytes; 52 53 54 /** 55 * @brief Get ELF core dump version. 56 * 57 * @note Currently, this is used in the core dump header to recognize the 58 * checksum used for a certain dump, as the version varies with the checksum. 59 * 60 * @return Version of the core dump used. 61 */ 62 uint32_t esp_core_dump_elf_version(void); 63 64 /** 65 * @brief Initialize checksum calculation for the given context. 66 * 67 * @param wr_data Core dump checksum context to fill. 68 */ 69 void esp_core_dump_checksum_init(core_dump_checksum_ctx** wr_data); 70 71 /** 72 * @brief Update checksum calculation by integrating the given data in the context. 73 * 74 * @param wr_data Core dump checksum context. 75 * @param data Pointer to the data to integrate in the checksum calculation. 76 * This is usually the new data to write (or already written) on 77 * the flash. 78 */ 79 void esp_core_dump_checksum_update(core_dump_checksum_ctx* wr_data, void* data, size_t data_len); 80 81 /** 82 * @brief Terminate and return checksum calculated for the given context. 83 * 84 * @param wr_data Core dump checksum context. It can be NULL only if chs_ptr is 85 * also NULL. 86 * @param chs_ptr Pointer used to return the checksum calculated. It can be 87 * NULL, in this case, it will be ignored but the correct size 88 * of the checksum will be returned. 89 * 90 * @return The size, in bytes, of the checksum. 91 */ 92 uint32_t esp_core_dump_checksum_finish(core_dump_checksum_ctx* wr_data, core_dump_checksum_bytes* chs_ptr); 93 94 /** 95 * @brief Return the size of the checksums. 96 * 97 * @note This is equivalent to `esp_core_dump_checksum_finish(NULL, NULL)`. 98 * 99 * @return The size, in bytes, of the checksums. 100 */ 101 uint32_t esp_core_dump_checksum_size(void); 102 103 /** 104 * @brief Print a message followed by the checksum given as a parameter. 105 * 106 * @note The checksum will be printed in hex format and followed by \r\n. 107 * 108 * @param msg Message to print before the checksum. Can be NULL. 109 * @param checksum Checksum to print. Must not be NULL. 110 */ 111 void esp_core_dump_print_checksum(const char* msg, core_dump_checksum_bytes checksum); 112 113 #ifdef __cplusplus 114 } 115 #endif 116 117 #endif 118
