1.. _OPAL_PCI_MAP_PE_DMA_WINDOW: 2 3OPAL_PCI_MAP_PE_DMA_WINDOW 4========================== 5 6.. code-block:: c 7 8 #define OPAL_PCI_MAP_PE_DMA_WINDOW 44 9 10 static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, 11 uint64_t pe_number, 12 uint16_t window_id, 13 uint16_t tce_levels, 14 uint64_t tce_table_addr, 15 uint64_t tce_table_size, 16 uint64_t tce_page_size); 17 18**WARNING:** following documentation is from old sources, and is possibly 19not representative of OPALv3 as implemented by skiboot. This should be 20used as a starting point for full documentation. 21 22The host calls this function to create a DMA window and map it to a PE. This 23call returns the address in PCI memory that corresponds to the specified DMA 24window, which in part may depend on the particular PHB DMA window used. An 25address that is all zeros in the upper 32 bits reflects a DMA window enabled 26for 32-bit DMA addresses. 27 28The overall size of the DMA window in PCI memory is determined by the number 29of tce_levels times the tce_table_size times the tce_page_size. 30 31``phb_id`` 32 is the value from the PHB node ``ibm,opal-phbid`` property. 33 34``dma_window_number`` 35 specifies the DMA window 36 37For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB 38total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number 39is an index from 0 to n-1, where n is the number of windows per window set, 40within the window set associated with the specified PE number. 41 42``pe_number`` 43 is the index of the PE that is authorized to DMA to this window 44 address space in PCI memory, 45 46``tce_levels`` 47 is the number of TCE table levels in the translation hiearchy, 48 from 1 to ibm,opal-dmawins property <translation levels>. 49 50``tce_table_addr`` 51 is the 64-bit system real address of the first level (root, 52 for mult-level) TCE table in the translation hiearchy. 53 54``tce_table_size`` 55 is the size, in bytes, of each TCE table in the translation 56 hierarchy. A value of '0' indicates to disable this DMA window. 57 58For ibm,opal-ioda, this must be a value in the range from 59128MB / tce_page_size to 256TB / tce_page_size, and must be in the format and 60matching a value in the tce_table ranges property that is minimally 256KB for 614K pages. 62 63A particular PE may be mapped to multiple DMA windows, each spanning a DMA 64window size corresponding to the win_size32 or win_size_64 specified in the 65ibm,opal-dmawins<> property. However, the TCE table base address must be 66unique for each window unless it is intended that the same page address in 67each DMA window is mapped through the same TCE table entry. Generally, when 68mapping the same PE to multiple DMA windows, so as to create a larger overall 69DMA window, it is recommended to use consecutive DMA windows and each DMA 70window should use a TCE table address that is offset by the win_size value of 71predecessor DMA window. 72 73``tce_page_size`` 74 is the size of PCI memory pages mapped to system real pages 75 through all TCE tables in the translation hierarchy. This must be the 76 same format as and match a value from the ibm,opal-dmawins property 77 <dma-page-sizes>. This page size applies to all TCE tables in the 78 translation hierarchy. 79 80``pci_start_addr`` 81 returns the starting address in PCI memory that corresponds 82 to this DMA window based on the input translation parameter values. 83 84``pci_mem_type`` 85 selects whether this DMA window should be created in 32-bit 86 or 64-bit PCI memory. The input values correspond to the same PCI memory 87 space locators as MMIO spaces in the ranges<> property -- 0x2 indicated 88 32-bit PCI memory and 0x3 indicates 64-bit memory. 89 90Window 0 for both ibm,opal-ioda and ibm,opal-ioda2 PHBs must be within 32-bit 91PCI memory and this call return opal_parameter for calls that specify window 920 in 64-bit PCI memory. 93 94The DMA win_size property for 32 bit DMA windows limits the number of 95ibm,opal-ioda PHB windows that can map32-bit address space. For example, with 96a win_size_32 = 256MB, only 16 DMA windows (and therefore no more than 16 97distinct PEs) can map the 4GB of 32-bit PCI memory for DMA. OPAL does not 98police this limitation. 99 100Return value: 101 102.. code-block:: c 103 104 if (!phb) 105 return OPAL_PARAMETER; 106 if (!phb->ops->map_pe_dma_window) 107 return OPAL_UNSUPPORTED; 108