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