OPAL API Documentation

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

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

Removed Calls

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

Name API Token Introduced Removed
OPAL_GET_COMPLETION_TOKEN_STATUS 21 Never  
OPAL_PCI_SHPC 24 Never  
OPAL_PCI_SET_PHB_TABLE_MEMORY 30 Never  
OPAL_PCI_GET_XIVE_REISSUE 35 Never  
OPAL_PCI_GET_XIVE_REISSUE 36 Never  
OPAL_PCI_FENCE_PHB 52 Never  
OPAL_PCI_MASK_PE_ERROR 54 Never  
OPAL_SET_SLOT_LED_STATUS 55 Never  
OPAL_SET_SYSTEM_ATTENTION_LED 57 Never  
OPAL_RESERVED1 58 Never  
OPAL_RESERVED2 59 Never  
OPAL_ELOG_SEND 92 pre-v1.0 pre-v1.0
OPAL_PCI_GET_PHB_DIAG_DATA 51 pre-v1.0 pre-v1.0, with last remnants removed in skiboot-6.4
OPAL_GET_XIVE_SOURCE 38 v1.0 Initial Release skiboot-6.4
OPAL_WRITE_OPPANEL 43 pre-v1.0 pre-v1.0
OPAL_OLD_I2C_REQUEST 106 v4.0 v4.0
OPAL_REGISTER_OPAL_EXCEPTION_HANDLER 22 v1.0 Initial Release skiboot 5.0
OPAL_PCI_SET_HUB_TCE_MEMORY 11 pre-v1.0 skiboot-5.2.0
OPAL_PCI_SET_PHB_TCE_MEMORY 12 pre-v1.0 skiboot-5.2.0
OPAL_PCI_EEH_FREEZE_STATUS2 61 v1.0 Initial Release skiboot-6.4

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_PCI_SHPC

A remnant of a long forgotten incarnation of OPAL. Never implemented, never will be.

OPAL_PCI_SET_PHB_TABLE_MEMORY

A remnant of an old API design. Never implemented, never used. Only ever returned OPAL_UNSUPPORTED, now the call is not implemented at all.

OPAL_PCI_GET_XIVE_REISSUE

A remnant of something prior to OPALv3. Never implemented in skiboot and never used by anyone. Returend OPAL_UNSUPPORTED until skiboot-6.4, where it was removed.

OPAL_PCI_SET_XIVE_REISSUE

A remnant of something prior to OPALv3. Never implemented in skiboot and never used by anyone. Returend OPAL_UNSUPPORTED until skiboot-6.4, where it was removed.

OPAL_PCI_FENCE_PHB

Never implemented.

OPAL_PCI_MASK_PE_ERROR

Never implemented.

OPAL_SET_SLOT_LED_STATUS

Never implemented.

OPAL_SET_SYSTEM_ATTENTION_LED

Never implemented.

OPAL_RESERVED1

Reserved for future use, but never used.

OPAL_RESERVED2

Reserved for future use, but never used.

OPAL_ELOG_SEND

Brielfy present prior to the first public release of OPAL. Never used in any public kernel tree. If this functionality were to ever be implemented, it’d appear as OPAL_ELOG_WRITE rather than this call.

OPAL_PCI_GET_PHB_DIAG_DATA

This call was introduced and functionally removed (all backends for it were) before the first public opal release. It has not been used since Linux 3.11-rc1. Considering the state of EEH in such old kernels and firmware, removing the remnants of this call is considered safe. If for some bizarre reason such an old kernel is run on skiboot-6.4 or later, an OPAL_PARAMETER error will be returned instead of OPAL_UNSUPPORTED.

It is replaced by OPAL_PCI_GET_PHB_DIAG_DATA2 instead.

OPAL_GET_XIVE_SOURCE

While this call was technically implemented by skiboot, no code has ever called it, and it was only ever implemented for the p7ioc-phb back-end (i.e. POWER7). Since this call was unused in Linux, and that POWER7 with OPAL was only ever available internally, it was determined that it was safe to remove this call as of skiboot-6.4.

OPAL_WRITE_OPPANEL

Never in a released version, use OPAL_WRITE_OPPANEL_ASYNC.

OPAL_OLD_I2C_REQUEST

Never used. Only existing briefly in the 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 OPAL_HANDLE_HMI and all machines that ever shipped without OPAL_HANDLE_HMI have a firmware update that supports it. For IBM Tuleta machines, this was FW810.20 (released Oct 2014) that had OPAL_HANDLE_HMI support.

This call was removed in skiboot 5.0 and now just returns OPAL_UNSUPPORTED.

Use of the 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 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 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.

Future Calls

OPAL_ELOG_WRITE

May be implemented in the future to complement the OPAL_ELOG_READ call.