The public iommu and iommu_domain API interface in Linux: what is the concept of "dm: direct mapping"?

1. iommu_domain

   /* iommu fault flags */
   #define IOMMU_FAULT_READ    0x0
   #define IOMMU_FAULT_WRITE   0x1
   
   typedef int (*iommu_fault_handler_t)(struct iommu_domain *,
               struct device *, unsigned long, int, void *);
   
   struct iommu_domain_geometry {
       dma_addr_t aperture_start; /* First address that can be mapped    */
       dma_addr_t aperture_end;   /* Last address that can be mapped     */
       bool force_aperture;       /* DMA only allowed in mappable range? */
   };
   
   /* Domain feature flags */
   #define __IOMMU_DOMAIN_PAGING   (1U << 0)  /* Support for iommu_map/unmap */
   #define __IOMMU_DOMAIN_DMA_API  (1U << 1)  /* Domain for use in DMA-API
                             implementation              */
   #define __IOMMU_DOMAIN_PT   (1U << 2)  /* Domain is identity mapped   */
   
   /*
    * This are the possible domain-types
    *
    *  IOMMU_DOMAIN_BLOCKED    - All DMA is blocked, can be used to isolate
    *                devices
    *  IOMMU_DOMAIN_IDENTITY   - DMA addresses are system physical addresses
    *  IOMMU_DOMAIN_UNMANAGED  - DMA mappings managed by IOMMU-API user, used
    *                for VMs
    *  IOMMU_DOMAIN_DMA    - Internally used for DMA-API implementations.
    *                This flag allows IOMMU drivers to implement
    *                certain optimizations for these domains
    */
   #define IOMMU_DOMAIN_BLOCKED    (0U)
   #define IOMMU_DOMAIN_IDENTITY   (__IOMMU_DOMAIN_PT)
   #define IOMMU_DOMAIN_UNMANAGED  (__IOMMU_DOMAIN_PAGING)
   #define IOMMU_DOMAIN_DMA    (__IOMMU_DOMAIN_PAGING |    \
                    __IOMMU_DOMAIN_DMA_API)
   struct iommu_domain {
       unsigned type;
       const struct iommu_ops *ops;
       iommu_fault_handler_t handler;
       void *handler_token;
       struct iommu_domain_geometry geometry;
       void *iova_cookie;
   };
                                                                                                   
    where IOMMU_DOMAIN_DMA has been integrated by the following:

   IOMMU_DOMAIN_DMA

   Defined as a preprocessor macro in:

   • include/linux/iommu.h, line 76

   Referenced (in 8 files total) in:

   • drivers/iommu/mtk_iommu.c, line 256
   • drivers/iommu/arm-smmu.c:
     • line 1007
     • line 1018
   • drivers/iommu/arm-smmu-v3.c:
     • line 1386
     • line 1398
   • drivers/iommu/iommu.c:
     • line 326
     • line 838
   • drivers/iommu/exynos-iommu.c:
     • line 735
     • line 780
     • line 806
   • drivers/iommu/rockchip-iommu.c:
     • line 892
     • line 909
     • line 945
     • line 975
   • drivers/iommu/amd_iommu.c:
     • line 2960
     • line 2998
   • include/linux/iommu.h, line 76

2. iommu operations:

/*
 * Following constraints are specifc to FSL_PAMUV1:
 *  -aperture must be power of 2, and naturally aligned
 *  -number of windows must be power of 2, and address space size
 *   of each window is determined by aperture size / # of windows
 *  -the actual size of the mapped region of a window must be power
 *   of 2 starting with 4KB and physical address must be naturally
 *   aligned.
 * DOMAIN_ATTR_FSL_PAMUV1 corresponds to the above mentioned contraints.
 * The caller can invoke iommu_domain_get_attr to check if the underlying
 * iommu implementation supports these constraints.
 */

enum iommu_attr {
    DOMAIN_ATTR_GEOMETRY,
    DOMAIN_ATTR_PAGING,
    DOMAIN_ATTR_WINDOWS,
    DOMAIN_ATTR_FSL_PAMU_STASH,
    DOMAIN_ATTR_FSL_PAMU_ENABLE,
    DOMAIN_ATTR_FSL_PAMUV1,
    DOMAIN_ATTR_NESTING,    /* two stages of translation */
    DOMAIN_ATTR_MAX,
};

/**
 * struct iommu_dm_region - descriptor for a direct mapped memory region
 * @list: Linked list pointers
 * @start: System physical start address of the region
 * @length: Length of the region in bytes
 * @prot: IOMMU Protection flags (READ/WRITE/...)
 */
struct iommu_dm_region {
    struct list_head    list;
    phys_addr_t        start;
    size_t            length;
    int            prot;
};

/**
 * struct iommu_ops - iommu ops and capabilities
 * @capable: check capability
 * @domain_alloc: allocate iommu domain
 * @domain_free: free iommu domain
 * @attach_dev: attach device to an iommu domain
 * @detach_dev: detach device from an iommu domain
 * @map: map a physically contiguous memory region to an iommu domain
 * @unmap: unmap a physically contiguous memory region from an iommu domain
 * @map_sg: map a scatter-gather list of physically contiguous memory chunks
 * to an iommu domain
 * @iova_to_phys: translate iova to physical address
 * @add_device: add device to iommu grouping
 * @remove_device: remove device from iommu grouping
 * @device_group: find iommu group for a particular device
 * @domain_get_attr: Query domain attributes
 * @domain_set_attr: Change domain attributes
 * @get_dm_regions: Request list of direct mapping requirements for a device
 * @put_dm_regions: Free list of direct mapping requirements for a device
 * @domain_window_enable: Configure and enable a particular window for a domain
 * @domain_window_disable: Disable a particular window for a domain
 * @domain_set_windows: Set the number of windows for a domain
 * @domain_get_windows: Return the number of windows for a domain
 * @of_xlate: add OF master IDs to iommu grouping
 * @pgsize_bitmap: bitmap of supported page sizes
 * @priv: per-instance data private to the iommu driver
 */
struct iommu_ops {
    bool (*capable)(enum iommu_cap);

    /* Domain allocation and freeing by the iommu driver */
    struct iommu_domain *(*domain_alloc)(unsigned iommu_domain_type);
    void (*domain_free)(struct iommu_domain *);

    int (*attach_dev)(struct iommu_domain *domain, struct device *dev);
    void (*detach_dev)(struct iommu_domain *domain, struct device *dev);
    int (*map)(struct iommu_domain *domain, unsigned long iova,
           phys_addr_t paddr, size_t size, int prot);
    size_t (*unmap)(struct iommu_domain *domain, unsigned long iova,
             size_t size);
    size_t (*map_sg)(struct iommu_domain *domain, unsigned long iova,
             struct scatterlist *sg, unsigned int nents, int prot);
    phys_addr_t (*iova_to_phys)(struct iommu_domain *domain, dma_addr_t iova);
    int (*add_device)(struct device *dev);
    void (*remove_device)(struct device *dev);
    struct iommu_group *(*device_group)(struct device *dev);
    int (*domain_get_attr)(struct iommu_domain *domain,
                   enum iommu_attr attr, void *data);
    int (*domain_set_attr)(struct iommu_domain *domain,
                   enum iommu_attr attr, void *data);

    /* Request/Free a list of direct mapping requirements for a device */
    void (*get_dm_regions)(struct device *dev, struct list_head *list);
    void (*put_dm_regions)(struct device *dev, struct list_head *list);

    /* Window handling functions */
    int (*domain_window_enable)(struct iommu_domain *domain, u32 wnd_nr,
                    phys_addr_t paddr, u64 size, int prot);
    void (*domain_window_disable)(struct iommu_domain *domain, u32 wnd_nr);
    /* Set the number of windows per domain */
    int (*domain_set_windows)(struct iommu_domain *domain, u32 w_count);
    /* Get the number of windows per domain */
    u32 (*domain_get_windows)(struct iommu_domain *domain);

#ifdef CONFIG_OF_IOMMU
    int (*of_xlate)(struct device *dev, struct of_phandle_args *args);
#endif

    unsigned long pgsize_bitmap;
    void *priv;
};