TheRock/rocm-systems/projects/cuid/docs/conceptual/cuid_file.rst

.. meta::
  :description: The CUID file help non-privileged users access the derived CUIDs.
  :keywords: CUID file, non-privileged users, sharing derived CUID, access derived CUID

.. _cuid-file:

***********
CUID files
***********

To help non-privileged users access the derived CUIDs generated by privileged applications or users, these CUIDs are stored in CUID files. In daemon mode, Inter-Process Communication (IPC) can be utilized to share derived CUIDs with non-privileged users. However, the CUID files retain information in both daemon and non-daemon modes.
Two files, one for unprivileged users and another containing sensitive device information for privileged users, are stored in the ``/tmp`` or ``tmpfs`` directory. These files are updated by a daemon, boot script, or a cron job.

CUID file format
==================

Here's a sample CUID file for your reference:

.. code-block:: shell

  [GPU:0]
  derived_cuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  vendor_id=1022
  device_id=1974
  pci_class=0004
  revision_id=01
  unit_id=0002
  device_node=/sys/class/drm/renderD128
  last_update=1753987166

  [CPU:0]
  derived_cuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  vendor_id=1022
  device_id=1974
  revision_id=01
  family=0019
  model=0074
  unit_id=0004
  package_id=0
  last_update=6980d761

  [NIC:0]
  derived_cuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  vendor_id=1414
  device_id=0003
  pci_class=0005
  revision_id=10
  device_node=/sys/class/net/enp131s0
  last_update=1753987166

  [PLATFORM]
  derived_cuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  vendor_id=1573
  last_update=1753987166

**Attributes associating the derived CUID with the device:**

Depending on the device type, different device attributes (present in the CUID file) serve as keys for associating the derived CUID with the device. The following list mentions those attributes as per the given device type:

- **GPU:** The ``device_node`` links the derived CUID to the hardware.

- **CPU:** The ``package_id`` identifies the physical CPU package, which is akin to a socket ID. CPUs will also display a ``device_node`` which represents the representative logical CPU for that package (currently selected as the lowest APIC ID seen for the socket). The derived CUID is associated with the physical CPU package, not the logical CPU core.

- **NIC:** The ``device_node`` links the derived CUID to the network device.

- **PLATFORM:** The platform doesn't necessitate a key for association. Therefore, only the derived CUID is listed.

The attribute ``last_update`` represents the Unix timestamp for the last modification of the device's ``derived_cuid``.

Privileged CUID file with primary CUIDs
========================================

The privileged CUID file is accessible only to the privileged users, because in addition to the information present in the CUID file, the privileged CUID file contains the primary CUID and some sensitive device information- primarily the serial number (labeled as hardware fingerprint). Privileged users can use this privileged CUID file to see the mapping between the ``primary_cuid`` and the ``derived_cuid``.

Here is a sample privileged CUID file:

.. code-block:: shell

  [GPU:0]
  primary_cuid=YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY
  derived_cuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  hardware_fingerprint=ZZZZZZZZ
  vendor_id=1022
  device_id=1974
  pci_class=0004
  revision_id=01
  unit_id=0002
  device_node=/sys/class/drm/renderD128
  last_update=1753987166

.. note::

  The privileged file contains sensitive information. To safeguard the ``primary_cuid`` and sensitive device information, ensure that access to the file is restricted.