Simplify the ioctl API. (#1348)

* Simplify the `ioctl` API.

As suggested [here], simplify the ioctl API by renaming `RawOpcode` to
`Opcode` and using const generics.

[here]: #1022 (comment)

* Remove `none`'s `T` parameter.

* Add more comments.

* Reword `ioctl`'s safety comment to be more explicit about opcode choice.

Author: sunfishcode

CHANGES.md

@@ -303,5 +303,23 @@ vector before calling `epoll::wait` or `kqueue`, or consuming it using
 [`Buffer` trait]: https://docs.rs/rustix/1.0.0/rustix/buffer/trait.Buffer.html
 [`spare_capacity`]: https://docs.rs/rustix/1.0.0/rustix/buffer/fn.spare_capacity.html
 
+The `Opcode` type has changed from a struct to a raw integer value, and the
+associated utilities are change to `const` functions. In place of `ReadOpcode`,
+`WriteOpcode`, `ReadWriteOpcode`, and `NoneOpcode`, use the `read`, `write`,
+`read_write`, and `none` const functions in the [`ioctl::opcode`] module. For
+example, in place of this:
+```rust
+ioctl::Setter::<ioctl::ReadOpcode<b'U', 15, c_uint>, c_uint>::new(interface)
+```
+use this:
+```rust
++ ioctl::Setter::<{ ioctl::opcode::read::<c_uint>(b'U', 15) }, c_uint>::new(interface)
+```
+.
+
+In place of `BadOpcode`, use the opcode value directly.
+
+[`ioctl::opcode`]: https://docs.rs/rustix/1.0.0/rustix/ioctl/opcode/index.html
+
 All explicitly deprecated functions and types have been removed. Their
 deprecation messages will have identified alternatives.

src/backend/libc/fs/mod.rs

@@ -16,8 +16,8 @@ pub(crate) mod types;
 
 // TODO: Fix linux-raw-sys to define ioctl codes for sparc.
 #[cfg(all(linux_kernel, any(target_arch = "sparc", target_arch = "sparc64")))]
-pub(crate) const EXT4_IOC_RESIZE_FS: crate::ioctl::RawOpcode = 0x8008_6610;
+pub(crate) const EXT4_IOC_RESIZE_FS: crate::ioctl::Opcode = 0x8008_6610;
 
 #[cfg(all(linux_kernel, not(any(target_arch = "sparc", target_arch = "sparc64"))))]
-pub(crate) const EXT4_IOC_RESIZE_FS: crate::ioctl::RawOpcode =
-    linux_raw_sys::ioctl::EXT4_IOC_RESIZE_FS as crate::ioctl::RawOpcode;
+pub(crate) const EXT4_IOC_RESIZE_FS: crate::ioctl::Opcode =
+    linux_raw_sys::ioctl::EXT4_IOC_RESIZE_FS as crate::ioctl::Opcode;

src/backend/libc/io/syscalls.rs

@@ -16,7 +16,7 @@ use crate::io::DupFlags;
 #[cfg(linux_kernel)]
 use crate::io::ReadWriteFlags;
 use crate::io::{self, FdFlags};
-use crate::ioctl::{IoctlOutput, RawOpcode};
+use crate::ioctl::{IoctlOutput, Opcode};
 use core::cmp::min;
 #[cfg(not(any(target_os = "espidf", target_os = "horizon")))]
 use {
@@ -210,7 +210,7 @@ pub(crate) unsafe fn try_close(raw_fd: RawFd) -> io::Result<()> {
 #[inline]
 pub(crate) unsafe fn ioctl(
     fd: BorrowedFd<'_>,
-    request: RawOpcode,
+    request: Opcode,
     arg: *mut c::c_void,
 ) -> io::Result<IoctlOutput> {
     ret_c_int(c::ioctl(borrowed_fd(fd), request, arg))
@@ -219,7 +219,7 @@ pub(crate) unsafe fn ioctl(
 #[inline]
 pub(crate) unsafe fn ioctl_readonly(
     fd: BorrowedFd<'_>,
-    request: RawOpcode,
+    request: Opcode,
     arg: *mut c::c_void,
 ) -> io::Result<IoctlOutput> {
     ioctl(fd, request, arg)

src/backend/libc/io/windows_syscalls.rs

@@ -7,7 +7,7 @@ use crate::backend::conv::{borrowed_fd, ret_c_int, ret_send_recv, send_recv_len}
 use crate::backend::fd::LibcFd;
 use crate::fd::{BorrowedFd, RawFd};
 use crate::io;
-use crate::ioctl::{IoctlOutput, RawOpcode};
+use crate::ioctl::{IoctlOutput, Opcode};
 
 pub(crate) unsafe fn read(fd: BorrowedFd<'_>, buf: (*mut u8, usize)) -> io::Result<usize> {
     // `read` on a socket is equivalent to `recv` with no flags.
@@ -43,7 +43,7 @@ pub(crate) unsafe fn try_close(raw_fd: RawFd) -> io::Result<()> {
 #[inline]
 pub(crate) unsafe fn ioctl(
     fd: BorrowedFd<'_>,
-    request: RawOpcode,
+    request: Opcode,
     arg: *mut c::c_void,
 ) -> io::Result<IoctlOutput> {
     ret_c_int(c::ioctl(borrowed_fd(fd), request, arg.cast()))
@@ -52,7 +52,7 @@ pub(crate) unsafe fn ioctl(
 #[inline]
 pub(crate) unsafe fn ioctl_readonly(
     fd: BorrowedFd<'_>,
-    request: RawOpcode,
+    request: Opcode,
     arg: *mut c::c_void,
 ) -> io::Result<IoctlOutput> {
     ioctl(fd, request, arg)

src/backend/linux_raw/io/syscalls.rs

@@ -27,7 +27,7 @@ use crate::backend::conv::{hi, lo};
 use crate::backend::{c, MAX_IOV};
 use crate::fd::{AsFd as _, BorrowedFd, OwnedFd, RawFd};
 use crate::io::{self, DupFlags, FdFlags, IoSlice, IoSliceMut, ReadWriteFlags};
-use crate::ioctl::{IoctlOutput, RawOpcode};
+use crate::ioctl::{IoctlOutput, Opcode};
 use core::cmp;
 use linux_raw_sys::general::{F_DUPFD_CLOEXEC, F_GETFD, F_SETFD};
 
@@ -272,7 +272,7 @@ pub(crate) unsafe fn try_close(fd: RawFd) -> io::Result<()> {
 #[inline]
 pub(crate) unsafe fn ioctl(
     fd: BorrowedFd<'_>,
-    request: RawOpcode,
+    request: Opcode,
     arg: *mut c::c_void,
 ) -> io::Result<IoctlOutput> {
     ret_c_int(syscall!(__NR_ioctl, fd, c_uint(request), arg))
@@ -281,7 +281,7 @@ pub(crate) unsafe fn ioctl(
 #[inline]
 pub(crate) unsafe fn ioctl_readonly(
     fd: BorrowedFd<'_>,
-    request: RawOpcode,
+    request: Opcode,
     arg: *mut c::c_void,
 ) -> io::Result<IoctlOutput> {
     ret_c_int(syscall_readonly!(__NR_ioctl, fd, c_uint(request), arg))

src/fs/ioctl.rs

@@ -25,7 +25,7 @@ use crate::fd::{AsRawFd as _, BorrowedFd};
 pub fn ioctl_blksszget<Fd: AsFd>(fd: Fd) -> io::Result<u32> {
     // SAFETY: `BLZSSZGET` is a getter opcode that gets a u32.
     unsafe {
-        let ctl = ioctl::Getter::<ioctl::BadOpcode<{ c::BLKSSZGET }>, c::c_uint>::new();
+        let ctl = ioctl::Getter::<{ c::BLKSSZGET }, c::c_uint>::new();
         ioctl::ioctl(fd, ctl)
     }
 }
@@ -37,7 +37,7 @@ pub fn ioctl_blksszget<Fd: AsFd>(fd: Fd) -> io::Result<u32> {
 pub fn ioctl_blkpbszget<Fd: AsFd>(fd: Fd) -> io::Result<u32> {
     // SAFETY: `BLKPBSZGET` is a getter opcode that gets a u32.
     unsafe {
-        let ctl = ioctl::Getter::<ioctl::BadOpcode<{ c::BLKPBSZGET }>, c::c_uint>::new();
+        let ctl = ioctl::Getter::<{ c::BLKPBSZGET }, c::c_uint>::new();
         ioctl::ioctl(fd, ctl)
     }
 }
@@ -64,9 +64,7 @@ pub fn ioctl_ficlone<Fd: AsFd, SrcFd: AsFd>(fd: Fd, src_fd: SrcFd) -> io::Result
 pub fn ext4_ioc_resize_fs<Fd: AsFd>(fd: Fd, blocks: u64) -> io::Result<()> {
     // SAFETY: `EXT4_IOC_RESIZE_FS` is a pointer setter opcode.
     unsafe {
-        let ctl = ioctl::Setter::<ioctl::BadOpcode<{ backend::fs::EXT4_IOC_RESIZE_FS }>, u64>::new(
-            blocks,
-        );
+        let ctl = ioctl::Setter::<{ backend::fs::EXT4_IOC_RESIZE_FS }, u64>::new(blocks);
         ioctl::ioctl(fd, ctl)
     }
 }
@@ -81,7 +79,7 @@ unsafe impl ioctl::Ioctl for Ficlone<'_> {
     const IS_MUTATING: bool = false;
 
     fn opcode(&self) -> ioctl::Opcode {
-        ioctl::Opcode::old(c::FICLONE as ioctl::RawOpcode)
+        c::FICLONE as ioctl::Opcode
     }
 
     fn as_ptr(&mut self) -> *mut c::c_void {
@@ -144,9 +142,9 @@ bitflags! {
 pub fn ioctl_getflags<Fd: AsFd>(fd: Fd) -> io::Result<IFlags> {
     unsafe {
         #[cfg(target_pointer_width = "32")]
-        let ctl = ioctl::Getter::<ioctl::BadOpcode<{ c::FS_IOC32_GETFLAGS }>, u32>::new();
+        let ctl = ioctl::Getter::<{ c::FS_IOC32_GETFLAGS }, u32>::new();
         #[cfg(target_pointer_width = "64")]
-        let ctl = ioctl::Getter::<ioctl::BadOpcode<{ c::FS_IOC_GETFLAGS }>, u32>::new();
+        let ctl = ioctl::Getter::<{ c::FS_IOC_GETFLAGS }, u32>::new();
 
         ioctl::ioctl(fd, ctl).map(IFlags::from_bits_retain)
     }
@@ -161,11 +159,10 @@ pub fn ioctl_getflags<Fd: AsFd>(fd: Fd) -> io::Result<IFlags> {
 pub fn ioctl_setflags<Fd: AsFd>(fd: Fd, flags: IFlags) -> io::Result<()> {
     unsafe {
         #[cfg(target_pointer_width = "32")]
-        let ctl =
-            ioctl::Setter::<ioctl::BadOpcode<{ c::FS_IOC32_SETFLAGS }>, u32>::new(flags.bits());
+        let ctl = ioctl::Setter::<{ c::FS_IOC32_SETFLAGS }, u32>::new(flags.bits());
 
         #[cfg(target_pointer_width = "64")]
-        let ctl = ioctl::Setter::<ioctl::BadOpcode<{ c::FS_IOC_SETFLAGS }>, u32>::new(flags.bits());
+        let ctl = ioctl::Setter::<{ c::FS_IOC_SETFLAGS }, u32>::new(flags.bits());
 
         ioctl::ioctl(fd, ctl)
     }

src/io/ioctl.rs

@@ -23,7 +23,7 @@ use backend::fd::AsFd;
 pub fn ioctl_fioclex<Fd: AsFd>(fd: Fd) -> io::Result<()> {
     // SAFETY: `FIOCLEX` is a no-argument setter opcode.
     unsafe {
-        let ctl = ioctl::NoArg::<ioctl::BadOpcode<{ c::FIOCLEX }>>::new();
+        let ctl = ioctl::NoArg::<{ c::FIOCLEX }>::new();
         ioctl::ioctl(fd, ctl)
     }
 }
@@ -43,7 +43,7 @@ pub fn ioctl_fioclex<Fd: AsFd>(fd: Fd) -> io::Result<()> {
 pub fn ioctl_fionbio<Fd: AsFd>(fd: Fd, value: bool) -> io::Result<()> {
     // SAFETY: `FIONBIO` is a pointer setter opcode.
     unsafe {
-        let ctl = ioctl::Setter::<ioctl::BadOpcode<{ c::FIONBIO }>, c::c_int>::new(value.into());
+        let ctl = ioctl::Setter::<{ c::FIONBIO }, c::c_int>::new(value.into());
         ioctl::ioctl(fd, ctl)
     }
 }
@@ -71,7 +71,7 @@ pub fn ioctl_fionbio<Fd: AsFd>(fd: Fd, value: bool) -> io::Result<()> {
 pub fn ioctl_fionread<Fd: AsFd>(fd: Fd) -> io::Result<u64> {
     // SAFETY: `FIONREAD` is a getter opcode that gets a `c_int`.
     unsafe {
-        let ctl = ioctl::Getter::<ioctl::BadOpcode<{ c::FIONREAD }>, c::c_int>::new();
+        let ctl = ioctl::Getter::<{ c::FIONREAD }, c::c_int>::new();
         ioctl::ioctl(fd, ctl).map(|n| n as u64)
     }
 }

src/ioctl/bsd.rs

@@ -1,13 +1,13 @@
 //! `ioctl` opcode behavior for BSD platforms.
 
-use super::{Direction, RawOpcode};
+use super::{Direction, Opcode};
 
 pub(super) const fn compose_opcode(
     dir: Direction,
-    group: RawOpcode,
-    num: RawOpcode,
-    size: RawOpcode,
-) -> RawOpcode {
+    group: Opcode,
+    num: Opcode,
+    size: Opcode,
+) -> Opcode {
     let dir = match dir {
         Direction::None => NONE,
         Direction::Read => READ,
@@ -19,9 +19,9 @@ pub(super) const fn compose_opcode(
 }
 
 // `IOC_VOID`
-pub const NONE: RawOpcode = 0x2000_0000;
+pub const NONE: Opcode = 0x2000_0000;
 // `IOC_OUT` (“out” is from the perspective of the kernel)
-pub const READ: RawOpcode = 0x4000_0000;
+pub const READ: Opcode = 0x4000_0000;
 // `IOC_IN` (“in” is from the perspective of the kernel)
-pub const WRITE: RawOpcode = 0x8000_0000;
-pub const IOCPARAM_MASK: RawOpcode = 0x1FFF;
+pub const WRITE: Opcode = 0x8000_0000;
+pub const IOCPARAM_MASK: Opcode = 0x1FFF;

src/ioctl/linux.rs

@@ -1,15 +1,15 @@
 //! `ioctl` opcode behavior for Linux platforms.
 
-use super::{Direction, RawOpcode};
+use super::{Direction, Opcode};
 use consts::*;
 
 /// Compose an opcode from its component parts.
 pub(super) const fn compose_opcode(
     dir: Direction,
-    group: RawOpcode,
-    num: RawOpcode,
-    size: RawOpcode,
-) -> RawOpcode {
+    group: Opcode,
+    num: Opcode,
+    size: Opcode,
+) -> Opcode {
     macro_rules! mask_and_shift {
         ($val:expr, $shift:expr, $mask:expr) => {{
             ($val & $mask) << $shift
@@ -29,18 +29,18 @@ pub(super) const fn compose_opcode(
         | mask_and_shift!(dir, DIR_SHIFT, DIR_MASK)
 }
 
-const NUM_BITS: RawOpcode = 8;
-const GROUP_BITS: RawOpcode = 8;
+const NUM_BITS: Opcode = 8;
+const GROUP_BITS: Opcode = 8;
 
-const NUM_SHIFT: RawOpcode = 0;
-const GROUP_SHIFT: RawOpcode = NUM_SHIFT + NUM_BITS;
-const SIZE_SHIFT: RawOpcode = GROUP_SHIFT + GROUP_BITS;
-const DIR_SHIFT: RawOpcode = SIZE_SHIFT + SIZE_BITS;
+const NUM_SHIFT: Opcode = 0;
+const GROUP_SHIFT: Opcode = NUM_SHIFT + NUM_BITS;
+const SIZE_SHIFT: Opcode = GROUP_SHIFT + GROUP_BITS;
+const DIR_SHIFT: Opcode = SIZE_SHIFT + SIZE_BITS;
 
-const NUM_MASK: RawOpcode = (1 << NUM_BITS) - 1;
-const GROUP_MASK: RawOpcode = (1 << GROUP_BITS) - 1;
-const SIZE_MASK: RawOpcode = (1 << SIZE_BITS) - 1;
-const DIR_MASK: RawOpcode = (1 << DIR_BITS) - 1;
+const NUM_MASK: Opcode = (1 << NUM_BITS) - 1;
+const GROUP_MASK: Opcode = (1 << GROUP_BITS) - 1;
+const SIZE_MASK: Opcode = (1 << SIZE_BITS) - 1;
+const DIR_MASK: Opcode = (1 << DIR_BITS) - 1;
 
 #[cfg(any(
     target_arch = "x86",
@@ -54,13 +54,13 @@ const DIR_MASK: RawOpcode = (1 << DIR_BITS) - 1;
     target_arch = "csky"
 ))]
 mod consts {
-    use super::RawOpcode;
+    use super::Opcode;
 
-    pub(super) const NONE: RawOpcode = 0;
-    pub(super) const READ: RawOpcode = 2;
-    pub(super) const WRITE: RawOpcode = 1;
-    pub(super) const SIZE_BITS: RawOpcode = 14;
-    pub(super) const DIR_BITS: RawOpcode = 2;
+    pub(super) const NONE: Opcode = 0;
+    pub(super) const READ: Opcode = 2;
+    pub(super) const WRITE: Opcode = 1;
+    pub(super) const SIZE_BITS: Opcode = 14;
+    pub(super) const DIR_BITS: Opcode = 2;
 }
 
 #[cfg(any(
@@ -74,13 +74,13 @@ mod consts {
     target_arch = "sparc64"
 ))]
 mod consts {
-    use super::RawOpcode;
+    use super::Opcode;
 
-    pub(super) const NONE: RawOpcode = 1;
-    pub(super) const READ: RawOpcode = 2;
-    pub(super) const WRITE: RawOpcode = 4;
-    pub(super) const SIZE_BITS: RawOpcode = 13;
-    pub(super) const DIR_BITS: RawOpcode = 3;
+    pub(super) const NONE: Opcode = 1;
+    pub(super) const READ: Opcode = 2;
+    pub(super) const WRITE: Opcode = 4;
+    pub(super) const SIZE_BITS: Opcode = 13;
+    pub(super) const DIR_BITS: Opcode = 3;
 }
 
 #[cfg(not(any(
@@ -98,11 +98,11 @@ fn check_known_opcodes() {
     assert_eq!(
         compose_opcode(
             Direction::Read,
-            b'U' as RawOpcode,
+            b'U' as Opcode,
             15,
-            size_of::<c_uint>() as RawOpcode
+            size_of::<c_uint>() as Opcode
         ),
-        linux_raw_sys::ioctl::USBDEVFS_CLAIMINTERFACE as RawOpcode
+        linux_raw_sys::ioctl::USBDEVFS_CLAIMINTERFACE as Opcode
     );
 
     // _IOW('v', 2, long)
@@ -111,10 +111,10 @@ fn check_known_opcodes() {
     assert_eq!(
         compose_opcode(
             Direction::Write,
-            b'v' as RawOpcode,
+            b'v' as Opcode,
             2,
-            size_of::<c_long>() as RawOpcode
+            size_of::<c_long>() as Opcode
         ),
-        linux_raw_sys::ioctl::FS_IOC_SETVERSION as RawOpcode
+        linux_raw_sys::ioctl::FS_IOC_SETVERSION as Opcode
     );
 }