以 Rust 編寫的螢幕驅動程式評量標準

use std::num::NonZero;
use zx_sys::zx_paddr_t;

// Useful displays have at least one pixel.
let display_width: NonZero<u16>;

// Our FIDL APIs use 0 as an invalid ID.
let imported_image_id: Option<NonZero<u64>>;

// To be obtained from a memory pinning API.
let mut image_physical_address: zx_paddr_t;

// Will be written into a register.
let image_physical_address: NonZero<u32>;

// [`None`] when the plane is disabled.
let image_physical_address_reg_value: Option<NonZero<u32>>;

struct Data {}

impl Data {
    pub async fn new() -> Result<Self, zx::Status> { /* ... */ }
}

use fdf_component::{Driver, Node};

struct DisplayDriver {
    // We must keep the Node alive for the lifetime of the driver.
    #[expect(dead_code)]
    device_node: Node,
}

impl Driver for DisplayDriver {
    async fn stop(&self) {
        // Intentionally ignoring failure during device shutdown. There's
        // nothing we can do at this point.
        let _ = fallible_function_that_logs();
    }
}

fn fallible_function_that_logs() -> Result<(), zx::Status> { /* ... */ }

use bitfield::bitfield;
use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};

bitfield! {
    #[repr(transparent)]
    #[derive(Copy, Clone, FromBytes, Immutable, IntoBytes, KnownLayout)]
    struct CommandFlags(u32);

    /* ... */
}

#[repr(C)]
#[derive(Copy, Clone, FromBytes, Immutable, IntoBytes, KnownLayout)]
struct Command {
    pub flags: CommandFlags,
    pub id: u32,
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::mem::{align_of, offset_of, size_of};

    #[fuchsia::test]
    fn test_command_abi() {
        assert_eq!(size_of::<Command>(), 8);
        assert_eq!(align_of::<Command>(), 4);
        assert_eq!(offset_of!(Command, flags), 0);
        assert_eq!(offset_of!(Command, id), 4);
    }
}

use fidl_next_fuchsia_sysmem2 as fidl_sysmem2;

pub async fn use_buffer_collection(
    sysmem_buffer_collection: &mut fidl_next::Client<fidl_sysmem2::BufferCollection>,
) {
    /* ... */
    log::warn!("Failed to get hardware pixel formats, falling back to safe set");
    /* ... */
}

use fidl_next_fuchsia_hardware_platform_device as fidl_platform_device;
use mmio::MmioSplit;
use mmio::region::MmioRegion;
use mmio::vmo::VmoMemory;
use std::sync::Arc;

/// Obtains an MMIO region from the Platform Device.
///
/// Logs on failure.
async fn map_mmio_range(
    platform_device: &fidl_next::Client<fidl_platform_device::Device>,
    range_name: &str,
) -> Result<MmioRegion<VmoMemory, Arc<VmoMemory>>, zx::Status> {
    let region = platform_device.map_mmio_by_name(range_name).await.map_err(|err| {
        log::error!("Failed to map MMIO range {range_name}: {err:?}");
        err.log_to_status()
    })?;
    Ok(region.into_split_send())
}

impl FunctionalUnit {
    pub fn new(mut mmio: MmioRegion<VmoMemory, Arc<VmoMemory>>) -> Self {
        // Subunit 1 manages the MMIO range 0x0000..0x1000.
        let subunit1_mmio = mmio.split_off(0x1000);
        let subunit1 = SubUnit1::new(subunit1_mmio);

        // Subunit 2 manages the MMIO range 0x1000..0x2000.
        let subunit2_mmio = mmio.split_off(0x1000);
        let subunit2 = SubUnit2::new(subunit2_mmio);

        // Subunit 3 manages the MMIO range from 0x2000 onwards.
        let subunit3 = SubUnit3::new(mmio);

        Self { subunit1, subunit2, subunit3 }
    }
}

use std::num::NonZero;
use std::ptr::NonNull;

#[repr(...)]
#[derive(...)]
struct Header { /* ... */ }

#[repr(...)]
#[derive(...)]
struct Trailer { /* ... */ }

struct SharedMemory {
    header_ptr: NonNull<Header>,
    trailer_ptr: NonNull<Trailer>,
}

impl SharedMemory {
    pub fn new() -> Result<Self, zx::Status> {
        let data_address = fuchsia_runtime::vmar_root_self().map(...)?;
        let data_address = NonZero::<usize>::new(data_address)
            .expect("zx::vmar::map() returned null address");

        // [`Option::unwrap()`] is guaranteed not to panic. The [`NonZero::new()`]
        // call above already checked that the pointer is non-null.
        let header_ptr = NonNull::new(
            std::ptr::with_exposed_provenance_mut(data_address.get())
        ).unwrap();

        // SAFETY: The memory allocation covers both [`Header`] and [`Trailer`].
        let trailer_ptr = unsafe { header_ptr.add(1) }.cast::<Trailer>();

        Ok(Self { header_ptr, trailer_ptr })
    }
}

/// Errors if the hardware returns an invalid version.
///
/// All error conditions are logged.
pub fn read_version() -> Result<u32, zx::Status> {
    log::debug!("read_version()");

    let version_value: u32 = read_from_register();

    // TODO(https://fxbug.dev/12345678): We suspect that the crashes are
    // correlated with specific hardware versions. Reduce the log level to DEBUG
    // after proving or disproving the hypothesis.
    log::info!("Component version: {version_value}");

    if version_value == 0 {
        log::warn!("Invalid version, device may be off: {version_value}");
        // ...
    }
    // ...
}

/// Errors if the hardware returns an invalid version.
///
/// All error conditions are logged.
pub fn read_version() -> Result<u32, zx::Status> { /* ... */ }

/// Initializes the hardware so it can receive commands.
///
/// All error conditions are logged.
pub fn initialize_hardware() -> Result<(), zx::Status> {
    let version_value = read_version()?;

    /* ... */
}

/// See [`DeviceBuilder`] for obtaining instances.
pub struct Device {}

use std::num::NonZero;

/// Packages the information in a FIDL request.
struct MessageRectangle {
    pub width: NonZero<u32>,
    pub height: NonZero<u32>,
}

impl MessageRectangle {
    /// True iff the instance meets the [`HorizontalRectangle`] invariants.
    pub fn is_horizontal(&self) -> bool { self.width >= self.height }
}

/// The width is guaranteed to be at least as large as the height.
struct HorizontalRectangle {
    width: NonZero<u32>,
    height: NonZero<u32>,
}

impl HorizontalRectangle {
    /// Factory function.
    pub fn square(width: NonZero<u32>) -> Self {
        Self { width, height: width }
    }

    pub fn aspect_ratio(&self) -> f64 { /* ... */ }
}

use std::num::NonZero;

enum Polarity {
    ActiveHigh,
    ActiveLow,
}

/// Argument for [`set_device_timing`].
struct DeviceTiming {
    pub horizontal_sync_polarity: Polarity,
    pub vertical_sync_polarity: Polarity,
    pub horizontal_active: NonZero<u32>,
    pub vertical_active: NonZero<u32>,
}

fn set_device_timing(device_timing: DeviceTiming) { /* ... */ }

pub fn initialize_device() {
    set_device_timing(DeviceTiming {
        horizontal_sync_polarity: Polarity::ActiveHigh,
        vertical_sync_polarity: Polarity::ActiveHigh,
        horizontal_active: const { NonZero::new(640).unwrap() },
        vertical_active: const { NonZero::new(480).unwrap() },
    });
}

pub struct Point {
    pub x: u32,
    pub y: u32,
}

// Returning a struct to avoid tuple indexing expressions.
pub fn cursor_position() -> Point { /* ... */ }

pub fn connect() {
    // `zx::Channel::create()` returns `(zx::Channel, zx::Channel)`.
    let (driver_channel, device_channel) = zx::Channel::create();
    /* ... */
}