rust: fs: introduce Type::read_dir

This allows file systems to report the contents of their directory
inodes.

User processes can use `getdents` to enumerate the entries reported by
`read_dir`.

Signed-off-by: Wedson Almeida Filho <walmeida@microsoft.com>

Author: wedsonaf

rust/kernel/fs.rs

@@ -24,6 +24,81 @@ pub mod ro {
 
         /// Initialises a super block for this file system type.
         fn fill_super(sb: NewSuperBlock<'_, Self>) -> Result<&SuperBlock<Self>>;
+
+        /// Reads directory entries from directory inodes.
+        ///
+        /// `pos` is the current position of the directory reader.
+        ///
+        /// `report` is a closure that takes the following arguments, in order: the entry name, its
+        /// position, its inode number, and its type. It returns `true` if the entry was copied to
+        /// caller or `false` otherwise (in which case, the `read_dir` implementation is advised to
+        /// stop calling `report`).
+        ///
+        /// On success, returns the new position of the reader.
+        fn read_dir(
+            inode: &INode<Self>,
+            pos: i64,
+            report: impl FnMut(&[u8], i64, u64, DirEntryType) -> bool,
+        ) -> Result<i64>;
+    }
+
+    /// The types of directory entries reported by [`Type::read_dir`].
+    #[repr(u32)]
+    #[derive(Copy, Clone)]
+    pub enum DirEntryType {
+        /// Unknown type.
+        Unknown = bindings::DT_UNKNOWN,
+
+        /// Named pipe (first-in, first-out) type.
+        Fifo = bindings::DT_FIFO,
+
+        /// Character device type.
+        Chr = bindings::DT_CHR,
+
+        /// Directory type.
+        Dir = bindings::DT_DIR,
+
+        /// Block device type.
+        Blk = bindings::DT_BLK,
+
+        /// Regular file type.
+        Reg = bindings::DT_REG,
+
+        /// Symbolic link type.
+        Lnk = bindings::DT_LNK,
+
+        /// Named unix-domain socket type.
+        Sock = bindings::DT_SOCK,
+
+        /// White-out type.
+        Wht = bindings::DT_WHT,
+    }
+
+    impl From<INodeType> for DirEntryType {
+        fn from(value: INodeType) -> Self {
+            match value {
+                INodeType::Dir => DirEntryType::Dir,
+            }
+        }
+    }
+
+    impl core::convert::TryFrom<u32> for DirEntryType {
+        type Error = crate::error::Error;
+
+        fn try_from(v: u32) -> Result<Self> {
+            match v {
+                v if v == Self::Unknown as u32 => Ok(Self::Unknown),
+                v if v == Self::Fifo as u32 => Ok(Self::Fifo),
+                v if v == Self::Chr as u32 => Ok(Self::Chr),
+                v if v == Self::Dir as u32 => Ok(Self::Dir),
+                v if v == Self::Blk as u32 => Ok(Self::Blk),
+                v if v == Self::Reg as u32 => Ok(Self::Reg),
+                v if v == Self::Lnk as u32 => Ok(Self::Lnk),
+                v if v == Self::Sock as u32 => Ok(Self::Sock),
+                v if v == Self::Wht as u32 => Ok(Self::Wht),
+                _ => Err(EDOM),
+            }
+        }
     }
 
     /// A registration of a read-only file system.
@@ -149,9 +224,7 @@ pub mod ro {
 
             let mode = match params.typ {
                 INodeType::Dir => {
-                    // SAFETY: `simple_dir_operations` never changes, it's safe to reference it.
-                    inode.__bindgen_anon_3.i_fop = unsafe { &bindings::simple_dir_operations };
-
+                    inode.__bindgen_anon_3.i_fop = &Tables::<T>::DIR_FILE_OPERATIONS;
                     // SAFETY: `simple_dir_inode_operations` never changes, it's safe to reference it.
                     inode.i_op = unsafe { &bindings::simple_dir_inode_operations };
                     bindings::S_IFDIR
@@ -422,6 +495,70 @@ pub mod ro {
             free_cached_objects: None,
             shutdown: None,
         };
+
+        const DIR_FILE_OPERATIONS: bindings::file_operations = bindings::file_operations {
+            owner: ptr::null_mut(),
+            llseek: Some(bindings::generic_file_llseek),
+            read: Some(bindings::generic_read_dir),
+            write: None,
+            read_iter: None,
+            write_iter: None,
+            iopoll: None,
+            iterate_shared: Some(Self::read_dir_callback),
+            poll: None,
+            unlocked_ioctl: None,
+            compat_ioctl: None,
+            mmap: None,
+            mmap_supported_flags: 0,
+            open: None,
+            flush: None,
+            release: None,
+            fsync: None,
+            fasync: None,
+            lock: None,
+            get_unmapped_area: None,
+            check_flags: None,
+            flock: None,
+            splice_write: None,
+            splice_read: None,
+            splice_eof: None,
+            setlease: None,
+            fallocate: None,
+            show_fdinfo: None,
+            copy_file_range: None,
+            remap_file_range: None,
+            fadvise: None,
+            uring_cmd: None,
+            uring_cmd_iopoll: None,
+        };
+
+        unsafe extern "C" fn read_dir_callback(
+            file: *mut bindings::file,
+            ctx_ptr: *mut bindings::dir_context,
+        ) -> core::ffi::c_int {
+            from_result(|| {
+                // SAFETY: The C api guarantees that `file` is valid for read. And since `f_inode`
+                // is immutable, we can read it directly.
+                let inode = unsafe { &*(*file).f_inode.cast::<INode<T>>() };
+
+                // SAFETY: The C api guarantees that this is the only reference to `dir_context`.
+                let ctx = unsafe { &mut *ctx_ptr };
+                let new_pos = T::read_dir(inode, ctx.pos, |name, foffset, ino, typ| {
+                    let Ok(name_len) = i32::try_from(name.len()) else {
+                        return false;
+                    };
+                    let Some(actor) = ctx.actor else {
+                        return false;
+                    };
+
+                    // SAFETY: `ctx` is valid by the C api convention, and name is valid at least
+                    // for the duration of the `actor` call.
+                    unsafe { actor(ctx, name.as_ptr().cast(), name_len, foffset, ino, typ as _) }
+                })?;
+                ctx.pos = new_pos;
+                Ok(0)
+            })
+        }
     }
 
     /// Kernel module that exposes a single read-only file system implemented by `T`.
@@ -470,6 +607,13 @@ pub mod ro {
     /// #    ) -> Result<&fs::ro::SuperBlock<Self>> {
     /// #        todo!()
     /// #    }
+    /// #    fn read_dir(
+    /// #        _: &fs::ro::INode<Self>,
+    /// #        _: i64,
+    /// #        _: impl FnMut(&[u8], i64, u64, fs::ro::DirEntryType) -> bool,
+    /// #    ) -> Result<i64> {
+    /// #        todo!()
+    /// #    }
     /// }
     /// ```
     #[macro_export]

samples/rust/rust_rofs.rs

@@ -2,7 +2,9 @@
 
 //! Rust read-only file system sample.
 
-use kernel::fs::ro::{INodeParams, INodeType, NewSuperBlock, SuperBlock, SuperParams};
+use kernel::fs::ro::{
+    DirEntryType, INode, INodeParams, INodeType, NewSuperBlock, SuperBlock, SuperParams,
+};
 use kernel::prelude::*;
 use kernel::{c_str, fs, time::UNIX_EPOCH, types::Either};
 
@@ -14,6 +16,30 @@ kernel::module_ro_fs! {
     license: "GPL",
 }
 
+struct Entry {
+    name: &'static [u8],
+    ino: u64,
+    etype: INodeType,
+}
+
+const ENTRIES: [Entry; 3] = [
+    Entry {
+        name: b".",
+        ino: 1,
+        etype: INodeType::Dir,
+    },
+    Entry {
+        name: b"..",
+        ino: 1,
+        etype: INodeType::Dir,
+    },
+    Entry {
+        name: b"subdir",
+        ino: 2,
+        etype: INodeType::Dir,
+    },
+];
+
 struct RoFs;
 impl fs::ro::Type for RoFs {
     const NAME: &'static CStr = c_str!("rust-fs");
@@ -24,7 +50,7 @@ impl fs::ro::Type for RoFs {
             Either::Right(new) => new.init(INodeParams {
                 typ: INodeType::Dir,
                 mode: 0o555,
-                size: 1,
+                size: ENTRIES.len().try_into()?,
                 blocks: 1,
                 nlink: 2,
                 uid: 0,
@@ -44,4 +70,27 @@ impl fs::ro::Type for RoFs {
             root,
         )
     }
+
+    fn read_dir(
+        inode: &INode<Self>,
+        mut pos: i64,
+        mut report: impl FnMut(&[u8], i64, u64, DirEntryType) -> bool,
+    ) -> Result<i64> {
+        if inode.ino() != 1 {
+            return Ok(pos);
+        }
+
+        if pos >= ENTRIES.len().try_into()? {
+            return Ok(pos);
+        }
+
+        for e in ENTRIES.iter().skip(pos.try_into()?) {
+            if !report(e.name, pos, e.ino, e.etype.into()) {
+                break;
+            }
+            pos += 1;
+        }
+
+        Ok(pos)
+    }
 }