rtems/rfs/rtems-rfs-file-system.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief RTEMS File System Data
0007  *
0008  * @ingroup rtems_rfs
0009  *
0010  * RTEMS File System Data
0011  *
0012  * This file defines the file system data.
0013  */
0014
0015 /*
0016  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #if !defined (_RTEMS_RFS_FILE_SYSTEM_H_)
0041 #define _RTEMS_RFS_FILE_SYSTEM_H_
0042
0043 #include <rtems/rfs/rtems-rfs-group.h>
0044
0045 /**
0046  * Superblock offsets and values.
0047  */
0048 #define RTEMS_RFS_SB_OFFSET_MAGIC           (0)
0049 #define RTEMS_RFS_SB_MAGIC                  (0x28092001)
0050 #define RTEMS_RFS_SB_OFFSET_VERSION         (RTEMS_RFS_SB_OFFSET_MAGIC           + 4)
0051 #define RTEMS_RFS_SB_OFFSET_BLOCK_SIZE      (RTEMS_RFS_SB_OFFSET_VERSION         + 4)
0052 #define RTEMS_RFS_SB_OFFSET_BLOCKS          (RTEMS_RFS_SB_OFFSET_BLOCK_SIZE      + 4)
0053 #define RTEMS_RFS_SB_OFFSET_BAD_BLOCKS      (RTEMS_RFS_SB_OFFSET_BLOCKS          + 4)
0054 #define RTEMS_RFS_SB_OFFSET_MAX_NAME_LENGTH (RTEMS_RFS_SB_OFFSET_BAD_BLOCKS      + 4)
0055 #define RTEMS_RFS_SB_OFFSET_GROUPS          (RTEMS_RFS_SB_OFFSET_MAX_NAME_LENGTH + 4)
0056 #define RTEMS_RFS_SB_OFFSET_GROUP_BLOCKS    (RTEMS_RFS_SB_OFFSET_GROUPS          + 4)
0057 #define RTEMS_RFS_SB_OFFSET_GROUP_INODES    (RTEMS_RFS_SB_OFFSET_GROUP_BLOCKS    + 4)
0058 #define RTEMS_RFS_SB_OFFSET_INODE_SIZE      (RTEMS_RFS_SB_OFFSET_GROUP_INODES    + 4)
0059
0060 /**
0061  * RFS Version Number.
0062  */
0063 #define RTEMS_RFS_VERSION (0x00000000)
0064
0065 /**
0066  * RFS Version Number Mask. The mask determines which bits of the version
0067  * number indicate compatility issues.
0068  */
0069 #define RTEMS_RFS_VERSION_MASK INT32_C(0x00000000)
0070
0071 /**
0072  * The root inode number. Do not use 0 as this has special meaning in some
0073  * Unix operating systems.
0074  */
0075 #define RTEMS_RFS_ROOT_INO (1)
0076
0077 /**
0078  * Empty inode number.
0079  */
0080 #define RTEMS_RFS_EMPTY_INO (0)
0081
0082 /**
0083  * The number of blocks in the inode. This number effects the size of the
0084  * inode and that effects the overhead of the inode tables in a group.
0085  */
0086 #define RTEMS_RFS_INODE_BLOCKS (5)
0087
0088 /**
0089  * The inode overhead is the percentage of space reserved for inodes. It is
0090  * calculated as the percentage number of blocks in a group. The number of
0091  * blocks in a group is the number of bits a block can hold.
0092  */
0093 #define RTEMS_RFS_INODE_OVERHEAD_PERCENTAGE (1)
0094
0095 /**
0096  * Number of blocks in the superblock. Yes I know it is a superblock and not
0097  * superblocks but if for any reason this needs to change it is handled.
0098  */
0099 #define RTEMS_RFS_SUPERBLOCK_SIZE (1)
0100
0101 /**
0102  * The maximum number of buffers held by the file system at any one time.
0103  */
0104 #define RTEMS_RFS_FS_MAX_HELD_BUFFERS (5)
0105
0106 /**
0107  * Absolute position. Make a 64bit value.
0108  */
0109 typedef uint64_t rtems_rfs_pos;
0110
0111 /**
0112  * Relative position. Make a 64bit value.
0113  */
0114 typedef int64_t rtems_rfs_pos_rel;
0115
0116 /**
0117  * Flags to control the file system.
0118  */
0119 #define RTEMS_RFS_FS_BITMAPS_HOLD      (1 << 0) /**< Do not release bitmaps
0120                                                  * when finished. Default is
0121                                                  * off so they are released. */
0122 #define RTEMS_RFS_FS_NO_LOCAL_CACHE    (1 << 1) /**< Do not cache the buffers
0123                                                  * and release directly to the
0124                                                  * buffer support layer. The
0125                                                  * default is to hold buffers. */
0126 #define RTEMS_RFS_FS_FORCE_OPEN        (1 << 2) /**< Force open and ignore any
0127                                                  * errors. */
0128 #define RTEMS_RFS_FS_READ_ONLY         (1 << 3) /**< Make the mount
0129                                                  * read-only. Currently not
0130                                                  * supported. */
0131 /**
0132  * RFS File System data.
0133  */
0134 struct _rtems_rfs_file_system
0135 {
0136   /**
0137    * Flags to control the file system. Some can be controlled via the ioctl.
0138    */
0139   uint32_t flags;
0140
0141   /**
0142    * The number of blocks in the disk. The size of the disk is the number of
0143    * blocks by the block size. This should be within a block size of the size
0144    * returned by the media driver.
0145    */
0146   size_t blocks;
0147
0148   /**
0149    * The size of a block. This must be a multiple of the disk's media block
0150    * size.
0151    */
0152   size_t block_size;
0153
0154   /**
0155    * The file descriptor for device I/O.
0156    */
0157   int device;
0158
0159 #if RTEMS_RFS_USE_LIBBLOCK
0160   /**
0161    * The disk device. This is the data about the block device this file system
0162    * is mounted on. We access the data held in this structure rather than
0163    * making an extra copy in this structure.
0164    */
0165   rtems_disk_device* disk;
0166 #else
0167   /**
0168    * The number of blocks in the file system.
0169    */
0170   size_t size;
0171 #endif
0172
0173   /**
0174    * Inode count.
0175    */
0176   uint32_t inodes;
0177
0178   /**
0179    * Bad block blocks. This is a table of blocks that have been found to be
0180    * bad.
0181    */
0182   uint32_t bad_blocks;
0183
0184   /**
0185    * Maximum length of names supported by this file system.
0186    */
0187   uint32_t max_name_length;
0188
0189   /**
0190    * A disk is broken down into a series of groups.
0191    */
0192   rtems_rfs_group* groups;
0193
0194   /**
0195    * Number of groups.
0196    */
0197   int group_count;
0198
0199   /**
0200    * Number of blocks in a group.
0201    */
0202   size_t group_blocks;
0203
0204   /**
0205    * Number of inodes in a group.
0206    */
0207   size_t group_inodes;
0208
0209   /**
0210    * Number of inodes in each block.
0211    */
0212   size_t inodes_per_block;
0213
0214   /**
0215    * Number of block numbers in a block.
0216    */
0217   size_t blocks_per_block;
0218
0219   /**
0220    * Block map single indirect count. This is the block number per block
0221    * multiplied but the slots in the inode.
0222    */
0223   size_t block_map_singly_blocks;
0224
0225   /**
0226    * Block map double indirect count. This is the block number per block
0227    * squared and multiplied by the slots in the inode. It is the maximum
0228    * number of blocks a map (file/directory) can have.
0229    */
0230   size_t block_map_doubly_blocks;
0231
0232   /**
0233    * Number of buffers held before releasing back to the cache.
0234    */
0235   uint32_t max_held_buffers;
0236
0237   /**
0238    * List of buffers attached to buffer handles. Allows sharing.
0239    */
0240   rtems_chain_control buffers;
0241
0242   /**
0243    * Number of buffers held on the buffers list.
0244    */
0245   uint32_t buffers_count;
0246
0247   /**
0248    * List of buffers that need to be released when the processing of a file
0249    * system request has completed.
0250    */
0251   rtems_chain_control release;
0252
0253   /**
0254    * Number of buffers held on the release list.
0255    */
0256   uint32_t release_count;
0257
0258   /**
0259    * List of buffers that need to be released modified when the processing of a
0260    * file system request has completed.
0261    */
0262   rtems_chain_control release_modified;
0263
0264   /**
0265    * Number of buffers held on the release modified list.
0266    */
0267   uint32_t release_modified_count;
0268
0269   /**
0270    * List of open shared file node data. The shared node data such as the inode
0271    * and block map allows a single file to be open more than once.
0272    */
0273   rtems_chain_control file_shares;
0274
0275   /**
0276    * Pointer to user data supplied when opening.
0277    */
0278   void* user;
0279 };
0280
0281 /**
0282  * Return the flags.
0283  *
0284  * @param[in] _fs is a pointer to the file system.
0285  */
0286 #define rtems_rfs_fs_flags(_f) ((_f)->flags)
0287 /**
0288  * Should bitmap buffers be released when finished ?
0289  *
0290  * @param[in] _fs is a pointer to the file system.
0291  */
0292 #define rtems_rfs_fs_release_bitmaps(_f) (!((_f)->flags & RTEMS_RFS_FS_BITMAPS_HOLD))
0293
0294 /**
0295  * Are the buffers locally cache or released back to the buffering layer ?
0296  *
0297  * @param[in] _fs is a pointer to the file system.
0298  */
0299 #define rtems_rfs_fs_no_local_cache(_f) ((_f)->flags & RTEMS_RFS_FS_NO_LOCAL_CACHE)
0300
0301 /**
0302  * The disk device number.
0303  *
0304  * @param[in] _fs is a pointer to the file system.
0305  */
0306 #if RTEMS_RFS_USE_LIBBLOCK
0307 #define rtems_rfs_fs_device(_fs) ((_fs)->disk)
0308 #else
0309 #define rtems_rfs_fs_device(_fs) ((_fs)->device)
0310 #endif
0311
0312 /**
0313  * The size of the disk in blocks.
0314  *
0315  * @param[in] _fs is a pointer to the file system.
0316  */
0317 #define rtems_rfs_fs_blocks(_fs) ((_fs)->blocks)
0318
0319 /**
0320  * The block size.
0321  *
0322  * @param[in] _fs is a pointer to the file system.
0323  */
0324 #define rtems_rfs_fs_block_size(_fs) ((_fs)->block_size)
0325
0326 /**
0327  * The number of inodes.
0328  *
0329  * @param[in] _fs is a pointer to the file system.
0330  */
0331 #define rtems_rfs_fs_inodes(_fs) ((_fs)->inodes)
0332
0333 /**
0334  * Calculate a block in the file system given the group and the block within
0335  * the group.
0336  *
0337  * @param[in] _fs is a pointer to the file system.
0338  * @param[in] _grp is the group.
0339  * @param[in] _blk is the block within the group.
0340  * @return The absolute block number.
0341  */
0342 #define rtems_rfs_fs_block(_fs, _grp, _blk) \
0343   ((((_fs)->group_blocks) * (_grp)) + (_blk) + 1)
0344
0345 /**
0346  * The media size of the disk in media size blocks.
0347  *
0348  * @param[in] _fs is a pointer to the file system.
0349  */
0350 #if RTEMS_RFS_USE_LIBBLOCK
0351 #define rtems_rfs_fs_media_blocks(_fs) ((_fs)->disk->size)
0352 #else
0353 #define rtems_rfs_fs_media_blocks(_fs) ((_fs)->media_size)
0354 #endif
0355
0356 /**
0357  * The media block size. This is the size of a block on disk. For a device I/O
0358  * this value is 1.
0359  *
0360  * @param[in] _fs is a pointer to the file system.
0361  */
0362 #if RTEMS_RFS_USE_LIBBLOCK
0363 #define rtems_rfs_fs_media_block_size(_fs) ((_fs)->disk->media_block_size)
0364 #else
0365 #define rtems_rfs_fs_media_block_size(_fs) (1)
0366 #endif
0367
0368 /**
0369  * The maximum length of a name supported by the file system.
0370  */
0371 #define rtems_rfs_fs_max_name(_fs) ((_fs)->max_name_length)
0372
0373 /**
0374  * Return the maximum number of blocks in a block map.
0375  *
0376  * @return uint32_t The maximum number of blocks possible.
0377  */
0378 #define rtems_rfs_fs_max_block_map_blocks(_fs) ((_fs)->block_map_doubly_blocks)
0379
0380 /**
0381  * Return the user pointer.
0382  */
0383 #define rtems_rfs_fs_user(_fs) ((_fs)->user)
0384
0385 /**
0386  * Return the size of the disk in bytes.
0387  *
0388  * @param[in] fs is a pointer to the file system.
0389  * @return uint64_t The size of the disk in bytes.
0390  */
0391 uint64_t rtems_rfs_fs_size(rtems_rfs_file_system* fs);
0392
0393 /**
0394  * The size of the disk in bytes calculated from the media parameters..
0395  *
0396  * @param[in] fs is a pointer to the file system.
0397  * @return uint64_t The size of the disk in bytes.
0398  */
0399 uint64_t rtems_rfs_fs_media_size (rtems_rfs_file_system* fs);
0400
0401 /**
0402  * Open the file system given a file path.
0403  *
0404  * @param[in] name is a pointer to the device to open.
0405  * @param[in] fs is the file system data filled in by this call.
0406  * @param[in] user is a pointer to the user data.
0407  * @param[in] flags is a initial set of user flags for the file system.
0408  * @param[in] max_held_buffers is the maximum number of buffers the RFS holds.
0409  *
0410  * @retval 0 Successful operation.
0411  * @retval -1 Error. See errno
0412  */
0413 int rtems_rfs_fs_open (const char*             name,
0414                        void*                   user,
0415                        uint32_t                flags,
0416                        uint32_t                max_held_buffers,
0417                        rtems_rfs_file_system** fs);
0418
0419 /**
0420  * Close the file system.
0421  *
0422  * @param[in] fs is the file system data.
0423  *
0424  * @retval 0 Successful operation.
0425  * @retval -1 Error. See errno
0426  */
0427 int rtems_rfs_fs_close (rtems_rfs_file_system* fs);
0428
0429 #endif