diff options
| -rw-r--r-- | doc/src/api/extfs.rst (renamed from doc/src/extfs.rst) | 0 | ||||
| -rw-r--r-- | doc/src/api/index.rst (renamed from doc/src/api.rst) | 0 | ||||
| -rw-r--r-- | doc/src/conf.py | 8 | ||||
| -rw-r--r-- | doc/src/index.rst | 3 | ||||
| -rw-r--r-- | doc/src/internal/index.rst | 7 | ||||
| -rw-r--r-- | doc/src/internal/superblock.rst | 42 | ||||
| -rw-r--r-- | include/fs/detail/superblock.hpp | 119 | ||||
| -rw-r--r-- | include/fs/detail/types.hpp | 42 |
8 files changed, 154 insertions, 67 deletions
diff --git a/doc/src/extfs.rst b/doc/src/api/extfs.rst index d8f1f5a..d8f1f5a 100644 --- a/doc/src/extfs.rst +++ b/doc/src/api/extfs.rst diff --git a/doc/src/api.rst b/doc/src/api/index.rst index 3b2cec2..3b2cec2 100644 --- a/doc/src/api.rst +++ b/doc/src/api/index.rst diff --git a/doc/src/conf.py b/doc/src/conf.py index a67aee4..bf3d6b1 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -9,11 +9,15 @@ subprocess.call('cd ../../ && doxygen', shell=True) html_theme = 'sphinx_rtd_theme' -extensions = ['breathe'] +extensions = [ + 'breathe', + 'sphinx.ext.todo', +] breathe_projects = {'extfs': os.path.abspath('../../build/xml') } breathe_default_project = 'extfs' + source_suffix = '.rst' master_doc = 'index' @@ -35,7 +39,7 @@ exclude_patterns = [ pygments_style = 'sphinx' -todo_include_todos = False +todo_include_todos = True htmlhelp_basename = 'extfsdoc' diff --git a/doc/src/index.rst b/doc/src/index.rst index dee63dd..9c02bcc 100644 --- a/doc/src/index.rst +++ b/doc/src/index.rst @@ -12,4 +12,5 @@ User documentation .. toctree:: :maxdepth: 2 - api + api/index + internal/index diff --git a/doc/src/internal/index.rst b/doc/src/internal/index.rst new file mode 100644 index 0000000..4b7e2f7 --- /dev/null +++ b/doc/src/internal/index.rst @@ -0,0 +1,7 @@ +Internal Design +=============== + +.. toctree:: + :maxdepth: 1 + + superblock diff --git a/doc/src/internal/superblock.rst b/doc/src/internal/superblock.rst new file mode 100644 index 0000000..6e85df4 --- /dev/null +++ b/doc/src/internal/superblock.rst @@ -0,0 +1,42 @@ +The Superblock +============== + +The **superblock** of an ext2/3/4 file system describes the structure and +configuration of the file system. This information is used by the +implementation to determine the physical and logical structure of the file +system. This section describes the structure of the superblock itself. + +Definitions +----------- + +All fields described in this section are stored on the disk in little-endian +format, regardless of the system architecture. + +.. warning:: The implementation currently only works in little-endian + architectures. If you would like to get involved in implementing big-endian + support, please file an issue at the project repository over at + `Github <https://github.com/fmorgner/extfs>`_ + +The code in `Implementation`_ makes us of several :code:`using` directives to +reduce the amount of typing as well as make the code more readable. The +following aliases are declared in ``fs/detail/types.hpp``: + +.. doxygentypedef:: fs::detail::u32 +.. doxygentypedef:: fs::detail::s32 +.. doxygentypedef:: fs::detail::u16 +.. doxygentypedef:: fs::detail::s16 +.. doxygentypedef:: fs::detail::u08 +.. doxygentypedef:: fs::detail::u32_arr +.. doxygentypedef:: fs::detail::u08_arr +.. doxygentypedef:: fs::detail::chr_arr + +Structure +--------- + +.. todo:: Describe structure of the superblock + +Implementation +-------------- + +.. doxygenstruct:: fs::detail::extfs_superblock + :members: diff --git a/include/fs/detail/superblock.hpp b/include/fs/detail/superblock.hpp index 5b7a4ca..f86fe3d 100644 --- a/include/fs/detail/superblock.hpp +++ b/include/fs/detail/superblock.hpp @@ -1,78 +1,69 @@ #ifndef EXTFS_SUPERBLOCK_HPP #define EXTFS_SUPERBLOCK_HPP +#include "fs/detail/types.hpp" + #include <array> #include <cstdint> namespace fs::detail { - using u32 = std::uint32_t; - using s32 = std::int32_t; - using u16 = std::uint16_t; - using s16 = std::uint16_t; - using u08 = std::uint8_t; - - template<std::size_t Size> - using chr_arr = std::array<char, Size>; - - template<std::size_t Size> - using u08_arr = std::array<u08, Size>; - - template<std::size_t Size> - using u32_arr = std::array<u32, Size>; - - + /** + * This structure describes the ext2/3/4 superblock + * + * @since 1.0 + */ struct extfs_superblock { - u32 const inodes_count{}; - u32 const blocks_count{}; - u32 const reserved_blocks_count{}; - u32 const free_blocks_count{}; - u32 const free_inodes_count{}; - u32 const first_data_block_id{}; - u32 const logical_block_size{}; - s32 const logical_fragment_size{}; - u32 const blocks_per_group{}; - u32 const fragments_per_group{}; - u32 const inodes_per_group{}; - u32 const last_mount_timestamp{}; - u32 const last_write_timestamp{}; - u16 const mount_count{}; - u16 const maximum_mount_count{}; - u16 const magic_number{}; - s16 const state{}; - s16 const error_behaviour{}; - s16 const revision_level_minor{}; - u32 const last_check_timestamp{}; - u32 const check_interval{}; - u32 const creator_operating_system_id{}; - u32 const revision_level{}; - u16 const super_user_id{}; - u16 const super_user_group_id{}; - u32 const first_inode_id{}; - u16 const inode_size{}; - u16 const superblock_group_id{}; - u32 const compatible_features{}; - u32 const incompatible_features{}; - u32 const read_only_compatible_features{}; - u08_arr<16> const uuid{}; - chr_arr<16> const volume_name{}; - chr_arr<64> const last_mount_point{}; - u32 const compression_algorithm{}; - u08 const file_preallocated_blocks_count{}; - u08 const directory_preallocated_blocks_count{}; - u16 const _padding{}; - u08_arr<16> const journal_superblock_uuid{}; - u32 const journal_inode_id{}; - u32 const journal_device_number{}; - u32 const last_orphan_inode_id{}; - u32_arr<4> const hash_seed{}; - u08 const hash_version{}; - u08_arr<3> const _reserved0{}; - u32 const default_mount_options{}; - u32 const first_meta_block_group_id{}; - u08_arr<760> const _reserved1{}; + u32 const inodes_count{}; ///< The total number of inodes in the file system + u32 const blocks_count{}; ///< The total number of blocks in the file system + u32 const reserved_blocks_count{}; ///< The number of blocks reserved for the super user + u32 const free_blocks_count{}; ///< The number of free blocks in the file system + u32 const free_inodes_count{}; ///< The mumber of free inodes in the file system + u32 const first_data_block_id{}; ///< The first block that carries user data in the file system + u32 const logical_block_size{}; ///< The logical size of a block (1024 << logical_block_size) + s32 const logical_fragment_size{}; ///< The logical size of a block (1024 << logical_fragment_size) + u32 const blocks_per_group{}; ///< The number of blocks per block group + u32 const fragments_per_group{}; ///< The number of fragments per block group + u32 const inodes_per_group{}; ///< The number of inodes per block group + u32 const last_mount_timestamp{}; ///< The unix timestamp when the file system was last mounted + u32 const last_write_timestamp{}; ///< The unix timestamp of the last write operation to the file system + u16 const mount_count{}; ///< The number of times the file system was mounted since the last check + u16 const maximum_mount_count{}; ///< The maximum number of times the file system can be mounted until a full check + u16 const magic_number{}; ///< The magic number identifying the file system type + s16 const state{}; ///< The state of the file system + s16 const error_behaviour{}; ///< The desired behaviour if a file system error occurs + s16 const revision_level_minor{}; ///< The minor revision level of the file system + u32 const last_check_timestamp{}; ///< The unix timestamp of the last check of the file system + u32 const check_interval{}; ///< The unix time interval in which to check the file system + u32 const creator_operating_system_id{}; ///< The operation system identifier of the OS that created the file system + u32 const revision_level{}; ///< The revision level of the file system + u16 const super_user_id{}; ///< The user ID of the super user + u16 const super_user_group_id{}; ///< The group ID of the super user group + u32 const first_inode_id{}; ///< The id of the first inode usable for standard files + u16 const inode_size{}; ///< The size of an inode in bytes + u16 const superblock_group_id{}; ///< The ID of the block group hosting this superblock + u32 const compatible_features{}; ///< The active compatible features + u32 const incompatible_features{}; ///< The active incompatible feature + u32 const read_only_compatible_features{}; ///< The active features compatible with read-only mode + u08_arr<16> const uuid{}; ///< The UUID of the file system + chr_arr<16> const label{}; ///< The label of the file system + chr_arr<64> const last_mount_point{}; ///< The location the file system was last mounted on + u32 const compression_algorithm{}; ///< The compression algorithm used in the file system + u08 const file_preallocated_blocks_count{}; ///< The number of blocks to preallocate for a file + u08 const directory_preallocated_blocks_count{}; ///< The number of block to preallocate for a directory + u16 const _padding{}; ///< Alignment padding + u08_arr<16> const journal_superblock_uuid{}; ///< The UUID of the superblock containing the journal + u32 const journal_inode_id{}; ///< The ID of the inode hosting the journal + u32 const journal_device_number{}; ///< The device number of the journal + u32 const last_orphan_inode_id{}; ///< The first inode in the list of inodes to delete + u32_arr<4> const hash_seed{}; ///< The seed for the directory hashing algorithm + u08 const hash_version{}; ///< The version of the directory hashing algorithm + u08_arr<3> const _reserved0{}; ///< Alignment padding + u32 const default_mount_options{}; ///< The default mount options for the file system + u32 const first_meta_block_group_id{}; ///< The ID of the first meta block group + u08_arr<760> const _reserved1{}; ///< Padding }; static_assert(sizeof(extfs_superblock) == 1024, "An ext* super block must have an exact size of 1024 byte!"); diff --git a/include/fs/detail/types.hpp b/include/fs/detail/types.hpp new file mode 100644 index 0000000..df84512 --- /dev/null +++ b/include/fs/detail/types.hpp @@ -0,0 +1,42 @@ +#ifndef EXTFS_TYPES_HPP +#define EXTFS_TYPES_HPP + +#include <array> +#include <cstdint> + +namespace fs::detail + { + + using u32 = std::uint32_t; ///< An unsigned 32-bit integer + using s32 = std::int32_t; ///< A signed 32-bit integer + using u16 = std::uint16_t; ///< An unsigned 16-bit integer + using s16 = std::uint16_t; ///< A signed 16-bit integer + using u08 = std::uint8_t; ///< An unsigned 8-bit integer + + /** + * An array of characters + * + * @tparam Size The size of the array + */ + template<std::size_t Size> + using chr_arr = std::array<char, Size>; + + /** + * An array of unsigned 8-bit integers + * + * @tparam Size The size of the array + */ + template<std::size_t Size> + using u08_arr = std::array<u08, Size>; + + /** + * An array of unsigned 32-bit integers + * + * @tparam Size The size of the array + */ + template<std::size_t Size> + using u32_arr = std::array<u32, Size>; + + } + +#endif |