Mistake on this page?
Report an issue in GitHub or email us
wiced_resource.h
Go to the documentation of this file.
1 /*
2  * Copyright 2021, 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_)
110 
111 /******************************************************
112 * Type Definitions
113 ******************************************************/
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 */
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 */
138 
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 */
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;
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 
resource_result_t resource_free_readonly_buffer(const resource_hnd_t *handle, const void *buffer)
Free a read only resource buffer using the handle specified.
resource location in memory
#define RESOURCE_RESULT_LIST(prefix)
Failed to read resource file.
Resource handle structure.
resource_result_t resource_read(const resource_hnd_t *resource, uint32_t offset, uint32_t maxsize, uint32_t *size, void *buffer)
Read resource using the handle specified.
resource_result_t
Result type for WICED Resource function.
resource location in external storage
resource location in filesystem
resource_location_t
resource_result_t resource_get_readonly_buffer(const resource_hnd_t *resource, uint32_t offset, uint32_t maxsize, uint32_t *size_out, const void **buffer)
Retrieve a read only resource buffer using the handle specified.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.