Merge branch 'linus' into x86/amd-iommu
authorIngo Molnar <mingo@elte.hu>
Fri, 18 Jul 2008 16:43:08 +0000 (18:43 +0200)
committerIngo Molnar <mingo@elte.hu>
Fri, 18 Jul 2008 16:43:08 +0000 (18:43 +0200)
arch/x86/kernel/amd_iommu.c
arch/x86/kernel/amd_iommu_init.c
include/asm-x86/amd_iommu_types.h

index f2766d84c7a00c78c4f24951a7f2912f550ef475..8c3deb027d3acf66408732bb998a62c7a0eb9f48 100644 (file)
 #define to_pages(addr, size) \
         (round_up(((addr) & ~PAGE_MASK) + (size), PAGE_SIZE) >> PAGE_SHIFT)
 
+#define EXIT_LOOP_COUNT 10000000
+
 static DEFINE_RWLOCK(amd_iommu_devtable_lock);
 
-struct command {
+/*
+ * general struct to manage commands send to an IOMMU
+ */
+struct iommu_cmd {
        u32 data[4];
 };
 
 static int dma_ops_unity_map(struct dma_ops_domain *dma_dom,
                             struct unity_map_entry *e);
 
+/* returns !0 if the IOMMU is caching non-present entries in its TLB */
 static int iommu_has_npcache(struct amd_iommu *iommu)
 {
        return iommu->cap & IOMMU_CAP_NPCACHE;
 }
 
-static int __iommu_queue_command(struct amd_iommu *iommu, struct command *cmd)
+/****************************************************************************
+ *
+ * IOMMU command queuing functions
+ *
+ ****************************************************************************/
+
+/*
+ * Writes the command to the IOMMUs command buffer and informs the
+ * hardware about the new command. Must be called with iommu->lock held.
+ */
+static int __iommu_queue_command(struct amd_iommu *iommu, struct iommu_cmd *cmd)
 {
        u32 tail, head;
        u8 *target;
@@ -63,7 +79,11 @@ static int __iommu_queue_command(struct amd_iommu *iommu, struct command *cmd)
        return 0;
 }
 
-static int iommu_queue_command(struct amd_iommu *iommu, struct command *cmd)
+/*
+ * General queuing function for commands. Takes iommu->lock and calls
+ * __iommu_queue_command().
+ */
+static int iommu_queue_command(struct amd_iommu *iommu, struct iommu_cmd *cmd)
 {
        unsigned long flags;
        int ret;
@@ -75,16 +95,24 @@ static int iommu_queue_command(struct amd_iommu *iommu, struct command *cmd)
        return ret;
 }
 
+/*
+ * This function is called whenever we need to ensure that the IOMMU has
+ * completed execution of all commands we sent. It sends a
+ * COMPLETION_WAIT command and waits for it to finish. The IOMMU informs
+ * us about that by writing a value to a physical address we pass with
+ * the command.
+ */
 static int iommu_completion_wait(struct amd_iommu *iommu)
 {
        int ret;
-       struct command cmd;
+       struct iommu_cmd cmd;
        volatile u64 ready = 0;
        unsigned long ready_phys = virt_to_phys(&ready);
+       unsigned long i = 0;
 
        memset(&cmd, 0, sizeof(cmd));
        cmd.data[0] = LOW_U32(ready_phys) | CMD_COMPL_WAIT_STORE_MASK;
-       cmd.data[1] = HIGH_U32(ready_phys);
+       cmd.data[1] = upper_32_bits(ready_phys);
        cmd.data[2] = 1; /* value written to 'ready' */
        CMD_SET_TYPE(&cmd, CMD_COMPL_WAIT);
 
@@ -95,15 +123,23 @@ static int iommu_completion_wait(struct amd_iommu *iommu)
        if (ret)
                return ret;
 
-       while (!ready)
+       while (!ready && (i < EXIT_LOOP_COUNT)) {
+               ++i;
                cpu_relax();
+       }
+
+       if (unlikely((i == EXIT_LOOP_COUNT) && printk_ratelimit()))
+               printk(KERN_WARNING "AMD IOMMU: Completion wait loop failed\n");
 
        return 0;
 }
 
+/*
+ * Command send function for invalidating a device table entry
+ */
 static int iommu_queue_inv_dev_entry(struct amd_iommu *iommu, u16 devid)
 {
-       struct command cmd;
+       struct iommu_cmd cmd;
 
        BUG_ON(iommu == NULL);
 
@@ -116,20 +152,23 @@ static int iommu_queue_inv_dev_entry(struct amd_iommu *iommu, u16 devid)
        return iommu_queue_command(iommu, &cmd);
 }
 
+/*
+ * Generic command send function for invalidaing TLB entries
+ */
 static int iommu_queue_inv_iommu_pages(struct amd_iommu *iommu,
                u64 address, u16 domid, int pde, int s)
 {
-       struct command cmd;
+       struct iommu_cmd cmd;
 
        memset(&cmd, 0, sizeof(cmd));
        address &= PAGE_MASK;
        CMD_SET_TYPE(&cmd, CMD_INV_IOMMU_PAGES);
        cmd.data[1] |= domid;
        cmd.data[2] = LOW_U32(address);
-       cmd.data[3] = HIGH_U32(address);
-       if (s)
+       cmd.data[3] = upper_32_bits(address);
+       if (s) /* size bit - we flush more than one 4kb page */
                cmd.data[2] |= CMD_INV_IOMMU_PAGES_SIZE_MASK;
-       if (pde)
+       if (pde) /* PDE bit - we wan't flush everything not only the PTEs */
                cmd.data[2] |= CMD_INV_IOMMU_PAGES_PDE_MASK;
 
        iommu->need_sync = 1;
@@ -137,6 +176,11 @@ static int iommu_queue_inv_iommu_pages(struct amd_iommu *iommu,
        return iommu_queue_command(iommu, &cmd);
 }
 
+/*
+ * TLB invalidation function which is called from the mapping functions.
+ * It invalidates a single PTE if the range to flush is within a single
+ * page. Otherwise it flushes the whole TLB of the IOMMU.
+ */
 static int iommu_flush_pages(struct amd_iommu *iommu, u16 domid,
                u64 address, size_t size)
 {
@@ -159,6 +203,20 @@ static int iommu_flush_pages(struct amd_iommu *iommu, u16 domid,
        return 0;
 }
 
+/****************************************************************************
+ *
+ * The functions below are used the create the page table mappings for
+ * unity mapped regions.
+ *
+ ****************************************************************************/
+
+/*
+ * Generic mapping functions. It maps a physical address into a DMA
+ * address space. It allocates the page table pages if necessary.
+ * In the future it can be extended to a generic mapping function
+ * supporting all features of AMD IOMMU page tables like level skipping
+ * and full 64 bit address spaces.
+ */
 static int iommu_map(struct protection_domain *dom,
                     unsigned long bus_addr,
                     unsigned long phys_addr,
@@ -209,6 +267,10 @@ static int iommu_map(struct protection_domain *dom,
        return 0;
 }
 
+/*
+ * This function checks if a specific unity mapping entry is needed for
+ * this specific IOMMU.
+ */
 static int iommu_for_unity_map(struct amd_iommu *iommu,
                               struct unity_map_entry *entry)
 {
@@ -223,6 +285,12 @@ static int iommu_for_unity_map(struct amd_iommu *iommu,
        return 0;
 }
 
+/*
+ * Init the unity mappings for a specific IOMMU in the system
+ *
+ * Basically iterates over all unity mapping entries and applies them to
+ * the default domain DMA of that IOMMU if necessary.
+ */
 static int iommu_init_unity_mappings(struct amd_iommu *iommu)
 {
        struct unity_map_entry *entry;
@@ -239,6 +307,10 @@ static int iommu_init_unity_mappings(struct amd_iommu *iommu)
        return 0;
 }
 
+/*
+ * This function actually applies the mapping to the page table of the
+ * dma_ops domain.
+ */
 static int dma_ops_unity_map(struct dma_ops_domain *dma_dom,
                             struct unity_map_entry *e)
 {
@@ -261,6 +333,9 @@ static int dma_ops_unity_map(struct dma_ops_domain *dma_dom,
        return 0;
 }
 
+/*
+ * Inits the unity mappings required for a specific device
+ */
 static int init_unity_mappings_for_device(struct dma_ops_domain *dma_dom,
                                          u16 devid)
 {
@@ -278,12 +353,26 @@ static int init_unity_mappings_for_device(struct dma_ops_domain *dma_dom,
        return 0;
 }
 
+/****************************************************************************
+ *
+ * The next functions belong to the address allocator for the dma_ops
+ * interface functions. They work like the allocators in the other IOMMU
+ * drivers. Its basically a bitmap which marks the allocated pages in
+ * the aperture. Maybe it could be enhanced in the future to a more
+ * efficient allocator.
+ *
+ ****************************************************************************/
 static unsigned long dma_mask_to_pages(unsigned long mask)
 {
        return (mask >> PAGE_SHIFT) +
                (PAGE_ALIGN(mask & ~PAGE_MASK) >> PAGE_SHIFT);
 }
 
+/*
+ * The address allocator core function.
+ *
+ * called with domain->lock held
+ */
 static unsigned long dma_ops_alloc_addresses(struct device *dev,
                                             struct dma_ops_domain *dom,
                                             unsigned int pages)
@@ -317,6 +406,11 @@ static unsigned long dma_ops_alloc_addresses(struct device *dev,
        return address;
 }
 
+/*
+ * The address free function.
+ *
+ * called with domain->lock held
+ */
 static void dma_ops_free_addresses(struct dma_ops_domain *dom,
                                   unsigned long address,
                                   unsigned int pages)
@@ -325,6 +419,16 @@ static void dma_ops_free_addresses(struct dma_ops_domain *dom,
        iommu_area_free(dom->bitmap, address, pages);
 }
 
+/****************************************************************************
+ *
+ * The next functions belong to the domain allocation. A domain is
+ * allocated for every IOMMU as the default domain. If device isolation
+ * is enabled, every device get its own domain. The most important thing
+ * about domains is the page table mapping the DMA address space they
+ * contain.
+ *
+ ****************************************************************************/
+
 static u16 domain_id_alloc(void)
 {
        unsigned long flags;
@@ -342,6 +446,10 @@ static u16 domain_id_alloc(void)
        return id;
 }
 
+/*
+ * Used to reserve address ranges in the aperture (e.g. for exclusion
+ * ranges.
+ */
 static void dma_ops_reserve_addresses(struct dma_ops_domain *dom,
                                      unsigned long start_page,
                                      unsigned int pages)
@@ -382,6 +490,10 @@ static void dma_ops_free_pagetable(struct dma_ops_domain *dma_dom)
        free_page((unsigned long)p1);
 }
 
+/*
+ * Free a domain, only used if something went wrong in the
+ * allocation path and we need to free an already allocated page table
+ */
 static void dma_ops_domain_free(struct dma_ops_domain *dom)
 {
        if (!dom)
@@ -396,6 +508,11 @@ static void dma_ops_domain_free(struct dma_ops_domain *dom)
        kfree(dom);
 }
 
+/*
+ * Allocates a new protection domain usable for the dma_ops functions.
+ * It also intializes the page table and the address allocator data
+ * structures required for the dma_ops interface
+ */
 static struct dma_ops_domain *dma_ops_domain_alloc(struct amd_iommu *iommu,
                                                   unsigned order)
 {
@@ -436,6 +553,7 @@ static struct dma_ops_domain *dma_ops_domain_alloc(struct amd_iommu *iommu,
        dma_dom->bitmap[0] = 1;
        dma_dom->next_bit = 0;
 
+       /* Intialize the exclusion range if necessary */
        if (iommu->exclusion_start &&
            iommu->exclusion_start < dma_dom->aperture_size) {
                unsigned long startpage = iommu->exclusion_start >> PAGE_SHIFT;
@@ -444,6 +562,11 @@ static struct dma_ops_domain *dma_ops_domain_alloc(struct amd_iommu *iommu,
                dma_ops_reserve_addresses(dma_dom, startpage, pages);
        }
 
+       /*
+        * At the last step, build the page tables so we don't need to
+        * allocate page table pages in the dma_ops mapping/unmapping
+        * path.
+        */
        num_pte_pages = dma_dom->aperture_size / (PAGE_SIZE * 512);
        dma_dom->pte_pages = kzalloc(num_pte_pages * sizeof(void *),
                        GFP_KERNEL);
@@ -472,6 +595,10 @@ free_dma_dom:
        return NULL;
 }
 
+/*
+ * Find out the protection domain structure for a given PCI device. This
+ * will give us the pointer to the page table root for example.
+ */
 static struct protection_domain *domain_for_device(u16 devid)
 {
        struct protection_domain *dom;
@@ -484,6 +611,10 @@ static struct protection_domain *domain_for_device(u16 devid)
        return dom;
 }
 
+/*
+ * If a device is not yet associated with a domain, this function does
+ * assigns it visible for the hardware
+ */
 static void set_device_domain(struct amd_iommu *iommu,
                              struct protection_domain *domain,
                              u16 devid)
@@ -508,6 +639,19 @@ static void set_device_domain(struct amd_iommu *iommu,
        iommu->need_sync = 1;
 }
 
+/*****************************************************************************
+ *
+ * The next functions belong to the dma_ops mapping/unmapping code.
+ *
+ *****************************************************************************/
+
+/*
+ * In the dma_ops path we only have the struct device. This function
+ * finds the corresponding IOMMU, the protection domain and the
+ * requestor id for a given device.
+ * If the device is not yet associated with a domain this is also done
+ * in this function.
+ */
 static int get_device_resources(struct device *dev,
                                struct amd_iommu **iommu,
                                struct protection_domain **domain,
@@ -520,8 +664,9 @@ static int get_device_resources(struct device *dev,
        BUG_ON(!dev || dev->bus != &pci_bus_type || !dev->dma_mask);
 
        pcidev = to_pci_dev(dev);
-       _bdf = (pcidev->bus->number << 8) | pcidev->devfn;
+       _bdf = calc_devid(pcidev->bus->number, pcidev->devfn);
 
+       /* device not translated by any IOMMU in the system? */
        if (_bdf >= amd_iommu_last_bdf) {
                *iommu = NULL;
                *domain = NULL;
@@ -547,6 +692,10 @@ static int get_device_resources(struct device *dev,
        return 1;
 }
 
+/*
+ * This is the generic map function. It maps one 4kb page at paddr to
+ * the given address in the DMA address space for the domain.
+ */
 static dma_addr_t dma_ops_domain_map(struct amd_iommu *iommu,
                                     struct dma_ops_domain *dom,
                                     unsigned long address,
@@ -578,6 +727,9 @@ static dma_addr_t dma_ops_domain_map(struct amd_iommu *iommu,
        return (dma_addr_t)address;
 }
 
+/*
+ * The generic unmapping function for on page in the DMA address space.
+ */
 static void dma_ops_domain_unmap(struct amd_iommu *iommu,
                                 struct dma_ops_domain *dom,
                                 unsigned long address)
@@ -597,6 +749,12 @@ static void dma_ops_domain_unmap(struct amd_iommu *iommu,
        *pte = 0ULL;
 }
 
+/*
+ * This function contains common code for mapping of a physically
+ * contiguous memory region into DMA address space. It is uses by all
+ * mapping functions provided by this IOMMU driver.
+ * Must be called with the domain lock held.
+ */
 static dma_addr_t __map_single(struct device *dev,
                               struct amd_iommu *iommu,
                               struct dma_ops_domain *dma_dom,
@@ -628,6 +786,10 @@ out:
        return address;
 }
 
+/*
+ * Does the reverse of the __map_single function. Must be called with
+ * the domain lock held too
+ */
 static void __unmap_single(struct amd_iommu *iommu,
                           struct dma_ops_domain *dma_dom,
                           dma_addr_t dma_addr,
@@ -652,6 +814,9 @@ static void __unmap_single(struct amd_iommu *iommu,
        dma_ops_free_addresses(dma_dom, dma_addr, pages);
 }
 
+/*
+ * The exported map_single function for dma_ops.
+ */
 static dma_addr_t map_single(struct device *dev, phys_addr_t paddr,
                             size_t size, int dir)
 {
@@ -664,6 +829,7 @@ static dma_addr_t map_single(struct device *dev, phys_addr_t paddr,
        get_device_resources(dev, &iommu, &domain, &devid);
 
        if (iommu == NULL || domain == NULL)
+               /* device not handled by any AMD IOMMU */
                return (dma_addr_t)paddr;
 
        spin_lock_irqsave(&domain->lock, flags);
@@ -683,6 +849,9 @@ out:
        return addr;
 }
 
+/*
+ * The exported unmap_single function for dma_ops.
+ */
 static void unmap_single(struct device *dev, dma_addr_t dma_addr,
                         size_t size, int dir)
 {
@@ -692,6 +861,7 @@ static void unmap_single(struct device *dev, dma_addr_t dma_addr,
        u16 devid;
 
        if (!get_device_resources(dev, &iommu, &domain, &devid))
+               /* device not handled by any AMD IOMMU */
                return;
 
        spin_lock_irqsave(&domain->lock, flags);
@@ -706,6 +876,10 @@ static void unmap_single(struct device *dev, dma_addr_t dma_addr,
        spin_unlock_irqrestore(&domain->lock, flags);
 }
 
+/*
+ * This is a special map_sg function which is used if we should map a
+ * device which is not handled by an AMD IOMMU in the system.
+ */
 static int map_sg_no_iommu(struct device *dev, struct scatterlist *sglist,
                           int nelems, int dir)
 {
@@ -720,6 +894,10 @@ static int map_sg_no_iommu(struct device *dev, struct scatterlist *sglist,
        return nelems;
 }
 
+/*
+ * The exported map_sg function for dma_ops (handles scatter-gather
+ * lists).
+ */
 static int map_sg(struct device *dev, struct scatterlist *sglist,
                  int nelems, int dir)
 {
@@ -775,6 +953,10 @@ unmap:
        goto out;
 }
 
+/*
+ * The exported map_sg function for dma_ops (handles scatter-gather
+ * lists).
+ */
 static void unmap_sg(struct device *dev, struct scatterlist *sglist,
                     int nelems, int dir)
 {
@@ -804,6 +986,9 @@ static void unmap_sg(struct device *dev, struct scatterlist *sglist,
        spin_unlock_irqrestore(&domain->lock, flags);
 }
 
+/*
+ * The exported alloc_coherent function for dma_ops.
+ */
 static void *alloc_coherent(struct device *dev, size_t size,
                            dma_addr_t *dma_addr, gfp_t flag)
 {
@@ -851,6 +1036,11 @@ out:
        return virt_addr;
 }
 
+/*
+ * The exported free_coherent function for dma_ops.
+ * FIXME: fix the generic x86 DMA layer so that it actually calls that
+ *        function.
+ */
 static void free_coherent(struct device *dev, size_t size,
                          void *virt_addr, dma_addr_t dma_addr)
 {
@@ -879,6 +1069,8 @@ free_mem:
 }
 
 /*
+ * The function for pre-allocating protection domains.
+ *
  * If the driver core informs the DMA layer if a driver grabs a device
  * we don't need to preallocate the protection domains anymore.
  * For now we have to.
@@ -921,12 +1113,20 @@ static struct dma_mapping_ops amd_iommu_dma_ops = {
        .unmap_sg = unmap_sg,
 };
 
+/*
+ * The function which clues the AMD IOMMU driver into dma_ops.
+ */
 int __init amd_iommu_init_dma_ops(void)
 {
        struct amd_iommu *iommu;
        int order = amd_iommu_aperture_order;
        int ret;
 
+       /*
+        * first allocate a default protection domain for every IOMMU we
+        * found in the system. Devices not assigned to any other
+        * protection domain will be assigned to the default one.
+        */
        list_for_each_entry(iommu, &amd_iommu_list, list) {
                iommu->default_dom = dma_ops_domain_alloc(iommu, order);
                if (iommu->default_dom == NULL)
@@ -936,6 +1136,10 @@ int __init amd_iommu_init_dma_ops(void)
                        goto free_domains;
        }
 
+       /*
+        * If device isolation is enabled, pre-allocate the protection
+        * domains for each device.
+        */
        if (amd_iommu_isolate)
                prealloc_protection_domains();
 
@@ -947,6 +1151,7 @@ int __init amd_iommu_init_dma_ops(void)
        gart_iommu_aperture = 0;
 #endif
 
+       /* Make the driver finally visible to the drivers */
        dma_ops = &amd_iommu_dma_ops;
 
        return 0;
index 2a13e430437dc5f1e05793aa995df4befcbc8938..9bf1b8111b08b042b8b259431e454e120ccfd244 100644 (file)
 /*
  * definitions for the ACPI scanning code
  */
-#define UPDATE_LAST_BDF(x) do {\
-       if ((x) > amd_iommu_last_bdf) \
-               amd_iommu_last_bdf = (x); \
-       } while (0);
-
-#define DEVID(bus, devfn) (((bus) << 8) | (devfn))
 #define PCI_BUS(x) (((x) >> 8) & 0xff)
 #define IVRS_HEADER_LENGTH 48
-#define TBL_SIZE(x) (1 << (PAGE_SHIFT + get_order(amd_iommu_last_bdf * (x))))
 
 #define ACPI_IVHD_TYPE                  0x10
 #define ACPI_IVMD_TYPE_ALL              0x20
 #define ACPI_DEVFLAG_LINT1              0x80
 #define ACPI_DEVFLAG_ATSDIS             0x10000000
 
+/*
+ * ACPI table definitions
+ *
+ * These data structures are laid over the table to parse the important values
+ * out of it.
+ */
+
+/*
+ * structure describing one IOMMU in the ACPI table. Typically followed by one
+ * or more ivhd_entrys.
+ */
 struct ivhd_header {
        u8 type;
        u8 flags;
@@ -83,6 +87,10 @@ struct ivhd_header {
        u32 reserved;
 } __attribute__((packed));
 
+/*
+ * A device entry describing which devices a specific IOMMU translates and
+ * which requestor ids they use.
+ */
 struct ivhd_entry {
        u8 type;
        u16 devid;
@@ -90,6 +98,10 @@ struct ivhd_entry {
        u32 ext;
 } __attribute__((packed));
 
+/*
+ * An AMD IOMMU memory definition structure. It defines things like exclusion
+ * ranges for devices and regions that should be unity mapped.
+ */
 struct ivmd_header {
        u8 type;
        u8 flags;
@@ -103,22 +115,80 @@ struct ivmd_header {
 
 static int __initdata amd_iommu_detected;
 
-u16 amd_iommu_last_bdf;
-struct list_head amd_iommu_unity_map;
-unsigned amd_iommu_aperture_order = 26;
-int amd_iommu_isolate;
+u16 amd_iommu_last_bdf;                        /* largest PCI device id we have
+                                          to handle */
+LIST_HEAD(amd_iommu_unity_map);                /* a list of required unity mappings
+                                          we find in ACPI */
+unsigned amd_iommu_aperture_order = 26; /* size of aperture in power of 2 */
+int amd_iommu_isolate;                 /* if 1, device isolation is enabled */
+
+LIST_HEAD(amd_iommu_list);             /* list of all AMD IOMMUs in the
+                                          system */
 
-struct list_head amd_iommu_list;
+/*
+ * Pointer to the device table which is shared by all AMD IOMMUs
+ * it is indexed by the PCI device id or the HT unit id and contains
+ * information about the domain the device belongs to as well as the
+ * page table root pointer.
+ */
 struct dev_table_entry *amd_iommu_dev_table;
+
+/*
+ * The alias table is a driver specific data structure which contains the
+ * mappings of the PCI device ids to the actual requestor ids on the IOMMU.
+ * More than one device can share the same requestor id.
+ */
 u16 *amd_iommu_alias_table;
+
+/*
+ * The rlookup table is used to find the IOMMU which is responsible
+ * for a specific device. It is also indexed by the PCI device id.
+ */
 struct amd_iommu **amd_iommu_rlookup_table;
+
+/*
+ * The pd table (protection domain table) is used to find the protection domain
+ * data structure a device belongs to. Indexed with the PCI device id too.
+ */
 struct protection_domain **amd_iommu_pd_table;
+
+/*
+ * AMD IOMMU allows up to 2^16 differend protection domains. This is a bitmap
+ * to know which ones are already in use.
+ */
 unsigned long *amd_iommu_pd_alloc_bitmap;
 
-static u32 dev_table_size;
-static u32 alias_table_size;
-static u32 rlookup_table_size;
+static u32 dev_table_size;     /* size of the device table */
+static u32 alias_table_size;   /* size of the alias table */
+static u32 rlookup_table_size; /* size if the rlookup table */
+
+static inline void update_last_devid(u16 devid)
+{
+       if (devid > amd_iommu_last_bdf)
+               amd_iommu_last_bdf = devid;
+}
+
+static inline unsigned long tbl_size(int entry_size)
+{
+       unsigned shift = PAGE_SHIFT +
+                        get_order(amd_iommu_last_bdf * entry_size);
+
+       return 1UL << shift;
+}
 
+/****************************************************************************
+ *
+ * AMD IOMMU MMIO register space handling functions
+ *
+ * These functions are used to program the IOMMU device registers in
+ * MMIO space required for that driver.
+ *
+ ****************************************************************************/
+
+/*
+ * This function set the exclusion range in the IOMMU. DMA accesses to the
+ * exclusion range are passed through untranslated
+ */
 static void __init iommu_set_exclusion_range(struct amd_iommu *iommu)
 {
        u64 start = iommu->exclusion_start & PAGE_MASK;
@@ -137,6 +207,7 @@ static void __init iommu_set_exclusion_range(struct amd_iommu *iommu)
                        &entry, sizeof(entry));
 }
 
+/* Programs the physical address of the device table into the IOMMU hardware */
 static void __init iommu_set_device_table(struct amd_iommu *iommu)
 {
        u32 entry;
@@ -149,6 +220,7 @@ static void __init iommu_set_device_table(struct amd_iommu *iommu)
                        &entry, sizeof(entry));
 }
 
+/* Generic functions to enable/disable certain features of the IOMMU. */
 static void __init iommu_feature_enable(struct amd_iommu *iommu, u8 bit)
 {
        u32 ctrl;
@@ -167,6 +239,7 @@ static void __init iommu_feature_disable(struct amd_iommu *iommu, u8 bit)
        writel(ctrl, iommu->mmio_base + MMIO_CONTROL_OFFSET);
 }
 
+/* Function to enable the hardware */
 void __init iommu_enable(struct amd_iommu *iommu)
 {
        printk(KERN_INFO "AMD IOMMU: Enabling IOMMU at ");
@@ -176,6 +249,10 @@ void __init iommu_enable(struct amd_iommu *iommu)
        iommu_feature_enable(iommu, CONTROL_IOMMU_EN);
 }
 
+/*
+ * mapping and unmapping functions for the IOMMU MMIO space. Each AMD IOMMU in
+ * the system has one.
+ */
 static u8 * __init iommu_map_mmio_space(u64 address)
 {
        u8 *ret;
@@ -199,16 +276,33 @@ static void __init iommu_unmap_mmio_space(struct amd_iommu *iommu)
        release_mem_region(iommu->mmio_phys, MMIO_REGION_LENGTH);
 }
 
+/****************************************************************************
+ *
+ * The functions below belong to the first pass of AMD IOMMU ACPI table
+ * parsing. In this pass we try to find out the highest device id this
+ * code has to handle. Upon this information the size of the shared data
+ * structures is determined later.
+ *
+ ****************************************************************************/
+
+/*
+ * This function reads the last device id the IOMMU has to handle from the PCI
+ * capability header for this IOMMU
+ */
 static int __init find_last_devid_on_pci(int bus, int dev, int fn, int cap_ptr)
 {
        u32 cap;
 
        cap = read_pci_config(bus, dev, fn, cap_ptr+MMIO_RANGE_OFFSET);
-       UPDATE_LAST_BDF(DEVID(MMIO_GET_BUS(cap), MMIO_GET_LD(cap)));
+       update_last_devid(calc_devid(MMIO_GET_BUS(cap), MMIO_GET_LD(cap)));
 
        return 0;
 }
 
+/*
+ * After reading the highest device id from the IOMMU PCI capability header
+ * this function looks if there is a higher device id defined in the ACPI table
+ */
 static int __init find_last_devid_from_ivhd(struct ivhd_header *h)
 {
        u8 *p = (void *)h, *end = (void *)h;
@@ -229,7 +323,8 @@ static int __init find_last_devid_from_ivhd(struct ivhd_header *h)
                case IVHD_DEV_RANGE_END:
                case IVHD_DEV_ALIAS:
                case IVHD_DEV_EXT_SELECT:
-                       UPDATE_LAST_BDF(dev->devid);
+                       /* all the above subfield types refer to device ids */
+                       update_last_devid(dev->devid);
                        break;
                default:
                        break;
@@ -242,6 +337,11 @@ static int __init find_last_devid_from_ivhd(struct ivhd_header *h)
        return 0;
 }
 
+/*
+ * Iterate over all IVHD entries in the ACPI table and find the highest device
+ * id which we need to handle. This is the first of three functions which parse
+ * the ACPI table. So we check the checksum here.
+ */
 static int __init find_last_devid_acpi(struct acpi_table_header *table)
 {
        int i;
@@ -277,19 +377,31 @@ static int __init find_last_devid_acpi(struct acpi_table_header *table)
        return 0;
 }
 
+/****************************************************************************
+ *
+ * The following functions belong the the code path which parses the ACPI table
+ * the second time. In this ACPI parsing iteration we allocate IOMMU specific
+ * data structures, initialize the device/alias/rlookup table and also
+ * basically initialize the hardware.
+ *
+ ****************************************************************************/
+
+/*
+ * Allocates the command buffer. This buffer is per AMD IOMMU. We can
+ * write commands to that buffer later and the IOMMU will execute them
+ * asynchronously
+ */
 static u8 * __init alloc_command_buffer(struct amd_iommu *iommu)
 {
-       u8 *cmd_buf = (u8 *)__get_free_pages(GFP_KERNEL,
+       u8 *cmd_buf = (u8 *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
                        get_order(CMD_BUFFER_SIZE));
-       u64 entry = 0;
+       u64 entry;
 
        if (cmd_buf == NULL)
                return NULL;
 
        iommu->cmd_buf_size = CMD_BUFFER_SIZE;
 
-       memset(cmd_buf, 0, CMD_BUFFER_SIZE);
-
        entry = (u64)virt_to_phys(cmd_buf);
        entry |= MMIO_CMD_SIZE_512;
        memcpy_toio(iommu->mmio_base + MMIO_CMD_BUF_OFFSET,
@@ -302,11 +414,10 @@ static u8 * __init alloc_command_buffer(struct amd_iommu *iommu)
 
 static void __init free_command_buffer(struct amd_iommu *iommu)
 {
-       if (iommu->cmd_buf)
-               free_pages((unsigned long)iommu->cmd_buf,
-                               get_order(CMD_BUFFER_SIZE));
+       free_pages((unsigned long)iommu->cmd_buf, get_order(CMD_BUFFER_SIZE));
 }
 
+/* sets a specific bit in the device table entry. */
 static void set_dev_entry_bit(u16 devid, u8 bit)
 {
        int i = (bit >> 5) & 0x07;
@@ -315,6 +426,10 @@ static void set_dev_entry_bit(u16 devid, u8 bit)
        amd_iommu_dev_table[devid].data[i] |= (1 << _bit);
 }
 
+/*
+ * This function takes the device specific flags read from the ACPI
+ * table and sets up the device table entry with that information
+ */
 static void __init set_dev_entry_from_acpi(u16 devid, u32 flags, u32 ext_flags)
 {
        if (flags & ACPI_DEVFLAG_INITPASS)
@@ -333,11 +448,16 @@ static void __init set_dev_entry_from_acpi(u16 devid, u32 flags, u32 ext_flags)
                set_dev_entry_bit(devid, DEV_ENTRY_LINT1_PASS);
 }
 
+/* Writes the specific IOMMU for a device into the rlookup table */
 static void __init set_iommu_for_device(struct amd_iommu *iommu, u16 devid)
 {
        amd_iommu_rlookup_table[devid] = iommu;
 }
 
+/*
+ * Reads the device exclusion range from ACPI and initialize IOMMU with
+ * it
+ */
 static void __init set_device_exclusion_range(u16 devid, struct ivmd_header *m)
 {
        struct amd_iommu *iommu = amd_iommu_rlookup_table[devid];
@@ -346,12 +466,22 @@ static void __init set_device_exclusion_range(u16 devid, struct ivmd_header *m)
                return;
 
        if (iommu) {
+               /*
+                * We only can configure exclusion ranges per IOMMU, not
+                * per device. But we can enable the exclusion range per
+                * device. This is done here
+                */
                set_dev_entry_bit(m->devid, DEV_ENTRY_EX);
                iommu->exclusion_start = m->range_start;
                iommu->exclusion_length = m->range_length;
        }
 }
 
+/*
+ * This function reads some important data from the IOMMU PCI space and
+ * initializes the driver data structure with it. It reads the hardware
+ * capabilities and the first/last device entries
+ */
 static void __init init_iommu_from_pci(struct amd_iommu *iommu)
 {
        int bus = PCI_BUS(iommu->devid);
@@ -363,10 +493,16 @@ static void __init init_iommu_from_pci(struct amd_iommu *iommu)
        iommu->cap = read_pci_config(bus, dev, fn, cap_ptr+MMIO_CAP_HDR_OFFSET);
 
        range = read_pci_config(bus, dev, fn, cap_ptr+MMIO_RANGE_OFFSET);
-       iommu->first_device = DEVID(MMIO_GET_BUS(range), MMIO_GET_FD(range));
-       iommu->last_device = DEVID(MMIO_GET_BUS(range), MMIO_GET_LD(range));
+       iommu->first_device = calc_devid(MMIO_GET_BUS(range),
+                                        MMIO_GET_FD(range));
+       iommu->last_device = calc_devid(MMIO_GET_BUS(range),
+                                       MMIO_GET_LD(range));
 }
 
+/*
+ * Takes a pointer to an AMD IOMMU entry in the ACPI table and
+ * initializes the hardware and our data structures with it.
+ */
 static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
                                        struct ivhd_header *h)
 {
@@ -374,7 +510,7 @@ static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
        u8 *end = p, flags = 0;
        u16 dev_i, devid = 0, devid_start = 0, devid_to = 0;
        u32 ext_flags = 0;
-       bool alias = 0;
+       bool alias = false;
        struct ivhd_entry *e;
 
        /*
@@ -424,7 +560,7 @@ static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
                        devid_start = e->devid;
                        flags = e->flags;
                        ext_flags = 0;
-                       alias = 0;
+                       alias = false;
                        break;
                case IVHD_DEV_ALIAS:
                        devid = e->devid;
@@ -437,7 +573,7 @@ static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
                        flags = e->flags;
                        devid_to = e->ext >> 8;
                        ext_flags = 0;
-                       alias = 1;
+                       alias = true;
                        break;
                case IVHD_DEV_EXT_SELECT:
                        devid = e->devid;
@@ -447,7 +583,7 @@ static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
                        devid_start = e->devid;
                        flags = e->flags;
                        ext_flags = e->ext;
-                       alias = 0;
+                       alias = false;
                        break;
                case IVHD_DEV_RANGE_END:
                        devid = e->devid;
@@ -467,6 +603,7 @@ static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
        }
 }
 
+/* Initializes the device->iommu mapping for the driver */
 static int __init init_iommu_devices(struct amd_iommu *iommu)
 {
        u16 i;
@@ -494,6 +631,11 @@ static void __init free_iommu_all(void)
        }
 }
 
+/*
+ * This function clues the initialization function for one IOMMU
+ * together and also allocates the command buffer and programs the
+ * hardware. It does NOT enable the IOMMU. This is done afterwards.
+ */
 static int __init init_iommu_one(struct amd_iommu *iommu, struct ivhd_header *h)
 {
        spin_lock_init(&iommu->lock);
@@ -521,6 +663,10 @@ static int __init init_iommu_one(struct amd_iommu *iommu, struct ivhd_header *h)
        return 0;
 }
 
+/*
+ * Iterates over all IOMMU entries in the ACPI table, allocates the
+ * IOMMU structure and initializes it with init_iommu_one()
+ */
 static int __init init_iommu_all(struct acpi_table_header *table)
 {
        u8 *p = (u8 *)table, *end = (u8 *)table;
@@ -528,8 +674,6 @@ static int __init init_iommu_all(struct acpi_table_header *table)
        struct amd_iommu *iommu;
        int ret;
 
-       INIT_LIST_HEAD(&amd_iommu_list);
-
        end += table->length;
        p += IVRS_HEADER_LENGTH;
 
@@ -555,6 +699,14 @@ static int __init init_iommu_all(struct acpi_table_header *table)
        return 0;
 }
 
+/****************************************************************************
+ *
+ * The next functions belong to the third pass of parsing the ACPI
+ * table. In this last pass the memory mapping requirements are
+ * gathered (like exclusion and unity mapping reanges).
+ *
+ ****************************************************************************/
+
 static void __init free_unity_maps(void)
 {
        struct unity_map_entry *entry, *next;
@@ -565,6 +717,7 @@ static void __init free_unity_maps(void)
        }
 }
 
+/* called when we find an exclusion range definition in ACPI */
 static int __init init_exclusion_range(struct ivmd_header *m)
 {
        int i;
@@ -588,6 +741,7 @@ static int __init init_exclusion_range(struct ivmd_header *m)
        return 0;
 }
 
+/* called for unity map ACPI definition */
 static int __init init_unity_map_range(struct ivmd_header *m)
 {
        struct unity_map_entry *e = 0;
@@ -619,13 +773,12 @@ static int __init init_unity_map_range(struct ivmd_header *m)
        return 0;
 }
 
+/* iterates over all memory definitions we find in the ACPI table */
 static int __init init_memory_definitions(struct acpi_table_header *table)
 {
        u8 *p = (u8 *)table, *end = (u8 *)table;
        struct ivmd_header *m;
 
-       INIT_LIST_HEAD(&amd_iommu_unity_map);
-
        end += table->length;
        p += IVRS_HEADER_LENGTH;
 
@@ -642,6 +795,10 @@ static int __init init_memory_definitions(struct acpi_table_header *table)
        return 0;
 }
 
+/*
+ * This function finally enables all IOMMUs found in the system after
+ * they have been initialized
+ */
 static void __init enable_iommus(void)
 {
        struct amd_iommu *iommu;
@@ -678,6 +835,34 @@ static struct sys_device device_amd_iommu = {
        .cls = &amd_iommu_sysdev_class,
 };
 
+/*
+ * This is the core init function for AMD IOMMU hardware in the system.
+ * This function is called from the generic x86 DMA layer initialization
+ * code.
+ *
+ * This function basically parses the ACPI table for AMD IOMMU (IVRS)
+ * three times:
+ *
+ *     1 pass) Find the highest PCI device id the driver has to handle.
+ *             Upon this information the size of the data structures is
+ *             determined that needs to be allocated.
+ *
+ *     2 pass) Initialize the data structures just allocated with the
+ *             information in the ACPI table about available AMD IOMMUs
+ *             in the system. It also maps the PCI devices in the
+ *             system to specific IOMMUs
+ *
+ *     3 pass) After the basic data structures are allocated and
+ *             initialized we update them with information about memory
+ *             remapping requirements parsed out of the ACPI table in
+ *             this last pass.
+ *
+ * After that the hardware is initialized and ready to go. In the last
+ * step we do some Linux specific things like registering the driver in
+ * the dma_ops interface and initializing the suspend/resume support
+ * functions. Finally it prints some information about AMD IOMMUs and
+ * the driver state and enables the hardware.
+ */
 int __init amd_iommu_init(void)
 {
        int i, ret = 0;
@@ -699,14 +884,14 @@ int __init amd_iommu_init(void)
        if (acpi_table_parse("IVRS", find_last_devid_acpi) != 0)
                return -ENODEV;
 
-       dev_table_size     = TBL_SIZE(DEV_TABLE_ENTRY_SIZE);
-       alias_table_size   = TBL_SIZE(ALIAS_TABLE_ENTRY_SIZE);
-       rlookup_table_size = TBL_SIZE(RLOOKUP_TABLE_ENTRY_SIZE);
+       dev_table_size     = tbl_size(DEV_TABLE_ENTRY_SIZE);
+       alias_table_size   = tbl_size(ALIAS_TABLE_ENTRY_SIZE);
+       rlookup_table_size = tbl_size(RLOOKUP_TABLE_ENTRY_SIZE);
 
        ret = -ENOMEM;
 
        /* Device table - directly used by all IOMMUs */
-       amd_iommu_dev_table = (void *)__get_free_pages(GFP_KERNEL,
+       amd_iommu_dev_table = (void *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
                                      get_order(dev_table_size));
        if (amd_iommu_dev_table == NULL)
                goto out;
@@ -730,27 +915,23 @@ int __init amd_iommu_init(void)
         * Protection Domain table - maps devices to protection domains
         * This table has the same size as the rlookup_table
         */
-       amd_iommu_pd_table = (void *)__get_free_pages(GFP_KERNEL,
+       amd_iommu_pd_table = (void *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
                                     get_order(rlookup_table_size));
        if (amd_iommu_pd_table == NULL)
                goto free;
 
-       amd_iommu_pd_alloc_bitmap = (void *)__get_free_pages(GFP_KERNEL,
+       amd_iommu_pd_alloc_bitmap = (void *)__get_free_pages(
+                                           GFP_KERNEL | __GFP_ZERO,
                                            get_order(MAX_DOMAIN_ID/8));
        if (amd_iommu_pd_alloc_bitmap == NULL)
                goto free;
 
        /*
-        * memory is allocated now; initialize the device table with all zeroes
-        * and let all alias entries point to itself
+        * let all alias entries point to itself
         */
-       memset(amd_iommu_dev_table, 0, dev_table_size);
        for (i = 0; i < amd_iommu_last_bdf; ++i)
                amd_iommu_alias_table[i] = i;
 
-       memset(amd_iommu_pd_table, 0, rlookup_table_size);
-       memset(amd_iommu_pd_alloc_bitmap, 0, MAX_DOMAIN_ID / 8);
-
        /*
         * never allocate domain 0 because its used as the non-allocated and
         * error value placeholder
@@ -795,24 +976,19 @@ out:
        return ret;
 
 free:
-       if (amd_iommu_pd_alloc_bitmap)
-               free_pages((unsigned long)amd_iommu_pd_alloc_bitmap, 1);
+       free_pages((unsigned long)amd_iommu_pd_alloc_bitmap, 1);
 
-       if (amd_iommu_pd_table)
-               free_pages((unsigned long)amd_iommu_pd_table,
-                               get_order(rlookup_table_size));
+       free_pages((unsigned long)amd_iommu_pd_table,
+                  get_order(rlookup_table_size));
 
-       if (amd_iommu_rlookup_table)
-               free_pages((unsigned long)amd_iommu_rlookup_table,
-                               get_order(rlookup_table_size));
+       free_pages((unsigned long)amd_iommu_rlookup_table,
+                  get_order(rlookup_table_size));
 
-       if (amd_iommu_alias_table)
-               free_pages((unsigned long)amd_iommu_alias_table,
-                               get_order(alias_table_size));
+       free_pages((unsigned long)amd_iommu_alias_table,
+                  get_order(alias_table_size));
 
-       if (amd_iommu_dev_table)
-               free_pages((unsigned long)amd_iommu_dev_table,
-                               get_order(dev_table_size));
+       free_pages((unsigned long)amd_iommu_dev_table,
+                  get_order(dev_table_size));
 
        free_iommu_all();
 
@@ -821,6 +997,13 @@ free:
        goto out;
 }
 
+/****************************************************************************
+ *
+ * Early detect code. This code runs at IOMMU detection time in the DMA
+ * layer. It just looks if there is an IVRS ACPI table to detect AMD
+ * IOMMUs
+ *
+ ****************************************************************************/
 static int __init early_amd_iommu_detect(struct acpi_table_header *table)
 {
        return 0;
@@ -828,7 +1011,7 @@ static int __init early_amd_iommu_detect(struct acpi_table_header *table)
 
 void __init amd_iommu_detect(void)
 {
-       if (swiotlb || no_iommu || iommu_detected)
+       if (swiotlb || no_iommu || (iommu_detected && !gart_iommu_aperture))
                return;
 
        if (acpi_table_parse("IVRS", early_amd_iommu_detect) == 0) {
@@ -841,6 +1024,13 @@ void __init amd_iommu_detect(void)
        }
 }
 
+/****************************************************************************
+ *
+ * Parsing functions for the AMD IOMMU specific kernel command line
+ * options.
+ *
+ ****************************************************************************/
+
 static int __init parse_amd_iommu_options(char *str)
 {
        for (; *str; ++str) {
@@ -853,20 +1043,10 @@ static int __init parse_amd_iommu_options(char *str)
 
 static int __init parse_amd_iommu_size_options(char *str)
 {
-       for (; *str; ++str) {
-               if (strcmp(str, "32M") == 0)
-                       amd_iommu_aperture_order = 25;
-               if (strcmp(str, "64M") == 0)
-                       amd_iommu_aperture_order = 26;
-               if (strcmp(str, "128M") == 0)
-                       amd_iommu_aperture_order = 27;
-               if (strcmp(str, "256M") == 0)
-                       amd_iommu_aperture_order = 28;
-               if (strcmp(str, "512M") == 0)
-                       amd_iommu_aperture_order = 29;
-               if (strcmp(str, "1G") == 0)
-                       amd_iommu_aperture_order = 30;
-       }
+       unsigned order = PAGE_SHIFT + get_order(memparse(str, &str));
+
+       if ((order > 24) && (order < 31))
+               amd_iommu_aperture_order = order;
 
        return 1;
 }
index 7bfcb47cc452d5dc27ce2bf34c7cb22acddec7b7..22aa58ca1991c3003565f8fbc0313f3cf37b9d92 100644 (file)
 /*
  * some size calculation constants
  */
-#define DEV_TABLE_ENTRY_SIZE           256
+#define DEV_TABLE_ENTRY_SIZE           32
 #define ALIAS_TABLE_ENTRY_SIZE         2
 #define RLOOKUP_TABLE_ENTRY_SIZE       (sizeof(void *))
 
 /* helper macros */
 #define LOW_U32(x) ((x) & ((1ULL << 32)-1))
-#define HIGH_U32(x) (LOW_U32((x) >> 32))
 
 /* Length of the MMIO region for the AMD IOMMU */
 #define MMIO_REGION_LENGTH       0x4000
 
 #define MAX_DOMAIN_ID 65536
 
+/*
+ * This structure contains generic data for  IOMMU protection domains
+ * independent of their use.
+ */
 struct protection_domain {
-       spinlock_t lock;
-       u16 id;
-       int mode;
-       u64 *pt_root;
-       void *priv;
+       spinlock_t lock; /* mostly used to lock the page table*/
+       u16 id;          /* the domain id written to the device table */
+       int mode;        /* paging mode (0-6 levels) */
+       u64 *pt_root;    /* page table root pointer */
+       void *priv;      /* private data */
 };
 
+/*
+ * Data container for a dma_ops specific protection domain
+ */
 struct dma_ops_domain {
        struct list_head list;
+
+       /* generic protection domain information */
        struct protection_domain domain;
+
+       /* size of the aperture for the mappings */
        unsigned long aperture_size;
+
+       /* address we start to search for free addresses */
        unsigned long next_bit;
+
+       /* address allocation bitmap */
        unsigned long *bitmap;
+
+       /*
+        * Array of PTE pages for the aperture. In this array we save all the
+        * leaf pages of the domain page table used for the aperture. This way
+        * we don't need to walk the page table to find a specific PTE. We can
+        * just calculate its address in constant time.
+        */
        u64 **pte_pages;
 };
 
+/*
+ * Structure where we save information about one hardware AMD IOMMU in the
+ * system.
+ */
 struct amd_iommu {
        struct list_head list;
+
+       /* locks the accesses to the hardware */
        spinlock_t lock;
 
+       /* device id of this IOMMU */
        u16 devid;
+       /*
+        * Capability pointer. There could be more than one IOMMU per PCI
+        * device function if there are more than one AMD IOMMU capability
+        * pointers.
+        */
        u16 cap_ptr;
 
+       /* physical address of MMIO space */
        u64 mmio_phys;
+       /* virtual address of MMIO space */
        u8 *mmio_base;
+
+       /* capabilities of that IOMMU read from ACPI */
        u32 cap;
+
+       /* first device this IOMMU handles. read from PCI */
        u16 first_device;
+       /* last device this IOMMU handles. read from PCI */
        u16 last_device;
+
+       /* start of exclusion range of that IOMMU */
        u64 exclusion_start;
+       /* length of exclusion range of that IOMMU */
        u64 exclusion_length;
 
+       /* command buffer virtual address */
        u8 *cmd_buf;
+       /* size of command buffer */
        u32 cmd_buf_size;
 
+       /* if one, we need to send a completion wait command */
        int need_sync;
 
+       /* default dma_ops domain for that IOMMU */
        struct dma_ops_domain *default_dom;
 };
 
+/*
+ * List with all IOMMUs in the system. This list is not locked because it is
+ * only written and read at driver initialization or suspend time
+ */
 extern struct list_head amd_iommu_list;
 
+/*
+ * Structure defining one entry in the device table
+ */
 struct dev_table_entry {
        u32 data[8];
 };
 
+/*
+ * One entry for unity mappings parsed out of the ACPI table.
+ */
 struct unity_map_entry {
        struct list_head list;
+
+       /* starting device id this entry is used for (including) */
        u16 devid_start;
+       /* end device id this entry is used for (including) */
        u16 devid_end;
+
+       /* start address to unity map (including) */
        u64 address_start;
+       /* end address to unity map (including) */
        u64 address_end;
+
+       /* required protection */
        int prot;
 };
 
+/*
+ * List of all unity mappings. It is not locked because as runtime it is only
+ * read. It is created at ACPI table parsing time.
+ */
 extern struct list_head amd_iommu_unity_map;
 
-/* data structures for device handling */
+/*
+ * Data structures for device handling
+ */
+
+/*
+ * Device table used by hardware. Read and write accesses by software are
+ * locked with the amd_iommu_pd_table lock.
+ */
 extern struct dev_table_entry *amd_iommu_dev_table;
+
+/*
+ * Alias table to find requestor ids to device ids. Not locked because only
+ * read on runtime.
+ */
 extern u16 *amd_iommu_alias_table;
+
+/*
+ * Reverse lookup table to find the IOMMU which translates a specific device.
+ */
 extern struct amd_iommu **amd_iommu_rlookup_table;
 
+/* size of the dma_ops aperture as power of 2 */
 extern unsigned amd_iommu_aperture_order;
 
+/* largest PCI device id we expect translation requests for */
 extern u16 amd_iommu_last_bdf;
 
 /* data structures for protection domain handling */
 extern struct protection_domain **amd_iommu_pd_table;
+
+/* allocation bitmap for domain ids */
 extern unsigned long *amd_iommu_pd_alloc_bitmap;
 
+/* will be 1 if device isolation is enabled */
 extern int amd_iommu_isolate;
 
+/* takes a PCI device id and prints it out in a readable form */
 static inline void print_devid(u16 devid, int nl)
 {
        int bus = devid >> 8;
@@ -241,4 +332,11 @@ static inline void print_devid(u16 devid, int nl)
                printk("\n");
 }
 
+/* takes bus and device/function and returns the device id
+ * FIXME: should that be in generic PCI code? */
+static inline u16 calc_devid(u8 bus, u8 devfn)
+{
+       return (((u16)bus) << 8) | devfn;
+}
+
 #endif