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