From 1b6a04ca5504955c571d1c97504fb45ea0befee4 Mon Sep 17 00:00:00 2001 From: Valentin Popov Date: Mon, 8 Jan 2024 01:21:28 +0400 Subject: Initial vendor packages Signed-off-by: Valentin Popov --- vendor/rustix/src/ioctl/mod.rs | 357 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 357 insertions(+) create mode 100644 vendor/rustix/src/ioctl/mod.rs (limited to 'vendor/rustix/src/ioctl/mod.rs') diff --git a/vendor/rustix/src/ioctl/mod.rs b/vendor/rustix/src/ioctl/mod.rs new file mode 100644 index 0000000..494cdc8 --- /dev/null +++ b/vendor/rustix/src/ioctl/mod.rs @@ -0,0 +1,357 @@ +//! Unsafe `ioctl` API. +//! +//! Unix systems expose a number of `ioctl`'s. `ioctl`s have been adopted as a +//! general purpose system call for making calls into the kernel. In addition +//! to the wide variety of system calls that are included by default in the +//! kernel, many drivers expose their own `ioctl`'s for controlling their +//! behavior, some of which are proprietary. Therefore it is impossible to make +//! a safe interface for every `ioctl` call, as they all have wildly varying +//! semantics. +//! +//! This module provides an unsafe interface to write your own `ioctl` API. To +//! start, create a type that implements [`Ioctl`]. Then, pass it to [`ioctl`] +//! to make the `ioctl` call. + +#![allow(unsafe_code)] + +use crate::backend::c; +use crate::fd::{AsFd, BorrowedFd}; +use crate::io::Result; + +#[cfg(any(linux_kernel, bsd))] +use core::mem; + +pub use patterns::*; + +mod patterns; + +#[cfg(linux_kernel)] +mod linux; + +#[cfg(bsd)] +mod bsd; + +#[cfg(linux_kernel)] +use linux as platform; + +#[cfg(bsd)] +use bsd as platform; + +/// Perform an `ioctl` call. +/// +/// `ioctl` was originally intended to act as a way of modifying the behavior +/// of files, but has since been adopted as a general purpose system call for +/// making calls into the kernel. In addition to the default calls exposed by +/// generic file descriptors, many drivers expose their own `ioctl` calls for +/// controlling their behavior, some of which are proprietary. +/// +/// This crate exposes many other `ioctl` interfaces with safe and idiomatic +/// wrappers, like [`ioctl_fionbio`] and [`ioctl_fionread`]. It is recommended +/// to use those instead of this function, as they are safer and more +/// idiomatic. For other cases, implement the [`Ioctl`] API and pass it to this +/// function. +/// +/// See documentation for [`Ioctl`] for more information. +/// +/// [`ioctl_fionbio`]: crate::io::ioctl_fionbio +/// [`ioctl_fionread`]: crate::io::ioctl_fionread +/// +/// # Safety +/// +/// While [`Ioctl`] takes much of the unsafety out of `ioctl` calls, it is +/// still unsafe to call this code with arbitrary device drivers, as it is up +/// to the device driver to implement the `ioctl` call correctly. It is on the +/// onus of the protocol between the user and the driver to ensure that the +/// `ioctl` call is safe to make. +/// +/// # References +/// - [Linux] +/// - [Winsock] +/// - [FreeBSD] +/// - [NetBSD] +/// - [OpenBSD] +/// - [Apple] +/// - [Solaris] +/// - [illumos] +/// +/// [Linux]: https://man7.org/linux/man-pages/man2/ioctl.2.html +/// [Winsock]: https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-ioctlsocket +/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=ioctl&sektion=2 +/// [NetBSD]: https://man.netbsd.org/ioctl.2 +/// [OpenBSD]: https://man.openbsd.org/ioctl.2 +/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/ioctl.2.html +/// [Solaris]: https://docs.oracle.com/cd/E23824_01/html/821-1463/ioctl-2.html +/// [illumos]: https://illumos.org/man/2/ioctl +#[inline] +pub unsafe fn ioctl(fd: F, mut ioctl: I) -> Result { + let fd = fd.as_fd(); + let request = I::OPCODE.raw(); + let arg = ioctl.as_ptr(); + + // SAFETY: The variant of `Ioctl` asserts that this is a valid IOCTL call + // to make. + let output = if I::IS_MUTATING { + _ioctl(fd, request, arg)? + } else { + _ioctl_readonly(fd, request, arg)? + }; + + // SAFETY: The variant of `Ioctl` asserts that this is a valid pointer to + // the output data. + I::output_from_ptr(output, arg) +} + +unsafe fn _ioctl( + fd: BorrowedFd<'_>, + request: RawOpcode, + arg: *mut c::c_void, +) -> Result { + crate::backend::io::syscalls::ioctl(fd, request, arg) +} + +unsafe fn _ioctl_readonly( + fd: BorrowedFd<'_>, + request: RawOpcode, + arg: *mut c::c_void, +) -> Result { + crate::backend::io::syscalls::ioctl_readonly(fd, request, arg) +} + +/// A trait defining the properties of an `ioctl` command. +/// +/// Objects implementing this trait can be passed to [`ioctl`] to make an +/// `ioctl` call. The contents of the object represent the inputs to the +/// `ioctl` call. The inputs must be convertible to a pointer through the +/// `as_ptr` method. In most cases, this involves either casting a number to a +/// pointer, or creating a pointer to the actual data. The latter case is +/// necessary for `ioctl` calls that modify userspace data. +/// +/// # Safety +/// +/// This trait is unsafe to implement because it is impossible to guarantee +/// that the `ioctl` call is safe. The `ioctl` call may be proprietary, or it +/// may be unsafe to call in certain circumstances. +/// +/// By implementing this trait, you guarantee that: +/// +/// - The `ioctl` call expects the input provided by `as_ptr` and produces the +/// output as indicated by `output`. +/// - That `output_from_ptr` can safely take the pointer from `as_ptr` and cast +/// it to the correct type, *only* after the `ioctl` call. +/// - That `OPCODE` uniquely identifies the `ioctl` call. +/// - That, for whatever platforms you are targeting, the `ioctl` call is safe +/// to make. +/// - If `IS_MUTATING` is false, that no userspace data will be modified by the +/// `ioctl` call. +pub unsafe trait Ioctl { + /// The type of the output data. + /// + /// Given a pointer, one should be able to construct an instance of this + /// type. + type Output; + + /// The opcode used by this `ioctl` command. + /// + /// There are different types of opcode depending on the operation. See + /// documentation for the [`Opcode`] struct for more information. + const OPCODE: Opcode; + + /// Does the `ioctl` mutate any data in the userspace? + /// + /// If the `ioctl` call does not mutate any data in the userspace, then + /// making this `false` enables optimizations that can make the call + /// faster. When in doubt, set this to `true`. + /// + /// # Safety + /// + /// This should only be set to `false` if the `ioctl` call does not mutate + /// any data in the userspace. Undefined behavior may occur if this is set + /// to `false` when it should be `true`. + const IS_MUTATING: bool; + + /// Get a pointer to the data to be passed to the `ioctl` command. + /// + /// See trait-level documentation for more information. + fn as_ptr(&mut self) -> *mut c::c_void; + + /// Cast the output data to the correct type. + /// + /// # Safety + /// + /// The `extract_output` value must be the resulting value after a + /// successful `ioctl` call, and `out` is the direct return value of an + /// `ioctl` call that did not fail. In this case `extract_output` is the + /// pointer that was passed to the `ioctl` call. + unsafe fn output_from_ptr( + out: IoctlOutput, + extract_output: *mut c::c_void, + ) -> Result; +} + +/// The opcode used by an `Ioctl`. +#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Opcode { + /// The raw opcode. + raw: RawOpcode, +} + +impl Opcode { + /// Create a new old `Opcode` from a raw opcode. + /// + /// Rather than being a composition of several attributes, old opcodes are + /// just numbers. In general most drivers follow stricter conventions, but + /// older drivers may still use this strategy. + #[inline] + pub const fn old(raw: RawOpcode) -> Self { + Self { raw } + } + + /// Create a new opcode from a direction, group, number, and size. + /// + /// This corresponds to the C macro `_IOC(direction, group, number, size)` + #[cfg(any(linux_kernel, bsd))] + #[inline] + pub const fn from_components( + direction: Direction, + group: u8, + number: u8, + data_size: usize, + ) -> Self { + if data_size > RawOpcode::MAX as usize { + panic!("data size is too large"); + } + + Self::old(platform::compose_opcode( + direction, + group as RawOpcode, + number as RawOpcode, + data_size as RawOpcode, + )) + } + + /// Create a new non-mutating opcode from a group, a number, and the type + /// of data. + /// + /// This corresponds to the C macro `_IO(group, number)` when `T` is zero + /// sized. + #[cfg(any(linux_kernel, bsd))] + #[inline] + pub const fn none(group: u8, number: u8) -> Self { + Self::from_components(Direction::None, group, number, mem::size_of::()) + } + + /// Create a new reading opcode from a group, a number and the type of + /// data. + /// + /// This corresponds to the C macro `_IOR(group, number, T)`. + #[cfg(any(linux_kernel, bsd))] + #[inline] + pub const fn read(group: u8, number: u8) -> Self { + Self::from_components(Direction::Read, group, number, mem::size_of::()) + } + + /// Create a new writing opcode from a group, a number and the type of + /// data. + /// + /// This corresponds to the C macro `_IOW(group, number, T)`. + #[cfg(any(linux_kernel, bsd))] + #[inline] + pub const fn write(group: u8, number: u8) -> Self { + Self::from_components(Direction::Write, group, number, mem::size_of::()) + } + + /// Create a new reading and writing opcode from a group, a number and the + /// type of data. + /// + /// This corresponds to the C macro `_IOWR(group, number, T)`. + #[cfg(any(linux_kernel, bsd))] + #[inline] + pub const fn read_write(group: u8, number: u8) -> Self { + Self::from_components(Direction::ReadWrite, group, number, mem::size_of::()) + } + + /// Get the raw opcode. + #[inline] + pub fn raw(self) -> RawOpcode { + self.raw + } +} + +/// The direction that an `ioctl` is going. +/// +/// Note that this is relative to userspace. `Read` means reading data from the +/// kernel, and write means the kernel writing data to userspace. +#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum Direction { + /// None of the above. + None, + + /// Read data from the kernel. + Read, + + /// Write data to the kernel. + Write, + + /// Read and write data to the kernel. + ReadWrite, +} + +/// The type used by the `ioctl` to signify the output. +pub type IoctlOutput = c::c_int; + +/// The type used by the `ioctl` to signify the command. +pub type RawOpcode = _RawOpcode; + +// Under raw Linux, this is an `unsigned int`. +#[cfg(linux_raw)] +type _RawOpcode = c::c_uint; + +// On libc Linux with GNU libc or uclibc, this is an `unsigned long`. +#[cfg(all( + not(linux_raw), + target_os = "linux", + any(target_env = "gnu", target_env = "uclibc") +))] +type _RawOpcode = c::c_ulong; + +// Musl uses `c_int`. +#[cfg(all( + not(linux_raw), + target_os = "linux", + not(target_env = "gnu"), + not(target_env = "uclibc") +))] +type _RawOpcode = c::c_int; + +// Android uses `c_int`. +#[cfg(all(not(linux_raw), target_os = "android"))] +type _RawOpcode = c::c_int; + +// BSD, Haiku, Hurd, Redox, and Vita use `unsigned long`. +#[cfg(any( + bsd, + target_os = "redox", + target_os = "haiku", + target_os = "hurd", + target_os = "vita" +))] +type _RawOpcode = c::c_ulong; + +// AIX, Emscripten, Fuchsia, Solaris, and WASI use a `int`. +#[cfg(any( + solarish, + target_os = "aix", + target_os = "fuchsia", + target_os = "emscripten", + target_os = "wasi", + target_os = "nto" +))] +type _RawOpcode = c::c_int; + +// ESP-IDF uses a `c_uint`. +#[cfg(target_os = "espidf")] +type _RawOpcode = c::c_uint; + +// Windows has `ioctlsocket`, which uses `i32`. +#[cfg(windows)] +type _RawOpcode = i32; -- cgit v1.2.3