Keil Studio Cloud
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 2020 Cypress Semiconductor Corporation
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_SECTION_WHD(name) CY_PRAGMA(location = name)
73 #else
74 #error "An unsupported toolchain"
75 #endif /* (__ARMCC_VERSION) */
76 #endif /* !defined(CY_SECTION_WHD) */
77 #endif /* defined(CY_SECTION) */
78 
79 /* These Enum result values are for Resource errors
80  * Values: 4000 - 4999
81  */
82 #define RESOURCE_RESULT_LIST(prefix) \
83  RESULT_ENUM(prefix, SUCCESS, 0), /**< Success */ \
84  RESULT_ENUM(prefix, UNSUPPORTED, 7), /**< Unsupported function */ \
85  RESULT_ENUM(prefix, OFFSET_TOO_BIG, 4001), /**< Offset past end of resource */ \
86  RESULT_ENUM(prefix, FILE_OPEN_FAIL, 4002), /**< Failed to open resource file */ \
87  RESULT_ENUM(prefix, FILE_SEEK_FAIL, 4003), /**< Failed to seek to requested offset in resource file */ \
88  RESULT_ENUM(prefix, FILE_READ_FAIL, 4004), /**< Failed to read resource file */
89 
90 #define resource_get_size(resource) ( (resource)->size )
91 
92 /******************************************************
93 * Constants
94 ******************************************************/
95 
96 #define RESOURCE_ENUM_OFFSET (1300)
97 
98 /******************************************************
99 * Enumerations
100 ******************************************************/
101 
102 /**
103  * Result type for WICED Resource function
104  */
105 typedef enum
106 {
107  RESOURCE_RESULT_LIST(RESOURCE_)
108 } resource_result_t;
109 
110 /******************************************************
111 * Type Definitions
112 ******************************************************/
113 
114 typedef const void *resource_data_t;
115 typedef unsigned long resource_size_t;
116 
117 /******************************************************
118 * Structures
119 ******************************************************/
120 
121 /**
122  * Memory handle
123  */
124 typedef struct
125 {
126  const char *data; /**< resource data */
127 } memory_resource_handle_t;
128 
129 /**
130  * Filesystem handle
131  */
132 typedef struct
133 {
134  unsigned long offset; /**< Offset to the start of the resource */
135  const char *filename; /**< name of the resource */
136 } filesystem_resource_handle_t;
137 
138 
139 typedef enum
140 {
141  RESOURCE_IN_MEMORY, /**< resource location in memory */
142  RESOURCE_IN_FILESYSTEM, /**< resource location in filesystem */
143  RESOURCE_IN_EXTERNAL_STORAGE /**< resource location in external storage */
144 } resource_location_t;
145 
146 /**
147  * Resource handle structure
148  */
149 typedef struct
150 {
151  resource_location_t location; /**< resource location */
152  unsigned long size; /**< resource size */
153  union
154  {
155  filesystem_resource_handle_t fs; /** < filesystem resource handle */
156  memory_resource_handle_t mem; /** < memory resource handle */
157  void *external_storage_context; /** < external storage context */
158  } val;
159 } resource_hnd_t;
160 
161 /******************************************************
162 * Global Variables
163 ******************************************************/
164 
165 /******************************************************
166 * Function Declarations
167 ******************************************************/
168 
169 /*****************************************************************************/
170 /** @addtogroup resourceapi Wiced Resource Management API's
171  * @ingroup framework
172  *
173  * WCIED Resource Management API's has functions to get the
174  * resource size and reads resource data from a resource
175  * location and returns the number of bytes in an caller
176  * filled buffer
177  *
178  * The Resource could be one of the three locations
179  *
180  * - Wiced Filesystem ( File System)
181  * - Internal Memory (Embedded Flash memory)
182  * - External Storage ( External Flash connected via SPI interface )
183  *
184  * @{
185  */
186 /*****************************************************************************/
187 
188 /** Read resource using the handle specified
189  *
190  * @param[in] resource : handle of the resource to read
191  * @param[in] offset : offset from the beginning of the resource block
192  * @param[in] maxsize : size of the buffer
193  * @param[out] size : size of the data successfully read
194  * @param[in] buffer : pointer to a buffer to contain the read data
195  *
196  * @return @ref resource_result_t
197  */
198 extern resource_result_t resource_read(const resource_hnd_t *resource, uint32_t offset, uint32_t maxsize,
199  uint32_t *size, void *buffer);
200 
201 /** Retrieve a read only resource buffer using the handle specified
202  *
203  * @param[in] resource : handle of the resource to read
204  * @param[in] offset : offset from the beginning of the resource block
205  * @param[in] maxsize : size of the buffer
206  * @param[out] size : size of the data successfully read
207  * @param[out] buffer : pointer to a buffer pointer to point to the resource data
208  *
209  * @return @ref resource_result_t
210  */
211 extern resource_result_t resource_get_readonly_buffer(const resource_hnd_t *resource, uint32_t offset, uint32_t maxsize,
212  uint32_t *size_out, const void **buffer);
213 
214 /** Free a read only resource buffer using the handle specified
215  *
216  * @param[in] resource : handle of the resource to read
217  * @param[in] buffer : pointer to a buffer set using resource_get_readonly_buffer
218  *
219  * @return @ref resource_result_t
220  */
221 extern resource_result_t resource_free_readonly_buffer(const resource_hnd_t *handle, const void *buffer);
222 /* @} */
223 #ifdef __cplusplus
224 } /*extern "C" */
225 #endif
226 
227 #endif /* ifndef INCLUDED_RESOURCE_H_ */
228 
memory_resource_handle_t
Memory handle.
Definition: wiced_resource.h:130
resource_free_readonly_buffer
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_IN_MEMORY
resource location in memory
Definition: wiced_resource.h:147
RESOURCE_RESULT_LIST
#define RESOURCE_RESULT_LIST(prefix)
Failed to read resource file.
Definition: wiced_resource.h:82
resource_hnd_t
Resource handle structure.
Definition: wiced_resource.h:155
resource_read
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
resource_result_t
Result type for WICED Resource function.
Definition: wiced_resource.h:111
RESOURCE_IN_EXTERNAL_STORAGE
resource location in external storage
Definition: wiced_resource.h:149
filesystem_resource_handle_t
Filesystem handle.
Definition: wiced_resource.h:138
RESOURCE_IN_FILESYSTEM
resource location in filesystem
Definition: wiced_resource.h:148
resource_location_t
resource_location_t
Definition: wiced_resource.h:145
resource_get_readonly_buffer
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.