initial commit

Author: npmccallum

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3
+    groups:
+      all-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+name: ci
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  deny:
+    name: cargo deny
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v5
+
+      - name: cargo deny
+        uses: EmbarkStudios/cargo-deny-action@v2
+
+  fmt:
+    name: cargo fmt
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v5
+
+      - name: install rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+          components: rustfmt
+
+      - name: cache rust toolchain
+        uses: Swatinem/rust-cache@v2
+
+      - name: cargo fmt
+        run: cargo fmt --all -- --check
+
+  clippy:
+    name: cargo clippy
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust: [stable, beta, nightly, 1.80.0]  # stable, beta, nightly, and MSRV
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v5
+
+      - name: install rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+          components: clippy
+
+      - name: cache rust toolchain
+        uses: Swatinem/rust-cache@v2
+
+      - name: cargo clippy
+        run: cargo clippy --bins -- -D warnings
+
+  build:
+    name: cargo build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust: [stable, beta, nightly, 1.80.0]  # stable, beta, nightly, and MSRV
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v5
+
+      - name: install rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+
+      - name: cache rust toolchain
+        uses: Swatinem/rust-cache@v2
+
+      - name: cargo build
+        run: cargo build
+
+
+  release:
+    name: cargo build --release
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        rust: [stable, beta, nightly, 1.80.0]  # stable, beta, nightly, and MSRV
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v5
+
+      - name: install rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.rust }}
+
+      - name: cache rust toolchain
+        uses: Swatinem/rust-cache@v2
+
+      - name: cargo build --release
+        run: cargo build --release

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: release
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout code
+        uses: actions/checkout@v5
+
+      - name: install rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: x86_64-unknown-linux-musl
+
+      - name: cache rust toolchain
+        uses: Swatinem/rust-cache@v2
+
+      - name: install musl-tools
+        run: sudo apt-get update && sudo apt-get install -y musl-tools
+
+      - name: cargo build
+        run: cargo build --release --target x86_64-unknown-linux-musl
+
+      - name: create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release delete --yes ${{ github.ref_name }} || true
+          gh release create --generate-notes ${{ github.ref_name }} target/x86_64-unknown-linux-musl/release/beacon

.gitignore

@@ -0,0 +1 @@
+target/

Cargo.lock

@@ -0,0 +1,11 @@
+[package]
+name = "devpath"
+version = "0.1.0"
+edition = "2021"
+description = "UEFI Device Path parsing library"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/AMDEPYC/snpcert"
+readme = "README.md"
+keywords = ["uefi", "device-path", "firmware", "boot", "efi"]
+categories = ["embedded", "hardware-support", "parsing"]
+rust-version = "1.80"

Cargo.toml

@@ -0,0 +1,119 @@
+# Code Style Guide
+
+## Module Organization
+
+- **Module names**: Shortened, clear (e.g., `bluetooth_le` → `btle`, `device_logical_unit` → `dlu`)
+- **Module structure**: One primary struct per sub-type, implementation in same file
+- **File naming**: Match shortened module names
+
+## Import Grouping
+
+```rust
+// 1. External crates (if any)
+use core::net::Ipv4Addr;
+
+// 2. Internal crate imports  
+use crate::{Error, Head};
+use crate::parser::{ByteOrder, Parser};
+
+// 3. Relative imports
+use super::ipv4::Protocol;
+```
+
+## Field Naming
+
+- **Brief names**: `vendor_id` → `vid`, `mac_address` → `mac`, `baud_rate` → `baud`
+- **Documentation**: Add doc comments for any ambiguous shortened names
+- **Standard abbreviations**: `nsid`, `lun`, `wwn`, `eui`, `vid`, `pid`, `hba_port`, `pm_port`
+
+## Data Types
+
+### String Handling
+- **UTF-8 strings**: Use `&CStr` for null-terminated UTF-8 strings
+- **UTF-16 strings**: Use `String` for UTF-16 strings (converted from parser)
+- **Raw strings**: Use `&str` for non-null-terminated UTF-8 strings (rare)
+
+### Newtypes
+- **Single field structs**: Use newtype pattern
+```rust
+pub struct Vlan(pub u16);
+pub struct Protocol(pub u16);
+```
+
+### Enums
+- **Small known value sets**: Use proper enums (no repr guarantees)
+- **Parser trait**: Implement for validation
+```rust
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Origin {
+    Manual = 0x00,
+    StatelessAutoConfiguration = 0x01,
+}
+```
+
+### Structs
+- **Multi-field types**: Regular structs with brief field names
+- **Derive**: Always include `Debug, Clone, Copy, PartialEq, Eq, Hash`
+
+## Reserved Fields
+
+- **Storage**: Do NOT store reserved fields in structs
+- **Validation**: Parse and validate in `TryFrom` implementation
+- **Pattern**: `let _reserved: u32 = node.data.parse(ByteOrder::Little)?;`
+
+## Error Handling
+
+- **Invalid values**: Return `Error::Invalid` for spec violations
+- **Validation**: Check reserved field values, invalid NSIDs, etc.
+
+## Documentation
+
+- **Struct docs**: Include UEFI sub-type number and byte length
+- **Field docs**: Required for abbreviated field names
+- **Example**:
+```rust
+/// SATA Device Path (SubType 0x12)
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Sata {
+    /// HBA port number
+    pub hba_port: u16,
+    /// Port multiplier port number  
+    pub pm_port: u16,
+    pub lun: u16,
+}
+```
+
+## Implementation Patterns
+
+### Parse Order
+- **Last field**: Always use `finish()` method to guarantee end of data
+- **Earlier fields**: Use regular `parse()` method
+
+### TryFrom Implementation
+```rust
+impl<'a> TryFrom<Head<'a>> for TypeName<'a> {
+    type Error = Error;
+
+    fn try_from(mut node: Head<'a>) -> Result<Self, Self::Error> {
+        // Parse reserved fields (don't store)
+        let _reserved: u32 = node.data.parse(ByteOrder::Little)?;
+        
+        // Parse fields (use finish() for last field)
+        let field1 = node.data.parse(ByteOrder::Little)?;
+        let utf8_string = node.data.finish(())?; // &CStr for UTF-8
+        
+        Ok(TypeName { field1, utf8_string })
+    }
+}
+```
+
+### Byte Order
+- **Multi-byte integers**: Always specify `ByteOrder::Little` 
+- **Single bytes**: Use `()` argument
+- **Arrays**: Use `()` argument
+
+## Constants
+
+- **Protocol numbers**: Define as associated constants
+- **Magic values**: Use descriptive constant names
+- **Grouping**: Related constants together with docs

STYLE.md

@@ -0,0 +1,14 @@
+[licenses]
+confidence-threshold = 0.8
+allow = [
+    "MIT",
+    "Apache-2.0",
+]
+
+[bans]
+multiple-versions = "warn"
+
+[sources]
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+unknown-registry = "deny"
+unknown-git = "deny"

deny.toml

@@ -0,0 +1,34 @@
+//! ACPI Device Path address (`_ADR`) implementation
+//!
+//! This module implements the ACPI `_ADR` device path as defined in UEFI 2.11 specification.
+//! Used for identifying video output devices using ACPI `_ADR` values.
+
+use crate::parser::{ByteOrder, Parser};
+use crate::{Error, Head};
+
+use alloc::vec::Vec;
+
+/// ACPI `_ADR` Device Path (SubType 0x03) - for video output devices
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Adr {
+    adrs: Vec<u32>,
+}
+
+impl TryFrom<Head<'_>> for Adr {
+    type Error = Error;
+
+    fn try_from(mut node: Head<'_>) -> Result<Self, Self::Error> {
+        let mut values = Vec::new();
+
+        while node.data.len() >= 4 {
+            let value: u32 = node.data.parse(ByteOrder::Little)?;
+            values.push(value);
+        }
+
+        if !node.data.is_empty() {
+            return Err(Error::Invalid);
+        }
+
+        Ok(Self { adrs: values })
+    }
+}

src/acpi/adr.rs

@@ -0,0 +1,40 @@
+//! ACPI Device Path expanded format implementation
+//!
+//! This module implements the expanded ACPI device path format as defined in UEFI 2.11
+//! specification. The expanded format includes additional string-based identifiers.
+
+use crate::parser::{ByteOrder, Format, Parser};
+use crate::{Error, Head};
+
+/// Helper struct for ACPI device identifiers
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Id(pub u32, pub String);
+
+/// Expanded ACPI Device Path (SubType 0x02)
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Expanded {
+    /// Hardware ID - identifies the device's Plug and Play ID
+    pub hid: Id,
+
+    /// Unique ID - distinguishes multiple instances of the same device
+    pub uid: Id,
+
+    /// Compatible ID - identifies devices compatible with this device
+    pub cid: Id,
+}
+
+impl TryFrom<Head<'_>> for Expanded {
+    type Error = Error;
+
+    fn try_from(mut node: Head<'_>) -> Result<Self, Self::Error> {
+        let hid = node.data.parse(ByteOrder::Little)?;
+        let uid = node.data.parse(ByteOrder::Little)?;
+        let cid = node.data.parse(ByteOrder::Little)?;
+
+        Ok(Self {
+            hid: Id(hid, node.data.parse(Format::Utf8(None))?),
+            uid: Id(uid, node.data.parse(Format::Utf8(None))?),
+            cid: Id(cid, node.data.finish(Format::Utf8(None))?),
+        })
+    }
+}