Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
wsf_efs.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file wsf_efs.h
4  *
5  * \brief Embedded File System service.
6  *
7  * Copyright (c) 2014-2018 Arm Ltd. All Rights Reserved.
8  *
9  * Copyright (c) 2019-2020 Packetcraft, Inc.
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 /*************************************************************************************************/
24 
25 #ifndef WSF_EFS_H
26 #define WSF_EFS_H
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /*! \addtogroup WSF_EFS_API
33  * \{ */
34 
35 /**************************************************************************************************
36  Macros
37 **************************************************************************************************/
38 
39 /*! \brief Max Number of Files and Media */
40 #ifndef WSF_EFS_MAX_FILES
41 #define WSF_EFS_MAX_FILES 6
42 #endif
43 
44 /*! \brief Max Number of Media */
45 #ifndef WSF_EFS_MAX_MEDIA
46 #define WSF_EFS_MAX_MEDIA 4
47 #endif
48 
49 /** \name Status Codes
50  *
51  */
52 /**@{*/
53 #define WSF_EFS_SUCCESS 0 /*!< \brief Success */
54 #define WSF_EFS_FAILURE 1 /*!< \brief Failure */
55 #define WSF_EFS_GET_FAILED 0xFFFF /*!< \brief Get operation failure */
56 #define WSF_EFS_PUT_FAILED 0xFFFF /*!< \brief PUT operation failure */
57 /**@}*/
58 
59 
60 /** \name Invalid Parameter Identifiers
61  *
62  */
63 /**@{*/
64 #define WSF_EFS_INVALID_HANDLE 0xFFFF /*!< \brief Invalid Handle */
65 #define WSF_EFS_INVALID_OFFSET 0xFFFFFFFF /*!< \brief Invalid Offset */
66 #define WSF_EFS_INVALID_SIZE 0xFFFFFFFF /*!< \brief Invalid Size */
67 #define WSF_EFS_INVALID_MEDIA 0xFF /*!< \brief Invalid Media */
68 /**@}*/
69 
70 /** \name File Types
71  *
72  */
73 /**@{*/
74 #define WSF_EFS_FILE_TYPE_BULK 0 /*!< \brief Bulk File Type */
75 #define WSF_EFS_FILE_TYPE_STREAM 1 /*!< \brief Stream File Type */
76 /**@}*/
77 
78 /*! \brief Offset to WsfEfsAddFile indicating any file offset can be used */
79 #define WSF_EFS_FILE_OFFSET_ANY 0xFFFFFFFF
80 
81 /** \name File Permissions
82  *
83  */
84 /**@{*/
85 #define WSF_EFS_REMOTE_PERMISSIONS_MASK 0xFF /*!< \brief Remote Permissions */
86 #define WSF_EFS_REMOTE_GET_PERMITTED 0x01 /*!< \brief Remote Get Permitted */
87 #define WSF_EFS_REMOTE_PUT_PERMITTED 0x02 /*!< \brief Remote Put Permitted */
88 #define WSF_EFS_REMOTE_ERASE_PERMITTED 0x04 /*!< \brief Remote Erase Permitted */
89 #define WSF_EFS_REMOTE_VERIFY_PERMITTED 0x08 /*!< \brief Remote Verify Permitted */
90 #define WSF_EFS_LOCAL_GET_PERMITTED 0x0100 /*!< \brief Local Get Permitted */
91 #define WSF_EFS_LOCAL_PUT_PERMITTED 0x0200 /*!< \brief Local Put Permitted */
92 #define WSF_EFS_LOCAL_ERASE_PERMITTED 0x0400 /*!< \brief Local Erase Permitted */
93 #define WSF_EFS_REMOTE_VISIBLE 0x0800 /*!< \brief File Visible via Remote WDXS */
94 /**@}*/
95 
96 /*! \brief File name length in bytes */
97 #define WSF_EFS_NAME_LEN 16
98 
99 /*! \brief File version length in bytes */
100 #define WSF_EFS_VERSION_LEN 16
101 
102 /** \name Standard Media Specific Command Identifiers
103  *
104  */
105 /**@{*/
106 #define WSF_EFS_WDXS_PUT_COMPLETE_CMD 0x00 /*!< \brief Put Complete */
107 #define WSF_EFS_VALIDATE_CMD 0x01 /*!< \brief Validate Req for the file */
108 /**@}*/
109 
110 /*! \brief Media Specific Command Identifiers reserved for applications begin at 0x80 */
111 #define WSF_EFS_USER_CMD 0x80
112 
113 /**************************************************************************************************
114  Data Types
115 **************************************************************************************************/
116 
117 /*! \brief File handle data type */
118 typedef uint16_t wsfEfsHandle_t;
119 
120 /*! \brief File attributes data type */
121 typedef struct
122 {
123  char name[WSF_EFS_NAME_LEN]; /*!< \brief File name string. */
124  char version[WSF_EFS_VERSION_LEN]; /*!< \brief File version string. */
125  uint16_t permissions; /*!< \brief File permissions. */
126  uint8_t type; /*!< \brief File type. */
127 } wsfEsfAttributes_t;
128 
129 /*! \brief File control block data type */
130 typedef struct
131 {
132  uint32_t maxSize; /*!< \brief File maximum size. */
133  uint32_t address; /*!< \brief File storage address. */
134  uint8_t media; /*!< \brief File media. */
135  uint32_t size; /*!< \brief File size. */
136  wsfEsfAttributes_t attributes; /*!< \brief File attributes. */
137 } wsfEfsControl_t;
138 
139 /*! \brief File Listing Information */
140 typedef struct
141 {
142  wsfEfsHandle_t handle; /*!< \brief File handle. */
143  uint32_t size; /*!< \brief File size. */
144  wsfEsfAttributes_t attributes; /*!< \brief File attributes. */
145 } wsfEfsFileInfo_t;
146 
147 /*************************************************************************************************/
148 /*!
149  * \brief Media Init function, called when media is registered.
150  *
151  * \return Status of the operation.
152  */
153 /*************************************************************************************************/
154 typedef uint8_t wsfMediaInitFunc_t(void);
155 
156 /*************************************************************************************************/
157 /*!
158  * \brief Media Erase function.
159  *
160  * \param pAddress Address in media to start erasing.
161  * \param size Number of bytes to erase.
162  *
163  * \return Status of the operation.
164  */
165 /*************************************************************************************************/
166 typedef uint8_t wsfMediaEraseFunc_t(uint8_t *pAddress, uint32_t size);
167 
168 /*************************************************************************************************/
169 /*!
170  * \brief Media Read function.
171  *
172  * \param pBuf Buffer to hold data.
173  * \param pAddress Address in media to read from.
174  * \param size Size of pBuf in bytes.
175  *
176  * \return Status of the operation.
177  */
178 /*************************************************************************************************/
179 typedef uint8_t wsfMediaReadFunc_t(uint8_t *pBuf, uint8_t *pAddress, uint32_t size);
180 
181 /*************************************************************************************************/
182 /*!
183  * \brief Media Write function.
184  *
185  * \param pBuf Buffer with data to be written.
186  * \param pAddress Address in media to write to.
187  * \param size Size of pBuf in bytes.
188  *
189  * \return Status of the operation.
190  */
191 /*************************************************************************************************/
192 typedef uint8_t wsfMediaWriteFunc_t(const uint8_t *pBuf, uint8_t *pAddress, uint32_t size);
193 
194 /*************************************************************************************************/
195 /*!
196  * \brief Media Specific Command handler.
197  *
198  * \param cmd Identifier of the media specific command.
199  * \param param Optional Parameter to the command.
200  *
201  * \return Status of the operation.
202  */
203 /*************************************************************************************************/
204 typedef uint8_t wsfMediaHandleCmdFunc_t(uint8_t cmd, uint32_t param);
205 
206 /*! \brief Media Control data type */
207 typedef struct
208 {
209  uint32_t startAddress; /*!< \brief Start address. */
210  uint32_t endAddress; /*!< \brief End address. */
211  uint32_t pageSize; /*!< \brief Page size. */
212  wsfMediaInitFunc_t *init; /*!< \brief Media intialization callback. */
213  wsfMediaEraseFunc_t *erase; /*!< \brief Media erase callback. */
214  wsfMediaReadFunc_t *read; /*!< \brief Media read callback. */
215  wsfMediaWriteFunc_t *write; /*!< \brief Media write callback. */
216  wsfMediaHandleCmdFunc_t *handleCmd; /*!< \brief Media command handler callback. */
217 } wsfEfsMedia_t;
218 
219 /*! \brief Pointer to Media Control data type */
220 typedef const wsfEfsMedia_t *pWsfEfsMedia_t;
221 
222 /**************************************************************************************************
223  Function Declarations
224 **************************************************************************************************/
225 
226 /*************************************************************************************************/
227 /*!
228  * \brief Initialise the embedded file system.
229  *
230  * \return none.
231  */
232 /*************************************************************************************************/
233 void WsfEfsInit(void);
234 
235 /*************************************************************************************************/
236 /*!
237  * \brief Create a file in the embedded file system.
238  *
239  * \param maxSize Max length in bytes of of the file.
240  * \param media Identifier of the media where the file is stored.
241  * \param pAttr Attributes of the file
242  * \param offset Offset address of the file in the memory space.
243  *
244  * \return File Handle, or WSF_EFS_INVALID_HANDLE.
245  */
246 /*************************************************************************************************/
247 wsfEfsHandle_t WsfEfsAddFile(uint32_t maxSize, uint8_t media, wsfEsfAttributes_t *pAttr, uint32_t offset);
248 
249 /*************************************************************************************************/
250 /*!
251  * \brief Deletes a file in the embedded file system.
252  *
253  * \param handle Handle identifying the file.
254  *
255  * \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
256  */
257 /*************************************************************************************************/
258 uint8_t WsfEfsRemoveFile(wsfEfsHandle_t handle);
259 
260 /*************************************************************************************************/
261 /*!
262  * \brief Clears the contents of a file without deleting the file.
263  *
264  * \param handle Handle identifying the file.
265  *
266  * \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
267  */
268 /*************************************************************************************************/
269 uint8_t WsfEfsErase(wsfEfsHandle_t handle);
270 
271 /*************************************************************************************************/
272 /*!
273  * \brief Gets the attributes of a file.
274  *
275  * \param handle Handle identifying the file.
276  * \param pAttr Pointer to memory to store the attributes.
277  *
278  * \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
279  */
280 /*************************************************************************************************/
281 uint8_t WsfEfsGetAttributes(wsfEfsHandle_t handle, wsfEsfAttributes_t *pAttr);
282 
283 /*************************************************************************************************/
284 /*!
285  * \brief Updates the attributes of a file.
286  *
287  * \param handle Handle identifying the file.
288  * \param pInfo Pointer to memory to with the updated attributes.
289  *
290  * \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
291  */
292 /*************************************************************************************************/
293 uint8_t WsfEfsSetAttributes(wsfEfsHandle_t handle, wsfEsfAttributes_t *pInfo);
294 
295 /*************************************************************************************************/
296 /*!
297  * \brief Copies data from a file.
298  *
299  * \param handle Handle identifying the file.
300  * \param offset Offset into the file to begin copying from.
301  * \param pBuffer Location to copy the data to.
302  * \param len Number of bytes to copy into pBuffer.
303  *
304  * \return The number of bytes read from the file
305  */
306 /*************************************************************************************************/
307 uint16_t WsfEfsGet(wsfEfsHandle_t handle, uint32_t offset, uint8_t *pBuffer, uint16_t len);
308 
309 /*************************************************************************************************/
310 /*!
311  * \brief Writes data to a file.
312  *
313  * \param handle Handle identifying the file.
314  * \param offset Offset into the file to begin writing to.
315  * \param pBuffer Data to write to the file.
316  * \param len Number of bytes to write to the file.
317  *
318  * \return The number of bytes written to the file
319  */
320 /*************************************************************************************************/
321 uint16_t WsfEfsPut(wsfEfsHandle_t handle, uint32_t offset, const uint8_t *pBuffer, uint16_t len);
322 
323 /*************************************************************************************************/
324 /*!
325  * \brief Registers a File Storage Medium with the Embedded File System.
326  *
327  * \param pMediaCtrl Pointer to the media control structure.
328  * \param mediaID User specified identifier of the media.
329  *
330  * \return WSF_EFS_SUCCESS or WSF_EFS_FAILURE.
331  */
332 /*************************************************************************************************/
333 uint8_t WsfEfsRegisterMedia(const wsfEfsMedia_t *pMediaCtrl, uint8_t mediaID);
334 
335 /*************************************************************************************************/
336 /*!
337  * \brief Returns the file control block for the given handle.
338  *
339  * \param handle Handle of the file
340  *
341  * \return File control block, or NULL.
342  */
343 /*************************************************************************************************/
344 wsfEfsControl_t *WsfEfsGetFileByHandle(wsfEfsHandle_t handle);
345 
346 /*************************************************************************************************/
347 /*!
348  * \brief Get the name of a file.
349  *
350  * \param handle File Handle.
351  *
352  * \return Filename string of a file.
353  */
354 /*************************************************************************************************/
355 char *WsfEfsGetFileName(wsfEfsHandle_t handle);
356 
357 /*************************************************************************************************/
358 /*!
359  * \brief Get the version of a file.
360  *
361  * \param handle File Handle.
362  *
363  * \return Version string of a file.
364  */
365 /*************************************************************************************************/
366 char *WsfEfsGetFileVersion(wsfEfsHandle_t handle);
367 
368 /*************************************************************************************************/
369 /*!
370  * \brief Get the size of a file.
371  *
372  * \param handle File Handle.
373  *
374  * \return Size of the file.
375  */
376 /*************************************************************************************************/
377 uint32_t WsfEfsGetFileSize(wsfEfsHandle_t handle);
378 
379 /*************************************************************************************************/
380 /*!
381  * \brief Get the number of bytes of memory reserved for use by a file.
382  *
383  * \param handle File Handle.
384  *
385  * \return Max size of the file.
386  */
387 /*************************************************************************************************/
388 uint32_t WsfEfsGetFileMaxSize(wsfEfsHandle_t handle);
389 
390 /*************************************************************************************************/
391 /*!
392  * \brief Get the type of a file.
393  *
394  * \param handle File Handle.
395  *
396  * \return Type of file (bulk or stream).
397  */
398 /*************************************************************************************************/
399 uint8_t WsfEfsGetFileType(wsfEfsHandle_t handle);
400 
401 /*************************************************************************************************/
402 /*!
403  * \brief Get the permissions of a file.
404  *
405  * \param handle File Handle.
406  *
407  * \return Permissions of the file.
408  */
409 /*************************************************************************************************/
410 uint16_t WsfEfsGetFilePermissions(wsfEfsHandle_t handle);
411 
412 /*************************************************************************************************/
413 /*!
414  * \brief Execute a media specific command on a file.
415  *
416  * \param handle File Handle.
417  * \param cmd Media specific command identifier.
418  * \param param Command specific parameter.
419  *
420  * \return Status of the operation.
421  */
422 /*************************************************************************************************/
423 uint8_t WsfEfsMediaSpecificCommand(wsfEfsHandle_t handle, uint8_t cmd, uint32_t param);
424 
425 /*! \} */ /* WSF_EFS_API */
426 
427 #ifdef __cplusplus
428 }
429 #endif
430 
431 #endif /* WSF_EFS_H */
wsfMediaEraseFunc_t
uint8_t wsfMediaEraseFunc_t(uint8_t *pAddress, uint32_t size)
Media Erase function.
Definition: wsf_efs.h:166
WsfEfsErase
uint8_t WsfEfsErase(wsfEfsHandle_t handle)
Clears the contents of a file without deleting the file.
wsfEfsMedia_t::read
wsfMediaReadFunc_t * read
Media read callback.
Definition: wsf_efs.h:214
wsfEfsHandle_t
uint16_t wsfEfsHandle_t
File handle data type.
Definition: wsf_efs.h:118
wsfEfsMedia_t::erase
wsfMediaEraseFunc_t * erase
Media erase callback.
Definition: wsf_efs.h:213
WsfEfsMediaSpecificCommand
uint8_t WsfEfsMediaSpecificCommand(wsfEfsHandle_t handle, uint8_t cmd, uint32_t param)
Execute a media specific command on a file.
wsfEsfAttributes_t::permissions
uint16_t permissions
File permissions.
Definition: wsf_efs.h:125
wsfEfsMedia_t::startAddress
uint32_t startAddress
Start address.
Definition: wsf_efs.h:209
WsfEfsPut
uint16_t WsfEfsPut(wsfEfsHandle_t handle, uint32_t offset, const uint8_t *pBuffer, uint16_t len)
Writes data to a file.
wsfEfsMedia_t::handleCmd
wsfMediaHandleCmdFunc_t * handleCmd
Media command handler callback.
Definition: wsf_efs.h:216
wsfEfsMedia_t::write
wsfMediaWriteFunc_t * write
Media write callback.
Definition: wsf_efs.h:215
wsfEfsFileInfo_t::attributes
wsfEsfAttributes_t attributes
File attributes.
Definition: wsf_efs.h:144
wsfEfsFileInfo_t
File Listing Information.
Definition: wsf_efs.h:140
wsfMediaWriteFunc_t
uint8_t wsfMediaWriteFunc_t(const uint8_t *pBuf, uint8_t *pAddress, uint32_t size)
Media Write function.
Definition: wsf_efs.h:192
WsfEfsGetFileVersion
char * WsfEfsGetFileVersion(wsfEfsHandle_t handle)
Get the version of a file.
wsfEsfAttributes_t::type
uint8_t type
File type.
Definition: wsf_efs.h:126
WsfEfsAddFile
wsfEfsHandle_t WsfEfsAddFile(uint32_t maxSize, uint8_t media, wsfEsfAttributes_t *pAttr, uint32_t offset)
Create a file in the embedded file system.
wsfMediaInitFunc_t
uint8_t wsfMediaInitFunc_t(void)
Media Init function, called when media is registered.
Definition: wsf_efs.h:154
WsfEfsGetAttributes
uint8_t WsfEfsGetAttributes(wsfEfsHandle_t handle, wsfEsfAttributes_t *pAttr)
Gets the attributes of a file.
wsfEfsMedia_t::endAddress
uint32_t endAddress
End address.
Definition: wsf_efs.h:210
wsfMediaReadFunc_t
uint8_t wsfMediaReadFunc_t(uint8_t *pBuf, uint8_t *pAddress, uint32_t size)
Media Read function.
Definition: wsf_efs.h:179
WsfEfsGetFilePermissions
uint16_t WsfEfsGetFilePermissions(wsfEfsHandle_t handle)
Get the permissions of a file.
wsfMediaHandleCmdFunc_t
uint8_t wsfMediaHandleCmdFunc_t(uint8_t cmd, uint32_t param)
Media Specific Command handler.
Definition: wsf_efs.h:204
WsfEfsInit
void WsfEfsInit(void)
Initialise the embedded file system.
wsfEfsFileInfo_t::handle
wsfEfsHandle_t handle
File handle.
Definition: wsf_efs.h:142
WsfEfsRegisterMedia
uint8_t WsfEfsRegisterMedia(const wsfEfsMedia_t *pMediaCtrl, uint8_t mediaID)
Registers a File Storage Medium with the Embedded File System.
wsfEfsMedia_t::init
wsfMediaInitFunc_t * init
Media intialization callback.
Definition: wsf_efs.h:212
WsfEfsGetFileMaxSize
uint32_t WsfEfsGetFileMaxSize(wsfEfsHandle_t handle)
Get the number of bytes of memory reserved for use by a file.
wsfEfsFileInfo_t::size
uint32_t size
File size.
Definition: wsf_efs.h:143
WsfEfsSetAttributes
uint8_t WsfEfsSetAttributes(wsfEfsHandle_t handle, wsfEsfAttributes_t *pInfo)
Updates the attributes of a file.
WsfEfsGet
uint16_t WsfEfsGet(wsfEfsHandle_t handle, uint32_t offset, uint8_t *pBuffer, uint16_t len)
Copies data from a file.
wsfEfsControl_t::address
uint32_t address
File storage address.
Definition: wsf_efs.h:133
pWsfEfsMedia_t
const wsfEfsMedia_t * pWsfEfsMedia_t
Pointer to Media Control data type.
Definition: wsf_efs.h:220
WSF_EFS_VERSION_LEN
#define WSF_EFS_VERSION_LEN
File version length in bytes.
Definition: wsf_efs.h:100
wsfEfsMedia_t::pageSize
uint32_t pageSize
Page size.
Definition: wsf_efs.h:211
wsfEsfAttributes_t
File attributes data type.
Definition: wsf_efs.h:121
WsfEfsGetFileSize
uint32_t WsfEfsGetFileSize(wsfEfsHandle_t handle)
Get the size of a file.
WsfEfsGetFileName
char * WsfEfsGetFileName(wsfEfsHandle_t handle)
Get the name of a file.
WsfEfsGetFileType
uint8_t WsfEfsGetFileType(wsfEfsHandle_t handle)
Get the type of a file.
wsfEfsMedia_t
Media Control data type.
Definition: wsf_efs.h:207
wsfEfsControl_t::media
uint8_t media
File media.
Definition: wsf_efs.h:134
WsfEfsRemoveFile
uint8_t WsfEfsRemoveFile(wsfEfsHandle_t handle)
Deletes a file in the embedded file system.
WSF_EFS_NAME_LEN
#define WSF_EFS_NAME_LEN
File name length in bytes.
Definition: wsf_efs.h:97
wsfEfsControl_t::size
uint32_t size
File size.
Definition: wsf_efs.h:135
WsfEfsGetFileByHandle
wsfEfsControl_t * WsfEfsGetFileByHandle(wsfEfsHandle_t handle)
Returns the file control block for the given handle.
wsfEfsControl_t
File control block data type.
Definition: wsf_efs.h:130
wsfEfsControl_t::attributes
wsfEsfAttributes_t attributes
File attributes.
Definition: wsf_efs.h:136
wsfEfsControl_t::maxSize
uint32_t maxSize
File maximum size.
Definition: wsf_efs.h:132
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.