smmu_device_add_generic()

Updated: May 06, 2022

Add a device to a SMMU object, or remove it

Synopsis:

#include <smmu.h>

int smmu_device_add_generic(struct smmu_object *sop,
                                   const union smmu_devid *devid);

Arguments:

sop
Pointer to the SMMU object to which the device referenced by devid will be added, or NULL to remove the device from any SMMU objects owned by the current client.
devid
Pointer to the ID of the device to be added to or removed from a SMMU object.

Library:

libsmmu.a

Description:

The smmu_device_add_generic() function is called by the smmu_device_add_mmio() and smmu_device_add_pci() convenience functions. It can also be used directly by a smmuman client.

The smmu_device_add_generic() function updates the smmu_object data structure referenced by sop with a pointer to a device ID. This adds the device to the SMMU object, so that the smmuman client that created the SMMU object can program the hardware IOMMU/SMMUs to allow the device to access the memory regions associated with the SMMU object.

Note:

All devices attached to a SMMU object are granted access to the memory regions mapped to that object, with the same permissions. If you want to give two devices access to the same memory region, but with different permissions (e.g., one device may only read, the other may only write), then you must create two separate SMMU objects (see smmu_mapping_add()).

A device may have only one owner. Attempting to use one of the smmu_device_add_*() functions when the device has already been added to a SMMU object of a different client will result in an EBUSY error. A smmuman client may move a device from one of its SMMU objects to another one of its SMMU objects, however, because this action doesn't change the device owner.

To remove a device from SMMU objects, call this function with the sop argument set to NULL.

Returns:

-1
Failure: errno is set.
EBUSY
Failure when attempting to add to a SMMU object a DMA device that is owned by another smmuman client.
ENOENT

Failure: when attempting to:

  • add a device – the smmuman service doesn't know which IOMMU/SMMU unit controls the device being added
  • remove a device – the smmuman client making the call doesn't own the SMMU object to which the device is attached
0
Success
+1
Success, but the client must call smmu_mapping_add() to reissue the memory mappings for this object (see Preferred sequence for adding memory mappings and devices for more information about why memory mappings may need to be reissued).