1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup OSAL 11 * @{ 12 * 13 * @brief Defines the structures and interfaces for the Operating System Abstraction Layer (OSAL) module. 14 * 15 * The OSAL module OpenHarmony OS interface differences and provides unified OS interfaces externally, 16 * including the memory management, thread, mutex, spinlock, semaphore, timer, file, interrupt, time, 17 * atomic, firmware, and I/O operation modules. 18 * 19 * @since 1.0 20 * @version 1.0 21 */ 22 23 /** 24 * @file osal_firmware.h 25 * 26 * @brief Declares firmware structures and interfaces. 27 * 28 * This file provides operations such as requesting and reading a firmware file, setting the offset for reading 29 * a firmware file, and releasing a firmware file. The firmware file can be read in split mode. 30 * The size of the firmware block to read each time is defined by the macro {@link HDF_FW_BLOCK_SIZE}. 31 * The firmware file is requested by calling {@link OsalRequestFirmware}, the firmware block is read from 32 * the firmware file by calling {@link OsalReadFirmware}, and the firmware block can also be randomly read 33 * at a specified position by calling {@link OsalSeekFirmware}. 34 * 35 * @since 1.0 36 * @version 1.0 37 */ 38 39 #ifndef OSAL_FIRMWARE_H 40 #define OSAL_FIRMWARE_H 41 42 #include "hdf_base.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif /* __cplusplus */ 47 48 /** 49 * @brief Defines the data structure for operating a firmware file. 50 */ 51 struct OsalFirmware { 52 uint32_t fwSize; /**< Firmware file size, which is returned by calling {@link OsalRequestFirmware}. */ 53 void *para; /**< Pointer to a firmware file, which is returned by calling {@link OsalRequestFirmware}. 54 * You do not need to allocate space. 55 */ 56 }; 57 58 /** 59 * @brief Defines the data structure for reading a firmware file. 60 * 61 * This structure declares the firmware block to read each time. The firmware file can be read in split mode. 62 */ 63 struct OsalFwBlock { 64 uint8_t *data; /**< Firmware content read this time. You do not need to allocate space. */ 65 bool endFlag; /**< Whether the firmware file is read completely */ 66 uint32_t dataSize; /**< Firmware block size read this time */ 67 int32_t curOffset; /**< Offset in the firmware file */ 68 }; 69 70 /** 71 * @brief Requests a firmware file based on its name and device information. 72 * 73 * @param fw Indicates the pointer to the firmware file {@link OsalFirmware}, which cannot be empty. 74 * @param fwName Indicates the pointer to the firmware file name, which cannot be empty. 75 * @param device Indicates the pointer to the information about the device that requests the firmware file. 76 * 77 * @return Returns a value listed below: \n 78 * HDF_STATUS | Description 79 * ----------------------| ----------------------- 80 * HDF_SUCCESS | The operation is successful. 81 * HDF_FAILURE | Failed to invoke the system function. 82 * HDF_ERR_INVALID_PARAM | Invalid parameter. 83 * HDF_ERR_MALLOC_FAIL | Memory allocation fails. 84 * 85 * @since 1.0 86 * @version 1.0 87 */ 88 int32_t OsalRequestFirmware(struct OsalFirmware *fw, const char *fwName, void *device); 89 90 /** 91 * @brief Sets the offset for reading a firmware file to implement random access to the firmware file. 92 * 93 * @param fw Indicates the pointer to the firmware file {@link OsalFirmware}. 94 * @param offset Indicates the offset where the firmware content is to read. 95 * 96 * @return Returns a value listed below: \n 97 * HDF_STATUS | Description 98 * ----------------------| ----------------------- 99 * HDF_SUCCESS | The operation is successful. 100 * HDF_ERR_INVALID_PARAM | Invalid parameter. 101 * 102 * @since 1.0 103 * @version 1.0 104 */ 105 int32_t OsalSeekFirmware(struct OsalFirmware *fw, uint32_t offset); 106 107 /** 108 * @brief Reads a firmware file. 109 * 110 * @param fw Indicates the pointer to the firmware file {@link OsalFirmware}. 111 * @param block Indicates the pointer to the firmware block to read. For details, see {@link OsalFwBlock}. 112 * 113 * @return Returns a value listed below: \n 114 * HDF_STATUS | Description 115 * ----------------------| ----------------------- 116 * HDF_SUCCESS | The operation is successful. 117 * HDF_FAILURE | Failed to invoke the system function. 118 * HDF_ERR_INVALID_PARAM | Invalid parameter. 119 * 120 * @since 1.0 121 * @version 1.0 122 */ 123 int32_t OsalReadFirmware(struct OsalFirmware *fw, struct OsalFwBlock *block); 124 125 /** 126 * @brief Releases a firmware file. 127 * 128 * After the firmware file is read, this function is called to release the firmware file. 129 * 130 * @param fw Indicates the pointer to the firmware file {@link OsalFirmware}. 131 * 132 * @return Returns a value listed below: \n 133 * HDF_STATUS | Description 134 * ----------------------| ----------------------- 135 * HDF_SUCCESS | The operation is successful. 136 * HDF_FAILURE | Failed to invoke the system function. 137 * HDF_ERR_INVALID_PARAM | Invalid parameter. 138 * 139 * @since 1.0 140 * @version 1.0 141 */ 142 int32_t OsalReleaseFirmware(struct OsalFirmware *fw); 143 144 #ifdef __cplusplus 145 } 146 #endif /* __cplusplus */ 147 148 #endif /* OSAL_FIRMWARE_H */ 149 /** @} */ 150