smmu_xfer_status()

Updated: May 06, 2022

Retrieve the record of a DMA device’s attempt to access memory outside its permitted region or regions

Synopsis:

#include <smmu.h>

int smmu_xfer_status(struct smmu_status *ssp);

Arguments:

ssp
A pointer to the smmu_status structure to be populated with the error information.

Library:

libsmmu.a

Description:

The smmu_xfer_status() function retrieves one status record of a DMA device memory access transgression.

If your smmuman client needs to be informed of DMA device memory access transgressions, after it connects to the service, the client should call smmu_xfer_notify() to register to receive notifications of remapping errors.

On receipt of a notification, the client can call smmu_xfer_status() to retrieve the record of the transgression and decide what to do about it.

The smmuman service can store up to 64 records of attempted transgressions per client attached to the service. If the DMA device produces more than 64 transgressions before a call to smmu_xfer_status(), the smmuman begins dropping new transgression records, and sets the SSF_DROPPED_FAULTS bit in the smmu_status's flag member.

You can check this bit to learn if the smmuman service had to drop one or transgression records before your client was able to read them.

Retrieving a records clears the buffer space used by that record.

When the smmuman service informs a client that an IOMMU/SMMU has refused a DMA device's memory access attempt, it clears that client's registration for notification of DMA device memory access transgressions. The client must call smmu_xfer_notify() to re-register for notification.

Note:

The smmuman service can only pass on information that has been supplied by the hardware. For example, if the hardware supplies the page offset portion of the address a DMA device attempted to access but to which it was refused access, a call to smmu_xfer_status() can retrieve that information. However, if the hardware doesn't make that information available, it won't be available to the smmuman service or to its clients.

If you will do more than simply log a DMA device's attempted transgression, then you should read the device registers directly to retrieve the information you need.

Returns:

-1
Failure: errno is set.
1
Success: a record was found and the smmu_status structure was populated with information about the transgression.
0
Success, but no record of a transgression was found.