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_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_PCI_SET_MVE

33 | v1.0 Initial Release | skiboot-7.1

OPAL_PCI_SET_MVE_ENABLE

34 | v1.0 Initial Release | skiboot-7.1

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.

OPAL_PCI_SET_MVE

Dead code, as the callback did nothing after the P7IOC code was removed in skiboot 6.4. Removed in skiboot-7.1.

OPAL_PCI_SET_MVE_ENABLE

Dead code, as the callback did nothing after the P7IOC code was removed in skiboot 6.4. Removed in skiboot-7.1.

Future Calls

OPAL_ELOG_WRITE

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