hid-decode 0.1.0

//! # HID report descriptor decoding utilities
//!
//! This library can perform text decoding of USB HID report descriptors.
//!
//! It does not perform stateful functional decoding, so it can't (yet)
//! determine the size and layout of HID reports.
//!
//! See [Device Class Definition for Human Interface Devices](https://www.usb.org/document-library/device-class-definition-hid-111)
//! for a detailed description of HID report descriptors.
//!
//! # Example
//! ```rust
//! # // This descriptor was generated by an example in the `hid-descriptor` crate sources.
//! # static GAMEPAD_DESCRIPTOR: &[u8] = include_bytes!("../tests/gamepad.bin");
//! let mut output = Vec::new();
//! hid_decode::decode(&mut output, GAMEPAD_DESCRIPTOR.iter().copied()).expect("write error");
//! let output = String::try_from(output).expect("non-UTF8 output");
//! assert_eq!(
//!     output.lines().collect::<Vec<_>>(),
//!     [
//!         "Usage Page: GenericDesktop",
//!         "Usage: Gamepad",
//!         "Collection: Application",
//!         "Usage Page: Button",
//!         "Usage Minimum: 1",
//!         "Usage Maximum: 8",
//!         "Logical Minimum: 0",
//!         "Logical Maximum: 1",
//!         "Report Size: 1",
//!         "Report Count: 8",
//!         "Input: Data Variable Absolute No-Wrap Linear Preferred-State No-Null-Position Bit-Field",
//!         "EndCollection",
//!     ]
//! );
//! ```

#![warn(clippy::print_stderr, clippy::print_stdout, clippy::dbg_macro)]
#![warn(clippy::todo)]
#![warn(missing_docs)]

use std::io::Write;

use hid_types::encoding::{Size, TagTypeSize, TypeBits};
use hid_types::hid::{CollectionType, InputFlags, IoFlags, OutputFeatureFlags, Unit};
use hid_types::id::tag::{GlobalItem, LocalItem, MainItem};
use hid_types::id::usage::UsagePage;
use hid_types::item::usage::{ExtendedUsage, Usage};
use hid_types::item::{Global, Item, Local, LongItem, Main};

/// Decode HID descriptor bytes as text.
///
/// The output text will be written to the `writer`.
pub fn decode<W, I>(writer: W, bytes: I) -> std::io::Result<()>
where
    W: Write,
    I: IntoIterator<Item = u8>,
{
    decode_with_options(writer, bytes, Verbosity::default())
}

/// Decode HID descriptor bytes as text.
///
/// The output text will be written to the `writer`.
/// Use `verbosity` to select the level of detail.
pub fn decode_with_options<W, I>(
    mut writer: W,
    bytes: I,
    verbosity: Verbosity,
) -> std::io::Result<()>
where
    W: Write,
    I: IntoIterator<Item = u8>,
{
    let mut iter = bytes.into_iter();
    let mut decoder = DecoderContext::new(verbosity);
    loop {
        match decoder.decode_one(&mut iter) {
            Ok(Some(item)) => {
                if decoder.verbosity.display_tag_type {
                    write!(writer, "{:9}", item.type_note())?;
                }
                writeln!(writer, "{item}")?;
            }
            Ok(None) => break,
            Err(_e) => return Err(std::io::Error::other("decoding failed")),
        }
    }
    Ok(())
}

/// Configuration for decoding descriptors to text.
#[derive(Clone, Default)]
pub struct Verbosity {
    /// Display the item tag types, i.e. Main, Global, Local.
    pub display_tag_type: bool,
}

/// HID Decoder state.
#[derive(Default)]
pub struct DecoderContext {
    /// Decoder verbosity.
    verbosity: Verbosity,
    /// The current usage page.
    usage_page: Option<UsagePage>,
}

impl DecoderContext {
    fn new(verbosity: Verbosity) -> Self {
        Self {
            verbosity,
            ..Default::default()
        }
    }

    /// Decode one item from its encoded bytes.
    ///
    /// This will consume a variable number of bytes from the input iterator.
    pub fn decode_one<Iter>(&mut self, iter: &mut Iter) -> Result<Option<Item>, LengthError>
    where
        Iter: Iterator<Item = u8>,
    {
        let Some(tag) = iter.next() else {
            // End of input iterator
            return Ok(None);
        };
        let tag = TagTypeSize::from_bits(tag);

        let more = match tag.size() {
            Size::Short(size_bytes) => {
                let iter_remaining = iter.take(size_bytes);
                iter_remaining.collect::<Vec<_>>()
            }
            Size::Long => {
                let (Some(size), Some(tag)) = (iter.next(), iter.next()) else {
                    return Err(LengthError::Truncated);
                };
                let iter_payload = iter.take(usize::from(size));
                let data = iter_payload.collect::<Vec<_>>();
                let item = Item::Long(LongItem { tag, data });
                return Ok(Some(item));
            }
        };

        match tag.ty() {
            TypeBits::Main => {
                let item = MainItem::from(tag.tag());
                let decoded = match item {
                    MainItem::Input => {
                        let data = slice_to_u32(&more)?;
                        let flags = InputFlags(IoFlags::from(data));
                        Main::Input(flags)
                    }
                    MainItem::Output => {
                        let data = slice_to_u32(&more)?;
                        let flags = OutputFeatureFlags(IoFlags::from(data));
                        Main::Output(flags)
                    }
                    MainItem::Feature => {
                        let data = slice_to_u32(&more)?;
                        let flags = OutputFeatureFlags(IoFlags::from(data));
                        Main::Feature(flags)
                    }
                    MainItem::Collection => {
                        assert_eq!(more.len(), 1);
                        let coll_type = CollectionType::from_integer(more[0]);
                        Main::Collection(coll_type)
                    }
                    MainItem::EndCollection => {
                        assert!(more.is_empty());
                        Main::EndCollection
                    }
                    MainItem::Reserved => Main::Reserved(tag.tag()),
                };
                Ok(Some(Item::Main(decoded)))
            }
            TypeBits::Global => {
                let item = GlobalItem::from(tag.tag());
                let decoded = match item {
                    GlobalItem::UsagePage => {
                        let page_number = slice_to_u16(&more)?;
                        let usage_page = UsagePage::from_integer(page_number);
                        self.usage_page = Some(usage_page);
                        Global::UsagePage(usage_page)
                    }
                    GlobalItem::LogicalMinimum => {
                        let num = slice_to_i32(&more)?;
                        Global::LogicalMinimum(num)
                    }
                    GlobalItem::LogicalMaximum => {
                        let num = slice_to_i32(&more)?;
                        Global::LogicalMaximum(num)
                    }
                    GlobalItem::PhysicalMinimum => {
                        let num = slice_to_i32(&more)?;
                        Global::PhysicalMinimum(num)
                    }
                    GlobalItem::PhysicalMaximum => {
                        let num = slice_to_i32(&more)?;
                        Global::PhysicalMaximum(num)
                    }
                    GlobalItem::UnitExponent => {
                        let num = slice_to_i32(&more)?;
                        Global::UnitExponent(num)
                    }
                    GlobalItem::ReportSize => {
                        let num = slice_to_u32(&more)?;
                        Global::ReportSize(num)
                    }
                    GlobalItem::ReportId => {
                        let num = slice_to_u32(&more)?;
                        Global::ReportId(num)
                    }
                    GlobalItem::ReportCount => {
                        let num = slice_to_u32(&more)?;
                        Global::ReportCount(num)
                    }
                    GlobalItem::Unit => {
                        let num = slice_to_u32(&more)?;
                        let unit = Unit::from_integer(num);
                        Global::Unit(unit)
                    }
                    GlobalItem::Push => Global::Push,
                    GlobalItem::Pop => Global::Pop,
                    GlobalItem::Reserved => Global::Reserved(tag.tag()),
                };
                Ok(Some(Item::Global(decoded)))
            }
            TypeBits::Local => {
                let item = LocalItem::from(tag.tag());
                let decoded = match item {
                    LocalItem::Usage => {
                        // If the payload is 1 or 2 bytes, we use the
                        // existing page number. If the payload is 4 bytes, it
                        // contains both the page number and page id.
                        match slice_to_u16(&more) {
                            Ok(page_id) => match self.usage_page {
                                Some(page) => Local::Usage(Usage::new(page, page_id)),

                                None => Local::Usage(Usage::without_page(page_id)),
                            },
                            Err(LengthError::DataTooBig) => {
                                let value = slice_to_u32(&more)?;
                                Local::ExtendedUsage(ExtendedUsage::from_u32(value))
                            }
                            Err(e) => return Err(e),
                        }
                    }
                    LocalItem::UsageMinimum => {
                        let num = slice_to_u32(&more)?;
                        Local::UsageMinimum(num)
                    }
                    LocalItem::UsageMaximum => {
                        let num = slice_to_u32(&more)?;
                        Local::UsageMaximum(num)
                    }
                    LocalItem::DesignatorIndex => {
                        let num = slice_to_u32(&more)?;
                        Local::DesignatorIndex(num)
                    }
                    LocalItem::DesignatorMinimum => {
                        let num = slice_to_u32(&more)?;
                        Local::DesignatorMinimum(num)
                    }
                    LocalItem::DesignatorMaximum => {
                        let num = slice_to_u32(&more)?;
                        Local::DesignatorMaximum(num)
                    }
                    LocalItem::StringIndex => {
                        let num = slice_to_u32(&more)?;
                        Local::StringIndex(num)
                    }
                    LocalItem::StringMinimum => {
                        let num = slice_to_u32(&more)?;
                        Local::StringMinimum(num)
                    }
                    LocalItem::StringMaximum => {
                        let num = slice_to_u32(&more)?;
                        Local::StringMaximum(num)
                    }
                    LocalItem::Delimiter => {
                        let num = slice_to_u8(&more)?;
                        let param = match num {
                            0 => false,
                            1 => true,
                            _ => return Err(LengthError::DataTooBig),
                        };
                        Local::Delimiter(param)
                    }
                    LocalItem::Reserved => Local::Reserved(tag.tag()),
                };
                Ok(Some(Item::Local(decoded)))
            }
            TypeBits::Reserved => {
                let decoded = Item::Reserved(tag.ty().into_bits());
                Ok(Some(decoded))
            }
        }
    }
}

/// An error that resulted from improper item encoding.
#[derive(Clone, Debug)]
pub enum LengthError {
    /// The data length was too big for this item.
    DataTooBig,
    /// A data length of zero is not allowed in this item.
    ZeroLength,
    /// Ran out of bytes trying to decode this item.
    Truncated,
}

fn slice_to_u8(slice: &[u8]) -> Result<u8, LengthError> {
    match slice.len() {
        0 => Err(LengthError::ZeroLength),
        1 => Ok(slice[0]),
        _ => Err(LengthError::DataTooBig),
    }
}

fn slice_to_u16(slice: &[u8]) -> Result<u16, LengthError> {
    match slice.len() {
        0 => Err(LengthError::ZeroLength),
        1 => Ok(slice[0] as u16),
        2 => {
            let ar: &[u8; 2] = slice.as_array().unwrap();
            Ok(u16::from_le_bytes(*ar))
        }
        _ => Err(LengthError::DataTooBig),
    }
}

fn slice_to_u32(slice: &[u8]) -> Result<u32, LengthError> {
    match slice.len() {
        0 => Err(LengthError::ZeroLength),
        1 => Ok(slice[0] as u32),
        2 => {
            let ar: &[u8; 2] = slice.as_array().unwrap();
            let value = u16::from_le_bytes(*ar);
            Ok(value as u32)
        }
        3 => Err(LengthError::Truncated),
        4 => {
            let ar: &[u8; 4] = slice.as_array().unwrap();
            Ok(u32::from_le_bytes(*ar))
        }
        _ => Err(LengthError::DataTooBig),
    }
}

fn slice_to_i32(slice: &[u8]) -> Result<i32, LengthError> {
    match slice.len() {
        0 => Err(LengthError::ZeroLength),
        1 => Ok(slice[0] as i8 as i32),
        2 => {
            let ar: &[u8; 2] = slice.as_array().unwrap();
            let value = i16::from_le_bytes(*ar);
            Ok(value as i32)
        }
        3 => Err(LengthError::Truncated),
        4 => {
            let ar: &[u8; 4] = slice.as_array().unwrap();
            Ok(i32::from_le_bytes(*ar))
        }
        _ => Err(LengthError::DataTooBig),
    }
}

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

    #[test]
    fn test_integer_decoding() {
        assert_eq!(slice_to_u8(&[0xFF]).unwrap(), 0xFF);
        slice_to_u8(&[]).unwrap_err();
        slice_to_u8(&[0xFF, 0xFF]).unwrap_err();

        assert_eq!(slice_to_u16(&[0xFF]).unwrap(), 0xFF);
        assert_eq!(slice_to_u16(&[0xFF, 0xFF]).unwrap(), 0xFFFF);
        assert_eq!(slice_to_u16(&[1, 2]).unwrap(), 0x0201);
        slice_to_u16(&[]).unwrap_err();
        slice_to_u16(&[0xFF; 3]).unwrap_err();
        slice_to_u16(&[0xFF; 4]).unwrap_err();

        assert_eq!(slice_to_u32(&[0xFF]).unwrap(), 0xFF);
        assert_eq!(slice_to_u32(&[0xFF, 0xFF]).unwrap(), 0xFFFF);
        assert_eq!(slice_to_u32(&[1, 2]).unwrap(), 0x0201);
        assert_eq!(slice_to_u32(&[0xFF; 4]).unwrap(), 0xFFFFFFFF);
        assert_eq!(slice_to_u32(&[1, 2, 3, 4]).unwrap(), 0x04030201);
        slice_to_u32(&[]).unwrap_err();
        slice_to_u32(&[0xFF; 3]).unwrap_err();
        slice_to_u32(&[0xFF; 5]).unwrap_err();

        assert_eq!(slice_to_i32(&[0]).unwrap(), 0);
        assert_eq!(slice_to_i32(&[0, 0]).unwrap(), 0);
        assert_eq!(slice_to_i32(&[1, 2]).unwrap(), 0x0201);
        assert_eq!(slice_to_i32(&[0; 4]).unwrap(), 0);
        assert_eq!(slice_to_i32(&[1, 2, 3, 4]).unwrap(), 0x04030201);
        assert_eq!(slice_to_i32(&[0xFF]).unwrap(), -1);
        assert_eq!(slice_to_i32(&[0xFF, 0xFF]).unwrap(), -1);
        assert_eq!(slice_to_i32(&[0xFF; 4]).unwrap(), -1);
        slice_to_i32(&[]).unwrap_err();
        slice_to_i32(&[0xFF; 3]).unwrap_err();
        slice_to_i32(&[0xFF; 5]).unwrap_err();
    }
}