gpiocdev-uapi 0.7.0

// SPDX-FileCopyrightText: 2021 Kent Gibson <warthog618@gmail.com>
//
// SPDX-License-Identifier: Apache-2.0 OR MIT

use bitflags::bitflags;
use std::fs::File;
use std::os::unix::prelude::{AsRawFd, FromRawFd};

// common to ABI v1 and v2.
pub use super::common::*;

#[repr(u8)]
enum Ioctl {
    GetLineInfo = 2,
    GetLineHandle = 3,
    GetLineEvent = 4,
    GetLineValues = 8,
    SetLineValues = 9,
    SetConfig = 0xA,
    WatchLineInfo = 0xB,
}

/// Information about a certain GPIO line.
#[repr(C)]
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct LineInfo {
    /// The line offset on this GPIO device.
    /// This is the identifier used when requesting the line from the kernel.
    pub offset: Offset,

    /// The configuration flags for this line.
    pub flags: LineInfoFlags,

    /// The name of this GPIO line, such as the output pin of the line on the
    /// chip, a rail or a pin header name on a board, as specified by the GPIO
    /// chip.
    ///
    /// May be empty.
    pub name: Name,

    /// A functional name for the consumer of this GPIO line as set by
    /// whatever is using it.
    ///
    /// Will be empty if there is no current user but may
    /// also be empty if the consumer doesn't set a consumer name.
    pub consumer: Name,
}

bitflags! {
    /// Flags indicating the configuration of a line.
    #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
    pub struct LineInfoFlags: u32 {
        /// The line is in use and is not available for request.
        const USED = 1;

        /// The line is an output.
        const OUTPUT = 2;

        /// The line active state corresponds to a physical low.
        const ACTIVE_LOW = 4;

        /// The line is an open drain output.
        const OPEN_DRAIN = 8;

        /// The line is an open source output.
        const OPEN_SOURCE = 16;

        /// The line has pull-up bias enabled.
        const BIAS_PULL_UP = 32;

        /// The line has pull-down bias enabled.
        const BIAS_PULL_DOWN = 64;

        /// The line has bias disabled.
        const BIAS_DISABLED = 128;
    }
}

/// Get the publicly available information for a line.
///
/// This does not include the line value.
/// The line must be requested to access the value.
///
/// * 'cf' - The open gpiochip device file.
/// * `offset` - The offset of the line.
#[inline]
pub fn get_line_info(cf: &File, offset: Offset) -> Result<LineInfo> {
    let mut li = LineInfo {
        offset,
        ..Default::default()
    };
    // SAFETY: returned struct contains raw byte arrays and bitfields that are safe to decode.
    match unsafe { libc::ioctl(cf.as_raw_fd(), iorw!(Ioctl::GetLineInfo, LineInfo), &mut li) } {
        0 => Ok(li),
        _ => Err(Error::from_errno()),
    }
}

/// Add a watch on changes to the [`LineInfo`] for a line.
///
/// Returns the current state of that information.
/// This does not include the line value.
/// The line must be requested to access the value.
///
/// * 'cf' - The open gpiochip device file.
/// * `offset` - The offset of the line to watch.
#[inline]
pub fn watch_line_info(cf: &File, offset: Offset) -> Result<LineInfo> {
    let mut li = LineInfo {
        offset,
        ..Default::default()
    };
    // SAFETY: returned struct contains raw byte arrays and bitfields that are safe to decode.
    match unsafe {
        libc::ioctl(
            cf.as_raw_fd(),
            iorw!(Ioctl::WatchLineInfo, LineInfo),
            &mut li,
        )
    } {
        0 => Ok(li),
        _ => Err(Error::from_errno()),
    }
}

/// Information about a change in status of a GPIO line.
#[repr(C)]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct LineInfoChangeEvent {
    /// Updated line information.
    pub info: LineInfo,

    /// An estimate of time of status change occurrence, in nanoseconds.
    pub timestamp_ns: u64,

    /// The kind of change event (LineInfoChangeKind).
    pub kind: u32,

    /// Reserved for future use.
    #[doc(hidden)]
    pub padding: Padding<5>,
}

impl LineInfoChangeEvent {
    /// Read a LineInfoChangeEvent from a buffer.
    ///
    /// The buffer is assumed to have been populated by a read of the chip File,
    /// so the content is initialised.
    pub fn from_slice(d: &[u64]) -> Result<&LineInfoChangeEvent> {
        debug_assert!(std::mem::size_of::<LineInfoChangeEvent>() % 8 == 0);
        let len = d.len() * 8;
        if len < std::mem::size_of::<LineInfoChangeEvent>() {
            return Err(Error::from(UnderReadError::new(
                "LineInfoChangeEvent",
                std::mem::size_of::<LineInfoChangeEvent>(),
                len,
            )));
        }
        // SAFETY: returned struct contains raw byte arrays and bitfields that are safe to decode.
        let le = unsafe { &*(d as *const [u64] as *const LineInfoChangeEvent) };
        Ok(le)
    }

    /// The number of u64 words required to store a LineInfoChangeEvent.
    pub fn u64_size() -> usize {
        std::mem::size_of::<LineInfoChangeEvent>() / 8
    }
}

/// Information about a GPIO line handle request.
#[repr(C)]
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct HandleRequest {
    /// An array of requested lines, identified by offset on the associated GPIO device.
    pub offsets: Offsets,

    /// The requested flags for the requested GPIO lines.
    ///
    /// Note that even if multiple lines are requested, the same flags must be applicable
    /// to all of them, if you want lines with individual flags set, request them one by one.
    /// It is possible to select a batch of input or output lines, but they must all
    /// have the same characteristics, i.e. all inputs or all outputs, all active low etc.
    pub flags: HandleRequestFlags,

    /// If the [`HandleRequestFlags::OUTPUT`] is set for a requested line, this specifies the
    /// output value for each offset.  Should be 0 (*inactive*) or 1 (*active*).
    /// Anything other than 0 or 1 is interpreted as 1 (*active*).
    pub values: LineValues,

    /// A requested consumer label for the selected GPIO line(s) such as "*my-bitbanged-relay*".
    pub consumer: Name,

    /// The number of lines requested in this request, i.e. the number of valid fields in
    /// the `offsets` and `values` arrays.
    ///
    /// Set to 1 to request a single line.
    pub num_lines: u32,

    /// This field is only present for the underlying ioctl call and is only used internally.
    //
    // This is actually specified as an int in gpio.h, but that presents problems
    // as it is not fixed width.  It is usually i32, so that is what we go with here,
    // but that may cause issues on platforms.
    #[doc(hidden)]
    pub fd: i32,
}

bitflags! {
    /// Configuration flags for requested lines.
    ///
    /// Note that several of the flags, such as BIAS_PULL_UP and BIAS_PULL_DOWN are mutually
    /// exclusive.  The kernel will reject requests with flag combinations that do not make
    /// sense.
    #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
    pub struct HandleRequestFlags: u32 {
        /// Requests line as an input.
        const INPUT = 1;

        /// Requests line as an output.
        const OUTPUT = 2;

        /// Requests line as active low.
        const ACTIVE_LOW = 4;

        /// Requests line as open drain.
        const OPEN_DRAIN = 8;

        /// Requests line as open source.
        const OPEN_SOURCE = 16;

        /// Requests line with pull-up bias.
        const BIAS_PULL_UP = 32;

        /// Requests line with pull-down bias.
        const BIAS_PULL_DOWN = 64;

        /// Requests line with bias disabled.
        const BIAS_DISABLED = 128;
    }
}

/// Request a line or set of lines for exclusive access.
///
/// * 'cf' - The open gpiochip device file.
/// * `hr` - The line handle request.
#[inline]
pub fn get_line_handle(cf: &File, mut hr: HandleRequest) -> Result<File> {
    // SAFETY: hr is consumed and the returned file is drawn from the returned fd.
    unsafe {
        match libc::ioctl(
            cf.as_raw_fd(),
            iorw!(Ioctl::GetLineHandle, HandleRequest),
            &mut hr,
        ) {
            0 => Ok(File::from_raw_fd(hr.fd)),
            _ => Err(Error::from_errno()),
        }
    }
}

/// Updated configuration for an existing GPIO handle request.
#[repr(C)]
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct HandleConfig {
    /// Updated flags for the requested GPIO lines.
    ///
    /// The flags will be applied to all lines in the existing request.
    pub flags: HandleRequestFlags,

    /// If the [`HandleRequestFlags::OUTPUT`] is set in flags, this specifies the
    /// output value, should be 0 (*inactive*) or 1 (*active*).
    ///
    /// All other values are interpreted as active.
    pub values: LineValues,

    /// Reserved for future use and should be zero filled.
    #[doc(hidden)]
    pub padding: Padding<4>,
}

/// Update the configuration of an existing handle or event request.
///
/// * `lf` - The request file returned by [`get_line_handle`].
/// * `hc` - The configuration to be applied.
#[inline]
pub fn set_line_config(lf: &File, hc: HandleConfig) -> Result<()> {
    // SAFETY: hc is consumed.
    unsafe {
        match libc::ioctl(lf.as_raw_fd(), iorw!(Ioctl::SetConfig, HandleConfig), &hc) {
            0 => Ok(()),
            _ => Err(Error::from_errno()),
        }
    }
}

/// The logical values of the requested lines.
///
/// Values are stored as u8, as that is what the uAPI specifies.
///
/// 0 is *inactive* with 1 and all other values taken as *active*.
///
/// Values are stored in the same order as the offsets in the [`HandleRequest.offsets`].
///
/// Values for input lines are ignored.
///
/// [`HandleRequest.offsets`]: struct@HandleRequest
#[repr(C)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct LineValues(pub [u8; 64usize]);

impl LineValues {
    /// Create values from a slice.
    ///
    /// The values are in the same order as [`HandleRequest.offsets`].
    ///
    /// [`HandleRequest.offsets`]: struct@HandleRequest
    pub fn from_slice(s: &[u8]) -> Self {
        let mut n: LineValues = Default::default();
        for (src, dst) in s.iter().zip(n.0.iter_mut()) {
            *dst = *src;
        }
        n
    }

    /// Copy values from an iterable list - in order of requested offsets.
    pub fn copy_from_slice(&mut self, s: &[u8]) {
        let extent = std::cmp::min(64usize, s.len());
        self.0[0..extent].copy_from_slice(s);
    }

    /// Return the value of a line.
    ///
    /// Note that the [`LineValues`] need to be populated via a call to [`get_line_values`]
    /// to get values from the underlying hardware.
    ///
    /// * `idx` - The index into the [`HandleRequest.offsets`] for the line of interest.
    ///
    /// [`HandleRequest.offsets`]: struct@HandleRequest
    #[inline]
    pub fn get(&self, idx: usize) -> u8 {
        self.0[idx]
    }

    /// Set the value of a line.
    ///
    /// Note that this is not applied to hardware until these values are passed to
    /// [`set_line_values`].
    ///
    /// * `idx` - The index into the [`HandleRequest.offsets`] for the line of interest.
    /// * `value` - The logical state of the line to be set.
    ///
    /// [`HandleRequest.offsets`]: struct@HandleRequest
    #[inline]
    pub fn set(&mut self, idx: usize, value: u8) {
        self.0[idx] = value;
    }
}
impl Default for LineValues {
    fn default() -> Self {
        LineValues([0; 64])
    }
}

/// Read the values of requested lines.
///
/// * `lf` - The request file returned by [`get_line_handle`] or [`get_line_event`].
/// * `vals` - The line values to be populated.
#[inline]
pub fn get_line_values(lf: &File, vals: &mut LineValues) -> Result<()> {
    // SAFETY: vals are raw integers that are safe to decode.
    match unsafe {
        libc::ioctl(
            lf.as_raw_fd(),
            iorw!(Ioctl::GetLineValues, LineValues),
            vals.0.as_mut_ptr(),
        )
    } {
        0 => Ok(()),
        _ => Err(Error::from_errno()),
    }
}

/// Set the values of requested lines.
///
/// * `lf` - The request file returned by [`get_line_handle`].
/// * `vals` - The line values to be set.
#[inline]
pub fn set_line_values(lf: &File, vals: &LineValues) -> Result<()> {
    // SAFETY: vals is not modified.
    match unsafe {
        libc::ioctl(
            lf.as_raw_fd(),
            iorw!(Ioctl::SetLineValues, LineValues),
            vals.0.as_ptr(),
        )
    } {
        0 => Ok(()),
        _ => Err(Error::from_errno()),
    }
}

/// Information about a GPIO event request.
#[repr(C)]
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct EventRequest {
    /// The line to request edge events from, identified by its offset
    /// on the associated GPIO device.
    pub offset: Offset,

    /// The requested handle flags for the GPIO line.
    pub handleflags: HandleRequestFlags,

    /// The requested event flags for the GPIO line.
    pub eventflags: EventRequestFlags,

    /// A requested consumer label for the selected GPIO line(s) such as "*my-listener*".
    pub consumer: Name,

    /// This field is only present for the underlying ioctl call and is only used internally.
    ///
    // This is actually specified as an int in gpio.h, but that presents problems
    // as it is not fixed width.  It is usually i32, so that is what we go with here,
    // though this may cause issues on platforms with a differently sized int.
    #[doc(hidden)]
    pub fd: i32,
}

bitflags! {
    /// Additional configuration flags for event requests.
    #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
    pub struct EventRequestFlags: u32 {
        /// Report rising edge events on the requested line.
        const RISING_EDGE = 1;

        /// Report falling edge events on the requested line.
        const FALLING_EDGE = 2;

        /// Report both rising and falling edge events on the requested line.
        const BOTH_EDGES = Self::RISING_EDGE.bits() | Self::FALLING_EDGE.bits();
    }
}

/// Request a line with edge detection enabled.
///
/// Detected events can be read from the returned file.
///
/// * 'cf' - The open gpiochip device file.
/// * `er` - The line event request.
#[inline]
pub fn get_line_event(cf: &File, mut er: EventRequest) -> Result<File> {
    // SAFETY: er is consumed and the returned file is drawn from the returned fd.
    unsafe {
        match libc::ioctl(
            cf.as_raw_fd(),
            iorw!(Ioctl::GetLineEvent, EventRequest),
            &mut er,
        ) {
            0 => Ok(File::from_raw_fd(er.fd)),
            _ => Err(Error::from_errno()),
        }
    }
}

/// Information about an edge event on a requested line.
#[repr(C)]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct LineEdgeEvent {
    /// The best estimate of time of event occurrence, in nanoseconds.
    pub timestamp_ns: u64,
    /// The kind of line event. (LineEdgeEventKind)
    pub kind: u32,
}

impl LineEdgeEvent {
    /// Read a LineEdgeEvent from a buffer.
    ///
    /// The buffer is assumed to have been populated by a read of the line request File,
    /// so the content is initialised.
    pub fn from_slice(d: &[u64]) -> Result<&LineEdgeEvent> {
        debug_assert!(std::mem::size_of::<LineEdgeEvent>() % 8 == 0);
        let len = d.len() * 8;
        if len < std::mem::size_of::<LineEdgeEvent>() {
            return Err(Error::from(UnderReadError::new(
                "LineEdgeEvent",
                std::mem::size_of::<LineEdgeEvent>(),
                len,
            )));
        }
        // SAFETY: returned struct contains raw byte arrays and bitfields that are safe to decode.
        let le = unsafe { &*(d as *const [u64] as *const LineEdgeEvent) };
        Ok(le)
    }

    /// The number of u64 words required to store a LineEdgeEvent.
    pub fn u64_size() -> usize {
        std::mem::size_of::<LineEdgeEvent>() / 8
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    mod line_info {
        use super::LineInfo;

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<LineInfo>(),
                72usize,
                concat!("Size of: ", stringify!(LineInfo))
            );
        }
    }

    mod line_info_changed {
        use super::LineInfoChangeEvent;

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<LineInfoChangeEvent>(),
                104usize,
                concat!("Size of: ", stringify!(LineInfoChangeEvent))
            );
        }
    }

    mod handle_request {
        use super::HandleRequest;

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<HandleRequest>(),
                364usize,
                concat!("Size of: ", stringify!(HandleRequest))
            );
        }
    }

    mod handle_config {
        use super::HandleConfig;

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<HandleConfig>(),
                84usize,
                concat!("Size of: ", stringify!(HandleConfig))
            );
        }
    }

    mod event_request {
        use super::EventRequest;

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<EventRequest>(),
                48usize,
                concat!("Size of: ", stringify!(EventRequest))
            );
        }
    }

    mod line_event {
        use super::LineEdgeEvent;

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<LineEdgeEvent>(),
                16usize,
                concat!("Size of: ", stringify!(LineEdgeEvent))
            );
        }
    }

    mod line_values {
        use super::LineValues;

        #[test]
        fn get() {
            let mut a = LineValues::default();
            for idx in [0, 2] {
                assert_eq!(a.0[idx], 0, "idx: {idx}");
                assert_eq!(a.get(idx), 0, "idx: {idx}");
                a.0[idx] = 1;
                assert_eq!(a.get(idx), 1, "idx: {idx}");
                a.0[idx] = 42;
                assert_eq!(a.get(idx), 42, "idx: {idx}");
            }
        }

        #[test]
        fn set() {
            let mut a = LineValues::default();
            for idx in [0, 2] {
                a.set(idx, 0);
                assert_eq!(a.0[idx], 0, "idx: {idx}");
                a.set(idx, 1);
                assert_eq!(a.0[idx], 1, "idx: {idx}");
                a.set(idx, 42);
                assert_eq!(a.0[idx], 42, "idx: {idx}");
            }
        }

        #[test]
        fn size() {
            assert_eq!(
                std::mem::size_of::<LineValues>(),
                64usize,
                concat!("Size of: ", stringify!(LineValues))
            );
        }
    }
}