Skip to main content

tenferro_gpu/cuda/
device.rs

1use std::fmt;
2
3use tenferro_tensor::BoxError;
4
5use super::identity::{CudaComputeCapability, CudaDeviceUuid};
6
7#[derive(Debug, thiserror::Error)]
8enum CudaDriverDiscoveryError {
9    #[error("the CUDA driver probe failed")]
10    DriverUnavailable {
11        #[source]
12        source: BoxError,
13    },
14    #[error("CUDA driver call {function} failed: {source}")]
15    DriverCall {
16        function: &'static str,
17        #[source]
18        source: cudarc::driver::result::DriverError,
19    },
20    #[error("CUDA returned an invalid device count {count}")]
21    InvalidDeviceCount { count: i32 },
22    #[error("CUDA device ordinal {device:?} is out of range")]
23    DeviceOrdinalOutOfRange { device: CudaDeviceId },
24}
25
26fn boxed_discovery_error(error: CudaDriverDiscoveryError) -> BoxError {
27    Box::new(error)
28}
29
30struct CudaDriverApi;
31
32/// Provider-qualified identity of a CUDA device ordinal.
33///
34/// A device ID is an opaque CUDA provider value. Use [`Self::ordinal`] only
35/// when passing the selected ordinal to CUDA APIs. The ordinal is
36/// process-visible and may change when `CUDA_VISIBLE_DEVICES` changes.
37///
38/// # Examples
39///
40/// ```
41/// use tenferro_gpu::cuda::CudaDeviceId;
42///
43/// let device = CudaDeviceId::from_ordinal(2);
44/// assert_eq!(device.ordinal(), 2);
45/// ```
46#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
47pub struct CudaDeviceId(u32);
48
49impl CudaDeviceId {
50    /// Construct a device ID from its CUDA ordinal.
51    ///
52    /// # Examples
53    ///
54    /// ```
55    /// use tenferro_gpu::cuda::CudaDeviceId;
56    ///
57    /// const DEVICE: CudaDeviceId = CudaDeviceId::from_ordinal(0);
58    /// assert_eq!(DEVICE.ordinal(), 0);
59    /// ```
60    pub const fn from_ordinal(ordinal: u32) -> Self {
61        Self(ordinal)
62    }
63
64    /// Return the CUDA ordinal represented by this device ID.
65    ///
66    /// # Examples
67    ///
68    /// ```
69    /// use tenferro_gpu::cuda::CudaDeviceId;
70    ///
71    /// let device = CudaDeviceId::from_ordinal(3);
72    /// assert_eq!(device.ordinal(), 3);
73    /// ```
74    pub const fn ordinal(self) -> u32 {
75        self.0
76    }
77}
78
79impl fmt::Debug for CudaDeviceId {
80    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
81        formatter
82            .debug_tuple("CudaDeviceId")
83            .field(&self.0)
84            .finish()
85    }
86}
87
88/// Immutable metadata describing one CUDA device.
89///
90/// Equality and debug output are deterministic only while the process-visible
91/// CUDA topology remains unchanged; they do not provide stable identity across
92/// topology changes.
93///
94/// # Examples
95///
96/// ```
97/// use tenferro_gpu::cuda::CudaDeviceInfo;
98///
99/// let _type_name = std::any::type_name::<CudaDeviceInfo>();
100/// ```
101#[derive(Clone, Debug, Eq, PartialEq)]
102pub struct CudaDeviceInfo {
103    id: CudaDeviceId,
104    name: String,
105    uuid: CudaDeviceUuid,
106    compute_capability: CudaComputeCapability,
107    total_memory_bytes: u64,
108}
109
110impl CudaDeviceInfo {
111    /// Construct device metadata for a CUDA device.
112    pub(crate) fn new(
113        id: CudaDeviceId,
114        name: impl Into<String>,
115        uuid: CudaDeviceUuid,
116        compute_capability: CudaComputeCapability,
117        total_memory_bytes: u64,
118    ) -> Self {
119        Self {
120            id,
121            name: name.into(),
122            uuid,
123            compute_capability,
124            total_memory_bytes,
125        }
126    }
127
128    /// Return this device's provider-qualified ID.
129    ///
130    /// # Examples
131    ///
132    /// ```
133    /// use tenferro_gpu::cuda::CudaDeviceInfo;
134    ///
135    /// let _id = CudaDeviceInfo::id;
136    /// ```
137    pub fn id(&self) -> CudaDeviceId {
138        self.id
139    }
140
141    /// Borrow this device's display name.
142    ///
143    /// # Examples
144    ///
145    /// ```
146    /// use tenferro_gpu::cuda::CudaDeviceInfo;
147    ///
148    /// let _name = CudaDeviceInfo::name;
149    /// ```
150    pub fn name(&self) -> &str {
151        &self.name
152    }
153
154    /// Return the stable physical/MIG identity of this device.
155    ///
156    /// The UUID is a durable comparison identity independent of the
157    /// process-visible ordinal. It is used for diagnostics, topology, and
158    /// explicit cross-runtime/cross-device placement decisions.
159    ///
160    /// # Examples
161    ///
162    /// ```
163    /// use tenferro_gpu::cuda::cuda_devices;
164    ///
165    /// // `cudarc` panics when the CUDA driver library is absent, so the call
166    /// // is guarded (the same pattern `gpu_available` uses).
167    /// let devices = std::panic::catch_unwind(cuda_devices)
168    ///     .unwrap_or_else(|_| Ok(Vec::new()))
169    ///     .unwrap_or_default();
170    /// let uuids: Vec<_> = devices.iter().map(|info| info.uuid()).collect();
171    /// let _ = uuids;
172    /// ```
173    pub fn uuid(&self) -> CudaDeviceUuid {
174        self.uuid
175    }
176
177    /// Return the compute capability of this device.
178    ///
179    /// # Examples
180    ///
181    /// ```
182    /// use tenferro_gpu::cuda::cuda_devices;
183    ///
184    /// // `cudarc` panics when the CUDA driver library is absent, so the call
185    /// // is guarded (the same pattern `gpu_available` uses).
186    /// let devices = std::panic::catch_unwind(cuda_devices)
187    ///     .unwrap_or_else(|_| Ok(Vec::new()))
188    ///     .unwrap_or_default();
189    /// let capabilities: Vec<_> = devices
190    ///     .iter()
191    ///     .map(|info| info.compute_capability())
192    ///     .collect();
193    /// let _ = capabilities;
194    /// ```
195    pub fn compute_capability(&self) -> CudaComputeCapability {
196        self.compute_capability
197    }
198
199    /// Return the total device memory in bytes.
200    ///
201    /// # Examples
202    ///
203    /// ```
204    /// use tenferro_gpu::cuda::cuda_devices;
205    ///
206    /// // `cudarc` panics when the CUDA driver library is absent, so the call
207    /// // is guarded (the same pattern `gpu_available` uses).
208    /// let devices = std::panic::catch_unwind(cuda_devices)
209    ///     .unwrap_or_else(|_| Ok(Vec::new()))
210    ///     .unwrap_or_default();
211    /// let memory: Vec<u64> = devices
212    ///     .iter()
213    ///     .map(|info| info.total_memory_bytes())
214    ///     .collect();
215    /// let _ = memory;
216    /// ```
217    pub fn total_memory_bytes(&self) -> u64 {
218        self.total_memory_bytes
219    }
220}
221
222pub(crate) trait DiscoveryDriver {
223    fn initialize(&self) -> Result<(), BoxError>;
224
225    fn device_count(&self) -> Result<u32, BoxError>;
226
227    fn device_name(&self, device: CudaDeviceId) -> Result<String, BoxError>;
228
229    fn device_uuid(&self, device: CudaDeviceId) -> Result<CudaDeviceUuid, BoxError>;
230
231    fn compute_capability(&self, device: CudaDeviceId) -> Result<CudaComputeCapability, BoxError>;
232
233    fn total_memory_bytes(&self, device: CudaDeviceId) -> Result<u64, BoxError>;
234}
235
236pub(crate) fn discover_with(
237    driver: &impl DiscoveryDriver,
238) -> Result<Vec<CudaDeviceInfo>, CudaDeviceError> {
239    driver
240        .initialize()
241        .map_err(|source| CudaDeviceError::Discovery {
242            operation: "initialize_driver",
243            source,
244        })?;
245    let device_count = driver
246        .device_count()
247        .map_err(|source| CudaDeviceError::Discovery {
248            operation: "enumerate_devices",
249            source,
250        })?;
251
252    let mut devices = Vec::new();
253    for ordinal in 0..device_count {
254        let id = CudaDeviceId::from_ordinal(ordinal);
255        let name = driver
256            .device_name(id)
257            .map_err(|source| CudaDeviceError::Discovery {
258                operation: "get_device_name",
259                source,
260            })?;
261        let uuid = driver
262            .device_uuid(id)
263            .map_err(|source| CudaDeviceError::Discovery {
264                operation: "get_device_uuid",
265                source,
266            })?;
267        let compute_capability =
268            driver
269                .compute_capability(id)
270                .map_err(|source| CudaDeviceError::Discovery {
271                    operation: "get_compute_capability",
272                    source,
273                })?;
274        let total_memory_bytes =
275            driver
276                .total_memory_bytes(id)
277                .map_err(|source| CudaDeviceError::Discovery {
278                    operation: "get_total_memory",
279                    source,
280                })?;
281        devices.push(CudaDeviceInfo::new(
282            id,
283            name,
284            uuid,
285            compute_capability,
286            total_memory_bytes,
287        ));
288    }
289    Ok(devices)
290}
291
292impl DiscoveryDriver for CudaDriverApi {
293    fn initialize(&self) -> Result<(), BoxError> {
294        // `cudarc` unwinds when the driver library or one of its entry points is missing, so ask
295        // the runtime's non-panicking probe first and keep the documented `Result` (#2401).
296        t4a_cuda_runtime::device_count().map_err(|error| {
297            boxed_discovery_error(CudaDriverDiscoveryError::DriverUnavailable {
298                source: Box::new(error),
299            })
300        })?;
301        cudarc::driver::result::init().map_err(|source| {
302            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
303                function: "cuInit",
304                source,
305            })
306        })
307    }
308
309    fn device_count(&self) -> Result<u32, BoxError> {
310        let count = cudarc::driver::result::device::get_count().map_err(|source| {
311            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
312                function: "cuDeviceGetCount",
313                source,
314            })
315        })?;
316        u32::try_from(count).map_err(|_| {
317            boxed_discovery_error(CudaDriverDiscoveryError::InvalidDeviceCount { count })
318        })
319    }
320
321    fn device_name(&self, device: CudaDeviceId) -> Result<String, BoxError> {
322        let cuda_device = self.cuda_device(device)?;
323        let name = cudarc::driver::result::device::get_name(cuda_device).map_err(|source| {
324            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
325                function: "cuDeviceGetName",
326                source,
327            })
328        })?;
329        Ok(name)
330    }
331
332    fn device_uuid(&self, device: CudaDeviceId) -> Result<CudaDeviceUuid, BoxError> {
333        let cuda_device = self.cuda_device(device)?;
334        let uuid = cudarc::driver::result::device::get_uuid(cuda_device).map_err(|source| {
335            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
336                function: "cuDeviceGetUuid",
337                source,
338            })
339        })?;
340        let mut bytes = [0u8; 16];
341        #[allow(clippy::needless_range_loop)]
342        for (index, byte) in bytes.iter_mut().enumerate() {
343            *byte = uuid.bytes[index] as u8;
344        }
345        Ok(CudaDeviceUuid::from_bytes(bytes))
346    }
347
348    fn compute_capability(&self, device: CudaDeviceId) -> Result<CudaComputeCapability, BoxError> {
349        let cuda_device = self.cuda_device(device)?;
350        use cudarc::driver::sys::CUdevice_attribute_enum as Attr;
351        let (major_name, minor_name) = unsafe {
352            (
353                cudarc::driver::result::device::get_attribute(
354                    cuda_device,
355                    Attr::CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR,
356                ),
357                cudarc::driver::result::device::get_attribute(
358                    cuda_device,
359                    Attr::CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MINOR,
360                ),
361            )
362        };
363        let major = major_name.map_err(|source| {
364            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
365                function: "cuDeviceGetAttribute(CC_MAJOR)",
366                source,
367            })
368        })?;
369        let minor = minor_name.map_err(|source| {
370            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
371                function: "cuDeviceGetAttribute(CC_MINOR)",
372                source,
373            })
374        })?;
375        Ok(CudaComputeCapability {
376            major: u32::try_from(major).map_err(|_| {
377                boxed_discovery_error(CudaDriverDiscoveryError::InvalidDeviceCount { count: major })
378            })?,
379            minor: u32::try_from(minor).map_err(|_| {
380                boxed_discovery_error(CudaDriverDiscoveryError::InvalidDeviceCount { count: minor })
381            })?,
382        })
383    }
384
385    fn total_memory_bytes(&self, device: CudaDeviceId) -> Result<u64, BoxError> {
386        let cuda_device = self.cuda_device(device)?;
387        // SAFETY: `cuda_device` was returned by `cuDeviceGet` for this session.
388        let bytes = unsafe { cudarc::driver::result::device::total_mem(cuda_device) }.map_err(
389            |source| {
390                boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
391                    function: "cuDeviceTotalMem",
392                    source,
393                })
394            },
395        )?;
396        u64::try_from(bytes).map_err(|_| {
397            boxed_discovery_error(CudaDriverDiscoveryError::InvalidDeviceCount { count: i32::MAX })
398        })
399    }
400}
401
402impl CudaDriverApi {
403    fn cuda_device(&self, device: CudaDeviceId) -> Result<cudarc::driver::sys::CUdevice, BoxError> {
404        let ordinal = i32::try_from(device.ordinal()).map_err(|_| {
405            boxed_discovery_error(CudaDriverDiscoveryError::DeviceOrdinalOutOfRange { device })
406        })?;
407        cudarc::driver::result::device::get(ordinal).map_err(|source| {
408            boxed_discovery_error(CudaDriverDiscoveryError::DriverCall {
409                function: "cuDeviceGet",
410                source,
411            })
412        })
413    }
414}
415
416/// Discover CUDA devices visible to the current process.
417///
418/// Discovery initializes the CUDA driver and queries device ordinals directly.
419/// It does not create a CUDA context, CUDA runtime, backend, or client. Device ordinals are process-visible and may change when
420/// `CUDA_VISIBLE_DEVICES` changes. The returned values have deterministic
421/// `Eq` and `Debug` behavior only while that process-visible topology remains
422/// unchanged.
423///
424/// # Errors
425///
426/// Returns [`CudaDeviceError::Discovery`] for driver initialization, device
427/// enumeration, or device-name lookup failures.
428///
429/// # Examples
430///
431/// ```
432/// use tenferro_gpu::{cuda::cuda_devices, cuda::CudaDeviceError, cuda::CudaDeviceInfo};
433///
434/// let _discover: fn() -> Result<Vec<CudaDeviceInfo>, CudaDeviceError> = cuda_devices;
435/// ```
436pub fn cuda_devices() -> Result<Vec<CudaDeviceInfo>, CudaDeviceError> {
437    discover_with(&CudaDriverApi)
438}
439
440/// Structured failures from CUDA device discovery and initialization.
441///
442/// The error retains only provider-neutral device identities and metadata. It
443/// does not expose the concrete CUDA runtime error type behind a source.
444///
445/// # Examples
446///
447/// ```
448/// use tenferro_gpu::{cuda::CudaDeviceError, cuda::CudaDeviceId};
449///
450/// let error = CudaDeviceError::Unavailable {
451///     requested: CudaDeviceId::from_ordinal(1),
452///     discovered: Vec::new().into_boxed_slice(),
453/// };
454/// assert_eq!(error.requested(), Some(CudaDeviceId::from_ordinal(1)));
455/// ```
456#[derive(Debug, thiserror::Error)]
457#[non_exhaustive]
458pub enum CudaDeviceError {
459    /// Device discovery failed while performing the named operation.
460    #[error("CUDA device discovery failed during {operation}: {source}")]
461    Discovery {
462        /// The provider-neutral discovery operation being performed.
463        operation: &'static str,
464        /// The underlying discovery failure.
465        #[source]
466        source: tenferro_tensor::BoxError,
467    },
468    /// The requested device was not present in the discovered device list.
469    #[error(
470        "requested CUDA device {requested:?} is unavailable; discovered devices: {discovered:?}"
471    )]
472    Unavailable {
473        /// The device selected by the caller.
474        requested: CudaDeviceId,
475        /// Devices found during discovery, in discovery order.
476        discovered: Box<[CudaDeviceInfo]>,
477    },
478    /// Device initialization failed while performing the named operation.
479    #[error("CUDA device {device:?} initialization failed during {operation}: {source}")]
480    Initialization {
481        /// The device whose runtime could not be initialized.
482        device: CudaDeviceId,
483        /// The provider-neutral initialization operation being performed.
484        operation: &'static str,
485        /// The underlying initialization failure.
486        #[source]
487        source: tenferro_tensor::BoxError,
488    },
489}
490
491impl CudaDeviceError {
492    /// Return the operation associated with discovery or initialization.
493    ///
494    /// # Examples
495    ///
496    /// ```
497    /// use tenferro_gpu::{cuda::CudaDeviceError, cuda::CudaDeviceId};
498    ///
499    /// let error = CudaDeviceError::Unavailable {
500    ///     requested: CudaDeviceId::from_ordinal(1),
501    ///     discovered: Vec::new().into_boxed_slice(),
502    /// };
503    /// assert_eq!(error.operation(), None);
504    /// ```
505    pub fn operation(&self) -> Option<&'static str> {
506        match self {
507            Self::Discovery { operation, .. } | Self::Initialization { operation, .. } => {
508                Some(operation)
509            }
510            Self::Unavailable { .. } => None,
511        }
512    }
513
514    /// Return the requested device for an unavailable-device error.
515    ///
516    /// # Examples
517    ///
518    /// ```
519    /// use tenferro_gpu::{cuda::CudaDeviceError, cuda::CudaDeviceId};
520    ///
521    /// let requested = CudaDeviceId::from_ordinal(1);
522    /// let error = CudaDeviceError::Unavailable {
523    ///     requested,
524    ///     discovered: Vec::new().into_boxed_slice(),
525    /// };
526    /// assert_eq!(error.requested(), Some(requested));
527    /// ```
528    pub fn requested(&self) -> Option<CudaDeviceId> {
529        match self {
530            Self::Unavailable { requested, .. } => Some(*requested),
531            Self::Discovery { .. } | Self::Initialization { .. } => None,
532        }
533    }
534
535    /// Borrow the devices discovered for an unavailable-device error.
536    ///
537    /// # Examples
538    ///
539    /// ```
540    /// use tenferro_gpu::{cuda::CudaDeviceError, cuda::CudaDeviceId};
541    ///
542    /// let error = CudaDeviceError::Unavailable {
543    ///     requested: CudaDeviceId::from_ordinal(1),
544    ///     discovered: Vec::new().into_boxed_slice(),
545    /// };
546    /// assert!(error.discovered().is_some_and(<[_]>::is_empty));
547    /// ```
548    pub fn discovered(&self) -> Option<&[CudaDeviceInfo]> {
549        match self {
550            Self::Unavailable { discovered, .. } => Some(discovered),
551            Self::Discovery { .. } | Self::Initialization { .. } => None,
552        }
553    }
554
555    /// Return the device whose initialization failed.
556    ///
557    /// # Examples
558    ///
559    /// ```
560    /// use tenferro_gpu::{cuda::CudaDeviceError, cuda::CudaDeviceId};
561    ///
562    /// let device = CudaDeviceId::from_ordinal(1);
563    /// let error = CudaDeviceError::Initialization {
564    ///     device,
565    ///     operation: "create_client",
566    ///     source: Box::new(std::io::Error::other("context failed")),
567    /// };
568    /// assert_eq!(error.device(), Some(device));
569    /// ```
570    pub fn device(&self) -> Option<CudaDeviceId> {
571        match self {
572            Self::Initialization { device, .. } => Some(*device),
573            Self::Discovery { .. } | Self::Unavailable { .. } => None,
574        }
575    }
576}
577
578#[cfg(test)]
579mod tests;