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;