Skip to main content

sys_lib/
gpu.rs

1//! Graphics adapters.
2//!
3//! What the OS says about each adapter: its name, vendor, kind, PCI ids,
4//! dedicated memory, and driver. No usage or memory in use: those need vendor
5//! libraries (NVML, ROCm SMI, DXGI), which sys-lib does not load.
6//!
7//! ```
8//! use sys_lib as sys;
9//!
10//! for g in sys::gpu::list().unwrap_or_default() {
11//!     println!("{} ({:?}, {:?}) memory {:?}", g.name, g.vendor, g.kind, g.memory);
12//! }
13//! ```
14
15use crate::{Bytes, Result};
16
17/// One graphics adapter.
18#[derive(Clone, Debug, PartialEq, Eq)]
19#[non_exhaustive]
20pub struct Gpu {
21    /// Its name: "NVIDIA GeForce RTX 4070", "Apple M2". On Linux without a
22    /// `pci.ids` database, the vendor and the device id: "NVIDIA GPU 0x2786".
23    pub name: String,
24    /// Who made it.
25    pub vendor: GpuVendor,
26    /// Built in, on its own card, or emulated.
27    pub kind: GpuKind,
28    /// The PCI vendor id.
29    pub vendor_id: Option<u16>,
30    /// The PCI device id.
31    pub device_id: Option<u16>,
32    /// Dedicated video memory, when the OS reports it.
33    pub memory: Option<Bytes>,
34    /// The driver: `amdgpu`, `i915`, a Windows driver version.
35    pub driver: Option<String>,
36}
37
38/// Who made a graphics adapter.
39#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
40#[non_exhaustive]
41pub enum GpuVendor {
42    /// NVIDIA.
43    Nvidia,
44    /// AMD.
45    Amd,
46    /// Intel.
47    Intel,
48    /// Apple.
49    Apple,
50    /// Qualcomm.
51    Qualcomm,
52    /// Arm (Mali).
53    Arm,
54    /// Microsoft (the basic display adapter, Hyper-V).
55    Microsoft,
56    /// VMware.
57    Vmware,
58    /// Anyone else.
59    Other,
60}
61
62impl GpuVendor {
63    /// The vendor for a PCI vendor id.
64    #[must_use]
65    pub const fn from_pci(id: u16) -> GpuVendor {
66        match id {
67            0x10de => Self::Nvidia,
68            0x1002 | 0x1022 => Self::Amd,
69            0x8086 => Self::Intel,
70            0x106b => Self::Apple,
71            0x5143 | 0x17cb => Self::Qualcomm,
72            0x13b5 => Self::Arm,
73            0x1414 => Self::Microsoft,
74            0x15ad => Self::Vmware,
75            _ => Self::Other,
76        }
77    }
78
79    /// Its name: `"NVIDIA"`, `"AMD"`.
80    #[must_use]
81    pub const fn name(self) -> &'static str {
82        match self {
83            Self::Nvidia => "NVIDIA",
84            Self::Amd => "AMD",
85            Self::Intel => "Intel",
86            Self::Apple => "Apple",
87            Self::Qualcomm => "Qualcomm",
88            Self::Arm => "Arm",
89            Self::Microsoft => "Microsoft",
90            Self::Vmware => "VMware",
91            Self::Other => "Other",
92        }
93    }
94}
95
96/// Where a graphics adapter is.
97#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
98#[non_exhaustive]
99pub enum GpuKind {
100    /// Part of the CPU or the system chip.
101    Integrated,
102    /// A card or chip of its own, with its own memory.
103    Discrete,
104    /// Emulated by a hypervisor, or a display driver with no hardware.
105    Virtual,
106    /// Not known.
107    Unknown,
108}
109
110/// The kind a vendor's adapter usually is, for platforms that do not say:
111/// Intel and Apple are integrated, NVIDIA discrete, the hypervisors' virtual;
112/// AMD makes both, so `Unknown` unless the caller knows more.
113#[allow(dead_code)] // unused on targets without a backend
114pub(crate) const fn kind_of(vendor: GpuVendor) -> GpuKind {
115    match vendor {
116        GpuVendor::Intel | GpuVendor::Apple | GpuVendor::Qualcomm | GpuVendor::Arm => {
117            GpuKind::Integrated
118        }
119        GpuVendor::Nvidia => GpuKind::Discrete,
120        GpuVendor::Microsoft | GpuVendor::Vmware => GpuKind::Virtual,
121        GpuVendor::Amd | GpuVendor::Other => GpuKind::Unknown,
122    }
123}
124
125/// Every graphics adapter the OS lists, in its order.
126///
127/// # Errors
128///
129/// `Unsupported` on iOS and targets without a backend; `Io` or `Os` when the
130/// OS's list cannot be read.
131pub fn list() -> Result<Vec<Gpu>> {
132    crate::sys::gpus()
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138
139    #[test]
140    fn test_gpu_vendor_from_pci() {
141        assert_eq!(GpuVendor::from_pci(0x10de), GpuVendor::Nvidia);
142        assert_eq!(GpuVendor::from_pci(0x1002), GpuVendor::Amd);
143        assert_eq!(GpuVendor::from_pci(0x8086), GpuVendor::Intel);
144        assert_eq!(GpuVendor::from_pci(0x1234), GpuVendor::Other);
145        assert_eq!(kind_of(GpuVendor::Nvidia), GpuKind::Discrete);
146        assert_eq!(kind_of(GpuVendor::Amd), GpuKind::Unknown);
147    }
148
149    #[test]
150    fn test_gpu_live_list_or_unavailable() {
151        match list() {
152            Ok(list) => {
153                for g in list {
154                    assert!(!g.name.is_empty(), "{g:?}");
155                }
156            }
157            Err(e) => assert!(e.is_unavailable(), "{e}"),
158        }
159    }
160}