1 /* 2 * Copyright 2022, Cypress Semiconductor Corporation (an Infineon company) 3 * SPDX-License-Identifier: Apache-2.0 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** @file 19 * WICED Resource API's 20 * The Resource Management functions reads resource from a resource location 21 * and returns the number of bytes from an offset in an caller filled buffer. 22 * 23 * Functions to get the resource size and resource data 24 * 25 * The Resource could be one of the three locations 26 * 27 * - Wiced Filesystem (File System) 28 * - Internal Memory (Embedded Flash memory) 29 * - External Storage ( External Flash connected via SPI interface) 30 * 31 */ 32 33 #ifndef INCLUDED_RESOURCE_H_ 34 #define INCLUDED_RESOURCE_H_ 35 36 #include <stdint.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 /****************************************************** 44 * Macros 45 ******************************************************/ 46 #ifndef MIN 47 #define MIN(x, y) ( (x) < (y) ? (x) : (y) ) 48 #endif /* ifndef MIN */ 49 50 /* Suppress unused parameter warning */ 51 #ifndef UNUSED_PARAMETER 52 #define UNUSED_PARAMETER(x) ( (void)(x) ) 53 #endif 54 55 #ifndef RESULT_ENUM 56 #define RESULT_ENUM(prefix, name, value) prefix ## name = (value) 57 #endif /* ifndef RESULT_ENUM */ 58 59 #if defined(CY_SECTION) 60 #define CY_SECTION_WHD CY_SECTION 61 #else 62 #if !defined(CY_SECTION_WHD) 63 #if defined(__ARMCC_VERSION) 64 #define CY_SECTION_WHD(name) __attribute__ ( (section(name) ) ) 65 #elif defined (__GNUC__) 66 #if defined (__clang__) 67 #define CY_SECTION_WHD(name) __attribute__ ( (section("__DATA, "name) ) ) 68 #else 69 #define CY_SECTION_WHD(name) __attribute__ ( (section(name) ) ) 70 #endif 71 #elif defined (__ICCARM__) 72 #define CY_PRAGMA_WHD(x) _Pragma(#x) 73 #define CY_SECTION_WHD(name) CY_PRAGMA_WHD(location = name) 74 #else 75 #error "An unsupported toolchain" 76 #endif /* (__ARMCC_VERSION) */ 77 #endif /* !defined(CY_SECTION_WHD) */ 78 #endif /* defined(CY_SECTION) */ 79 80 /* These Enum result values are for Resource errors 81 * Values: 4000 - 4999 82 */ 83 #define RESOURCE_RESULT_LIST(prefix) \ 84 RESULT_ENUM(prefix, SUCCESS, 0), /**< Success */ \ 85 RESULT_ENUM(prefix, UNSUPPORTED, 7), /**< Unsupported function */ \ 86 RESULT_ENUM(prefix, OFFSET_TOO_BIG, 4001), /**< Offset past end of resource */ \ 87 RESULT_ENUM(prefix, FILE_OPEN_FAIL, 4002), /**< Failed to open resource file */ \ 88 RESULT_ENUM(prefix, FILE_SEEK_FAIL, 4003), /**< Failed to seek to requested offset in resource file */ \ 89 RESULT_ENUM(prefix, FILE_READ_FAIL, 4004), /**< Failed to read resource file */ 90 91 #define resource_get_size(resource) ( (resource)->size ) 92 93 /****************************************************** 94 * Constants 95 ******************************************************/ 96 97 #define RESOURCE_ENUM_OFFSET (1300) 98 99 /****************************************************** 100 * Enumerations 101 ******************************************************/ 102 103 /** 104 * Result type for WICED Resource function 105 */ 106 typedef enum 107 { 108 RESOURCE_RESULT_LIST(RESOURCE_) 109 } resource_result_t; 110 111 /****************************************************** 112 * Type Definitions 113 ******************************************************/ 114 115 typedef const void *resource_data_t; 116 typedef unsigned long resource_size_t; 117 118 /****************************************************** 119 * Structures 120 ******************************************************/ 121 122 /** 123 * Memory handle 124 */ 125 typedef struct 126 { 127 const char *data; /**< resource data */ 128 } memory_resource_handle_t; 129 130 /** 131 * Filesystem handle 132 */ 133 typedef struct 134 { 135 unsigned long offset; /**< Offset to the start of the resource */ 136 const char *filename; /**< name of the resource */ 137 } filesystem_resource_handle_t; 138 139 140 typedef enum 141 { 142 RESOURCE_IN_MEMORY, /**< resource location in memory */ 143 RESOURCE_IN_FILESYSTEM, /**< resource location in filesystem */ 144 RESOURCE_IN_EXTERNAL_STORAGE /**< resource location in external storage */ 145 } resource_location_t; 146 147 /** 148 * Resource handle structure 149 */ 150 typedef struct 151 { 152 resource_location_t location; /**< resource location */ 153 unsigned long size; /**< resource size */ 154 union 155 { 156 filesystem_resource_handle_t fs; /** < filesystem resource handle */ 157 memory_resource_handle_t mem; /** < memory resource handle */ 158 void *external_storage_context; /** < external storage context */ 159 } val; 160 } resource_hnd_t; 161 162 /****************************************************** 163 * Global Variables 164 ******************************************************/ 165 166 /****************************************************** 167 * Function Declarations 168 ******************************************************/ 169 170 /*****************************************************************************/ 171 /** @addtogroup resourceapi Wiced Resource Management API's 172 * @ingroup framework 173 * 174 * WCIED Resource Management API's has functions to get the 175 * resource size and reads resource data from a resource 176 * location and returns the number of bytes in an caller 177 * filled buffer 178 * 179 * The Resource could be one of the three locations 180 * 181 * - Wiced Filesystem ( File System) 182 * - Internal Memory (Embedded Flash memory) 183 * - External Storage ( External Flash connected via SPI interface ) 184 * 185 * @{ 186 */ 187 /*****************************************************************************/ 188 189 /** Read resource using the handle specified 190 * 191 * @param[in] resource : handle of the resource to read 192 * @param[in] offset : offset from the beginning of the resource block 193 * @param[in] maxsize : size of the buffer 194 * @param[out] size : size of the data successfully read 195 * @param[in] buffer : pointer to a buffer to contain the read data 196 * 197 * @return @ref resource_result_t 198 */ 199 extern resource_result_t resource_read(const resource_hnd_t *resource, uint32_t offset, uint32_t maxsize, 200 uint32_t *size, void *buffer); 201 202 /** Retrieve a read only resource buffer using the handle specified 203 * 204 * @param[in] resource : handle of the resource to read 205 * @param[in] offset : offset from the beginning of the resource block 206 * @param[in] maxsize : size of the buffer 207 * @param[out] size : size of the data successfully read 208 * @param[out] buffer : pointer to a buffer pointer to point to the resource data 209 * 210 * @return @ref resource_result_t 211 */ 212 extern resource_result_t resource_get_readonly_buffer(const resource_hnd_t *resource, uint32_t offset, uint32_t maxsize, 213 uint32_t *size_out, const void **buffer); 214 215 /** Free a read only resource buffer using the handle specified 216 * 217 * @param[in] resource : handle of the resource to read 218 * @param[in] buffer : pointer to a buffer set using resource_get_readonly_buffer 219 * 220 * @return @ref resource_result_t 221 */ 222 extern resource_result_t resource_free_readonly_buffer(const resource_hnd_t *handle, const void *buffer); 223 /* @} */ 224 #ifdef __cplusplus 225 } /*extern "C" */ 226 #endif 227 228 #endif /* ifndef INCLUDED_RESOURCE_H_ */ 229
