From db7574f676c2c0f90a48dde0c34a73e9549d955f Mon Sep 17 00:00:00 2001 From: Bryant Mairs Date: Sun, 7 Jan 2018 18:30:34 -0800 Subject: Refactor the ioctl API and documentation * Split `ioctl!` into separate macros. This makes documentation easier to read. * For every `ioctl_*!` macro include a description of the macro arguments as, the function prototype for the generated wrapper function, and an example if we have one. * Expose `request_code_*!` in the documentation to make the `ioctl_*_bad` macros easier to use. * Reorganize the file hierarchy to be simpler --- test/sys/test_ioctl.rs | 198 ++++++++++++++++++------------------------------- 1 file changed, 72 insertions(+), 126 deletions(-) (limited to 'test/sys') diff --git a/test/sys/test_ioctl.rs b/test/sys/test_ioctl.rs index 9a7a4819..ec9d26a3 100644 --- a/test/sys/test_ioctl.rs +++ b/test/sys/test_ioctl.rs @@ -1,80 +1,26 @@ #![allow(dead_code)] // Simple tests to ensure macro generated fns compile -ioctl!(bad none do_bad with 0x1234); -ioctl!(bad read do_bad_read with 0x1234; u16); -ioctl!(bad write_int do_bad_write_int with 0x1234); -ioctl!(bad write_ptr do_bad_write_ptr with 0x1234; u8); -ioctl!(bad readwrite do_bad_readwrite with 0x1234; u32); -ioctl!(none do_none with 0, 0); -ioctl!(read read_test with 0, 0; u32); -ioctl!(write_int write_ptr_int with 0, 0); -ioctl!(write_ptr write_ptr_u8 with 0, 0; u8); -ioctl!(write_ptr write_ptr_u32 with 0, 0; u32); -ioctl!(write_ptr write_ptr_u64 with 0, 0; u64); -ioctl!(readwrite readwrite_test with 0, 0; u64); -ioctl!(read_buf readbuf_test with 0, 0; u32); +ioctl_none_bad!(do_bad, 0x1234); +ioctl_read_bad!(do_bad_read, 0x1234, u16); +ioctl_write_int_bad!(do_bad_write_int, 0x1234); +ioctl_write_ptr_bad!(do_bad_write_ptr, 0x1234, u8); +ioctl_readwrite_bad!(do_bad_readwrite, 0x1234, u32); +ioctl_none!(do_none, 0, 0); +ioctl_read!(read_test, 0, 0, u32); +ioctl_write_int!(write_ptr_int, 0, 0); +ioctl_write_ptr!(write_ptr_u8, 0, 0, u8); +ioctl_write_ptr!(write_ptr_u32, 0, 0, u32); +ioctl_write_ptr!(write_ptr_u64, 0, 0, u64); +ioctl_readwrite!(readwrite_test, 0, 0, u64); +ioctl_read_buf!(readbuf_test, 0, 0, u32); const SPI_IOC_MAGIC: u8 = b'k'; const SPI_IOC_MESSAGE: u8 = 0; -ioctl!(write_buf writebuf_test_consts with SPI_IOC_MAGIC, SPI_IOC_MESSAGE; u8); -ioctl!(write_buf writebuf_test_u8 with 0, 0; u8); -ioctl!(write_buf writebuf_test_u32 with 0, 0; u32); -ioctl!(write_buf writebuf_test_u64 with 0, 0; u64); -ioctl!(readwrite_buf readwritebuf_test with 0, 0; u32); - -// Make sure documentation works -ioctl! { - /// This documents the ioctl function - bad none do_bad_docs with 0x1234 -} -ioctl! { - /// This documents the ioctl function - bad read do_bad_read_docs with 0x1234; u16 -} -ioctl! { - /// This documents the ioctl function - bad write_int do_bad_write_int_docs with 0x1234 -} -ioctl! { - /// This documents the ioctl function - bad write_ptr do_bad_write_ptr_docs with 0x1234; u8 -} -ioctl! { - /// This documents the ioctl function - bad readwrite do_bad_readwrite_docs with 0x1234; u32 -} -ioctl! { - /// This documents the ioctl function - none do_none_docs with 0, 0 -} -ioctl! { - /// This documents the ioctl function - read do_read_docs with 0, 0; u32 -} -ioctl! { - /// This documents the ioctl function - write_int do_write_int_docs with 0, 0 -} -ioctl! { - /// This documents the ioctl function - write_ptr do_write_ptr_docs with 0, 0; u32 -} -ioctl! { - /// This documents the ioctl function - readwrite do_readwrite_docs with 0, 0; u32 -} -ioctl! { - /// This documents the ioctl function - read_buf do_read_buf_docs with 0, 0; u32 -} -ioctl! { - /// This documents the ioctl function - write_buf do_write_buf_docs with 0, 0; u32 -} -ioctl! { - /// This documents the ioctl function - readwrite_buf do_readwrite_buf_docs with 0, 0; u32 -} +ioctl_write_buf!(writebuf_test_consts, SPI_IOC_MAGIC, SPI_IOC_MESSAGE, u8); +ioctl_write_buf!(writebuf_test_u8, 0, 0, u8); +ioctl_write_buf!(writebuf_test_u32, 0, 0, u32); +ioctl_write_buf!(writebuf_test_u64, 0, 0, u64); +ioctl_readwrite_buf!(readwritebuf_test, 0, 0, u32); // See C code for source of values for op calculations (does NOT work for mips/powerpc): // https://gist.github.com/posborne/83ea6880770a1aef332e @@ -87,22 +33,22 @@ mod linux { #[test] fn test_op_none() { if cfg!(any(target_arch = "mips", target_arch = "mips64", target_arch="powerpc", target_arch="powerpc64")){ - assert_eq!(io!(b'q', 10), 0x2000_710A); - assert_eq!(io!(b'a', 255), 0x2000_61FF); + assert_eq!(request_code_none!(b'q', 10), 0x2000_710A); + assert_eq!(request_code_none!(b'a', 255), 0x2000_61FF); } else { - assert_eq!(io!(b'q', 10), 0x0000_710A); - assert_eq!(io!(b'a', 255), 0x0000_61FF); + assert_eq!(request_code_none!(b'q', 10), 0x0000_710A); + assert_eq!(request_code_none!(b'a', 255), 0x0000_61FF); } } #[test] fn test_op_write() { if cfg!(any(target_arch = "mips", target_arch = "mips64", target_arch="powerpc", target_arch="powerpc64")){ - assert_eq!(iow!(b'z', 10, 1), 0x8001_7A0A); - assert_eq!(iow!(b'z', 10, 512), 0x8200_7A0A); + assert_eq!(request_code_write!(b'z', 10, 1), 0x8001_7A0A); + assert_eq!(request_code_write!(b'z', 10, 512), 0x8200_7A0A); } else { - assert_eq!(iow!(b'z', 10, 1), 0x4001_7A0A); - assert_eq!(iow!(b'z', 10, 512), 0x4200_7A0A); + assert_eq!(request_code_write!(b'z', 10, 1), 0x4001_7A0A); + assert_eq!(request_code_write!(b'z', 10, 512), 0x4200_7A0A); } } @@ -110,9 +56,9 @@ mod linux { #[test] fn test_op_write_64() { if cfg!(any(target_arch = "mips64", target_arch="powerpc64")){ - assert_eq!(iow!(b'z', 10, (1 as u64) << 32), 0x8000_7A0A); + assert_eq!(request_code_write!(b'z', 10, (1 as u64) << 32), 0x8000_7A0A); } else { - assert_eq!(iow!(b'z', 10, (1 as u64) << 32), 0x4000_7A0A); + assert_eq!(request_code_write!(b'z', 10, (1 as u64) << 32), 0x4000_7A0A); } } @@ -120,11 +66,11 @@ mod linux { #[test] fn test_op_read() { if cfg!(any(target_arch = "mips", target_arch = "mips64", target_arch="powerpc", target_arch="powerpc64")){ - assert_eq!(ior!(b'z', 10, 1), 0x4001_7A0A); - assert_eq!(ior!(b'z', 10, 512), 0x4200_7A0A); + assert_eq!(request_code_read!(b'z', 10, 1), 0x4001_7A0A); + assert_eq!(request_code_read!(b'z', 10, 512), 0x4200_7A0A); } else { - assert_eq!(ior!(b'z', 10, 1), 0x8001_7A0A); - assert_eq!(ior!(b'z', 10, 512), 0x8200_7A0A); + assert_eq!(request_code_read!(b'z', 10, 1), 0x8001_7A0A); + assert_eq!(request_code_read!(b'z', 10, 512), 0x8200_7A0A); } } @@ -132,72 +78,72 @@ mod linux { #[test] fn test_op_read_64() { if cfg!(any(target_arch = "mips64", target_arch="powerpc64")){ - assert_eq!(ior!(b'z', 10, (1 as u64) << 32), 0x4000_7A0A); + assert_eq!(request_code_read!(b'z', 10, (1 as u64) << 32), 0x4000_7A0A); } else { - assert_eq!(ior!(b'z', 10, (1 as u64) << 32), 0x8000_7A0A); + assert_eq!(request_code_read!(b'z', 10, (1 as u64) << 32), 0x8000_7A0A); } } #[test] fn test_op_read_write() { - assert_eq!(iorw!(b'z', 10, 1), 0xC001_7A0A); - assert_eq!(iorw!(b'z', 10, 512), 0xC200_7A0A); + assert_eq!(request_code_readwrite!(b'z', 10, 1), 0xC001_7A0A); + assert_eq!(request_code_readwrite!(b'z', 10, 512), 0xC200_7A0A); } #[cfg(target_pointer_width = "64")] #[test] fn test_op_read_write_64() { - assert_eq!(iorw!(b'z', 10, (1 as u64) << 32), 0xC000_7A0A); + assert_eq!(request_code_readwrite!(b'z', 10, (1 as u64) << 32), 0xC000_7A0A); } } -#[cfg(any(target_os = "macos", +#[cfg(any(target_os = "dragonfly", + target_os = "freebsd", target_os = "ios", + target_os = "macos", target_os = "netbsd", - target_os = "openbsd", - target_os = "freebsd", - target_os = "dragonfly"))] + target_os = "openbsd"))] mod bsd { #[test] fn test_op_none() { - assert_eq!(io!(b'q', 10), 0x2000_710A); - assert_eq!(io!(b'a', 255), 0x2000_61FF); + assert_eq!(request_code_none!(b'q', 10), 0x2000_710A); + assert_eq!(request_code_none!(b'a', 255), 0x2000_61FF); } #[test] fn test_op_write() { - assert_eq!(iow!(b'z', 10, 1), 0x8001_7A0A); - assert_eq!(iow!(b'z', 10, 512), 0x8200_7A0A); + assert_eq!(request_code_write!(b'z', 10, 1), 0x8001_7A0A); + assert_eq!(request_code_write!(b'z', 10, 512), 0x8200_7A0A); } #[cfg(target_pointer_width = "64")] #[test] fn test_op_write_64() { - assert_eq!(iow!(b'z', 10, (1 as u64) << 32), 0x8000_7A0A); + assert_eq!(request_code_write!(b'z', 10, (1 as u64) << 32), 0x8000_7A0A); } #[test] fn test_op_read() { - assert_eq!(ior!(b'z', 10, 1), 0x4001_7A0A); - assert_eq!(ior!(b'z', 10, 512), 0x4200_7A0A); + assert_eq!(request_code_read!(b'z', 10, 1), 0x4001_7A0A); + assert_eq!(request_code_read!(b'z', 10, 512), 0x4200_7A0A); } #[cfg(target_pointer_width = "64")] #[test] fn test_op_read_64() { - assert_eq!(ior!(b'z', 10, (1 as u64) << 32), 0x4000_7A0A); + assert_eq!(request_code_read!(b'z', 10, (1 as u64) << 32), 0x4000_7A0A); } #[test] fn test_op_read_write() { - assert_eq!(iorw!(b'z', 10, 1), 0xC001_7A0A); - assert_eq!(iorw!(b'z', 10, 512), 0xC200_7A0A); + assert_eq!(request_code_readwrite!(b'z', 10, 1), 0xC001_7A0A); + assert_eq!(request_code_readwrite!(b'z', 10, 512), 0xC200_7A0A); } #[cfg(target_pointer_width = "64")] #[test] fn test_op_read_write_64() { - assert_eq!(iorw!(b'z', 10, (1 as u64) << 32), 0xC000_7A0A); + assert_eq!(request_code_readwrite!(b'z', 10, (1 as u64) << 32), 0xC000_7A0A); } } @@ -212,44 +158,44 @@ mod linux_ioctls { use nix::Error::Sys; use nix::errno::Errno::{ENOTTY, ENOSYS}; - ioctl!(bad none tiocnxcl with TIOCNXCL); + ioctl_none_bad!(tiocnxcl, TIOCNXCL); #[test] - fn test_ioctl_bad_none() { + fn test_ioctl_none_bad() { let file = tempfile().unwrap(); let res = unsafe { tiocnxcl(file.as_raw_fd()) }; assert_eq!(res, Err(Sys(ENOTTY))); } - ioctl!(bad read tcgets with TCGETS; termios); + ioctl_read_bad!(tcgets, TCGETS, termios); #[test] - fn test_ioctl_bad_read() { + fn test_ioctl_read_bad() { let file = tempfile().unwrap(); let mut termios = unsafe { mem::uninitialized() }; let res = unsafe { tcgets(file.as_raw_fd(), &mut termios) }; assert_eq!(res, Err(Sys(ENOTTY))); } - ioctl!(bad write_int tcsbrk with TCSBRK); + ioctl_write_int_bad!(tcsbrk, TCSBRK); #[test] - fn test_ioctl_bad_write_int() { + fn test_ioctl_write_int_bad() { let file = tempfile().unwrap(); let res = unsafe { tcsbrk(file.as_raw_fd(), 0) }; assert_eq!(res, Err(Sys(ENOTTY))); } - ioctl!(bad write_ptr tcsets with TCSETS; termios); + ioctl_write_ptr_bad!(tcsets, TCSETS, termios); #[test] - fn test_ioctl_bad_write_ptr() { + fn test_ioctl_write_ptr_bad() { let file = tempfile().unwrap(); let termios: termios = unsafe { mem::uninitialized() }; let res = unsafe { tcsets(file.as_raw_fd(), &termios) }; assert_eq!(res, Err(Sys(ENOTTY))); } - // FIXME: Find a suitable example for "bad readwrite". + // FIXME: Find a suitable example for `ioctl_readwrite_bad` // From linux/videodev2.h - ioctl!(none log_status with b'V', 70); + ioctl_none!(log_status, b'V', 70); #[test] fn test_ioctl_none() { let file = tempfile().unwrap(); @@ -267,7 +213,7 @@ mod linux_ioctls { } // From linux/videodev2.h - ioctl!(write_ptr s_audio with b'V', 34; v4l2_audio); + ioctl_write_ptr!(s_audio, b'V', 34, v4l2_audio); #[test] fn test_ioctl_write_ptr() { let file = tempfile().unwrap(); @@ -279,7 +225,7 @@ mod linux_ioctls { // From linux/net/bluetooth/hci_sock.h const HCI_IOC_MAGIC: u8 = b'H'; const HCI_IOC_HCIDEVUP: u8 = 201; - ioctl!(write_int hcidevup with HCI_IOC_MAGIC, HCI_IOC_HCIDEVUP); + ioctl_write_int!(hcidevup, HCI_IOC_MAGIC, HCI_IOC_HCIDEVUP); #[test] fn test_ioctl_write_int() { let file = tempfile().unwrap(); @@ -288,7 +234,7 @@ mod linux_ioctls { } // From linux/videodev2.h - ioctl!(read g_audio with b'V', 33; v4l2_audio); + ioctl_read!(g_audio, b'V', 33, v4l2_audio); #[test] fn test_ioctl_read() { let file = tempfile().unwrap(); @@ -298,7 +244,7 @@ mod linux_ioctls { } // From linux/videodev2.h - ioctl!(readwrite enum_audio with b'V', 65; v4l2_audio); + ioctl_readwrite!(enum_audio, b'V', 65, v4l2_audio); #[test] fn test_ioctl_readwrite() { let file = tempfile().unwrap(); @@ -307,7 +253,7 @@ mod linux_ioctls { assert!(res == Err(Sys(ENOTTY)) || res == Err(Sys(ENOSYS))); } - // FIXME: Find a suitable example for read_buf. + // FIXME: Find a suitable example for `ioctl_read_buf`. #[repr(C)] pub struct spi_ioc_transfer { @@ -324,7 +270,7 @@ mod linux_ioctls { } // From linux/spi/spidev.h - ioctl!(write_buf spi_ioc_message with super::SPI_IOC_MAGIC, super::SPI_IOC_MESSAGE; spi_ioc_transfer); + ioctl_write_buf!(spi_ioc_message, super::SPI_IOC_MAGIC, super::SPI_IOC_MESSAGE, spi_ioc_transfer); #[test] fn test_ioctl_write_buf() { let file = tempfile().unwrap(); @@ -333,7 +279,7 @@ mod linux_ioctls { assert!(res == Err(Sys(ENOTTY)) || res == Err(Sys(ENOSYS))); } - // FIXME: Find a suitable example for readwrite_buf. + // FIXME: Find a suitable example for `ioctl_readwrite_buf`. } #[cfg(target_os = "freebsd")] @@ -353,7 +299,7 @@ mod freebsd_ioctls { const TTY_IOC_TYPE_GETA: u8 = 19; const TTY_IOC_TYPE_SETA: u8 = 20; - ioctl!(none tiocnxcl with TTY_IOC_MAGIC, TTY_IOC_TYPE_NXCL); + ioctl_none!(tiocnxcl, TTY_IOC_MAGIC, TTY_IOC_TYPE_NXCL); #[test] fn test_ioctl_none() { let file = tempfile().unwrap(); @@ -361,7 +307,7 @@ mod freebsd_ioctls { assert_eq!(res, Err(Sys(ENOTTY))); } - ioctl!(read tiocgeta with TTY_IOC_MAGIC, TTY_IOC_TYPE_GETA; termios); + ioctl_read!(tiocgeta, TTY_IOC_MAGIC, TTY_IOC_TYPE_GETA, termios); #[test] fn test_ioctl_read() { let file = tempfile().unwrap(); @@ -370,7 +316,7 @@ mod freebsd_ioctls { assert_eq!(res, Err(Sys(ENOTTY))); } - ioctl!(write_ptr tiocseta with TTY_IOC_MAGIC, TTY_IOC_TYPE_SETA; termios); + ioctl_write_ptr!(tiocseta, TTY_IOC_MAGIC, TTY_IOC_TYPE_SETA, termios); #[test] fn test_ioctl_write_ptr() { let file = tempfile().unwrap(); -- cgit v1.2.3