diff options
author | Stewart Smith <stewart@linux.vnet.ibm.com> | 2015-06-11 14:22:34 +1000 |
---|---|---|
committer | Stewart Smith <stewart@linux.vnet.ibm.com> | 2015-06-11 14:22:34 +1000 |
commit | e0ab4a2dae4028eaeb9a188c901704f40dc6e872 (patch) | |
tree | f90d874dd53814cbb62dcc3638a0240883043ef8 /doc | |
parent | a38800182cacbc409abc28476f79d7e425ef20dd (diff) | |
download | skiboot-e0ab4a2dae4028eaeb9a188c901704f40dc6e872.zip skiboot-e0ab4a2dae4028eaeb9a188c901704f40dc6e872.tar.gz skiboot-e0ab4a2dae4028eaeb9a188c901704f40dc6e872.tar.bz2 |
Add the final bits of old docs OPAL calls related to PCI
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/opal-api/opal-pci-map-pe-dma-window-44.txt | 92 | ||||
-rw-r--r-- | doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt | 39 | ||||
-rw-r--r-- | doc/opal-api/opal-pci-map-pe-mmio-window-29.txt | 39 | ||||
-rw-r--r-- | doc/opal-api/opal-pci-set-phb-mem-window-28.txt | 71 |
4 files changed, 241 insertions, 0 deletions
diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-44.txt b/doc/opal-api/opal-pci-map-pe-dma-window-44.txt new file mode 100644 index 0000000..0793209 --- /dev/null +++ b/doc/opal-api/opal-pci-map-pe-dma-window-44.txt @@ -0,0 +1,92 @@ +OPAL_PCI_MAP_PE_DMA_WINDOW +-------------------------- + +#define OPAL_PCI_MAP_PE_DMA_WINDOW 44 + + +static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, uint16_t pe_number, + uint16_t window_id, + uint16_t tce_levels, + uint64_t tce_table_addr, + uint64_t tce_table_size, + uint64_t tce_page_size) + +WARNING: following documentation is from old sources, and is possibly +not representative of OPALv3 as implemented by skiboot. This should be +used as a starting point for full documentation. + +The host calls this function to create a DMA window and map it to a PE. This +call returns the address in PCI memory that corresponds to the specified DMA +window, which in part may depend on the particular PHB DMA window used. An +address that is all zeros in the upper 32 bits reflects a DMA window enabled +for 32-bit DMA addresses. + +The overall size of the DMA window in PCI memory is determined by the number +of tce_levels times the tce_table_size times the tce_page_size. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + dma_window_number specifies the DMA window + +For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB +total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number +is an index from 0 to n-1, where n is the number of windows per window set, +within the window set associated with the specified PE number. + + pe_number is the index of the PE that is authorized to DMA to this window + address space in PCI memory, + + tce_levels is the number of TCE table levels in the translation hiearchy, + from 1 to ibm,opal-dmawins property <translation levels>. + + tce_table_addr is the 64-bit system real address of the first level (root, + for mult-level) TCE table in the translation hiearchy. + + tce_table_size is the size, in bytes, of each TCE table in the translation + hierarchy. A value of '0' indicates to disable this DMA window. + +For ibm,opal-ioda, this must be a value in the range from +128MB / tce_page_size to 256TB / tce_page_size, and must be in the format and +matching a value in the tce_table ranges property that is minimally 256KB for +4K pages. + +A particular PE may be mapped to multiple DMA windows, each spanning a DMA +window size corresponding to the win_size32 or win_size_64 specified in the +ibm,opal-dmawins<> property. However, the TCE table base address must be +unique for each window unless it is intended that the same page address in +each DMA window is mapped through the same TCE table entry. Generally, when +mapping the same PE to multiple DMA windows, so as to create a larger overall +DMA window, it is recommended to use consecutive DMA windows and each DMA +window should use a TCE table address that is offset by the win_size value of +predecessor DMA window. + + tce_page_size is the size of PCI memory pages mapped to system real pages + through all TCE tables in the translation hierarchy. This must be the + same format as and match a value from the ibm,opal-dmawins property + <dma-page-sizes>. This page size applies to all TCE tables in the + translation hierarchy. + + pci_start_addr returns the starting address in PCI memory that corresponds + to this DMA window based on the input translation parameter values. + + pci_mem_type selects whether this DMA window should be created in 32-bit + or 64-bit PCI memory. The input values correspond to the same PCI memory + space locators as MMIO spaces in the ranges<> property -- 0x2 indicated + 32-bit PCI memory and 0x3 indicates 64-bit memory. + +Window 0 for both ibm,opal-ioda and ibm,opal-ioda2 PHBs must be within 32-bit +PCI memory and this call return opal_parameter for calls that specify window +0 in 64-bit PCI memory. + +The DMA win_size property for 32 bit DMA windows limits the number of +ibm,opal-ioda PHB windows that can map32-bit address space. For example, with +a win_size_32 = 256MB, only 16 DMA windows (and therefore no more than 16 +distinct PEs) can map the 4GB of 32-bit PCI memory for DMA. OPAL does not +police this limitation. + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->map_pe_dma_window) + return OPAL_UNSUPPORTED; + diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt new file mode 100644 index 0000000..28ea112 --- /dev/null +++ b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.txt @@ -0,0 +1,39 @@ +OPAL_PCI_MAP_PE_DMA_WINDOW_REAL +------------------------------- + +#define OPAL_PCI_MAP_PE_DMA_WINDOW_REAL 45 + +WARNING: following documentation is from old sources, and is possibly +not representative of OPALv3 as implemented by skiboot. This should be +used as a starting point for full documentation. + +The host calls this function to initialize the specified DMA window for +untranslated DMA addresses. This allows a PE to DMA directly to system memory +without TCE translation. The DMA window PCI memory address is equal to the +system memory real address. The PHB passes PCI address bits 04:63 directly to +system real address bits 04:63 when PCI address bits 04:39 are within the +region specified by mem_addr t0 mem_addr + window_size. + +The addresses must be 16MB aligned and a multiple of 16MB in size. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + dma_window_number specifies the DMA window + +For ibm,opal-ioda PHBs the dma_window_number is an index from 0 to the PHB +total number of windows minus 1. For ibm,opal-ioda2 PHBs the DMA window_number +is an index from 0 to n-1, where n is the number of windows per window set, +within the window set associated with the specified PE number. + + pe_number is the index of the PE that is authorized to DMA to this window + address space in PCI memory, + + mem_addr is the starting 64-bit system real address mapped directly to the + starting address in PCI memory. Addresses below 4GB are zero in bits above + bit 32. This value must be aligned on a 16MB boundary; OPAL returns + OPAL_PARAMETER for any value that is not a multiple of 16MB. + + window_size is the size, in bytes, of the address range defined by this + window. This value must be a multiple of 16MB; OPAL returns OPAL_PARAMETER + for any value that is not a multiple of 16MB. A value of '0' indicates to + disable this DMA window. diff --git a/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt b/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt new file mode 100644 index 0000000..4f43506 --- /dev/null +++ b/doc/opal-api/opal-pci-map-pe-mmio-window-29.txt @@ -0,0 +1,39 @@ +OPAL_PCI_MAP_PE_MMIO_WINDOW +--------------------------- +#define OPAL_PCI_MAP_PE_MMIO_WINDOW 29 + +static int64_t opal_pci_map_pe_mmio_window(uint64_t phb_id, uint16_t pe_number, + uint16_t window_type, + uint16_t window_num, + uint16_t segment_num) + +WARNING: following documentation is from old sources, and is possibly +not representative of OPALv3 as implemented by skiboot. This should be +used as a starting point for full documentation. + +The host calls this function to map a segment of MMIO address space to a PE. + + phb_id is the value from the PHB node ibm,opal-phbid property. + + window_type specifies 32-bit or 64-bit PCI memory + + '0' selects PCI IO Space. ibm,opal-ioda2 PHBs do not support IO space, + and OPAL returns opal_unsupported if called for IO windows. + + '1' selects 32-bit PCI memory space + + '2' selects 64 bit PCI memory space + + window_num is the MMIO window number within the specified PCI memory space + + segment_num is an index from 0 to the number of segments minus 1 defined + or this window, and selects a particular segment within the specified + window. + + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->map_pe_mmio_window) + return OPAL_UNSUPPORTED; + diff --git a/doc/opal-api/opal-pci-set-phb-mem-window-28.txt b/doc/opal-api/opal-pci-set-phb-mem-window-28.txt new file mode 100644 index 0000000..8a355e8 --- /dev/null +++ b/doc/opal-api/opal-pci-set-phb-mem-window-28.txt @@ -0,0 +1,71 @@ +OPAL_PCI_SET_PHB_MEM_WINDOW +--------------------------- + +#define OPAL_PCI_SET_PHB_MEM_WINDOW 28 + +static int64_t opal_pci_set_phb_mem_window(uint64_t phb_id, + uint16_t window_type, + uint16_t window_num, + uint64_t addr, + uint64_t pci_addr, + uint64_t size) + +WARNING: following documentation is from old sources, and is possibly +not representative of OPALv3 as implemented by skiboot. This should be +used as a starting point for full documentation. + +The host calls this function to set the PHB PCI memory window parameters for +PHBs. OPAL sets IO space for P7IOC and KVM cannot relocate this. KVM should +changes these windows only while all devices below the PHB are disabled for +PCI memory ops, and with the target window in disabled state (where supported +by PHB hardware). + + phb_id is the value from the PHB node ibm,opal-phbid property. + + window_type specifies 32-bit or 64-bit PCI memory + + '0' selects IO space, and is not supported for relocation. OPAL + returns OPAL_UNSUPPORTED for this value. + + '1' selects 32-bit PCI memory space + + '2' selects 64 bit PCI memory space + + window_num is the MMIO window number within the specified PCI memory space + + starting_real_address specifies the location within sytsem (processor)real + address space this MMIO window starts. This must be a location within the + IO Hub or PHB node ibm,opal-mmio-real property. + + starting_pci_address specifies the location within PCI 32 or 64-bit + address space that this MMIO window starts. For 64-bit PCI memory, this + must be within the low order 60 bit (1 Exabyte) region of PCI memory. + Addresses above 1EB are reserved to IODA definitions. + + segment_size defines the segment size of this window, in the same format + as and a matching value from the ibm,opal-memwin32/64 <segment_size> + property. The window total size, in bytes, is the segment_size times the + ibm,opal-memwin32/64 <num_segments> property and must not extend beyond + the ibm,opal-mmio-real property range within system real address space. + The total MMIO window size is the segment_size times the num_segments + supported for the specifice window. The host must assure that the + cumulative address space for all enabled windows does not exceed the total + PHB 32-bit or 64-bit real address window space, or extend outside these + address ranges, and that no windows overlap each other in real or PCI + address space. OPAL does not validate those conditions. + +A segment size of '0' indicates to disable this MMIO window. If the PHB +hardware does not support disabling a window, OPAL returns OPAL_UNSUPPORTED +status. + +The size of the system real and PCI memory spaces are equal and defined by +segment_size times the number of segments within this MMIO window. + +The host must set PHB memory windows to be within the system real address +ranges indicated in the PHB parent HDT hub node ibm,opal-mmio-real property. + +Return value: + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_phb_mem_window) + return OPAL_UNSUPPORTED; |