1OPAL Console calls
2==================
3
4There are four OPAL calls relating to the OPAL console:
5
6+---------------------------------------------+--------------+------------------------+----------+-----------------+
7| Name                                        | API Token ID | Introduced             | Required | Notes           |
8|                                             |              |                        | as of    |                 |
9+---------------------------------------------+--------------+------------------------+----------+-----------------+
10| :ref:`OPAL_CONSOLE_WRITE`                   |   1          | v1.0 (Initial Release) | POWER8   |                 |
11+---------------------------------------------+--------------+------------------------+----------+-----------------+
12| :ref:`OPAL_CONSOLE_READ`                    |   2          | v1.0 (Initial Release) | POWER8   |                 |
13+---------------------------------------------+--------------+------------------------+----------+-----------------+
14| :ref:`OPAL_CONSOLE_WRITE_BUFFER_SPACE`      |  25          | v1.0 (Initial Release) | POWER8   |                 |
15+---------------------------------------------+--------------+------------------------+----------+-----------------+
16| :ref:`OPAL_CONSOLE_FLUSH`                   | 117          | :ref:`skiboot-5.1.13`  | POWER9   |                 |
17+---------------------------------------------+--------------+------------------------+----------+-----------------+
18
19The OPAL console calls can support multiple consoles. Each console MUST
20be represented in the device tree.
21
22A conforming implementation SHOULD have at least one console. It is valid
23for it to simply be an in-memory buffer and only support writing.
24
25[TODO: details on device tree specs for console]
26
27.. _OPAL_CONSOLE_WRITE:
28
29OPAL_CONSOLE_WRITE
30------------------
31
32Parameters: ::
33
34  int64_t term_number
35  int64_t *length,
36  const uint8_t *buffer
37
38Returns:
39
40 - :ref:`OPAL_SUCCESS`
41 - :ref:`OPAL_PARAMETER` on invalid term_number
42 - :ref:`OPAL_CLOSED` if console device closed
43 - :ref:`OPAL_BUSY_EVENT` if unable to write any of buffer
44
45``term_number`` is the terminal number as represented in the device tree.
46``length`` is a pointer to the length of buffer.
47
48A conforming implementation SHOULD try to NOT do partial writes, although
49partial writes and not writing anything are valid.
50
51.. _OPAL_CONSOLE_WRITE_BUFFER_SPACE:
52
53OPAL_CONSOLE_WRITE_BUFFER_SPACE
54-------------------------------
55
56Parameters: ::
57
58  int64_t term_number
59  int64_t *length
60
61Returns:
62
63 - :ref:`OPAL_SUCCESS`
64 - :ref:`OPAL_PARAMETER` on invalid term_number
65
66Returns the available buffer length for OPAL_CONSOLE_WRITE in ``length``.
67This call can be used to help work out if there is sufficient buffer
68space to write your full message to the console with OPAL_CONSOLE_WRITE.
69
70.. _OPAL_CONSOLE_READ:
71
72OPAL_CONSOLE_READ
73-----------------
74
75Parameters: ::
76
77  int64_t term_number
78  int64_t *length
79  uint8_t *buffer
80
81Returns:
82
83 - :ref:`OPAL_SUCCESS`
84 - :ref:`OPAL_PARAMETER` on invalid term_number
85 - :ref:`OPAL_CLOSED`
86
87Use :ref:`OPAL_POLL_EVENTS` for how to determine
88
89.. _OPAL_CONSOLE_FLUSH:
90
91OPAL_CONSOLE_FLUSH
92------------------
93
94Parameters: ::
95
96  int64_t term_number
97
98Returns:
99
100 - :ref:`OPAL_SUCCESS`
101 - :ref:`OPAL_UNSUPPORTED` if the console does not implement a flush call
102 - :ref:`OPAL_PARAMETER` on invalid term_number
103 - :ref:`OPAL_PARTIAL` if more to flush, call again
104 - :ref:`OPAL_BUSY` if nothing was flushed this call
105