rust: fs: introduce FileSystem::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

@@ -22,6 +22,81 @@ pub trait FileSystem {
 
     /// 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 [`FileSystem::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 file system.
@@ -149,9 +224,7 @@ impl<T: FileSystem + ?Sized> NewINode<T> {
 
         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
@@ -419,6 +492,70 @@ impl<T: FileSystem + ?Sized> Tables<T> {
         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 file system implemented by `T`.
@@ -447,7 +584,7 @@ impl<T: FileSystem + ?Sized + Sync + Send> crate::InPlaceModule for Module<T> {
 ///
 /// ```
 /// # mod module_ro_fs_sample {
-/// use kernel::fs::{NewSuperBlock, SuperBlock};
+/// use kernel::fs::{DirEntryType, INode, NewSuperBlock, SuperBlock};
 /// use kernel::prelude::*;
 /// use kernel::{c_str, fs};
 ///
@@ -465,6 +602,13 @@ impl<T: FileSystem + ?Sized + Sync + Send> crate::InPlaceModule for Module<T> {
 ///     fn fill_super(_: NewSuperBlock<'_, Self>) -> Result<&SuperBlock<Self>> {
 ///         todo!()
 ///     }
+///     fn read_dir(
+///         _: &INode<Self>,
+///         _: i64,
+///         _: impl FnMut(&[u8], i64, u64, DirEntryType) -> bool,
+///     ) -> Result<i64> {
+///         todo!()
+///     }
 /// }
 /// # }
 /// ```

samples/rust/rust_rofs.rs

@@ -2,7 +2,9 @@
 
 //! Rust read-only file system sample.
 
-use kernel::fs::{INodeParams, INodeType, NewSuperBlock, SuperBlock, SuperParams};
+use kernel::fs::{
+    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_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::FileSystem for RoFs {
     const NAME: &'static CStr = c_str!("rust-fs");
@@ -24,7 +50,7 @@ impl fs::FileSystem 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::FileSystem 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)
+    }
 }