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