diff options
Diffstat (limited to 'roms/skiboot/doc/opal-api')
90 files changed, 7644 insertions, 0 deletions
diff --git a/roms/skiboot/doc/opal-api/index.rst b/roms/skiboot/doc/opal-api/index.rst new file mode 100644 index 000000000..663108889 --- /dev/null +++ b/roms/skiboot/doc/opal-api/index.rst @@ -0,0 +1,676 @@ +.. _opal-api: + +====================== +OPAL API Documentation +====================== + +The OPAL API is the interface between an Operating System and OPAL. + ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| Name | API Token ID | Introduced | Required | Notes | +| | | | as of | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | | Was POWER7 | +| | | Present only on | | p5ioc specific. | +| | | internal systems. | | No use outside | +| | | | | IBM development | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_SET_PHB_TCE_MEMORY` | 12 | N/A | | Was POWER7 | +| | | Present only on | | p5ioc specific. | +| | | internal systems. | | 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 | Never | POWER8 | Never | +| | | | | Implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | Never | POWER8 | Never used or | +| | | | | Implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | Never | | Never used or | +| | | | | Implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_SET_XIVE_REISSUE` | 36 | Never | | Never used or | +| | | | | Implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_SET_XIVE_PE` | 37 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_GET_XIVE_SOURCE` | 38 | v1.0 (Initial Release) | POWER8 | Never used, | +| | | | | now removed. | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| Never used | 46 | | | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| Never used | 47 | | | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| Never used | 48 | | | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | N/A | | Only | +| | | | | implemented | +| | | | | prior to public | +| | | | | release. | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_FENCE_PHB` | 52 | Never | | Never | +| | | | | implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_REINIT` | 53 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_MASK_PE_ERROR` | 54 | Never | | Never | +| | | | | implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_SET_SLOT_LED_STATUS` | 55 | Never | | Never | +| | | | | implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_GET_EPOW_STATUS` | 56 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_SET_SYSTEM_ATTENTION_LED` | 57 | Never | | Never | +| | | | | implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_RESERVED1` | 58 | Never | | Never | +| | | | | implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_RESERVED2` | 59 | Never | | Never | +| | | | | implemented | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_NEXT_ERROR` | 60 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PCI_EEH_FREEZE_STATUS2` | 61 | v1.0 (Initial Release) | POWER8 | Removed, never | +| | | | | used! | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | Never | | Never used | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | | Do not use. | +| | | deprecated in | | | +| | | :ref:`skiboot-4.0`. | | | +| | | Should be completely | | | +| | | unused. | | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :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 | | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_MPIPL_UPDATE` | 173 | Future, likely 6.4 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_MPIPL_REGISTER_TAG` | 174 | Future, likely 6.4 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_MPIPL_QUERY_TAG` | 175 | Future, likely 6.4 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PHB_SET_OPTION` | 179 | Future, likely 6.6 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_PHB_GET_OPTION` | 180 | Future, likely 6.6 | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ + +.. toctree:: + :maxdepth: 1 + :glob: + + * + + +Removed Calls +------------- + +Under **very** specific and careful circumstances, an OPAL call has been +removed and no longer supported. + ++---------------------------------------------+-------+-----------------------+-----------------------+ +| Name | API | Introduced | Removed | +| | Token | | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_GET_COMPLETION_TOKEN_STATUS` | 21 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_SHPC` | 24 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_SET_PHB_TABLE_MEMORY` | 30 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_GET_XIVE_REISSUE` | 35 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_GET_XIVE_REISSUE` | 36 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_FENCE_PHB` | 52 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_MASK_PE_ERROR` | 54 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_SET_SLOT_LED_STATUS` | 55 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_SET_SYSTEM_ATTENTION_LED` | 57 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_RESERVED1` | 58 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_RESERVED2` | 59 | Never | | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_ELOG_SEND` | 92 | pre-v1.0 | pre-v1.0 | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_GET_PHB_DIAG_DATA` | 51 | pre-v1.0 | pre-v1.0, with last | +| | | | remnants removed in | +| | | | :ref:`skiboot-6.4` | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_GET_XIVE_SOURCE` | 38 | v1.0 Initial Release | :ref:`skiboot-6.4` | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :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` | ++---------------------------------------------+-------+-----------------------+-----------------------+ +| :ref:`OPAL_PCI_EEH_FREEZE_STATUS2` | 61 | v1.0 Initial Release | :ref:`skiboot-6.4` | ++---------------------------------------------+-------+-----------------------+-----------------------+ + +.. _OPAL_GET_COMPLETION_TOKEN_STATUS: + +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: + +OPAL_PCI_SHPC +^^^^^^^^^^^^^ + +A remnant of a long forgotten incarnation of OPAL. Never implemented, never +will be. + +.. _OPAL_PCI_SET_PHB_TABLE_MEMORY: + +OPAL_PCI_SET_PHB_TABLE_MEMORY +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A remnant of an old API design. Never implemented, never used. Only ever +returned :ref:`OPAL_UNSUPPORTED`, now the call is not implemented at all. + +.. _OPAL_PCI_GET_XIVE_REISSUE: + +OPAL_PCI_GET_XIVE_REISSUE +^^^^^^^^^^^^^^^^^^^^^^^^^ + +A remnant of something prior to OPALv3. Never implemented in skiboot and never +used by anyone. Returend :ref:`OPAL_UNSUPPORTED` until :ref:`skiboot-6.4`, where +it was removed. + +.. _OPAL_PCI_SET_XIVE_REISSUE: + +OPAL_PCI_SET_XIVE_REISSUE +^^^^^^^^^^^^^^^^^^^^^^^^^ + +A remnant of something prior to OPALv3. Never implemented in skiboot and never +used by anyone. Returend :ref:`OPAL_UNSUPPORTED` until :ref:`skiboot-6.4`, where +it was removed. + +.. _OPAL_PCI_FENCE_PHB: + +OPAL_PCI_FENCE_PHB +^^^^^^^^^^^^^^^^^^ + +Never implemented. + +.. _OPAL_PCI_MASK_PE_ERROR: + +OPAL_PCI_MASK_PE_ERROR +^^^^^^^^^^^^^^^^^^^^^^ + +Never implemented. + +.. _OPAL_SET_SLOT_LED_STATUS: + +OPAL_SET_SLOT_LED_STATUS +^^^^^^^^^^^^^^^^^^^^^^^^ + +Never implemented. + +.. _OPAL_SET_SYSTEM_ATTENTION_LED: + +OPAL_SET_SYSTEM_ATTENTION_LED +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Never implemented. + +.. _OPAL_RESERVED1: + +OPAL_RESERVED1 +^^^^^^^^^^^^^^ + +Reserved for future use, but never used. + +.. _OPAL_RESERVED2: + +OPAL_RESERVED2 +^^^^^^^^^^^^^^ + +Reserved for future use, but never used. + +.. _OPAL_ELOG_SEND: + +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 :ref:`OPAL_ELOG_WRITE` rather than this call. + +.. _OPAL_PCI_GET_PHB_DIAG_DATA: + +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 :ref:`skiboot-6.4` or later, an :ref:`OPAL_PARAMETER` error +will be returned instead of :ref:`OPAL_UNSUPPORTED`. + +It is replaced by :ref:`OPAL_PCI_GET_PHB_DIAG_DATA2` instead. + +.. _OPAL_GET_XIVE_SOURCE: + +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 :ref:`skiboot-6.4`. + +.. _OPAL_WRITE_OPPANEL: + +OPAL_WRITE_OPPANEL +^^^^^^^^^^^^^^^^^^ + +Never in a released version, use :ref:`OPAL_WRITE_OPPANEL_ASYNC`. + +.. _OPAL_OLD_I2C_REQUEST: + +OPAL_OLD_I2C_REQUEST +^^^^^^^^^^^^^^^^^^^^ + +Never used. Only existing briefly in the :ref:`skiboot-4.0` development cycle. + + +.. _OPAL_REGISTER_OPAL_EXCEPTION_HANDLER: + +OPAL_REGISTER_OPAL_EXCEPTION_HANDLER +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + + #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: + +OPAL_PCI_SET_HUB_TCE_MEMORY +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + + #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: + +OPAL_PCI_SET_PHB_TCE_MEMORY +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + + #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. + + +Future Calls +------------ + +.. _OPAL_ELOG_WRITE: + +OPAL_ELOG_WRITE +^^^^^^^^^^^^^^^ + +May be implemented in the future to complement the :ref:`OPAL_ELOG_READ` call. diff --git a/roms/skiboot/doc/opal-api/opal-cec-power-down-5.rst b/roms/skiboot/doc/opal-api/opal-cec-power-down-5.rst new file mode 100644 index 000000000..7a84fce89 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-cec-power-down-5.rst @@ -0,0 +1,76 @@ +.. _OPAL_CEC_POWER_DOWN: + +OPAL_CEC_POWER_DOWN +=================== + +.. code-block:: c + + #define OPAL_CEC_POWER_DOWN 5 + + int64 opal_cec_power_down(uint64 request) + +As powering down the system is likely an asynchronous operation that we +have to wait for a service processor to do, :ref:`OPAL_CEC_POWER_DOWN` +should be called like the example code below: + +.. code-block:: c + + int rc = OPAL_BUSY; + + do { + rc = opal_cec_power_down(0); + if (rc == OPAL_BUSY_EVENT) + opal_poll_events(NULL); + } while (rc == OPAL_BUSY || rc == OPAL_BUSY_EVENT); + + for (;;) + opal_poll_events(NULL); + + +Arguments +--------- + +`uint64 request` values as follows: + +0 + Power down normally +1 + Power down immediately + +This OPAL call requests OPAL to power down the system. The exact difference +between a normal and immediate shutdown is platform specific. + +Current Linux kernels just use power down normally (0). It is valid for a +platform to only support some types of power down operations. + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + the power down request was successful. + This may/may not result in immediate power down. An OS should + spin in a loop after getting :ref:`OPAL_SUCCESS` as it is likely that there + will be a delay before instructions stop being executed. + +:ref:`OPAL_BUSY` + unable to power down, try again later. + +:ref:`OPAL_BUSY_EVENT` + Unable to power down, call :ref:`OPAL_POLL_EVENTS` and try again. + +:ref:`OPAL_PARAMETER` + a parameter was incorrect + +:ref:`OPAL_INTERNAL_ERROR` + Something went wrong, and waiting and trying again is unlikely to be + successful. Although, considering that in a shutdown code path, there's + unlikely to be any other valid option to take, retrying is perfectly valid. + + In older OPAL versions (prior to skiboot v5.9), on IBM FSP systems, this + return code was returned erroneously instead of :ref:`OPAL_BUSY_EVENT` during an + FSP Reset/Reload. + +:ref:`OPAL_UNSUPPORTED` + this platform does not support being powered off. Practically speaking, this + should **never** be returned, but in various simulation or bring-up situations, + it's plausible it is, so code should handle this gracefully. diff --git a/roms/skiboot/doc/opal-api/opal-cec-reboot-6-116.rst b/roms/skiboot/doc/opal-api/opal-cec-reboot-6-116.rst new file mode 100644 index 000000000..431098f3b --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-cec-reboot-6-116.rst @@ -0,0 +1,152 @@ +.. _opal-api-cec-reboot: + +OPAL_CEC_REBOOT and OPAL_CEC_REBOOT2 +==================================== + +.. code-block:: c + + #define OPAL_CEC_REBOOT 6 + #define OPAL_CEC_REBOOT2 116 + +There are two opal calls to invoke system reboot. + +:ref:`OPAL_CEC_REBOOT` + Original reboot call for a normal reboot. + It is recommended to first try :ref:`OPAL_CEC_REBOOT2` + (use :ref:`OPAL_CHECK_TOKEN` first), and then, if not available, + fall back to :ref:`OPAL_CEC_REBOOT`. + All POWER9 systems shipped with support for :ref:`OPAL_CEC_REBOOT2`, + so it is safe to exclusively call the new call if an OS only targets POWER9 + and above. + +:ref:`OPAL_CEC_REBOOT2` + Newer call for rebooting a system, supporting different types of reboots. + For example, the OS may request a reboot due to a platform or OS error, + which may trigger host or BMC firmware to save debugging information. + +.. _OPAL_CEC_REBOOT: + +OPAL_CEC_REBOOT +--------------- +Syntax: :: + + int64_t opal_cec_reboot(void) + +System reboots normally, equivalent to :ref:`OPAL_CEC_REBOOT2`. See +:ref:`OPAL_CEC_REBOOT2` for details, as both OPAL calls should be called +in the same way. + +.. _OPAL_CEC_REBOOT2: + +OPAL_CEC_REBOOT2 +---------------- +Syntax: + +.. code-block:: c + + int64_t opal_cec_reboot2(uint32_t reboot_type, char *diag) + +A reboot call is likely going to involve talking to a service processor to +request a reboot, which can be quite a slow operation. Thus, the correct +way for an OS to make an OPAL reboot call is to spin on :ref:`OPAL_POLL_EVENTS` +to crank any state machine needed for the reboot until the machine reboots +from underneath the OS. + +For example, the below code could be part of an OS calling to do any type +of reboot, and falling back to a normal reboot if that type is not supported. + +.. code-block:: c + + int rc; + int reboot_type = OPAL_REBOOT_NORMAL; + + do { + if (opal_check_token(OPAL_CEC_REBOOT2) == 0) { + rc = opal_cec_reboot2(reboot_type, NULL); + } else { + rc = opal_cec_reboot(); + } + if (rc == OPAL_UNSUPPORTED) { + printf("Falling back to normal reboot\n"); + reboot_type = OPAL_REBOOT_NORMAL; + rc = OPAL_BUSY; + } + opal_poll_events(NULL); + } while (rc == OPAL_BUSY || rc == OPAL_BUSY_EVENT); + + for (;;) + opal_poll_events(NULL); + + +Input parameters +^^^^^^^^^^^^^^^^ +``reboot_type`` + Type of reboot. (see below) + +``diag`` + Null-terminated string. + +Depending on reboot type, this call will carry out additional steps +before triggering a reboot. + +Return Codes +^^^^^^^^^^^^ + +:ref:`OPAL_SUCCESS` + The system will soon reboot. The OS should loop on :ref:`OPAL_POLL_EVENTS` + in case there's any work for OPAL to do. + +:ref:`OPAL_BUSY` or :ref:`OPAL_BUSY_EVENT` + OPAL is currently busy and can't issue a reboot, call + :ref:`OPAL_POLL_EVENTS` and retry reboot call. + +:ref:`OPAL_UNSUPPORTED` + Unsupported reboot type (applicable to :ref:`OPAL_CEC_REBOOT2` only), retry + with other reboot type. + +Other error codes + Keep calling reboot and hope for the best? In theory this should never happen. + + +Supported reboot types: +----------------------- + +OPAL_REBOOT_NORMAL = 0 + Behavior is as similar to that of opal_cec_reboot() + +OPAL_REBOOT_PLATFORM_ERROR = 1 + Log an error to the BMC and then trigger a system checkstop, using + the information provided by 'ibm,sw-checkstop-fir' property in the + device-tree. Post the checkstop trigger, OCC/BMC will collect + relevant data for error analysis and trigger a reboot. + + In absence of 'ibm,sw-checkstop-fir' device property, this function + will return with OPAL_UNSUPPORTED and no reboot will be triggered. + +OPAL_REBOOT_FULL_IPL = 2 + Force a full IPL reboot rather than using fast reboot. + + On platforms that don't support fast reboot, this is equivalent to a + normal reboot. + +OPAL_REBOOT_MPIPL = 3 + Request for MPIPL reboot. Firmware will reboot the system and collect + dump. + + On platforms that don't support MPIPL, this is equivalent to a + normal assert. + +Unsupported Reboot type + For unsupported reboot type, this function will return with + OPAL_UNSUPPORTED and no reboot will be triggered. + +Debugging +^^^^^^^^^ + +This is **not** ABI and may change or be removed at any time. + +You can change if the software checkstop trigger is used or not by an NVRAM +variable: :: + + nvram -p ibm,skiboot --update-config opal-sw-xstop=enable + nvram -p ibm,skiboot --update-config opal-sw-xstop=disable diff --git a/roms/skiboot/doc/opal-api/opal-check-async-completion-86.rst b/roms/skiboot/doc/opal-api/opal-check-async-completion-86.rst new file mode 100644 index 000000000..1744c6928 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-check-async-completion-86.rst @@ -0,0 +1,35 @@ +.. _OPAL_CHECK_ASYNC_COMPLETION: + +OPAL_CHECK_ASYNC_COMPLETION +=========================== + +:ref:`OPAL_CHECK_ASYNC_COMPLETION` checks if an async OPAL pending message was +completed. (see :ref:`opal-messages`). + +.. code-block:: c + + #define OPAL_CHECK_ASYNC_COMPLETION 86 + + int64_t opal_check_completion(uint64_t *buffer, uint64_t size, uint64_t token); + +Parameters: + +buffer + buffer to copy message into +size + sizeof buffer to copy message into +token + async message token + +Currently unused by Linux, but it is used by FreeBSD. + + +Return values +------------- + +:ref:`OPAL_PARAMETER` + buffer parameter is an invalid pointer (NULL or > top of RAM). +:ref:`OPAL_SUCCESS` + message successfully copied to buffer. +:ref:`OPAL_BUSY` + message is still pending and should be re-checked later. diff --git a/roms/skiboot/doc/opal-api/opal-check-token-80.rst b/roms/skiboot/doc/opal-api/opal-check-token-80.rst new file mode 100644 index 000000000..34eb0a224 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-check-token-80.rst @@ -0,0 +1,31 @@ +.. _OPAL_CHECK_TOKEN: + +OPAL_CHECK_TOKEN +================ + +.. code-block:: c + + #define OPAL_CHECK_TOKEN 80 + + int64_t opal_check_token(uint64_t token); + +This OPAL call allows the host OS to determine if a particular OPAL call is present +on a system. This allows for simple compatibility between OPAL versions and different +OPAL implementations/platforms. + +One parameter is accepted: the OPAL token number. + +``OPAL_CHECK_TOKEN`` will return: :: + + enum OpalCheckTokenStatus { + OPAL_TOKEN_ABSENT = 0, + OPAL_TOKEN_PRESENT = 1 + }; + +indicating the presence/absence of the particular OPAL_CALL. + +``OPAL_CHECK_TOKEN`` is REQUIRED to be implemented by a conformant OPAL implementation. + +For skiboot, only positively ancient internal-to-IBM versions were missing +OPAL_CHECK_TOKEN. In this case, OPAL_PARAMETER would be returned. There is no +reason for a host OS to support this behaviour. diff --git a/roms/skiboot/doc/opal-api/opal-code-update-76-77-78.rst b/roms/skiboot/doc/opal-api/opal-code-update-76-77-78.rst new file mode 100644 index 000000000..5a58d2520 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-code-update-76-77-78.rst @@ -0,0 +1,126 @@ +Code Update on FSP based machine +================================ + +There are three OPAL calls for code update. These are currently only +implemented on FSP based machines. + +.. code-block::c + + #define OPAL_FLASH_VALIDATE 76 + #define OPAL_FLASH_MANAGE 77 + #define OPAL_FLASH_UPDATE 78 + +.. _OPAL_FLASH_VALIDATE: + +OPAL_FLASH_VALIDATE +------------------- + +.. code-block:: c + + #define OPAL_FLASH_VALIDATE 76 + + int64_t fsp_opal_validate_flash(uint64_t buffer, uint32_t *size, uint32_t *result); + + +Validate new image is valid for this platform or not. We do below +validation in OPAL: + + - We do below sys parameters validation to confirm inband + update is allowed. + - Platform is managed by HMC or not?. + - Code update policy (inband code update allowed?). + + - We parse candidate image header (first 4k bytes) to perform + below validations. + - Image magic number. + - Image version to confirm image is valid for this platform. + +Input +^^^^^ +buffer + First 4k bytes of new image + +size + Input buffer size + +Output +^^^^^^ + +buffer + Output result (current and new image version details) + +size + Output buffer size + +result + Token to identify what will happen if update is attempted + See hw/fsp/fsp-codeupdate.h for token values. + +Return value +^^^^^^^^^^^^ +Validation status + +.. _OPAL_FLASH_MANAGE: + +OPAL_FLASH_MANAGE +----------------- + +.. code-block:: c + + #define OPAL_FLASH_MANAGE 77 + + int64_t fsp_opal_manage_flash(uint8_t op); + +Commit/Reject image. + + - We can commit new image (T -> P), if system is running with T side image. + - We can reject T side image, if system is running with P side image. + +**Note:** If a platform is running from a T side image when an update is to be +applied, then the platform may automatically commit the current T side +image to the P side to allow the new image to be updated to the +temporary image area. + +Input +^^^^^ +op + Operation (1 : Commit /0 : Reject) + +Return value + Commit operation status (0 : Success) + +.. _OPAL_FLASH_UPDATE: + +OPAL_FLASH_UPDATE +----------------- + +.. code-block:: c + + #define OPAL_FLASH_UPDATE 78 + + int64_t fsp_opal_update_flash(struct opal_sg_list *list); + +Update new image. It only sets the flag, actual update happens +during system reboot/shutdown. + +Host splits FW image to scatter/gather list and sends it to OPAL. +OPAL parse the image to get indivisual LID and passes it to FSP +via MBOX command. + +FW update flow : + + - if (running side == T) + Swap P & T side + - Start code update + - Delete T side LIDs + - Write LIDs + - Code update complete + - Deep IPL + +Input +^^^^^ +list + Real address of image scatter/gather list of the FW image + +Return value: + Update operation status (0: update requested) diff --git a/roms/skiboot/doc/opal-api/opal-config-cpu-idle-state-99.rst b/roms/skiboot/doc/opal-api/opal-config-cpu-idle-state-99.rst new file mode 100644 index 000000000..787d2cae9 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-config-cpu-idle-state-99.rst @@ -0,0 +1,32 @@ +.. _OPAL_CONFIG_CPU_IDLE_STATE: + +OPAL_CONFIG_CPU_IDLE_STATE +========================== + +.. code-block:: c + + #define OPAL_CONFIG_CPU_IDLE_STATE 99 + + /* + * Setup and cleanup method for fast-sleep workarounds + * state = 1 fast-sleep + * enter = 1 Enter state + * exit = 0 Exit state + */ + + #define OPAL_PM_SLEEP_ENABLED_ER1 0x00080000 /* with workaround */ + + int64_t opal_config_cpu_idle_state(uint64_t state, uint64_t enter); + +If the `OPAL_PM_SLEEP_ENABLED_ER1` bit is set on a stop state, then this OPAL +call needs to be made upon entry and exit of stop state. +This is currently needed for the `fastsleep_` idle state, present on POWER8 +systems. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Applied workaround +:ref:`OPAL_PARAMETER` + Invalid state or enter/exit. diff --git a/roms/skiboot/doc/opal-api/opal-console-read-write-1-2.rst b/roms/skiboot/doc/opal-api/opal-console-read-write-1-2.rst new file mode 100644 index 000000000..ef71a6aa7 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-console-read-write-1-2.rst @@ -0,0 +1,104 @@ +OPAL Console calls +================== + +There are four OPAL calls relating to the OPAL console: + ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| Name | API Token ID | Introduced | Required | Notes | +| | | | as of | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_CONSOLE_WRITE` | 1 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_CONSOLE_READ` | 2 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_CONSOLE_WRITE_BUFFER_SPACE` | 25 | v1.0 (Initial Release) | POWER8 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ +| :ref:`OPAL_CONSOLE_FLUSH` | 117 | :ref:`skiboot-5.1.13` | POWER9 | | ++---------------------------------------------+--------------+------------------------+----------+-----------------+ + +The OPAL console calls can support multiple consoles. Each console MUST +be represented in the device tree. + +A conforming implementation SHOULD have at least one console. It is valid +for it to simply be an in-memory buffer and only support writing. + +[TODO: details on device tree specs for console] + +.. _OPAL_CONSOLE_WRITE: + +OPAL_CONSOLE_WRITE +------------------ + +Parameters: :: + + int64_t term_number + int64_t *length, + const uint8_t *buffer + +Returns: + + - :ref:`OPAL_SUCCESS` + - :ref:`OPAL_PARAMETER` on invalid term_number + - :ref:`OPAL_CLOSED` if console device closed + - :ref:`OPAL_BUSY_EVENT` if unable to write any of buffer + +``term_number`` is the terminal number as represented in the device tree. +``length`` is a pointer to the length of buffer. + +A conforming implementation SHOULD try to NOT do partial writes, although +partial writes and not writing anything are valid. + +.. _OPAL_CONSOLE_WRITE_BUFFER_SPACE: + +OPAL_CONSOLE_WRITE_BUFFER_SPACE +------------------------------- + +Parameters: :: + + int64_t term_number + int64_t *length + +Returns: + + - :ref:`OPAL_SUCCESS` + - :ref:`OPAL_PARAMETER` on invalid term_number + +Returns the available buffer length for OPAL_CONSOLE_WRITE in ``length``. +This call can be used to help work out if there is sufficient buffer +space to write your full message to the console with OPAL_CONSOLE_WRITE. + +.. _OPAL_CONSOLE_READ: + +OPAL_CONSOLE_READ +----------------- + +Parameters: :: + + int64_t term_number + int64_t *length + uint8_t *buffer + +Returns: + + - :ref:`OPAL_SUCCESS` + - :ref:`OPAL_PARAMETER` on invalid term_number + - :ref:`OPAL_CLOSED` + +Use :ref:`OPAL_POLL_EVENTS` for how to determine + +.. _OPAL_CONSOLE_FLUSH: + +OPAL_CONSOLE_FLUSH +------------------ + +Parameters: :: + + int64_t term_number + +Returns: + + - :ref:`OPAL_SUCCESS` + - :ref:`OPAL_UNSUPPORTED` if the console does not implement a flush call + - :ref:`OPAL_PARAMETER` on invalid term_number + - :ref:`OPAL_PARTIAL` if more to flush, call again + - :ref:`OPAL_BUSY` if nothing was flushed this call diff --git a/roms/skiboot/doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst b/roms/skiboot/doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst new file mode 100644 index 000000000..04dc8a044 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst @@ -0,0 +1,293 @@ +.. _opal-dumps: + +========== +OPAL Dumps +========== + +.. code-block:: c + + #define OPAL_REGISTER_DUMP_REGION 101 + #define OPAL_UNREGISTER_DUMP_REGION 102 + + int64_t opal_register_dump_region(uint32_t id, uint64_t addr, uint64_t size); + int64_t opal_unregister_dump_region(uint32_t id); + +In the event of crashes, some service processors and firmware support gathering +a limited amount of memory from a limited number of memory regions to save into +a debug dump that can be useful for firmware and operating system developers +in diagnosing problems. Typically, firmware and kernel log buffers are useful to +save in a dump. + +An OS can register a memory region with :ref:`OPAL_REGISTER_DUMP_REGION` and should, +when the region is no longer valid (e.g. when kexec()ing), it should unregister the +region with :ref:`OPAL_UNREGISTER_DUMP_REGION`. + +An OS will be made aware of a dump being available through :ref:`OPAL_EVENT_DUMP_AVAIL` +being set from a :ref:`OPAL_POLL_EVENTS` call. + +Retreiving dumps from a service processor can also be performed using the +:ref:`OPAL_DUMP_INFO`, :ref:`OPAL_DUMP_INFO2`, :ref:`OPAL_DUMP_READ`, +and :ref:`OPAL_DUMP_RESEND` calls. Dumps are identified by a ``uint32_t``, and +once a dump is acknowledged, this ID can be re-used. + +Dumps can also be initiated by OPAL through the :ref:`OPAL_DUMP_INIT` call, which +will request that the service processor performs the requested type of dump. + +A call to :ref:`OPAL_DUMP_ACK` indicates to the service processor that we have +retreived/acknowledged the dump and the service processor can free up the storage +used by it. + +.. code-block:: c + + #define OPAL_DUMP_INIT 81 + #define OPAL_DUMP_INFO 82 + #define OPAL_DUMP_READ 83 + #define OPAL_DUMP_ACK 84 + #define OPAL_DUMP_RESEND 91 + #define OPAL_DUMP_INFO2 94 + + int64_t opal_dump_init(uint8_t dump_type); + int64_t opal_dump_info(uint32_t *dump_id, uint32_t *dump_size); + int64_t opal_dump_read(uint32_t dump_id, struct opal_sg_list *list); + int64_t opal_dump_ack(uint32_t dump_id); + int64_t opal_dump_resend_notification(void); + int64_t opal_dump_info2(uint32_t *dump_id, uint32_t *dump_size, uint32_t *dump_type); + + +.. _OPAL_REGISTER_DUMP_REGION: + +OPAL_REGISTER_DUMP_REGION +========================= + +.. code-block:: c + + #define OPAL_REGISTER_DUMP_REGION 101 + + int64_t opal_register_dump_region(uint32_t id, uint64_t addr, uint64_t size); + +This call is used to register regions of memory for a service processor to capture +when the host crashes. + +e.g. if an assert is hit in OPAL, a service processor will copy the region of +memory into some kind of crash dump for further analysis. + +This is an OPTIONAL feature that may be unsupported, the host OS should use an +:ref:`OPAL_CHECK_TOKEN` call to find out if :ref:`OPAL_REGISTER_DUMP_REGION` is supported. + +:ref:`OPAL_REGISTER_DUMP_REGION` accepts 3 parameters: + +- region ID +- address +- length + +There is a range of region IDs that can be used by the host OS. A host OS should +start from OPAL_DUMP_REGION_HOST_END and work down if it wants to add a not well +defined region to dump. Currently the only well defined region is for the host +OS log buffer (e.g. dmesg on linux). :: + + /* + * Dump region ID range usable by the OS + */ + #define OPAL_DUMP_REGION_HOST_START 0x80 + #define OPAL_DUMP_REGION_LOG_BUF 0x80 + #define OPAL_DUMP_REGION_HOST_END 0xFF + +:ref:`OPAL_REGISTER_DUMP_REGION` will return :ref:`OPAL_UNSUPPORTED` if the call is present but +the system doesn't support registering regions to be dumped. + +In the event of being passed an invalid region ID, :ref:`OPAL_REGISTER_DUMP_REGION` will +return :ref:`OPAL_PARAMETER`. + +Systems likely have a limit as to how many regions they can support being dumped. If +this limit is reached, :ref:`OPAL_REGISTER_DUMP_REGION` will return :ref:`OPAL_INTERNAL_ERROR`. + +BUGS +---- +Some skiboot versions incorrectly returned :ref:`OPAL_SUCCESS` in the case of +:ref:`OPAL_REGISTER_DUMP_REGION` being supported on a platform (so the call was present) +but the call being unsupported for some reason (e.g. on an IBM POWER7 machine). + +See also: :ref:`OPAL_UNREGISTER_DUMP_REGION` + +.. _OPAL_UNREGISTER_DUMP_REGION: + +OPAL_UNREGISTER_DUMP_REGION +=========================== + +.. code-block:: c + + #define OPAL_UNREGISTER_DUMP_REGION 102 + + int64_t opal_unregister_dump_region(uint32_t id); + +While :ref:`OPAL_REGISTER_DUMP_REGION` registers a region, :ref:`OPAL_UNREGISTER_DUMP_REGION` +will unregister a region by region ID. + +:ref:`OPAL_UNREGISTER_DUMP_REGION` takes one argument: the region ID. + +A host OS should check :ref:`OPAL_UNREGISTER_DUMP_REGION` is supported through a call to +:ref:`OPAL_CHECK_TOKEN`. + +If :ref:`OPAL_UNREGISTER_DUMP_REGION` is called on a system where the call is present but +unsupported, it will return :ref:`OPAL_UNSUPPORTED`. + +BUGS +---- +Some skiboot versions incorrectly returned :ref:`OPAL_SUCCESS` in the case of +:ref:`OPAL_UNREGISTER_DUMP_REGION` being supported on a platform (so the call was present) +but the call being unsupported for some reason (e.g. on an IBM POWER7 machine). + +.. _OPAL_DUMP_INIT: + +OPAL_DUMP_INIT +============== + +.. code-block:: c + + #define OPAL_DUMP_INIT 81 + + #define DUMP_TYPE_FSP 0x01 + #define DUMP_TYPE_SYS 0x02 + #define DUMP_TYPE_SMA 0x03 + + int64_t opal_dump_init(uint8_t dump_type); + +Ask the service processor to initiate a dump. Currently, only ``DUMP_TYPE_FSP`` +is supported. + +Currently only implemented on FSP based systems. Use :ref:`OPAL_CHECK_TOKEN` to +ensure the call is valid. + +Returns +------- +:ref:`OPAL_SUCCESS` + Dump initiated +:ref:`OPAL_PARAMETER` + Unsupported dump type. Currently only ``DUMP_TYPE_FSP`` is supported and + only on FSP based platforms. +:ref:`OPAL_INTERNAL_ERROR` + Failed to ask service processor to initiated dump. + +.. _OPAL_DUMP_INFO: + +OPAL_DUMP_INFO +============== + +.. code-block:: c + + #define OPAL_DUMP_INFO 82 + + int64_t opal_dump_info(uint32_t *dump_id, uint32_t *dump_size); + +Obsolete, use :ref:`OPAL_DUMP_INFO2` instead. + +No upstream Linux code ever used :ref:`OPAL_DUMP_INFO`, although early PowerKVM +trees did. :ref:`OPAL_DUMP_INFO` is implemented as a wrapper around +:ref:`OPAL_DUMP_INFO2`. + +.. _OPAL_DUMP_READ: + +OPAL_DUMP_READ +============== + +.. code-block:: c + + #define OPAL_DUMP_READ 83 + + int64_t opal_dump_read(uint32_t dump_id, struct opal_sg_list *list); + +Read ``dump_id`` dump from the service processor into memory. + + +Returns +------- +:ref:`OPAL_INTERNAL_ERROR` + Invalid Dump ID or internal error. +:ref:`OPAL_PARAMETER` + Insuffcient space to store dump. +:ref:`OPAL_BUSY_EVENT` + Fetching dump, call :ref:`OPAL_POLL_EVENTS` to crank the state machine, + and call :ref:`OPAL_DUMP_READ` again until neither :ref:`OPAL_BUSY_EVENT` + nor :ref:`OPAL_BUSY` are returned. +:ref:`OPAL_PARTIAL` + Only part of the dump was read. +:ref:`OPAL_SUCCESS` + Dump successfully read. + +.. _OPAL_DUMP_ACK: + +OPAL_DUMP_ACK +============= + +.. code-block:: c + + #define OPAL_DUMP_ACK 84 + + int64_t opal_dump_ack(uint32_t dump_id); + +Acknowledge the dump to the service processor. This means the service processor +can re-claim the storage space used by the dump. Effectively, this is an +``unlink`` style operation. + +Returns +------- +:ref:`OPAL_SUCCESS` + Dump successfully acknowledged. +:ref:`OPAL_INTERNAL_ERROR` + Failed to acknowledge the dump, e.g. could not communicate with service + processor. +:ref:`OPAL_PARAMETER` + Invalid dump ID. + + +.. _OPAL_DUMP_RESEND: + +OPAL_DUMP_RESEND +================ + +.. code-block:: c + + #define OPAL_DUMP_RESEND 91 + + int64_t opal_dump_resend_notification(void); + +Resend notification to the OS if there is a dump available. This will +cause OPAL to check if a dump is available and set the +:ref:`OPAL_EVENT_DUMP_AVAIL` bit in the next :ref:`OPAL_POLL_EVENTS` call. + +Returns +------- +:ref:`OPAL_SUCCESS` + Successfully reset :ref:`OPAL_EVENT_DUMP_AVAIL` bit. + +In future, this may return other standard OPAL error codes. + +.. _OPAL_DUMP_INFO2: + +OPAL_DUMP_INFO2 +=============== + +.. code-block:: c + + #define OPAL_DUMP_INFO2 94 + + #define DUMP_TYPE_FSP 0x01 + #define DUMP_TYPE_SYS 0x02 + #define DUMP_TYPE_SMA 0x03 + + int64_t opal_dump_info2(uint32_t *dump_id, uint32_t *dump_size, uint32_t *dump_type); + +Retreives information about a dump, notably it's ``dump_id``, size, and type. +Call this after the :ref:`OPAL_EVENT_DUMP_AVAIL` bit is set from a +:ref:`OPAL_POLL_EVENTS` call. It will retreive the information on the *next* +dump to be retreived and/or ACKed, even though there may be more than one dump +available for retreiving. + +This call replaces :ref:`OPAL_DUMP_INFO`. + +Returns +------- +:ref:`OPAL_SUCCESS` + Information retreived. +:ref:`OPAL_INTERNAL_ERROR` + No dump available or internal error. diff --git a/roms/skiboot/doc/opal-api/opal-elog-71-72-73-74-75.rst b/roms/skiboot/doc/opal-api/opal-elog-71-72-73-74-75.rst new file mode 100644 index 000000000..76cc967d5 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-elog-71-72-73-74-75.rst @@ -0,0 +1,125 @@ +.. _OPAL_ELOG: + +OPAL_ELOG: Error logging +======================== + +OPAL provides an abstraction to platform specific methods of storing and +retrieving error logs. Some service processors may be able to store information +in the Platform Error Log (PEL) format. These may be generated at runtime +by the service processor or OPAL in reaction to certain events. For example, +an IPL failure could be recorded in an error log, as could the reason and +details of an unexpected shut-down/reboot (e.g. hard thermal limits, check-stop). + +There are five OPAL calls from host to OPAL on error log: + +.. code-block:: c + + #define OPAL_ELOG_READ 71 + #define OPAL_ELOG_WRITE 72 + #define OPAL_ELOG_ACK 73 + #define OPAL_ELOG_RESEND 74 + #define OPAL_ELOG_SIZE 75 + +Note: :ref:`OPAL_ELOG_WRITE` (72) Unused for now, might be supported in the +future. + +Not all platforms support these calls, so it's important for a host Operating +System to use the :ref:`OPAL_CHECK_TOKEN` call first. If :ref:`OPAL_ELOG_READ`, +:ref:`OPAL_ELOG_ACK`, :ref:`OPAL_ELOG_RESEND`, or :ref:`OPAL_ELOG_SIZE` is present, +then the rest of that group is also present. The presence of :ref:`OPAL_ELOG_WRITE` +must be checked separately. + +**TODO**: we need a good explanation of the notification mechanism and in +what order and *when* to call each of the OPAL APIs. + +.. _OPAL_ELOG_READ: + +OPAL_ELOG_READ +-------------- + +The :ref:`OPAL_ELOG_READ` call will copy the error log identified by ``id`` into +the ``buffer`` of size ``size``. + +``OPAL_ELOG_READ`` accepts 3 parameters: :: + + uint64_t *elog_buffer + uint64_t elog_size + uint64_t elog_id + +Returns: + +:ref:`OPAL_WRONG_STATE` + When there are no error logs to read, or ``OPAL_ELOG`` calls are done in the + wrong order. + +:ref:`OPAL_PARAMETER` + The ``id`` does not match the log id that is available. + +:ref:`OPAL_SUCCESS` + Error log is copied to ``buffer``. + +Other generic OPAL error codes may also be returned and should be treated +like :ref:`OPAL_INTERNAL_ERROR`. + +.. _OPAL_ELOG_ACK: + +OPAL_ELOG_ACK +------------- + +Acknowledging (ACKing) an error log tells OPAL and the service processor that +the host operating system has dealt with the error log successfully. This allows +OPAL and the service processor to delete the error log from their +memory/storage. + +:ref:`OPAL_ELOG_ACK` accepts 1 parameter: :: + + uint64_t ack_id + +Returns: + +:ref:`OPAL_INTERNAL_ERROR` + OPAL failed to send acknowledgement to the error log creator. +:ref:`OPAL_SUCCESS` + Success! + +Other generic OPAL error codes may also be returned, and should be treated +like :ref:`OPAL_INTERNAL_ERROR`. + +.. _OPAL_ELOG_RESEND: + +OPAL_ELOG_RESEND +---------------- + +The :ref:`OPAL_ELOG_RESEND` call will cause OPAL to resend notification to the +host operating system of all outstanding error logs. This is commonly used +(although doesn't have to be) in a kexec scenario. + +The call registered with this token accepts no parameter and returns type is +void. + +.. _OPAL_ELOG_SIZE: + +OPAL_ELOG_SIZE +-------------- + +The :ref:`OPAL_ELOG_SIZE` call retrieves information about an error log. + +Here, ``type`` specifies error log format. Supported types are : :: + + 0 -> Platform Error Log + +:ref:`OPAL_ELOG_SIZE` accepts 3 parameters: :: + + uint64_t *elog_id + uint64_t *elog_size + uint64_t *elog_type + +Returns: + +:ref:`OPAL_WRONG_STATE` + There is no error log to fetch information about. + +:ref:`OPAL_SUCCESS` + Success. + +Other general OPAL errors may be returned. diff --git a/roms/skiboot/doc/opal-api/opal-flash-110-111-112.rst b/roms/skiboot/doc/opal-api/opal-flash-110-111-112.rst new file mode 100644 index 000000000..cee9bcc7d --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-flash-110-111-112.rst @@ -0,0 +1,90 @@ +OPAL Flash calls +================ + +There are three OPAL calls for interacting with flash devices: + +.. code-block:: c + + #define OPAL_FLASH_READ 110 + #define OPAL_FLASH_WRITE 111 + #define OPAL_FLASH_ERASE 112 + +Multiple flash devices are supported by OPAL - each of these calls takes an id +parameter, which must match an ID found in the corresponding ``ibm,opal/flash@n`` +device tree node. See :ref:`device-tree/ibm,opal/flash` for details of +the device tree bindings. + +All operations on the flash device must be aligned to the block size of the +flash. This applies to both offset and size arguments. + +This interface is asynchronous; all calls require a 'token' argument. On +success, the calls will return :ref:`OPAL_ASYNC_COMPLETION`, and an +opal_async_completion message will be sent (with the appropriate token +argument) when the operation completes. + +.. note:: These calls can have higher than normal latency, spending many + **milliseconds** inside OPAL. This is due to the OPAL_FLASH_* calls + typically being backed by flash on the other side of the LPC bus, + which has a maximum transfer rate of 5MB/sec, or to/from flash attached + to the ast2400/ast2500 (the typical setup for OpenPOWER systems) of + only 1.75MB/sec. + +All calls share the same return values: + +:ref:`OPAL_ASYNC_COMPLETION` + operation started, an async completion will be triggered with the ``token`` argument +:ref:`OPAL_PARAMETER` + invalid flash id +:ref:`OPAL_PARAMETER` + invalid size or offset (alignment, or access beyond end of device) +:ref:`OPAL_BUSY` + flash in use +:ref:`OPAL_HARDWARE` + error accessing flash device + +.. _OPAL_FLASH_READ: + +OPAL_FLASH_READ +--------------- + +.. code-block:: c + + #define OPAL_FLASH_READ 110 + + int64_t opal_flash_read(uint64_t id, uint64_t offset, uint64_t buf, + uint64_t size, uint64_t token); + +Reads from the specified flash id, at the specified offset, into the buffer. +Will trigger an async completion with token when completed. + +.. _OPAL_FLASH_ERASE: + +OPAL_FLASH_ERASE +---------------- + +.. code-block:: c + + #define OPAL_FLASH_ERASE 112 + + int64_t opal_flash_erase(uint64_t id, uint64_t offset, uint64_t size, + uint64_t token); + +Erases the specified flash id, at the specified offset and size. Will trigger +an async completion with token when completed. + +.. _OPAL_FLASH_WRITE: + +OPAL_FLASH_WRITE +---------------- + +.. code-block:: c + + #define OPAL_FLASH_WRITE 111 + + int64_t opal_flash_write(uint64_t id, uint64_t offset, uint64_t buf, + uint64_t size, uint64_t token); + +Writes buffer to the specified flash id, at the specified offset and size. The +flash must be erased before being written. Will trigger an async completion with +token when completed. + diff --git a/roms/skiboot/doc/opal-api/opal-get-device-tree-118.rst b/roms/skiboot/doc/opal-api/opal-get-device-tree-118.rst new file mode 100644 index 000000000..df00205af --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-get-device-tree-118.rst @@ -0,0 +1,41 @@ +.. _OPAL_GET_DEVICE_TREE: + +OPAL_GET_DEVICE_TREE +==================== + +.. code-block:: c + + #define OPAL_GET_DEVICE_TREE 118 + + int64_t opal_get_device_tree(uint32_t phandle, uint64_t buf, uint64_t len); + +Get device sub-tree. + +``uint32_t phandle`` + root device node phandle of the device sub-tree +``uint64_t buf`` + FDT blob buffer or NULL +``uint64_t len`` + length of the FDT blob buffer + + +Retrieve device sub-tree. The root node's phandle is identified by @phandle. +The typical use is for the kernel to update its device tree following a change +in hardware (e.g. PCI hotplug). + +Return Codes +^^^^^^^^^^^^ + +FDT blob size + returned FDT blob buffer size when ``buf`` is NULL + +:ref:`OPAL_SUCCESS` + FDT blob is created successfully +:ref:`OPAL_PARAMETER` + invalid argument @phandle or @len +:ref:`OPAL_INTERNAL_ERROR` + failure creating FDT blob when calculating its size +:ref:`OPAL_NO_MEM` + not enough room in buffer for device sub-tree +:ref:`OPAL_EMPTY` + failure creating FDT blob diff --git a/roms/skiboot/doc/opal-api/opal-get-epow-status-56.rst b/roms/skiboot/doc/opal-api/opal-get-epow-status-56.rst new file mode 100644 index 000000000..7de7d12c4 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-get-epow-status-56.rst @@ -0,0 +1,66 @@ +.. _OPAL_GET_EPOW_STATUS: + +OPAL_GET_EPOW_STATUS +==================== + +.. code-block:: c + + #define OPAL_GET_EPOW_STATUS 56 + + enum OpalEpowStatus { + OPAL_EPOW_NONE = 0, + OPAL_EPOW_UPS = 1, + OPAL_EPOW_OVER_AMBIENT_TEMP = 2, + OPAL_EPOW_OVER_INTERNAL_TEMP = 3 + }; + + /* System EPOW type */ + enum OpalSysEpow { + OPAL_SYSEPOW_POWER = 0, /* Power EPOW */ + OPAL_SYSEPOW_TEMP = 1, /* Temperature EPOW */ + OPAL_SYSEPOW_COOLING = 2, /* Cooling EPOW */ + OPAL_SYSEPOW_MAX = 3, /* Max EPOW categories */ + }; + + /* Power EPOW */ + enum OpalSysPower { + OPAL_SYSPOWER_UPS = 0x0001, /* System on UPS power */ + OPAL_SYSPOWER_CHNG = 0x0002, /* System power configuration change */ + OPAL_SYSPOWER_FAIL = 0x0004, /* System impending power failure */ + OPAL_SYSPOWER_INCL = 0x0008, /* System incomplete power */ + }; + + /* Temperature EPOW */ + enum OpalSysTemp { + OPAL_SYSTEMP_AMB = 0x0001, /* System over ambient temperature */ + OPAL_SYSTEMP_INT = 0x0002, /* System over internal temperature */ + OPAL_SYSTEMP_HMD = 0x0004, /* System over ambient humidity */ + }; + + /* Cooling EPOW */ + enum OpalSysCooling { + OPAL_SYSCOOL_INSF = 0x0001, /* System insufficient cooling */ + }; + + int64_t opal_get_epow_status(int16_t *out_epow, int16_t *length); + +The :ref:`OPAL_GET_EPOW_STATUS` call gets the Environmental and Power Warnings +state from OPAL. This can allow an OS to take action based on information from +firmware / sensors. + +On receipt of an :ref:`OPAL_MSG_EPOW` message, the OS can query the status +using the :ref:`OPAL_GET_EPOW_STATUS` call. The OS allocates an array for the +status bits, and passes in the length of this array. OPAL will return the +maximum length it filled out. Thus, new classes can be added and backwards +compatibility is maintained. + +At time of writing, this call is only implemented on FSP based systems. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Successfully retreived status. Note, success is returned even if only + able to retreive a subset of the EPOW classes. + +Other return codes may be returned in the future. diff --git a/roms/skiboot/doc/opal-api/opal-get-msg-85.rst b/roms/skiboot/doc/opal-api/opal-get-msg-85.rst new file mode 100644 index 000000000..a7afc686c --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-get-msg-85.rst @@ -0,0 +1,47 @@ +.. _OPAL_GET_MSG: + +OPAL_GET_MSG +============ + +.. code-block:: c + + #define OPAL_GET_MSG 85 + + int64_t opal_get_msg(uint64_t *buffer, uint64_t size); + +:ref:`OPAL_GET_MSG` will get the next pending OPAL Message (see :ref:`opal-messages`). + +The maximum size of an opal message is specified in the device tree passed +to the host OS: :: + + ibm,opal { + opal-msg-size = <0x48>; + } + +It is ALWAYS at least 72 bytes. In the future, OPAL may have messages larger +than 72 bytes. Naturally, a HOST OS will only be able to interpret these +if it correctly uses opal-msg-size. Any OPAL message > 72 bytes, a host OS +may safely ignore. + +A host OS *SHOULD* always supply a buffer to OPAL_GET_MSG of either 72 +bytes or opal-msg-size. It MUST NOT supply a buffer of < 72 bytes. + + +Return values +------------- + +:ref:`OPAL_RESOURCE` + no available message. +:ref:`OPAL_PARAMETER` + buffer is NULL or size is < 72 bytes. + If buffer size < 72 bytes, the message will NOT be discarded by OPAL. +:ref:`OPAL_PARTIAL` + If pending opal message is greater than supplied buffer. + In this case the message is *DISCARDED* by OPAL. + This is to keep compatibility with host Operating Systems + with a hard coded opal-msg-size of 72 bytes. + **NOT CURRENTLY IMPLEMENTED**. Specified so that host OS can + prepare for the possible future with either a sensible + error message or by gracefully ignoring such OPAL messages. +:ref:`OPAL_SUCCESS` + message successfully copied to buffer. diff --git a/roms/skiboot/doc/opal-api/opal-get-msi-39-40.rst b/roms/skiboot/doc/opal-api/opal-get-msi-39-40.rst new file mode 100644 index 000000000..86741ce22 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-get-msi-39-40.rst @@ -0,0 +1,90 @@ +=================================== +OPAL_GET_MSI_32 and OPAL_GET_MSI_64 +=================================== + +.. code-block:: c + + #define OPAL_GET_MSI_32 39 + #define OPAL_GET_MSI_64 40 + + int64_t opal_get_msi_32(uint64_t phb_id, uint32_t mve_number, + uint32_t xive_num, uint8_t msi_range, + uint32_t *msi_address, uint32_t *message_data); + + int64_t opal_get_msi_64(uint64_t phb_id, uint32_t mve_number, + uint32_t xive_num, uint8_t msi_range, + uint64_t *msi_address, uint32_t *message_data); + +.. _OPAL_GET_MSI_32: + +OPAL_GET_MSI_32 +=============== + +.. code-block:: c + + #define OPAL_GET_MSI_32 39 + + int64_t opal_get_msi_32(uint64_t phb_id, uint32_t mve_number, + uint32_t xive_num, uint8_t msi_range, + uint32_t *msi_address, uint32_t *message_data); + +See :ref:`OPAL_GET_MSI_64`. + +.. _OPAL_GET_MSI_64: + +OPAL_GET_MSI_64 +=============== + +.. code-block:: c + + #define OPAL_GET_MSI_64 40 + + int64_t opal_get_msi_64(uint64_t phb_id, uint32_t mve_number, + uint32_t xive_num, uint8_t msi_range, + uint64_t *msi_address, uint32_t *message_data); + + +**WARNING:** the 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. + +OPAL PHBs encode MVE and XIVE specifiers in MSI DMA and message data values. +The host calls these functions to determine the PHB MSI DMA address and message +data to program into a PE PCIE function for a particular MVE and XIVE. The +msi_address parameter returns the MSI DMA address and the msi_data parameter +returns the MSI DMA message data value the PE uses to signal that interrupt. + +``phb_id`` + The ``phb_id`` parameter is the value from the PHB node ``ibm,opal-phbid`` + property. + +``mve_number`` + The ``mve_number`` is the index of an MVE used to authorize this PE to this + MSI. For ``ibm,opal-ioda2`` PHBs, the MVE number argument is ignored. + +``xive_number`` + The ``xive_number`` is the index of an XIVE that corresponds to a particular + DMA address and message data value this PE will signal as an MSI ro MSI-X. + +``msi_range`` + The msi_range parameter specifies the number of MSIs associated with the + in put MVE and XIVE, primarily for MSI-conventional Multiple Message + Enable > 1 MSI. MSI requires consecutive MSIs per MSI address, and each + MSI DMA address must be unique for any given consecutive power of 2 set + of 32 message data values,. which in turn select particular PHB XIVEs. + This value must be a power of 2 value in the range of 0 to 32. OPAL + returns :ref:`OPAL_PARAMETER` for values outside of this range. + +For MSI conventional, the MSI address and message data returned apply to a +power of 2 sequential set of XIVRs starting from the xive_number for the +power of 2 msi_range input argument. The message data returned represents the +power of 2 aligned starting message data value of the first interrupt number +in that sequential range. Valid msi_range input values are from 1 to 32. +Non-power of 2 values result in a return code of :ref:`OPAL_PARAMETER`. + +An msi_range value of 0 or 1 signifies that OPAL should return the message +data and message address for exactly one MSI specified by the input XIVE +number. For MSI conventional, the host should specify either a value of 0 or 1, +for an MSI Capability MME value of 1 MSI. For MSI-X XIVRs, the host should +specify a value of '1' for the msi_range argument and call this function for +each MSI-X uniquely. diff --git a/roms/skiboot/doc/opal-api/opal-get-xive-20.rst b/roms/skiboot/doc/opal-api/opal-get-xive-20.rst new file mode 100644 index 000000000..cdca1fcb6 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-get-xive-20.rst @@ -0,0 +1,28 @@ +.. _OPAL_GET_XIVE: + +OPAL_GET_XIVE +============= + +.. code-block:: c + + #define OPAL_GET_XIVE 20 + + int64_t opal_get_xive(uint32_t isn, uint16_t *server, uint8_t *priority); + +The host calls this function to return the configuration of an +interrupt source. See :ref:`OPAL_SET_XIVE` for details. + +Parameters +---------- + +``isn`` + The ``isn`` is the global interrupt number being queried + +``server_number`` + the ``server_number`` returns the mangled server (processor) + that is set to receive that interrupt. + +``priority`` + the ``priority`` returns the current interrupt priority setting + for that interrupt. + diff --git a/roms/skiboot/doc/opal-api/opal-handle-hmi-98-166.rst b/roms/skiboot/doc/opal-api/opal-handle-hmi-98-166.rst new file mode 100644 index 000000000..5b75144dc --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-handle-hmi-98-166.rst @@ -0,0 +1,155 @@ +Hypervisor Maintenance Interrupt (HMI) +====================================== + +Hypervisor Maintenance Interrupt usually reports error related to processor +recovery/checkstop, NX/NPU checkstop and Timer facility. Hypervisor then +takes this opportunity to analyze and recover from some of these errors. +Hypervisor takes assistance from OPAL layer to handle and recover from HMI. +After handling HMI, OPAL layer sends the summary of error report and status +of recovery action using HMI event. See ref:`opal-messages` for HMI +event structure under :ref:`OPAL_MSG_HMI_EVT` section. + +HMI is thread specific. The reason for HMI is available in a per thread +Hypervisor Maintenance Exception Register (HMER). A Hypervisor Maintenance +Exception Enable Register (HMEER) is per core. Bits from the HMER need to +be enabled by the corresponding bits in the HMEER in order to cause an HMI. + +Several interrupt reasons are routed in parallel to each of the thread +specific copies. Each thread can only clear bits in its own HMER. OPAL +handler from each thread clears the respective bit from HMER register +after handling the error. + +List of errors that causes HMI +============================== + + - CPU Errors + + - Processor Core checkstop + - Processor retry recovery + - NX/NPU/CAPP checkstop. + + - Timer facility Errors + + - ChipTOD Errors + + - ChipTOD sync check and parity errors + - ChipTOD configuration register parity errors + - ChiTOD topology failover + + - Timebase (TB) errors + + - TB parity/residue error + - TFMR parity and firmware control error + - DEC/HDEC/PURR/SPURR parity errors + +HMI handling +============ + +A core/NX/NPU checkstops are reported as malfunction alert (HMER bit 0). +OPAL handler scans through Fault Isolation Register (FIR) for each +core/nx/npu to detect the exact reason for checkstop and reports it back +to the host alongwith the disposition. + +A processor recovery is reported through HMER bits 2, 3 and 11. These are +just an informational messages and no extra recovery is required. + +Timer facility errors are reported through HMER bit 4. These are all +recoverable errors. The exact reason for the errors are stored in +Timer Facility Management Register (TFMR). Some of the Timer facility +errors affects TB and some of them affects TOD. TOD is a per chip +Time-Of-Day logic that holds the actual time value of the chip and +communicates with every TOD in the system to achieve synchronized +timer value within a system. TB is per core register (64-bit) derives its +value from ChipTOD at startup and then it gets periodically incremented +by STEP signal provided by the TOD. In a multi-socket system TODs are +always configured as master/backup TOD under primary/secondary +topology configuration respectively. + +TB error generates HMI on all threads of the affected core. TB errors +except DEC/HDEC/PURR/SPURR parity errors, causes TB to stop running +making it invalid. As part of TB recovery, OPAL hmi handler synchronizes +with all threads, clears the TB errors and then re-sync the TB with TOD +value putting it back in running state. + +TOD errors generates HMI on every core/thread of affected chip. The reason +for TOD errors are stored in TOD ERROR register (0x40030). As part of the +recovery OPAL hmi handler clears the TOD error and then requests new TOD +value from another running chipTOD in the system. Sometimes, if a primary +chipTOD is in error, it may need a TOD topology switch to recover from +error. A TOD topology switch basically makes a backup as new active master. + +.. _OPAL_HANDLE_HMI: + +OPAL_HANDLE_HMI +=============== + +.. code-block:: c + + #define OPAL_HANDLE_HMI 98 + + int64_t opal_handle_hmi(void); + + +Superseded by :ref:`OPAL_HANDLE_HMI2`, meaning that :ref:`OPAL_HANDLE_HMI` +should only be called if :ref:`OPAL_HANDLE_HMI2` is not available. + +Since :ref:`OPAL_HANDLE_HMI2` has been available since the start of POWER9 +systems being supported, if you only target POWER9 and above, you can +assume the presence of :ref:`OPAL_HANDLE_HMI2`. + +.. _OPAL_HANDLE_HMI2: + +OPAL_HANDLE_HMI2 +================ + +.. code-block:: c + + #define OPAL_HANDLE_HMI2 166 + + int64_t opal_handle_hmi2(__be64 *out_flags); + +When OS host gets an Hypervisor Maintenance Interrupt (HMI), it must call +:ref:`OPAL_HANDLE_HMI` or :ref:`OPAL_HANDLE_HMI2`. The :ref:`OPAL_HANDLE_HMI` +is an old interface. :ref:`OPAL_HANDLE_HMI2` is newly introduced opal call +that returns direct info to the OS. It returns a 64-bit flag mask currently +set to provide info about which timer facilities were lost, and whether an +event was generated. This information will help OS to take respective +actions. + +In case where opal hmi handler is unable to recover from TOD or TB errors, +it would flag ``OPAL_HMI_FLAGS_TOD_TB_FAIL`` to indicate OS that TB is +dead. This information then can be used by OS to make sure that the +functions relying on TB value (e.g. udelay()) are aware of TB not ticking. +This will avoid OS getting stuck or hang during its way to panic path. + + +Parameters +^^^^^^^^^^ + +.. code-block:: c + + __be64 *out_flags; + +Returns the 64-bit flag mask that provides info about which timer facilities +were lost, and whether an event was generated. + +.. code-block:: c + + /* OPAL_HANDLE_HMI2 out_flags */ + enum { + OPAL_HMI_FLAGS_TB_RESYNC = (1ull << 0), /* Timebase has been resynced */ + OPAL_HMI_FLAGS_DEC_LOST = (1ull << 1), /* DEC lost, needs to be reprogrammed */ + OPAL_HMI_FLAGS_HDEC_LOST = (1ull << 2), /* HDEC lost, needs to be reprogrammed */ + OPAL_HMI_FLAGS_TOD_TB_FAIL = (1ull << 3), /* TOD/TB recovery failed. */ + OPAL_HMI_FLAGS_NEW_EVENT = (1ull << 63), /* An event has been created */ + }; + +.. _OPAL_HMI_FLAGS_TOD_TB_FAIL: + +OPAL_HMI_FLAGS_TOD_TB_FAIL + The Time of Day (TOD) / Timebase facility has failed. This is probably fatal + for the OS, and requires the OS to be very careful to not call any function + that may rely on it, usually as it heads down a `panic()` code path. + This code path should be :ref:`OPAL_CEC_REBOOT2` with the OPAL_REBOOT_PLATFORM_ERROR + option. Details of the failure are likely delivered as part of HMI events if + `OPAL_HMI_FLAGS_NEW_EVENT` is set. diff --git a/roms/skiboot/doc/opal-api/opal-handle-interrupt.rst b/roms/skiboot/doc/opal-api/opal-handle-interrupt.rst new file mode 100644 index 000000000..f652af5a3 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-handle-interrupt.rst @@ -0,0 +1,29 @@ +.. _OPAL_HANDLE_INTERRUPT: + +OPAL_HANDLE_INTERRUPT +===================== + +The host OS must pass all interrupts in the `opal-interrupts` property of :ref:`device-tree/ibm,opal` in the device tree to OPAL. + +An example dt snippet is: + +.. code-block:: dts + + ibm,opal { + opal-interrupts = <0x10 0x11 0x12 0x13 0x14 0x20010 0x20011 0x20012 0x20013 0x20014 0xffe 0xfff 0x17fe 0x17ff 0x2ffe 0x2fff 0x37fe 0x37ff 0x20ffe 0x20fff 0x217fe 0x217ff 0x22ffe 0x22fff 0x237fe 0x237ff>; + }; + +When the host OS gets any of these interrupts, it must call +``OPAL_HANDLE_INTERRUPT``. + +The ``OPAL_HANDLE_INTERRUPT`` call takes two parameters, one input and one output. + +``uint32_t isn`` + the interrupt + +``uint64_t *outstanding_event_mask`` + returns outstanding events for host OS to handle + +The host OS should then handle any outstanding events. + +See :ref:`OPAL_POLL_EVENTS` for documentation on events. diff --git a/roms/skiboot/doc/opal-api/opal-i2c-request-109.rst b/roms/skiboot/doc/opal-api/opal-i2c-request-109.rst new file mode 100644 index 000000000..edcde4bcb --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-i2c-request-109.rst @@ -0,0 +1,64 @@ +.. _OPAL_I2C_REQUEST: + +OPAL_I2C_REQUEST +================ + +.. code-block:: c + + #define OPAL_I2C_REQUEST 109 + + /* OPAL I2C request */ + struct opal_i2c_request { + uint8_t type; + #define OPAL_I2C_RAW_READ 0 + #define OPAL_I2C_RAW_WRITE 1 + #define OPAL_I2C_SM_READ 2 + #define OPAL_I2C_SM_WRITE 3 + uint8_t flags; + #define OPAL_I2C_ADDR_10 0x01 /* Not supported yet */ + uint8_t subaddr_sz; /* Max 4 */ + uint8_t reserved; + __be16 addr; /* 7 or 10 bit address */ + __be16 reserved2; + __be32 subaddr; /* Sub-address if any */ + __be32 size; /* Data size */ + __be64 buffer_ra; /* Buffer real address */ + }; + + int opal_i2c_request(uint64_t async_token, uint32_t bus_id, + struct opal_i2c_request *oreq); + +Initiate I2C request using i2c master that OPAL controls. + +Return Codes +------------ + +Most return codes will come through as part of async completion. + +:ref:`OPAL_PARAMETER` + Invalid request pointer, or bus ID. +:ref:`OPAL_UNSUPPORTED` + Unsupported operation. e.g. 10 bit addresses not yet supported. +:ref:`OPAL_NO_MEM` + Not enough free memory in OPAL to initiate request. +:ref:`OPAL_ASYNC_COMPLETION` + Operation will complete asynchronously. +:ref:`OPAL_I2C_TIMEOUT` + I2C operation initiated successfully, but timed out. +:ref:`OPAL_I2C_INVALID_CMD` + Invalid i2c Command. +:ref:`OPAL_I2C_LBUS_PARITY` + I2C LBUS Parity error +:ref:`OPAL_I2C_BKEND_OVERRUN` + I2C Backend overrun. +:ref:`OPAL_I2C_BKEND_ACCESS` + I2C Backend Access error. +:ref:`OPAL_I2C_ARBT_LOST` + I2C Bus Arbitration lost. +:ref:`OPAL_I2C_NACK_RCVD` + I2C NACK received. +:ref:`OPAL_I2C_STOP_ERR` + I2C STOP error. +:ref:`OPAL_SUCCESS` + I2C operation completed successfully. Typically only as part of + async completion. diff --git a/roms/skiboot/doc/opal-api/opal-imc-counters.rst b/roms/skiboot/doc/opal-api/opal-imc-counters.rst new file mode 100644 index 000000000..85ade3f5a --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-imc-counters.rst @@ -0,0 +1,104 @@ +.. _opal-imc-counters: + +.. _OPAL_IMC_COUNTERS_INIT: + +OPAL_IMC_COUNTERS_INIT +====================== +OPAL call interface to initialize In-memory collection +infrastructure. Call does multiple scom writes on each +invocation for Core/Trace IMC initialization. And for the +Nest IMC, at this point, call is a no-op and returns +OPAL_SUCCESS. Incase of kexec, OS driver should first +stop the engine via OPAL_IMC_COUNTER_STOP(and then +free the memory if allocated, for nest memory is +mmapped). Incase of kdump, OS driver should stop +the engine via OPAL_IMC_COUNTER_STOP. + +OPAL does sanity checks to detect unknown or +unsupported IMC device type and nest units. +check_imc_device_type() function removes +unsupported IMC device type. disable_unavailable_units() +removes unsupported nest units by the microcode. +This way OPAL can lock down and advertise only +supported device type and nest units. + +Parameters +---------- +``uint32_t type`` + This parameter specifies the imc counter domain. + The value can be 'OPAL_IMC_COUNTERS_NEST', 'OPAL_IMC_COUNTERS_CORE' + or 'OPAL_IMC_COUNTERS_TRACE'. + +``uint64_t addr`` + This parameter must have a non-zero value. + This value must be a physical address of the core. + +``uint64_t cpu_pir`` + This parameter specifices target cpu pir + +Returns +------- + +:ref:`OPAL_PARAMETER` + In case of unsupported ``type`` +:ref:`OPAL_HARDWARE` + If any error in setting up the hardware. +:ref:`OPAL_SUCCESS` + On succesfully initialized or even if init operation is a no-op. + +.. _OPAL_IMC_COUNTERS_START: + +OPAL_IMC_COUNTERS_START +======================= +OPAL call interface for starting the In-Memory Collection +counters for a specified domain (NEST/CORE/TRACE). + +Parameters +---------- +``uint32_t type`` + This parameter specifies the imc counter domain. + The value can be 'OPAL_IMC_COUNTERS_NEST', + 'OPAL_IMC_COUNTERS_CORE' or 'OPAL_IMC_COUNTERS_TRACE'. + +``uint64_t cpu_pir`` + This parameter specifices target cpu pir + +Returns +------- + +:ref:`OPAL_PARAMETER` + In case of Unsupported ``type`` +:ref:`OPAL_HARDWARE` + If any error in setting up the hardware. +:ref:`OPAL_SUCCESS` + On successful execution of the operation for the given ``type``. + +.. _OPAL_IMC_COUNTERS_STOP: + +OPAL_IMC_COUNTERS_STOP +====================== +OPAL call interface for stoping In-Memory +Collection counters for a specified domain (NEST/CORE/TRACE). +STOP should always be called after a related START. +While STOP *may* run successfully without an associated +START call, this is not gaurenteed. + +Parameters +---------- +``uint32_t type`` + This parameter specifies the imc counter domain. + The value can be 'OPAL_IMC_COUNTERS_NEST', + 'OPAL_IMC_COUNTERS_CORE' or 'OPAL_IMC_COUNTERS_TRACE' + +``uint64_t cpu_pir`` + This parameter specifices target cpu pir + +Returns +------- + +:ref:`OPAL_PARAMETER` + In case of Unsupported ``type`` +:ref:`OPAL_HARDWARE` + If any error in setting up the hardware. +:ref:`OPAL_SUCCESS` + On successful execution of the operation for the given ``type``. diff --git a/roms/skiboot/doc/opal-api/opal-int-eoi-124.rst b/roms/skiboot/doc/opal-api/opal-int-eoi-124.rst new file mode 100644 index 000000000..c7d991c88 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-int-eoi-124.rst @@ -0,0 +1,24 @@ +.. _OPAL_INT_EOI: + +OPAL_INT_EOI +============ + +.. code-block:: c + + #define OPAL_INT_EOI 124 + + static int64_t opal_int_eoi(uint32_t xirr); + +Modelled on the ``H_EOI`` PAPR call. + +This can return a positive value, which means more interrupts +are queued for that CPU/priority and must be fetched as the XIVE is not +guaranteed to assert the CPU external interrupt line again until the +pending queue for the current priority has been emptied. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must +exist in the device tree (see :ref:`xive-device-tree`). If OPAL does not create +such a device, the host OS MUST NOT use this call. diff --git a/roms/skiboot/doc/opal-api/opal-int-get-xirr-122.rst b/roms/skiboot/doc/opal-api/opal-int-get-xirr-122.rst new file mode 100644 index 000000000..85daa15f4 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-int-get-xirr-122.rst @@ -0,0 +1,19 @@ +.. _OPAL_INT_GET_XIRR: + +OPAL_INT_GET_XIRR +================= + +.. code-block:: c + + #define OPAL_INT_GET_XIRR 122 + + int64_t opal_int_get_xirr(uint32_t *out_xirr, bool just_poll); + +Modelled on the PAPR call. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must +exist in the device tree (see :ref:`xive-device-tree`). If OPAL does not create +such a device, the host OS MUST NOT use this call. diff --git a/roms/skiboot/doc/opal-api/opal-int-set-cppr-123.rst b/roms/skiboot/doc/opal-api/opal-int-set-cppr-123.rst new file mode 100644 index 000000000..918022a82 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-int-set-cppr-123.rst @@ -0,0 +1,19 @@ +.. _OPAL_INT_SET_CPPR: + +OPAL_INT_SET_CPPR +================= + +.. code-block:: c + + #define OPAL_INT_SET_CPPR 123 + + static int64_t opal_int_set_cppr(uint8_t cppr); + +Modelled on the ``H_CPPR`` PAPR call. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must +exist in the device tree (see :ref:`xive-device-tree`). If OPAL does not create +such a device, the host OS MUST NOT use this call. diff --git a/roms/skiboot/doc/opal-api/opal-int-set-mfrr-125.rst b/roms/skiboot/doc/opal-api/opal-int-set-mfrr-125.rst new file mode 100644 index 000000000..8e0f18530 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-int-set-mfrr-125.rst @@ -0,0 +1,20 @@ +.. _OPAL_INT_SET_MFRR: + +OPAL_INT_SET_MFRR +================= + +.. code-block:: c + + #define OPAL_INT_SET_MFRR 125 + + static int64_t opal_int_set_mfrr(uint32_t cpu, uint8_t mfrr); + + +Modelled on the ``H_IPI`` PAPR call. + +For P9 and above systems where host doesn't know about interrupt controller. +An OS can instead make OPAL calls for XICS emulation. + +For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must +exist in the device tree (see :ref:`xive-device-tree`). If OPAL does not create +such a device, the host OS MUST NOT use this call. diff --git a/roms/skiboot/doc/opal-api/opal-invalid-call--1.rst b/roms/skiboot/doc/opal-api/opal-invalid-call--1.rst new file mode 100644 index 000000000..cb7b06c84 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-invalid-call--1.rst @@ -0,0 +1,6 @@ +OPAL_INVALID_CALL +================= + +An OPAL call of ``-1`` will always return ``OPAL_PARAMETER``. It is always ivalid. + +It exists purely for testing. diff --git a/roms/skiboot/doc/opal-api/opal-ipmi-send-recv-107-108.rst b/roms/skiboot/doc/opal-api/opal-ipmi-send-recv-107-108.rst new file mode 100644 index 000000000..b8c3ed1f6 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-ipmi-send-recv-107-108.rst @@ -0,0 +1,97 @@ +.. _OPAL_IPMI_SEND: + +OPAL_IPMI_SEND +============== + +.. code-block:: c + + #define OPAL_IPMI_SEND 107 + + enum { + OPAL_IPMI_MSG_FORMAT_VERSION_1 = 1, + }; + + struct opal_ipmi_msg { + uint8_t version; + uint8_t netfn; + uint8_t cmd; + uint8_t data[]; + }; + + int64_t opal_ipmi_send(uint64_t interface, + struct opal_ipmi_msg *opal_ipmi_msg, uint64_t msg_len); + +:ref:`OPAL_IPMI_SEND` call will send an IPMI message to the service processor. + +Parameters +---------- + +``interface`` + ``interface`` parameter is the value from the ipmi interface node ``ibm,ipmi-interface-id`` +``opal_ipmi_msg`` + ``opal_ipmi_msg`` is the pointer to a ``struct opal_ipmi_msg`` (see above) +``msg_len`` + ipmi message request size + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + ``msg`` queued successfully +:ref:`OPAL_PARAMETER` + invalid ipmi message request length ``msg_len`` +:ref:`OPAL_HARDWARE` + backend support is not present as block transfer/service processor ipmi routines are not + initialized which are used for communication +:ref:`OPAL_UNSUPPORTED` + in-correct opal ipmi message format version ``opal_ipmi_msg->version`` +:ref:`OPAL_RESOURCE` + insufficient resources to create ``ipmi_msg`` structure + +.. _OPAL_IPMI_RECV: + +OPAL_IPMI_RECV +============== + +.. code-block:: c + + #define OPAL_IPMI_RECV 108 + + enum { + OPAL_IPMI_MSG_FORMAT_VERSION_1 = 1, + }; + + struct opal_ipmi_msg { + uint8_t version; + uint8_t netfn; + uint8_t cmd; + uint8_t data[]; + }; + + int64_t opal_ipmi_recv(uint64_t interface, + struct opal_ipmi_msg *opal_ipmi_msg, uint64_t *msg_len) + +``OPAL_IPMI_RECV`` call reads an ipmi message of type ``ipmi_msg`` from ipmi message +queue ``msgq`` into host OS structure ``opal_ipmi_msg``. + +Parameters +---------- + +``interface`` + ``interface`` parameter is the value from the ipmi interface node ``ibm,ipmi-interface-id`` +``opal_ipmi_msg`` + ``opal_ipmi_msg`` is the pointer to a ``struct opal_ipmi_msg`` (see above) +``msg_len`` + ``msg_len`` is the pointer to ipmi message response size + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + ipmi message dequeued from ``msgq`` queue and memory taken by it got released successfully +:ref:`OPAL_EMPTY` + ``msgq`` list is empty +ref:`OPAL_PARAMETER` + invalid ipmi ``interface`` value +:ref:`OPAL_UNSUPPORTED` + incorrect opal ipmi message format version ``opal_ipmi_msg->version`` diff --git a/roms/skiboot/doc/opal-api/opal-led-get-set-114-115.rst b/roms/skiboot/doc/opal-api/opal-led-get-set-114-115.rst new file mode 100644 index 000000000..9bec84731 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-led-get-set-114-115.rst @@ -0,0 +1,133 @@ +.. _opal-api-LEDs: + +Service Indicators (LEDS) +========================= + +The service indicator is one element of an overall hardware service strategy +where end user simplicity is a high priority. The goal is system firmware or +operating system code to isolate hardware failures to the failing FRU and +automatically activate the fault indicator associated with the failing FRU. +The end user then needs only to look for the FRU with the active fault +indicator to know which part to replace. + +Different types of indicators handled by LED code: + + - System attention indicator (Check log indicator) + Indicates there is a problem with the system that needs attention. + - Identify + Helps the user locate/identify a particular FRU or resource in the + system. + - Fault + Indicates there is a problem with the FRU or resource at the + location with which the indicator is associated. + +All LEDs are defined in the device tree (see :ref:`device-tree/ibm,opal/leds`). + +LED Design +---------- + When it comes to implementation we can classify LEDs into two + categories: + +1. Hypervisor (OPAL) controlled LEDs (All identify & fault indicators) + During boot, we read/cache these LED details in OPAL (location code, + state, etc). We use cached data to serve read request from FSP/Host. + And we use SPCN passthrough MBOX command to update these LED state. + +2. Service processor (FSP) controlled LEDs (System Attention Indicator) + During boot, we read/cache this LED info using MBOX command. Later + anytime FSP updates this LED, it sends update system parameter + notification MBOX command. We use that data to update cached data. + LED update request is sent via set/reset attn MBOX command. + +LED update request: + Both FSP and Host will send LED update requests. We have to serialize + SPCN passthrough command. Hence we maintain local queue. + +Note: + + - For more information regarding service indicator refer to PAPR spec + (Service Indicators chapter). + +There are two OPAL calls relating to LED operations. + +.. _OPAL_LEDS_GET_INDICATOR: + +OPAL_LEDS_GET_INDICATOR +----------------------- + +.. code-block:: c + + #define OPAL_LEDS_GET_INDICATOR 114 + + int64_t opal_leds_get_indicator(char *loc_code, u64 *led_mask, + u64 *led_value, u64 *max_led_type); + +Returns LED state for the given location code. + +``loc_code`` + Location code of the LEDs. +``led_mask`` + LED types whose status is available (return by OPAL) +``led_value`` + Status of the available LED types (return by OPAL) +``max_led_type`` + Maximum number of supported LED types (Host/OPAL) + +The host will pass the location code of the LED types (loc_code) and +maximum number of LED types it understands (max_led_type). OPAL will +update the 'led_mask' with set bits pointing to LED types whose status +is available and updates the 'led_value' with actual status. OPAL checks +the 'max_led_type' to understand whether the host is newer or older +compared to itself. In the case where the OPAL is newer compared +to host (OPAL's max_led_type > host's max_led_type), it will update +led_mask and led_value according to max_led_type requested by the host. +When the host is newer compared to the OPAL (host's max_led_type > +OPAL's max_led_type), OPAL updates 'max_led_type' to the maximum +number of LED type it understands and updates 'led_mask', 'led_value' +based on that maximum value of LED types. + +Currently this is only implemented on FSP basde machines, see +hw/fsp/fsp-leds.c for more deatails. + +.. _OPAL_LEDS_SET_INDICATOR: + +OPAL_LEDS_SET_INDICATOR +----------------------- + +.. code-block:: c + + #define OPAL_LEDS_SET_INDICATOR 115 + + int64_t opal_leds_set_indicator(uint64_t async_token, + char *loc_code, const u64 led_mask, + const u64 led_value, u64 *max_led_type); + +Sets LED state for the given location code. + +``loc_code`` + Location code of the LEDs to be set. +``led_mask`` + LED types whose status will be updated +``led_value`` + Requested status of various LED types. +``max_led_type`` + Maximum number of supported LED types. If OPAL supports fewer LED types + than requested, it will set ``max_led_type`` to the maximum it does support. + +The host will pass the location code of the LED types, mask, value +and maximum number of LED types it understands. OPAL will update +LED status for all the LED types mentioned in the mask with their +value mentioned. OPAL checks the 'max_led_type' to understand +whether the host is newer or older compared to itself. In case where +the OPAL is newer compared to the host (OPAL's max_led_type > +host's max_led_type), it updates LED status based on max_led_type +requested from the host. When the host is newer compared to the OPAL +(host's max_led_type > OPAL's max_led_type), OPAL updates +'max_led_type' to the maximum number of LED type it understands and +then it updates LED status based on that updated maximum value of LED +types. Host needs to check the returned updated value of max_led_type +to figure out which part of it's request got served and which ones got +ignored. + +Currently this is only implemented on FSP basde machines, see +hw/fsp/fsp-leds.c for more deatails. diff --git a/roms/skiboot/doc/opal-api/opal-lpc-read-write-67-68.rst b/roms/skiboot/doc/opal-api/opal-lpc-read-write-67-68.rst new file mode 100644 index 000000000..52d377892 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-lpc-read-write-67-68.rst @@ -0,0 +1,114 @@ +.. _OPAL_LPC_READ: + +OPAL_LPC_READ +============= + +.. code-block:: c + + #define OPAL_LPC_READ 67 + + /* + * Address cycle types for LPC accesses. These also correspond + * to the content of the first cell of the "reg" property for + * device nodes on the LPC bus + */ + enum OpalLPCAddressType { + OPAL_LPC_MEM = 0, + OPAL_LPC_IO = 1, + OPAL_LPC_FW = 2, + }; + + int64_t opal_lpc_read(uint32_t chip_id, enum OpalLPCAddressType addr_type, + uint32_t addr, uint32_t *data, uint32_t sz); + +This function related to Low Pin Count (LPC) bus. This function reads the +data from IDSEL register for ``chip_id``, which has LPC information. +From ``addr`` for ``addr_type`` with read size ``sz`` bytes in to a +variable named ``data``. + +Parameters +---------- + +``chip_id`` + The ``chip_id`` parameter contains value of the chip number identified at + boot time. +``addr_type`` + The ``addr_type`` is one of the LPC supported address types. + Supported address types are: + + - LPC memory, + - LPC IO and + - LPC firmware. + +``addr`` + The ``addr`` from which the data has to be read. +``data`` + The ``data`` will be used to store the read data. +``sz`` + How many ``sz`` bytes to be read in to ``data``. + +Return Codes +------------ + +:ref:`OPAL_PARAMETER` + Indicates either ``chip_id`` not found or ``chip_id`` doesn’t contain + LPC information. +:ref:`OPAL_SUCCESS` + Indicates Success! + +.. _OPAL_LPC_WRITE: + +OPAL_LPC_WRITE +============== + +.. code-block:: c + + #define OPAL_LPC_WRITE 68 + + /* + * Address cycle types for LPC accesses. These also correspond + * to the content of the first cell of the "reg" property for + * device nodes on the LPC bus + */ + enum OpalLPCAddressType { + OPAL_LPC_MEM = 0, + OPAL_LPC_IO = 1, + OPAL_LPC_FW = 2, + }; + + int64_t opal_lpc_write(uint32_t chip_id, enum OpalLPCAddressType addr_type, + uint32_t addr, uint32_t data, uint32_t sz); + +This function related to Low Pin Count (LPC) bus. This function writes the +``data`` in to ECCB register for ``chip_id``, which has LPC information. +From ``addr`` for ``addr_type`` with write size ``sz`` bytes. + +Parameters +---------- + +``chip_id`` + The ``chip_id`` parameter contains value of the chip number identified at + boot time. +``addr_type`` + The ``addr_type`` is one of the address types LPC supported. + Supported address types are: + + - LPC memory, + - LPC IO and + - LPC firmware. + +``addr`` + The ``addr`` to where the ``data`` need to be written. +``data`` + The ``data`` for writing. +``sz`` + How many ``sz`` bytes to write. + +Return Codes +------------ + +:ref:`OPAL_PARAMETER` + Indicates either ``chip_id`` not found or ``chip_id`` doesn’t contain LPC + information. +:ref:`OPAL_SUCCESS` + Indicates Success! diff --git a/roms/skiboot/doc/opal-api/opal-messages.rst b/roms/skiboot/doc/opal-api/opal-messages.rst new file mode 100644 index 000000000..1f5d6f20b --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-messages.rst @@ -0,0 +1,235 @@ +.. _opal-messages: + +OPAL_MESSAGE +============ + +The host OS can use OPAL_GET_MSG to retrive messages queued by OPAL. The +messages are defined by enum opal_msg_type. The host is notified of there +being messages to be consumed by the OPAL_EVENT_MSG_PENDING bit being set. + +An opal_msg is: :: + + struct opal_msg { + __be32 msg_type; + __be32 size; + __be64 params[8]; + }; + +The data structure is ALWAYS at least this size (4+4+8*8 = 72 bytes). Some +messages define fewer than eight parameters. For messages that do not +define all eight parameters, the value in the undefined parameters is +undefined, although can safely be memcpy()d or otherwise moved. + +In the device tree, there's an opal-msg-size property of the OPAL node that +says the size of a struct opal-msg. Kernel will use this property to allocate +memory for opal_msg structure. See ``OPAL_GET_MESSAGE`` documentation for +details. +:: + + ibm,opal { + opal-msg-size = <0x48>; + } + + +OPAL_MSG_ASYNC_COMP +------------------- +:: + + params[0] = token + params[1] = rc + +Additional parameters are function-specific. + +OPAL_MSG_MEM_ERR +---------------- + +.. _OPAL_MSG_EPOW: + +OPAL_MSG_EPOW +------------- + +Used by OPAL to issue environmental and power warnings to host OS for +conditions requiring an earlier poweroff. A few examples of these are high +ambient temperature or system running on UPS power with low UPS battery. +Host OS can query OPAL via :ref:`OPAL_GET_EPOW_STATUS` API to obtain information about +EPOW conditions present. Refer include/opal-api.h for description of +all supported EPOW events. OPAL_SYSPOWER_CHNG, OPAL_SYSPOWER_FAIL and +OPAL_SYSPOWER_INC events don't require system poweroff. + +Host OS should look for 'ibm,opal-v3-epow' string as compatible property +for 'epow' node under OPAL device-tree to determine epow support. + +OPAL_MSG_SHUTDOWN +----------------- + +Used by OPAL to inform the host OS it must imitate a graceful shutdown. Uses +the first parameter to indicate weather the system is going down for shutdown +or a reboot. :: + + params[0] = 0x01 reboot, 0x00 shutdown + +.. _OPAL_MSG_HMI_EVT: + +OPAL_MSG_HMI_EVT +---------------- + +Used by OPAL to sends the OPAL HMI Event to the host OS that reports a +summary of HMI error and whether it was successfully recovered or not. + +HMI is a Hypervisor Maintenance Interrupt usually reports error related +to processor recovery/checkstop, NX checkstop and Timer facility. Hypervisor +then takes this opportunity to analyze and recover from some of these errors. +Hypervisor takes assistance from OPAL layer to handle and recover from +HMI. After handling HMI, OPAL layer sends the summary of error report and +status of recovery action using HMI event structure shown below. + +The HMI event structure uses version numbering to allow future enhancement +to accommodate additional members. The version start from V1 onward. +Version 0 is invalid version and unsupported. + +The current version of HMI event structure V2 and is backward compatible +to V1 version. + +Notes: + +- When adding new structure to the union in future, the version number + must be bumped. +- All future versions must be backward compatible to all its older versions. +- Size of this structure should not exceed that of struct opal_msg. + +:: + + struct OpalHMIEvent { + uint8_t version; /* 0x00 */ + uint8_t severity; /* 0x01 */ + uint8_t type; /* 0x02 */ + uint8_t disposition; /* 0x03 */ + uint8_t reserved_1[4]; /* 0x04 */ + + __be64 hmer; + /* TFMR register. Valid only for TFAC and TFMR_PARITY error type. */ + __be64 tfmr; + + /* version 2 and later */ + union { + /* + * checkstop info (Core/NX). + * Valid for OpalHMI_ERROR_MALFUNC_ALERT. + */ + struct { + uint8_t xstop_type; /* enum OpalHMI_XstopType */ + uint8_t reserved_1[3]; + __be32 xstop_reason; + union { + __be32 pir; /* for CHECKSTOP_TYPE_CORE */ + __be32 chip_id; /* for CHECKSTOP_TYPE_NX */ + } u; + } xstop_error; + } u; + }; + +.. _OPAL_MSG_DPO: + +OPAL_MSG_DPO +------------ + +Delayed poweroff where OPAL informs host OS that a poweroff has been +requested and a forced shutdown will happen in future. Host OS can use +OPAL_GET_DPO_STATUS API to query OPAL the number of seconds remaining +before a forced poweroff will occur. + +.. _OPAL_MSG_PRD: + +OPAL_MSG_PRD +------------ + +This message is a OPAL-to-HBRT notification, and contains a +struct opal_prd_msg: :: + + enum opal_prd_msg_type { + OPAL_PRD_MSG_TYPE_INIT = 0, /* HBRT --> OPAL */ + OPAL_PRD_MSG_TYPE_FINI, /* HBRT --> OPAL */ + OPAL_PRD_MSG_TYPE_ATTN, /* HBRT <-- OPAL */ + OPAL_PRD_MSG_TYPE_ATTN_ACK, /* HBRT --> OPAL */ + OPAL_PRD_MSG_TYPE_OCC_ERROR, /* HBRT <-- OPAL */ + OPAL_PRD_MSG_TYPE_OCC_RESET, /* HBRT <-- OPAL */ + }; + + struct opal_prd_msg { + uint8_t type; + uint8_t pad[3]; + __be32 token; + union { + struct { + __be64 version; + __be64 ipoll; + } init; + struct { + __be64 proc; + __be64 ipoll_status; + __be64 ipoll_mask; + } attn; + struct { + __be64 proc; + __be64 ipoll_ack; + } attn_ack; + struct { + __be64 chip; + } occ_error; + struct { + __be64 chip; + } occ_reset; + }; + }; + +Responses from the kernel use the same message format, but are passed +through the :ref:`OPAL_PRD_MSG` call. + +OPAL_MSG_OCC +------------ + +This is used by OPAL to inform host about OCC events like OCC reset, +OCC load and throttle status change by OCC which can indicate the +host the reason for frequency throttling/unthrottling. :: + + #define OCC_RESET 0 + #define OCC_LOAD 1 + #define OCC_THROTTLE 2 + #define OCC_MAX_THROTTLE_STATUS 5 + /* + * struct opal_occ_msg: + * type: OCC_RESET, OCC_LOAD, OCC_THROTTLE + * chip: chip id + * throttle status: Indicates the reason why OCC may have limited + * the max Pstate of the chip. + * 0x00 = No throttle + * 0x01 = Power Cap + * 0x02 = Processor Over Temperature + * 0x03 = Power Supply Failure (currently not used) + * 0x04 = Over current (currently not used) + * 0x05 = OCC Reset (not reliable as some failures will not allow for + * OCC to update throttle status) + */ + struct opal_occ_msg { + __be64 type; + __be64 chip; + __be64 throttle_status; + }; + +Host should read opal_occ_msg.chip and opal_occ_msg.throttle_status +only when ``opal_occ_msg.type = OCC_THROTTLE``. +If host receives ``OCC_THROTTLE`` after an ``OCC_RESET`` then this throttle +message will have a special meaning which indicates that all the OCCs +have become active after a reset. In such cases ``opal_occ_msg.chip`` and +``opal_occ_msg.throttle_status`` will be set to 0 and host should not use +these values. + +If ``opal_occ_msg.type > 2`` then host should ignore the message for now, +new events can be defined for ``opal_occ_msg.type`` in the future versions +of OPAL. + +OPAL_MSG_PRD2 +------------- + +This message is a OPAL-to-HBRT notification. Its same as OPAL_MSG_PRD except +this one supports passing more than 64bytes (8*8) of data. diff --git a/roms/skiboot/doc/opal-api/opal-mpipl-173-174.rst b/roms/skiboot/doc/opal-api/opal-mpipl-173-174.rst new file mode 100644 index 000000000..32e64e375 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-mpipl-173-174.rst @@ -0,0 +1,157 @@ +.. _opal-api-mpipl: + +OPAL MPIPL APIs +=============== + +.. code-block:: c + + #define OPAL_MPIPL_UPDATE 173 + #define OPAL_MPIPL_REGISTER_TAG 174 + #define OPAL_MPIPL_QUERY_TAG 175 + +These calls are used for MPIPL (Memory Preserving Initial Program Load). + +It is an OPTIONAL part of the OPAL spec. + +If a platform supports MPIPL, then we will have "/ibm,opal/dump" node in +device tree (see :ref:`device-tree/ibm,opal/dump`). + +.. _OPAL_MPIPL_UPDATE: + +OPAL_MPIPL_UPDATE +================== +Linux kernel will use this call to register/unregister MPIPL. + +.. code-block:: c + + #define OPAL_MPIPL_UPDATE 173 + + int64_t opal_mpipl_update(enum mpipl_ops ops, u64 src, u64 dest, u64 size) + + /* MPIPL update operations */ + enum mpipl_ops { + OPAL_MPIPL_ADD_RANGE = 0, + OPAL_MPIPL_REMOVE_RANGE = 1, + OPAL_MPIPL_REMOVE_ALL = 2, + OPAL_MPIPL_FREE_PRESERVED_MEMORY= 3, + }; + +ops : +----- + OPAL_MPIPL_ADD_RANGE + Add new entry to MPIPL table. Kernel will send src, dest and size. + During MPIPL content from source address is moved to destination address. + src = Source start address + dest = Destination start address + size = size + + OPAL_MPIPL_REMOVE_RANGE + Remove kernel requested entry from MPIPL table. + src = Source start address + dest = Destination start address + size = ignore + + OPAL_MPIPL_REMOVE_ALL + Remove all kernel passed entry from MPIPL table. + src = ignore + dest = ignore + size = ignore + + OPAL_MPIPL_FREE_PRESERVED_MEMORY + Post MPIPL, kernel will indicate OPAL that it has processed dump and + it can clear/release metadata area. + src = ignore + dest = ignore + size = ignore + +Return Values +------------- + +``OPAL_SUCCESS`` + Operation success + +``OPAL_PARAMETER`` + Invalid parameter + +``OPAL_RESOURCE`` + Ran out of space in MDST/MDDT table to add new entry + +``OPAL_HARDWARE`` + Platform does not support fadump + + +.. _OPAL_MPIPL_REGISTER_TAG: + +OPAL_MPIPL_REGISTER_TAG +======================= +Kernel will use this API to register tags during MPIPL registration. +It expects OPAL to preserve these tags across MPIPL. Post MPIPL Linux +kernel will use `opal_mpipl_query_tag` call to retrieve these tags. + +.. code-block:: c + + opal_mpipl_register_tag(enum opal_mpipl_tags tag, uint64_t tag_val) + + tag: + OPAL_MPIPL_TAG_KERNEL + During first boot, kernel will setup its metadata area and asks + OPAL to preserve metadata area pointer across MPIPL. Post MPIPL + kernel requests OPAL to provide metadata pointer and it will use + that pointer to retrieve metadata and create dump. + + OPAL_MPIPL_TAG_BOOT_MEM + During MPIPL registration kernel will specify how much memory + firmware can use for Post MPIPL load. Post MPIPL petitboot kernel + will query for this tag to get boot memory size. + +Return Values +------------- +``OPAL_SUCCESS`` + Operation success + +``OPAL_PARAMETER`` + Invalid parameter + +.. _OPAL_MPIPL_QUERY_TAG: + +OPAL_MPIPL_QUERY_TAG +==================== +Post MPIPL linux kernel will call this API to get metadata tag. And use this +tag to retrieve metadata information and generate dump. + +.. code-block:: c + + #define OPAL_MPIPL_QUERY_TAG 175 + + uint64_t opal_mpipl_query_tag(enum opal_mpipl_tags tag, uint64_t *tag_val) + + enum opal_mpipl_tags { + OPAL_MPIPL_TAG_CPU = 0, + OPAL_MPIPL_TAG_OPAL = 1, + OPAL_MPIPL_TAG_KERNEL = 2, + OPAL_MPIPL_TAG_BOOT_MEM = 3, + }; + + tag : + OPAL_MPIPL_TAG_CPU + Pointer to CPU register data content metadata area + OPAL_MPIPL_TAG_OPAL + Pointer to OPAL metadata area + OPAL_MPIPL_TAG_KERNEL + During first boot, kernel will setup its metadata area and asks + OPAL to preserve metadata area pointer across MPIPL. Post MPIPL + kernel calls this API to get metadata pointer and it will use + that pointer to retrieve metadata and create dump. + OPAL_MPIPL_TAG_BOOT_MEM + During MPIPL registration kernel will specify how much memory + firmware can use for Post MPIPL load. Post MPIPL petitboot kernel + will query for this tag to get boot memory size. + +Return Values +------------- + +``OPAL_SUCCESS`` + Operation success + +``OPAL_PARAMETER`` + Invalid parameter diff --git a/roms/skiboot/doc/opal-api/opal-nmmu-set-ptcr-127.rst b/roms/skiboot/doc/opal-api/opal-nmmu-set-ptcr-127.rst new file mode 100644 index 000000000..0e5181cf4 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-nmmu-set-ptcr-127.rst @@ -0,0 +1,29 @@ +.. _OPAL_NMMU_SET_PTCR: + +OPAL_NMMU_SET_PTCR +------------------ + +.. code-block:: c + + #define OPAL_NMMU_SET_PTCR 127 + + int64 opal_nmmu_set_ptcr(uint64 chip_id, uint64_t ptcr); + + +``uint64 chip_id`` + either the chip id containing the nest mmu who's ptcr should be set + or alternatively -1ULL to indicate all nest mmu ptcr's should be set to + the same value. +``uint64 ptcr`` + ptcr value pointing to either the radix tables or hash tables. + +This OPAL call sets up the Nest MMU by pointing it at the radix page +table base or the hash page table base (HTABORG). + +Return Values +^^^^^^^^^^^^^ + +:ref:`OPAL_SUCCESS` + the PTCR was updated successful +:ref:`OPAL_PARAMETER` + a parameter was incorrect diff --git a/roms/skiboot/doc/opal-api/opal-npu2-146-147-148.rst b/roms/skiboot/doc/opal-api/opal-npu2-146-147-148.rst new file mode 100644 index 000000000..4b9a7c19d --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-npu2-146-147-148.rst @@ -0,0 +1,74 @@ +.. _OPAL_NPU2: + +OPAL NPU2 calls +================ + +There are three OPAL calls for interacting with NPU2 devices: :: + +#define OPAL_NPU_INIT_CONTEXT 146 +#define OPAL_NPU_DESTROY_CONTEXT 147 +#define OPAL_NPU_MAP_LPAR 148 + +These are used to setup and configure address translation services +(ATS) for a given NVLink2 device. Note that in some documentation this +is also referred to as extended translation services (XTS). + +Each NVLink2 supports multiple processes running on a GPU which issues +requests for address translation. The NPU2 is responsible for +completing the request by forwarding it to the Nest MMU (NMMU) along +with the appropriate translation context (MSR/LPCR) bits. These bits +are keyed off a 20-bit process ID (PASID/PID) which is identical to +the PID used on the processor. + +The OPAL calls documented here are used to setup/destroy the +appropriate context for a given process on a given NVLink2 device. + +.. _OPAL_NPU_INIT_CONTEXT: + +OPAL_NPU_INIT_CONTEXT +--------------------- + +Parameters: :: + + uint64_t phb_id + int pasid + uint64_t msr + uint64_t lpid + +Allocates a new context ID and sets up the given PASID/PID to be +associated with the supplied MSR on for the given LPID. MSR should +only contain bits set requried for NPU2 address lookups - ie. MSR +DR/HV/PR/SF. + +Returns the context ID on success or ``OPAL_RESOURCE`` if no more +contexts are available or ``OPAL_UNSUPPORTED`` in the case of +unsupported MSR bits. + +.. _OPAL_NPU_DESTROY_CONTEXT: + +OPAL_NPU_DESTROY_CONTEXT +------------------------ + +Parameters: :: + + uint64_t phb_id + uint64_t id + +Destroys a previously allocated context ID. This may cause further +translation requests from the GPU to fail. + +.. _OPAL_NPU_MAP_LPAR: + +OPAL_NPU_MAP_LPAR +----------------- + +Parameters: :: + + uint64_t phb_id + uint64_t bdf + uint64_t lparid + uint64_t lpcr + +Associates the given GPU BDF with a particular LPAR and LPCR +bits. Hash mode ATS is currently unsupported so lpcr should be set +to 0. diff --git a/roms/skiboot/doc/opal-api/opal-npu2-get-set-relaxed-order-168-169.rst b/roms/skiboot/doc/opal-api/opal-npu2-get-set-relaxed-order-168-169.rst new file mode 100644 index 000000000..a27729c11 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-npu2-get-set-relaxed-order-168-169.rst @@ -0,0 +1,67 @@ +.. _OPAL_NPU_SET_RELAXED_ORDER: + +OPAL_NPU_SET_RELAXED_ORDER +========================== + +Request that relaxed memory ordering be enabled or disabled for a device. + +Parameters +---------- +:: + + uint64_t phb_id + uint16_t bdfn + bool request_enabled + +``phb_id`` + OPAL ID of the PHB + +``bdfn`` + Bus-Device-Function number of the device + +``request_enabled`` + Requested state of relaxed memory ordering enablement + +Return values +------------- + +``OPAL_SUCCESS`` + Requested state set + +``OPAL_PARAMETER`` + The given phb_id or bdfn is invalid or out of range + +``OPAL_CONSTRAINED`` + Relaxed ordering can not be enabled until an enable request is made + for every device on this PHB. + +``OPAL_RESOURCE`` + No more relaxed ordering sources are available + +.. _OPAL_NPU_GET_RELAXED_ORDER: + +OPAL_NPU_GET_RELAXED_ORDER +========================== + +Query the relaxed memory ordering state of a device. + +Parameters +---------- +:: + + uint64_t phb_id + uint64_t bdfn + +``phb_id`` + OPAL ID of the PHB + +``bdfn`` + Bus-Device-Function number of the device + +Return values +------------- + +On success, the current relaxed ordering state is returned. + +``OPAL_PARAMETER`` + The given phb_id or bdfn is invalid. diff --git a/roms/skiboot/doc/opal-api/opal-npu2-opencapi-159-160-161-171-172.rst b/roms/skiboot/doc/opal-api/opal-npu2-opencapi-159-160-161-171-172.rst new file mode 100644 index 000000000..6d603f173 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-npu2-opencapi-159-160-161-171-172.rst @@ -0,0 +1,203 @@ +.. _OPAL_NPU_SPA_SETUP: + +OPAL_NPU_SPA_SETUP +================== + +OpenCAPI devices only. + +Sets up a Shared Process Area (SPA) with the Shared Process Area +Pointer (SPAP) set to the provided address `addr`, and sets the OTL PE +mask (used for PASID to PE handle conversion) to `PE_mask`. + +If `addr` is NULL, the SPA will be disabled. `addr` must be 4K aligned. + +Parameters +---------- +:: + + uint64_t phb_id + int bdfn + uint64_t addr + uint64_t PE_mask + +``phb_id`` + OPAL ID of PHB + +``bdfn`` + Bus-Device-Function number of OpenCAPI AFU + +``addr`` + Address of Shared Process Area, or NULL to disable SPA. Must be 4K aligned. + +``PE_mask`` + Process Element mask for PASID to PE handle conversion + +Return Values +------------- + +OPAL_SUCCESS + SPAP and PE mask were successfully set + +OPAL_PARAMETER + A provided parameter was invalid + +OPAL_BUSY + SPA is already enabled (or if addr is NULL, SPA is already disabled) + +.. _OPAL_NPU_SPA_CLEAR_CACHE: + +OPAL_NPU_SPA_CLEAR_CACHE +======================== + +OpenCAPI devices only. + +Invalidates the Process Element with the given `PE_handle` from the NPU's SPA cache. + +Parameters +---------- +:: + + uint64_t phb_id + uint32_t bdfn + uint64_t PE_handle + +``phb_id`` + OPAL ID of PHB + +``bdfn`` + Bus-Device-Function number of OpenCAPI AFU + +``PE_handle`` + Handle of Process Element being cleared from SPA cache + +Return Values +------------- + +OPAL_SUCCESS + PE was successfully cleared from SPA cache + +OPAL_PARAMETER + A provided parameter was invalid + +OPAL_BUSY + XSLO is currently invalidating a previously requested entry + +.. _OPAL_NPU_TL_SET: + +OPAL_NPU_TL_SET +=============== + +OpenCAPI devices only. + +Update the NPU OTL configuration with device capabilities. + +Parameters +---------- +:: + + uint64_t phb_id + uint32_t bdfn + long capabilities + uint64_t rate_phys + int rate_sz + +``phb_id`` + OPAL ID of PHB + +``bdfn`` + Bus-Device-Function number of OpenCAPI AFU + +``capabilities`` + Bitmap of TL templates the device can receive + +``rate_phys`` + Physical address of rates buffer + +``rate_sz`` + Size of rates buffer (must be equal to 32) + +Return Values +------------- + +OPAL_SUCCESS + OTL configuration was successfully updated + +OPAL_PARAMETER + A provided parameter was invalid + + .. _OPAL_NPU_MEM_ALLOC: + +OPAL_NPU_MEM_ALLOC +================== + +OpenCAPI devices only. + +Sets up the NPU memory BAR for Lowest Point of Coherency (LPC) memory. + +At present, only one device per CPU can use LPC memory, and a maximum of 4TB +can be allocated. + +Parameters +---------- +:: + + uint64_t phb_id + uint32_t bdfn + uint64_t size + uint64_t *bar + +``phb_id`` + OPAL ID of PHB + +``bdfn`` + Bus-Device-Function number of OpenCAPI AFU + +``size`` + Size of requested LPC memory area in bytes + +``bar`` + Pointer to variable where base of LPC memory area will be returned + +Return Values +------------- + +OPAL_SUCCESS + BAR setup completed successfully + +OPAL_PARAMETER + A provided parameter was invalid + +OPAL_RESOURCE + The BAR could not be assigned due to limitations + +.. _OPAL_NPU_MEM_RELEASE: + +OPAL_NPU_MEM_RELEASE +==================== + +OpenCAPI devices only. + +Releases NPU memory BAR. + +Parameters +---------- +:: + + uint64_t phb_id + uint32_t bdfn + +``phb_id`` + OPAL ID of PHB + +``bdfn`` + Bus-Device-Function number of OpenCAPI AFU + +Return Values +------------- + +OPAL_SUCCESS + BAR setup completed successfully + +OPAL_PARAMETER + A provided parameter was invalid, or the specified device does not currently + have LPC memory assigned diff --git a/roms/skiboot/doc/opal-api/opal-nvram-read-write-7-8.rst b/roms/skiboot/doc/opal-api/opal-nvram-read-write-7-8.rst new file mode 100644 index 000000000..54cf30a0c --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-nvram-read-write-7-8.rst @@ -0,0 +1,126 @@ +.. _nvram: + +========== +OPAL NVRAM +========== + +The NVRAM requirements for OPAL systems is derived from LoPAPR, and all +requirements listed in it apply to OPAL with some exceptions. Note that +Section 8.4.1.1.3 "OF Configuration Variables" does NOT apply to OPAL, +neither does 8.4.1.2 "DASD Spin-up Control". Not that the RTAS calls of +`nvram-fetch` and `nvram-store` are roughly equivalent to the +:ref:`OPAL_READ_NVRAM` and :ref:`OPAL_WRITE_NVRAM` calls. + +LoPAPR has a minimum requirement of 8KB of Non-Volatile Memory. While this +requirement carries over, it's important to note that historically all OPAL +systems have had roughly 500kb of NVRAM. + +See :ref:`device-tree/ibm,opal/nvram` for details on how NVRAM is represented +in the device tree. It's fairly simple, it looks like this: + +.. code-block:: dts + + nvram { + compatible = "ibm,opal-nvram"; + #bytes = <0x90000>; + }; + + +.. _OPAL_READ_NVRAM: + +OPAL_READ_NVRAM +=============== + +.. code-block:: c + + #define OPAL_READ_NVRAM 7 + + int64_t opal_read_nvram(uint64_t buffer, uint64_t size, uint64_t offset); + +:ref:`OPAL_READ_NVRAM` call requests OPAL to read the data from system NVRAM +memory into a memory buffer. The data at ``offset`` from nvram_image +will be copied to memory ``buffer`` of size ``size``. + +This is a *synchronous* OPAL call, as OPAL will typically read the content of +NVRAM from its storage (typically flash) during boot, so the call duration +should be along the lines of a ``memcpy()`` operation rather than reading +from storage. + + +Parameters +---------- +:: + + uint64_t buffer + uint64_t size + uint64_t offset + +``buffer`` + the data from nvram will be copied to ``buffer`` + +``size`` + the data of size ``size`` will be copied + +``offset`` + the data will be copied from address equal to base ``nvram_image`` plus ``offset`` + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + data from nvram to memory ``buffer`` copied successfully + +:ref:`OPAL_PARAMETER` + a parameter ``offset`` or ``size`` was incorrect + +:ref:`OPAL_HARDWARE` + either nvram is not initialized or permanent error related to nvram hardware. + +.. _OPAL_WRITE_NVRAM: + +OPAL_WRITE_NVRAM +================ + +.. code-block:: c + + #define OPAL_WRITE_NVRAM 8 + + int64_t opal_write_nvram(uint64_t buffer, uint64_t size, uint64_t offset); + +:ref:`OPAL_WRITE_NVRAM` call requests OPAL to write the data to actual system NVRAM memory +from memory ``buffer`` at ``offset``, of size ``size`` + +Parameters +---------- +:: + + uint64_t buffer + uint64_t size + uint64_t offset + +``buffer`` + data from ``buffer`` will be copied to nvram + +``size`` + the data of size ``size`` will be copied + +``offset`` + the data will be copied to address which is equal to base ``nvram_image`` plus ``offset`` + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + data from memory ``buffer`` to actual nvram_image copied successfully + +:ref:`OPAL_PARAMETER` + a parameter ``offset`` or ``size`` was incorrect + +:ref:`OPAL_HARDWARE` + either nvram is not initialized or permanent error related to nvram hardware. + +:ref:`OPAL_BUSY` + OPAL is currently busy, retry the :ref:`OPAL_WRITE_NVRAM` call. + +:ref:`OPAL_BUSY_EVENT` + OPAL is currently busy, call :ref:`OPAL_POLL_EVENTS` and then retry :ref:`OPAL_WRITE_NVRAM` diff --git a/roms/skiboot/doc/opal-api/opal-param-89-90.rst b/roms/skiboot/doc/opal-api/opal-param-89-90.rst new file mode 100644 index 000000000..1d1cedaf6 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-param-89-90.rst @@ -0,0 +1,84 @@ +.. _opal-sysparams: + +========================= +Get/Set System Parameters +========================= + +The usual way for setting system parameters is via IPMI for things controlled +by the service processor, or through NVRAM for things controlled by host +firmware. However, some platforms may have other options not easily (or +possible to be) exposed over IPMI. These OPAL calls will read (and write) +these parameters. + +The list of parameters is set at boot time, and is represented in the device +tree (see :ref:`device-tree/ibm,opal/sysparams` for details). + +Currently only implemented on FSP based systems. + +.. _OPAL_GET_PARAM: + +OPAL_GET_PARAM +============== + +.. code-block:: c + + #define OPAL_GET_PARAM 89 + + int64_t fsp_opal_get_param(uint64_t async_token, uint32_t param_id, + uint64_t buffer, uint64_t length); + +Get the current setting of `param_id`. This is an asynchronous call as OPAL may +need to communicate with a service processor. The `param_id` and `length` are +described in the device tree for each parameter (see +:ref:`device-tree/ibm,opal/sysparams` for details). + +Returns +------- +:ref:`OPAL_HARDWARE` + Hardware issue prevents retreiving parameter. e.g. FSP is offline or + absent. +:ref:`OPAL_PARAMETER` + Invalid `param_id` +:ref:`OPAL_PERMISSION` + Not allowed to read parameter. +:ref:`OPAL_NO_MEM` + Not enough free memory in OPAL to process request. +:ref:`OPAL_INTERNAL_ERROR` + Other internal OPAL error +:ref:`OPAL_ASYNC_COMPLETION` + Request is submitted. + +.. _OPAL_SET_PARAM: + +OPAL_SET_PARAM +============== + +.. code-block:: c + + #define OPAL_SET_PARAM 90 + + int64_t fsp_opal_set_param(uint64_t async_token, uint32_t param_id, + uint64_t buffer, uint64_t length); + + +Write a new setting for `param_id`. This is an asynchronous call as OPAL may +need to communicate with a service processor. The `param_id` and `length` are +described in the device tree for each parameter (see +:ref:`device-tree/ibm,opal/sysparams` for details). + + +Returns +------- +:ref:`OPAL_HARDWARE` + Hardware issue prevents retreiving parameter. e.g. FSP is offline or + absent. +:ref:`OPAL_PARAMETER` + Invalid `param_id` +:ref:`OPAL_PERMISSION` + Not allowed to write parameter. +:ref:`OPAL_NO_MEM` + Not enough free memory in OPAL to process request. +:ref:`OPAL_INTERNAL_ERROR` + Other internal OPAL error +:ref:`OPAL_ASYNC_COMPLETION` + Request is submitted. diff --git a/roms/skiboot/doc/opal-api/opal-pci-config-read-write-13-14-15-16-17-18.rst b/roms/skiboot/doc/opal-api/opal-pci-config-read-write-13-14-15-16-17-18.rst new file mode 100644 index 000000000..8fbb116a4 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-config-read-write-13-14-15-16-17-18.rst @@ -0,0 +1,132 @@ + +.. _OPAL_PCI_CONFIG: + +============================ +OPAL PCI Config Space Access +============================ + +PCI Config space is read or written to through OPAL calls. All of these calls + +.. _OPAL_PCI_CONFIG_return_codes: + +OPAL_PCI_CONFIG_* Return codes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:ref:`OPAL_SUCCESS` + Read/Write operation completed successfully. +:ref:`OPAL_PARAMETER` + Invalid parameter. e.g. invalid `phb_id` or `bus_dev_func`. +:ref:`OPAL_HARDWARE` + Invalid request for the hardware either permanently or in its + current state. Can also be a hardware problem, e.g. fenced or + config access is currently blocked. +:ref:`OPAL_UNSUPPORTED` + Unsupported operation. For example, phb4 doesn't support ASB config + space writes. +Other return codes + Should be handled gracefully. For example, for any return code other than + :ref:`OPAL_SUCCESS`, Linux will return all bits set for the specified size + for a read, and will ignore the error on a write. + +.. _OPAL_PCI_CONFIG_READ_BYTE: + +OPAL_PCI_CONFIG_READ_BYTE +------------------------- + +.. code-block:: c + + #define OPAL_PCI_CONFIG_READ_BYTE 13 + + int64_t opal_pci_config_read_byte(uint64_t phb_id, + uint64_t bus_dev_func, + uint64_t offset, + uint8_t *data); + +Reads a single byte from PCI config space, +see :ref:`OPAL_PCI_CONFIG_return_codes`. + +.. _OPAL_PCI_CONFIG_READ_HALF_WORD: + +OPAL_PCI_CONFIG_READ_HALF_WORD +------------------------------ + +.. code-block:: c + + #define OPAL_PCI_CONFIG_READ_HALF_WORD 14 + + int64_t opal_pci_config_read_half_word(uint64_t phb_id, + uint64_t bus_dev_func, + uint64_t offset, + uint16_t *data); + +Reads a half word (16 bits) from PCI config space, +see :ref:`OPAL_PCI_CONFIG_return_codes`. + +.. _OPAL_PCI_CONFIG_READ_WORD: + +OPAL_PCI_CONFIG_READ_WORD +------------------------- + +.. code-block:: c + + #define OPAL_PCI_CONFIG_READ_WORD 15 + + int64_t opal_pci_config_read_word(uint64_t phb_id, + uint64_t bus_dev_func, + uint64_t offset, + uint32_t *data); + +Reads a word (32 bits) from PCI config space, +see :ref:`OPAL_PCI_CONFIG_return_codes`. + +.. _OPAL_PCI_CONFIG_WRITE_BYTE: + +OPAL_PCI_CONFIG_WRITE_BYTE +-------------------------- + +.. code-block:: c + + #define OPAL_PCI_CONFIG_WRITE_BYTE 16 + + int64_t opal_pci_config_write_byte(uint64_t phb_id, + uint64_t bus_dev_func, + uint64_t offset, + uint8_t data); + +Writes a byte (8 bits) to PCI config space, +see :ref:`OPAL_PCI_CONFIG_return_codes`. + +.. _OPAL_PCI_CONFIG_WRITE_HALF_WORD: + +OPAL_PCI_CONFIG_WRITE_HALF_WORD +------------------------------- + +.. code-block:: c + + #define OPAL_PCI_CONFIG_WRITE_HALF_WORD 17 + + int64_t opal_pci_config_read_half_word(uint64_t phb_id, + uint64_t bus_dev_func, + uint64_t offset, + uint16_t data); + +Writes a half word (16 bits) to PCI config space, +see :ref:`OPAL_PCI_CONFIG_return_codes`. + +.. _OPAL_PCI_CONFIG_WRITE_WORD: + +OPAL_PCI_CONFIG_WRITE_WORD +-------------------------- + +.. code-block:: c + + #define OPAL_PCI_CONFIG_WRITE_WORD 18 + + int64_t opal_pci_config_read_word(uint64_t phb_id, + uint64_t bus_dev_func, + uint64_t offset, + uint32_t data); + +Writes a word (32 bits) to PCI config space, +see :ref:`OPAL_PCI_CONFIG_return_codes`. + diff --git a/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-clear-26.rst b/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-clear-26.rst new file mode 100644 index 000000000..af796f0f3 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-clear-26.rst @@ -0,0 +1,33 @@ +.. _OPAL_PCI_EEH_FREEZE_CLEAR: + +OPAL_PCI_EEH_FREEZE_CLEAR +========================= + +.. code-block:: c + + #define OPAL_PCI_EEH_FREEZE_CLEAR 26 + + enum OpalEehFreezeActionToken { + OPAL_EEH_ACTION_CLEAR_FREEZE_MMIO = 1, + OPAL_EEH_ACTION_CLEAR_FREEZE_DMA = 2, + OPAL_EEH_ACTION_CLEAR_FREEZE_ALL = 3, + + OPAL_EEH_ACTION_SET_FREEZE_MMIO = 1, + OPAL_EEH_ACTION_SET_FREEZE_DMA = 2, + OPAL_EEH_ACTION_SET_FREEZE_ALL = 3 + }; + + int64_t opal_pci_eeh_freeze_clear(uint64_t phb_id, uint64_t pe_number, uint64_t eeh_action_token); + + +Returns +------- +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_PARAMETER` + Invalid PHB +:ref:`OPAL_UNSUPPORTED` + PHB doesn't support this operation. +:ref:`OPAL_HARDWARE` + Hardware issue prevents completing operation. OPAL may have detected it + being broken. diff --git a/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-set-97.rst b/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-set-97.rst new file mode 100644 index 000000000..b601ef689 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-set-97.rst @@ -0,0 +1,29 @@ +.. _OPAL_PCI_EEH_FREEZE_SET: + +OPAL_PCI_EEH_FREEZE_SET +======================= + +.. code-block:: c + + #define OPAL_PCI_EEH_FREEZE_SET 97 + + enum OpalEehFreezeActionToken { + OPAL_EEH_ACTION_CLEAR_FREEZE_MMIO = 1, + OPAL_EEH_ACTION_CLEAR_FREEZE_DMA = 2, + OPAL_EEH_ACTION_CLEAR_FREEZE_ALL = 3, + + OPAL_EEH_ACTION_SET_FREEZE_MMIO = 1, + OPAL_EEH_ACTION_SET_FREEZE_DMA = 2, + OPAL_EEH_ACTION_SET_FREEZE_ALL = 3 + }; + + int64_t opal_pci_eeh_freeze_set(uint64_t phb_id, uint64_t pe_number, uint64_t eeh_action_token); + +Returns +------- +:ref:`OPAL_PARAMETER` + Invalid parameter. +:ref:`OPAL_UNSUPPORTED` + Unsupported operation +:ref:`OPAL_HARDWARE` + Hardware in a bad state. diff --git a/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-status-23.rst b/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-status-23.rst new file mode 100644 index 000000000..94b7245b4 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-eeh-freeze-status-23.rst @@ -0,0 +1,71 @@ +.. _OPAL_PCI_EEH_FREEZE_STATUS: + +OPAL_PCI_EEH_FREEZE_STATUS +========================== + +.. code-block:: c + + #define OPAL_PCI_EEH_FREEZE_STATUS 23 + + enum OpalFreezeState { + OPAL_EEH_STOPPED_NOT_FROZEN = 0, + OPAL_EEH_STOPPED_MMIO_FREEZE = 1, + OPAL_EEH_STOPPED_DMA_FREEZE = 2, + OPAL_EEH_STOPPED_MMIO_DMA_FREEZE = 3, + OPAL_EEH_STOPPED_RESET = 4, + OPAL_EEH_STOPPED_TEMP_UNAVAIL = 5, + OPAL_EEH_STOPPED_PERM_UNAVAIL = 6 + }; + + enum OpalPciStatusToken { + OPAL_EEH_NO_ERROR = 0, + OPAL_EEH_IOC_ERROR = 1, + OPAL_EEH_PHB_ERROR = 2, + OPAL_EEH_PE_ERROR = 3, + OPAL_EEH_PE_MMIO_ERROR = 4, + OPAL_EEH_PE_DMA_ERROR = 5 + }; + + int64_t opal_pci_eeh_freeze_status(uint64_t phb_id, uint64_t pe_number, + uint8_t *freeze_state, + uint16_t *pci_error_type, + uint64_t *phb_status); + +.. note:: The ``phb_status`` parameter is deprecated as + of :ref:`skiboot-6.3-rc1`. Linux only ever passed in NULL, + and this was safe. Supplying a pointer was previously *unsafe*. + Always pass NULL. + +.. note:: There once was a :ref:`OPAL_PCI_EEH_FREEZE_STATUS2` call, but it + was introduced in firmware and never used by any OS, so it has since + been removed from OPAL. + +Returns +------- + +:ref:`OPAL_PARAMETER` + Invalid address or PHB. +:ref:`OPAL_UNSUPPORTED` + PHB does not support this operation. +:ref:`OPAL_HARDWARE` + Hardware prohibited getting status, OPAL maybe marked it as broken. +:ref:`OPAL_SUCCESS` + Retreived status. + +.. _OPAL_PCI_EEH_FREEZE_STATUS2: + +OPAL_PCI_EEH_FREEZE_STATUS2 +=========================== + +.. code-block:: c + + #define OPAL_PCI_EEH_FREEZE_STATUS2 61 + +Use :ref:`OPAL_PCI_EEH_FREEZE_STATUS` instead of this (removed) call. + +While you'd think that a call introduced in the first public OPAL release would +have been used somewhere, it seems that all existing code has only ever used +:ref:`OPAL_PCI_EEH_FREEZE_STATUS` over :ref:`OPAL_PCI_EEH_FREEZE_STATUS2`. + +This call has been removed as of :ref:`skiboot-6.4` as it has literally never +been used. diff --git a/roms/skiboot/doc/opal-api/opal-pci-err-inject-96.rst b/roms/skiboot/doc/opal-api/opal-pci-err-inject-96.rst new file mode 100644 index 000000000..0820e9001 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-err-inject-96.rst @@ -0,0 +1,54 @@ +.. _OPAL_PCI_ERR_INJECT: + +OPAL_PCI_ERR_INJECT +=================== + +.. code-block:: c + + #define OPAL_PCI_ERR_INJECT 96 + + enum OpalErrinjectType { + OPAL_ERR_INJECT_TYPE_IOA_BUS_ERR = 0, + OPAL_ERR_INJECT_TYPE_IOA_BUS_ERR64 = 1, + }; + + enum OpalErrinjectFunc { + /* IOA bus specific errors */ + OPAL_ERR_INJECT_FUNC_IOA_LD_MEM_ADDR = 0, + OPAL_ERR_INJECT_FUNC_IOA_LD_MEM_DATA = 1, + OPAL_ERR_INJECT_FUNC_IOA_LD_IO_ADDR = 2, + OPAL_ERR_INJECT_FUNC_IOA_LD_IO_DATA = 3, + OPAL_ERR_INJECT_FUNC_IOA_LD_CFG_ADDR = 4, + OPAL_ERR_INJECT_FUNC_IOA_LD_CFG_DATA = 5, + OPAL_ERR_INJECT_FUNC_IOA_ST_MEM_ADDR = 6, + OPAL_ERR_INJECT_FUNC_IOA_ST_MEM_DATA = 7, + OPAL_ERR_INJECT_FUNC_IOA_ST_IO_ADDR = 8, + OPAL_ERR_INJECT_FUNC_IOA_ST_IO_DATA = 9, + OPAL_ERR_INJECT_FUNC_IOA_ST_CFG_ADDR = 10, + OPAL_ERR_INJECT_FUNC_IOA_ST_CFG_DATA = 11, + OPAL_ERR_INJECT_FUNC_IOA_DMA_RD_ADDR = 12, + OPAL_ERR_INJECT_FUNC_IOA_DMA_RD_DATA = 13, + OPAL_ERR_INJECT_FUNC_IOA_DMA_RD_MASTER = 14, + OPAL_ERR_INJECT_FUNC_IOA_DMA_RD_TARGET = 15, + OPAL_ERR_INJECT_FUNC_IOA_DMA_WR_ADDR = 16, + OPAL_ERR_INJECT_FUNC_IOA_DMA_WR_DATA = 17, + OPAL_ERR_INJECT_FUNC_IOA_DMA_WR_MASTER = 18, + OPAL_ERR_INJECT_FUNC_IOA_DMA_WR_TARGET = 19, + }; + + int64_t opal_pci_err_inject(uint64_t phb_id, uint64_t pe_number, + uint32_t type, uint32_t func, + uint64_t addr, uint64_t mask); + +Inject an error, used to test OS and OPAL EEH handling. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Error injected successfully. +:ref:`OPAL_PARAMETER` + Invalid argument. +:ref:`OPAL_UNSUPPORTED` + PHB doesn't support error injection or the specific error attempting to + be injected. diff --git a/roms/skiboot/doc/opal-api/opal-pci-get-hub-diag-data-50.rst b/roms/skiboot/doc/opal-api/opal-pci-get-hub-diag-data-50.rst new file mode 100644 index 000000000..7ee98063e --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-get-hub-diag-data-50.rst @@ -0,0 +1,34 @@ +.. _OPAL_PCI_GET_HUB_DIAG_DATA: + +OPAL_PCI_GET_HUB_DIAG_DATA +========================== + +.. code-block:: c + + #define OPAL_PCI_GET_HUB_DIAG_DATA 50 + + int64_t opal_pci_get_hub_diag_data(uint64_t hub_id, void *diag_buffer, uint64_t diag_buffer_len); + +Fetch diagnostic data for an IO hub. This was only implemented for hardware +specific to POWER7 systems, something that was only ever available +internally to IBM for development purposes. + +It is currently not used. + +If :ref:`OPAL_PCI_NEXT_ERROR` error type is `OPAL_EEH_IOC_ERROR` and severity +is `OPAL_EEH_SEV_INF`, then the OS should call :ref:`OPAL_PCI_GET_HUB_DIAG_DATA` +to retreive diagnostic data to log appropriately. + +Returns +------- +:ref:`OPAL_SUCCESS` + Diagnostic data copied successfully +:ref:`OPAL_PARAMETER` + Invalid address, invalid hub ID, or insufficient space in buffer for + diagnostic data. +:ref:`OPAL_UNSUPPORTED` + hub doesn't support retreiving diagnostic data. +:ref:`OPAL_CLOSED` + No pending error. +:ref:`OPAL_INTERNAL_ERROR` + Something went wrong. diff --git a/roms/skiboot/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst b/roms/skiboot/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst new file mode 100644 index 000000000..ac98bc2a7 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst @@ -0,0 +1,271 @@ +.. _OPAL_PCI_GET_PHB_DIAG_DATA2: + +OPAL_PCI_GET_PHB_DIAG_DATA2 +=========================== + +.. code-block:: c + + #define OPAL_PCI_GET_PHB_DIAG_DATA2 64 + + /** + * This structure defines the overlay which will be used to store PHB error + * data upon request. + */ + enum { + OPAL_PHB_ERROR_DATA_VERSION_1 = 1, + }; + + enum { + OPAL_PHB_ERROR_DATA_TYPE_P7IOC = 1, + OPAL_PHB_ERROR_DATA_TYPE_PHB3 = 2, + OPAL_PHB_ERROR_DATA_TYPE_PHB4 = 3 + }; + + enum { + OPAL_P7IOC_NUM_PEST_REGS = 128, + OPAL_PHB3_NUM_PEST_REGS = 256, + OPAL_PHB4_NUM_PEST_REGS = 512 + }; + + struct OpalIoPhbErrorCommon { + __be32 version; + __be32 ioType; + __be32 len; + }; + + struct OpalIoP7IOCPhbErrorData { + struct OpalIoPhbErrorCommon common; + + __be32 brdgCtl; + + // P7IOC utl regs + __be32 portStatusReg; + __be32 rootCmplxStatus; + __be32 busAgentStatus; + + // P7IOC cfg regs + __be32 deviceStatus; + __be32 slotStatus; + __be32 linkStatus; + __be32 devCmdStatus; + __be32 devSecStatus; + + // cfg AER regs + __be32 rootErrorStatus; + __be32 uncorrErrorStatus; + __be32 corrErrorStatus; + __be32 tlpHdr1; + __be32 tlpHdr2; + __be32 tlpHdr3; + __be32 tlpHdr4; + __be32 sourceId; + + __be32 rsv3; + + // Record data about the call to allocate a buffer. + __be64 errorClass; + __be64 correlator; + + //P7IOC MMIO Error Regs + __be64 p7iocPlssr; // n120 + __be64 p7iocCsr; // n110 + __be64 lemFir; // nC00 + __be64 lemErrorMask; // nC18 + __be64 lemWOF; // nC40 + __be64 phbErrorStatus; // nC80 + __be64 phbFirstErrorStatus; // nC88 + __be64 phbErrorLog0; // nCC0 + __be64 phbErrorLog1; // nCC8 + __be64 mmioErrorStatus; // nD00 + __be64 mmioFirstErrorStatus; // nD08 + __be64 mmioErrorLog0; // nD40 + __be64 mmioErrorLog1; // nD48 + __be64 dma0ErrorStatus; // nD80 + __be64 dma0FirstErrorStatus; // nD88 + __be64 dma0ErrorLog0; // nDC0 + __be64 dma0ErrorLog1; // nDC8 + __be64 dma1ErrorStatus; // nE00 + __be64 dma1FirstErrorStatus; // nE08 + __be64 dma1ErrorLog0; // nE40 + __be64 dma1ErrorLog1; // nE48 + __be64 pestA[OPAL_P7IOC_NUM_PEST_REGS]; + __be64 pestB[OPAL_P7IOC_NUM_PEST_REGS]; + }; + + struct OpalIoPhb3ErrorData { + struct OpalIoPhbErrorCommon common; + + __be32 brdgCtl; + + /* PHB3 UTL regs */ + __be32 portStatusReg; + __be32 rootCmplxStatus; + __be32 busAgentStatus; + + /* PHB3 cfg regs */ + __be32 deviceStatus; + __be32 slotStatus; + __be32 linkStatus; + __be32 devCmdStatus; + __be32 devSecStatus; + + /* cfg AER regs */ + __be32 rootErrorStatus; + __be32 uncorrErrorStatus; + __be32 corrErrorStatus; + __be32 tlpHdr1; + __be32 tlpHdr2; + __be32 tlpHdr3; + __be32 tlpHdr4; + __be32 sourceId; + + __be32 rsv3; + + /* Record data about the call to allocate a buffer */ + __be64 errorClass; + __be64 correlator; + + /* PHB3 MMIO Error Regs */ + __be64 nFir; /* 000 */ + __be64 nFirMask; /* 003 */ + __be64 nFirWOF; /* 008 */ + __be64 phbPlssr; /* 120 */ + __be64 phbCsr; /* 110 */ + __be64 lemFir; /* C00 */ + __be64 lemErrorMask; /* C18 */ + __be64 lemWOF; /* C40 */ + __be64 phbErrorStatus; /* C80 */ + __be64 phbFirstErrorStatus; /* C88 */ + __be64 phbErrorLog0; /* CC0 */ + __be64 phbErrorLog1; /* CC8 */ + __be64 mmioErrorStatus; /* D00 */ + __be64 mmioFirstErrorStatus; /* D08 */ + __be64 mmioErrorLog0; /* D40 */ + __be64 mmioErrorLog1; /* D48 */ + __be64 dma0ErrorStatus; /* D80 */ + __be64 dma0FirstErrorStatus; /* D88 */ + __be64 dma0ErrorLog0; /* DC0 */ + __be64 dma0ErrorLog1; /* DC8 */ + __be64 dma1ErrorStatus; /* E00 */ + __be64 dma1FirstErrorStatus; /* E08 */ + __be64 dma1ErrorLog0; /* E40 */ + __be64 dma1ErrorLog1; /* E48 */ + __be64 pestA[OPAL_PHB3_NUM_PEST_REGS]; + __be64 pestB[OPAL_PHB3_NUM_PEST_REGS]; + }; + + struct OpalIoPhb4ErrorData { + struct OpalIoPhbErrorCommon common; + + __be32 brdgCtl; + + /* XXX missing UTL registers? */ + + /* PHB4 cfg regs */ + __be32 deviceStatus; + __be32 slotStatus; + __be32 linkStatus; + __be32 devCmdStatus; + __be32 devSecStatus; + + /* cfg AER regs */ + __be32 rootErrorStatus; + __be32 uncorrErrorStatus; + __be32 corrErrorStatus; + __be32 tlpHdr1; + __be32 tlpHdr2; + __be32 tlpHdr3; + __be32 tlpHdr4; + __be32 sourceId; + + /* PHB4 ETU Error Regs */ + __be64 nFir; /* 000 */ + __be64 nFirMask; /* 003 */ + __be64 nFirWOF; /* 008 */ + __be64 phbPlssr; /* 120 */ + __be64 phbCsr; /* 110 */ + __be64 lemFir; /* C00 */ + __be64 lemErrorMask; /* C18 */ + __be64 lemWOF; /* C40 */ + __be64 phbErrorStatus; /* C80 */ + __be64 phbFirstErrorStatus; /* C88 */ + __be64 phbErrorLog0; /* CC0 */ + __be64 phbErrorLog1; /* CC8 */ + __be64 phbTxeErrorStatus; /* D00 */ + __be64 phbTxeFirstErrorStatus; /* D08 */ + __be64 phbTxeErrorLog0; /* D40 */ + __be64 phbTxeErrorLog1; /* D48 */ + __be64 phbRxeArbErrorStatus; /* D80 */ + __be64 phbRxeArbFirstErrorStatus; /* D88 */ + __be64 phbRxeArbErrorLog0; /* DC0 */ + __be64 phbRxeArbErrorLog1; /* DC8 */ + __be64 phbRxeMrgErrorStatus; /* E00 */ + __be64 phbRxeMrgFirstErrorStatus; /* E08 */ + __be64 phbRxeMrgErrorLog0; /* E40 */ + __be64 phbRxeMrgErrorLog1; /* E48 */ + __be64 phbRxeTceErrorStatus; /* E80 */ + __be64 phbRxeTceFirstErrorStatus; /* E88 */ + __be64 phbRxeTceErrorLog0; /* EC0 */ + __be64 phbRxeTceErrorLog1; /* EC8 */ + + /* PHB4 REGB Error Regs */ + __be64 phbPblErrorStatus; /* 1900 */ + __be64 phbPblFirstErrorStatus; /* 1908 */ + __be64 phbPblErrorLog0; /* 1940 */ + __be64 phbPblErrorLog1; /* 1948 */ + __be64 phbPcieDlpErrorLog1; /* 1AA0 */ + __be64 phbPcieDlpErrorLog2; /* 1AA8 */ + __be64 phbPcieDlpErrorStatus; /* 1AB0 */ + __be64 phbRegbErrorStatus; /* 1C00 */ + __be64 phbRegbFirstErrorStatus; /* 1C08 */ + __be64 phbRegbErrorLog0; /* 1C40 */ + __be64 phbRegbErrorLog1; /* 1C48 */ + + __be64 pestA[OPAL_PHB4_NUM_PEST_REGS]; + __be64 pestB[OPAL_PHB4_NUM_PEST_REGS]; + }; + + int64_t opal_pci_get_phb_diag_data2(uint64_t phb_id, void *diag_buffer, uint64_t diag_buffer_len); + +Get PCI diagnostic data from a given PHB. Each PHB present in the device tree +has a ``ibm,phb-diag-data-size`` property which is the size of the diagnostic +data structure that can be returned. + +Each PHB generation has a different structure for diagnostic data, and the +small common structure will allow the OS to work out what format the data +is coming in. + +In future, it's possible that the format will change to be more flexible, and +require less OS support. + +Parameters +---------- +``uint64_t phb_id`` + the ID of the PHB you want to retrieve data from + +``void *diag_buffer`` + an allocated buffer to store diag data in + +``uint64_t diag_buffer_len`` + size in bytes of the diag buffer + +Calling +------- + +Retrieve the PHB's diagnostic data. The diagnostic data is stored in the +buffer pointed by @diag_buffer. Different PHB versions will store different +diagnostics, defined in include/opal-api.h as ``struct OpalIo<PHBVer>ErrorData``. + +:ref:`OPAL_PCI_GET_PHB_DIAG_DATA` is deprecated and +:ref:`OPAL_PCI_GET_PHB_DIAG_DATA2` should be used instead. + +Return Codes +------------ +:ref:`OPAL_SUCCESS` + Diagnostic data has been retrieved and stored successfully +:ref:`OPAL_PARAMETER` + The given buffer is too small to store the diagnostic data +:ref:`OPAL_HARDWARE` + The PHB is in a broken state and its data cannot be retreived +:ref:`OPAL_UNSUPPORTED` + Diagnostic data is not implemented for this PHB type diff --git a/roms/skiboot/doc/opal-api/opal-pci-get-power-state-120.rst b/roms/skiboot/doc/opal-api/opal-pci-get-power-state-120.rst new file mode 100644 index 000000000..fa0375d83 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-get-power-state-120.rst @@ -0,0 +1,37 @@ +.. _OPAL_PCI_GET_POWER_STATE: + +OPAL_PCI_GET_POWER_STATE +======================== + +.. code-block:: c + + #define OPAL_PCI_GET_POWER_STATE 120 + + int64_t opal_pci_get_power_state(uint64_t id, uint64_t data); + +Get PCI slot power state + +Parameter +--------- + +``uint64_t id`` + PCI slot ID + +``uint64_t data`` + memory buffer pointer for power state + +Calling +------- + +Retrieve PCI slot's power state. The retrieved power state is stored +in buffer pointed by @data. + +Return Codes +------------ + +:ref:`OPAL_SUCCESS` + PCI slot's power state is retrieved successfully +:ref:`OPAL_PARAMETER` + The indicated PCI slot isn't found +:ref:`OPAL_UNSUPPORTED` + Power state retrieval not supported on the PCI slot diff --git a/roms/skiboot/doc/opal-api/opal-pci-get-presence-state-119.rst b/roms/skiboot/doc/opal-api/opal-pci-get-presence-state-119.rst new file mode 100644 index 000000000..b31df47a8 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-get-presence-state-119.rst @@ -0,0 +1,39 @@ +.. _OPAL_PCI_GET_PRESENCE_STATE: + +OPAL_PCI_GET_PRESENCE_STATE +=========================== + +.. code-block: c + + #define OPAL_PCI_GET_PRESENCE_STATE 119 + + int64_t opal_pci_get_presence_state(uint64_t id, uint64_t data); + +Get PCI slot presence state + +Parameters +---------- + +``uint64_t id`` + PCI slot ID + +``uint64_t data`` + memory buffer pointer for presence state + +Calling +------- + +Retrieve PCI slot's presence state. The detected presence means there are +adapters inserted to the PCI slot. Otherwise, the PCI slot is regarded as +an empty one. The typical use is to ensure there are adapters existing +before probing the PCI slot in PCI hot add path. The retrieved presence +state is stored in buffer pointed by @data. + +Return Codes +------------ +:ref:`OPAL_SUCCESS` + PCI slot's presence state is retrieved successfully +:ref:`OPAL_PARAMETER` + The indicated PCI slot isn't found +:ref:`OPAL_UNSUPPORTED` + Presence retrieval not supported on the PCI slot diff --git a/roms/skiboot/doc/opal-api/opal-pci-get-set-pbcq-tunnel-bar-164-165.rst b/roms/skiboot/doc/opal-api/opal-pci-get-set-pbcq-tunnel-bar-164-165.rst new file mode 100644 index 000000000..dcbd62e31 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-get-set-pbcq-tunnel-bar-164-165.rst @@ -0,0 +1,70 @@ +.. _OPAL_PCI_GET_PBCQ_TUNNEL_BAR: + +OPAL_PCI_GET_PBCQ_TUNNEL_BAR +============================ + +.. code-block:: c + + #define OPAL_PCI_GET_PBCQ_TUNNEL_BAR 164 + + int64_t opal_pci_get_pbcq_tunnel_bar(uint64_t phb_id, uint64_t *addr); + +The host calls this function to read the address out of the PBCQ Tunnel +Bar register. + +Parameters +---------- + +``phb_id`` + The value from the PHB node ibm,opal-phbid property for the device. + +``addr`` + A pointer to where the address stored in the PBCQ Tunnel Bar register + will be copied. + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + Operation was successful +:ref:`OPAL_PARAMETER` + Invalid PHB or addr parameter +:ref:`OPAL_UNSUPPORTED` + Not supported by hardware + +.. _OPAL_PCI_SET_PBCQ_TUNNEL_BAR: + +OPAL_PCI_SET_PBCQ_TUNNEL_BAR +============================ + +.. code-block:: c + + #define OPAL_PCI_SET_PBCQ_TUNNEL_BAR 165 + + int64_t opal_pci_set_pbcq_tunnel_bar(uint64_t phb_id, uint64_t addr); + +The host calls this function to set the PBCQ Tunnel Bar register. + +Parameters +---------- + +`phb_id` + The value from the PHB node ibm,opal-phbid property for the device. + +`addr` + The value of the address chosen for the PBCQ Tunnel Bar register. + If the address is 0, then the PBCQ Tunnel Bar register will be reset. + It the address is non-zero, then the PBCQ Tunnel Bar register will be + set with :: + + Bit[0:42] Bit[8:50] of the address + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + Operation was successful +:ref:`OPAL_PARAMETER` + Invalid PHB or addr parameter +:ref:`OPAL_UNSUPPORTED` + Not supported by hardware diff --git a/roms/skiboot/doc/opal-api/opal-pci-map-pe-dma-window-44.rst b/roms/skiboot/doc/opal-api/opal-pci-map-pe-dma-window-44.rst new file mode 100644 index 000000000..9450629f0 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-map-pe-dma-window-44.rst @@ -0,0 +1,107 @@ +.. _OPAL_PCI_MAP_PE_DMA_WINDOW: + +OPAL_PCI_MAP_PE_DMA_WINDOW +========================== + +.. code-block:: c + + #define OPAL_PCI_MAP_PE_DMA_WINDOW 44 + + static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, + uint64_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: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->map_pe_dma_window) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst b/roms/skiboot/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst new file mode 100644 index 000000000..87395d1ee --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst @@ -0,0 +1,55 @@ +.. _OPAL_PCI_MAP_PE_DMA_WINDOW_REAL: + +OPAL_PCI_MAP_PE_DMA_WINDOW_REAL +=============================== + +.. code-block:: c + + #define OPAL_PCI_MAP_PE_DMA_WINDOW_REAL 45 + + int64_t opal_pci_map_pe_dma_window_real(uint64_t phb_id, + uint64_t pe_number, + uint16_t window_id, + uint64_t pci_start_addr, + uint64_t pci_mem_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 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 :ref:`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/roms/skiboot/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst b/roms/skiboot/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst new file mode 100644 index 000000000..a84da18dd --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst @@ -0,0 +1,53 @@ +.. _OPAL_PCI_MAP_PE_MMIO_WINDOW: + +OPAL_PCI_MAP_PE_MMIO_WINDOW +=========================== + +.. code-block:: c + + #define OPAL_PCI_MAP_PE_MMIO_WINDOW 29 + + int64_t opal_pci_map_pe_mmio_window(uint64_t phb_id, + uint64_t pe_number, + uint16_t window_type, + uint16_t window_num, + uint16_t segment_num); + +.. note:: Appears to be POWER7 p7ioc specific. Likely to be removed soon. + +**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: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->map_pe_mmio_window) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-msi-eoi-63.rst b/roms/skiboot/doc/opal-api/opal-pci-msi-eoi-63.rst new file mode 100644 index 000000000..24bdb789d --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-msi-eoi-63.rst @@ -0,0 +1,24 @@ +.. _OPAL_PCI_MSI_EOI: + +OPAL_PCI_MSI_EOI +================ + +.. code-block:: c + + #define OPAL_PCI_MSI_EOI 63 + + int64_t opal_pci_msi_eoi(uint64_t phb_id, uint32_t hwirq); + +Only required on PHB3 (POWER8) based systems. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_PARAMETER` + Invalid PHB id or hwirq. +:ref:`OPAL_HARDWARE` + Hardware or configuration issue. +:ref:`OPAL_UNSUPPORTED` + Unsupported on this PHB. diff --git a/roms/skiboot/doc/opal-api/opal-pci-next-error-60.rst b/roms/skiboot/doc/opal-api/opal-pci-next-error-60.rst new file mode 100644 index 000000000..1453835b2 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-next-error-60.rst @@ -0,0 +1,41 @@ +.. _OPAL_PCI_NEXT_ERROR: + +OPAL_PCI_NEXT_ERROR +=================== + +.. code-block:: c + + #define OPAL_PCI_NEXT_ERROR 60 + + enum OpalPciStatusToken { + OPAL_EEH_NO_ERROR = 0, + OPAL_EEH_IOC_ERROR = 1, + OPAL_EEH_PHB_ERROR = 2, + OPAL_EEH_PE_ERROR = 3, + OPAL_EEH_PE_MMIO_ERROR = 4, + OPAL_EEH_PE_DMA_ERROR = 5 + }; + + enum OpalPciErrorSeverity { + OPAL_EEH_SEV_NO_ERROR = 0, + OPAL_EEH_SEV_IOC_DEAD = 1, + OPAL_EEH_SEV_PHB_DEAD = 2, + OPAL_EEH_SEV_PHB_FENCED = 3, + OPAL_EEH_SEV_PE_ER = 4, + OPAL_EEH_SEV_INF = 5 + }; + + int64_t opal_pci_next_error(uint64_t phb_id, uint64_t *first_frozen_pe, + uint16_t *pci_error_type, uint16_t *severity); + +Retreives details of a PCIe error. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Successfully filled `pci_error_type` and `severity` with error details. +:ref:`OPAL_UNSUPPORTED` + Unsupported operation on this PHB. +:ref:`OPAL_PARAMETER` + Invalid phb_id, or address for other arguments. diff --git a/roms/skiboot/doc/opal-api/opal-pci-phb-mmio-enable-27.rst b/roms/skiboot/doc/opal-api/opal-pci-phb-mmio-enable-27.rst new file mode 100644 index 000000000..e3ca02f57 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-phb-mmio-enable-27.rst @@ -0,0 +1,54 @@ +.. _OPAL_PCI_PHB_MMIO_ENABLE: + +OPAL_PCI_PHB_MMIO_ENABLE +======================== + +.. code-block:: c + + #define OPAL_PCI_PHB_MMIO_ENABLE 27 + + int64_t opal_pci_phb_mmio_enable(uint64_t phb_id, uint16_t window_type, + uint16_t window_num, uint16_t enable); + +.. note:: Appears to be POWER7 p7ioc specific. Likely to be removed soon. + +**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 enable or disable PHB decode of the PCI IO +and Memory address spaces below that PHB. Window_num selects an mmio window +within that address space. Enable set to '1' enables the PHB to decode and +forward system real addresses to PCI memory, while enable set to '0' disables +PHB decode and forwarding for the address range defined in a particular MMIO +window. + +Not all PHB hardware may support disabling some or all MMIO windows. OPAL +returns :ref:`OPAL_UNSUPPORTED` if called to disable an MMIO window for which +hardware does not support disable. KVM may call this function for all MMIO +windows and ignore the opal_unsuppsorted return code so long as KVM has +disabled MMIO to all downstream PCI devices and assured that KVM and OS guest +partitions cannot issue CI loads/stores to these address spaces from the +processor (e.g.,via HPT). + +OPAL returns :ref:`OPAL_SUCCESS` for calls to OPAL to enable them for PHBs that do +not support disable. + +``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 + + '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 + +``enable`` + specifies to enable or disable this MMIO window. diff --git a/roms/skiboot/doc/opal-api/opal-pci-poll-62.rst b/roms/skiboot/doc/opal-api/opal-pci-poll-62.rst new file mode 100644 index 000000000..298aa6d36 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-poll-62.rst @@ -0,0 +1,18 @@ +.. _OPAL_PCI_POLL: + +OPAL_PCI_POLL +============= + +.. code-block:: c + + #define OPAL_PCI_POLL 62 + + int64_t opal_pci_poll(uint64_t id); + +Crank the state machine for the PHB id. Returns how many milliseconds for +the caller to sleep. + +Returns +------- + +Milliseconds for the caller to sleep for, error code, or :ref:`OPAL_SUCCESS`. diff --git a/roms/skiboot/doc/opal-api/opal-pci-reinit-53.rst b/roms/skiboot/doc/opal-api/opal-pci-reinit-53.rst new file mode 100644 index 000000000..677bd2343 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-reinit-53.rst @@ -0,0 +1,31 @@ +.. _OPAL_PCI_REINIT: + +OPAL_PCI_REINIT +=============== + +.. code-block:: c + + #define OPAL_PCI_REINIT 53 + + enum OpalPciReinitScope { + /* + * Note: we chose values that do not overlap + * OpalPciResetScope as OPAL v2 used the same + * enum for both + */ + OPAL_REINIT_PCI_DEV = 1000 + }; + + int64_t opal_pci_reinit(uint64_t phb_id, uint64_t reinit_scope, uint64_t data); + +.. note:: Much glory awaits the one who fills in this documentation. + +Returns +------- + +:ref:`OPAL_PARAMETER` + Invalid PHB, scope, or device. +:ref:`OPAL_UNSUPPORTED` + Operation unsupported +:ref:`OPAL_HARDWARE` + Some hardware issue prevented the reinit. diff --git a/roms/skiboot/doc/opal-api/opal-pci-reset-49.rst b/roms/skiboot/doc/opal-api/opal-pci-reset-49.rst new file mode 100644 index 000000000..85acc0bb7 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-reset-49.rst @@ -0,0 +1,42 @@ +.. _OPAL_PCI_RESET: + +OPAL_PCI_RESET +============== + +.. code-block:: c + + #define OPAL_PCI_RESET 49 + + enum OpalPciResetScope { + OPAL_RESET_PHB_COMPLETE = 1, + OPAL_RESET_PCI_LINK = 2, + OPAL_RESET_PHB_ERROR = 3, + OPAL_RESET_PCI_HOT = 4, + OPAL_RESET_PCI_FUNDAMENTAL = 5, + OPAL_RESET_PCI_IODA_TABLE = 6 + }; + + enum OpalPciResetState { + OPAL_DEASSERT_RESET = 0, + OPAL_ASSERT_RESET = 1 + }; + + int64_t opal_pci_reset(uint64_t id, uint8_t reset_scope, uint8_t assert_state); + +Kick off the requested PCI reset operation. This starts a state machine off to +perform the requested operation. This call will return how many milliseconds to +wait before calling back into :ref:`OPAL_PCI_POLL`. An OS can +call :ref:`OPAL_PCI_POLL` earlier, but it is unlikely any progress will have +been made. + + +Returns +------- + +:ref:`OPAL_PARAMETER` + Invalid ``id``, ``reset_scope``, or ``assert_state``. +:ref:`OPAL_UNSUPPORTED` + Operation is unsupported on ``id``. +value > 0 + How many ms to wait for the state machine to crank. + Call :ref:`OPAL_PCI_POLL` to crank the state machine further. diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-mve-33.rst b/roms/skiboot/doc/opal-api/opal-pci-set-mve-33.rst new file mode 100644 index 000000000..b0c7e6111 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-mve-33.rst @@ -0,0 +1,43 @@ +.. _OPAL_PCI_SET_MVE: + +OPAL_PCI_SET_MVE +================ + +.. code-block:: c + + #define OPAL_PCI_SET_MVE 33 + + int64_t opal_pci_set_mve(uint64_t phb_id, uint32_t mve_number, uint64_t pe_number); + +**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 bind a PE to an MSI Validation Table Entry +(MVE) in the PHB. The MVE compares the MSI requester (RID) to a PE RID, +including within the XIVE, to validate that the requester is authorized to +signal an interrupt to the associated DMA address for a message value that +selects a particular XIVE. + +``phb_id`` + is the value from the PHB node ibm,opal-phbid property. + +``mve_number`` + is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1 + +``pe_number`` + is the index of a PE, from 0 to ibm,opal-num-pes minus 1. + +This call maps an MVE to a PE and PE RID domain. OPAL uses the PELT to +determine the PE domain. OPAL treats this call as a NOP for IODA2 PHBs +and returns a status of OPAL_SUCCESS. + + +Return value: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_mve) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-mve-enable-34.rst b/roms/skiboot/doc/opal-api/opal-pci-set-mve-enable-34.rst new file mode 100644 index 000000000..55bf10a08 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-mve-enable-34.rst @@ -0,0 +1,44 @@ +.. _OPAL_PCI_SET_MVE_ENABLE: + +OPAL_PCI_SET_MVE_ENABLE +======================= + + +.. code-block:: c + + #define OPAL_PCI_SET_MVE_ENABLE 34 + + int64_t opal_pci_set_mve_enable(uint64_t phb_id, uint32_t mve_number, uint32_t state); + + enum OpalMveEnableAction { + OPAL_DISABLE_MVE = 0, + OPAL_ENABLE_MVE = 1 + }; + +**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 enable or disable an MVE to respond to an MSI +DMA address and message data value. + +``phb_id`` + is the value from the PHB node ibm,opal-phbid property. + +``mve_number`` + is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1 + +``state`` + A '1' value of the state parameter indicates to enable the MVE and a '0' + value indicates to disable the MVE. + +This call sets the MVE to an enabled (1) or disabled (0) state. + +Return value: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_mve_enable) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-p2p-157.rst b/roms/skiboot/doc/opal-api/opal-pci-set-p2p-157.rst new file mode 100644 index 000000000..d7be11475 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-p2p-157.rst @@ -0,0 +1,44 @@ +.. _OPAL_PCI_SET_P2P: + +OPAL_PCI_SET_P2P +================ + +.. code-block:: c + + #define OPAL_PCI_SET_P2P 157 + + int64_t opal_pci_set_p2p(uint64_t phbid_init, uint64_t phbid_target, + uint64_t desc, uint16_t pe_number); + + /* PCI p2p descriptor */ + #define OPAL_PCI_P2P_ENABLE 0x1 + #define OPAL_PCI_P2P_LOAD 0x2 + #define OPAL_PCI_P2P_STORE 0x4 + +The host calls this function to enable PCI peer-to-peer on the PHBs. + +Parameters +---------- + +``phbid_init`` + is the value from the PHB node ibm,opal-phbid property for the device initiating the p2p operation + +``phbid_target`` + is the value from the PHB node ibm,opal-phbid property for the device targeted by the p2p operation + +``desc`` + tells whether the p2p operation is a store (OPAL_PCI_P2P_STORE) or load (OPAL_PCI_P2P_LOAD). Can be both. + OPAL_PCI_P2P_ENABLE enables/disables the setting + +``pe_number`` + PE number for the initiating device + +Return Values +------------- + +:ref:`OPAL_SUCCESS` + Configuration was successful +:ref:`OPAL_PARAMETER` + Invalid PHB or mode parameter +:ref:`OPAL_UNSUPPORTED` + Not supported by hardware diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-pe-31.rst b/roms/skiboot/doc/opal-api/opal-pci-set-pe-31.rst new file mode 100644 index 000000000..41df45440 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-pe-31.rst @@ -0,0 +1,93 @@ +.. _OPAL_PCI_SET_PE: + +OPAL_PCI_SET_PE +=============== + +.. code-block:: c + + #define OPAL_PCI_SET_PE 31 + + int64_t opal_pci_set_pe(uint64_t phb_id, uint64_t pe_number, + uint64_t bus_dev_func, uint8_t bus_compare, + uint8_t dev_compare, uint8_t func_compare, + uint8_t pe_action); + +**NOTE:** The following two paragraphs come from some old documentation and +have not been checked for accuracy. Same goes for bus_compare, dev_compare +and func_compare documentation. Do *NOT* assume this documentation is correct +without checking the source. + +A host OS calls this function to map a PCIE function (RID), or range of +function bus/dev/funcs (RIDs), to a PHB PE. The bus, device, func, and +compare parameters define a range of bus, device, or function numbers to +define a range of RIDs within this domain. A value of "7" for the bus_compare, +and non-zero for the dev_compare and func_compare, define exactly one function +RID to be a PE (within a PE number domain). + +This must be called prior to ALL other OPAL calls that take a PE number +argument, for OPAL to correlate the RID (bus/dev/func) domain of the PE. If a +PE domain is changed, the host must call this to reset the PE bus/dev/func +domain and then call all other OPAL calls that map PHB IODA resources to +update those domains within PHB facilities. + +``phb_id`` + is the value from the PHB node ibm,opal-phbid property. + +``pe_number`` + is the index of a PE, from 0 to ibm,opal-num-pes minus 1. + +``bus_compare`` + is a value from 0 to 7 indicating which bus number + bits define the range of buses in a PE domain: + + 0 = do not validate against RID bus number (PE = all bus numbers) + + 2 = compare high order 3 bits of RID bus number to high order 3 bits of + PE bus number + + 3 = compare high order 4 bits of RID bus number to high order 4 bits of + PE bus number + + 6 = compare high order 7 bits of RID bus number to high order 7 bits of + PE bus number + + 7 = compare all bits of RID bus number to all bits of PE bus number + +``dev_compare`` + indicates to compare the RID device number to the PE + device number or not. '0' signifies that the RID device number is not compared + -- essentially all device numbers within the bus and function number range of + this PE are also within this PE. Non-zero signifies to compare the RID device + number to the PE device number, such that only that device number is in the PE + domain, for all buses and function numbers in the PE domain. + +``func_compare`` + indicates to compare the RID function number to the + PE function number or not. '0' signifies that the RID function number is not + compared -- essentially all function numbers within the bus and device number + range of this PE are also within this PE. Non-zero signifies to compare the + RID function number to the PE function number, such that only that function + number is in the PE domain, for all buses and device numbers in the PE domain. + +``pe_action`` + is one of: :: + + enum OpalPeAction { + OPAL_UNMAP_PE = 0, + OPAL_MAP_PE = 1 + }; + +Returns +------- + +:ref:`OPAL_PARAMETER` + If one of the following: + + - invalid phb + - invalid pe_action + - invalid bus_dev_func + - invalid bus_compare +:ref:`OPAL_UNSUPPORTED` + PHB does not support set_pe operation +:ref:`OPAL_SUCCESS` + if operation was successful diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-peltv-32.rst b/roms/skiboot/doc/opal-api/opal-pci-set-peltv-32.rst new file mode 100644 index 000000000..acb2d479a --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-peltv-32.rst @@ -0,0 +1,64 @@ +.. _OPAL_PCI_SET_PELTV: + +OPAL_PCI_SET_PELTV +================== + +.. code-block:: c + + #define OPAL_PCI_SET_PELTV 32 + + int64_t opal_pci_set_peltv(uint64_t phb_id, uint32_t parent_pe, + uint32_t child_pe, uint8_t state); + +**WARNING:** This documentation comes from an old source and is possibly not up +to date with OPALv3. Rely on this documentation only as a starting point, +use the source (and update the docs). + + +This call sets the PELTV of a parent PE to add or remove a PE number as a PE +within that parent PE domain. The host must call this function for each child +of a parent PE. + +``phb_id`` + is the value from the PHB node ibm,opal-phbid property + +``parent_pe`` + is the PE number of a PE that is higher in the PCI hierarchy + to other PEs, such that an error involving this parent PE should cause a + collateral PE freeze for PEs below this PE in the PCI hierarchy. For example + a switch upstream bridge is a PE that is parent to PEs reached through that + upstream bridge such that an error involving the upstream bridge + (e.g, ERR_FATAL) should cause the PHB to freeze all other PEs below that + upstream bridge (e.g., a downstream bridge, or devices below a downstream + bridge). + +``child_pe`` + is the PE number of a PE that is lower in the PCI hierarchy + than another PE, such that an error involving that other PE should cause a + collateral PE freeze for this child PE. For example a device below a + downstream bridge of a PCIE switch is a child PE that downstream bridge PE + and the upstream bridge PE of that switch -- an ERR_Fatal from either bridge + should result in a collateral freeze of that device PE. + +.. code-block:: c + + enum OpalPeltvAction { + OPAL_REMOVE_PE_FROM_DOMAIN = 0, + OPAL_ADD_PE_TO_DOMAIN = 1 + }; + +**OPAL Implementation Note:** +**WARNING TODO**: *CHECK IF THIS IS CORRECT FOR skiboot:* +For ibm,opal-ioda2, OPAL sets the PELTV bit in all RTT entries for the parent +PE when the state argument is '1'. OPAL clears the PELTV bit in all RTT +entries for the parent PE when the state argument is '0' and setting the child +PE bit in the parent PELTV results in an all-zeros value for that PELTV. + +Return value: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_peltv) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst b/roms/skiboot/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst new file mode 100644 index 000000000..130e382b5 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-phb-capi-mode-93.rst @@ -0,0 +1,89 @@ +.. _OPAL_PCI_SET_PHB_CAPI_MODE: + +OPAL_PCI_SET_PHB_CAPI_MODE +========================== + +.. code-block:: c + + #define OPAL_PCI_SET_PHB_CAPI_MODE 93 + + /* CAPI modes for PHB */ + enum { + OPAL_PHB_CAPI_MODE_PCIE = 0, + OPAL_PHB_CAPI_MODE_CAPI = 1, + OPAL_PHB_CAPI_MODE_SNOOP_OFF = 2, + OPAL_PHB_CAPI_MODE_SNOOP_ON = 3, + OPAL_PHB_CAPI_MODE_DMA = 4, + OPAL_PHB_CAPI_MODE_DMA_TVT1 = 5, + }; + + int64_t opal_pci_set_phb_capi_mode(uint64_t phb_id, uint64_t mode, uint64_t pe_number); + +Switch the CAPP attached to the given PHB in one of the supported CAPI modes. + +Parameters +---------- + +``uint64_t phb_id`` + the ID of the PHB which identifies attached CAPP to perform mode switch on +``uint64_t mode`` + A mode id as described below +``pe_number`` + PE number for the initiating device + +Calling +------- + +Switch CAPP attached to the given PHB in one of the following supported modes: :: + + OPAL_PHB_CAPI_MODE_PCIE = 0 + OPAL_PHB_CAPI_MODE_CAPI = 1 + OPAL_PHB_CAPI_MODE_SNOOP_OFF = 2 + OPAL_PHB_CAPI_MODE_SNOOP_ON = 3 + OPAL_PHB_CAPI_MODE_DMA = 4 + OPAL_PHB_CAPI_MODE_DMA_TVT1 = 5 + +Modes `OPAL_PHB_CAPI_MODE_PCIE` and `OPAL_PHB_CAPI_MODE_CAPI` are used to +enable/disable CAPP attached to the PHB. + +Modes `OPAL_PHB_CAPI_MODE_SNOOP_OFF` and `OPAL_PHB_CAPI_MODE_SNOOP_ON` are +used to enable/disable CAPP snooping of Powerbus traffic for cache line +invalidates. + +Mode `OPAL_PHB_CAPI_MODE_DMA` and `OPAL_PHB_CAPI_MODE_DMA_TVT1` are used to +enable CAPP DMA mode. + +Presently Mode `OPAL_PHB_CAPI_MODE_DMA_TVT1` is exclusively used by the Mellanox +CX5 adapter. Requesting this mode will also indicate to opal that the card +requests maximum number of DMA read engines allocated to improve DMA read +performance at cost of reduced bandwidth available to other traffic including +CAPP-PSL transactions. + +Notes +----- + +* If PHB is in PEC2 then requesting mode `OPAL_PHB_CAPI_MODE_DMA_TVT1` will + allocate extra 16/8 dma read engines to the PHB depending on its stack + (stack 0/ stack 1). This is needed to improve the Direct-GPU DMA read + performance for the Mellanox CX5 card. +* Mode `OPAL_PHB_CAPI_MODE_PCIE` not supported on Power-9. +* Requesting mode `OPAL_PHB_CAPI_MODE_CAPI` on Power-9 will disable fast-reboot. +* Modes `OPAL_PHB_CAPI_MODE_DMA`, `OPAL_PHB_CAPI_MODE_SNOOP_OFF` are + not supported on Power-9. +* CAPI is only supported on Power-8 and Power-9. + +Return Codes +------------ + +:ref:`OPAL_SUCCESS` + Switch to the requested capi mode performed successfully. +:ref:`OPAL_PARAMETER` + The requested value of mode or phb_id parameter is not valid. +:ref:`OPAL_HARDWARE` + An error occurred while switching the CAPP to requested mode. +:ref:`OPAL_UNSUPPORTED` + Switching to requested capi mode is not possible at the moment +:ref:`OPAL_RESOURCE` + CAPP ucode not available hence activating CAPP not supported. +:ref:`OPAL_BUSY` + CAPP is presently in recovery-mode and mode switch cannot be performed. diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-phb-mem-window-28.rst b/roms/skiboot/doc/opal-api/opal-pci-set-phb-mem-window-28.rst new file mode 100644 index 000000000..e23d841c1 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-phb-mem-window-28.rst @@ -0,0 +1,86 @@ +.. _OPAL_PCI_SET_PHB_MEM_WINDOW: + +OPAL_PCI_SET_PHB_MEM_WINDOW +=========================== + +.. code-block:: c + + #define OPAL_PCI_SET_PHB_MEM_WINDOW 28 + + 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); + +.. note:: Appears to be POWER7 p7ioc specific. Likely to be removed soon. + +**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: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_phb_mem_window) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-power-state-121.rst b/roms/skiboot/doc/opal-api/opal-pci-set-power-state-121.rst new file mode 100644 index 000000000..0209efb79 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-power-state-121.rst @@ -0,0 +1,57 @@ +.. _OPAL_PCI_SET_POWER_STATE: + +OPAL_PCI_SET_POWER_STATE +======================== + +.. code-block:: c + + #define OPAL_PCI_SET_POWER_STATE 121 + + int64_t opal_pci_set_power_state(uint64_t async_token, uint64_t id, uint64_t data); + +Set PCI slot power state + +Parameters +---------- + +``uint64_t async_token`` + Token of asynchronous message to be sent + on completion of OPAL_PCI_SLOT_POWER_{OFF, ON}. It is + ignored when @data is OPAL_PCI_SLOT_{OFFLINE, ONLINE}. + +``uint64_t id`` + PCI slot ID + +``uint64_t data`` + memory buffer pointer for the power state which + can be one of OPAL_PCI_SLOT_POWER_{OFF, ON, OFFLINE, ONLINE}. + +Calling +------- + +Set PCI slot's power state. The power state is stored in buffer pointed +by @data. The typical use is to hot add or remove adapters behind the +indicated PCI slot (by @id) in PCI hotplug path. + +User will receive an asychronous message after calling the API. The message +contains the API completion status: event (Power off or on), device node's +phandle identifying the PCI slot, errcode (e.g. :ref:`OPAL_SUCCESS`). The API returns +:ref:`OPAL_ASYNC_COMPLETION` for the case. + +The states OPAL_PCI_SLOT_OFFLINE and OPAL_PCI_SLOT_ONLINE are used for removing +or adding devices behind the slot. The device nodes in the device tree are +removed or added accordingly, without actually changing the slot's power state. +The API call will return OPAL_SUCCESS immediately and no further asynchronous +message will be sent. + +Return Codes +------------ + +:ref:`OPAL_SUCCESS` + PCI hotplug on the slot is completed successfully +:ref:`OPAL_ASYNC_COMPLETION` + PCI hotplug needs further message to confirm +:ref:`OPAL_PARAMETER` + The indicated PCI slot isn't found +:ref:`OPAL_UNSUPPORTED` + Setting power state not supported on the PCI slot diff --git a/roms/skiboot/doc/opal-api/opal-pci-set-xive-pe-37.rst b/roms/skiboot/doc/opal-api/opal-pci-set-xive-pe-37.rst new file mode 100644 index 000000000..9f7badffc --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-set-xive-pe-37.rst @@ -0,0 +1,39 @@ +.. _OPAL_PCI_SET_XIVE_PE: + +OPAL_PCI_SET_XIVE_PE +==================== + +.. code-block:: c + + #define OPAL_PCI_SET_XIVE_PE 37 + + int64_t opal_pci_set_xive_pe(uint64_t phb_id, uint64_t pe_number, uint32_t xive_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 bind a PE to an XIVE. Only that PE may then +signal an MSI that selects this XIVE. + +``phb_id`` + is the value from the PHB node ibm,opal-phbid property. + +``pe_number`` + is the index of a PE, from 0 to ibm,opal-num-pes minus 1. + +``xive_number`` + is the index, from 0 to ibm,opal,ibm-num-msis minus (num_lsis+1) + +This call maps the XIVR indexed by xive_num to the PE specified by +pe_number. For ibm,opal-ioda HW, the pe_number must match the pe_number +set in the MVE. + +Return value: + +.. code-block:: c + + if (!phb) + return OPAL_PARAMETER; + if (!phb->ops->set_xive_pe) + return OPAL_UNSUPPORTED; diff --git a/roms/skiboot/doc/opal-api/opal-pci-tce-kill-126.rst b/roms/skiboot/doc/opal-api/opal-pci-tce-kill-126.rst new file mode 100644 index 000000000..edd8706b9 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-pci-tce-kill-126.rst @@ -0,0 +1,70 @@ +.. _OPAL_PCI_TCE_KILL: + +OPAL_PCI_TCE_KILL +================= + +.. code-block:: c + + int64_t opal_pci_tce_kill(uint64_t phb_id, + uint32_t kill_type, + uint64_t pe_number, + uint32_t tce_size, + uint64_t dma_addr, + uint32_t npages); + +An abstraction around TCE kill. This allows host OS kernels to use an OPAL +call if they don't know the model specific invalidation method. + +Where kill_type is one of: + +.. code-block:: c + + enum { + OPAL_PCI_TCE_KILL_PAGES, + OPAL_PCI_TCE_KILL_PE, + OPAL_PCI_TCE_KILL_ALL, + }; + +Not all PHB types currently support this abstraction. It is supported in +PHB4, which means from POWER9 onwards it will be present. + +Returns +------- +:ref:`OPAL_PARAMETER` + if ``phb_id`` is invalid (or similar) +:ref:`OPAL_UNSUPPORTED` + if PHB model doesn't support this call. This is likely + true for systems before POWER9/PHB4. + Do *NOT* rely on this call existing for systems prior to + POWER9 (i.e. PHB4). + +Example code (from linux/arch/powerpc/platforms/powernv/pci-ioda.c) + +.. code-block:: c + + static inline void pnv_pci_ioda2_tce_invalidate_pe(struct pnv_ioda_pe *pe) + { + struct pnv_phb *phb = pe->phb; + + if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs) + pnv_pci_phb3_tce_invalidate_pe(pe); + else + opal_pci_tce_kill(phb->opal_id, OPAL_PCI_TCE_KILL_PE, + pe->pe_number, 0, 0, 0); + } + +and + +.. code-block:: c + + struct pnv_phb *phb = pe->phb; + unsigned int shift = tbl->it_page_shift; + + if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs) + pnv_pci_phb3_tce_invalidate(pe, rm, shift, + index, npages); + else + opal_pci_tce_kill(phb->opal_id, + OPAL_PCI_TCE_KILL_PAGES, + pe->pe_number, 1u << shift, + index << shift, npages); diff --git a/roms/skiboot/doc/opal-api/opal-phb-flag-set-get-179-180.rst b/roms/skiboot/doc/opal-api/opal-phb-flag-set-get-179-180.rst new file mode 100644 index 000000000..babc8376f --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-phb-flag-set-get-179-180.rst @@ -0,0 +1,63 @@ +.. _OPAL_PHB_SET_OPTION: + +OPAL_PHB_SET_OPTION +=================== + +.. code-block:: c + + #define OPAL_PHB_SET_OPTION 179 + + int64_t opal_phb_set_option(uint64_t phb_id, uint64_t opt, uint64_t setting); + + +This call translate an PHB option to a PHB flag for specific PHB model and +writes it to the hardware. + +Supported options are: + +.. code-block:: c + + enum OpalPhbOption { + OPAL_PHB_OPTION_TVE1_4GB = 0x1, + OPAL_PHB_OPTION_MMIO_EEH_DISABLE = 0x2 + }; + +OPAL_PHB_OPTION_TVE1_4GB: If set, uses TVE#1 for DMA access above 4GB; allowed setting 0 or 1. + +OPAL_PHB_OPTION_MMIO_EEH_DISABLE: Disables EEH for all MMIO commands; allowed setting 0 or 1. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_UNSUPPORTED` + if either the call or the option is not supported +:ref:`OPAL_PARAMETER` + if PHB is unknown or a new setting is out of range + +.. _OPAL_PHB_GET_OPTION: + +OPAL_PHB_GET_OPTION +=================== + +.. code-block:: c + + #define OPAL_PHB_GET_OPTION 180 + + int64_t opal_phb_get_option(uint64_t phb_id, uint64_t opt, uint64_t *setting); + +This call reads the hardware specific PHB flag and translates to a PHB option. + +For the list of supported options refer to OPAL_PHB_SET_OPTION above. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_UNSUPPORTED` + if either the call or the option is not supported +:ref:`OPAL_PARAMETER` + if PHB is unknown or a new setting is out of range or no memory + allocated for the return value diff --git a/roms/skiboot/doc/opal-api/opal-poll-events.rst b/roms/skiboot/doc/opal-api/opal-poll-events.rst new file mode 100644 index 000000000..bcf218a51 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-poll-events.rst @@ -0,0 +1,87 @@ +.. _OPAL_POLL_EVENTS: + +OPAL_POLL_EVENTS +================ + +Poll for outstanding events. + +Fills in a bitmask of pending events. + +Current events are: + +OPAL_EVENT_OPAL_INTERNAL = 0x1 +------------------------------ +Currently unused. + + +OPAL_EVENT_NVRAM = 0x2 +---------------------- +Unused + +.. _OPAL_EVENT_RTC: + +OPAL_EVENT_RTC = 0x4 +-------------------- +**TODO**: clean this up, this is just copied from hw/fsp/fsp-rtc.c: :: + + * Because the RTC calls can be pretty slow, these functions will shoot + * an asynchronous request to the FSP (if none is already pending) + * + * The requests will return OPAL_BUSY_EVENT as long as the event has + * not been completed. + * + * WARNING: An attempt at doing an RTC write while one is already pending + * will simply ignore the new arguments and continue returning + * OPAL_BUSY_EVENT. This is to be compatible with existing Linux code. + * + * Completion of the request will result in an event OPAL_EVENT_RTC + * being signaled, which will remain raised until a corresponding call + * to opal_rtc_read() or opal_rtc_write() finally returns OPAL_SUCCESS, + * at which point the operation is complete and the event cleared. + * + * If we end up taking longer than rtc_read_timeout_ms millieconds waiting + * for the response from a read request, we simply return a cached value (plus + * an offset calculated from the timebase. When the read request finally + * returns, we update our cache value accordingly. + * + * There is two separate set of state for reads and writes. If both are + * attempted at the same time, the event bit will remain set as long as either + * of the two has a pending event to signal. + +OPAL_EVENT_CONSOLE_OUTPUT = 0x8 +------------------------------- +TODO + +OPAL_EVENT_CONSOLE_INPUT = 0x10 +------------------------------- +TODO + +OPAL_EVENT_ERROR_LOG_AVAIL = 0x20 +--------------------------------- +TODO + +OPAL_EVENT_ERROR_LOG = 0x40 +--------------------------- +TODO + +OPAL_EVENT_EPOW = 0x80 +---------------------- +TODO + +OPAL_EVENT_LED_STATUS = 0x100 +----------------------------- +TODO + +OPAL_EVENT_PCI_ERROR = 0x200 +---------------------------- +TODO + +.. _OPAL_EVENT_DUMP_AVAIL: + +OPAL_EVENT_DUMP_AVAIL = 0x400 +----------------------------- +Signifies that there is a pending system dump available. See :ref:`opal-dumps` suite +of calls for details. + +OPAL_EVENT_MSG_PENDING = 0x800 +------------------------------ diff --git a/roms/skiboot/doc/opal-api/opal-power-shift-ratio.rst b/roms/skiboot/doc/opal-api/opal-power-shift-ratio.rst new file mode 100644 index 000000000..4437b55bb --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-power-shift-ratio.rst @@ -0,0 +1,89 @@ +.. _opal-psr: + +====================== +OPAL Power Shift Ratio +====================== + +Sometimes power management firmware needs to throttle power availability +to system components in order to keep within power cap or thermal limits. +It's possible to set a preference as to what trade-offs power management +firmware will make. For example, certain workloads may heavily prefer +throttling CPU over GPUs or vice-versa. + +.. _OPAL_GET_POWER_SHIFT_RATIO: + +OPAL_GET_POWER_SHIFT_RATIO +========================== +OPAL call to read the power-shifting-ratio using a handle to identify +the type (e.g CPU vs. GPU, CPU vs. MEM) which is exported via +device-tree. + +The call can be asynchronus, where the token parameter is used to wait +for the completion. + +Parameters +---------- + +=== ======= +=== ======= +u32 handle +int token +u32 \*ratio +=== ======= + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_PARAMETER` + Invalid ratio pointer +:ref:`OPAL_UNSUPPORTED` + No support for reading psr +:ref:`OPAL_HARDWARE` + Unable to procced due to the current hardware state +:ref:`OPAL_ASYNC_COMPLETION` + Request was sent and an async completion message will be sent with + token and status of the request. + +.. _OPAL_SET_POWER_SHIFT_RATIO: + +OPAL_SET_POWER_SHIFT_RATIO +========================== +OPAL call to set power-shifting-ratio using a handle to identify +the type of PSR which is exported in device-tree. This call can be +asynchronus where the token parameter is used to wait for the +completion. + +Parameters +---------- + +=== ====== +=== ====== +u32 handle +int token +u32 ratio +=== ====== + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_PARAMETER` + Invalid ratio requested +:ref:`OPAL_UNSUPPORTED` + No support for changing the ratio +:ref:`OPAL_PERMISSION` + Hardware cannot take the request +:ref:`OPAL_ASYNC_COMPLETION` + Request was sent and an async completion message will be sent with + token and status of the request. +:ref:`OPAL_HARDWARE` + Unable to procced due to the current hardware state +:ref:`OPAL_BUSY` + Previous request in progress +:ref:`OPAL_INTERNAL_ERROR` + Error in request response +:ref:`OPAL_TIMEOUT` + Timeout in request completion diff --git a/roms/skiboot/doc/opal-api/opal-powercap.rst b/roms/skiboot/doc/opal-api/opal-powercap.rst new file mode 100644 index 000000000..6ff4d5cca --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-powercap.rst @@ -0,0 +1,104 @@ +.. _opal-powercap: + +=============== +OPAL Power Caps +=============== + +Each entity that can be power capped is described in the device tree, +see :ref:`device-tree/ibm,opal/power-mgt/powercap`. The values for each +power cap aren't in the device tree, but rather fetched using the +:ref:`OPAL_GET_POWERCAP` OPAL call. This is because there may be other +entities such as a service processor that can change the nature of the +power cap asynchronously to OPAL. + +.. _OPAL_GET_POWERCAP: + +OPAL_GET_POWERCAP +================= +The OPAL_GET_POWERCAP call retreives current information on the power +cap. + +For each entity that can be power capped, the device tree +binding indicates what handle should be passed for each of the power cap +properties (minimum possible, maximum possible, current powercap). + +The current power cap must be between the minimium possible and maximum +possible power cap. The minimum and maximum values are dynamic to allow +for them possibly being changed by other factors or entities +(e.g. service processor). + +The call can be asynchronus, where the token parameter is used to wait +for the completion. + +Parameters +---------- + +=== ====== +=== ====== +u32 handle +int token +u32 \*pcap +=== ====== + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_PARAMETER` + Invalid pcap pointer +:ref:`OPAL_UNSUPPORTED` + No support for reading powercap sensor +:ref:`OPAL_HARDWARE` + Unable to procced due to the current hardware state +:ref:`OPAL_ASYNC_COMPLETION` + Request was sent and an async completion message will be sent with + token and status of the request. + +.. _OPAL_SET_POWERCAP: + +OPAL_SET_POWERCAP +================= +The OPAL_SET_POWERCAP call sets a power cap. + +For each entity that can be power capped, the device tree +binding indicates what handle should be passed for each of the power cap +properties (minimum possible, maximum possible, current powercap). + +The current power cap must be between the minimium possible and maximum +possible power cap. + +You cannot currently set the minimum or maximum power cap, and thus +OPAL_PERMISSION will be returned if it is attempted to set. In the +future, this may change - but for now, the correct behaviour for an +Operating System is to not attempt to set them. + +Parameters +---------- +:: + u32 handle + int token + u32 pcap + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_PARAMETER` + Invalid powercap requested beyond powercap limits +:ref:`OPAL_UNSUPPORTED` + No support for changing the powercap +:ref:`OPAL_PERMISSION` + Hardware cannot take the request +:ref:`OPAL_ASYNC_COMPLETION` + Request was sent and an async completion message will be sent with + token and status of the request. +:ref:`OPAL_HARDWARE` + Unable to procced due to the current hardware state +:ref:`OPAL_BUSY` + Previous request in progress +:ref:`OPAL_INTERNAL_ERROR` + Error in request response +:ref:`OPAL_TIMEOUT` + Timeout in request completion diff --git a/roms/skiboot/doc/opal-api/opal-prd-msg-113.rst b/roms/skiboot/doc/opal-api/opal-prd-msg-113.rst new file mode 100644 index 000000000..91d30aca7 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-prd-msg-113.rst @@ -0,0 +1,19 @@ +.. _OPAL_PRD_MSG: + +OPAL_PRD_MSG +============ + +.. code-block:: c + + #define OPAL_PRD_MSG 113 + + int64_t opal_prd_msg(struct opal_prd_msg *msg); + +The OPAL_PRD_MSG call is used to pass a struct opal_prd_msg from the HBRT +code into opal, and is paired with the :ref:`OPAL_PRD_MSG` message type. + +Parameters +---------- + +``struct opal_msg *msg`` + Passes an opal_msg, of type OPAL_PRD_MSG, from the OS to OPAL. diff --git a/roms/skiboot/doc/opal-api/opal-query-cpu-status-42.rst b/roms/skiboot/doc/opal-api/opal-query-cpu-status-42.rst new file mode 100644 index 000000000..b33edddc6 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-query-cpu-status-42.rst @@ -0,0 +1,35 @@ +.. _OPAL_QUERY_CPU_STATUS: + +OPAL_QUERY_CPU_STATUS +===================== + +.. code-block:: c + + #define OPAL_QUERY_CPU_STATUS 42 + + enum OpalThreadStatus { + OPAL_THREAD_INACTIVE = 0x0, + OPAL_THREAD_STARTED = 0x1, + OPAL_THREAD_UNAVAILABLE = 0x2 /* opal-v3 */ + }; + + int64_t opal_query_cpu_status(uint64_t server_no, uint8_t *thread_status); + +Sets `thread_status` to be the state of the `server_no` CPU thread. CPU threads +can be owned by OPAL or the OS. Ownership changes based on :ref:`OPAL_START_CPU` +and :ref:`OPAL_RETURN_CPU`. + +``OPAL_THREAD_INACTIVE`` + Active in skiboot, not in OS. Skiboot owns the CPU thread. +``OPAL_THREAD_STARTED`` + CPU has been started by OS, not owned by OPAL. +``OPAL_THREAD_UNAVAILABLE`` + CPU is unavailable. e.g. is guarded out. + +Returns +------- + +:ref:`OPAL_PARAMETER` + Invalid address for `thread_status`, invalid CPU, or CPU not in OPAL or OS. +:ref:`OPAL_SUCCESS` + Successfully retreived status. diff --git a/roms/skiboot/doc/opal-api/opal-quiesce-158.rst b/roms/skiboot/doc/opal-api/opal-quiesce-158.rst new file mode 100644 index 000000000..babbe0413 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-quiesce-158.rst @@ -0,0 +1,72 @@ +.. _OPAL_QUIESCE: + +OPAL_QUIESCE +============ + +.. code-block:: c + + #define OPAL_QUIESCE 158 + + int64_t opal_quiesce(uint32_t quiesce_type, int32_t cpu_target); + +The host OS can use :ref:`OPAL_QUIESCE` to ensure CPUs under host control are not +executing OPAL. This is useful in crash or shutdown scenarios to try to +ensure that CPUs are not holding locks, and is intended to be used with +:ref:`OPAL_SIGNAL_SYSTEM_RESET`, for example. + +Arguments +--------- + +quiesce_type +^^^^^^^^^^^^ + +QUIESCE_HOLD + Wait for all target(s) currently executing OPAL to + return to the host. Any new OPAL call that is made + will be held off until QUIESCE_RESUME. +QUIESCE_REJECT + Wait for all target(s) currently executing OPAL to + return to the host. Any new OPAL call that is made + will fail with OPAL_BUSY until QUIESCE_RESUME. +QUIESCE_LOCK_BREAK + After QUIESCE_HOLD or QUIESCE_REJECT is successful, + the CPU can call QUIESCE_LOCK_BREAK to skip all + locking in OPAL to give the best chance of making + progress in the crash/debug paths. The host should + ensure all other CPUs are stopped (e.g., with + OPAL_SIGNAL_SYSTEM_RESET) before this call is made, to + avoid concurrency. +QUIESCE_RESUME + Undo the effects of QUIESCE_HOLD/QUIESCE_REJECT and + QUIESCE_LOCK_BREAK calls. +QUIESCE_RESUME_FAST_REBOOT + As above, but also reset the tracking of OS calls + into firmware as part of fast reboot (secondaries + will never return to OS, but instead be released + into a new OS boot). + +target_cpu +^^^^^^^^^^ + +``cpu_nr >= 0`` + The cpu server number of the target cpu to reset. +``-1`` + All cpus except the current one should be quiesced. + +Returns +------- + +:ref:`OPAL_SUCCESS` + The quiesce call was successful. +:ref:`OPAL_PARTIAL` + Some or all of the CPUs executing OPAL when the call was made did not + return to the host after a timeout of 1 second. This is a best effort + at quiescing OPAL, and QUIESCE_RESUME must be called to resume normal + firmware operation. +:ref:`OPAL_PARAMETER` + A parameter was incorrect. +:ref:`OPAL_BUSY` + This CPU was not able to complete the operation, either because another + has concurrently started quiescing the system, or because it has not + successfully called QUIESCE_HOLD or QUIESCE_REJECT before attempting + QUIESCE_LOCK_BREAK or QUIESCE_RESUME. diff --git a/roms/skiboot/doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst b/roms/skiboot/doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst new file mode 100644 index 000000000..52bb67e38 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst @@ -0,0 +1,82 @@ + +========================================= +OPAL Timed Power On and Delayed Power Off +========================================= + +.. code-block:: c + + #define OPAL_WRITE_TPO 103 + #define OPAL_READ_TPO 104 + #define OPAL_GET_DPO_STATUS 105 + +TPO is a Timed Power On facility, and DPO is Delayed Power Off. + +It is an OPTIONAL part of the OPAL spec. + +If a platform supports Timed Power On (TPO), the RTC node in the device tree +(itself under the "ibm,opal" node will have the has-tpo property: + +.. code-block:: dts + + rtc { + compatible = "ibm,opal-rtc"; + has-tpo; + }; + +If the "has-tpo" proprety is *NOT* present then OPAL does *NOT* support TPO. + +.. _OPAL_READ_TPO: + +OPAL_READ_TPO +============= + +.. code-block:: c + + #define OPAL_READ_TPO 104 + + static int64_t opal_read_tpo(uint64_t async_token, uint32_t *y_m_d, uint32_t *hr_min); + + +.. _OPAL_WRITE_TPO: + +OPAL_WRITE_TPO +============== + +.. code-block:: c + + #define OPAL_WRITE_TPO 103 + + int64_t fsp_opal_tpo_write(uint64_t async_token, uint32_t y_m_d, uint32_t hr_min); + + +.. _OPAL_GET_DPO_STATUS: + +OPAL_GET_DPO_STATUS +=================== + +.. code-block:: c + + #define OPAL_GET_DPO_STATUS 105 + + static int64_t opal_get_dpo_status(int64_t *dpo_timeout); + +A :ref:`OPAL_MSG_DPO` message may be sent to indicate that there will shortly +be a forced system shutdown. In this case, an OS can call +:ref:`OPAL_GET_DPO_STATUS` to find out how many seconds it has before power +is cut to the system. + +This call could be present on systems where the service processor is integrated +with a UPS or similar. + +Returns zero if Delayed Power Off is not active, positive value indicating +number of seconds remaining for a forced system shutdown. This will enable +the host to schedule for shutdown voluntarily before timeout occurs. + +Returns +------- + +:ref:`OPAL_SUCCESS` + ``dpo_timeout`` is set to the number of seconds remaining before power is + cut. +:ref:`OPAL_WRONG_STATE` + A Delayed Power Off is not pending, ``dpo_timeout`` is set to zero. diff --git a/roms/skiboot/doc/opal-api/opal-reinit-cpus-70.rst b/roms/skiboot/doc/opal-api/opal-reinit-cpus-70.rst new file mode 100644 index 000000000..3a6e54373 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-reinit-cpus-70.rst @@ -0,0 +1,68 @@ +.. _OPAL_REINIT_CPUS: + +OPAL_REINIT_CPUS +================ + +.. code-block:: c + + #define OPAL_REINIT_CPUS 70 + + static int64_t opal_reinit_cpus(uint64_t flags); + +This OPAL call reinitializes some bit of CPU state across *ALL* CPUs. +Consequently, all CPUs must be in OPAL for this call to succeed (either +at boot time or after OPAL_RETURN_CPU is called). + +Arguments +--------- +Currently, possible flags are: + +.. code-block:: c + + enum { + OPAL_REINIT_CPUS_HILE_BE = (1 << 0), + OPAL_REINIT_CPUS_HILE_LE = (1 << 1), + OPAL_REINIT_CPUS_MMU_HASH = (1 << 2), + OPAL_REINIT_CPUS_MMU_RADIX = (1 << 3), + OPAL_REINIT_CPUS_TM_SUSPEND_DISABLED = (1 << 4), + }; + +Extra flags may be added in the future, so other bits *must* be 0. + +On POWER7 CPUs, only OPAL_REINIT_CPUS_HILE_BE is supported. All other +flags will return OPAL_UNSUPPORTED. + +On POWER8 CPUs, only OPAL_REINIT_CPUS_HILE_BE and OPAL_REINIT_CPUS_HILE_LE +are support and other bits *MUST NOT* be set. + +On POWER9 CPUs, all options including OPAL_REINIT_CPUS_MMU_HASH and +OPAL_REINIT_CPUS_MMU_RADIX. + +OPAL_REINIT_CPUS_TM_SUSPEND_DISABLED +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This flag requests that CPUs be configured with TM (Transactional Memory) +suspend mode disabled. This may only be supported on some CPU versions. + +OPAL_REINIT_CPUS_MMU_HASH and OPAL_REINIT_CPUS_MMU_RADIX +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some processors may need to change a processor specific register in order to +support Hash or Radix translation. + +For POWER9 CPUs, this is bit 8 of the HID register (see the POWER9 User Manual +for details). On POWER9 CPUS, when in Hash mode, the full TLB is available to +the host OS rather than when in radix mode, half the TLB is taken for a Page +Walk Cache (PWC). + +Future CPUs may or may not do anything with these flags, but a host OS must +use them to ensure compatibility in the future. + + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_UNSUPPORTED` + Processor does not suport reinit flags. diff --git a/roms/skiboot/doc/opal-api/opal-resync-timebase-79.rst b/roms/skiboot/doc/opal-api/opal-resync-timebase-79.rst new file mode 100644 index 000000000..b4df452e3 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-resync-timebase-79.rst @@ -0,0 +1,21 @@ +.. _OPAL_RESYNC_TIMEBASE: + +OPAL_RESYNC_TIMEBASE +==================== + +.. code-block:: c + + #define OPAL_RESYNC_TIMEBASE 79 + + int64_t opal_resync_timebase(void); + +Resynchronises the timebase for all threads in a core to the timebase from +chiptod. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Successfully resynced timebases (or it's a no-op on this platform). +:ref:`OPAL_HARDWARE` + Failed to resync timebase. diff --git a/roms/skiboot/doc/opal-api/opal-rtc-read-write-3-4.rst b/roms/skiboot/doc/opal-api/opal-rtc-read-write-3-4.rst new file mode 100644 index 000000000..e324e1a3c --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-rtc-read-write-3-4.rst @@ -0,0 +1,91 @@ +=============================== +OPAL Real Time Clock (RTC) APIs +=============================== + +.. _OPAL_RTC_READ: + +OPAL_RTC_READ +============= + +Read the Real Time Clock. + +Parameters +---------- + +``uint32_t* year_month_day`` + the year, month and day formatted as follows: + + - bits 0-15 is bcd formatted year (0100-9999) + - bits 16-23 is bcd formatted month (01-12) + - bits 24-31 is bcd formatted day (01-31) + +``uint64_t* hour_minute_second_millisecond`` + the hour, minute, second and millisecond formatted as follows: + + - bits 0-16 is reserved + - bits 17-24 is bcd formatted hour (00-23) + - bits 25-31 is bcd formatted minute (00-59) + - bits 32-39 is bcd formatted second (00-60) + - bits 40-63 is bcd formatted milliseconds (000000-999999) + +Calling +------- +Since RTC calls can be pretty slow, :ref:`OPAL_RTC_READ` is likely to first return +:ref:`OPAL_BUSY_EVENT`, requiring the caller to wait until the :ref:`OPAL_EVENT_RTC` event +has been signaled. Once the event has been signaled, a subsequent +:ref:`OPAL_RTC_READ` call will retrieve the time. Since the :ref:`OPAL_EVENT_RTC` event is +used for both reading and writing the RTC, callers must be able to handle +the event being signaled for a concurrent in flight :ref:`OPAL_RTC_WRITE` rather +than this read request. + +The following code is one way to correctly issue and then wait for a response: + +.. code-block:: c + + int rc = OPAL_BUSY_EVENT; + while (rc == OPAL_BUSY_EVENT) { + rc = opal_rtc_read(&y_m_d, &h_m_s_ms); + if (rc == OPAL_BUSY_EVENT) + opal_poll_events(NULL); + } + +Although as of writing all :ref:`OPAL_RTC_READ` backends are asynchronous, there is +no requirement for them to be - it is valid for :ref:`OPAL_RTC_READ` to immediately +return the retreived value rather than :ref:`OPAL_BUSY_EVENT`. + +**TODO**: describe/document format of arguments. + +Return codes +------------ + +:ref:`OPAL_SUCCESS` + parameters now contain the current time, or one read from cache. + +:ref:`OPAL_HARDWARE` + error in retrieving the time. May be transient error, + may be permanent. + +:ref:`OPAL_PARAMETER` + year_month_day or hour_minute_second_millisecond parameters are NULL + +:ref:`OPAL_INTERNAL_ERROR` + something went wrong, Possibly reported in error log. + This can be a transient error + +:ref:`OPAL_BUSY_EVENT` + request is in flight + +:ref:`OPAL_BUSY` + request may be in flight + +.. _OPAL_RTC_WRITE: + +OPAL_RTC_WRITE +============== + +:ref:`OPAL_RTC_WRITE` is much like :ref:`OPAL_RTC_READ` in that it can be asynchronous. + +If multiple WRITES are issued before the first one completes, subsequent +writes are ignored. There can only be one write in flight at any one time. + +Format of the time is the same as for :ref:`OPAL_RTC_READ`. diff --git a/roms/skiboot/doc/opal-api/opal-secvar.rst b/roms/skiboot/doc/opal-api/opal-secvar.rst new file mode 100644 index 000000000..3bb130e5d --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-secvar.rst @@ -0,0 +1,192 @@ +OPAL Secure Variable API +======================== + +Overview +-------- + +In order to support host OS secure boot on POWER systems, the platform needs +some form of tamper-resistant persistant storage for authorized public keys. +Furthermore, these keys must be retrieveable by the host kernel, and new +keys must be able to be submitted. + +OPAL exposes an abstracted "variable" API, in which these keys can be stored +and retrieved. At a high level, ``opal_secvar_get`` retrieves a specific +variable corresponding to a particular key. ``opal_secvar_get_next`` can be +used to iterate through the keys of the stored variables. +``opal_secvar_enqueue_update`` can be used to submit a new variable for +processing on next boot. + +OPAL_SECVAR_GET +=============== +:: + + #define OPAL_SECVAR_GET 176 + +``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied +key. + + +Parameters +---------- +:: + + char *key + uint64_t key_len + void *data + uint64_t *data_size + +``key`` + a buffer used to associate with the variable data. May + be any encoding, but must not be all zeroes + +``key_len`` + size of the key buffer in bytes + +``data`` + return buffer to store the data blob of the requested variable if + a match was found. May be set to NULL to only query the size into + ``data_size`` + +``data_size`` + reference to the size of the ``data`` buffer. OPAL sets this to + the size of the requested variable if found. + + +Return Values +------------- + +``OPAL_SUCCESS`` + the requested data blob was copied successfully. ``data`` was NULL, + and the ``data_size`` value was set successfully + +``OPAL_PARAMETER`` + ``key`` is NULL. + ``key_len`` is zero. + ``data_size`` is NULL. + +``OPAL_EMPTY`` + no variable with the supplied ``key`` was found + +``OPAL_PARTIAL`` + the buffer size provided in ``data_size`` was insufficient. + ``data_size`` is set to the minimum required size. + +``OPAL_UNSUPPORTED`` + secure variables are not supported by the platform + +``OPAL_RESOURCE`` + secure variables are supported, but did not initialize properly + +OPAL_SECVAR_GET_NEXT +==================== +:: + + #define OPAL_SECVAR_GET_NEXT 177 + +``OPAL_SECVAR_GET_NEXT`` returns the key of the next variable in the secure +variable bank in sequence. + +Parameters +---------- +:: + + char *key + uint64_t *key_len + uint64_t key_buf_size + + +``key`` + name of the previous variable or empty. The key of the next + variable in sequence will be copied to ``key``. If passed as empty, + returns the first variable in the bank + +``key_len`` + length in bytes of the key in the ``key`` buffer. OPAL sets + this to the length in bytes of the next variable in sequence + +``key_buf_size`` + maximum size of the ``key`` buffer. The next key will not be + copied if this value is less than the length of the next key + + +Return Values +------------- + +``OPAL_SUCCESS`` + the key and length of the next variable in sequence was copied + successfully + +``OPAL_PARAMETER`` + ``key`` or ``key_length`` is NULL. + ``key_size`` is zero. + ``key_length`` is impossibly large. No variable with the associated + ``key`` was found + +``OPAL_EMPTY`` + end of list reached + +``OPAL_PARTIAL`` + the size specified in ``key_size`` is insufficient for the next + variable's key length. ``key_length`` is set to the next variable's + length, but ``key`` is untouched + +``OPAL_UNSUPPORTED`` + secure variables are not supported by the platform + +``OPAL_RESOURCE`` + secure variables are supported, but did not initialize properly + +OPAL_SECVAR_ENQUEUE_UPDATE +========================== +:: + + #define OPAL_SECVAR_ENQUEUE_UPDATE 178 + +``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the +queue for processing on next boot. + +Parameters +---------- +:: + + char *key + uint64_t key_len + void *data + uint64_t data_size + +``key`` + a buffer used to associate with the variable data. May + be any encoding, but must not be all zeroes + +``key_len`` + size of the key buffer in bytes + +``data`` + buffer containing the blob of data to enqueue + +``data_size`` + size of the ``data`` buffer + +Return Values +------------- + +``OPAL_SUCCESS`` + the variable was appended to the update queue bank successfully + +``OPAL_PARAMETER`` + ``key`` or ``data`` was NULL. + ``key`` was empty. + ``key_len`` or ``data_size`` was zero. + ``key_len``, ``data_size`` is larger than the maximum size + +``OPAL_NO_MEM`` + OPAL was unable to allocate memory for the variable update + +``OPAL_HARDWARE`` + OPAL was unable to write the update to persistant storage + +``OPAL_UNSUPPORTED`` + secure variables are not supported by the platform + +``OPAL_RESOURCE`` + secure variables are supported, but did not initialize properly diff --git a/roms/skiboot/doc/opal-api/opal-sensor-group-enable-clear-163-156.rst b/roms/skiboot/doc/opal-api/opal-sensor-group-enable-clear-163-156.rst new file mode 100644 index 000000000..dbf5e3a66 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-sensor-group-enable-clear-163-156.rst @@ -0,0 +1,88 @@ +.. _opal-sensor-groups: + +================== +OPAL Sensor Groups +================== + +See :ref:`device-tree/ibm,opal/sensor-groups` for device tree layout. + +.. _OPAL_SENSOR_GROUP_ENABLE: + +OPAL_SENSOR_GROUP_ENABLE +======================== + +.. code-block:: c + + #define OPAL_SENSOR_GROUP_ENABLE 163 + + int opal_sensor_group_enable(u32 group_hndl, int token, bool enable); + +OPAL call to enable/disable the sensor group using a handle to identify +the type of sensor group provided in the device tree. + +For example this call is used to disable/enable copying of sensor +group by OCC to main memory. + +The call can be asynchronus, where the token parameter is used to wait +for the completion. + + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_UNSUPPORTED` + No support to enable/disable the sensor group +:ref:`OPAL_HARDWARE` + Unable to procced due to the current hardware state +:ref:`OPAL_PERMISSION` + Hardware cannot take the request +:ref:`OPAL_ASYNC_COMPLETION` + Request was sent and an async completion message will be sent with + token and status of the request. +:ref:`OPAL_BUSY` + Previous request in progress +:ref:`OPAL_INTERNAL_ERROR` + Error in request response +:ref:`OPAL_TIMEOUT` + Timeout in request completion + +.. _OPAL_SENSOR_GROUP_CLEAR: + +OPAL_SENSOR_GROUP_CLEAR +======================= + +.. code-block:: c + + int opal_sensor_group_clear(u32 group_hndl, int token); + + #define OPAL_SENSOR_GROUP_CLEAR 156 + +OPAL call to clear the sensor groups data using a handle to identify +the type of sensor group which is exported via DT. + +The call can be asynchronus, where the token parameter is used to wait +for the completion. + + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success +:ref:`OPAL_UNSUPPORTED` + No support for clearing the sensor group +:ref:`OPAL_HARDWARE` + Unable to procced due to the current hardware state +:ref:`OPAL_PERMISSION` + Hardware cannot take the request +:ref:`OPAL_ASYNC_COMPLETION` + Request was sent and an async completion message will be sent with + token and status of the request. +:ref:`OPAL_BUSY` + Previous request in progress +:ref:`OPAL_INTERNAL_ERROR` + Error in request response +:ref:`OPAL_TIMEOUT` + Timeout in request completion diff --git a/roms/skiboot/doc/opal-api/opal-sensor-read-88.rst b/roms/skiboot/doc/opal-api/opal-sensor-read-88.rst new file mode 100644 index 000000000..793dcfdf6 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-sensor-read-88.rst @@ -0,0 +1,82 @@ +.. _OPAL_SENSOR_READ: + +OPAL_SENSOR_READ +================ + +.. code-block:: c + + #define OPAL_SENSOR_READ 88 + + int64_t opal_sensor_read(uint32_t sensor_hndl, int token, uint32_t *sensor_data); + +The OPAL sensor call reads a sensor data using a unique handler to +identity the targeted sensor. The `sensor_handle` is provided +via the device tree and is opaque to the OS (although we currently +do use an encoding scheme). + +This call can be asynchronous, when a message needs to be sent to a +service processor for example. In this case, the call will return +OPAL_ASYNC_COMPLETION and the token parameter will be used to wait for +the completion of the request. + +The OPAL API doesn't enforce alimit on the number of sensor calls that can +be in flight. + +Internally, :ref:`OPAL_SENSOR_READ` is implemented as a wrapper around +:ref:`OPAL_SENSOR_READ_U64`. Any code targeting processor generations prior +to POWER9 will need to use :ref:`OPAL_CHECK_TOKEN` to ensure :ref:`OPAL_SENSOR_READ_U64` +is present and gracefully fall back to :ref:`OPAL_SENSOR_READ` if it is not. + +Parameters +---------- +:: + + uint32_t sensor_handle + int token + uint32_t *sensor_data + + +Return values +------------- +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_PARAMETER` + invalid sensor handle +:ref:`OPAL_UNSUPPORTED` + platform does not support reading sensors. +:ref:`OPAL_ASYNC_COMPLETION` + a request was sent and an async completion will + be triggered with the @token argument +:ref:`OPAL_PARTIAL` + the request completed but the data returned is invalid +:ref:`OPAL_BUSY_EVENT` + a previous request is still pending +:ref:`OPAL_NO_MEM` + allocation failed +:ref:`OPAL_INTERNAL_ERROR` + communication failure with the FSP +:ref:`OPAL_HARDWARE` + FSP is not available + +.. _OPAL_SENSOR_READ_U64: + +OPAL_SENSOR_READ_U64 +==================== + +.. code-block:: c + + #define OPAL_SENSOR_READ_U64 162 + + s64 opal_sensor_read_u64(u32 sensor_hndl, int token, u64 *sensor_data); + +The OPAL sensor call to read sensor data of type u64. Unlike +opal_sensor_read which reads upto u32 this call can be used to +read values of sensors upto 64bits. The calling conventions and +return values are same as :ref:`OPAL_SENSOR_READ`. + +All sensors can be read through the :ref:`OPAL_SENSOR_READ_U64` call that +can be read using the :ref:`OPAL_SENSOR_READ` call. Internally, +:ref:`OPAL_SENSOR_READ` is a wrapper around :ref:`OPAL_SENSOR_READ_U64`. +Any code targeting processor generations prior to POWER9 will need to use +:ref:`OPAL_CHECK_TOKEN` to ensure :ref:`OPAL_SENSOR_READ_U64` +is present and gracefully fall back to :ref:`OPAL_SENSOR_READ` if it is not. diff --git a/roms/skiboot/doc/opal-api/opal-set-xive-19.rst b/roms/skiboot/doc/opal-api/opal-set-xive-19.rst new file mode 100644 index 000000000..2a7332f03 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-set-xive-19.rst @@ -0,0 +1,50 @@ +.. _OPAL_SET_XIVE: + +OPAL_SET_XIVE +============= + +.. code-block:: c + + #define OPAL_SET_XIVE 19 + + int64_t opal_set_xive(uint32_t isn, uint16_t server, uint8_t priority); + +The host calls this function to set the server (target processor) +and priority parameters of an interrupt source. + +This can be also used to mask or unmask the interrupt (by changing +the priority to 0xff one masks an interrupt). + +WARNINGS: + + - For MSIs or generally edge sensitive interrupts, OPAL provides no + guarantee as to whether the interrupt will be latched if it occurs + while masked and replayed on unmask. It may or may not. The OS needs + to be aware of this. The current implementation will *not* replay, + neither on P8 nor on P9 XICS emulation. + + - When masking, there is no guarantee that the interrupt will not + still occur after this call returns. The reason is that it might + already be on its way past the source controller and latched into one + of the presenters. There is however a guarantee that it won't replay + indefinitely so it's acceptable for the OS to simply ignore it. + +Parameters +---------- + +``isn`` + This is a global interrupt number as obtained from the device-tree + "interrupts" or "interrupt-map" properties. + +``server_number`` + is the mangled server (processor) that is to receive the + interrupt request. The mangling means that the actual processor + number is shifted left by 2 bits, the bottom bits representing + the "link". However links aren't supported in OPAL so the bottom + 2 bits should be 0. + +``priority`` + is the interrupt priority value applied to the interrupt + (0=highest, 0xFF = lowest/disabled). + + diff --git a/roms/skiboot/doc/opal-api/opal-signal-system-reset-145.rst b/roms/skiboot/doc/opal-api/opal-signal-system-reset-145.rst new file mode 100644 index 000000000..98baef72a --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-signal-system-reset-145.rst @@ -0,0 +1,59 @@ +.. _OPAL_SIGNAL_SYSTEM_RESET: + +OPAL_SIGNAL_SYSTEM_RESET +======================== +:: + + int64_t signal_system_reset(int32_t cpu_nr); + +This OPAL call causes the specified cpu(s) to be reset to the system +reset exception handler (0x100). + +The SRR1 register will indicate a power-saving wakeup when appropriate, +and the wake reason will be System Reset (see Power ISA). + +This interrupt may not be recoverable in some cases (e.g., if it is +raised when the target has MSR[RI]=0), so it should not be used in +normal operation, but only for crashing, debugging, and similar +exceptional cases. + +OPAL_SIGNAL_SYSTEM_RESET can pull CPUs out of OPAL, which may be +undesirable in a crash or shutdown situation (e.g., because they may +hold locks which are required to access the console, or may be halfway +through setting hardware registers), so OPAL_QUIESCE can be used +before OPAL_SIGNAL_SYSTEM_RESET to (attempt to) ensure all CPUs are +out of OPAL before being interrupted. + +Arguments +--------- +:: + + int32_t cpu_nr + cpu_nr >= 0 The cpu server number of the target cpu to reset. + SYS_RESET_ALL (-1) All cpus should be reset. + SYS_RESET_ALL_OTHERS (-2) All but the current cpu should be reset. + +Returns +------- +OPAL_SUCCESS + The system reset requests to target CPU(s) was successful. This returns + asynchronously without acknowledgement from targets that system reset + interrupt processing has completed or even started. + +OPAL_PARAMETER + A parameter was incorrect. + +OPAL_HARDWARE + Hardware indicated failure during reset, some or all of the target CPUs + may have the system reset delivered. + +OPAL_CONSTRAINED + Platform does not support broadcast operations. + +OPAL_PARTIAL + Platform can not reset sibling threads on the same core as requested. + None of the specified CPUs are reset in this case. + +OPAL_UNSUPPORTED + This processor/platform is not supported. + diff --git a/roms/skiboot/doc/opal-api/opal-slw-set-reg-100.rst b/roms/skiboot/doc/opal-api/opal-slw-set-reg-100.rst new file mode 100644 index 000000000..2e8f1bd61 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-slw-set-reg-100.rst @@ -0,0 +1,44 @@ +.. _OPAL_SLW_SET_REG: + +OPAL_SLW_SET_REG +================ + +.. code-block:: c + + #define OPAL_SLW_SET_REG 100 + + int64_t opal_slw_set_reg(uint64_t cpu_pir, uint64_t sprn, uint64_t val); + +:ref:`OPAL_SLW_SET_REG` is used to inform low-level firmware to restore a +given value of SPR when there is a state loss. The actual set of SPRs +that are supported is platform dependent. + +In Power 8, it uses p8_pore_gen_cpufreq_fixed(), api provided by pore engine, +to inform the spr with their corresponding values with which they +must be restored. + +In Power 9, it uses p9_stop_save_cpureg(), api provided by self restore code, +to inform the spr with their corresponding values with which they +must be restored. + + +Parameters +---------- + +``uint64_t cpu_pir`` + This parameter specifies the pir of the cpu for which the call is being made. +``uint64_t sprn`` + This parameter specifies the spr number as mentioned in p9_stop_api.H for + Power9 and p8_pore_table_gen_api.H for Power8. +``uint64_t val`` + This parameter specifices value with which the spr should be restored. + +Returns +------- + +:ref:`OPAL_INTERNAL_ERROR` + On failure. The actual error code from the platform specific code is logged in the OPAL logs +:ref:`OPAL_UNSUPPORTED` + If spr restore is not supported by pore engine. +:ref:`OPAL_SUCCESS` + On success diff --git a/roms/skiboot/doc/opal-api/opal-start-return-cpu-41-69.rst b/roms/skiboot/doc/opal-api/opal-start-return-cpu-41-69.rst new file mode 100644 index 000000000..7bb73a769 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-start-return-cpu-41-69.rst @@ -0,0 +1,57 @@ +==================================== +Starting and stopping secondary CPUs +==================================== + +In this context, each thread is a CPU. That is, you start and stop threads of +CPUs. + +.. _OPAL_START_CPU: + +OPAL_START_CPU +============== + +.. code-block:: c + + #define OPAL_START_CPU 41 + + int64_t opal_start_cpu_thread(uint64_t server_no, uint64_t start_address); + +Returns +------- + +:ref:`OPAL_SUCCESS` + The CPU was instructed to start executing instructions from the specified + `start_address`. + This is an *asynchronous* operation, so it may take a short period of + time before the CPU actually starts at that address. +:ref:`OPAL_PARAMETER` + Invalid CPU. +:ref:`OPAL_WRONG_STATE` + If the CPU thread is not in OPAL, or is being re-initialized through :ref:`OPAL_REINIT_CPUS` +:ref:`OPAL_INTERNAL_ERROR` + Something else went horribly wrong. + +.. _OPAL_RETURN_CPU: + +OPAL_RETURN_CPU +=============== + +.. code-block:: c + + #define OPAL_RETURN_CPU 69 + + int64_t opal_return_cpu(void); + +When OPAL first starts the host, all secondary CPUs are spinning in OPAL. +To start them, one must call OPAL_START_CPU (you may want to OPAL_REINIT_CPUS +to set the HILE bit first). + +In cases where you need OPAL to do something for you across all CPUs, such +as OPAL_REINIT_CPUS, (on some platforms) a firmware update or get the machine +back into a similar state as to when the host OS was started (e.g. for kexec) +you may also need to return control of the CPU to OPAL. + + +Returns +------- +This call does **not return**. You need to OPAL_START_CPU. diff --git a/roms/skiboot/doc/opal-api/opal-sync-host-reboot-87.rst b/roms/skiboot/doc/opal-api/opal-sync-host-reboot-87.rst new file mode 100644 index 000000000..bc5605d31 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-sync-host-reboot-87.rst @@ -0,0 +1,25 @@ +.. _OPAL_SYNC_HOST_REBOOT: + +OPAL_SYNC_HOST_REBOOT +===================== + +.. code-block:: c + + #define OPAL_SYNC_HOST_REBOOT 87 + + static int64_t opal_sync_host_reboot(void); + +This OPAL call halts asynchronous operations in preparation for something +like kexec. It will halt DMA as well notification of some events (such +as a new error log being available for retreival). + +It's meant to be called in a loop until :ref:`OPAL_SUCCESS` is returned. + +Returns +------- +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_BUSY_EVENT` + not yet complete, call opal_sync_host_reboot() again, possibly with a short delay. +:ref:`OPAL_BUSY` + Call opal_poll_events() and then retry opal_sync_host_reboot diff --git a/roms/skiboot/doc/opal-api/opal-test-0.rst b/roms/skiboot/doc/opal-api/opal-test-0.rst new file mode 100644 index 000000000..107f5ce72 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-test-0.rst @@ -0,0 +1,44 @@ +.. _OPAL_TEST: + +OPAL_TEST +========= + +:ref:`OPAL_TEST` is a REQUIRED call for OPAL and conforming implementations MUST +have it. + +It is designed to test basic OPAL call functionality. + +Token: + +.. code-block:: c + + #define OPAL_TEST 0 + +Arguments +--------- +:: + + uint64_t arg + +Returns +------- +:: + + 0xfeedf00d + + +Function +-------- +:ref:`OPAL_TEST` MAY print a string to the OPAL log with the value of argument. + +For example, the reference implementation (skiboot) implements :ref:`OPAL_TEST` as: + +.. code-block:: c + + static uint64_t opal_test_func(uint64_t arg) + { + printf("OPAL: Test function called with arg 0x%llx\n", arg); + + return 0xfeedf00d; + } + diff --git a/roms/skiboot/doc/opal-api/opal-write-oppanel-async-95.rst b/roms/skiboot/doc/opal-api/opal-write-oppanel-async-95.rst new file mode 100644 index 000000000..6a3d73886 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-write-oppanel-async-95.rst @@ -0,0 +1,49 @@ +.. _OPAL_WRITE_OPPANEL_ASYNC: + +OPAL_WRITE_OPPANEL_ASYNC +======================== + +.. code-block:: c + + #define OPAL_WRITE_OPPANEL_ASYNC 95 + + typedef struct oppanel_line { + __be64 line; + __be64 line_len; + } oppanel_line_t; + + int64_t opal_write_oppanel_async(uint64_t async_token, + oppanel_line_t *lines, + uint64_t num_lines); + +Writes to a (possibly physical) Operator Panel. An Operator Panel contains +a small LCD screen (or similar) displaying a small amount of ASCII text. +It can be used to report on boot progress, failure, or witty messages from +a systems administrator. + +A typical panel, as present on IBM FSP based machines, is two lines of 16 +characters each. + +See :ref:`device-tree/ibm,opal/oppanel` for how the panel is described in the +device tree. Not all systems have an operator panel. + +Pass in an array of oppanel_line_t structs defining the ASCII characters +to display on each line of the oppanel. If there are two lines on the +physical panel, and you only want to write to the first line, you only +need to pass in one line. If you only want to write to the second line, +you need to pass in both lines, and set the line_len of the first line +to zero. + +Returns +------- +:ref:`OPAL_SUCCESS` + Success! Typically this is async operation, so immediate success is + unlikely. +:ref:`OPAL_ASYNC_COMPLETION` + Request submitted asynchronously. +:ref:`OPAL_PARAMETER` + Invalid `lines` or `num_lines` +:ref:`OPAL_NO_MEM` + Not enough free memory in OPAL to complete the request. +:ref:`OPAL_INTERNAL_ERROR` + Other internal error. diff --git a/roms/skiboot/doc/opal-api/opal-xscom-read-write-65-66.rst b/roms/skiboot/doc/opal-api/opal-xscom-read-write-65-66.rst new file mode 100644 index 000000000..f8006e643 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal-xscom-read-write-65-66.rst @@ -0,0 +1,88 @@ +.. _OPAL_XSCOM_READ: + +OPAL_XSCOM_READ +=============== + +.. code-block:: c + + #define OPAL_XSCOM_READ 65 + + int xscom_read(uint32_t partid, uint64_t pcb_addr, uint64_t *val); + +This low level call will read XSCOM values directly. + +They should only be used by low level manufacturing/debug tools. +"Normal" host OS kernel code should not know about XSCOM. + +This is also needed by HBRT/`opal-prd`. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_HARDWARE` + if operation failed +:ref:`OPAL_WRONG_STATE` + if CPU is asleep +:ref:`OPAL_XSCOM_BUSY` + Alias for :ref:`OPAL_BUSY`. +:ref:`OPAL_XSCOM_CHIPLET_OFF` + Alias for :ref:`OPAL_WRONG_STATE` +:ref:`OPAL_XSCOM_PARTIAL_GOOD` + XSCOM Partial Good +:ref:`OPAL_XSCOM_ADDR_ERROR` + XSCOM Address Error +:ref:`OPAL_XSCOM_CLOCK_ERROR` + XSCOM Clock Error +:ref:`OPAL_XSCOM_PARITY_ERROR` + XSCOM Parity Error +:ref:`OPAL_XSCOM_TIMEOUT` + XSCOM Timeout +:ref:`OPAL_XSCOM_CTR_OFFLINED` + XSCOM Controller Offlined due to too many errors. + +.. _OPAL_XSCOM_WRITE: + +OPAL_XSCOM_WRITE +================ + +.. code-block:: c + + #define OPAL_XSCOM_WRITE 66 + + int xscom_write(uint32_t partid, uint64_t pcb_addr, uint64_t val); + + +This low level call will write an XSCOM value directly. + +They should only be used by low level manufacturing/debug tools. +"Normal" host OS kernel code should not know about XSCOM. + +This is also needed by HBRT/`opal-prd`. + +Returns +------- + +:ref:`OPAL_SUCCESS` + Success! +:ref:`OPAL_HARDWARE` + if operation failed +:ref:`OPAL_WRONG_STATE` + if CPU is asleep +:ref:`OPAL_XSCOM_BUSY` + Alias for :ref:`OPAL_BUSY`. +:ref:`OPAL_XSCOM_CHIPLET_OFF` + Alias for :ref:`OPAL_WRONG_STATE` +:ref:`OPAL_XSCOM_PARTIAL_GOOD` + XSCOM Partial Good +:ref:`OPAL_XSCOM_ADDR_ERROR` + XSCOM Address Error +:ref:`OPAL_XSCOM_CLOCK_ERROR` + XSCOM Clock Error +:ref:`OPAL_XSCOM_PARITY_ERROR` + XSCOM Parity Error +:ref:`OPAL_XSCOM_TIMEOUT` + XSCOM Timeout +:ref:`OPAL_XSCOM_CTR_OFFLINED` + XSCOM Controller Offlined due to too many errors. diff --git a/roms/skiboot/doc/opal-api/opal_nx_coproc_init-167.rst b/roms/skiboot/doc/opal-api/opal_nx_coproc_init-167.rst new file mode 100644 index 000000000..b22c5a078 --- /dev/null +++ b/roms/skiboot/doc/opal-api/opal_nx_coproc_init-167.rst @@ -0,0 +1,36 @@ +.. _opal_nx_coproc_init: + +OPAL_NX_COPROC_INIT +=================== + +This OPAL call resets read offset and queued entries in high and normal +priority receive FIFO control registers. The kernel initializes read +offset entry in RXFIFO that it maintains during initialization. So this +register reset is needed for NX module reload or in kexec boot to make sure +read offset value matches with kernel entries. Otherwise NX reads requests +with wrong offset in RxFIFO which could cause NX request failures. + +The kernel initiates this call for each coprocessor type such as 842 and +GZIP per NX instance. + +Arguments +--------- +:: + + ``uint32_t chip_id`` + Contains value of the chip number identified at boot time. + + ``uint32_t pid`` + Contains NX coprocessor type (pid from the device tree). + +Returns +------- +OPAL_SUCCESS + The call to reset readOffset and queued entries for high and normal + FIFOs was successful. + +OPAL_PARAMETER + Indicates invalid chip ID or NX coprocessor type. + +OPAL_UNSUPPORTED + Not supported on P7 and P8. diff --git a/roms/skiboot/doc/opal-api/power9-changes.rst b/roms/skiboot/doc/opal-api/power9-changes.rst new file mode 100644 index 000000000..1163e2562 --- /dev/null +++ b/roms/skiboot/doc/opal-api/power9-changes.rst @@ -0,0 +1,39 @@ +POWER9 Changes to OPAL API +========================== + +This document is a summary of POWER9 changes to the OPAL API over what it +was for POWER7 and POWER8. As the POWER series of processors (at least up +to POWER9) require changes in the hypervisor to work on a new processor +generation, this gives us an opportunity with POWER9 to clean up several +parts of the OPAL API. + +Eventually, when the kernel drops support for POWER8 and before, we can then +remove the associated kernel code too. + +OPAL_REINIT_CPUS +---------------- +Can now be extended beyond HILE BE/LE bits. If invalid flags are set on +POWER9, OPAL_UNSUPPORTED will be returned. + +Device Tree +----------- + +- ``/ibm,opal/`` compatible property now just lists ``ibm,opal-v3`` and no longer ``ibm,opal-v2`` (power9 and above only) +- Use only ``stdout-path`` property from POWER9 and above as usage of ``linux,stdout-path`` is deprecated +- Rename ``fsp-ipl-side`` as ``sp-ipl-side`` in ``/ipl-params`` +- Add interrupt-parent property for ``/ibm,opal/ipmi`` node on POWER9 and above + to make use of OPAL irqchip rather than event interface in linux. + +TODO +---- +Things we still have to do for POWER9: + +- PCI to use async API rather than returning delays +- deprecate/remove v1 APIs where there's a V2 +- Fix this FWTS warning: :: + + FAILED [MEDIUM] DeviceTreeBaseDTCWarnings: Test 3, dtc reports warnings from + device tree: Warning (reg_format): "reg" property in /ibm,opal/flash@0 has + invalid length (8 bytes) (#address-cells == 0, #size-cells == 0) + +- Remove mi-version / ml-version from ``/ibm,opal/firmware`` and replace with something better and more portable diff --git a/roms/skiboot/doc/opal-api/return-codes.rst b/roms/skiboot/doc/opal-api/return-codes.rst new file mode 100644 index 000000000..296675d5a --- /dev/null +++ b/roms/skiboot/doc/opal-api/return-codes.rst @@ -0,0 +1,465 @@ +OPAL API Return Codes +===================== + +All OPAL calls return an integer relaying the success/failure of the OPAL +call. + +Success is typically indicated by OPAL_SUCCESS. Failure is always indicated +by a negative return code. + +Conforming host Operating Systems MUST handle return codes other than those +listed here. In future OPAL versions, additional return codes may be added. + +In the reference implementation (skiboot) these are all in `include/opal-api.h`_ + +.. _include/opal-api.h: https://github.com/open-power/skiboot/blob/master/include/opal-api.h + +There have been additions to the return codes from OPAL over time. A conforming +host OS should gracefully handle receiving a new error code for existing calls. + +An OS running on a POWER8 system only has to know about error codes that existed +when POWER8 with OPAL was introduced (indicated by YES in the POWER8 column below). +Additional OPAL error codes *may be returned on POWER8 systems* and as such OSs +need to gracefully handle unknown error codes. + +An OS running on POWER9 or above must handle all error codes as they were when +POWER9 was introduced. We use the placeholder "v1.0" version for +"since the dawn of time" even though there never was a skiboot v1.0 + ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| Name | Return Code | POWER8 GA | POWER9 GA | skiboot version where introduced | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_SUCCESS` | 0 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_PARAMETER` | -1 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_BUSY` | -2 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_PARTIAL` | -3 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_CONSTRAINED` | -4 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_CLOSED` | -5 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_HARDWARE` | -6 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_UNSUPPORTED` | -7 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_PERMISSION` | -8 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_NO_MEM` | -9 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_RESOURCE` | -10 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_INTERNAL_ERROR` | -11 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_BUSY_EVENT` | -12 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_HARDWARE_FROZEN` | -13 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_WRONG_STATE` | -14 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_ASYNC_COMPLETION` | -15 | YES | YES | v1.0 (initial release) | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_EMPTY` | -16 | NO | YES | v4.0 | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_TIMEOUT` | -17 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_INVALID_CMD` | -18 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_LBUS_PARITY` | -19 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_BKEND_OVERRUN` | -20 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_BKEND_ACCESS` | -21 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_ARBT_LOST` | -22 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_NACK_RCVD` | -23 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_I2C_STOP_ERR` | -24 | NO | YES | :ref:`skiboot-5.1.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_BUSY` | OPAL_BUSY | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_CHIPLET_OFF` | OPAL_WRONG_STATE | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_PARTIAL_GOOD` | -25 | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_ADDR_ERROR` | -26 | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_CLOCK_ERROR` | -27 | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_PARITY_ERROR` | -28 | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_TIMEOUT` | -29 | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XSCOM_CTR_OFFLINED` | -30 | NO | YES | :ref:`skiboot-5.4.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XIVE_PROVISIONING` | -31 | NO | YES | :ref:`skiboot-5.5.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_XIVE_FREE_ACTIVE` | -32 | NO | YES | :ref:`skiboot-5.5.0` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ +| :ref:`OPAL_TIMEOUT` | -33 | NO | YES | :ref:`skiboot-5.8` | ++--------------------------------+------------------+-----------+-----------+----------------------------------+ + + +The core set of return codes are: + +.. _OPAL_SUCCESS: + +OPAL_SUCCESS +------------ +.. code-block:: c + + #define OPAL_SUCCESS 0 + +Success! + +.. _OPAL_PARAMETER: + +OPAL_PARAMETER +-------------- +.. code-block:: c + + #define OPAL_PARAMETER -1 + +A parameter was invalid. This will also be returned if you call an +invalid OPAL call. To determine if a specific OPAL call is supported +or not, OPAL_CHECK_TOKEN should be called rather than relying on +OPAL_PARAMETER being returned for an invalid token. + +.. _OPAL_BUSY: + +OPAL_BUSY +--------- +.. code-block:: c + + #define OPAL_BUSY -2 + +Try again later. Related to `OPAL_BUSY_EVENT`, but `OPAL_BUSY` indicates that the +caller need not call `OPAL_POLL_EVENTS` itself. **TODO** Clarify current situation. + +.. _OPAL_PARTIAL: + +OPAL_PARTIAL +------------ +.. code-block:: c + + #define OPAL_PARTIAL -3 + +The operation partially succeeded. + +.. _OPAL_CONSTRAINED: + +OPAL_CONSTRAINED +---------------- +.. code-block:: c + + #define OPAL_CONSTRAINED -4 + +**FIXME** + +.. _OPAL_CLOSED: + +OPAL_CLOSED +----------- +.. code-block:: c + + #define OPAL_CLOSED -5 + +**FIXME** document these + +.. _OPAL_HARDWARE: + +OPAL_HARDWARE +------------- +.. code-block:: c + + #define OPAL_HARDWARE -6 + +**FIXME** document these + +.. _OPAL_UNSUPPORTED: + +OPAL_UNSUPPORTED +---------------- +.. code-block:: c + + #define OPAL_UNSUPPORTED -7 + +Unsupported operation. Non-fatal. + +.. _OPAL_PERMISSION: + +OPAL_PERMISSION +--------------- +.. code-block:: c + + #define OPAL_PERMISSION -8 + +Inadequate permission to perform the operation. + +.. _OPAL_NO_MEM: + +OPAL_NO_MEM +----------- +.. code-block:: c + + #define OPAL_NO_MEM -9 + +Indicates a temporary or permanent lack of adequate memory to perform the +operation. Ideally, this should never happen. Skiboot reserves a small amount +of memory for its heap and some operations (such as I2C requests) are allocated +from this heap. + +If this is ever hit, you should likely file a bug. + +.. _OPAL_RESOURCE: + +OPAL_RESOURCE +------------- +.. code-block:: c + + #define OPAL_RESOURCE -10 + +When trying to use a limited resource, OPAL found that there were none free. +While OPAL_BUSY indicates that OPAL may soon be able to proces the requent, +OPAL_RESOURCE is a more permanent error and while the resource *may* become +available again in the future, it is not certain that it will. + +.. _OPAL_INTERNAL_ERROR: + +OPAL_INTERNAL_ERROR +------------------- +.. code-block:: c + + #define OPAL_INTERNAL_ERROR -11 + +Something has gone wrong inside OPAL. This is likely a bug somewhere and we +return OPAL_INTERNAL_ERROR for safety. + +.. _OPAL_BUSY_EVENT: + +OPAL_BUSY_EVENT +--------------- +.. code-block:: c + + #define OPAL_BUSY_EVENT -12 + +The same as `OPAL_BUSY` but signals that the OS should call `OPAL_POLL_EVENTS` as +that may be required to get into a state where the call will succeed. + +.. _OPAL_HARDWARE_FROZEN: + +OPAL_HARDWARE_FROZEN +-------------------- +.. code-block:: c + + #define OPAL_HARDWARE_FROZEN -13 + +.. _OPAL_WRONG_STATE: + +OPAL_WRONG_STATE +---------------- +.. code-block:: c + + #define OPAL_WRONG_STATE -14 + +The requested operation requires a (hardware or software) component to be in +a different state. For example, you cannot call OPAL_START_CPU on a CPU that +is not currently in OPAL. + +.. _OPAL_ASYNC_COMPLETION: + +OPAL_ASYNC_COMPLETION +--------------------- +.. code-block:: c + + #define OPAL_ASYNC_COMPLETION -15 + +For asynchronous calls, successfully queueing/starting executing the +command is indicated by the OPAL_ASYNC_COMPLETION return code. +pseudo-code for an async call: :: + + token = opal_async_get_token(); + rc = opal_async_example(foo, token); + if (rc != OPAL_ASYNC_COMPLETION) + handle_error(rc); + rc = opal_async_wait(token); + // handle result here + +.. _OPAL_EMPTY: + +OPAL_EMPTY +---------- +.. code-block:: c + + #define OPAL_EMPTY -16 + +The call was successful and the correct result is empty. For example, the +OPAL_IPMI_RECV call can succeed and return that there is no waiting IPMI +message. + +.. _OPAL_I2C_TIMEOUT: + +OPAL_I2C_TIMEOUT +---------------- +.. code-block:: c + + #define OPAL_I2C_TIMEOUT -17 + + +.. _OPAL_I2C_INVALID_CMD: + +OPAL_I2C_INVALID +---------------- +.. code-block:: c + + #define OPAL_I2C_INVALID_CMD -18 + + +.. _OPAL_I2C_LBUS_PARITY: + +OPAL_I2C_LBUS_PARITY +-------------------- +.. code-block:: c + + #define OPAL_I2C_LBUS_PARITY -19 + + +.. _OPAL_I2C_BKEND_OVERRUN: + +OPAL_I2C_BKEND_OVERRUN +---------------------- +.. code-block:: c + + #define OPAL_I2C_BKEND_OVERRUN -20 + + +.. _OPAL_I2C_BKEND_ACCESS: + +OPAL_I2C_BKEND_ACCESS +--------------------- +.. code-block:: c + + #define OPAL_I2C_BKEND_ACCESS -21 + +.. _OPAL_I2C_ARBT_LOST: + +OPAL_I2C_ARBT_LOST +------------------ +.. code-block:: c + + #define OPAL_I2C_ARBT_LOST -22 + +.. _OPAL_I2C_NACK_RCVD: + +OPAL_I2C_NACK_RCVD +------------------ +.. code-block:: c + + #define OPAL_I2C_NACK_RCVD -23 + +.. _OPAL_I2C_STOP_ERR: + +OPAL_I2C_STOP_ERR +----------------- +.. code-block:: c + + #define OPAL_I2C_STOP_ERR -24 + + +.. _OPAL_XSCOM_BUSY: + +OPAL_XSCOM_BUSY +--------------- + +An alias for :ref:`OPAL_BUSY` + +.. _OPAL_XSCOM_CHIPLET_OFF: + +OPAL_XSCOM_CHIPLET_OFF +---------------------- + +An alias for :ref:`OPAL_WRONG_STATE` + +.. _OPAL_XSCOM_PARTIAL_GOOD: + +OPAL_XSCOM_PARTIAL_GOOD +----------------------- + +.. code-block:: c + + #define OPAL_XSCOM_PARTIAL_GOOD -25 + +.. _OPAL_XSCOM_ADDR_ERROR: + +OPAL_XSCOM_ADDR_ERROR +--------------------- + +.. code-block:: c + + #define OPAL_XSCOM_ADDR_ERROR -26 + +.. _OPAL_XSCOM_CLOCK_ERROR: + +OPAL_XSCOM_CLOCK_ERROR +---------------------- + +.. code-block:: c + + #define OPAL_XSCOM_CLOCK_ERROR -27 + +.. _OPAL_XSCOM_PARITY_ERROR: + +OPAL_XSCOM_PARITY_ERROR +----------------------- + +.. code-block:: c + + #define OPAL_XSCOM_PARITY_ERROR -28 + +.. _OPAL_XSCOM_TIMEOUT: + +OPAL_XSCOM_TIMEOUT +------------------ + +.. code-block:: c + + #define OPAL_XSCOM_TIMEOUT -29 + +.. _OPAL_XSCOM_CTR_OFFLINED: + +OPAL_XSCOM_CTR_OFFLINED +----------------------- + +.. code-block:: c + + #define OPAL_XSCOM_CTR_OFFLINED -30 + +.. _OPAL_XIVE_PROVISIONING: + +OPAL_XIVE_PROVISIONING +---------------------- + +.. code-block:: c + + #define OPAL_XIVE_PROVISIONING -31 + +.. _OPAL_XIVE_FREE_ACTIVE: + +OPAL_XIVE_FREE_ACTIVE +--------------------- + +.. code-block:: c + + #define OPAL_XIVE_FREE_ACTIVE -32 + +.. _OPAL_TIMEOUT: + +OPAL_TIMEOUT +------------ + +.. code-block:: c + + #define OPAL_TIMEOUT -33 |