[Skiboot] [RFC PATCH 18/23] doc/opal-api: fix ReStructured Text syntax
Stewart Smith
stewart at linux.vnet.ibm.com
Wed Jul 27 17:43:19 AEST 2016
Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
doc/opal-api/opal-cec-power-down-5.rst | 36 +++++---
doc/opal-api/opal-cec-reboot-6-116.rst | 46 ++++++----
doc/opal-api/opal-check-token-80.rst | 14 +--
doc/opal-api/opal-code-update-76-77-78.rst | 87 +++++++++++-------
doc/opal-api/opal-console-read-write-1-2.rst | 72 ++++++++-------
doc/opal-api/opal-flash-110-111-112.rst | 40 ++++----
doc/opal-api/opal-get-device-tree-118.rst | 30 ++++--
doc/opal-api/opal-get-msg-85.rst | 37 ++++----
doc/opal-api/opal-get-msi-39-40.rst | 45 +++++----
doc/opal-api/opal-get-xive-20.rst | 28 +++---
doc/opal-api/opal-handle-interrupt.rst | 17 ++--
doc/opal-api/opal-int-eoi-124.rst | 11 ++-
doc/opal-api/opal-int-get-xirr-122.rst | 9 +-
doc/opal-api/opal-int-set-cppr-123.rst | 11 ++-
doc/opal-api/opal-int-set-mfrr-125.rst | 11 ++-
doc/opal-api/opal-invalid-call--1.rst | 4 +-
doc/opal-api/opal-led-get-set-114-115.rst | 47 +++++-----
doc/opal-api/opal-messages.rst | 86 ++++++++++--------
doc/opal-api/opal-pci-get-phb-diag-data2-64.rst | 42 ++++++---
doc/opal-api/opal-pci-get-power-state-120.rst | 29 ++++--
doc/opal-api/opal-pci-get-presence-state-119.rst | 29 ++++--
.../opal-pci-get-set-xive-reissue-35-36.rst | 9 +-
doc/opal-api/opal-pci-map-pe-dma-window-44.rst | 64 +++++++------
.../opal-pci-map-pe-dma-window-real-45.rst | 40 ++++----
doc/opal-api/opal-pci-map-pe-mmio-window-29.rst | 37 +++++---
doc/opal-api/opal-pci-phb-mmio-enable-27.rst | 27 +++---
doc/opal-api/opal-pci-set-mve-33.rst | 27 +++---
doc/opal-api/opal-pci-set-mve-enable-34.rst | 28 +++---
doc/opal-api/opal-pci-set-pe-31.rst | 101 ++++++++++++---------
doc/opal-api/opal-pci-set-peltv-32.rst | 62 +++++++------
doc/opal-api/opal-pci-set-phb-mem-window-28.rst | 68 ++++++++------
doc/opal-api/opal-pci-set-power-state-121.rst | 44 ++++++---
doc/opal-api/opal-pci-set-xive-pe-37.rst | 27 +++---
doc/opal-api/opal-pci-tce-kill-126.rst | 46 ++++++----
doc/opal-api/opal-poll-events.rst | 11 +--
doc/opal-api/opal-prd-msg-113.rst | 12 +--
doc/opal-api/opal-read-write-tpo-103-104.rst | 8 +-
doc/opal-api/opal-register-dump-region-101.rst | 20 ++--
doc/opal-api/opal-reinit-cpus-70.rst | 26 ++++--
doc/opal-api/opal-return-cpu-69.rst | 10 +-
doc/opal-api/opal-rtc-read-3.rst | 72 +++++++++------
doc/opal-api/opal-rtc-write-4.rst | 2 +-
doc/opal-api/opal-sensor-read-88.rst | 48 +++++++---
doc/opal-api/opal-set-xive-19.rst | 29 +++---
doc/opal-api/opal-sync-host-reboot-87.rst | 17 +++-
doc/opal-api/opal-test-0.rst | 30 +++---
doc/opal-api/opal-unregister-dump-region-102.rst | 5 +-
doc/opal-api/opal-xscom-read-write-65-66.rst | 22 +++--
48 files changed, 961 insertions(+), 662 deletions(-)
diff --git a/doc/opal-api/opal-cec-power-down-5.rst b/doc/opal-api/opal-cec-power-down-5.rst
index d18912a..6daea3d 100644
--- a/doc/opal-api/opal-cec-power-down-5.rst
+++ b/doc/opal-api/opal-cec-power-down-5.rst
@@ -1,13 +1,16 @@
OPAL_CEC_POWER_DOWN
--------------------
+===================
+::
-#define OPAL_CEC_POWER_DOWN 5
+ #define OPAL_CEC_POWER_DOWN 5
-int64 opal_cec_power_down(uint64 request)
+ int64 opal_cec_power_down(uint64 request)
-Arguments:
+Arguments
+---------
+::
- uint64 request values as follows:
+ uint64 request values as follows:
0 - Power down normally
1 - Power down immediately
@@ -17,9 +20,20 @@ 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:
-OPAL_SUCCESS: the power down was updated successful
-OPAL_BUSY: unable to power down, try again later
-OPAL_PARAMETER: a parameter was incorrect
-OPAL_INTERNAL_ERROR: hal code sent incorrect data to hardware device
-OPAL_UNSUPPORTED: this platform does not support being powered off.
+Return Values
+-------------
+
+``OPAL_SUCCESS``
+ the power down was updated successful
+
+``OPAL_BUSY``
+ unable to power down, try again later
+
+``OPAL_PARAMETER``
+ a parameter was incorrect
+
+``OPAL_INTERNAL_ERROR``
+ hal code sent incorrect data to hardware device
+
+``OPAL_UNSUPPORTED``
+ this platform does not support being powered off.
diff --git a/doc/opal-api/opal-cec-reboot-6-116.rst b/doc/opal-api/opal-cec-reboot-6-116.rst
index 4d2b2ca..db7cd83 100644
--- a/doc/opal-api/opal-cec-reboot-6-116.rst
+++ b/doc/opal-api/opal-cec-reboot-6-116.rst
@@ -1,42 +1,50 @@
OPAL_CEC_REBOOT and OPAL_CEC_REBOOT2
-------------------------------------
+====================================
+::
-#define OPAL_CEC_REBOOT 6
-#define OPAL_CEC_REBOOT2 116
+ #define OPAL_CEC_REBOOT 6
+ #define OPAL_CEC_REBOOT2 116
There are two opal calls to invoke system reboot.
-OPAL_CEC_REBOOT: Used for normal reboot by Linux host.
-OPAL_CEC_REBOOT2: Newly introduced to handle abnormal system reboots.
-The Linux kernel will make this OPAL call when it has to terminate
-abruptly due to an anomalous condition. The kernel will push some system
-state context to OPAL, which will in turn push it down to the BMC for
-further analysis.
+``OPAL_CEC_REBOOT``
+ Used for normal reboot by Linux host.
+
+``OPAL_CEC_REBOOT2``
+ Newly introduced to handle abnormal system reboots.
+ The Linux kernel will make this OPAL call when it has to terminate
+ abruptly due to an anomalous condition. The kernel will push some system
+ state context to OPAL, which will in turn push it down to the BMC for
+ further analysis.
OPAL_CEC_REBOOT
---------------
-Syntax:
-int64_t opal_cec_reboot(void)
+Syntax: ::
-Input parameters:
-None.
+ int64_t opal_cec_reboot(void)
System reboots normally.
OPAL_CEC_REBOOT2
----------------
-Syntax:
-int64_t opal_cec_reboot2(uint32_t reboot_type, char *diag)
+Syntax: ::
+
+ int64_t opal_cec_reboot2(uint32_t reboot_type, char *diag)
-Input parameters:
- @reboot_type Type of reboot. (see below)
- @diag Null-terminated string.
+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 reboot.
Supported reboot types:
-----------------------
+-----------------------
+
OPAL_REBOOT_NORMAL = 0
Behavior is as similar to that of opal_cec_reboot()
diff --git a/doc/opal-api/opal-check-token-80.rst b/doc/opal-api/opal-check-token-80.rst
index 4c5f7c3..fb63179 100644
--- a/doc/opal-api/opal-check-token-80.rst
+++ b/doc/opal-api/opal-check-token-80.rst
@@ -1,5 +1,5 @@
OPAL_CHECK_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
@@ -7,16 +7,16 @@ OPAL implementations/platforms.
One parameter is accepted: the OPAL token number.
-OPAL_CHECK_TOKEN will return:
+``OPAL_CHECK_TOKEN`` will return: ::
-enum OpalCheckTokenStatus {
- OPAL_TOKEN_ABSENT = 0,
- OPAL_TOKEN_PRESENT = 1
-};
+ 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.
+``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
diff --git a/doc/opal-api/opal-code-update-76-77-78.rst b/doc/opal-api/opal-code-update-76-77-78.rst
index e7657d1..91037d6 100644
--- a/doc/opal-api/opal-code-update-76-77-78.rst
+++ b/doc/opal-api/opal-code-update-76-77-78.rst
@@ -1,7 +1,7 @@
Code Update on FSP based machine
================================
-There are three OPAL calls for code update on FSP based machine:
+There are three OPAL calls for code update on FSP based machine: ::
#define OPAL_FLASH_VALIDATE 76
#define OPAL_FLASH_MANAGE 77
@@ -9,8 +9,10 @@ There are three OPAL calls for code update on FSP based machine:
OPAL_FLASH_VALIDATE
-------------------
- Validate new image is valid for this platform or not. We do below
- validation in OPAL:
+
+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?.
@@ -21,48 +23,63 @@ OPAL_FLASH_VALIDATE
- 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
+Input
+^^^^^
+buffer
+ First 4k bytes of new image
+
+size
+ Input buffer size
+
+Output
+^^^^^^
- 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.
+buffer
+ Output result (current and new image version details)
- Return value:
- Validation status
+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
-----------------
- 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.
+Commit/Reject 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.
+ - 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.
- Input
- op : Operation (1 : Commit /0 : Reject)
+**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.
- Return value:
+Input
+^^^^^
+op
+ Operation (1 : Commit /0 : Reject)
+
+Return value
Commit operation status (0 : Success)
OPAL_FLASH_UPDATE
------------------
- Update new image. It only sets the flag, actual update happens
- during system reboot/shutdown.
+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.
- 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 :
- FW update flow :
- if (running side == T)
Swap P & T side
- Start code update
@@ -71,8 +88,10 @@ OPAL_FLASH_UPDATE
- Code update complete
- Deep IPL
- Input
- list : Real address of image scatter/gather list of the FW image
+Input
+^^^^^
+list
+ Real address of image scatter/gather list of the FW image
- Return value:
- Update operation status (0: update requested)
+Return value:
+ Update operation status (0: update requested)
diff --git a/doc/opal-api/opal-console-read-write-1-2.rst b/doc/opal-api/opal-console-read-write-1-2.rst
index 26f9a16..43b5f9d 100644
--- a/doc/opal-api/opal-console-read-write-1-2.rst
+++ b/doc/opal-api/opal-console-read-write-1-2.rst
@@ -1,12 +1,12 @@
OPAL Console calls
-------------------
+==================
-There are four OPAL calls relating to the OPAL console:
+There are four OPAL calls relating to the OPAL console: ::
-#define OPAL_CONSOLE_WRITE 1
-#define OPAL_CONSOLE_READ 2
-#define OPAL_CONSOLE_WRITE_BUFFER_SPACE 25
-#define OPAL_CONSOLE_FLUSH 117
+ #define OPAL_CONSOLE_WRITE 1
+ #define OPAL_CONSOLE_READ 2
+ #define OPAL_CONSOLE_WRITE_BUFFER_SPACE 25
+ #define OPAL_CONSOLE_FLUSH 117
The OPAL console calls can support multiple consoles. Each console MUST
be represented in the device tree.
@@ -19,16 +19,18 @@ for it to simply be an in-memory buffer and only support writing.
OPAL_CONSOLE_WRITE
------------------
-Parameters:
- int64_t term_number
- int64_t *length,
- const uint8_t *buffer
+Parameters: ::
-Returns:
- OPAL_SUCCESS
- OPAL_PARAMETER - invalid term_number
- OPAL_CLOSED - console device closed
- OPAL_BUSY_EVENT - unable to write any of buffer
+ int64_t term_number
+ int64_t *length,
+ const uint8_t *buffer
+
+Returns: ::
+
+ OPAL_SUCCESS
+ OPAL_PARAMETER - invalid term_number
+ OPAL_CLOSED - console device closed
+ OPAL_BUSY_EVENT - 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.
@@ -39,13 +41,15 @@ partial writes and not writing anything are valid.
OPAL_CONSOLE_WRITE_BUFFER_SPACE
-------------------------------
-Parameters:
- int64_t term_number
- int64_t *length
+Parameters: ::
-Returns:
- OPAL_SUCCESS
- OPAL_PARAMETER - invalid term_number
+ int64_t term_number
+ int64_t *length
+
+Returns: ::
+
+ OPAL_SUCCESS
+ OPAL_PARAMETER - 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
@@ -54,25 +58,29 @@ space to write your full message to the console with OPAL_CONSOLE_WRITE.
OPAL_CONSOLE_READ
-----------------
-Parameters:
- int64_t term_number
- int64_t *length
- uint8_t *buffer
+Parameters: ::
-Returns:
- OPAL_SUCCESS
- OPAL_PARAMETER - invalid term_number
- OPAL_CLOSED
+ int64_t term_number
+ int64_t *length
+ uint8_t *buffer
+
+Returns: ::
+
+ OPAL_SUCCESS
+ OPAL_PARAMETER - invalid term_number
+ OPAL_CLOSED
Use OPAL_POLL_EVENTS for how to determine
OPAL_CONSOLE_FLUSH
------------------
-Parameters:
- int64_t term_number
+Parameters: ::
+
+ int64_t term_number
+
+Returns: ::
-Returns:
OPAL_SUCCESS
OPAL_UNSUPPORTED - the console does not implement a flush call
OPAL_PARAMETER - invalid term_number
diff --git a/doc/opal-api/opal-flash-110-111-112.rst b/doc/opal-api/opal-flash-110-111-112.rst
index 860172b..51bdb6c 100644
--- a/doc/opal-api/opal-flash-110-111-112.rst
+++ b/doc/opal-api/opal-flash-110-111-112.rst
@@ -1,15 +1,14 @@
-
OPAL Flash calls
-----------------
+================
-There are three OPAL calls for interacting with flash devices:
+There are three OPAL calls for interacting with flash devices: ::
#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 much match an ID found in the corresponding ibm,opal/flash at n
+parameter, which much match an ID found in the corresponding ``ibm,opal/flash at n``
device tree node. See doc/device-tree/ibm,opal/flash.txt for details of
the device tree bindings.
@@ -17,19 +16,26 @@ 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 OPAL_ASYNC_COMPLETION, and an
+success, the calls will return ``OPAL_ASYNC_COMPLETION``, and an
opal_async_completion message will be sent (with the appropriate token
argument) when the operation completes.
All calls share the same return values:
- OPAL_ASYNC_COMPLETION - operation started, an async completion will
- be triggered with the @token argument
- OPAL_PARAMETER - invalid flash id
- OPAL_PARAMETER - invalid size or offset (alignment, or access beyond end
- of device)
- OPAL_BUSY - flash in use
- OPAL_HARDWARE - error accessing flash device
+``OPAL_ASYNC_COMPLETION``
+ operation started, an async completion will be triggered with the ``token`` argument
+
+OPAL_PARAMETER
+ invalid flash id
+
+OPAL_PARAMETER
+ invalid size or offset (alignment, or access beyond end of device)
+
+OPAL_BUSY
+ flash in use
+
+OPAL_HARDWARE
+ error accessing flash device
OPAL_FLASH_READ
---------------
@@ -45,9 +51,10 @@ 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
----------------
+----------------
+
+Parameters: ::
-Parameters:
uint64_t id
uint64_t offset
uint64_t size
@@ -57,9 +64,10 @@ Erases the specified flash id, at the specified offset and size. Will trigger
an async completion with token when completed.
OPAL_FLASH_WRITE
----------------
+----------------
+
+Parameters: ::
-Parameters:
uint64_t id
uint64_t offset
uint64_t buffer
diff --git a/doc/opal-api/opal-get-device-tree-118.rst b/doc/opal-api/opal-get-device-tree-118.rst
index 235a321..af3fdf7 100644
--- a/doc/opal-api/opal-get-device-tree-118.rst
+++ b/doc/opal-api/opal-get-device-tree-118.rst
@@ -1,9 +1,10 @@
OPAL_GET_DEVICE_TREE
---------------------
+====================
-Get device sub-tree
+Get device sub-tree.
+
+Parameters: ::
-Parameters:
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
@@ -16,9 +17,20 @@ in hardware (e.g. PCI hotplug).
Return Codes:
-FDT blob size - returned FDT blob buffer size when @buf is NULL
-OPAL_SUCCESS - FDT blob is created successfully
-OPAL_PARAMETER - invalid argument @phandle or @len
-OPAL_INTERNAL_ERROR - failure creating FDT blob when calculating its size
-OPAL_NO_MEM - not enough room in buffer for device sub-tree
-OPAL_EMPTY - failure creating FDT blob
+FDT blob size
+ returned FDT blob buffer size when ``buf`` is NULL
+
+OPAL_SUCCESS
+ FDT blob is created successfully
+
+OPAL_PARAMETER
+ invalid argument @phandle or @len
+
+OPAL_INTERNAL_ERROR
+ failure creating FDT blob when calculating its size
+
+OPAL_NO_MEM
+ not enough room in buffer for device sub-tree
+
+OPAL_EMPTY
+ failure creating FDT blob
diff --git a/doc/opal-api/opal-get-msg-85.rst b/doc/opal-api/opal-get-msg-85.rst
index fa839a8..17c2557 100644
--- a/doc/opal-api/opal-get-msg-85.rst
+++ b/doc/opal-api/opal-get-msg-85.rst
@@ -1,15 +1,16 @@
OPAL_GET_MSG
-------------
+============
OPAL_GET_MSG will get the next pending OPAL Message (see
opal-messages.txt).
-Parameters:
+Parameters: ::
+
buffer to copy message into
sizeof buffer to copy message into
The maximum size of an opal message is specified in the device tree passed
-to the host OS:
+to the host OS: ::
ibm,opal {
opal-msg-size = <0x48>;
@@ -24,20 +25,24 @@ 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:
+Return values
+-------------
-OPAL_RESOURCE - no available message.
+OPAL_RESOURCE
+ no available message.
-OPAL_PARAMETER - buffer is NULL or size is < 72 bytes.
- If buffer size < 72 bytes, the message will NOT be discarded
- by OPAL.
+OPAL_PARAMETER
+ buffer is NULL or size is < 72 bytes.
+ If buffer size < 72 bytes, the message will NOT be discarded by OPAL.
-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.
+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.
-OPAL_SUCCESS - message successfully copied to buffer.
+OPAL_SUCCESS
+ message successfully copied to buffer.
diff --git a/doc/opal-api/opal-get-msi-39-40.rst b/doc/opal-api/opal-get-msi-39-40.rst
index dbc809f..14bd980 100644
--- a/doc/opal-api/opal-get-msi-39-40.rst
+++ b/doc/opal-api/opal-get-msi-39-40.rst
@@ -1,10 +1,11 @@
OPAL_GET_MSI_32 and OPAL_GET_MSI_64
------------------------------------
+===================================
+::
-#define OPAL_GET_MSI_32 39
-#define OPAL_GET_MSI_64 40
+ #define OPAL_GET_MSI_32 39
+ #define OPAL_GET_MSI_64 40
-WARNING: following documentation is from old sources, and is possibly
+**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.
@@ -14,22 +15,26 @@ 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.
- The phb_id parameter is the value from the PHB node ibm,opal-phbid
- property.
-
- 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.
-
- 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.
-
- 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 opal_parameter for values outside of this range.
+``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 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
diff --git a/doc/opal-api/opal-get-xive-20.rst b/doc/opal-api/opal-get-xive-20.rst
index 2a83cc8..2d56a3a 100644
--- a/doc/opal-api/opal-get-xive-20.rst
+++ b/doc/opal-api/opal-get-xive-20.rst
@@ -1,25 +1,31 @@
OPAL_GET_XIVE
--------------
+=============
+::
-#define OPAL_GET_XIVE 20
+ #define OPAL_GET_XIVE 20
-WARNING: following documentation is from old sources, and is possibly
+**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 return the POWER XIVE server and priority
values currently set in a PHB XIVE.
- The phb_id parameter is the value from the PHB node ibm,opal-phbid
- property.
+``phb_id``
+ The ``phb_id`` parameter is the value from the PHB node ``ibm,opal-phbid``
+ property.
- The xive_number is the index of an XIVE that corresponds to a particular
- interrupt
+``xive_number``
+ The ``xive_number`` is the index of an XIVE that corresponds to a particular
+ interrupt.
- the server_number returns the server (processor) that is set in this XIVE
+``server_number``
+ the ``server_number`` returns the server (processor) that is set in this XIVE
- the priority returns the interrupt priority value that is set in this XIVE
+``priority``
+ the ``priority`` returns the interrupt priority value that is set in this XIVE
- This call returns the server and priority numbers from within the XIVE
- specified by the XIVE_number.
+
+This call returns the server and priority numbers from within the XIVE
+specified by the XIVE_number.
diff --git a/doc/opal-api/opal-handle-interrupt.rst b/doc/opal-api/opal-handle-interrupt.rst
index efae29e..8f53a49 100644
--- a/doc/opal-api/opal-handle-interrupt.rst
+++ b/doc/opal-api/opal-handle-interrupt.rst
@@ -1,10 +1,10 @@
OPAL_HANDLE_INTERRUPT
----------------------
+=====================
-The host OS must pass all interrupts in "ibm,opal/opal-interrupts" in the
+The host OS must pass all interrupts in ``ibm,opal/opal-interrupts`` in the
device tree to OPAL.
-An example dt snippet is:
+An example dt snippet is: ::
ibm,opal {
...
@@ -12,14 +12,15 @@ An example dt snippet is:
}
When the host OS gets any of these interrupts, it must call
-OPAL_HANDLE_INTERRUPT.
+``OPAL_HANDLE_INTERRUPT``.
-The OPAL_HANDLE_INTERRUPT call takes two parameters, one input and one output.
+The ``OPAL_HANDLE_INTERRUPT`` call takes two parameters, one input and one output.
-uint32_t isn - the interrupt
+``uint32_t isn``
+ the interrupt
-uint64_t *outstanding_event_mask - returns outstanding events for host
- OS to handle
+``uint64_t *outstanding_event_mask``
+ returns outstanding events for host OS to handle
The host OS should then handle any outstanding events.
diff --git a/doc/opal-api/opal-int-eoi-124.rst b/doc/opal-api/opal-int-eoi-124.rst
index 17e4eff..ec5bdd2 100644
--- a/doc/opal-api/opal-int-eoi-124.rst
+++ b/doc/opal-api/opal-int-eoi-124.rst
@@ -1,11 +1,12 @@
OPAL_INT_EOI
-------------
+============
+::
-static int64_t opal_xive_eoi(uint32_t xirr)
+ static int64_t opal_xive_eoi(uint32_t xirr)
-Not yet implemented.
+**Not yet implemented.**
-Modelled on the H_EOI PAPR call.
+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
@@ -15,6 +16,6 @@ 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
+For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must
exist in the device tree. If OPAL does not create such a device, the host
OS MUST NOT use this call.
diff --git a/doc/opal-api/opal-int-get-xirr-122.rst b/doc/opal-api/opal-int-get-xirr-122.rst
index efa86d5..b79be6f 100644
--- a/doc/opal-api/opal-int-get-xirr-122.rst
+++ b/doc/opal-api/opal-int-get-xirr-122.rst
@@ -1,15 +1,16 @@
OPAL_INT_GET_XIRR
------------------
+=================
+::
-int64_t opal_xive_get_xirr(uint32_t *out_xirr, bool just_poll)
+ int64_t opal_xive_get_xirr(uint32_t *out_xirr, bool just_poll)
-Not yet implemented.
+**Not yet implemented.**
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
+For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must
exist in the device tree. If OPAL does not create such a device, the host
OS MUST NOT use this call.
diff --git a/doc/opal-api/opal-int-set-cppr-123.rst b/doc/opal-api/opal-int-set-cppr-123.rst
index b6858c9..ad1e5a4 100644
--- a/doc/opal-api/opal-int-set-cppr-123.rst
+++ b/doc/opal-api/opal-int-set-cppr-123.rst
@@ -1,16 +1,17 @@
OPAL_INT_SET_CPPR
------------------
+=================
+::
-static int64_t opal_xive_set_cppr(uint8_t cppr)
+ static int64_t opal_xive_set_cppr(uint8_t cppr)
-Not yet implemented.
+**Not yet implemented.**
-Modelled on the H_CPPR PAPR call.
+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
+For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must
exist in the device tree. If OPAL does not create such a device, the host
OS MUST NOT use this call.
diff --git a/doc/opal-api/opal-int-set-mfrr-125.rst b/doc/opal-api/opal-int-set-mfrr-125.rst
index 64a7506..46b0902 100644
--- a/doc/opal-api/opal-int-set-mfrr-125.rst
+++ b/doc/opal-api/opal-int-set-mfrr-125.rst
@@ -1,15 +1,16 @@
OPAL_INT_SET_MFRR
------------------
+=================
+::
-static int64_t opal_xive_set_mfrr(uint32_t cpu, uint8_t mfrr)
+ static int64_t opal_xive_set_mfrr(uint32_t cpu, uint8_t mfrr)
-Not yet implemented.
+**Not yet implemented.**
-Modelled on the H_IPI PAPR call.
+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
+For an OS to use this OPAL call, an ``ibm,opal-intc`` compatible device must
exist in the device tree. If OPAL does not create such a device, the host
OS MUST NOT use this call.
diff --git a/doc/opal-api/opal-invalid-call--1.rst b/doc/opal-api/opal-invalid-call--1.rst
index affdbda..cb7b06c 100644
--- a/doc/opal-api/opal-invalid-call--1.rst
+++ b/doc/opal-api/opal-invalid-call--1.rst
@@ -1,6 +1,6 @@
OPAL_INVALID_CALL
------------------
+=================
-An OPAL call of -1 will always return OPAL_PARAMETER. It is always ivalid.
+An OPAL call of ``-1`` will always return ``OPAL_PARAMETER``. It is always ivalid.
It exists purely for testing.
diff --git a/doc/opal-api/opal-led-get-set-114-115.rst b/doc/opal-api/opal-led-get-set-114-115.rst
index 1d90ea4..85656bf 100644
--- a/doc/opal-api/opal-led-get-set-114-115.rst
+++ b/doc/opal-api/opal-led-get-set-114-115.rst
@@ -1,5 +1,5 @@
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
@@ -9,36 +9,39 @@ 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.
+ 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.
+ 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.
+ Indicates there is a problem with the FRU or resource at the
+ location with which the indicator is associated.
-LED Design:
------------
+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.
+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.
+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).
@@ -46,10 +49,10 @@ There are two OPAL calls relating to LED operations.
OPAL_LEDS_GET_INDICATOR
-----------------------
- Returns LED state for the given location code.
+Returns LED state for the given location code.
OPAL_LEDS_SET_INDICATOR
-----------------------
- Sets LED state for the given location code.
+Sets LED state for the given location code.
See hw/fsp/fsp-leds.c for more deatails.
diff --git a/doc/opal-api/opal-messages.rst b/doc/opal-api/opal-messages.rst
index 00a28e5..ceddb69 100644
--- a/doc/opal-api/opal-messages.rst
+++ b/doc/opal-api/opal-messages.rst
@@ -5,12 +5,13 @@ 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 {
+An opal_msg is: ::
+
+ struct opal_msg {
__be32 msg_type;
__be32 reserved;
__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
@@ -19,7 +20,8 @@ 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. In the future, OPAL may support larger
-messages. See OPAL_GET_MESSAGE documentation for details.
+messages. See ``OPAL_GET_MESSAGE`` documentation for details.
+::
ibm,opal {
opal-msg-size = <0x48>;
@@ -28,9 +30,10 @@ messages. See OPAL_GET_MESSAGE documentation for details.
OPAL_MSG_ASYNC_COMP
-------------------
+::
-params[0] = token
-params[1] = rc
+ params[0] = token
+ params[1] = rc
Additional parameters are function-specific.
@@ -43,7 +46,7 @@ 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 GET_EPOW_STATUS API to obtain information about
+Host OS can query OPAL via ``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.
@@ -56,9 +59,9 @@ 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.
+or a reboot. ::
-params[0] = 0x01 reboot, 0x00 shutdown
+ params[0] = 0x01 reboot, 0x00 shutdown
OPAL_MSG_HMI_EVT
----------------
@@ -81,12 +84,15 @@ 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 {
+::
+
+ struct OpalHMIEvent {
uint8_t version; /* 0x00 */
uint8_t severity; /* 0x01 */
uint8_t type; /* 0x02 */
@@ -113,7 +119,7 @@ struct OpalHMIEvent {
} u;
} xstop_error;
} u;
-};
+ };
OPAL_MSG_DPO
@@ -128,7 +134,7 @@ OPAL_MSG_PRD
------------
This message is a OPAL-to-HBRT notification, and contains a
-struct opal_prd_msg:
+struct opal_prd_msg: ::
enum opal_prd_msg_type {
OPAL_PRD_MSG_TYPE_INIT = 0, /* HBRT --> OPAL */
@@ -174,40 +180,40 @@ 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 {
+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
+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
+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
+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.
diff --git a/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst b/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst
index 837cbb9..58f65db 100644
--- a/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst
+++ b/doc/opal-api/opal-pci-get-phb-diag-data2-64.rst
@@ -1,24 +1,38 @@
OPAL_PCI_GET_PHB_DIAG_DATA2
----------------------------
+===========================
+
Get PCI diagnostic data from a given PHB
-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
+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:
+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".
+diagnostics, defined in include/opal-api.h as ``struct OpalIo<PHBVer>ErrorData``.
+
+``OPAL_PCI_GET_PHB_DIAG_DATA`` is deprecated and ``OPAL_PCI_GET_PHB_DIAG_DATA2`` should be used instead.
+
+Return Codes
+------------
+OPAL_SUCCESS
+ Diagnostic data has been retrieved and stored successfully
-OPAL_PCI_GET_PHB_DIAG_DATA is deprecated and OPAL_PCI_GET_PHB_DIAG_DATA2 should
-be used instead.
+OPAL_PARAMETER
+ The given buffer is too small to store the diagnostic data
-Return Codes:
+OPAL_HARDWARE
+ The PHB is in a broken state and its data cannot be retreived
-OPAL_SUCCESS - Diagnostic data has been retrieved and stored successfully
-OPAL_PARAMETER - The given buffer is too small to store the diagnostic data
-OPAL_HARDWARE - The PHB is in a broken state and its data cannot be retreived
-OPAL_UNSUPPORTED - Diagnostic data is not implemented for this PHB type
+OPAL_UNSUPPORTED
+ Diagnostic data is not implemented for this PHB type
diff --git a/doc/opal-api/opal-pci-get-power-state-120.rst b/doc/opal-api/opal-pci-get-power-state-120.rst
index 420cf8d..9e6f94b 100644
--- a/doc/opal-api/opal-pci-get-power-state-120.rst
+++ b/doc/opal-api/opal-pci-get-power-state-120.rst
@@ -1,19 +1,30 @@
OPAL_PCI_GET_POWER_STATE
----------------------------
+========================
Get PCI slot power state
-Parameters:
- uint64_t id: PCI slot ID
- uint64_t data: memory buffer pointer for power state
+Parameter
+---------
-Calling:
+``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:
+Return Codes
+------------
+OPAL_SUCCESS
+ PCI slot's power state is retrieved successfully
+
+OPAL_PARAMETER
+ The indicated PCI slot isn't found
-OPAL_SUCCESS - PCI slot's power state is retrieved successfully
-OPAL_PARAMETER - The indicated PCI slot isn't found
-OPAL_UNSUPPORTED - Power state retrieval not supported on the PCI slot
+OPAL_UNSUPPORTED
+ Power state retrieval not supported on the PCI slot
diff --git a/doc/opal-api/opal-pci-get-presence-state-119.rst b/doc/opal-api/opal-pci-get-presence-state-119.rst
index f3fbd83..23ea831 100644
--- a/doc/opal-api/opal-pci-get-presence-state-119.rst
+++ b/doc/opal-api/opal-pci-get-presence-state-119.rst
@@ -1,13 +1,19 @@
OPAL_PCI_GET_PRESENCE_STATE
----------------------------
+===========================
Get PCI slot presence state
-Parameters:
- uint64_t id: PCI slot ID
- uint64_t data: memory buffer pointer for presence state
+Parameters
+----------
-Calling:
+``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
@@ -15,8 +21,13 @@ 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:
+Return Codes
+------------
+OPAL_SUCCESS
+ PCI slot's presence state is retrieved successfully
+
+OPAL_PARAMETER
+ The indicated PCI slot isn't found
-OPAL_SUCCESS - PCI slot's presence state is retrieved successfully
-OPAL_PARAMETER - The indicated PCI slot isn't found
-OPAL_UNSUPPORTED - Presence retrieval not supported on the PCI slot
+OPAL_UNSUPPORTED
+ Presence retrieval not supported on the PCI slot
diff --git a/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst b/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst
index 897bc37..5c4e685 100644
--- a/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst
+++ b/doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst
@@ -1,17 +1,18 @@
OPAL_PCI_GET_XIVE_REISSUE and OPAL_PCI_SET_XIVE_REISSUE
--------------------------------------------------------
+=======================================================
+::
-static int64_t opal_pci_get_xive_reissue(uint64_t phb_id __unused,
+ static int64_t opal_pci_get_xive_reissue(uint64_t phb_id __unused,
uint32_t xive_number __unused,
uint8_t *p_bit __unused,
uint8_t *q_bit __unused)
-static int64_t opal_pci_set_xive_reissue(uint64_t phb_id __unused,
+ static int64_t opal_pci_set_xive_reissue(uint64_t phb_id __unused,
uint32_t xive_number __unused,
uint8_t p_bit __unused,
uint8_t q_bit __unused)
Both of these calls are remnants from previous OPAL versions, calling either
-of them shall return OPAL_UNSUPPORTED.
+of them shall return ``OPAL_UNSUPPORTED``.
diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-44.rst b/doc/opal-api/opal-pci-map-pe-dma-window-44.rst
index 0793209..dbfe231 100644
--- a/doc/opal-api/opal-pci-map-pe-dma-window-44.rst
+++ b/doc/opal-api/opal-pci-map-pe-dma-window-44.rst
@@ -1,17 +1,17 @@
OPAL_PCI_MAP_PE_DMA_WINDOW
---------------------------
+==========================
+::
-#define OPAL_PCI_MAP_PE_DMA_WINDOW 44
+ #define OPAL_PCI_MAP_PE_DMA_WINDOW 44
-
-static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, uint16_t pe_number,
+ static int64_t opal_pci_map_pe_dma_window(uint64_t phb_id, uint16_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
+**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.
@@ -24,26 +24,32 @@ 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.
+``phb_id``
+ is the value from the PHB node ``ibm,opal-phbid`` property.
- dma_window_number specifies the DMA window
+``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,
+``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_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_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.
+``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
@@ -60,19 +66,22 @@ 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.
+``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_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.
+``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
@@ -84,7 +93,8 @@ 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:
+Return value: ::
+
if (!phb)
return OPAL_PARAMETER;
if (!phb->ops->map_pe_dma_window)
diff --git a/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst
index 28ea112..bc364dc 100644
--- a/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst
+++ b/doc/opal-api/opal-pci-map-pe-dma-window-real-45.rst
@@ -1,9 +1,10 @@
OPAL_PCI_MAP_PE_DMA_WINDOW_REAL
--------------------------------
+===============================
+::
-#define OPAL_PCI_MAP_PE_DMA_WINDOW_REAL 45
+ #define OPAL_PCI_MAP_PE_DMA_WINDOW_REAL 45
-WARNING: following documentation is from old sources, and is possibly
+**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.
@@ -16,24 +17,29 @@ 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.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
- dma_window_number specifies the DMA window
+``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 OPAL_PARAMETER
- for any value that is not a multiple of 16MB. A value of '0' indicates to
- disable this DMA window.
+``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 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/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst b/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst
index 4f43506..595c588 100644
--- a/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst
+++ b/doc/opal-api/opal-pci-map-pe-mmio-window-29.rst
@@ -1,37 +1,44 @@
OPAL_PCI_MAP_PE_MMIO_WINDOW
----------------------------
-#define OPAL_PCI_MAP_PE_MMIO_WINDOW 29
+===========================
+::
-static int64_t opal_pci_map_pe_mmio_window(uint64_t phb_id, uint16_t pe_number,
+ #define OPAL_PCI_MAP_PE_MMIO_WINDOW 29
+
+ static int64_t opal_pci_map_pe_mmio_window(uint64_t phb_id, uint16_t pe_number,
uint16_t window_type,
uint16_t window_num,
uint16_t segment_num)
-WARNING: following documentation is from old sources, and is possibly
+**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.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
+
+``window_type``
+ specifies 32-bit or 64-bit PCI memory
- 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.
- '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
- '1' selects 32-bit PCI memory space
+ '2' selects 64 bit PCI memory space
- '2' selects 64 bit PCI memory space
+``window_num``
+ is the MMIO window number within the specified 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.
- 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: ::
-Return value:
if (!phb)
return OPAL_PARAMETER;
if (!phb->ops->map_pe_mmio_window)
diff --git a/doc/opal-api/opal-pci-phb-mmio-enable-27.rst b/doc/opal-api/opal-pci-phb-mmio-enable-27.rst
index 9bff057..62b4ea3 100644
--- a/doc/opal-api/opal-pci-phb-mmio-enable-27.rst
+++ b/doc/opal-api/opal-pci-phb-mmio-enable-27.rst
@@ -1,12 +1,13 @@
OPAL_PCI_PHB_MMIO_ENABLE
-------------------------
+========================
+::
-#define OPAL_PCI_PHB_MMIO_ENABLE 27
+ #define OPAL_PCI_PHB_MMIO_ENABLE 27
-static int64_t opal_pci_phb_mmio_enable(uint64_t phb_id, uint16_t window_type,
+ static int64_t opal_pci_phb_mmio_enable(uint64_t phb_id, uint16_t window_type,
uint16_t window_num, uint16_t enable)
-WARNING: following documentation is from old sources, and is possibly
+**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.
@@ -29,16 +30,20 @@ processor (e.g.,via HPT).
OPAL returns 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.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
- window_type specifies 32-bit or 64-bit PCI memory
+``window_type``
+ specifies 32-bit or 64-bit PCI memory
- '0' selects PCI IO Space
+ '0' selects PCI IO Space
- '1' selects 32-bit PCI memory space
+ '1' selects 32-bit PCI memory space
- '2' selects 64 bit PCI memory space
+ '2' selects 64 bit PCI memory space
- window_num is the MMIO window number within the specified 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.
+``enable``
+ specifies to enable or disable this MMIO window.
diff --git a/doc/opal-api/opal-pci-set-mve-33.rst b/doc/opal-api/opal-pci-set-mve-33.rst
index f407d41..66a81ed 100644
--- a/doc/opal-api/opal-pci-set-mve-33.rst
+++ b/doc/opal-api/opal-pci-set-mve-33.rst
@@ -1,12 +1,13 @@
OPAL_PCI_SET_MVE
-----------------
+================
+::
-#define OPAL_PCI_SET_MVE 33
+ #define OPAL_PCI_SET_MVE 33
-static int64_t opal_pci_set_mve(uint64_t phb_id, uint32_t mve_number,
+ static int64_t opal_pci_set_mve(uint64_t phb_id, uint32_t mve_number,
uint32_t pe_number)
-WARNING: following documentation is from old sources, and is possibly
+**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.
@@ -16,19 +17,21 @@ 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.
- The phb_id parameter is the value from the PHB node ibm,opal-phbid
- property.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
- The mve_number is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1
+``mve_number``
+ is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1
- the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1.
+``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.
+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:
+Return value: ::
if (!phb)
return OPAL_PARAMETER;
diff --git a/doc/opal-api/opal-pci-set-mve-enable-34.rst b/doc/opal-api/opal-pci-set-mve-enable-34.rst
index 4c13d3c..44af37f 100644
--- a/doc/opal-api/opal-pci-set-mve-enable-34.rst
+++ b/doc/opal-api/opal-pci-set-mve-enable-34.rst
@@ -1,34 +1,38 @@
OPAL_PCI_SET_MVE_ENABLE
------------------------
+=======================
+::
-#define OPAL_PCI_SET_MVE_ENABLE 34
+ #define OPAL_PCI_SET_MVE_ENABLE 34
-static int64_t opal_pci_set_mve_enable(uint64_t phb_id, uint32_t mve_number,
+ static int64_t opal_pci_set_mve_enable(uint64_t phb_id, uint32_t mve_number,
uint32_t state)
-enum OpalMveEnableAction {
+ enum OpalMveEnableAction {
OPAL_DISABLE_MVE = 0,
OPAL_ENABLE_MVE = 1
-};
+ };
-WARNING: following documentation is from old sources, and is possibly
+**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.
-The phb_id parameter is the value from the PHB node ibm,opal-phbid
- property.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
-The mve_number is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1
+``mve_number``
+ is the index, from 0 to ibm,opal,ibm-num-msi-ports minus1
-A '1' value of the state parameter indicates to enable the MVE and a '0'
-value indicates to disable the MVE.
+``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:
+Return value: ::
+
if (!phb)
return OPAL_PARAMETER;
if (!phb->ops->set_mve_enable)
diff --git a/doc/opal-api/opal-pci-set-pe-31.rst b/doc/opal-api/opal-pci-set-pe-31.rst
index bfe3890..a101b90 100644
--- a/doc/opal-api/opal-pci-set-pe-31.rst
+++ b/doc/opal-api/opal-pci-set-pe-31.rst
@@ -1,9 +1,10 @@
OPAL_PCI_SET_PE
----------------
+===============
+::
-#define OPAL_PCI_SET_PE 31
+ #define OPAL_PCI_SET_PE 31
-NOTE: The following two paragraphs come from some old documentation and
+**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.
@@ -20,55 +21,71 @@ 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.
+::
-static int64_t opal_pci_set_pe(uint64_t phb_id, uint64_t pe_number,
+ static 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)
-The phb_id parameter is the value from the PHB node ibm,opal-phbid property.
-
-the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1.
-
-the bus_compare parameter 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
-
-the dev_compare parameter 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.
-
-the func_compare parameter 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 {
+``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
-};
-
+ };
Return value:
-- OPAL_PARAMETER if:
+
+OPAL_PARAMETER
+ If one of the following:
- invalid phb
- invalid pe_action
- invalid bus_dev_func
- invalid bus_compare
-- if PHB does not support set_pe operation, OPAL_UNSUPPORTED
-- OPAL_SUCCESS if opreation was successful
+
+OPAL_UNSUPPORTED
+ PHB does not support set_pe operation
+
+OPAL_SUCCESS
+ if opreation was successful
diff --git a/doc/opal-api/opal-pci-set-peltv-32.rst b/doc/opal-api/opal-pci-set-peltv-32.rst
index 9274aab..9cc13a2 100644
--- a/doc/opal-api/opal-pci-set-peltv-32.rst
+++ b/doc/opal-api/opal-pci-set-peltv-32.rst
@@ -1,50 +1,58 @@
OPAL_PCI_SET_PELTV
-------------------
+==================
+::
-#define OPAL_PCI_SET_PELTV 32
+ #define OPAL_PCI_SET_PELTV 32
-WARNING: This documentation comes from an old source and is possibly not up
+**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).
-static int64_t opal_pci_set_peltv(uint64_t phb_id, uint32_t parent_pe,
+::
+
+ static int64_t opal_pci_set_peltv(uint64_t phb_id, uint32_t parent_pe,
uint32_t child_pe, uint8_t state)
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.
- The phb_id parameter is the value from the PHB node ibm,opal-phbid property
-
- the 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).
-
- the 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.
-
-enum OpalPeltvAction {
+``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.
+
+::
+
+ 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:
+**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:
+Return value: ::
if (!phb)
return OPAL_PARAMETER;
diff --git a/doc/opal-api/opal-pci-set-phb-mem-window-28.rst b/doc/opal-api/opal-pci-set-phb-mem-window-28.rst
index 8a355e8..0dc6b70 100644
--- a/doc/opal-api/opal-pci-set-phb-mem-window-28.rst
+++ b/doc/opal-api/opal-pci-set-phb-mem-window-28.rst
@@ -1,16 +1,17 @@
OPAL_PCI_SET_PHB_MEM_WINDOW
----------------------------
+===========================
+::
-#define OPAL_PCI_SET_PHB_MEM_WINDOW 28
+ #define OPAL_PCI_SET_PHB_MEM_WINDOW 28
-static int64_t opal_pci_set_phb_mem_window(uint64_t phb_id,
+ static 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)
-WARNING: following documentation is from old sources, and is possibly
+**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.
@@ -20,39 +21,45 @@ 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.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
- window_type specifies 32-bit or 64-bit PCI memory
+``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.
+ '0' selects IO space, and is not supported for relocation. OPAL
+ returns OPAL_UNSUPPORTED for this value.
- '1' selects 32-bit PCI memory space
+ '1' selects 32-bit PCI memory space
- '2' selects 64 bit PCI memory space
+ '2' selects 64 bit PCI memory space
- window_num is the MMIO window number within the specified 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_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.
+``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.
+``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
@@ -64,7 +71,8 @@ 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:
+Return value: ::
+
if (!phb)
return OPAL_PARAMETER;
if (!phb->ops->set_phb_mem_window)
diff --git a/doc/opal-api/opal-pci-set-power-state-121.rst b/doc/opal-api/opal-pci-set-power-state-121.rst
index 92da235..54c1a33 100644
--- a/doc/opal-api/opal-pci-set-power-state-121.rst
+++ b/doc/opal-api/opal-pci-set-power-state-121.rst
@@ -1,17 +1,25 @@
OPAL_PCI_SET_POWER_STATE
----------------------------
+========================
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}.
+Parameters
+----------
-Calling:
+``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
@@ -28,9 +36,17 @@ 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:
+Return Codes
+------------
+
+OPAL_SUCCESS
+ PCI hotplug on the slot is completed successfully
+
+OPAL_ASYNC_COMPLETION
+ PCI hotplug needs further message to confirm
+
+OPAL_PARAMETER
+ The indicated PCI slot isn't found
-OPAL_SUCCESS - PCI hotplug on the slot is completed successfully
-OPAL_ASYNC_COMPLETION - PCI hotplug needs further message to confirm
-OPAL_PARAMETER - The indicated PCI slot isn't found
-OPAL_UNSUPPORTED - Setting power state not supported on the PCI slot
+OPAL_UNSUPPORTED
+ Setting power state not supported on the PCI slot
diff --git a/doc/opal-api/opal-pci-set-xive-pe-37.rst b/doc/opal-api/opal-pci-set-xive-pe-37.rst
index e37d65c..67a86e7 100644
--- a/doc/opal-api/opal-pci-set-xive-pe-37.rst
+++ b/doc/opal-api/opal-pci-set-xive-pe-37.rst
@@ -1,29 +1,32 @@
OPAL_PCI_SET_XIVE_PE
---------------------
+====================
+::
-static int64_t opal_pci_set_xive_pe(uint64_t phb_id, uint32_t pe_number,
+ static int64_t opal_pci_set_xive_pe(uint64_t phb_id, uint32_t pe_number,
uint32_t xive_num)
-WARNING: following documentation is from old sources, and is possibly
+**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.
- The phb_id parameter is the value from the PHB node ibm,opal-phbid
- property.
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
- the pe_number is the index of a PE, from 0 to ibm,opal-num-pes minus 1.
+``pe_number``
+ is the index of a PE, from 0 to ibm,opal-num-pes minus 1.
- The xive_number is the index, from 0 to ibm,opal,ibm-num-msis minus
- (num_lsis+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.
+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: ::
-Return value:
if (!phb)
return OPAL_PARAMETER;
if (!phb->ops->set_xive_pe)
diff --git a/doc/opal-api/opal-pci-tce-kill-126.rst b/doc/opal-api/opal-pci-tce-kill-126.rst
index e774966..4aa6eb9 100644
--- a/doc/opal-api/opal-pci-tce-kill-126.rst
+++ b/doc/opal-api/opal-pci-tce-kill-126.rst
@@ -1,7 +1,8 @@
OPAL_PCI_TCE_KILL
------------------
+=================
+::
-int64_t opal_pci_tce_kill(uint64_t phb_id,
+ int64_t opal_pci_tce_kill(uint64_t phb_id,
uint32_t kill_type,
uint32_t pe_num,
uint32_t tce_size,
@@ -11,27 +12,32 @@ int64_t opal_pci_tce_kill(uint64_t phb_id,
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:
-enum {
+Where kill_type is one of: ::
+
+ 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:
-OPAL_PARAMETER: if phb_id is invalid (or similar)
-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).
+Returns
+-------
+OPAL_PARAMETER
+ if phb_id is invalid (or similar)
+
+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)
+Example code (from linux/arch/powerpc/platforms/powernv/pci-ioda.c) ::
-static inline void pnv_pci_ioda2_tce_invalidate_pe(struct pnv_ioda_pe *pe)
-{
+ 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)
@@ -39,16 +45,16 @@ static inline void pnv_pci_ioda2_tce_invalidate_pe(struct pnv_ioda_pe *pe)
else
opal_pci_tce_kill(phb->opal_id, OPAL_PCI_TCE_KILL_PE,
pe->pe_number, 0, 0, 0);
-}
+ }
-and
+and ::
-struct pnv_phb *phb = pe->phb;
-unsigned int shift = tbl->it_page_shift;
-if (phb->model == PNV_PHB_MODEL_PHB3 && phb->regs)
+ 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
+ else
opal_pci_tce_kill(phb->opal_id,
OPAL_PCI_TCE_KILL_PAGES,
pe->pe_number, 1u << shift,
diff --git a/doc/opal-api/opal-poll-events.rst b/doc/opal-api/opal-poll-events.rst
index 6a0832e..c70d7f0 100644
--- a/doc/opal-api/opal-poll-events.rst
+++ b/doc/opal-api/opal-poll-events.rst
@@ -1,5 +1,5 @@
OPAL_POLL_EVENTS
-----------------
+================
Poll for outstanding events.
@@ -19,8 +19,7 @@ Unused
OPAL_EVENT_RTC = 0x4
--------------------
-
-TODO: clean this up, this is just copied from hw/fsp/fsp-rtc.c:
+**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)
@@ -46,8 +45,6 @@ TODO: clean this up, this is just copied from hw/fsp/fsp-rtc.c:
* 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
@@ -79,6 +76,6 @@ TODO
OPAL_EVENT_DUMP_AVAIL = 0x400
-----------------------------
Signifies that there is a pending system dump available. See OPAL_DUMP suite
-of calls for details.
+of calls for details. ::
-OPAL_EVENT_MSG_PENDING = 0x800,
+ OPAL_EVENT_MSG_PENDING = 0x800,
diff --git a/doc/opal-api/opal-prd-msg-113.rst b/doc/opal-api/opal-prd-msg-113.rst
index b41f17e..0cda30a 100644
--- a/doc/opal-api/opal-prd-msg-113.rst
+++ b/doc/opal-api/opal-prd-msg-113.rst
@@ -1,11 +1,11 @@
-
-OPAL_PRD_MSG call
--------------
+OPAL_PRD_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 OPAL_PRD_MSG message type.
-Parameters:
- struct opal_msg *msg
+Parameters
+----------
-Passes an opal_msg, of type OPAL_PRD_MSG, from the OS to OPAL.
+``struct opal_msg *msg``
+ Passes an opal_msg, of type OPAL_PRD_MSG, from the OS to OPAL.
diff --git a/doc/opal-api/opal-read-write-tpo-103-104.rst b/doc/opal-api/opal-read-write-tpo-103-104.rst
index 0040615..b465006 100644
--- a/doc/opal-api/opal-read-write-tpo-103-104.rst
+++ b/doc/opal-api/opal-read-write-tpo-103-104.rst
@@ -1,15 +1,15 @@
OPAL_READ_TPO and OPAL_WRITE_TPO
---------------------------------
+================================
TPO is a Timed Power On facility.
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:
+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: ::
-rtc {
+ rtc {
compatible = "ibm,opal-rtc";
has-tpo;
-};
+ };
If the "has-tpo" proprety is *NOT* present then OPAL does *NOT* support TPO.
diff --git a/doc/opal-api/opal-register-dump-region-101.rst b/doc/opal-api/opal-register-dump-region-101.rst
index e88e8cf..1530082 100644
--- a/doc/opal-api/opal-register-dump-region-101.rst
+++ b/doc/opal-api/opal-register-dump-region-101.rst
@@ -1,5 +1,5 @@
OPAL_REGISTER_DUMP_REGION
--------------------------
+=========================
This call is used to register regions of memory for a service processor to capture
when the host crashes.
@@ -10,6 +10,7 @@ This is an OPTIONAL feature that may be unsupported, the host OS should use an
OPAL_CHECK_TOKEN call to find out if OPAL_REGISTER_DUMP_REGION is supported.
OPAL_REGISTER_DUMP_REGION accepts 3 parameters:
+
- region ID
- address
- length
@@ -17,14 +18,14 @@ OPAL_REGISTER_DUMP_REGION accepts 3 parameters:
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).
+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
+ /*
+ * 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
OPAL_REGISTER_DUMP_REGION will return OPAL_UNSUPPORTED if the call is present but
the system doesn't support registering regions to be dumped.
@@ -35,7 +36,8 @@ return OPAL_PARAMETER.
Systems likely have a limit as to how many regions they can support being dumped. If
this limit is reached, OPAL_REGISTER_DUMP_REGION will return OPAL_INTERNAL_ERROR.
-BUGS:
+BUGS
+----
Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of
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).
diff --git a/doc/opal-api/opal-reinit-cpus-70.rst b/doc/opal-api/opal-reinit-cpus-70.rst
index bf9b238..f628670 100644
--- a/doc/opal-api/opal-reinit-cpus-70.rst
+++ b/doc/opal-api/opal-reinit-cpus-70.rst
@@ -1,18 +1,21 @@
OPAL_REINIT_CPUS
-----------------
+================
+::
-static int64_t opal_reinit_cpus(uint64_t flags);
+ 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:
-enum {
+Arguments
+---------
+Currently, possible flags are: ::
+
+ enum {
OPAL_REINIT_CPUS_HILE_BE = (1 << 0),
OPAL_REINIT_CPUS_HILE_LE = (1 << 1),
-};
+ };
Extra flags may be added in the future, so other bits *must* be 0.
@@ -24,6 +27,11 @@ are support and other bits *MUST NOT* be set.
On POWER9 CPUs, other flags may be supported in the future.
-Returns:
-- OPAL_SUCCESS
-- OPAL_UNSUPPORTED
+Returns
+-------
+
+``OPAL_SUCCESS``
+ Success!
+
+``OPAL_UNSUPPORTED``
+ Processor does not suport reinit flags.
diff --git a/doc/opal-api/opal-return-cpu-69.rst b/doc/opal-api/opal-return-cpu-69.rst
index db54cae..29894ac 100644
--- a/doc/opal-api/opal-return-cpu-69.rst
+++ b/doc/opal-api/opal-return-cpu-69.rst
@@ -1,7 +1,8 @@
OPAL_RETURN_CPU
----------------
+===============
+::
-int64_t opal_return_cpu(void);
+ 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_CPU
@@ -13,5 +14,6 @@ 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.
+Returns
+-------
+This call does **not return**. You need to OPAL_START_CPU.
diff --git a/doc/opal-api/opal-rtc-read-3.rst b/doc/opal-api/opal-rtc-read-3.rst
index 13a0655..cb23876 100644
--- a/doc/opal-api/opal-rtc-read-3.rst
+++ b/doc/opal-api/opal-rtc-read-3.rst
@@ -1,23 +1,29 @@
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:
+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, OPAL_RTC_READ is likely to first return
OPAL_BUSY_EVENT, requiring the caller to wait until the OPAL_EVENT_RTC event
has been signaled. Once the event has been signaled, a subsequent
@@ -26,7 +32,7 @@ used for both reading and writing the RTC, callers must be able to handle
the event being signaled for a concurrent in flight OPAL_RTC_WRITE rather
than this read request.
-The following code is one way to correctly issue and then wait for a response:
+The following code is one way to correctly issue and then wait for a response: ::
int rc = OPAL_BUSY_EVENT;
while (rc == OPAL_BUSY_EVENT) {
@@ -39,17 +45,23 @@ Although as of writing all OPAL_RTC_READ backends are asynchronous, there is
no requirement for them to be - it is valid for OPAL_RTC_READ to immediately
return the retreived value rather than OPAL_BUSY_EVENT.
-TODO: describe/document format of arguments.
-
-Return codes:
-OPAL_SUCCESS:
- - parameters now contain the current time, or one read from cache.
-OPAL_HARDWARE:
- - error in retrieving the time. May be transient error,
- may be permanent.
-OPAL_PARAMETER:
- - year_month_day or hour_minute_second_millisecond parameters are NULL
-OPAL_INTERNAL_ERROR:
- - something went wrong, Possibly reported in error log.
-OPAL_BUSY_EVENT:
- - request is in flight
+**TODO**: describe/document format of arguments.
+
+Return codes
+------------
+
+OPAL_SUCCESS
+ parameters now contain the current time, or one read from cache.
+
+OPAL_HARDWARE
+ error in retrieving the time. May be transient error,
+ may be permanent.
+
+OPAL_PARAMETER
+ year_month_day or hour_minute_second_millisecond parameters are NULL
+
+OPAL_INTERNAL_ERROR
+ something went wrong, Possibly reported in error log.
+
+OPAL_BUSY_EVENT
+ request is in flight
diff --git a/doc/opal-api/opal-rtc-write-4.rst b/doc/opal-api/opal-rtc-write-4.rst
index 37ca915..3416b79 100644
--- a/doc/opal-api/opal-rtc-write-4.rst
+++ b/doc/opal-api/opal-rtc-write-4.rst
@@ -1,5 +1,5 @@
OPAL_RTC_WRITE
---------------
+==============
OPAL_RTC_WRITE is much like OPAL_RTC_READ in that it can be asynchronous.
diff --git a/doc/opal-api/opal-sensor-read-88.rst b/doc/opal-api/opal-sensor-read-88.rst
index f6c62e1..22f880e 100644
--- a/doc/opal-api/opal-sensor-read-88.rst
+++ b/doc/opal-api/opal-sensor-read-88.rst
@@ -1,5 +1,5 @@
OPAL_SENSOR_READ
-----------------
+================
The OPAL sensor call reads a sensor data using a unique handler to
identity the targeted sensor.
@@ -11,23 +11,43 @@ OPAL_ASYNC_COMPLETION and the token parameter will be used to wait for
the completion of the request.
-Parameters:
+Parameters
+----------
+::
+
uint32_t sensor_handler
int token
uint32_t *sensor_data
-Return values:
- OPAL_SUCCESS
- OPAL_PARAMETER - invalid sensor handler
- OPAL_UNSUPPORTED - plateform does not support reading sensors.
+Return values
+-------------
+OPAL_SUCCESS
+ Success!
+
+OPAL_PARAMETER
+ invalid sensor handler
+
+OPAL_UNSUPPORTED
+ platform does not support reading sensors.
+
+In case of communication with the FSP on IBM systems:
+
+OPAL_ASYNC_COMPLETION
+ a request was sent and an async completion will
+ be triggered with the @token argument
+
+OPAL_PARTIAL
+ the request completed but the data returned is invalid
+
+OPAL_BUSY_EVENT
+ a previous request is still pending
+
+OPAL_NO_MEM
+ allocation failed
-in case of communication with the FSP on IBM systems
+OPAL_INTERNAL_ERROR
+ communication failure with the FSP
- OPAL_ASYNC_COMPLETION - a request was sent and an async completion will
- be triggered with the @token argument
- OPAL_PARTIAL - the request completed but the data returned is invalid
- OPAL_BUSY_EVENT - a previous request is still pending
- OPAL_NO_MEM - allocation failed
- OPAL_INTERNAL_ERROR - communication failure with the FSP
- OPAL_HARDWARE - FSP is not available
+OPAL_HARDWARE
+ FSP is not available
diff --git a/doc/opal-api/opal-set-xive-19.rst b/doc/opal-api/opal-set-xive-19.rst
index 590847b..871d9eb 100644
--- a/doc/opal-api/opal-set-xive-19.rst
+++ b/doc/opal-api/opal-set-xive-19.rst
@@ -1,24 +1,31 @@
OPAL_SET_XIVE
--------------
+=============
+::
-#define OPAL_SET_XIVE 19
+ #define OPAL_SET_XIVE 19
-WARNING: following documentation is from old sources, and is possibly
+**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 POWER XIVE server and priority
parameters into the PHB XIVE.
- The phb_id parameter is the value from the PHB node ibm,opal-phbid
- property.
+Parameters
+----------
- The xive_number is the index of an XIVE that corresponds to a particular
- interrupt
+``phb_id``
+ is the value from the PHB node ibm,opal-phbid property.
- the service_number is the server (processor) that is to receive the
- interrupt request
+``xive_number``
+ is the index of an XIVE that corresponds to a particular
+ interrupt
- the priority is the interrupt priority value applied to the interrupt
- (0=highest, 0xFF = lowest/disabled).
+``service_number``
+ is the server (processor) that is to receive the
+ interrupt request
+
+``priority``
+ is the interrupt priority value applied to the interrupt
+ (0=highest, 0xFF = lowest/disabled).
diff --git a/doc/opal-api/opal-sync-host-reboot-87.rst b/doc/opal-api/opal-sync-host-reboot-87.rst
index 52d3776..466e673 100644
--- a/doc/opal-api/opal-sync-host-reboot-87.rst
+++ b/doc/opal-api/opal-sync-host-reboot-87.rst
@@ -1,7 +1,8 @@
OPAL_SYNC_HOST_REBOOT
=====================
+::
-static int64_t opal_sync_host_reboot(void)
+ 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
@@ -9,7 +10,13 @@ as a new error log being available for retreival).
It's meant to be called in a loop until OPAL_SUCCESS is returned.
-Returns:
-- OPAL_SUCCESS: Success!
-- OPAL_BUSY_EVENT: not yet complete, call opal_sync_host_reboot() again, possibly with a short delay.
-- OPAL_BUSY: Call opal_poll_events() and then retry opal_sync_host_reboot
+Returns
+-------
+OPAL_SUCCESS
+ Success!
+
+OPAL_BUSY_EVENT
+ not yet complete, call opal_sync_host_reboot() again, possibly with a short delay.
+
+OPAL_BUSY
+ Call opal_poll_events() and then retry opal_sync_host_reboot
diff --git a/doc/opal-api/opal-test-0.rst b/doc/opal-api/opal-test-0.rst
index f732227..ff56aba 100644
--- a/doc/opal-api/opal-test-0.rst
+++ b/doc/opal-api/opal-test-0.rst
@@ -1,30 +1,38 @@
OPAL_TEST
----------
+=========
OPAL_TEST is a REQUIRED call for OPAL and conforming implementations MUST
have it.
It is designed to test basic OPAL call functionality.
-Token:
-#define OPAL_TEST 0
+Token: ::
+
+ #define OPAL_TEST 0
+
+Arguments
+---------
+::
+
+ uint64_t arg
-Arguments:
- uint64_t arg
+Returns
+-------
+::
-Returns:
0xfeedf00d
-Function:
+Function
+--------
OPAL_TEST MAY print a string to the OPAL log with the value of argument.
-For example, the reference implementation (skiboot) implements OPAL_TEST as:
+For example, the reference implementation (skiboot) implements OPAL_TEST as: ::
-static uint64_t opal_test_func(uint64_t arg)
-{
+ 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/doc/opal-api/opal-unregister-dump-region-102.rst b/doc/opal-api/opal-unregister-dump-region-102.rst
index 268d501..d382c82 100644
--- a/doc/opal-api/opal-unregister-dump-region-102.rst
+++ b/doc/opal-api/opal-unregister-dump-region-102.rst
@@ -1,5 +1,5 @@
OPAL_UNREGISTER_DUMP_REGION
----------------------------
+===========================
While OPAL_REGISTER_DUMP_REGION registers a region, OPAL_UNREGISTER_DUMP_REGION
will unregister a region by region ID.
@@ -12,7 +12,8 @@ OPAL_CHECK_TOKEN.
If OPAL_UNREGISTER_DUMP_REGION is called on a system where the call is present but
unsupported, it will return OPAL_UNSUPPORTED.
-BUGS:
+BUGS
+----
Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of
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).
diff --git a/doc/opal-api/opal-xscom-read-write-65-66.rst b/doc/opal-api/opal-xscom-read-write-65-66.rst
index 4ed0134..d24651d 100644
--- a/doc/opal-api/opal-xscom-read-write-65-66.rst
+++ b/doc/opal-api/opal-xscom-read-write-65-66.rst
@@ -1,17 +1,23 @@
OPAL_XSCOM_READ and OPAL_XSCOM_WRITE
-------------------------------------
+====================================
These low level calls will read/write XSCOM values directly.
They should only be used by low level manufacturing/debug tools.
"Normal" host OS kernel code should not know about XSCOM.
-each takes three parameters:
+each takes three parameters: ::
-int xscom_read(uint32_t partid, uint64_t pcb_addr, uint64_t *val)
-int xscom_write(uint32_t partid, uint64_t pcb_addr, uint64_t val)
+ int xscom_read(uint32_t partid, uint64_t pcb_addr, uint64_t *val)
+ int xscom_write(uint32_t partid, uint64_t pcb_addr, uint64_t val)
-Returns:
- OPAL_SUCCESS
- OPAL_HARDWARE if operation failed
- OPAL_WRONG_STATE if CPU is asleep
+Returns
+-------
+OPAL_SUCCESS
+ Success!
+
+OPAL_HARDWARE
+ if operation failed
+
+OPAL_WRONG_STATE
+ if CPU is asleep
--
2.7.4
More information about the Skiboot
mailing list