2 * Copyright (C) 2007-2010 Advanced Micro Devices, Inc.
3 * Author: Joerg Roedel <joerg.roedel@amd.com>
4 * Leo Duran <leo.duran@amd.com>
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License version 2 as published
8 * by the Free Software Foundation.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 #include <linux/pci.h>
21 #include <linux/acpi.h>
22 #include <linux/list.h>
23 #include <linux/slab.h>
24 #include <linux/syscore_ops.h>
25 #include <linux/interrupt.h>
26 #include <linux/msi.h>
27 #include <linux/amd-iommu.h>
28 #include <linux/export.h>
29 #include <asm/pci-direct.h>
30 #include <asm/iommu.h>
32 #include <asm/x86_init.h>
33 #include <asm/iommu_table.h>
35 #include "amd_iommu_proto.h"
36 #include "amd_iommu_types.h"
39 * definitions for the ACPI scanning code
41 #define IVRS_HEADER_LENGTH 48
43 #define ACPI_IVHD_TYPE 0x10
44 #define ACPI_IVMD_TYPE_ALL 0x20
45 #define ACPI_IVMD_TYPE 0x21
46 #define ACPI_IVMD_TYPE_RANGE 0x22
48 #define IVHD_DEV_ALL 0x01
49 #define IVHD_DEV_SELECT 0x02
50 #define IVHD_DEV_SELECT_RANGE_START 0x03
51 #define IVHD_DEV_RANGE_END 0x04
52 #define IVHD_DEV_ALIAS 0x42
53 #define IVHD_DEV_ALIAS_RANGE 0x43
54 #define IVHD_DEV_EXT_SELECT 0x46
55 #define IVHD_DEV_EXT_SELECT_RANGE 0x47
57 #define IVHD_FLAG_HT_TUN_EN_MASK 0x01
58 #define IVHD_FLAG_PASSPW_EN_MASK 0x02
59 #define IVHD_FLAG_RESPASSPW_EN_MASK 0x04
60 #define IVHD_FLAG_ISOC_EN_MASK 0x08
62 #define IVMD_FLAG_EXCL_RANGE 0x08
63 #define IVMD_FLAG_UNITY_MAP 0x01
65 #define ACPI_DEVFLAG_INITPASS 0x01
66 #define ACPI_DEVFLAG_EXTINT 0x02
67 #define ACPI_DEVFLAG_NMI 0x04
68 #define ACPI_DEVFLAG_SYSMGT1 0x10
69 #define ACPI_DEVFLAG_SYSMGT2 0x20
70 #define ACPI_DEVFLAG_LINT0 0x40
71 #define ACPI_DEVFLAG_LINT1 0x80
72 #define ACPI_DEVFLAG_ATSDIS 0x10000000
75 * ACPI table definitions
77 * These data structures are laid over the table to parse the important values
82 * structure describing one IOMMU in the ACPI table. Typically followed by one
83 * or more ivhd_entrys.
95 } __attribute__((packed));
98 * A device entry describing which devices a specific IOMMU translates and
99 * which requestor ids they use.
106 } __attribute__((packed));
109 * An AMD IOMMU memory definition structure. It defines things like exclusion
110 * ranges for devices and regions that should be unity mapped.
121 } __attribute__((packed));
125 static int __initdata amd_iommu_detected;
126 static bool __initdata amd_iommu_disabled;
128 u16 amd_iommu_last_bdf; /* largest PCI device id we have
130 LIST_HEAD(amd_iommu_unity_map); /* a list of required unity mappings
132 u32 amd_iommu_unmap_flush; /* if true, flush on every unmap */
134 LIST_HEAD(amd_iommu_list); /* list of all AMD IOMMUs in the
137 /* Array to assign indices to IOMMUs*/
138 struct amd_iommu *amd_iommus[MAX_IOMMUS];
139 int amd_iommus_present;
141 /* IOMMUs have a non-present cache? */
142 bool amd_iommu_np_cache __read_mostly;
143 bool amd_iommu_iotlb_sup __read_mostly = true;
145 u32 amd_iommu_max_pasids __read_mostly = ~0;
147 bool amd_iommu_v2_present __read_mostly;
149 bool amd_iommu_force_isolation __read_mostly;
152 * The ACPI table parsing functions set this variable on an error
154 static int __initdata amd_iommu_init_err;
157 * List of protection domains - used during resume
159 LIST_HEAD(amd_iommu_pd_list);
160 spinlock_t amd_iommu_pd_lock;
163 * Pointer to the device table which is shared by all AMD IOMMUs
164 * it is indexed by the PCI device id or the HT unit id and contains
165 * information about the domain the device belongs to as well as the
166 * page table root pointer.
168 struct dev_table_entry *amd_iommu_dev_table;
171 * The alias table is a driver specific data structure which contains the
172 * mappings of the PCI device ids to the actual requestor ids on the IOMMU.
173 * More than one device can share the same requestor id.
175 u16 *amd_iommu_alias_table;
178 * The rlookup table is used to find the IOMMU which is responsible
179 * for a specific device. It is also indexed by the PCI device id.
181 struct amd_iommu **amd_iommu_rlookup_table;
184 * AMD IOMMU allows up to 2^16 differend protection domains. This is a bitmap
185 * to know which ones are already in use.
187 unsigned long *amd_iommu_pd_alloc_bitmap;
189 static u32 dev_table_size; /* size of the device table */
190 static u32 alias_table_size; /* size of the alias table */
191 static u32 rlookup_table_size; /* size if the rlookup table */
194 * This function flushes all internal caches of
195 * the IOMMU used by this driver.
197 extern void iommu_flush_all_caches(struct amd_iommu *iommu);
199 static int amd_iommu_enable_interrupts(void);
201 static inline void update_last_devid(u16 devid)
203 if (devid > amd_iommu_last_bdf)
204 amd_iommu_last_bdf = devid;
207 static inline unsigned long tbl_size(int entry_size)
209 unsigned shift = PAGE_SHIFT +
210 get_order(((int)amd_iommu_last_bdf + 1) * entry_size);
215 /* Access to l1 and l2 indexed register spaces */
217 static u32 iommu_read_l1(struct amd_iommu *iommu, u16 l1, u8 address)
221 pci_write_config_dword(iommu->dev, 0xf8, (address | l1 << 16));
222 pci_read_config_dword(iommu->dev, 0xfc, &val);
226 static void iommu_write_l1(struct amd_iommu *iommu, u16 l1, u8 address, u32 val)
228 pci_write_config_dword(iommu->dev, 0xf8, (address | l1 << 16 | 1 << 31));
229 pci_write_config_dword(iommu->dev, 0xfc, val);
230 pci_write_config_dword(iommu->dev, 0xf8, (address | l1 << 16));
233 static u32 iommu_read_l2(struct amd_iommu *iommu, u8 address)
237 pci_write_config_dword(iommu->dev, 0xf0, address);
238 pci_read_config_dword(iommu->dev, 0xf4, &val);
242 static void iommu_write_l2(struct amd_iommu *iommu, u8 address, u32 val)
244 pci_write_config_dword(iommu->dev, 0xf0, (address | 1 << 8));
245 pci_write_config_dword(iommu->dev, 0xf4, val);
248 /****************************************************************************
250 * AMD IOMMU MMIO register space handling functions
252 * These functions are used to program the IOMMU device registers in
253 * MMIO space required for that driver.
255 ****************************************************************************/
258 * This function set the exclusion range in the IOMMU. DMA accesses to the
259 * exclusion range are passed through untranslated
261 static void iommu_set_exclusion_range(struct amd_iommu *iommu)
263 u64 start = iommu->exclusion_start & PAGE_MASK;
264 u64 limit = (start + iommu->exclusion_length) & PAGE_MASK;
267 if (!iommu->exclusion_start)
270 entry = start | MMIO_EXCL_ENABLE_MASK;
271 memcpy_toio(iommu->mmio_base + MMIO_EXCL_BASE_OFFSET,
272 &entry, sizeof(entry));
275 memcpy_toio(iommu->mmio_base + MMIO_EXCL_LIMIT_OFFSET,
276 &entry, sizeof(entry));
279 /* Programs the physical address of the device table into the IOMMU hardware */
280 static void iommu_set_device_table(struct amd_iommu *iommu)
284 BUG_ON(iommu->mmio_base == NULL);
286 entry = virt_to_phys(amd_iommu_dev_table);
287 entry |= (dev_table_size >> 12) - 1;
288 memcpy_toio(iommu->mmio_base + MMIO_DEV_TABLE_OFFSET,
289 &entry, sizeof(entry));
292 /* Generic functions to enable/disable certain features of the IOMMU. */
293 static void iommu_feature_enable(struct amd_iommu *iommu, u8 bit)
297 ctrl = readl(iommu->mmio_base + MMIO_CONTROL_OFFSET);
299 writel(ctrl, iommu->mmio_base + MMIO_CONTROL_OFFSET);
302 static void iommu_feature_disable(struct amd_iommu *iommu, u8 bit)
306 ctrl = readl(iommu->mmio_base + MMIO_CONTROL_OFFSET);
308 writel(ctrl, iommu->mmio_base + MMIO_CONTROL_OFFSET);
311 static void iommu_set_inv_tlb_timeout(struct amd_iommu *iommu, int timeout)
315 ctrl = readl(iommu->mmio_base + MMIO_CONTROL_OFFSET);
316 ctrl &= ~CTRL_INV_TO_MASK;
317 ctrl |= (timeout << CONTROL_INV_TIMEOUT) & CTRL_INV_TO_MASK;
318 writel(ctrl, iommu->mmio_base + MMIO_CONTROL_OFFSET);
321 /* Function to enable the hardware */
322 static void iommu_enable(struct amd_iommu *iommu)
324 static const char * const feat_str[] = {
325 "PreF", "PPR", "X2APIC", "NX", "GT", "[5]",
326 "IA", "GA", "HE", "PC", NULL
330 printk(KERN_INFO "AMD-Vi: Enabling IOMMU at %s cap 0x%hx",
331 dev_name(&iommu->dev->dev), iommu->cap_ptr);
333 if (iommu->cap & (1 << IOMMU_CAP_EFR)) {
334 printk(KERN_CONT " extended features: ");
335 for (i = 0; feat_str[i]; ++i)
336 if (iommu_feature(iommu, (1ULL << i)))
337 printk(KERN_CONT " %s", feat_str[i]);
339 printk(KERN_CONT "\n");
341 iommu_feature_enable(iommu, CONTROL_IOMMU_EN);
344 static void iommu_disable(struct amd_iommu *iommu)
346 /* Disable command buffer */
347 iommu_feature_disable(iommu, CONTROL_CMDBUF_EN);
349 /* Disable event logging and event interrupts */
350 iommu_feature_disable(iommu, CONTROL_EVT_INT_EN);
351 iommu_feature_disable(iommu, CONTROL_EVT_LOG_EN);
353 /* Disable IOMMU hardware itself */
354 iommu_feature_disable(iommu, CONTROL_IOMMU_EN);
358 * mapping and unmapping functions for the IOMMU MMIO space. Each AMD IOMMU in
359 * the system has one.
361 static u8 * __init iommu_map_mmio_space(u64 address)
363 if (!request_mem_region(address, MMIO_REGION_LENGTH, "amd_iommu")) {
364 pr_err("AMD-Vi: Can not reserve memory region %llx for mmio\n",
366 pr_err("AMD-Vi: This is a BIOS bug. Please contact your hardware vendor\n");
370 return ioremap_nocache(address, MMIO_REGION_LENGTH);
373 static void __init iommu_unmap_mmio_space(struct amd_iommu *iommu)
375 if (iommu->mmio_base)
376 iounmap(iommu->mmio_base);
377 release_mem_region(iommu->mmio_phys, MMIO_REGION_LENGTH);
380 /****************************************************************************
382 * The functions below belong to the first pass of AMD IOMMU ACPI table
383 * parsing. In this pass we try to find out the highest device id this
384 * code has to handle. Upon this information the size of the shared data
385 * structures is determined later.
387 ****************************************************************************/
390 * This function calculates the length of a given IVHD entry
392 static inline int ivhd_entry_length(u8 *ivhd)
394 return 0x04 << (*ivhd >> 6);
398 * This function reads the last device id the IOMMU has to handle from the PCI
399 * capability header for this IOMMU
401 static int __init find_last_devid_on_pci(int bus, int dev, int fn, int cap_ptr)
405 cap = read_pci_config(bus, dev, fn, cap_ptr+MMIO_RANGE_OFFSET);
406 update_last_devid(calc_devid(MMIO_GET_BUS(cap), MMIO_GET_LD(cap)));
412 * After reading the highest device id from the IOMMU PCI capability header
413 * this function looks if there is a higher device id defined in the ACPI table
415 static int __init find_last_devid_from_ivhd(struct ivhd_header *h)
417 u8 *p = (void *)h, *end = (void *)h;
418 struct ivhd_entry *dev;
423 find_last_devid_on_pci(PCI_BUS(h->devid),
429 dev = (struct ivhd_entry *)p;
431 case IVHD_DEV_SELECT:
432 case IVHD_DEV_RANGE_END:
434 case IVHD_DEV_EXT_SELECT:
435 /* all the above subfield types refer to device ids */
436 update_last_devid(dev->devid);
441 p += ivhd_entry_length(p);
450 * Iterate over all IVHD entries in the ACPI table and find the highest device
451 * id which we need to handle. This is the first of three functions which parse
452 * the ACPI table. So we check the checksum here.
454 static int __init find_last_devid_acpi(struct acpi_table_header *table)
457 u8 checksum = 0, *p = (u8 *)table, *end = (u8 *)table;
458 struct ivhd_header *h;
461 * Validate checksum here so we don't need to do it when
462 * we actually parse the table
464 for (i = 0; i < table->length; ++i)
467 /* ACPI table corrupt */
468 amd_iommu_init_err = -ENODEV;
472 p += IVRS_HEADER_LENGTH;
474 end += table->length;
476 h = (struct ivhd_header *)p;
479 find_last_devid_from_ivhd(h);
491 /****************************************************************************
493 * The following functions belong the the code path which parses the ACPI table
494 * the second time. In this ACPI parsing iteration we allocate IOMMU specific
495 * data structures, initialize the device/alias/rlookup table and also
496 * basically initialize the hardware.
498 ****************************************************************************/
501 * Allocates the command buffer. This buffer is per AMD IOMMU. We can
502 * write commands to that buffer later and the IOMMU will execute them
505 static u8 * __init alloc_command_buffer(struct amd_iommu *iommu)
507 u8 *cmd_buf = (u8 *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
508 get_order(CMD_BUFFER_SIZE));
513 iommu->cmd_buf_size = CMD_BUFFER_SIZE | CMD_BUFFER_UNINITIALIZED;
519 * This function resets the command buffer if the IOMMU stopped fetching
522 void amd_iommu_reset_cmd_buffer(struct amd_iommu *iommu)
524 iommu_feature_disable(iommu, CONTROL_CMDBUF_EN);
526 writel(0x00, iommu->mmio_base + MMIO_CMD_HEAD_OFFSET);
527 writel(0x00, iommu->mmio_base + MMIO_CMD_TAIL_OFFSET);
529 iommu_feature_enable(iommu, CONTROL_CMDBUF_EN);
533 * This function writes the command buffer address to the hardware and
536 static void iommu_enable_command_buffer(struct amd_iommu *iommu)
540 BUG_ON(iommu->cmd_buf == NULL);
542 entry = (u64)virt_to_phys(iommu->cmd_buf);
543 entry |= MMIO_CMD_SIZE_512;
545 memcpy_toio(iommu->mmio_base + MMIO_CMD_BUF_OFFSET,
546 &entry, sizeof(entry));
548 amd_iommu_reset_cmd_buffer(iommu);
549 iommu->cmd_buf_size &= ~(CMD_BUFFER_UNINITIALIZED);
552 static void __init free_command_buffer(struct amd_iommu *iommu)
554 free_pages((unsigned long)iommu->cmd_buf,
555 get_order(iommu->cmd_buf_size & ~(CMD_BUFFER_UNINITIALIZED)));
558 /* allocates the memory where the IOMMU will log its events to */
559 static u8 * __init alloc_event_buffer(struct amd_iommu *iommu)
561 iommu->evt_buf = (u8 *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
562 get_order(EVT_BUFFER_SIZE));
564 if (iommu->evt_buf == NULL)
567 iommu->evt_buf_size = EVT_BUFFER_SIZE;
569 return iommu->evt_buf;
572 static void iommu_enable_event_buffer(struct amd_iommu *iommu)
576 BUG_ON(iommu->evt_buf == NULL);
578 entry = (u64)virt_to_phys(iommu->evt_buf) | EVT_LEN_MASK;
580 memcpy_toio(iommu->mmio_base + MMIO_EVT_BUF_OFFSET,
581 &entry, sizeof(entry));
583 /* set head and tail to zero manually */
584 writel(0x00, iommu->mmio_base + MMIO_EVT_HEAD_OFFSET);
585 writel(0x00, iommu->mmio_base + MMIO_EVT_TAIL_OFFSET);
587 iommu_feature_enable(iommu, CONTROL_EVT_LOG_EN);
590 static void __init free_event_buffer(struct amd_iommu *iommu)
592 free_pages((unsigned long)iommu->evt_buf, get_order(EVT_BUFFER_SIZE));
595 /* allocates the memory where the IOMMU will log its events to */
596 static u8 * __init alloc_ppr_log(struct amd_iommu *iommu)
598 iommu->ppr_log = (u8 *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
599 get_order(PPR_LOG_SIZE));
601 if (iommu->ppr_log == NULL)
604 return iommu->ppr_log;
607 static void iommu_enable_ppr_log(struct amd_iommu *iommu)
611 if (iommu->ppr_log == NULL)
614 entry = (u64)virt_to_phys(iommu->ppr_log) | PPR_LOG_SIZE_512;
616 memcpy_toio(iommu->mmio_base + MMIO_PPR_LOG_OFFSET,
617 &entry, sizeof(entry));
619 /* set head and tail to zero manually */
620 writel(0x00, iommu->mmio_base + MMIO_PPR_HEAD_OFFSET);
621 writel(0x00, iommu->mmio_base + MMIO_PPR_TAIL_OFFSET);
623 iommu_feature_enable(iommu, CONTROL_PPFLOG_EN);
624 iommu_feature_enable(iommu, CONTROL_PPR_EN);
627 static void __init free_ppr_log(struct amd_iommu *iommu)
629 if (iommu->ppr_log == NULL)
632 free_pages((unsigned long)iommu->ppr_log, get_order(PPR_LOG_SIZE));
635 static void iommu_enable_gt(struct amd_iommu *iommu)
637 if (!iommu_feature(iommu, FEATURE_GT))
640 iommu_feature_enable(iommu, CONTROL_GT_EN);
643 /* sets a specific bit in the device table entry. */
644 static void set_dev_entry_bit(u16 devid, u8 bit)
646 int i = (bit >> 6) & 0x03;
647 int _bit = bit & 0x3f;
649 amd_iommu_dev_table[devid].data[i] |= (1UL << _bit);
652 static int get_dev_entry_bit(u16 devid, u8 bit)
654 int i = (bit >> 6) & 0x03;
655 int _bit = bit & 0x3f;
657 return (amd_iommu_dev_table[devid].data[i] & (1UL << _bit)) >> _bit;
661 void amd_iommu_apply_erratum_63(u16 devid)
665 sysmgt = get_dev_entry_bit(devid, DEV_ENTRY_SYSMGT1) |
666 (get_dev_entry_bit(devid, DEV_ENTRY_SYSMGT2) << 1);
669 set_dev_entry_bit(devid, DEV_ENTRY_IW);
672 /* Writes the specific IOMMU for a device into the rlookup table */
673 static void __init set_iommu_for_device(struct amd_iommu *iommu, u16 devid)
675 amd_iommu_rlookup_table[devid] = iommu;
679 * This function takes the device specific flags read from the ACPI
680 * table and sets up the device table entry with that information
682 static void __init set_dev_entry_from_acpi(struct amd_iommu *iommu,
683 u16 devid, u32 flags, u32 ext_flags)
685 if (flags & ACPI_DEVFLAG_INITPASS)
686 set_dev_entry_bit(devid, DEV_ENTRY_INIT_PASS);
687 if (flags & ACPI_DEVFLAG_EXTINT)
688 set_dev_entry_bit(devid, DEV_ENTRY_EINT_PASS);
689 if (flags & ACPI_DEVFLAG_NMI)
690 set_dev_entry_bit(devid, DEV_ENTRY_NMI_PASS);
691 if (flags & ACPI_DEVFLAG_SYSMGT1)
692 set_dev_entry_bit(devid, DEV_ENTRY_SYSMGT1);
693 if (flags & ACPI_DEVFLAG_SYSMGT2)
694 set_dev_entry_bit(devid, DEV_ENTRY_SYSMGT2);
695 if (flags & ACPI_DEVFLAG_LINT0)
696 set_dev_entry_bit(devid, DEV_ENTRY_LINT0_PASS);
697 if (flags & ACPI_DEVFLAG_LINT1)
698 set_dev_entry_bit(devid, DEV_ENTRY_LINT1_PASS);
700 amd_iommu_apply_erratum_63(devid);
702 set_iommu_for_device(iommu, devid);
706 * Reads the device exclusion range from ACPI and initialize IOMMU with
709 static void __init set_device_exclusion_range(u16 devid, struct ivmd_header *m)
711 struct amd_iommu *iommu = amd_iommu_rlookup_table[devid];
713 if (!(m->flags & IVMD_FLAG_EXCL_RANGE))
718 * We only can configure exclusion ranges per IOMMU, not
719 * per device. But we can enable the exclusion range per
720 * device. This is done here
722 set_dev_entry_bit(m->devid, DEV_ENTRY_EX);
723 iommu->exclusion_start = m->range_start;
724 iommu->exclusion_length = m->range_length;
729 * This function reads some important data from the IOMMU PCI space and
730 * initializes the driver data structure with it. It reads the hardware
731 * capabilities and the first/last device entries
733 static void __init init_iommu_from_pci(struct amd_iommu *iommu)
735 int cap_ptr = iommu->cap_ptr;
736 u32 range, misc, low, high;
739 pci_read_config_dword(iommu->dev, cap_ptr + MMIO_CAP_HDR_OFFSET,
741 pci_read_config_dword(iommu->dev, cap_ptr + MMIO_RANGE_OFFSET,
743 pci_read_config_dword(iommu->dev, cap_ptr + MMIO_MISC_OFFSET,
746 iommu->first_device = calc_devid(MMIO_GET_BUS(range),
748 iommu->last_device = calc_devid(MMIO_GET_BUS(range),
750 iommu->evt_msi_num = MMIO_MSI_NUM(misc);
752 if (!(iommu->cap & (1 << IOMMU_CAP_IOTLB)))
753 amd_iommu_iotlb_sup = false;
755 /* read extended feature bits */
756 low = readl(iommu->mmio_base + MMIO_EXT_FEATURES);
757 high = readl(iommu->mmio_base + MMIO_EXT_FEATURES + 4);
759 iommu->features = ((u64)high << 32) | low;
761 if (iommu_feature(iommu, FEATURE_GT)) {
766 shift = iommu->features & FEATURE_PASID_MASK;
767 shift >>= FEATURE_PASID_SHIFT;
768 pasids = (1 << shift);
770 amd_iommu_max_pasids = min(amd_iommu_max_pasids, pasids);
772 glxval = iommu->features & FEATURE_GLXVAL_MASK;
773 glxval >>= FEATURE_GLXVAL_SHIFT;
775 if (amd_iommu_max_glx_val == -1)
776 amd_iommu_max_glx_val = glxval;
778 amd_iommu_max_glx_val = min(amd_iommu_max_glx_val, glxval);
781 if (iommu_feature(iommu, FEATURE_GT) &&
782 iommu_feature(iommu, FEATURE_PPR)) {
783 iommu->is_iommu_v2 = true;
784 amd_iommu_v2_present = true;
787 if (!is_rd890_iommu(iommu->dev))
791 * Some rd890 systems may not be fully reconfigured by the BIOS, so
792 * it's necessary for us to store this information so it can be
793 * reprogrammed on resume
796 pci_read_config_dword(iommu->dev, iommu->cap_ptr + 4,
797 &iommu->stored_addr_lo);
798 pci_read_config_dword(iommu->dev, iommu->cap_ptr + 8,
799 &iommu->stored_addr_hi);
801 /* Low bit locks writes to configuration space */
802 iommu->stored_addr_lo &= ~1;
804 for (i = 0; i < 6; i++)
805 for (j = 0; j < 0x12; j++)
806 iommu->stored_l1[i][j] = iommu_read_l1(iommu, i, j);
808 for (i = 0; i < 0x83; i++)
809 iommu->stored_l2[i] = iommu_read_l2(iommu, i);
813 * Takes a pointer to an AMD IOMMU entry in the ACPI table and
814 * initializes the hardware and our data structures with it.
816 static void __init init_iommu_from_acpi(struct amd_iommu *iommu,
817 struct ivhd_header *h)
820 u8 *end = p, flags = 0;
821 u16 devid = 0, devid_start = 0, devid_to = 0;
822 u32 dev_i, ext_flags = 0;
824 struct ivhd_entry *e;
827 * First save the recommended feature enable bits from ACPI
829 iommu->acpi_flags = h->flags;
832 * Done. Now parse the device entries
834 p += sizeof(struct ivhd_header);
839 e = (struct ivhd_entry *)p;
843 DUMP_printk(" DEV_ALL\t\t\t first devid: %02x:%02x.%x"
844 " last device %02x:%02x.%x flags: %02x\n",
845 PCI_BUS(iommu->first_device),
846 PCI_SLOT(iommu->first_device),
847 PCI_FUNC(iommu->first_device),
848 PCI_BUS(iommu->last_device),
849 PCI_SLOT(iommu->last_device),
850 PCI_FUNC(iommu->last_device),
853 for (dev_i = iommu->first_device;
854 dev_i <= iommu->last_device; ++dev_i)
855 set_dev_entry_from_acpi(iommu, dev_i,
858 case IVHD_DEV_SELECT:
860 DUMP_printk(" DEV_SELECT\t\t\t devid: %02x:%02x.%x "
868 set_dev_entry_from_acpi(iommu, devid, e->flags, 0);
870 case IVHD_DEV_SELECT_RANGE_START:
872 DUMP_printk(" DEV_SELECT_RANGE_START\t "
873 "devid: %02x:%02x.%x flags: %02x\n",
879 devid_start = e->devid;
886 DUMP_printk(" DEV_ALIAS\t\t\t devid: %02x:%02x.%x "
887 "flags: %02x devid_to: %02x:%02x.%x\n",
892 PCI_BUS(e->ext >> 8),
893 PCI_SLOT(e->ext >> 8),
894 PCI_FUNC(e->ext >> 8));
897 devid_to = e->ext >> 8;
898 set_dev_entry_from_acpi(iommu, devid , e->flags, 0);
899 set_dev_entry_from_acpi(iommu, devid_to, e->flags, 0);
900 amd_iommu_alias_table[devid] = devid_to;
902 case IVHD_DEV_ALIAS_RANGE:
904 DUMP_printk(" DEV_ALIAS_RANGE\t\t "
905 "devid: %02x:%02x.%x flags: %02x "
906 "devid_to: %02x:%02x.%x\n",
911 PCI_BUS(e->ext >> 8),
912 PCI_SLOT(e->ext >> 8),
913 PCI_FUNC(e->ext >> 8));
915 devid_start = e->devid;
917 devid_to = e->ext >> 8;
921 case IVHD_DEV_EXT_SELECT:
923 DUMP_printk(" DEV_EXT_SELECT\t\t devid: %02x:%02x.%x "
924 "flags: %02x ext: %08x\n",
931 set_dev_entry_from_acpi(iommu, devid, e->flags,
934 case IVHD_DEV_EXT_SELECT_RANGE:
936 DUMP_printk(" DEV_EXT_SELECT_RANGE\t devid: "
937 "%02x:%02x.%x flags: %02x ext: %08x\n",
943 devid_start = e->devid;
948 case IVHD_DEV_RANGE_END:
950 DUMP_printk(" DEV_RANGE_END\t\t devid: %02x:%02x.%x\n",
956 for (dev_i = devid_start; dev_i <= devid; ++dev_i) {
958 amd_iommu_alias_table[dev_i] = devid_to;
959 set_dev_entry_from_acpi(iommu,
960 devid_to, flags, ext_flags);
962 set_dev_entry_from_acpi(iommu, dev_i,
970 p += ivhd_entry_length(p);
974 /* Initializes the device->iommu mapping for the driver */
975 static int __init init_iommu_devices(struct amd_iommu *iommu)
979 for (i = iommu->first_device; i <= iommu->last_device; ++i)
980 set_iommu_for_device(iommu, i);
985 static void __init free_iommu_one(struct amd_iommu *iommu)
987 free_command_buffer(iommu);
988 free_event_buffer(iommu);
990 iommu_unmap_mmio_space(iommu);
993 static void __init free_iommu_all(void)
995 struct amd_iommu *iommu, *next;
997 for_each_iommu_safe(iommu, next) {
998 list_del(&iommu->list);
999 free_iommu_one(iommu);
1005 * This function clues the initialization function for one IOMMU
1006 * together and also allocates the command buffer and programs the
1007 * hardware. It does NOT enable the IOMMU. This is done afterwards.
1009 static int __init init_iommu_one(struct amd_iommu *iommu, struct ivhd_header *h)
1011 spin_lock_init(&iommu->lock);
1013 /* Add IOMMU to internal data structures */
1014 list_add_tail(&iommu->list, &amd_iommu_list);
1015 iommu->index = amd_iommus_present++;
1017 if (unlikely(iommu->index >= MAX_IOMMUS)) {
1018 WARN(1, "AMD-Vi: System has more IOMMUs than supported by this driver\n");
1022 /* Index is fine - add IOMMU to the array */
1023 amd_iommus[iommu->index] = iommu;
1026 * Copy data from ACPI table entry to the iommu struct
1028 iommu->dev = pci_get_bus_and_slot(PCI_BUS(h->devid), h->devid & 0xff);
1032 iommu->root_pdev = pci_get_bus_and_slot(iommu->dev->bus->number,
1035 iommu->cap_ptr = h->cap_ptr;
1036 iommu->pci_seg = h->pci_seg;
1037 iommu->mmio_phys = h->mmio_phys;
1038 iommu->mmio_base = iommu_map_mmio_space(h->mmio_phys);
1039 if (!iommu->mmio_base)
1042 iommu->cmd_buf = alloc_command_buffer(iommu);
1043 if (!iommu->cmd_buf)
1046 iommu->evt_buf = alloc_event_buffer(iommu);
1047 if (!iommu->evt_buf)
1050 iommu->int_enabled = false;
1052 init_iommu_from_pci(iommu);
1053 init_iommu_from_acpi(iommu, h);
1054 init_iommu_devices(iommu);
1056 if (iommu_feature(iommu, FEATURE_PPR)) {
1057 iommu->ppr_log = alloc_ppr_log(iommu);
1058 if (!iommu->ppr_log)
1062 if (iommu->cap & (1UL << IOMMU_CAP_NPCACHE))
1063 amd_iommu_np_cache = true;
1065 return pci_enable_device(iommu->dev);
1069 * Iterates over all IOMMU entries in the ACPI table, allocates the
1070 * IOMMU structure and initializes it with init_iommu_one()
1072 static int __init init_iommu_all(struct acpi_table_header *table)
1074 u8 *p = (u8 *)table, *end = (u8 *)table;
1075 struct ivhd_header *h;
1076 struct amd_iommu *iommu;
1079 end += table->length;
1080 p += IVRS_HEADER_LENGTH;
1083 h = (struct ivhd_header *)p;
1085 case ACPI_IVHD_TYPE:
1087 DUMP_printk("device: %02x:%02x.%01x cap: %04x "
1088 "seg: %d flags: %01x info %04x\n",
1089 PCI_BUS(h->devid), PCI_SLOT(h->devid),
1090 PCI_FUNC(h->devid), h->cap_ptr,
1091 h->pci_seg, h->flags, h->info);
1092 DUMP_printk(" mmio-addr: %016llx\n",
1095 iommu = kzalloc(sizeof(struct amd_iommu), GFP_KERNEL);
1096 if (iommu == NULL) {
1097 amd_iommu_init_err = -ENOMEM;
1101 ret = init_iommu_one(iommu, h);
1103 amd_iommu_init_err = ret;
1118 /****************************************************************************
1120 * The following functions initialize the MSI interrupts for all IOMMUs
1121 * in the system. Its a bit challenging because there could be multiple
1122 * IOMMUs per PCI BDF but we can call pci_enable_msi(x) only once per
1125 ****************************************************************************/
1127 static int iommu_setup_msi(struct amd_iommu *iommu)
1131 r = pci_enable_msi(iommu->dev);
1135 r = request_threaded_irq(iommu->dev->irq,
1136 amd_iommu_int_handler,
1137 amd_iommu_int_thread,
1142 pci_disable_msi(iommu->dev);
1146 iommu->int_enabled = true;
1151 static int iommu_init_msi(struct amd_iommu *iommu)
1155 if (iommu->int_enabled)
1158 if (pci_find_capability(iommu->dev, PCI_CAP_ID_MSI))
1159 ret = iommu_setup_msi(iommu);
1167 iommu_feature_enable(iommu, CONTROL_EVT_INT_EN);
1169 if (iommu->ppr_log != NULL)
1170 iommu_feature_enable(iommu, CONTROL_PPFINT_EN);
1175 /****************************************************************************
1177 * The next functions belong to the third pass of parsing the ACPI
1178 * table. In this last pass the memory mapping requirements are
1179 * gathered (like exclusion and unity mapping reanges).
1181 ****************************************************************************/
1183 static void __init free_unity_maps(void)
1185 struct unity_map_entry *entry, *next;
1187 list_for_each_entry_safe(entry, next, &amd_iommu_unity_map, list) {
1188 list_del(&entry->list);
1193 /* called when we find an exclusion range definition in ACPI */
1194 static int __init init_exclusion_range(struct ivmd_header *m)
1199 case ACPI_IVMD_TYPE:
1200 set_device_exclusion_range(m->devid, m);
1202 case ACPI_IVMD_TYPE_ALL:
1203 for (i = 0; i <= amd_iommu_last_bdf; ++i)
1204 set_device_exclusion_range(i, m);
1206 case ACPI_IVMD_TYPE_RANGE:
1207 for (i = m->devid; i <= m->aux; ++i)
1208 set_device_exclusion_range(i, m);
1217 /* called for unity map ACPI definition */
1218 static int __init init_unity_map_range(struct ivmd_header *m)
1220 struct unity_map_entry *e = 0;
1223 e = kzalloc(sizeof(*e), GFP_KERNEL);
1231 case ACPI_IVMD_TYPE:
1232 s = "IVMD_TYPEi\t\t\t";
1233 e->devid_start = e->devid_end = m->devid;
1235 case ACPI_IVMD_TYPE_ALL:
1236 s = "IVMD_TYPE_ALL\t\t";
1238 e->devid_end = amd_iommu_last_bdf;
1240 case ACPI_IVMD_TYPE_RANGE:
1241 s = "IVMD_TYPE_RANGE\t\t";
1242 e->devid_start = m->devid;
1243 e->devid_end = m->aux;
1246 e->address_start = PAGE_ALIGN(m->range_start);
1247 e->address_end = e->address_start + PAGE_ALIGN(m->range_length);
1248 e->prot = m->flags >> 1;
1250 DUMP_printk("%s devid_start: %02x:%02x.%x devid_end: %02x:%02x.%x"
1251 " range_start: %016llx range_end: %016llx flags: %x\n", s,
1252 PCI_BUS(e->devid_start), PCI_SLOT(e->devid_start),
1253 PCI_FUNC(e->devid_start), PCI_BUS(e->devid_end),
1254 PCI_SLOT(e->devid_end), PCI_FUNC(e->devid_end),
1255 e->address_start, e->address_end, m->flags);
1257 list_add_tail(&e->list, &amd_iommu_unity_map);
1262 /* iterates over all memory definitions we find in the ACPI table */
1263 static int __init init_memory_definitions(struct acpi_table_header *table)
1265 u8 *p = (u8 *)table, *end = (u8 *)table;
1266 struct ivmd_header *m;
1268 end += table->length;
1269 p += IVRS_HEADER_LENGTH;
1272 m = (struct ivmd_header *)p;
1273 if (m->flags & IVMD_FLAG_EXCL_RANGE)
1274 init_exclusion_range(m);
1275 else if (m->flags & IVMD_FLAG_UNITY_MAP)
1276 init_unity_map_range(m);
1285 * Init the device table to not allow DMA access for devices and
1286 * suppress all page faults
1288 static void init_device_table(void)
1292 for (devid = 0; devid <= amd_iommu_last_bdf; ++devid) {
1293 set_dev_entry_bit(devid, DEV_ENTRY_VALID);
1294 set_dev_entry_bit(devid, DEV_ENTRY_TRANSLATION);
1298 static void iommu_init_flags(struct amd_iommu *iommu)
1300 iommu->acpi_flags & IVHD_FLAG_HT_TUN_EN_MASK ?
1301 iommu_feature_enable(iommu, CONTROL_HT_TUN_EN) :
1302 iommu_feature_disable(iommu, CONTROL_HT_TUN_EN);
1304 iommu->acpi_flags & IVHD_FLAG_PASSPW_EN_MASK ?
1305 iommu_feature_enable(iommu, CONTROL_PASSPW_EN) :
1306 iommu_feature_disable(iommu, CONTROL_PASSPW_EN);
1308 iommu->acpi_flags & IVHD_FLAG_RESPASSPW_EN_MASK ?
1309 iommu_feature_enable(iommu, CONTROL_RESPASSPW_EN) :
1310 iommu_feature_disable(iommu, CONTROL_RESPASSPW_EN);
1312 iommu->acpi_flags & IVHD_FLAG_ISOC_EN_MASK ?
1313 iommu_feature_enable(iommu, CONTROL_ISOC_EN) :
1314 iommu_feature_disable(iommu, CONTROL_ISOC_EN);
1317 * make IOMMU memory accesses cache coherent
1319 iommu_feature_enable(iommu, CONTROL_COHERENT_EN);
1321 /* Set IOTLB invalidation timeout to 1s */
1322 iommu_set_inv_tlb_timeout(iommu, CTRL_INV_TO_1S);
1325 static void iommu_apply_resume_quirks(struct amd_iommu *iommu)
1328 u32 ioc_feature_control;
1329 struct pci_dev *pdev = iommu->root_pdev;
1331 /* RD890 BIOSes may not have completely reconfigured the iommu */
1332 if (!is_rd890_iommu(iommu->dev) || !pdev)
1336 * First, we need to ensure that the iommu is enabled. This is
1337 * controlled by a register in the northbridge
1340 /* Select Northbridge indirect register 0x75 and enable writing */
1341 pci_write_config_dword(pdev, 0x60, 0x75 | (1 << 7));
1342 pci_read_config_dword(pdev, 0x64, &ioc_feature_control);
1344 /* Enable the iommu */
1345 if (!(ioc_feature_control & 0x1))
1346 pci_write_config_dword(pdev, 0x64, ioc_feature_control | 1);
1348 /* Restore the iommu BAR */
1349 pci_write_config_dword(iommu->dev, iommu->cap_ptr + 4,
1350 iommu->stored_addr_lo);
1351 pci_write_config_dword(iommu->dev, iommu->cap_ptr + 8,
1352 iommu->stored_addr_hi);
1354 /* Restore the l1 indirect regs for each of the 6 l1s */
1355 for (i = 0; i < 6; i++)
1356 for (j = 0; j < 0x12; j++)
1357 iommu_write_l1(iommu, i, j, iommu->stored_l1[i][j]);
1359 /* Restore the l2 indirect regs */
1360 for (i = 0; i < 0x83; i++)
1361 iommu_write_l2(iommu, i, iommu->stored_l2[i]);
1363 /* Lock PCI setup registers */
1364 pci_write_config_dword(iommu->dev, iommu->cap_ptr + 4,
1365 iommu->stored_addr_lo | 1);
1369 * This function finally enables all IOMMUs found in the system after
1370 * they have been initialized
1372 static void enable_iommus(void)
1374 struct amd_iommu *iommu;
1376 for_each_iommu(iommu) {
1377 iommu_disable(iommu);
1378 iommu_init_flags(iommu);
1379 iommu_set_device_table(iommu);
1380 iommu_enable_command_buffer(iommu);
1381 iommu_enable_event_buffer(iommu);
1382 iommu_enable_ppr_log(iommu);
1383 iommu_enable_gt(iommu);
1384 iommu_set_exclusion_range(iommu);
1385 iommu_enable(iommu);
1386 iommu_flush_all_caches(iommu);
1390 static void disable_iommus(void)
1392 struct amd_iommu *iommu;
1394 for_each_iommu(iommu)
1395 iommu_disable(iommu);
1399 * Suspend/Resume support
1400 * disable suspend until real resume implemented
1403 static void amd_iommu_resume(void)
1405 struct amd_iommu *iommu;
1407 for_each_iommu(iommu)
1408 iommu_apply_resume_quirks(iommu);
1410 /* re-load the hardware */
1413 amd_iommu_enable_interrupts();
1416 static int amd_iommu_suspend(void)
1418 /* disable IOMMUs to go out of the way for BIOS */
1424 static struct syscore_ops amd_iommu_syscore_ops = {
1425 .suspend = amd_iommu_suspend,
1426 .resume = amd_iommu_resume,
1429 static void __init free_on_init_error(void)
1431 amd_iommu_uninit_devices();
1433 free_pages((unsigned long)amd_iommu_pd_alloc_bitmap,
1434 get_order(MAX_DOMAIN_ID/8));
1436 free_pages((unsigned long)amd_iommu_rlookup_table,
1437 get_order(rlookup_table_size));
1439 free_pages((unsigned long)amd_iommu_alias_table,
1440 get_order(alias_table_size));
1442 free_pages((unsigned long)amd_iommu_dev_table,
1443 get_order(dev_table_size));
1449 #ifdef CONFIG_GART_IOMMU
1451 * We failed to initialize the AMD IOMMU - try fallback to GART
1460 * This is the hardware init function for AMD IOMMU in the system.
1461 * This function is called either from amd_iommu_init or from the interrupt
1462 * remapping setup code.
1464 * This function basically parses the ACPI table for AMD IOMMU (IVRS)
1467 * 1 pass) Find the highest PCI device id the driver has to handle.
1468 * Upon this information the size of the data structures is
1469 * determined that needs to be allocated.
1471 * 2 pass) Initialize the data structures just allocated with the
1472 * information in the ACPI table about available AMD IOMMUs
1473 * in the system. It also maps the PCI devices in the
1474 * system to specific IOMMUs
1476 * 3 pass) After the basic data structures are allocated and
1477 * initialized we update them with information about memory
1478 * remapping requirements parsed out of the ACPI table in
1481 * After everything is set up the IOMMUs are enabled and the necessary
1482 * hotplug and suspend notifiers are registered.
1484 int __init amd_iommu_init_hardware(void)
1488 if (!amd_iommu_detected)
1491 if (amd_iommu_dev_table != NULL) {
1492 /* Hardware already initialized */
1497 * First parse ACPI tables to find the largest Bus/Dev/Func
1498 * we need to handle. Upon this information the shared data
1499 * structures for the IOMMUs in the system will be allocated
1501 if (acpi_table_parse("IVRS", find_last_devid_acpi) != 0)
1504 ret = amd_iommu_init_err;
1508 dev_table_size = tbl_size(DEV_TABLE_ENTRY_SIZE);
1509 alias_table_size = tbl_size(ALIAS_TABLE_ENTRY_SIZE);
1510 rlookup_table_size = tbl_size(RLOOKUP_TABLE_ENTRY_SIZE);
1512 /* Device table - directly used by all IOMMUs */
1514 amd_iommu_dev_table = (void *)__get_free_pages(GFP_KERNEL | __GFP_ZERO,
1515 get_order(dev_table_size));
1516 if (amd_iommu_dev_table == NULL)
1520 * Alias table - map PCI Bus/Dev/Func to Bus/Dev/Func the
1521 * IOMMU see for that device
1523 amd_iommu_alias_table = (void *)__get_free_pages(GFP_KERNEL,
1524 get_order(alias_table_size));
1525 if (amd_iommu_alias_table == NULL)
1528 /* IOMMU rlookup table - find the IOMMU for a specific device */
1529 amd_iommu_rlookup_table = (void *)__get_free_pages(
1530 GFP_KERNEL | __GFP_ZERO,
1531 get_order(rlookup_table_size));
1532 if (amd_iommu_rlookup_table == NULL)
1535 amd_iommu_pd_alloc_bitmap = (void *)__get_free_pages(
1536 GFP_KERNEL | __GFP_ZERO,
1537 get_order(MAX_DOMAIN_ID/8));
1538 if (amd_iommu_pd_alloc_bitmap == NULL)
1541 /* init the device table */
1542 init_device_table();
1545 * let all alias entries point to itself
1547 for (i = 0; i <= amd_iommu_last_bdf; ++i)
1548 amd_iommu_alias_table[i] = i;
1551 * never allocate domain 0 because its used as the non-allocated and
1552 * error value placeholder
1554 amd_iommu_pd_alloc_bitmap[0] = 1;
1556 spin_lock_init(&amd_iommu_pd_lock);
1559 * now the data structures are allocated and basically initialized
1560 * start the real acpi table scan
1563 if (acpi_table_parse("IVRS", init_iommu_all) != 0)
1566 if (amd_iommu_init_err) {
1567 ret = amd_iommu_init_err;
1571 if (acpi_table_parse("IVRS", init_memory_definitions) != 0)
1574 if (amd_iommu_init_err) {
1575 ret = amd_iommu_init_err;
1579 ret = amd_iommu_init_devices();
1585 amd_iommu_init_notifier();
1587 register_syscore_ops(&amd_iommu_syscore_ops);
1593 free_on_init_error();
1598 static int amd_iommu_enable_interrupts(void)
1600 struct amd_iommu *iommu;
1603 for_each_iommu(iommu) {
1604 ret = iommu_init_msi(iommu);
1614 * This is the core init function for AMD IOMMU hardware in the system.
1615 * This function is called from the generic x86 DMA layer initialization
1618 * The function calls amd_iommu_init_hardware() to setup and enable the
1619 * IOMMU hardware if this has not happened yet. After that the driver
1620 * registers for the DMA-API and for the IOMMU-API as necessary.
1622 static int __init amd_iommu_init(void)
1626 ret = amd_iommu_init_hardware();
1630 ret = amd_iommu_enable_interrupts();
1634 if (iommu_pass_through)
1635 ret = amd_iommu_init_passthrough();
1637 ret = amd_iommu_init_dma_ops();
1642 amd_iommu_init_api();
1644 x86_platform.iommu_shutdown = disable_iommus;
1646 if (iommu_pass_through)
1649 if (amd_iommu_unmap_flush)
1650 printk(KERN_INFO "AMD-Vi: IO/TLB flush on unmap enabled\n");
1652 printk(KERN_INFO "AMD-Vi: Lazy IO/TLB flushing enabled\n");
1660 free_on_init_error();
1665 /****************************************************************************
1667 * Early detect code. This code runs at IOMMU detection time in the DMA
1668 * layer. It just looks if there is an IVRS ACPI table to detect AMD
1671 ****************************************************************************/
1672 static int __init early_amd_iommu_detect(struct acpi_table_header *table)
1677 int __init amd_iommu_detect(void)
1679 if (no_iommu || (iommu_detected && !gart_iommu_aperture))
1682 if (amd_iommu_disabled)
1685 if (acpi_table_parse("IVRS", early_amd_iommu_detect) == 0) {
1687 amd_iommu_detected = 1;
1688 x86_init.iommu.iommu_init = amd_iommu_init;
1690 /* Make sure ACS will be enabled */
1697 /****************************************************************************
1699 * Parsing functions for the AMD IOMMU specific kernel command line
1702 ****************************************************************************/
1704 static int __init parse_amd_iommu_dump(char *str)
1706 amd_iommu_dump = true;
1711 static int __init parse_amd_iommu_options(char *str)
1713 for (; *str; ++str) {
1714 if (strncmp(str, "fullflush", 9) == 0)
1715 amd_iommu_unmap_flush = true;
1716 if (strncmp(str, "off", 3) == 0)
1717 amd_iommu_disabled = true;
1718 if (strncmp(str, "force_isolation", 15) == 0)
1719 amd_iommu_force_isolation = true;
1725 __setup("amd_iommu_dump", parse_amd_iommu_dump);
1726 __setup("amd_iommu=", parse_amd_iommu_options);
1728 IOMMU_INIT_FINISH(amd_iommu_detect,
1729 gart_iommu_hole_init,
1733 bool amd_iommu_v2_supported(void)
1735 return amd_iommu_v2_present;
1737 EXPORT_SYMBOL(amd_iommu_v2_supported);