Skip to content

Latest commit

 

History

History
494 lines (447 loc) · 45.8 KB

index.rst

File metadata and controls

494 lines (447 loc) · 45.8 KB
Raw

OPAL API Documentation

The OPAL API is the interface between an Operating System and OPAL.

Name API Token ID Introduced Required as of Notes
:ref:`OPAL_TEST` 0 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CONSOLE_WRITE` 1 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CONSOLE_READ` 2 v1.0 (Initial Release) POWER8  
:ref:`OPAL_RTC_READ` 3 v1.0 (Initial Release) POWER8  
:ref:`OPAL_RTC_WRITE` 4 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CEC_POWER_DOWN` 5 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CEC_REBOOT` 6 v1.0 (Initial Release) POWER8  
:ref:`OPAL_READ_NVRAM` 7 v1.0 (Initial Release) POWER8  
:ref:`OPAL_WRITE_NVRAM` 8 v1.0 (Initial Release) POWER8  
:ref:`OPAL_HANDLE_INTERRUPT` 9 v1.0 (Initial Release) POWER8  
:ref:`OPAL_POLL_EVENTS` 10 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_HUB_TCE_MEMORY` 11 N/A Present only on internal systems.   Was POWER7 p5ioc specific. No use outside IBM development
:ref:`OPAL_PCI_SET_PHB_TCE_MEMORY` 12 N/A Present only on internal systems.   Was POWER7 p5ioc specific. No use outside IBM development
:ref:`OPAL_PCI_CONFIG_READ_BYTE` 13 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_CONFIG_READ_HALF_WORD` 14 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_CONFIG_READ_WORD` 15 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_CONFIG_WRITE_BYTE` 16 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_CONFIG_WRITE_HALF_WORD` 17 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_CONFIG_WRITE_WORD` 18 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SET_XIVE` 19 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_XIVE` 20 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_COMPLETION_TOKEN_STATUS` 21 Never   Never Implemented
:ref:`OPAL_REGISTER_OPAL_EXCEPTION_HANDLER` 22 v1.0 (Initial Release)   Removed
:ref:`OPAL_PCI_EEH_FREEZE_STATUS` 23 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SHPC` 24 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CONSOLE_WRITE_BUFFER_SPACE` 25 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_EEH_FREEZE_CLEAR` 26 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_PHB_MMIO_ENABLE` 27 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_PHB_MEM_WINDOW` 28 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_MAP_PE_MMIO_WINDOW` 29 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_PHB_TABLE_MEMORY` 30 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_PE` 31 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_PELTV` 32 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_MVE` 33 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_MVE_ENABLE` 34 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_GET_XIVE_REISSUE` 35 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_XIVE_REISSUE` 36 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_SET_XIVE_PE` 37 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_XIVE_SOURCE` 38 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_MSI_32` 39 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_MSI_64` 40 v1.0 (Initial Release) POWER8  
:ref:`OPAL_START_CPU` 41 v1.0 (Initial Release) POWER8  
:ref:`OPAL_QUERY_CPU_STATUS` 42 v1.0 (Initial Release) POWER8  
:ref:`OPAL_WRITE_OPPANEL` 43 v1.0 (Initial Release) POWER8 unimplemented
:ref:`OPAL_PCI_MAP_PE_DMA_WINDOW` 44 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_MAP_PE_DMA_WINDOW_REAL` 45 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_RESET` 49 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_GET_HUB_DIAG_DATA` 50 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_GET_PHB_DIAG_DATA` 51 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_FENCE_PHB` 52 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_REINIT` 53 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_MASK_PE_ERROR` 54 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SET_SLOT_LED_STATUS` 55 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_EPOW_STATUS` 56 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SET_SYSTEM_ATTENTION_LED` 57 v1.0 (Initial Release) POWER8  
:ref:`OPAL_RESERVED1` 58 v1.0 (Initial Release) POWER8  
:ref:`OPAL_RESERVED2` 59 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_NEXT_ERROR` 60 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_EEH_FREEZE_STATUS2` 61 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_POLL` 62 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_MSI_EOI` 63 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_GET_PHB_DIAG_DATA2` 64 v1.0 (Initial Release) POWER8  
:ref:`OPAL_XSCOM_READ` 65 v1.0 (Initial Release) POWER8  
:ref:`OPAL_XSCOM_WRITE` 66 v1.0 (Initial Release) POWER8  
:ref:`OPAL_LPC_READ` 67 v1.0 (Initial Release) POWER8  
:ref:`OPAL_LPC_WRITE` 68 v1.0 (Initial Release) POWER8  
:ref:`OPAL_RETURN_CPU` 69 v1.0 (Initial Release) POWER8  
:ref:`OPAL_REINIT_CPUS` 70 v1.0 (Initial Release) POWER8  
:ref:`OPAL_ELOG_READ` 71 v1.0 (Initial Release) POWER8  
:ref:`OPAL_ELOG_WRITE` 72 N/A   Currently unused.
:ref:`OPAL_ELOG_ACK` 73 v1.0 (Initial Release) POWER8  
:ref:`OPAL_ELOG_RESEND` 74 v1.0 (Initial Release) POWER8  
:ref:`OPAL_ELOG_SIZE` 75 v1.0 (Initial Release) POWER8  
:ref:`OPAL_FLASH_VALIDATE` 76 v1.0 (Initial Release) POWER8  
:ref:`OPAL_FLASH_MANAGE` 77 v1.0 (Initial Release) POWER8  
:ref:`OPAL_FLASH_UPDATE` 78 v1.0 (Initial Release) POWER8  
:ref:`OPAL_RESYNC_TIMEBASE` 79 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CHECK_TOKEN` 80 v1.0 (Initial Release) POWER8  
:ref:`OPAL_DUMP_INIT` 81 v1.0 (Initial Release) POWER8  
:ref:`OPAL_DUMP_INFO` 82 v1.0 (Initial Release) POWER8  
:ref:`OPAL_DUMP_READ` 83 v1.0 (Initial Release) POWER8  
:ref:`OPAL_DUMP_ACK` 84 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_MSG` 85 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CHECK_ASYNC_COMPLETION` 86 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SYNC_HOST_REBOOT` 87 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SENSOR_READ` 88 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_PARAM` 89 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SET_PARAM` 90 v1.0 (Initial Release) POWER8  
:ref:`OPAL_DUMP_RESEND` 91 v1.0 (Initial Release) POWER8  
:ref:`OPAL_ELOG_SEND` 92 v1.0 (Initial Release) POWER8 Deprecated
:ref:`OPAL_PCI_SET_PHB_CAPI_MODE` 93 v1.0 (Initial Release) POWER8  
:ref:`OPAL_DUMP_INFO2` 94 v1.0 (Initial Release) POWER8  
:ref:`OPAL_WRITE_OPPANEL_ASYNC` 95 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_ERR_INJECT` 96 v1.0 (Initial Release) POWER8  
:ref:`OPAL_PCI_EEH_FREEZE_SET` 97 v1.0 (Initial Release) POWER8  
:ref:`OPAL_HANDLE_HMI` 98 v1.0 (Initial Release) POWER8  
:ref:`OPAL_CONFIG_CPU_IDLE_STATE` 99 v1.0 (Initial Release) POWER8  
:ref:`OPAL_SLW_SET_REG` 100 v1.0 (Initial Release) POWER8  
:ref:`OPAL_REGISTER_DUMP_REGION` 101 v1.0 (Initial Release) POWER8  
:ref:`OPAL_UNREGISTER_DUMP_REGION` 102 v1.0 (Initial Release) POWER8  
:ref:`OPAL_WRITE_TPO` 103 v1.0 (Initial Release) POWER8  
:ref:`OPAL_READ_TPO` 104 v1.0 (Initial Release) POWER8  
:ref:`OPAL_GET_DPO_STATUS` 105 v1.0 (Initial Release) POWER8  
:ref:`OPAL_OLD_I2C_REQUEST` 106 Introduced and deprecated in :ref:`skiboot-4.0`. Should be completely unused.   Do not use.
:ref:`OPAL_IPMI_SEND` 107 :ref:`skiboot-4.0` POWER9  
:ref:`OPAL_IPMI_RECV` 108 :ref:`skiboot-4.0` POWER9  
:ref:`OPAL_I2C_REQUEST` 109 :ref:`skiboot-4.0` POWER9  
:ref:`OPAL_FLASH_READ` 110 :ref:`skiboot-5.0` POWER9  
:ref:`OPAL_FLASH_WRITE` 111 :ref:`skiboot-5.0` POWER9  
:ref:`OPAL_FLASH_ERASE` 112 :ref:`skiboot-5.0` POWER9  
:ref:`OPAL_PRD_MSG` 113 :ref:`skiboot-5.0` POWER9  
:ref:`OPAL_LEDS_GET_INDICATOR` 114 :ref:`skiboot-5.0` POWER9  
:ref:`OPAL_LEDS_SET_INDICATOR` 115 :ref:`skiboot-5.0` POWER9  
:ref:`OPAL_CEC_REBOOT2` 116 :ref:`skiboot-5.1.0` POWER9  
:ref:`OPAL_CONSOLE_FLUSH` 117 :ref:`skiboot-5.1.13` POWER9  
:ref:`OPAL_GET_DEVICE_TREE` 118 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_PCI_GET_PRESENCE_STATE` 119 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_PCI_GET_POWER_STATE` 120 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_PCI_SET_POWER_STATE` 121 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_INT_GET_XIRR` 122 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_INT_SET_CPPR` 123 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_INT_EOI` 124 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_INT_SET_MFRR` 125 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_PCI_TCE_KILL` 126 :ref:`skiboot-5.3.0` POWER9  
:ref:`OPAL_NMMU_SET_PTCR` 127 :ref:`skiboot-5.4.0` POWER9  
:ref:`OPAL_XIVE_RESET` 128 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_GET_IRQ_INFO` 129 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_GET_IRQ_CONFIG` 130 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_SET_IRQ_CONFIG` 131 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_GET_QUEUE_INFO` 132 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_SET_QUEUE_INFO` 133 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_DONATE_PAGE` 134 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_ALLOCATE_VP_BLOCK` 135 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_FREE_VP_BLOCK` 136 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_GET_VP_INFO` 137 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_SET_VP_INFO` 138 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_ALLOCATE_IRQ` 139 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_FREE_IRQ` 140 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_SYNC` 141 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_DUMP` 142 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_XIVE_GET_QUEUE_STATE` 143 :ref:`skiboot-6.3`    
:ref:`OPAL_XIVE_SET_QUEUE_STATE` 144 :ref:`skiboot-6.3`    
:ref:`OPAL_SIGNAL_SYSTEM_RESET` 145 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_NPU_INIT_CONTEXT` 146 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_NPU_DESTROY_CONTEXT` 147 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_NPU_MAP_LPAR` 148 :ref:`skiboot-5.5.0` POWER9  
:ref:`OPAL_IMC_COUNTERS_INIT` 149 :ref:`skiboot-5.7` POWER9  
:ref:`OPAL_IMC_COUNTERS_START` 150 :ref:`skiboot-5.7` POWER9  
:ref:`OPAL_IMC_COUNTERS_STOP` 151 :ref:`skiboot-5.7` POWER9  
:ref:`OPAL_GET_POWERCAP` 152 :ref:`skiboot-5.8` POWER9  
:ref:`OPAL_SET_POWERCAP` 153 :ref:`skiboot-5.8` POWER9  
:ref:`OPAL_GET_POWER_SHIFT_RATIO` 154 :ref:`skiboot-5.8` POWER9  
:ref:`OPAL_SET_POWER_SHIFT_RATIO` 155 :ref:`skiboot-5.8` POWER9  
:ref:`OPAL_SENSOR_GROUP_CLEAR` 156 :ref:`skiboot-5.8` POWER9  
:ref:`OPAL_PCI_SET_P2P` 157 :ref:`skiboot-5.8` POWER9  
:ref:`OPAL_QUIESCE` 158 :ref:`skiboot-5.10` POWER9  
:ref:`OPAL_NPU_SPA_SETUP` 159 :ref:`skiboot-5.11` POWER9  
:ref:`OPAL_NPU_SPA_CLEAR_CACHE` 160 :ref:`skiboot-5.11` POWER9  
:ref:`OPAL_NPU_TL_SET` 161 :ref:`skiboot-5.11` POWER9  
:ref:`OPAL_SENSOR_READ_U64` 162 :ref:`skiboot-5.10` POWER9  
:ref:`OPAL_SENSOR_GROUP_ENABLE` 163 :ref:`skiboot-5.10` POWER9  
:ref:`OPAL_PCI_GET_PBCQ_TUNNEL_BAR` 164 :ref:`skiboot-5.11` POWER9  
:ref:`OPAL_PCI_SET_PBCQ_TUNNEL_BAR` 165 :ref:`skiboot-5.11` POWER9  
:ref:`OPAL_HANDLE_HMI2` 166 :ref:`skiboot-6.0` POWER9  
:ref:`OPAL_NX_COPROC_INIT` 167 :ref:`skiboot-6.1` :ref:`skiboot-6.0.5`    
:ref:`OPAL_NPU_SET_RELAXED_ORDER` 168 :ref:`skiboot-6.2`    
:ref:`OPAL_NPU_GET_RELAXED_ORDER` 169 :ref:`skiboot-6.2`    
:ref:`OPAL_XIVE_GET_VP_STATE` 170 :ref:`skiboot-6.3`    
:ref:`OPAL_NPU_MEM_ALLOC` 171 Future, likely 6.4    
:ref:`OPAL_NPU_MEM_RELEASE` 172 Future, likely 6.4     
.. toctree::
   :maxdepth: 1
   :glob:

   *

Removed Calls

Under very specific and careful circumstances, an OPAL call has been removed and no longer supported.

Name API Token Introduced Removed
:ref:`OPAL_GET_COMPLETION_TOKEN_STATUS` 21 Never  
:ref:`OPAL_WRITE_OPPANEL` 43 pre-v1.0 pre-v1.0
:ref:`OPAL_OLD_I2C_REQUEST` 106 v4.0 v4.0
:ref:`OPAL_REGISTER_OPAL_EXCEPTION_HANDLER` 22 v1.0 Initial Release :ref:`skiboot-5.0`
:ref:`OPAL_PCI_SET_HUB_TCE_MEMORY` 11 pre-v1.0 :ref:`skiboot-5.2.0`
:ref:`OPAL_PCI_SET_PHB_TCE_MEMORY` 12 pre-v1.0 :ref:`skiboot-5.2.0`

OPAL_GET_COMPLETION_TOKEN_STATUS

In the before time, long-long ago, there existed something called OPAL before the incarnation we know today. Presumably, this long forgotten incarnation had a call called this.

This call has never been implemented, and never will be.

OPAL_WRITE_OPPANEL

Never in a released version, use :ref:`OPAL_WRITE_OPPANEL_ASYNC`.

OPAL_OLD_I2C_REQUEST

Never used. Only existing briefly in the :ref:`skiboot-4.0` development cycle.

OPAL_REGISTER_OPAL_EXCEPTION_HANDLER

#define OPAL_REGISTER_OPAL_EXCEPTION_HANDLER 22


int64_t opal_register_exc_handler(uint64_t opal_exception __unused,
                                  uint64_t handler_address __unused,
                                  uint64_t glue_cache_line __unused);

This call existed for a very short period of time and only ever worked with Big Endian host operating systems. The idea was that OPAL would handle HMIs and an OS could (if it chose to) register a handler for them. This call is not required since the introduction of :ref:`OPAL_HANDLE_HMI` and all machines that ever shipped without :ref:`OPAL_HANDLE_HMI` have a firmware update that supports it. For IBM Tuleta machines, this was FW810.20 (released Oct 2014) that had :ref:`OPAL_HANDLE_HMI` support.

This call was removed in :ref:`skiboot-5.0` and now just returns :ref:`OPAL_UNSUPPORTED`.

Use of the :ref:`OPAL_HANDLE_HMI` call was introduced in Linux 3.17.

OPAL_PCI_SET_HUB_TCE_MEMORY

#define OPAL_PCI_SET_HUB_TCE_MEMORY          11

int64_t opal_pci_set_hub_tce_memory(uint64_t hub_id,
                                    uint64_t tce_mem_addr __unused,
                                    uint64_t tce_mem_size __unused);

This call was only ever relevant for p5ioc based POWER7 systems. These were never available with OPAL outside of IBM development.

Support for POWER7 systems with p5ioc was dropped in :ref:`skiboot-5.2.0`, and these systems were only ever used with OPAL inside IBM for development and bring-up purposes.

Support for p5ioc was removed from the Linux kernel in v4.6-rc1.

OPAL_PCI_SET_PHB_TCE_MEMORY

#define OPAL_PCI_SET_PHB_TCE_MEMORY          12

int64_t opal_pci_set_phb_tce_memory(uint64_t phb_id,
                                    uint64_t tce_mem_addr,
                                    uint64_t tce_mem_size);

This call was only ever relevant for p5ioc based POWER7 systems. These were never available with OPAL outside of IBM development.

Support for POWER7 systems with p5ioc was dropped in :ref:`skiboot-5.2.0`, and these systems were only ever used with OPAL inside IBM for development and bring-up purposes.

Support for p5ioc was removed from the Linux kernel in v4.6-rc1.