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