pal_fileSystem.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef PAL_FILE_SYSTEM_H
00020 #define PAL_FILE_SYSTEM_H
00021 
00022 #ifndef _PAL_H
00023     #error "Please do not include this file directly, use pal.h instead"
00024 #endif
00025 
00026 /*! \file pal_fileSystem.h
00027  *  \brief PAL file system. This file contains the file system APIs and is part of the PAL service API.
00028  *
00029  *  It provides APIs to create and remove directories as well as open, read and write to files.
00030  */
00031 
00032 /*! \mainpage
00033  *
00034  *\section file_sec File System
00035  *
00036  *\subsection rev_hist Revision History
00037  *     19-Jan-2017    Created and First Draft\n
00038  *     25-Jan-2017    Updated Design according to DR meeting \n
00039  *     02-Jan-2017    Minor implementation Changes \n
00040  *
00041  *
00042  *
00043  * \subsection int_sec Introduction
00044  * This file details an abstraction layer for accessing POSIX-like file systems.
00045  *
00046  *
00047  * \subsection req_sec Requirements
00048  * The requirements for PAL Version 1.2 are to support the following POSIX-like APIs:
00049  *
00050  *
00051  *
00052  *\b Folder \b Operations
00053  *    -# mkdir        <a href="http://man7.org/linux/man-pages/man2/mkdir.2.html"> http://man7.org/linux/man-pages/man2/mkdir.2.html</a>
00054  *    -# rmdir()        <a href="http://man7.org/linux/man-pages/man2/rmdir.2.html"> http://man7.org/linux/man-pages/man2/rmdir.2.html</a>
00055  *
00056  *
00057  *\b File \b Operations
00058  *    -# fopen()      <a href="http://man7.org/linux/man-pages/man3/fopen.3.html"> http://man7.org/linux/man-pages/man3/fopen.3.html</a>
00059  *    -# fclose()     <a href="http://man7.org/linux/man-pages/man3/fclose.3.html"> http://man7.org/linux/man-pages/man3/fclose.3.html</a>
00060  *    -# fread()      <a href="http://man7.org/linux/man-pages/man3/fwrite.3.html"> http://man7.org/linux/man-pages/man3/fwrite.3.html</a>
00061  *    -# fwrite()     <a href="http://man7.org/linux/man-pages/man3/fwrite.3.html"> http://man7.org/linux/man-pages/man3/fwrite.3.html</a>
00062  *    -# fseek()      <a href="http://man7.org/linux/man-pages/man3/fseek.3.html"> http://man7.org/linux/man-pages/man3/fseek.3.html</a>
00063  *    -# ftell()      <a href="http://man7.org/linux/man-pages/man3/fseek.3.html"> http://man7.org/linux/man-pages/man3/fseek.3.html</a>
00064  *    -# unlink()     <a href="http://man7.org/linux/man-pages/man2/unlink.2.html"> http://man7.org/linux/man-pages/man2/unlink.2.html</a>
00065  *
00066  *
00067  *\b Special \b Operations
00068 
00069 *   -# rmfiles()    Delete folder content (files only) (flat deletion).
00070 *   -# cpfiles()    Copy all files in the folder to a different folder (flat copy).
00071  *
00072  *
00073  * \subsection preq_sec Prerequisites
00074 *   User need to set up the file system on your project and mount the proper drive if needed.
00075  *
00076  *
00077  * \subsection Limitations
00078 *   -# File size: Up to 2 GiB.
00079 *   -# Filename length: PAL_MAX_FILE_NAME_SIZE.
00080 *   -# Legal characters for object name: (file/directory name) are, (0-9), (a-z), (A - Z) (_ . # ).
00081 *   -# System is case-insensitive.
00082 *   -# The root folder can manage a maximum of 512 entries.
00083 *   -# Max path length is 66 Characters.
00084 *   -# Folder shall be separated with "/"
00085 *   -# All folder Paths shall end with "/"
00086 *
00087  *
00088  *
00089  * \subsection  References
00090  *      PAL_FileSystemSpecification.doc
00091  */
00092 
00093 /*!  @defgroup PAL_GROUP_FS File System Specification
00094  *
00095  *
00096  */
00097 /**
00098  @defgroup PAL_DEFINES  PAL Services Defined Symbols & Macros
00099  @ingroup PAL_GROUP_FS
00100  */
00101 
00102 /**
00103  @defgroup PAL_ENUM  PAL Services Enumerated Data Types
00104  @ingroup PAL_GROUP_FS
00105  */
00106 
00107 /**
00108  @defgroup PAL_PUBLIC_FUNCTION  PAL Services Public Functions
00109  @ingroup PAL_GROUP_FS
00110  */
00111 
00112 /**
00113  @addtogroup PAL_DEFINES
00114  @{*/
00115 
00116 
00117 #define PAL_MAX_FILE_NAME_SIZE      8               //!< Max length for file name received by user.
00118 #define PAL_MAX_FILE_NAME_SUFFIX    3               //!< Max length for file name suffix.
00119 #define PAL_MAX_FOLDER_DEPTH_CHAR   66              //!< Max folder length in chars.
00120 #define PAL_MAX_FILE_AND_FOLDER_LENGTH  (PAL_MAX_FILE_NAME_SIZE + PAL_MAX_FILE_NAME_SUFFIX + PAL_MAX_FOLDER_DEPTH_CHAR + 1) //!< Maximum combined file and folder name length. Plus 1 is for the period that separates file name and file suffix.
00121 #define PAL_MAX_FULL_FILE_NAME  (PAL_MAX_FILE_NAME_SUFFIX + PAL_MAX_FOLDER_DEPTH_CHAR + 1) //!< Maximum combined file name. Plus 1 is for the period that separates file name and file suffix.
00122 
00123 typedef uintptr_t palFileDescriptor_t; //!< Pointer to a generic File Descriptor object
00124 
00125 /**
00126  @} */
00127 /**
00128  @addtogroup PAL_ENUM
00129  @{*/
00130 
00131 /** \brief Enum for `fseek()` relative options. */
00132 typedef enum {
00133     PAL_FS_OFFSET_KEEP_FIRST = 0,
00134     PAL_FS_OFFSET_SEEKSET,      //!< Relative to the start of the file.
00135     PAL_FS_OFFSET_SEEKCUR,      //!< The current position indicator.
00136     PAL_FS_OFFSET_SEEKEND,      //!< End of file.
00137     PAL_FS_OFFSET_KEEP_LAST,
00138 
00139 } pal_fsOffset_t;
00140 
00141 /** \brief Enum for `fopen()` permission options*/
00142 typedef enum {
00143     PAL_FS_FLAG_KEEP_FIRST = 0,
00144     PAL_FS_FLAG_READONLY,           //!< Open file for reading only. The stream is positioned at the beginning of the file, same as "r". \note File must exist.
00145     PAL_FS_FLAG_READWRITE,          //!< Open for reading and writing. The stream is positioned at the beginning of the file, same as "r+ ". \note File must exist.
00146     PAL_FS_FLAG_READWRITEEXCLUSIVE, //!< Open for reading and writing exclusively. The stream is positioned at the beginning of the file. same as "w+x" \note If the file already exists, `fopen()` fails.
00147     PAL_FS_FLAG_READWRITETRUNC,     //!< Open for reading and writing exclusively. The stream is positioned at the beginning of the file. same as "w+" \note If the file already exists, it is truncated.
00148   PAL_FS_FLAG_KEEP_LAST,
00149 } pal_fsFileMode_t;
00150 /**
00151  @} */
00152 
00153 
00154 /** \brief Enum for partition access. */
00155 typedef enum {
00156     PAL_FS_PARTITION_PRIMARY = 0,        //!< Primary partition.\n
00157     PAL_FS_PARTITION_SECONDARY,          //!< Secondary partition.\n
00158     PAL_FS_PARTITION_LAST                //!< Must be last value.\n
00159 } pal_fsStorageID_t;
00160 
00161 
00162 /**
00163  @addtogroup PAL_PUBLIC_FUNCTION
00164  @{*/
00165 
00166 /*! \brief     This function attempts to create a directory named \c pathName.
00167  *
00168  * @param[in]   *pathName A pointer to the null-terminated string that specifies the directory name to create.
00169  *
00170  * \return PAL_SUCCESS upon successful operation.
00171  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00172  *
00173  * \note To remove a directory, use \c PAL_ERR_FS_rmdir.
00174  *
00175  *\b Example
00176  \code{.cpp}
00177  palStatus_t ret;
00178  ret = PAL_ERR_FS_mkdir("Dir1");
00179  if(!ret)
00180  {
00181  //Error
00182  }
00183  \endcode
00184  */
00185 palStatus_t pal_fsMkDir(const char *pathName);
00186 
00187 /*! \brief This function deletes a directory
00188  *
00189  * @param[in]   *pathName A pointer to the null-terminated string that specifies the directory name to be deleted.
00190  *
00191  * \return PAL_SUCCESS upon successful operation.
00192  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00193  *
00194 
00195 * \note The deleted directory \b must be both \e empty and \e closed and the
00196 *       folder path end with \c / .
00197 
00198  *
00199  *\b Example
00200  \code{.cpp}
00201  palStatus_t ret;
00202  ret = PAL_ERR_FS_mkdir("Dir1"); //Create folder name "Dir1"
00203  if(!ret)
00204  {
00205  //Error
00206  }
00207  ret = PAL_ERR_FS_rmdir("Dir1); //Remove directory from partition
00208  if(!ret)
00209  {
00210  //Error
00211  }
00212  \endcode
00213  */
00214 palStatus_t pal_fsRmDir(const char *pathName);
00215 
00216 
00217 /*!\brief This function opens the file whose name is specified in the parameter `pathName` and associates it with a stream
00218  *         that can be identified in future operations by the `fd` pointer returned.
00219  *
00220  * @param[out]  fd The file descriptor to the file entered in the `pathName`.
00221  * @param[in]   *pathName A pointer to the null-terminated string that specifies the file name to open or create.
00222  * @param[in]   mode A mode flag that specifies the type of access and open method for the file.
00223  *
00224  *
00225  * \return PAL_SUCCESS upon successful operation.
00226  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00227  *
00228  * \note      The folder path shall end with "/".
00229  *
00230  *\b Example
00231  \code{.cpp}
00232  //Copy File from "File1" to "File2"
00233  palStatus_t ret;
00234  palFileDescriptor_t fd1 = NULL,fd2 = NULL ; // File Object 1 & 2
00235  uint8 buffer[1024];
00236  size_t bytes_read = 0, Bytes_wrote = 0;
00237 
00238  //Open first file with Read permission
00239  ret = PAL_ERR_FS_fopen(&fd1, "File1", PAL_ERR_FS_READWRITEEXCLUSIVE);
00240  if(ret)    {//Error}
00241 
00242  //Create second file with Read/Write permissions
00243  ret = PAL_ERR_FS_fopen(&fd2, "File2", PAL_ERR_FS_READWRITEEXCLUSIVE);
00244  if(ret)    {//Error}
00245 
00246  //    Copy source to destination
00247  for (;;)
00248  {
00249  ret = PAL_ERR_FS_read(&fd1, buffer, sizeof(buffer), &bytes_read);    // Read a chunk of source file
00250  if (ret || bytes_read == 0) break;    // error or EOF
00251  ret = PAL_ERR_FS_write(&fd2, buffer, sizeof(buffer), &Bytes_wrote);    // Write it to the destination file
00252  if (ret || Bytes_wrote < bytes_read) break;    // error or disk full
00253  }
00254 
00255  PAL_ERR_FS_close(&fd1);
00256  PAL_ERR_FS_close(&fd2);
00257  }
00258  \endcode
00259  */
00260 palStatus_t pal_fsFopen(const char *pathName, pal_fsFileMode_t mode,
00261         palFileDescriptor_t *fd);
00262 
00263 /*! \brief This function closes an open file object.
00264  *
00265  * @param[in] fd A pointer to the open file object structure to be closed.
00266  *
00267  *
00268  * \return PAL_SUCCESS upon successful operation. \n
00269  *         PAL_FILE_SYSTEM_ERROR - see error code \c palError_t.
00270  *
00271  * \note When the function has completed successfully, the file object is no longer valid and it can be discarded.
00272  *
00273  */
00274 palStatus_t pal_fsFclose(palFileDescriptor_t *fd);
00275 
00276 
00277 /*! \brief This function reads an array of bytes from the stream and stores it in the block of memory
00278  *          specified by `buffer`. The position indicator of the stream is advanced by the total amount of bytes read.
00279  *
00280  * @param[in]   fd A pointer to the open file object structure.
00281  * @param[in]   buffer The buffer to store the read data.
00282  * @param[in]   numOfBytes The number of bytes to read.
00283  * @param[out]  numberOfBytesRead The number of bytes read.
00284 
00285  *
00286  * \return PAL_SUCCESS upon successful operation.
00287  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00288  *
00289  * \note    When the function has completed successfully,
00290  *      `numberOfBytesRead` should be checked to detect end of the file.
00291  *      If `numberOfBytesRead` is less than `numOfBytes`,
00292  *      the read/write pointer has reached the end of the file during the read operation or there is an error.
00293  *
00294  */
00295 palStatus_t pal_fsFread(palFileDescriptor_t *fd, void * buffer,
00296         size_t numOfBytes, size_t *numberOfBytesRead);
00297 
00298 /*! \brief This function starts to write data from \c buffer to the file at the position pointed by the read/write pointer.
00299  *
00300  * @param[in]   fd A pointer to the open file object structure.
00301  * @param[in]   buffer A pointer to the data to be written.
00302  * @param[in]   numOfBytes The number of bytes to write.
00303  * @param[out]  numberOfBytesWritten The number of bytes written.
00304  *
00305  * \return PAL_SUCCESS upon successful operation.
00306  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00307  *
00308  * \note The read/write pointer advances as number of bytes written. When the function has completed successfully,
00309  * \note `numberOfBytesWritten` should be checked to detect the whether the disk is full.
00310  *      If `numberOfBytesWritten` is less than `numOfBytes`, the volume got full during the write operation.
00311  *
00312  */
00313 palStatus_t pal_fsFwrite(palFileDescriptor_t *fd, const void * buffer,
00314         size_t numOfBytes, size_t *numberOfBytesWritten);
00315 
00316 
00317 /*! \brief This function moves the file read/write pointer without any read/write operation to the file.
00318  *
00319  * @param[in]   fd A pointer to the open file object structure.
00320  * @param[in]   offset The byte offset from the top of the file to set the read/write pointer.
00321  * @param[out]   whence Where the offset is relative to.
00322  *
00323  * \return PAL_SUCCESS upon successful operation.
00324  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00325  *
00326  * \note The `whence` options are: \n
00327  *       -# PAL_ERR_FS_SEEKSET - Relative to the start of the file.
00328  *           -# PAL_ERR_FS_SEEKCUR - The current position indicator.
00329  *       -# PAL_ERR_FS_SEEKEND - End-of-file.
00330  *
00331  *\b Example
00332  \code{.cpp}
00333  palStatus_t ret;
00334  palFileDescriptor_t fd1 = NULL; // File Object 1
00335  uint8 buffer[1024];
00336  size_t bytes_read = 0, Bytes_wrote = 0;
00337 
00338  //Open file with Read permission
00339  ret = PAL_ERR_FS_fopen(&fd1, "File1", PAL_ERR_FS_READ);
00340  if(ret)    {//Error}
00341 
00342  ret = PAL_ERR_FS_fseek(&fd1, 500, PAL_ERR_FS_SEEKSET)
00343 
00344  \endcode
00345  */
00346 palStatus_t pal_fsFseek(palFileDescriptor_t *fd, int32_t offset,
00347         pal_fsOffset_t whence);
00348 
00349 /*! \brief This function gets the current read/write pointer of a file.
00350  *
00351  * @param[in]   fd A pointer to the open file object structure.
00352  *
00353  * \return PAL_SUCCESS upon successful operation.
00354  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00355  *
00356  */
00357 palStatus_t pal_fsFtell(palFileDescriptor_t *fd, int32_t *pos);
00358 
00359 /*! \brief This function deletes a \e single file from the file system.
00360  *
00361  * @param[in]  pathName A pointer to a null-terminated string that specifies the file to be removed.
00362  *
00363  * \return PAL_SUCCESS upon successful operation.
00364  * \return PAL_FILE_SYSTEM_ERROR - see error code description \c palError_t.
00365  *
00366  * \note The file must \b not \b be \b open.
00367  *
00368  */
00369 palStatus_t pal_fsUnlink(const char *pathName);
00370 
00371 /*! \brief This function deletes \b all files and folders in a specified folder from the file system. Flat remove only.
00372  *
00373  * @param[in]  pathName A pointer to a null-terminated string that specifies the folder.
00374  *
00375  * \return PAL_SUCCESS upon successful operation.
00376  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00377  *
00378  * \note The folder must \b not \b be \b open and the folder path must end with \c / .
00379  */
00380 palStatus_t pal_fsRmFiles(const char *pathName);
00381 
00382 /*! \brief This function copies \b all files from the source folder to the destination folder. Flat copy only.
00383  *
00384  * @param[in]  pathNameSrc A pointer to a null-terminated string that specifies the source folder.
00385  * @param[in]  pathNameDest A pointer to a null-terminated string that specifies the destination folder. The folder MUST already exist.
00386  *
00387  * \return PAL_SUCCESS upon successful operation.
00388  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00389  *
00390  * \note Both folders must \b not \b be \b open. If the folders do not exist, the function fails.
00391  *
00392  */
00393 palStatus_t pal_fsCpFolder(const char *pathNameSrc, char *pathNameDest);
00394 
00395 /*! \brief This function sets the mount directory for the given storage ID (primary or secondary),
00396  *
00397  * @param[in]  Path A pointer to a null-terminated string that specifies the root folder.
00398  *
00399  * \return PAL_SUCCESS upon successful operation.
00400  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00401  *
00402  * \note    If called with \c NULL, the ESFS root folder is set to default PAL_SOURCE_FOLDER.
00403  * \note    The folder path must end with \c / .
00404  */
00405 palStatus_t pal_fsSetMountPoint(pal_fsStorageID_t dataID, const char *Path);
00406 
00407 /*! \brief This function gets the mount directory for the given storage ID (primary or secondary), The function copies the path to the user pre allocated buffer.
00408  *
00409  * @param[in]   length The length of the buffer.
00410  * @param[out]  Path A pointer to a \e pre-allocated \e buffer with size \c PAL_MAX_FOLDER_DEPTH_CHAR + 1 chars. The plus 1 is to account for the '\0' terminator at the end of the buffer
00411  *
00412  * \return PAL_SUCCESS upon successful operation.
00413  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t.
00414  *
00415  */
00416 palStatus_t pal_fsGetMountPoint(pal_fsStorageID_t dataID, size_t length, char *Path);
00417 
00418 /*! \brief This function formats a given SD partition.
00419  *
00420  * @param[in] dataID The ID of the partition to be formatted.
00421  *
00422  * \return PAL_SUCCESS upon successful operation.
00423  * \return PAL_FILE_SYSTEM_ERROR For error code description, see \c palError_t. \n
00424  * \return PAL_ERR_INVALID_ARGUMENT an invalid `partitionID`.
00425  *
00426  * \note The actual partition values mapped to the IDs is determined by the porting layer.
00427  */
00428 palStatus_t pal_fsFormat(pal_fsStorageID_t dataID);
00429 
00430 /*! \brief This function will return whether a given partition is used only by PAL or not.
00431  *
00432  * @param[in]   dataID - the ID of the data to be cleared.
00433  *
00434  * \return true  - if partition is used only by pal.
00435  * \return false - if partition is used by other component then pal.
00436  *
00437  * \note  The actual partition values mapped the IDs will be determined by the porting layer.
00438  */
00439 bool pal_fsIsPrivatePartition(pal_fsStorageID_t dataID);
00440 
00441 
00442 /*! \brief This function will perform clean up on all file system resources.
00443  */
00444 void pal_fsCleanup(void);
00445 
00446 
00447 /**
00448  @} */
00449 
00450 #endif//test