[Skiboot] [RFC PATCH 04/23] doc/*.rst: fix ReSTructured text syntax
Stewart Smith
stewart at linux.vnet.ibm.com
Wed Jul 27 17:43:05 AEST 2016
Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
doc/bmc.rst | 8 +-
doc/console-log.rst | 47 ++---
doc/device-tree.rst | 127 ++++++-------
doc/error-logging.rst | 411 ++++++++++++++++++++++---------------------
doc/gcov.rst | 41 +++--
doc/index.rst | 15 ++
doc/memory.rst | 29 +--
doc/nvlink.rst | 90 +++++-----
doc/opal-spec.rst | 99 ++++++-----
doc/overview.rst | 28 ++-
doc/pci-slot.rst | 25 ++-
doc/pci.rst | 68 +++----
doc/stable-skiboot-rules.rst | 82 +++++----
doc/versioning.rst | 93 +++++-----
doc/xscom-node-bindings.rst | 34 ++--
15 files changed, 634 insertions(+), 563 deletions(-)
diff --git a/doc/bmc.rst b/doc/bmc.rst
index 78c3b29..bbb390a 100644
--- a/doc/bmc.rst
+++ b/doc/bmc.rst
@@ -21,13 +21,11 @@ FW Boot Progress: assertion type. During boot, skiboot will update this sensor
to one of the IPMI-defined progress codes. The codes use by skiboot are:
* PCI Resource configuration (0x01)
- - asserted as the PCI devices have been probed and resources allocated
-
+ * asserted as the PCI devices have been probed and resources allocated
* Motherboard init (0x14)
- - asserted as the platform-specific components have been initialised
-
+ * asserted as the platform-specific components have been initialised
* OS boot (0x13)
- - asserted after skiboot has loaded the PAYLOAD image, and is about to
+ * asserted after skiboot has loaded the PAYLOAD image, and is about to
boot it.
Chassis control messages
diff --git a/doc/console-log.rst b/doc/console-log.rst
index fbdd33b..9802418 100644
--- a/doc/console-log.rst
+++ b/doc/console-log.rst
@@ -1,5 +1,5 @@
SkiBoot Console Log
--------------------
+===================
Skiboot maintains a circular textual log buffer in memory.
@@ -20,17 +20,22 @@ with prlog() calls.
See timebase.h for full timebase explanation.
Log level from skiboot.h:
-#define PR_EMERG 0
-#define PR_ALERT 1
-#define PR_CRIT 2
-#define PR_ERR 3
-#define PR_WARNING 4
-#define PR_NOTICE 5
-#define PR_PRINTF PR_NOTICE
-#define PR_INFO 6
-#define PR_DEBUG 7
-#define PR_TRACE 8
-#define PR_INSANE 9
+
+=============== ==========
+Define Value
+=============== ==========
+PR_EMERG 0
+PR_ALERT 1
+PR_CRIT 2
+PR_ERR 3
+PR_WARNING 4
+PR_NOTICE 5
+PR_PRINTF PR_NOTICE
+PR_INFO 6
+PR_DEBUG 7
+PR_TRACE 8
+PR_INSANE 9
+=============== ==========
The console_log_levels byte in the debug_descriptor controls what
messages are written to any console drivers (e.g. fsp, uart) and
@@ -40,21 +45,21 @@ This enables (advanced) users to vary what level of output they want
at runtime in the memory console and through console drivers (fsp/uart)
You can vary two things by poking in the debug descriptor:
-a) what log level is printed at all
- e.g. only turn on PR_TRACE at specific points during runtime
-b) what log level goes out the fsp/uart console
- defaults to PR_PRINTF
-
+
+1. what log level is printed at all
+ e.g. only turn on PR_TRACE at specific points during runtime
+2. what log level goes out the fsp/uart console, defaults to PR_PRINTF
+
We use two 4bit numbers (1 byte) for this in debug descriptor (saving
some space, not needlessly wasting space that we may want in future).
-
+
The default is 0x75 (7=PR_DEBUG to in memory console, 5=PR_PRINTF to drivers
-
+
If you write 0x77 you will get debug info on uart/fsp console as
well as in memory. If you write 0x95 you get PR_INSANE in memory but
still only PR_NOTICE through drivers.
-
+
People who write something like 0x1f will get a very quiet boot indeed.
-
+
diff --git a/doc/device-tree.rst b/doc/device-tree.rst
index 742ff43..0597194 100644
--- a/doc/device-tree.rst
+++ b/doc/device-tree.rst
@@ -1,77 +1,54 @@
-/*
- * Sapphire device-tree requirements
- *
- * Version: 0.2.1
- *
- * This documents the generated device-tree requirements, this is based on
- * a commented device-tree dump obtained from a DT generated by Sapphire
- * itself from an HDAT.
- */
-
-/*
- * General comments:
- *
- * - skiboot does not require nodes to have phandle properties, but
- * if you have them then *all* nodes must have them including the
- * root of the device-tree (currently a HB bug !). It is recommended
- * to have them since they are needed to represent the cache levels.
- *
- * NOTE: The example tree below only has phandle properties for
- * nodes that are referenced by other nodes. This is *not* correct
- * and is purely done for keeping this document smaller, make sure
- * to follow the rule above.
- *
- * - Only the "phandle" property is required. Sapphire also generates
- * a "linux,phandle" for backward compatibility but doesn't require
- * it as an input
- *
- * - Any property not specifically documented must be put in "as is"
- *
- * - All ibm,chip-id properties contain a HW chip ID which correspond
- * on P8 to the PIR value shifted right by 7 bits, ie. it's a 6-bit
- * value made of a 3-bit node number and a 3-bit chip number.
- *
- * - Unit addresses (@xxxx part of node names) should if possible use
- * lower case hexadecimal to be consistent with what skiboot does
- * and to help some stupid parsers out there...
- */
-
-/*
- * Version history
- *
- * 2013/10/08 : Version 0.1
- *
- * 2013/10/09 : Version 0.2
- *
- * - Add comment about case of unit addresses
- * - Add missing lpc node definition
- * - Add example UART node on LPC
- * - Remove "status" property from PSI xsco nodes
- *
- * 2014/03/26 : Version 0.2.1
- *
- * - Fix cpus/xxx/ibm,pa-features to be a byte array
- */
-
-/dts-v1/;
-
-
-/*
- * Here are the reserve map entries. They should exactly match the
- * reserved-ranges property of the root node (see documentation
- * of that property)
- */
-
-/memreserve/ 0x00000007fe600000 0x0000000000100000;
-/memreserve/ 0x00000007fe200000 0x0000000000100000;
-/memreserve/ 0x0000000031e00000 0x00000000003e0000;
-/memreserve/ 0x0000000031000000 0x0000000000e00000;
-/memreserve/ 0x0000000030400000 0x0000000000c00000;
-/memreserve/ 0x0000000030000000 0x0000000000400000;
-/memreserve/ 0x0000000400000000 0x0000000000600450;
-
-/* Root node */
-/ {
+Device Tree
+===========
+
+General notes on the Device Tree produced by skiboot. This chapter
+**needs updating**.
+
+
+General comments
+----------------
+
+* skiboot does not require nodes to have phandle properties, but
+ if you have them then *all* nodes must have them including the
+ root of the device-tree (currently a HB bug !). It is recommended
+ to have them since they are needed to represent the cache levels.
+* **NOTE**: The example tree below only has phandle properties for
+ nodes that are referenced by other nodes. This is *not* correct
+ and is purely done for keeping this document smaller, make sure
+ to follow the rule above.
+* Only the "phandle" property is required. Sapphire also generates
+ a "linux,phandle" for backward compatibility but doesn't require
+ it as an input
+* Any property not specifically documented must be put in "as is"
+* All ibm,chip-id properties contain a HW chip ID which correspond
+ on P8 to the PIR value shifted right by 7 bits, ie. it's a 6-bit
+ value made of a 3-bit node number and a 3-bit chip number.
+* Unit addresses (@xxxx part of node names) should if possible use
+ lower case hexadecimal to be consistent with what skiboot does
+ and to help some stupid parsers out there...
+
+
+Reserve Map
+-----------
+
+Here are the reserve map entries. They should exactly match the
+reserved-ranges property of the root node (see documentation
+of that property)::
+
+ /memreserve/ 0x00000007fe600000 0x0000000000100000;
+ /memreserve/ 0x00000007fe200000 0x0000000000100000;
+ /memreserve/ 0x0000000031e00000 0x00000000003e0000;
+ /memreserve/ 0x0000000031000000 0x0000000000e00000;
+ /memreserve/ 0x0000000030400000 0x0000000000c00000;
+ /memreserve/ 0x0000000030000000 0x0000000000400000;
+ /memreserve/ 0x0000000400000000 0x0000000000600450;
+
+Root Node
+---------
+
+Root node of device tree::
+
+ / {
/*
* "compatible" properties are string lists (ASCII strings separated by
* \0 characters) indicating the overall compatibility from the more
@@ -512,4 +489,4 @@
}
};
};
-};
+ };
diff --git a/doc/error-logging.rst b/doc/error-logging.rst
index 7c62520..02261e8 100644
--- a/doc/error-logging.rst
+++ b/doc/error-logging.rst
@@ -1,4 +1,4 @@
-How to log errors on Sapphire and POWERNV:
+How to log errors on Sapphire and POWERNV
=========================================
Currently the errors reported by POWERNV/Sapphire (OPAL) interfaces
@@ -14,8 +14,8 @@ passed by user using the error-logging interfaces outlined below.
Following which, PEL structure is generated based on the input and
then passed on to FSP.
-Error logging interfaces in Sapphire:
-====================================
+Error logging interfaces in Sapphire
+------------------------------------
Interfaces are provided for the user to log/report an error in Sapphire.
Using these interfaces relevant error information is collected and later
@@ -23,29 +23,30 @@ converted to PEL format and then pushed to FSP.
Step 1: To report an error, invoke opal_elog_create() with required argument.
- struct errorlog *opal_elog_create(struct opal_err_info *e_info,
- uint32_t tag);
+ ``struct errorlog *opal_elog_create(struct opal_err_info *e_info, uint32_t tag);``
- Parameters:
-
- struct opal_err_info *e_info: Struct to hold information identifying
- error/event source.
+Parameters:
- uint32_t tag: Unique value to identify the data.
+ * ``struct opal_err_info *e_info``
+ Struct to hold information identifying error/event source.
+ * ``uint32_t tag:`` Unique value to identify the data.
Ideal to have ASCII value for 4-byte string.
The opal_err_info struct holds several pieces of information to help
identify the error/event. The struct can be obtained via the
- DEFINE_LOG_ENTRY macro as below - it only needs to be called once.
+ ``DEFINE_LOG_ENTRY`` macro as below - it only needs to be called once.
- DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_CHIP,
+ ::
+
+ DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_CHIP,
OPAL_PLATFORM_FIRMWARE, OPAL_PREDICTIVE_ERR_GENERAL,
OPAL_NA);
The various attributes set by this macro are described below.
- uint8_t opal_error_event_type: Classification of error/events
- type reported on OPAL
+ ``uint8_t opal_error_event_type``: Classification of error/events
+ type reported on OPAL::
+
/* Platform Events/Errors: Report Machine Check Interrupt */
#define OPAL_PLATFORM_ERR_EVT 0x01
/* INPUT_OUTPUT: Report all I/O related events/errors */
@@ -55,10 +56,11 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
/* MISC: Miscellaneous error */
#define OPAL_MISC_ERR_EVT 0x04
- uint16_t component_id: Component ID of Sapphire component as
+ ``uint16_t component_id``: Component ID of Sapphire component as
listed in include/errorlog.h
- uint8_t subsystem_id: ID of the sub-system reporting error.
+ ``uint8_t subsystem_id``: ID of the sub-system reporting error.::
+
/* OPAL Subsystem IDs listed for reporting events/errors */
#define OPAL_PROCESSOR_SUBSYSTEM 0x10
#define OPAL_MEMORY_SUBSYSTEM 0x20
@@ -72,7 +74,8 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
#define OPAL_SOFTWARE 0x90
#define OPAL_EXTERNAL_ENV 0xA0
- uint8_t event_severity: Severity of the event/error to be reported
+ ``uint8_t event_severity``: Severity of the event/error to be reported ::
+
#define OPAL_INFO 0x00
#define OPAL_RECOVERED_ERR_GENERAL 0x10
@@ -105,83 +108,84 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
#define OPAL_ERROR_PANIC 0x50
- uint8_t event_subtype: Event Sub-type
- #define OPAL_NA 0x00
- #define OPAL_MISCELLANEOUS_INFO_ONLY 0x01
- #define OPAL_PREV_REPORTED_ERR_RECTIFIED 0x10
- #define OPAL_SYS_RESOURCES_DECONFIG_BY_USER 0x20
- #define OPAL_SYS_RESOURCE_DECONFIG_PRIOR_ERR 0x21
- #define OPAL_RESOURCE_DEALLOC_EVENT_NOTIFY 0x22
- #define OPAL_CONCURRENT_MAINTENANCE_EVENT 0x40
- #define OPAL_CAPACITY_UPGRADE_EVENT 0x60
- #define OPAL_RESOURCE_SPARING_EVENT 0x70
- #define OPAL_DYNAMIC_RECONFIG_EVENT 0x80
- #define OPAL_NORMAL_SYS_PLATFORM_SHUTDOWN 0xD0
- #define OPAL_ABNORMAL_POWER_OFF 0xE0
-
- uint8_t opal_srctype: SRC type, value should be OPAL_SRC_TYPE_ERROR.
+ ``uint8_t event_subtype``: Event Sub-type ::
+
+ #define OPAL_NA 0x00
+ #define OPAL_MISCELLANEOUS_INFO_ONLY 0x01
+ #define OPAL_PREV_REPORTED_ERR_RECTIFIED 0x10
+ #define OPAL_SYS_RESOURCES_DECONFIG_BY_USER 0x20
+ #define OPAL_SYS_RESOURCE_DECONFIG_PRIOR_ERR 0x21
+ #define OPAL_RESOURCE_DEALLOC_EVENT_NOTIFY 0x22
+ #define OPAL_CONCURRENT_MAINTENANCE_EVENT 0x40
+ #define OPAL_CAPACITY_UPGRADE_EVENT 0x60
+ #define OPAL_RESOURCE_SPARING_EVENT 0x70
+ #define OPAL_DYNAMIC_RECONFIG_EVENT 0x80
+ #define OPAL_NORMAL_SYS_PLATFORM_SHUTDOWN 0xD0
+ #define OPAL_ABNORMAL_POWER_OFF 0xE0
+
+
+ ``uint8_t opal_srctype``: SRC type, value should be OPAL_SRC_TYPE_ERROR.
SRC refers to System Reference Code.
It is 4 byte hexa-decimal number that reflects the
current system state.
Eg: BB821010,
- 1st byte -> BB -> SRC Type
- 2nd byte -> 82 -> Subsystem
- 3rd, 4th byte -> Component ID and Reason Code
+
+ * 1st byte -> BB -> SRC Type
+ * 2nd byte -> 82 -> Subsystem
+ * 3rd, 4th byte -> Component ID and Reason Code
+
SRC needs to be generated on the fly depending on the state
of the system. All the parameters needed to generate a SRC
should be provided during reporting of an event/error.
- uint32_t reason_code: Reason for failure as stated in include/errorlog.h
- for Sapphire
+ ``uint32_t reason_code``: Reason for failure as stated in include/errorlog.h for Sapphire.
Eg: Reason code for code-update failures can be
- OPAL_RC_CU_INIT -> Initialisation failure
- OPAL_RC_CU_FLASH -> Flash failure
+
+ * ``OPAL_RC_CU_INIT`` -> Initialisation failure
+ * ``OPAL_RC_CU_FLASH`` -> Flash failure
Step 2: Data can be appended to the user data section using the either of
- the below two interfaces:
+ the below two interfaces: ::
- void log_append_data(struct errorlog *buf, unsigned char *data,
+ void log_append_data(struct errorlog *buf, unsigned char *data,
uint16_t size)
Parameters:
- struct opal_errorlog *buf:
- struct opal_errorlog *buf: struct opal_errorlog pointer returned
- by opal_elog_create() call.
+ ``struct opal_errorlog *buf``: ``struct opal_errorlog`` pointer
+ returned by opal_elog_create() call.
- unsigned char *data: Pointer to the dump data
+ ``unsigned char *data``: Pointer to the dump data
- uint16_t size: Size of the dump data.
+ ``uint16_t size``: Size of the dump data.
- void log_append_msg(struct errorlog *buf, const char *fmt, ...)
+ ``void log_append_msg(struct errorlog *buf, const char *fmt, ...)``
Parameters:
- struct opal_errorlog *buf:
- struct opal_errorlog *buf: struct opal_errorlog pointer returned
- by opal_elog_create() call.
+ ``struct opal_errorlog *buf``: pointer returned by opal_elog_create()
+ call.
- const char *fmt: Formatted error log string.
+ ``const char *fmt``: Formatted error log string.
Additional user data sections can be added to the error log to
separate data (eg. readable text vs binary data) by calling
log_add_section(). The interfaces in Step 2 operate on the 'last'
user data section of the error log.
- void log_add_section(struct errorlog *buf, uint32_t tag);
+ ``void log_add_section(struct errorlog *buf, uint32_t tag);``
Parameters:
- struct opal_errorlog *buf:
- struct opal_errorlog *buf: struct opal_errorlog pointer returned
- by opal_elog_create() call.
+ ``struct opal_errorlog *buf``: pointer returned by opal_elog_create() call.
- uint32_t tag: Unique value to identify the data.
+ ``uint32_t tag``: Unique value to identify the data.
Ideal to have ASCII value for 4-byte string.
Step 3: Once all the data for an error is logged in, the error needs to be
- committed in FSP.
+ committed in FSP. ::
+
+ rc = elog_fsp_commit(buf);
- rc = elog_fsp_commit(buf);
Value of 0 is returned on success.
In the process of committing an error to FSP, log info is first internally
@@ -191,11 +195,13 @@ reported by Sapphire and POWERNV are logged in FSP.
If the user does not intend to dump various user data sections, but just
log the error with some amount of description around that error, they can do
-so using just the simple error logging interface
+so using just the simple error logging interface ::
+
+ log_simple_error(uint32_t reason_code, char *fmt, ...);
-log_simple_error(uint32_t reason_code, char *fmt, ...);
+For example: ::
-Eg: log_simple_error(OPAL_RC_SURVE_STATUS,
+ log_simple_error(OPAL_RC_SURVE_STATUS,
"SURV: Error retreiving surveillance status: %d\n",
err_len);
@@ -203,8 +209,8 @@ Using the reason code, an error log is generated with the information derived
from the look-up table, populated and committed to FSP. All of it
is done with just one call.
-Note:
-====
+Note
+----
* For more information regarding error logging and PEL format
refer to PAPR doc and P7 PEL and SRC PLDD document.
@@ -212,15 +218,17 @@ Note:
interface parameters and include/pel.h for PEL
structures.
-Sample error logging:
-===================
+Sample error logging
+--------------------
-DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_ATTN,
+::
+
+ DEFINE_LOG_ENTRY(OPAL_RC_ATTN, OPAL_PLATFORM_ERR_EVT, OPAL_ATTN,
OPAL_PLATFORM_FIRMWARE, OPAL_PREDICTIVE_ERR_GENERAL,
OPAL_NA);
-void report_error(int index)
-{
+ void report_error(int index)
+ {
struct errorlog *buf;
char data1[] = "This is a sample user defined data section1";
char data2[] = "Error logging sample. These are dummy errors. Section 2";
@@ -258,138 +266,141 @@ void report_error(int index)
/* Once all info is updated, ready to be sent to FSP */
printf("ELOG:commit to FSP\n");
log_commit(buf);
-}
+ }
+
+Sample output PEL dump got from FSP
+-----------------------------------
- Sample output PEL dump got from FSP:
- ===================================
+::
+
$ errl -d -x 0x533C9B37
-| 00000000 50480030 01004154 20150728 02000500 PH.0..AT ..(.... |
-| 00000010 20150728 02000566 4B000107 00000000 ..(...fK....... |
-| 00000020 00000000 00000000 B0000002 533C9B37 ............S..7 |
-| 00000030 55480018 01004154 80002000 00000000 UH....AT.. ..... |
-| 00000040 00002000 01005300 50530050 01004154 .. ...S.PS.P..AT |
-| 00000050 02000008 00000048 00000080 00000000 .......H........ |
-| 00000060 00000000 00000000 00000000 00000000 ................ |
-| 00000070 00000000 00000000 42423832 31343130 ........BB821410 |
-| 00000080 20202020 20202020 20202020 20202020 |
-| 00000090 20202020 20202020 4548004C 01004154 EH.L..AT |
-| 000000A0 38323836 2D343241 31303738 34415400 8286-42A10784AT. |
-| 000000B0 00000000 00000000 00000000 00000000 ................ |
-| 000000C0 00000000 00000000 00000000 00000000 ................ |
-| 000000D0 00000000 00000000 20150728 02000500 ........ ..(.... |
-| 000000E0 00000000 4D54001C 01004154 38323836 ....MT....AT8286 |
-| 000000F0 2D343241 31303738 34415400 00000000 -42A10784AT..... |
-| 00000100 5544003C 01004154 4B4B4B4B 00340000 UD....ATKKKK.4.. |
-| 00000110 54686973 20697320 61207361 6D706C65 This is a sample |
-| 00000120 20757365 72206465 66696E65 64206461 user defined da |
-| 00000130 74612073 65637469 6F6E3100 554400A7 ta section1.UD.. |
-| 00000140 01004154 4C4C4C4C 009F0000 4572726F ..ATLLLL....Erro |
-| 00000150 72206C6F 6767696E 67207361 6D706C65 r logging sample |
-| 00000160 2E205468 65736520 61726520 64756D6D . These are dumm |
-| 00000170 79206572 726F7273 2E205365 6374696F y errors. Sectio |
-| 00000180 6E203200 53616D70 6C652065 72726F72 n 2.Sample error |
-| 00000190 2053616D 706C6520 6572726F 72205361 Sample error Sa |
-| 000001A0 6D706C65 20657272 6F722053 616D706C mple error Sampl |
-| 000001B0 65206572 726F7220 09090953 616D706C e error ...Sampl |
-| 000001C0 65206572 726F7220 61626364 65666768 e error abcdefgh |
-| 000001D0 696A6B6C 6D6E6F70 71727374 75767778 ijklmnopqrstuvwx |
-| 000001E0 797A00 yz. |
-|------------------------------------------------------------------------------|
-| Platform Event Log - 0x533C9B37 |
-|------------------------------------------------------------------------------|
-| Private Header |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Created by : 4154 |
-| Created at : 07/28/2015 02:00:05 |
-| Committed at : 07/28/2015 02:00:05 |
-| Creator Subsystem : OPAL |
-| CSSVER : |
-| Platform Log Id : 0xB0000002 |
-| Entry Id : 0x533C9B37 |
-| Total Log Size : 483 |
-|------------------------------------------------------------------------------|
-| User Header |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Log Committed by : 4154 |
-| Subsystem : Platform Firmware |
-| Event Scope : Unknown - 0x00000000 |
-| Event Severity : Predictive Error |
-| Event Type : Not Applicable |
-| Return Code : 0x00000000 |
-| Action Flags : Report Externally |
-| Action Status : Sent to Hypervisor |
-|------------------------------------------------------------------------------|
-| Primary System Reference Code |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Created by : 4154 |
-| SRC Format : 0x80 |
-| SRC Version : 0x02 |
-| Virtual Progress SRC : False |
-| I5/OS Service Event Bit : False |
-| Hypervisor Dump Initiated: False |
-| Power Control Net Fault : False |
-| |
-| Valid Word Count : 0x08 |
-| Reference Code : BB821410 |
-| Hex Words 2 - 5 : 00000080 00000000 00000000 00000000 |
-| Hex Words 6 - 9 : 00000000 00000000 00000000 00000000 |
-| |
-|------------------------------------------------------------------------------|
-| Extended User Header |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Created by : 4154 |
-| Reporting Machine Type : 8286-42A |
-| Reporting Serial Number : 10784AT |
-| FW Released Ver : |
-| FW SubSys Version : |
-| Common Ref Time : 07/28/2015 02:00:05 |
-| Symptom Id Len : 0 |
-| Symptom Id : |
-|------------------------------------------------------------------------------|
-| Machine Type/Model & Serial Number |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Created by : 4154 |
-| Machine Type Model : 8286-42A |
-| Serial Number : 10784AT |
-|------------------------------------------------------------------------------|
-| User Defined Data |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Created by : 4154 |
-| |
-| 00000000 4B4B4B4B 00340000 54686973 20697320 KKKK.4..This is |
-| 00000010 61207361 6D706C65 20757365 72206465 a sample user de |
-| 00000020 66696E65 64206461 74612073 65637469 fined data secti |
-| 00000030 6F6E3100 on1. |
-| |
-|------------------------------------------------------------------------------|
-| User Defined Data |
-|------------------------------------------------------------------------------|
-| Section Version : 1 |
-| Sub-section type : 0 |
-| Created by : 4154 |
-| |
-| 00000000 4C4C4C4C 009F0000 4572726F 72206C6F LLLL....Error lo |
-| 00000010 6767696E 67207361 6D706C65 2E205468 gging sample. Th |
-| 00000020 65736520 61726520 64756D6D 79206572 ese are dummy er |
-| 00000030 726F7273 2E205365 6374696F 6E203200 rors. Section 2. |
-| 00000040 53616D70 6C652065 72726F72 2053616D Sample error Sam |
-| 00000050 706C6520 6572726F 72205361 6D706C65 ple error Sample |
-| 00000060 20657272 6F722053 616D706C 65206572 error Sample er |
-| 00000070 726F7220 09090953 616D706C 65206572 ror ...Sample er |
-| 00000080 726F7220 61626364 65666768 696A6B6C ror abcdefghijkl |
-| 00000090 6D6E6F70 71727374 75767778 797A00 mnopqrstuvwxyz. |
-| |
-|------------------------------------------------------------------------------|
+ | 00000000 50480030 01004154 20150728 02000500 PH.0..AT ..(.... |
+ | 00000010 20150728 02000566 4B000107 00000000 ..(...fK....... |
+ | 00000020 00000000 00000000 B0000002 533C9B37 ............S..7 |
+ | 00000030 55480018 01004154 80002000 00000000 UH....AT.. ..... |
+ | 00000040 00002000 01005300 50530050 01004154 .. ...S.PS.P..AT |
+ | 00000050 02000008 00000048 00000080 00000000 .......H........ |
+ | 00000060 00000000 00000000 00000000 00000000 ................ |
+ | 00000070 00000000 00000000 42423832 31343130 ........BB821410 |
+ | 00000080 20202020 20202020 20202020 20202020 |
+ | 00000090 20202020 20202020 4548004C 01004154 EH.L..AT |
+ | 000000A0 38323836 2D343241 31303738 34415400 8286-42A10784AT. |
+ | 000000B0 00000000 00000000 00000000 00000000 ................ |
+ | 000000C0 00000000 00000000 00000000 00000000 ................ |
+ | 000000D0 00000000 00000000 20150728 02000500 ........ ..(.... |
+ | 000000E0 00000000 4D54001C 01004154 38323836 ....MT....AT8286 |
+ | 000000F0 2D343241 31303738 34415400 00000000 -42A10784AT..... |
+ | 00000100 5544003C 01004154 4B4B4B4B 00340000 UD....ATKKKK.4.. |
+ | 00000110 54686973 20697320 61207361 6D706C65 This is a sample |
+ | 00000120 20757365 72206465 66696E65 64206461 user defined da |
+ | 00000130 74612073 65637469 6F6E3100 554400A7 ta section1.UD.. |
+ | 00000140 01004154 4C4C4C4C 009F0000 4572726F ..ATLLLL....Erro |
+ | 00000150 72206C6F 6767696E 67207361 6D706C65 r logging sample |
+ | 00000160 2E205468 65736520 61726520 64756D6D . These are dumm |
+ | 00000170 79206572 726F7273 2E205365 6374696F y errors. Sectio |
+ | 00000180 6E203200 53616D70 6C652065 72726F72 n 2.Sample error |
+ | 00000190 2053616D 706C6520 6572726F 72205361 Sample error Sa |
+ | 000001A0 6D706C65 20657272 6F722053 616D706C mple error Sampl |
+ | 000001B0 65206572 726F7220 09090953 616D706C e error ...Sampl |
+ | 000001C0 65206572 726F7220 61626364 65666768 e error abcdefgh |
+ | 000001D0 696A6B6C 6D6E6F70 71727374 75767778 ijklmnopqrstuvwx |
+ | 000001E0 797A00 yz. |
+ |------------------------------------------------------------------------------|
+ | Platform Event Log - 0x533C9B37 |
+ |------------------------------------------------------------------------------|
+ | Private Header |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Created by : 4154 |
+ | Created at : 07/28/2015 02:00:05 |
+ | Committed at : 07/28/2015 02:00:05 |
+ | Creator Subsystem : OPAL |
+ | CSSVER : |
+ | Platform Log Id : 0xB0000002 |
+ | Entry Id : 0x533C9B37 |
+ | Total Log Size : 483 |
+ |------------------------------------------------------------------------------|
+ | User Header |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Log Committed by : 4154 |
+ | Subsystem : Platform Firmware |
+ | Event Scope : Unknown - 0x00000000 |
+ | Event Severity : Predictive Error |
+ | Event Type : Not Applicable |
+ | Return Code : 0x00000000 |
+ | Action Flags : Report Externally |
+ | Action Status : Sent to Hypervisor |
+ |------------------------------------------------------------------------------|
+ | Primary System Reference Code |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Created by : 4154 |
+ | SRC Format : 0x80 |
+ | SRC Version : 0x02 |
+ | Virtual Progress SRC : False |
+ | I5/OS Service Event Bit : False |
+ | Hypervisor Dump Initiated: False |
+ | Power Control Net Fault : False |
+ | |
+ | Valid Word Count : 0x08 |
+ | Reference Code : BB821410 |
+ | Hex Words 2 - 5 : 00000080 00000000 00000000 00000000 |
+ | Hex Words 6 - 9 : 00000000 00000000 00000000 00000000 |
+ | |
+ |------------------------------------------------------------------------------|
+ | Extended User Header |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Created by : 4154 |
+ | Reporting Machine Type : 8286-42A |
+ | Reporting Serial Number : 10784AT |
+ | FW Released Ver : |
+ | FW SubSys Version : |
+ | Common Ref Time : 07/28/2015 02:00:05 |
+ | Symptom Id Len : 0 |
+ | Symptom Id : |
+ |------------------------------------------------------------------------------|
+ | Machine Type/Model & Serial Number |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Created by : 4154 |
+ | Machine Type Model : 8286-42A |
+ | Serial Number : 10784AT |
+ |------------------------------------------------------------------------------|
+ | User Defined Data |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Created by : 4154 |
+ | |
+ | 00000000 4B4B4B4B 00340000 54686973 20697320 KKKK.4..This is |
+ | 00000010 61207361 6D706C65 20757365 72206465 a sample user de |
+ | 00000020 66696E65 64206461 74612073 65637469 fined data secti |
+ | 00000030 6F6E3100 on1. |
+ | |
+ |------------------------------------------------------------------------------|
+ | User Defined Data |
+ |------------------------------------------------------------------------------|
+ | Section Version : 1 |
+ | Sub-section type : 0 |
+ | Created by : 4154 |
+ | |
+ | 00000000 4C4C4C4C 009F0000 4572726F 72206C6F LLLL....Error lo |
+ | 00000010 6767696E 67207361 6D706C65 2E205468 gging sample. Th |
+ | 00000020 65736520 61726520 64756D6D 79206572 ese are dummy er |
+ | 00000030 726F7273 2E205365 6374696F 6E203200 rors. Section 2. |
+ | 00000040 53616D70 6C652065 72726F72 2053616D Sample error Sam |
+ | 00000050 706C6520 6572726F 72205361 6D706C65 ple error Sample |
+ | 00000060 20657272 6F722053 616D706C 65206572 error Sample er |
+ | 00000070 726F7220 09090953 616D706C 65206572 ror ...Sample er |
+ | 00000080 726F7220 61626364 65666768 696A6B6C ror abcdefghijkl |
+ | 00000090 6D6E6F70 71727374 75767778 797A00 mnopqrstuvwxyz. |
+ | |
+ |------------------------------------------------------------------------------|
diff --git a/doc/gcov.rst b/doc/gcov.rst
index 956c5c8..d50fbe5 100644
--- a/doc/gcov.rst
+++ b/doc/gcov.rst
@@ -1,11 +1,11 @@
GCOV for skiboot
-----------------
+================
Unit tests
----------
-All unit tests are built+run with gcov enabled.
+All unit tests are built+run with gcov enabled. ::
-make coverage-report
+ make coverage-report
will generate a unit test coverage report like:
http://open-power.github.io/skiboot/coverage-report/
@@ -18,10 +18,11 @@ from real hardware (or a simulator).
Building Skiboot with GCOV
--------------------------
+::
-SKIBOOT_GCOV=1 make
+ SKIBOOT_GCOV=1 make
-You may need to "make clean" first.
+You may need to ``make clean`` first.
This will build a skiboot lid roughly *twice* the size.
@@ -33,28 +34,36 @@ The way we extract the gcov data from a system is by dumping the contents
of skiboot memory and then parsing the data structures in user space with
the extract-gcov utility in the skiboot repo.
-mambo:
+mambo: ::
+
mysim memory fwrite 0x30000000 0x240000 skiboot.dump
-FSP:
+
+FSP: ::
+
getmemproc 30000000 3407872 -fb skiboot.dump
-linux (e.g. petitboot environment):
+
+linux (e.g. petitboot environment): ::
+
dd if=/proc/kcore skip=1572864 count=6656 of=skiboot.dump
You basically need to dump out the first 3MB of skiboot memory.
-Then you need to find out where the gcov data structures are:
-perl -e "printf '0x%x', 0x30000000 + 0x`grep gcov_info_list skiboot.map|cut -f 1 -d ' '`"
+Then you need to find out where the gcov data structures are: ::
+
+ perl -e "printf '0x%x', 0x30000000 + 0x`grep gcov_info_list skiboot.map|cut -f 1 -d ' '`"
-That address needs to be supplied to the extract-gcov utility:
-./extract-gcov skiboot.dump 0x3023ec40
+That address needs to be supplied to the extract-gcov utility: ::
+
+ ./extract-gcov skiboot.dump 0x3023ec40
Once you've run extract-gcov, it will have extracted the gcda files
from the skiboot memory image.
-You can then run lcov:
-lcov -b . -q -c -d . -o skiboot-boot.info \
---gcov-tool
-/opt/cross/gcc-4.8.0-nolibc/powerpc64-linux/bin/powerpc64-linux-gcov
+You can then run lcov: ::
+
+ lcov -b . -q -c -d . -o skiboot-boot.info
+ --gcov-tool
+ /opt/cross/gcc-4.8.0-nolibc/powerpc64-linux/bin/powerpc64-linux-gcov
*IMPORTANT* you should point lcov to the gcov for the compiler you used
to build skiboot, otherwise you're likely to get errors.
diff --git a/doc/index.rst b/doc/index.rst
index 5630004..bd40ad8 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -11,6 +11,21 @@ Contents:
.. toctree::
:maxdepth: 2
+ overview
+ opal-spec
+ console-log
+ device-tree
+ error-logging
+ bmc
+ gcov
+ memory
+ nvlink
+ stable-skiboot-rules
+ versioning
+ pci
+ pci-slot
+ xscom-node-bindings
+
Indices and tables
==================
diff --git a/doc/memory.rst b/doc/memory.rst
index 002d460..923509d 100644
--- a/doc/memory.rst
+++ b/doc/memory.rst
@@ -1,5 +1,5 @@
Memory in skiboot
------------------
+=================
There are regions of memory we statically allocate for firmware as well as
a HEAP region for boot and runtime allocations.
@@ -25,20 +25,23 @@ all the heap once skiboot became 2MB with GCOV.
Heap usage is printed before running the payload.
-For example, as of writing, on a dual socket Tuleta:
-[45215870591,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
-[3680939340,5] CUPD: T side MI Keyword = SV830_027
-[3680942658,5] CUPD: T side ML Keyword = FW830.00
-[15404383291,5] Region ibm,firmware-heap free: 5378072
+For example, as of writing, on a dual socket Tuleta: ::
-and on a palmetto:
-[24748502575,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
-[9870429550,5] Region ibm,firmware-heap free: 10814856
+ [45215870591,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
+ [3680939340,5] CUPD: T side MI Keyword = SV830_027
+ [3680942658,5] CUPD: T side ML Keyword = FW830.00
+ [15404383291,5] Region ibm,firmware-heap free: 5378072
-Our memory allocator is simple, a use pattern of:
-A = malloc();
-B = malloc();
-free(A);
+and on a palmetto: ::
+
+ [24748502575,5] SkiBoot skiboot-5.0.1-94-gb759ce2 starting...
+ [9870429550,5] Region ibm,firmware-heap free: 10814856
+
+Our memory allocator is simple, a use pattern of: ::
+
+ A = malloc();
+ B = malloc();
+ free(A);
is likely to generate fragmentation, so it should generally be avoided
where possible.
diff --git a/doc/nvlink.rst b/doc/nvlink.rst
index 5aef539..981cf11 100644
--- a/doc/nvlink.rst
+++ b/doc/nvlink.rst
@@ -1,9 +1,8 @@
OPAL/Skiboot Nvlink Interface Documentation
-----------------------------------------------------------------------
+===========================================
-========
Overview
-========
+--------
NV-Link is a high speed interconnect that is used in conjunction with
a PCI-E connection to create an interface between chips that provides
@@ -22,9 +21,8 @@ Presently the NV-Link is only capable of data transfers initiated by
the target, thus the emulated PCI device will only handle registers
for link initialisation, DMA transfers and error reporting (EEH).
-====================
Emulated PCI Devices
-====================
+--------------------
Each link will be exported as an emulated PCI device with a minimum of
two emulated PCI devices per GPU. Emulated PCI devices are grouped per
@@ -36,38 +34,42 @@ necessary device parameters. The only functionality available is
related to the setup of DMA windows.
Configuration Space Parameters
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Vendor ID = 0x1014 (IBM)
-Device ID = 0x04ea
-Revision ID = 0x00
-Class = 0x068000 (Bridge Device Other, ProgIf = 0x0)
-BAR0/1 = TL/DL Registers
+============ =============== =====
+============ =============== =====
+Vendor ID 0x1014 (IBM)
+Device ID 0x04ea
+Revision ID 0x00
+Class 0x068000 (Bridge Device Other, ProgIf = 0x0)
+BAR0/1 TL/DL Registers
+============ =============== =====
TL/DL Registers
----------------
+^^^^^^^^^^^^^^^
Each link has 128KB of TL/DL registers. These will always be mapped
-to 64-bit BAR#0 of the emulated PCI device configuration space.
+to 64-bit BAR#0 of the emulated PCI device configuration space. ::
-BAR#0 + 128K +-----------+
- | NTL (64K) |
-BAR#0 + 64K +-----------+
+ BAR#0 + 128K +-----------+
+ | NTL (64K) |
+ BAR#0 + 64K +-----------+
| DL (64K) |
-BAR#0 +-----------+
+ BAR#0 +-----------+
Vendor Specific Capabilities
-----------------------------
-
-+-----------------+----------------+----------------+----------------+
-| Version (0x02) | Cap Length | Next Cap Ptr | Cap ID (0x09) |
-+-----------------+----------------+----------------+----------------+
-| Procedure Status Register |
-+--------------------------------------------------------------------+
-| Procedure Control Register |
-+---------------------------------------------------+----------------+
-| Reserved | PCI Dev Flag | Link Number |
-+---------------------------------------------------+----------------+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+::
+
+ +-----------------+----------------+----------------+----------------+
+ | Version (0x02) | Cap Length | Next Cap Ptr | Cap ID (0x09) |
+ +-----------------+----------------+----------------+----------------+
+ | Procedure Status Register |
+ +--------------------------------------------------------------------+
+ | Procedure Control Register |
+ +---------------------------------------------------+----------------+
+ | Reserved | PCI Dev Flag | Link Number |
+ +---------------------------------------------------+----------------+
Version
@@ -88,19 +90,20 @@ Procedure Control Register
procedure number depending on the procedure status field.
Procedure Numbers:
- 0 - Abort in-progress procedure
- 1 - NOP
- 2 - Unsupported procedure
- 3 - Unsupported procedure
- 4 - Naples PHY - RESET
- 5 - Naples PHY - TX_ZCAL
- 6 - Naples PHY - RX_DCCAL
- 7 - Naples PHY - TX_RXCAL_ENABLE
- 8 - Naples PHY - TX_RXCAL_DISABLE
- 9 - Naples PHY - RX_TRAINING
- 10 - Naples NPU - RESET
- 11 - Naples PHY - PHY preterminate
- 12 - Naples PHY - PHY terminated
+
+ 0. Abort in-progress procedure
+ 1. NOP
+ 2. Unsupported procedure
+ 3. Unsupported procedure
+ 4. Naples PHY - RESET
+ 5. Naples PHY - TX_ZCAL
+ 6. Naples PHY - RX_DCCAL
+ 7. Naples PHY - TX_RXCAL_ENABLE
+ 8. Naples PHY - TX_RXCAL_DISABLE
+ 9. Naples PHY - RX_TRAINING
+ 10. Naples NPU - RESET
+ 11. Naples PHY - PHY preterminate
+ 12. Naples PHY - PHY terminated
Procedure 5 (TX_ZCAL) should only be run once. System firmware will
ensure this so device drivers may call this procedure mutiple
@@ -142,7 +145,7 @@ Reserved
These fields must be ignored and no value should be assumed.
Interrupts
-----------
+^^^^^^^^^^
Each link has a single DL/TL interrupt assigned to it. These will be
exposed as an LSI via the emulated PCI device. There are 4 links
@@ -150,8 +153,7 @@ consuming 4 LSI interrupts. The 4 remaining interrupts supported by the
corresponding PHB will be routed to OS platform for the purpose of error
reporting.
-====================
Device Tree Bindings
-====================
+--------------------
See doc/device-tree/nvlink.txt
diff --git a/doc/opal-spec.rst b/doc/opal-spec.rst
index ea76e59..eca8472 100644
--- a/doc/opal-spec.rst
+++ b/doc/opal-spec.rst
@@ -1,9 +1,9 @@
OPAL Specification
==================
-DRAFT - VERSION 0.0.1 AT BEST.
+**DRAFT - VERSION 0.0.1 AT BEST.**
-COMMENTS ARE WELCOME - and indeed, needed.
+**COMMENTS ARE WELCOME** - and indeed, needed.
If you are reading this, congratulations: you're now reviewing it!
@@ -34,21 +34,27 @@ POWER systems. There are several components to what makes up a firmware
image for OpenPower machines.
For example, there may be:
-- BMC firmware
- - Firmware that runs purely on the BMC.
- - On IBM systems that have an FSP rather than a BMC, there is FSP firmware
- - While essential to having the machine function, this firmware is not
+
+* BMC firmware
+
+ * Firmware that runs purely on the BMC.
+ * On IBM systems that have an FSP rather than a BMC, there is FSP firmware
+ * While essential to having the machine function, this firmware is not
part of the OPAL Specification.
-- HostBoot
- - HostBoot ( https://github.com/open-power/hostboot ) performs all
+* HostBoot
+
+ * HostBoot ( https://github.com/open-power/hostboot ) performs all
processor, bus and memory initialization within IBM POWER based systems.
-- OCC Firmware
- - On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
+* OCC Firmware
+
+ * On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
POWER8 in charge of keeping the system thermally and power safe ).
-- SkiBoot
- - Boot and runtime services.
-- A linux kernel and initramfs incorporating petitboot
- - The bootloader. This is where a user chooses what OS to boot, and
+* SkiBoot
+
+ * Boot and runtime services.
+* A linux kernel and initramfs incorporating petitboot
+
+ * The bootloader. This is where a user chooses what OS to boot, and
petitboot will use kexec to switch to the host Operating System
(for example, PowerKVM).
@@ -66,15 +72,17 @@ Operating System. It does not dictate that any specific pieces of firmware
code be used, although re-inventing the wheel is strongly discouraged.
The OPAL Specification explicitly allows for:
-- A conforming implementation to not use any of the reference implementation
+
+* A conforming implementation to not use any of the reference implementation
code.
-- A conforming implementation to use any 64bit POWER ISA conforming processor,
+* A conforming implementation to use any 64bit POWER ISA conforming processor,
and not be limited to the IBM POWER8.
-- A conforming implementation to be a simulator, emulator or virtual environment
-- A host OS other than Linux
+* A conforming implementation to be a simulator, emulator or virtual environment
+* A host OS other than Linux
Explicitly not covered in this specification:
-- A 32bit OPAL Specification
+
+* A 32bit OPAL Specification
There is no reason this couldn't exist but the current specification is for
64bit POWER systems only.
@@ -93,32 +101,38 @@ The OPAL Specification explicitly allows variation in this payload.
A requirement of the payload is that it MUST support loading and booting
an uncomppressed vmlinux Linux kernel.
-[TODO: expand on what this actually means]
+[**TODO**: expand on what this actually means]
An OPAL system MUST pass a device tree to the host kernel.
-[TODO: expand the details, add device-tree section and spec]
+[**TODO**: expand the details, add device-tree section and spec]
An OPAL system MUST provide the host kernel with enough information to
know how to call OPAL runtime services.
-[TODO: expand on this. ]
+[**TODO**: expand on this. ]
Explicitly not covered by the OPAL Specification:
-- Kernel module ABI for skiroot kernel
-- Userspace environment of skiroot
-- That skiroot is Linux.
+
+* Kernel module ABI for skiroot kernel
+* Userspace environment of skiroot
+* That skiroot is Linux.
Explicitly allowed:
-- Replacing the payload with something of equal/similar functionality
+
+* Replacing the payload with something of equal/similar functionality
(weather replacing skiroot with an implementation of Zork would be compliant
- is left as an exercise for the reader)
+ is left as an exercise for the reader)
Payload Environment
-------------------
The payload is started with:
-r3 = address of flattened device-tree (fdt)
-r8 = OPAL base
-r9 = OPAL entry
+======== =====
+Register Value
+======== =====
+r3 address of flattened device-tree (fdt)
+r8 OPAL base
+r9 OPAL entry
+======== =====
Runtime Services
----------------
@@ -143,12 +157,13 @@ All parameters to OPAL calls are big endian. Little endian hosts MUST
appropriately convert parameters before passing them to OPAL.
Machine state across OPAL calls:
-- r1 is preserved
-- r12 is scratch
-- r13 - 31 preserved
-- 64bit HV real mode
-- big endian
-- external interrupts disabled
+
+* r1 is preserved
+* r12 is scratch
+* r13 - 31 preserved
+* 64bit HV real mode
+* big endian
+* external interrupts disabled
Detecting OPAL Support
----------------------
@@ -165,14 +180,14 @@ The presence of the "/ibm,opal" entry in the device tree signifies running
under OPAL. Additionally, the "/ibm,opal" node MUST have a compatibile property
listing "ibm,opal-v3".
-The "/ibm,opal" node MUST have the following properties:
+The "/ibm,opal" node MUST have the following properties: ::
-ibm,opal {
+ ibm,opal {
compatible = "ibm,opal-v3";
opal-base-address = <>;
opal-entry-address = <>;
opal-runtime-size = <>;
-}
+ }
The compatible property MAY have other strings, such as a future "ibm,opal-v4".
These are reserved for future use.
@@ -182,11 +197,11 @@ contain "ibm,opal-v2" as well as "ibm,opal-v3". Host operating systems MUST
NOT rely on "ibm,opal-v2", this is a relic from early OPAL history.
The "ibm,opal" node MUST have a child node named "firmware". It MUST contain
-the following:
+the following: ::
-firmware {
+ firmware {
compatible = "ibm,opal-firmware";
-}
+ }
It MUST contain one of the following two properties: git-id, version.
The git-id property is deprecated, and version SHOULD be used. These
diff --git a/doc/overview.rst b/doc/overview.rst
index 760f391..e324ca2 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -6,6 +6,10 @@ it provides some runtime services to the OS (typically Linux).
Source layout
-------------
+
+========= ===================================
+Directory Content
+========= ===================================
asm/ small amount, mainly entry points
ccan/ bits from CCAN
core/ common code among machines.
@@ -17,6 +21,7 @@ include/ headers!
libc/ tiny libc, from SLOF
libfdt/ straight device tree lib
libpore/ to manipulate PORE engine.
+========= ===================================
We have a spinlock implementation in asm/lock.S
Entry points are detailed in asm/head.S
@@ -26,9 +31,13 @@ Binaries
--------
The following binaries are built:
-skiboot.lid: is the actual lid. objdump out
-skiboot.elf: is the elf binary of it, lid comes from this
-skiboot.map: plain map of symbols
+=========== ============================================
+File Purpose
+=========== ============================================
+skiboot.lid is the actual lid. objdump out
+skiboot.elf is the elf binary of it, lid comes from this
+skiboot.map plain map of symbols
+=========== ============================================
Booting
-------
@@ -65,7 +74,7 @@ At the bottom of each stack area is a per CPU data structure, which we
can get to by chopping off the LSBs of the stack pointer.
The OPAL interface is a generic message queue. The Linux side of things
-can be found in linux/arch/powerpc/platform/powernv/opal-*.c
+can be found in linux/arch/powerpc/platform/powernv/
Interrupts
----------
@@ -99,11 +108,12 @@ should be used sparingly though.
Important memory locations:
-SKIBOOT_BASE - where we sit
-
-HEAP_BASE,
-HEAP_SIZE - the location and size for heap. We reserve 4MB for
- initial allocations.
+============= ============================================================
+Location What's there
+============= ============================================================
+SKIBOOT_BASE where skiboot lives, of SKIBOOT_SIZE
+HEAP_BASE Where skiboot heap starts, of HEAP_SIZE
+============= ============================================================
There is also SKIBOOT_SIZE (manually calculated) and DEVICE_TREE_MAX_SIZE,
which is largely historical.
diff --git a/doc/pci-slot.rst b/doc/pci-slot.rst
index 1b64f69..e76fba1 100644
--- a/doc/pci-slot.rst
+++ b/doc/pci-slot.rst
@@ -1,5 +1,5 @@
-Overview
-========
+PCI Slots
+=========
The PCI slots are instantiated to represent their associated properties and
operations. The slot properties are exported to OS through the device tree
@@ -26,11 +26,14 @@ The operation set supplied by the template might be overrided and reimplemented,
partially. It's usually done according to the VPD figured out by individual platforms.
PCI Slot Operations
-===================
+-------------------
The following operations are supported to one particular PCI slot. More details
could be found from the definition of struct pci_slot_ops:
+===================== ==========
+Operation Definition
+===================== ==========
get_presence_state Check if any adapter connected to slot
get_link_state Retrieve PCIE link status: up, down, link width
get_power_state Retrieve the power status: on, off
@@ -48,6 +51,7 @@ hreset Hot reset
poll Interface for OPAL API to drive internal state machine
add_properties Additional PCI slot properties seen by platform
+===================== ==========
PCI Slot Properties
===================
@@ -57,16 +61,19 @@ node for a root port, a PCIE switch port, or a PCIE to PCIx bridge. If the
individual platforms (e.g. Firenze and Apollo) have VPD for the PCI slot, they
should extract the PCI slot properties from VPD and export them accordingly.
-ibm,reset-by-firmware Boolean indicating whether the slot reset should be
- done in firmware
+====================== ==========
+Property Definition
+====================== ==========
+ibm,reset-by-firmware Boolean indicating whether the slot reset should be done in firmware
ibm,slot-pluggable Boolean indicating whether the slot is pluggable
ibm,slot-power-ctl Boolean indicating whether the slot has power control
ibm,slot-wired-lanes The number of hardware lanes that are wired
ibm,slot-pwr-led-ctl Presence of slot power led, and controlling entity
ibm,slot-attn-led-ctl Presence of slot ATTN led, and controlling entity
+====================== ==========
PCI Hotplug
-===========
+-----------
The implementation of PCI slot hotplug heavily relies on its power state.
Initially, the slot is powered off if there are no adapters behind it.
@@ -98,7 +105,7 @@ The API call will return OPAL_SUCCESS immediately and no further asynchronous
message will be sent.
PCI Slot on Apollo and Firenze
-==============================
+------------------------------
On IBM's Apollo and Firenze platform, the PCI VPD is fetched from dedicated LID,
which is organized in so-called 1004, 1005, or 1006 format. 1006 mapping format
@@ -115,5 +122,9 @@ power management entity doesn't exist.
For Apollo and Firenze platform, following PCI slot properties are exported through
PCI device tree node except those generic properties (as above):
+======================= ==========
+Property Definition
+======================= ==========
ibm,slot-location-code System location code string for the slot connector
ibm,slot-label Slot label, part of "ibm,slot-location-code"
+======================= ==========
diff --git a/doc/pci.rst b/doc/pci.rst
index a139176..5ccfd6e 100644
--- a/doc/pci.rst
+++ b/doc/pci.rst
@@ -1,71 +1,61 @@
+PCI
+===
+
+**WARNING**: This documentation **urgently needs updating** and is *woefully* incomplete.
+
IODA PE Setup Sequences
-----------------------
-(WARNING: this was rescued from old internal documentation. Needs verification)
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
To setup basic PE mappings, the host performs this basic sequence:
- For ibm,opal-ioda2, prior to allocating PHB resources to PEs, the host must
- allocate memory for PE structures and then calls
- opal_pci_set_phb_table_memory( phb_id, rtt_addr, ivt_addr, ivt_len,
- rrba_addr, peltv_addr) to define them to the PHB. OPAL returns
- OPAL_UNSUPPORTED status for ibm,opal-ioda PHBs.
+For ibm,opal-ioda2, prior to allocating PHB resources to PEs, the host must
+allocate memory for PE structures and then calls
+``opal_pci_set_phb_table_memory( phb_id, rtt_addr, ivt_addr, ivt_len, rrba_addr, peltv_addr)`` to define them to the PHB. OPAL returns ``OPAL_UNSUPPORTED`` status for ``ibm,opal-ioda`` PHBs.
- The host calls opal_pci_set_pe( phb_id, pe_number, bus, dev, func,
- validate_mask, bus_mask, dev_mask, func mask) to map a PE to a PCI RID or
- range of RIDs in the same PE domain.
+The host calls ``opal_pci_set_pe( phb_id, pe_number, bus, dev, func, validate_mask, bus_mask, dev_mask, func mask)`` to map a PE to a PCI RID or range of RIDs in the same PE domain.
- The host calls opal_pci_set_peltv(phb_id, parent_pe, child_pe, state) to
- set a parent PELT vector bit for the child PE argument to 1 (a child of the
- parent) or 0 (not in the parent PE domain).
+The host calls ``opal_pci_set_peltv(phb_id, parent_pe, child_pe, state)`` to
+set a parent PELT vector bit for the child PE argument to 1 (a child of the
+parent) or 0 (not in the parent PE domain).
IODA MMIO Setup Sequences
-------------------------
-(WARNING: this was rescued from old internal documentation. Needs verification)
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
- The host calls opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x0) to disable the MMIO window.
+The host calls ``opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x0)`` to disable the MMIO window.
- The host calls opal_pci_set_phb_mmio_window( phb_id, mmio_window, starting_real_address, starting_pci_address, segment_size) to change the MMIO window location in PCI and/or processor real address space, or to change the size -- and corresponding window size -- of a particular MMIO window.
+The host calls ``opal_pci_set_phb_mmio_window( phb_id, mmio_window, starting_real_address, starting_pci_address, segment_size)`` to change the MMIO window location in PCI and/or processor real address space, or to change the size -- and corresponding window size -- of a particular MMIO window.
- The host calls opal_pci_map_pe_mmio_window( pe_number, mmio_window, segment_number) to map PEs to window segments, for each segment mapped to each PE.
+The host calls ``opal_pci_map_pe_mmio_window( pe_number, mmio_window, segment_number)`` to map PEs to window segments, for each segment mapped to each PE.
- The host calls opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x1) to enable the MMIO window.
+The host calls ``opal_pci_phb_mmio_enable( phb_id, window_type, window_num, 0x1)`` to enable the MMIO window.
IODA MSI Setup Sequences
------------------------
-(WARNING: this was rescued from old internal documentation. Needs verification)
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
To setup MSIs:
+1. For ibm,opal-ioda PHBs, the host chooses an MVE for a PE to use and calls ``opal_pci_set_mve( phb_id, mve_number, pe_number,)`` to setup the MVE for the PE number. HAL treats this call as a NOP and returns hal_success status for ibm,opal-ioda2 PHBs.
+2. The host chooses an XIVE to use with a PE and calls
+ a. ``opal_pci_set_xive_pe( phb_id, xive_number, pe_number)`` to authorize that PE to signal that XIVE as an interrupt. The host must call this function for each XIVE assigned to a particular PE, but may use this call for all XIVEs prior to calling ``opel_pci_set_mve()`` to bind the PE XIVEs to an MVE. For MSI conventional, the host must bind a unique MVE for each sequential set of 32 XIVEs.
+ b. The host forms the interrupt_source_number from the combination of the device tree MSI property base BUID and XIVE number, as an input to ``opal_set_xive(interrupt_source_number, server_number, priority)`` and ``opal_get_xive(interrupt_source_number, server_number, priority)`` to set or return the server and priority numbers within an XIVE.
+ c. ``opal_get_msi_64[32](phb_id, mve_number, xive_num, msi_range, msi_address, message_data)`` to determine the MSI DMA address (32 or 64 bit) and message data value for that xive.
-1. For ibm,opal-ioda PHBs, the host chooses an MVE for a PE to use and calls opal_pci_set_mve( phb_id, mve_number, pe_number,) to setup the MVE for the PE number. HAL treats this call as a NOP and returns hal_success status for ibm,opal-ioda2 PHBs.
-
-2. the host chooses an XIVE to use with a PE and calls
-
- a. opal_pci_set_xive_pe( phb_id, xive_number, pe_number) to authorize that PE to signal that XIVE as an interrupt. The host must call this function for each XIVE assigned to a particular PE, but may use this call for all XIVEs prior to calling opel_pci_set_mve() to bind the PE XIVEs to an MVE.For MSI conventional, the host must bind a unique MVE for each sequential set of 32 XIVEs.
-
- b. The host forms the interrupt_source_number from the combination of the device tree MSI property base BUID and XIVE number, as an input to opal_set_xive(interrupt_source_number, server_number, priority) and opal_get_xive(interrupt_source_number, server_number, priority) to set or return the server and priority numbers within an XIVE.
-
- c. opal_get_msi_64[32](phb_id, mve_number, xive_num, msi_range, msi_address, message_data) to determine the MSI DMA address (32 or 64 bit) and message data value for that xive.
-
- For MSI conventional, the host uses this for each sequential power of 2 set of 1 to 32 MSIs, to determine the MSI DMA address and starting message data value for that MSI range. For MSI-X, the host calls this uniquely for each MSI interrupt with an msi_range input value of 1.
-
-
-3. For ibm,opal-ioda PHBs, once the MVE and XIVRs are setup for a PE, the host calls opal_pci_set_mve_enable( phb_id, mve_number, state)to enable that MVE to be a valid target of MSI DMAs. The host may also call this function to disable an MVE when changing PE domains or states.
+ For MSI conventional, the host uses this for each sequential power of 2 set of 1 to 32 MSIs, to determine the MSI DMA address and starting message data value for that MSI range. For MSI-X, the host calls this uniquely for each MSI interrupt with an msi_range input value of 1.
+3. For ``ibm,opal-ioda`` PHBs, once the MVE and XIVRs are setup for a PE, the host calls ``opal_pci_set_mve_enable( phb_id, mve_number, state)`` to enable that MVE to be a valid target of MSI DMAs. The host may also call this function to disable an MVE when changing PE domains or states.
IODA DMA Setup Sequences
------------------------
-(WARNING: this was rescued from old internal documentation. Needs verification)
-
-
+(**WARNING**: this was rescued from old internal documentation. Needs verification)
To Manage DMA Windows :
-
-1. The host calls opal_pci_map_pe_dma_window( phb_id, dma_window_number, pe_number, tce_levels, tce_table_addr, tce_table_size, tce_page_size, utin64_t* pci_start_addr ) to setup a DMA window for a PE to translate through a TCE table structure in KVM memory.
-
-2. The host calls opal_pci_map_pe_dma_window_real( phb_id, dma_window_number, pe_number, mem_low_addr, mem_high_addr) to setup a DMA window for a PE that is translated (but validated by the PHB as an untranlsated address space authorized to this PE).
+1. The host calls ``opal_pci_map_pe_dma_window( phb_id, dma_window_number, pe_number, tce_levels, tce_table_addr, tce_table_size, tce_page_size, utin64_t* pci_start_addr )`` to setup a DMA window for a PE to translate through a TCE table structure in KVM memory.
+2. The host calls ``opal_pci_map_pe_dma_window_real( phb_id, dma_window_number, pe_number, mem_low_addr, mem_high_addr)`` to setup a DMA window for a PE that is translated (but validated by the PHB as an untranlsated address space authorized to this PE).
diff --git a/doc/stable-skiboot-rules.rst b/doc/stable-skiboot-rules.rst
index 1db47a3..bf4f5f0 100644
--- a/doc/stable-skiboot-rules.rst
+++ b/doc/stable-skiboot-rules.rst
@@ -1,5 +1,5 @@
Stable Skiboot tree/releases
-----------------------------
+============================
If you're at all familiar with the Linux kernel stable trees, this should
seem fairly familiar.
@@ -15,48 +15,64 @@ with my IBMer hat on, we'll maintain branches that we ship in products.
What patches are accepted?
--------------------------
-- Patches must be obviously correct and tested
- - A Tested-by signoff is *important*
-- A patch must fix a real bug
-- No trivial patches, such fixups belong in main branch
-- Not fix a purely theoretical problem unless you can prove how
+* Patches must be obviously correct and tested
+
+ * A Tested-by signoff is *important*
+* A patch must fix a real bug
+* No trivial patches, such fixups belong in main branch
+* Not fix a purely theoretical problem unless you can prove how
it's exploitable
-- The patch, or an equivalent one, must already be in master
- - Submitting to both at the same time is okay, but backporting is better
+* The patch, or an equivalent one, must already be in master
+
+ * Submitting to both at the same time is okay, but backporting is better
HOWTO submit to stable
----------------------
Two ways:
-1) Send patch to the skiboot@ list with "[PATCH stable]" in subject
- - This targets the patch *ONLY* to the stable branch.
- - Such commits will *NOT* be merged into master.
- - Use this when:
- a) cherry-picking a fix from master
- b) fixing something that is only broken in stable
- c) fix in stable needs to be completely different than in master
+1. Send patch to the skiboot@ list with "[PATCH stable]" in subject
+
+ * This targets the patch *ONLY* to the stable branch.
+
+ * Such commits will *NOT* be merged into master.
+ * Use this when:
+
+ a. cherry-picking a fix from master
+ b. fixing something that is only broken in stable
+ c. fix in stable needs to be completely different than in master
+
If b or c: explain why.
- - If cherry-picking, include the following at the top of your
- commit message:
- commit <sha1> upstream.
- - If the patch has been modified, explain why in description.
-
-2) Add "Cc: stable" above your Signed-off-by line when sending to skiboot@
- - This targets the patch to master and stable.
- - You can target a patch to a specific stable tree with:
- Cc: stable # 5.1.x
+ * If cherry-picking, include the following at the top of your
+ commit message: ::
+
+ commit <sha1> upstream.
+ * If the patch has been modified, explain why in description.
+
+2. Add "Cc: stable" above your Signed-off-by line when sending to skiboot@
+
+ * This targets the patch to master and stable.
+ * You can target a patch to a specific stable tree with: ::
+
+ Cc: stable # 5.1.x
+
and that will target it to the 5.1.x branch.
- - You can ask for prerequisites to be cherry-picked:
- Cc: stable # 5.1.x 55ae15b Ensure we run pollers in cpu_wait_job()
- Cc: stable # 5.1.x
+ * You can ask for prerequisites to be cherry-picked: ::
+
+ Cc: stable # 5.1.x 55ae15b Ensure we run pollers in cpu_wait_job()
+ Cc: stable # 5.1.x
+
Which means:
- 1) please git cherry-pick 55ae15b
- 2) then apply this patch to 5.1.x".
+
+ 1. please ``git cherry-pick 55ae15b``
+ 2. then apply this patch to 5.1.x".
Trees
-----
-- https://github.com/open-power/skiboot/tree/stable
- git at github.com:open-power/skiboot.git (branches are skiboot-X.Y.x - e.g. skiboot-5.1.x)
-- Some stable versions may last longer than others
- - So there may be skiboot-5.1.x and skiboot-5.2.x actively maintained
+* https://github.com/open-power/skiboot/tree/stable (or via ssh at ``git at github.com:open-power/skiboot.git`` )
+
+ * (branches are skiboot-X.Y.x - e.g. skiboot-5.1.x)
+
+* Some stable versions may last longer than others
+
+ * So there may be skiboot-5.1.x and skiboot-5.2.x actively maintained
and skiboot-5.1.x could possibly outlast skiboot-5.2.x
diff --git a/doc/versioning.rst b/doc/versioning.rst
index 2bbad69..64ccc2c 100644
--- a/doc/versioning.rst
+++ b/doc/versioning.rst
@@ -5,10 +5,11 @@ History
-------
For roughly the first six months of public life, skiboot just presented a
git SHA1 as a version "number". This was "user visible" in two places:
-1) /sys/firmware/opal/msglog
- the familiar "SkiBoot 71664fd-dirty starting..." message
-2) device tree:
- /proc/device-tree/ibm,opal/firmware/git-id
+
+1. ``/sys/firmware/opal/msglog``
+ the familiar ``SkiBoot 71664fd-dirty starting...`` message
+2. device tree:
+ ``/proc/device-tree/ibm,opal/firmware/git-id``
Builds were also referred to by date and by corresponding PowerKVM release.
Clearly, this was unlikely to be good practice going forward.
@@ -27,10 +28,11 @@ only times you need to do something is if you are a) making an upstream
skiboot release or b) building firmware to release for your platform(s).
OPAL/skiboot has several consumers, for example:
-- IBM shipping POWER8 systems with an FSP (FW810.XX and future)
-- OpenPower
-- OpenPower partners manufacturing OpenPower systems
-- developers, test and support needing to understand what code a system
+
+* IBM shipping POWER8 systems with an FSP (FW810.XX and future)
+* OpenPower
+* OpenPower partners manufacturing OpenPower systems
+* developers, test and support needing to understand what code a system
is running
and there are going to be several concurrent maintained releases in the wild,
@@ -38,38 +40,39 @@ likely build by different teams of people at different companies.
tl;dr; is you're likely going to see version numbers like this (for the
hypothetical platforms 'ketchup' and 'mustard'):
-skiboot-4.0-ketchup-0
-skiboot-4.0-ketchup-1
-skiboot-4.1-mustard-4
-skiboot-4.1-ketchup-0
+
+* ``skiboot-4.0-ketchup-0``
+* ``skiboot-4.0-ketchup-1``
+* ``skiboot-4.1-mustard-4``
+* ``skiboot-4.1-ketchup-0``
If you see *extra* things on the end of the version, then you're running
a custom build from a developer
-(e.g. 'skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40' means something to
+(e.g. ``skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40`` means something to
us - explained below).
-If you see less, for example 'skiboot-4.0', then you're running a build
+If you see less, for example ``skiboot-4.0``, then you're running a build
directly out of the main git tree. Those producing OPAL builds for users
must *not* ship like this, even if the tree is identical.
-Here are the components of the version string from master:
-
-skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40
-^ ^^^ ^ ^^^^^^^ ^-------^ ^ ^ ^^^^^^^
-| | | | | | | |
-| | | | | \ / - 'git diff|sha1sum'
-| | | | | \ /
-| | | | | - built from a dirty tree of $USER
-| | | | |
-| | | | - $EXTRA_VERSION (optional)
-| | | |
-| | | - git SHA1 of commit built
-| | |
-| | - commits head of skiboot-4.0 tag
-| |
-| - skiboot version number ---\
-| >-- from the 'skiboot-4.0' git tag
- - product name (always skiboot) ---/
+Here are the components of the version string from master: ::
+
+ skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40
+ ^ ^^^ ^ ^^^^^^^ ^-------^ ^ ^ ^^^^^^^
+ | | | | | | | |
+ | | | | | \ / - 'git diff|sha1sum'
+ | | | | | \ /
+ | | | | | - built from a dirty tree of $USER
+ | | | | |
+ | | | | - $EXTRA_VERSION (optional)
+ | | | |
+ | | | - git SHA1 of commit built
+ | | |
+ | | - commits head of skiboot-4.0 tag
+ | |
+ | - skiboot version number ---\
+ | >-- from the 'skiboot-4.0' git tag
+ - product name (always skiboot) ---/
When doing a release for a particular platform, you are expected to create
@@ -77,19 +80,19 @@ and tag a branch from master. For the (hypothetical) ketchup platform which
is going to do a release based on skiboot-4.0, you would create a tag
'skiboot-4.0-ketchup-0' pointing to the same revision as the 'skiboot-4.0' tag
and then make any additional modifications to skiboot that were not in the 4.0
-release. So, you could ship a skiboot with the following version string:
-
-skiboot-4.0-ketchup-1
-^ ^^^ ^ ^
-| | | |
-| | | - revision for this platform
-| | |
-| | |
-| | - Platform name/version
-| |
-| - skiboot version number
-|
- - product name (always skiboot)
+release. So, you could ship a skiboot with the following version string: ::
+
+ skiboot-4.0-ketchup-1
+ ^ ^^^ ^ ^
+ | | | |
+ | | | - revision for this platform
+ | | |
+ | | |
+ | | - Platform name/version
+ | |
+ | - skiboot version number
+ |
+ - product name (always skiboot)
This version string tells your users to expect what is in skiboot-4.0 plus
some revisions for your platform.
diff --git a/doc/xscom-node-bindings.rst b/doc/xscom-node-bindings.rst
index 0c2545e..0fd5e93 100644
--- a/doc/xscom-node-bindings.rst
+++ b/doc/xscom-node-bindings.rst
@@ -1,18 +1,22 @@
+XSCOM Bindings
+==============
+
XSCOM regions
-=============
+-------------
The top-level xscom nodes specify the mapping range from the 64-bit address
space into the PCB address space.
There's one mapping range per chip xscom, therefore one node per mapping range.
+::
-/
-/xscom@<chip-base-address-0>/
-/xscom@<chip-base-address-1>/
-…
-/xscom@<chip-base-address-n>/
+ /
+ /xscom@<chip-base-address-0>/
+ /xscom@<chip-base-address-1>/
+ …
+ /xscom@<chip-base-address-n>/
-- where <chip-base-address-n> is the xscom base address with the gcid-specific
+* where <chip-base-address-n> is the xscom base address with the gcid-specific
bits (for chip n) OR-ed in.
Each xscom node has the following properties:
@@ -25,17 +29,18 @@ Each xscom node has the following properties:
Chiplet endpoints
-=================
+-----------------
One sub-node per endpoint. Endpoints are defined by their (port,
endpoint-address) data on the PCB, and are named according to their endpoint
types:
+::
-/xscom@<chip-base-address>/
-/xscom@<chip-base-address>/chiptod@<endpoint-addr>
-/xscom@<chip-base-address>/lpc@<endpoint-addr>
+ /xscom@<chip-base-address>/
+ /xscom@<chip-base-address>/chiptod@<endpoint-addr>
+ /xscom@<chip-base-address>/lpc@<endpoint-addr>
-- where the <endpoint-addr> is a single address (as distinct from the current
+* where the <endpoint-addr> is a single address (as distinct from the current
(gcid,base) format), consisting of the SCOM port and SCOM endpoint bits in
their 31-bit address format.
@@ -46,12 +51,13 @@ Each endpoint node has the following properties:
The endpoint address specifies the address on the PCB. So, to calculate the
MMIO address for a PCB register:
+::
mmio_addr = <xscom-base-addr> | (pcb_addr[1:27] << 4)
| (pcb_addr[28:31] << 3)
Where:
- - xscom-base-addr is the address from the first two cells of the parent
+ * xscom-base-addr is the address from the first two cells of the parent
node's reg property
- - pcb_addr is the first cell of the endpoint's reg property
+ * pcb_addr is the first cell of the endpoint's reg property
--
2.7.4
More information about the Skiboot
mailing list