errorlog: Update documentation to reflect append changes

Signed-off-by: Samuel Mendoza-Jonas <sam.mj@au1.ibm.com>
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

1 files changed, 217 insertions, 206 deletions

diff --git a/doc/error-logging.txt b/doc/error-logging.txt
index ee21d22..3d6b2a2 100644
--- a/doc/error-logging.txt
+++ b/doc/error-logging.txt
@@ -23,23 +23,26 @@ converted to PEL format and then pushed to FSP.
 
 Step 1: To report an error, invoke opal_elog_create() with required argument.
 
-	struct opal_errorlog *opal_elog_create(int reason_code);
-
-	Each error/event that needs to be reported should do so with its
-	unique 32 bit reason code/SRC. Based on this SRC, relevant information
-	around that error/event is gathered from look-up table and updated
-	into the error log buffer.
+	struct errorlog *opal_elog_create(struct opal_err_info *e_info,
+					  uint32_t tag);
 
 	Parameters:
 
-	 int 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
+	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.
 
-	Following info is gathered from the look-up table in fsp-elog_write.c
-	and is pre-defined for a given error.
+	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
@@ -136,11 +139,11 @@ Step 1: To report an error, invoke opal_elog_create() with required argument.
 				OPAL_RC_CU_FLASH -> Flash failure
 
 
-Step 2: Multiple extended user dumps can be appened to error log
-	using the below interface.
+Step 2: Data can be appended to the user data section using the either of
+        the below two interfaces:
 
-	int opal_elog_update_user_dump(struct opal_errorlog *buf, unsigned char *data,
-                                               uint32_t tag, uint16_t size)
+	void log_append_data(struct errorlog *buf, unsigned char *data,
+			     uint16_t size)
 
 	Parameters:
 	struct opal_errorlog *buf:
@@ -149,11 +152,32 @@ Step 2: Multiple extended user dumps can be appened to error log
 
 	unsigned char *data: Pointer to the dump data
 
-	uint32_t tag: Unique value to identify the data.
-		      Ideal to have ASCII value for 4-byte string.
-
 	uint16_t size: Size of the dump data.
 
+	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.
+
+	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);
+
+	Parameters:
+	struct opal_errorlog *buf:
+		struct opal_errorlog *buf: struct opal_errorlog pointer returned
+		by opal_elog_create() call.
+
+	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.
 
@@ -166,7 +190,7 @@ in Sapphire are again pushed up to POWERNV platform by the FSP and all the error
 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, theb can do
+log the error with some amount of description around that error, they can do
 so using just the simple error logging interface
 
 log_simple_error(uint32_t reason_code, char *fmt, ...);
@@ -190,195 +214,182 @@ Note:
 
 Sample error logging:
 ===================
+
+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)
 {
-        struct opal_errorlog *buf;
-        int rc;
-        char data1[] = "This is a sample user defined data section1";
-        char data2[] = "Error logging sample. These are dummy errors. Section 2";
-        char data3[] = "Sample error Sample error Sample error Sample error \
-                                 Sample error abcdefghijklmnopqrstuvwxyz";
-        int tag;
-
-        printf("ELOG: In machine check report error index: %d\n", index);
-
-        /* To report an error, create an error log with relevant information
-	 * struct opal_errorlog *opal_elog_create(int reason_code);
-         * Call returns a pre-allocated buffer of type 'struct opal_errorlog'
-         * buffer with relevant fields updated.
-         */
-
-        buf = opal_elog_create(OPAL_RC_CHIP_MASTER);
-        if (buf == NULL) {
-                printf("ELOG: Error getting buffer.\n");
-                return;
-        }
-
-        /* In case of user wanting to add multiple sections of various dump data
-         * for better debug, data sections can be added using this interface
-         * int opal_elog_update_user_dump(struct opal_errorlog *buf, unsigned char *data,
-         *                                          uint32_t tag, uint16_t size)
-         */
-        /* tag -> unqiue ascii tag to identify a particular data dump section */
-        tag = 0x4b4b4b4b;
-        rc =  opal_elog_update_user_dump(buf, data1, tag, sizeof(data1));
-        printf("ELOG: User data updated. rc : %d \n", rc);
-
-        tag = 0x4c4c4c4c;
-        rc =  opal_elog_update_user_dump(buf, data2, tag, sizeof(data2));
-        printf("ELOG: User data updated. rc : %d \n", rc);
-
-        tag = 0x4d4d4d4d;
-        rc =  opal_elog_update_user_dump(buf, data3, tag, sizeof(data3));
-        printf("ELOG: User data updated. rc : %d \n", rc);
-
-        /* Once all info is updated, ready to be sent to FSP */
-        printf("ELOG:commit to FSP\n");
-        rc = elog_fsp_commit(buf);
-        if (rc != 0)
-                printf("ELOG: Re-try error logging\n");
+	struct errorlog *buf;
+	char data1[] = "This is a sample user defined data section1";
+	char data2[] = "Error logging sample. These are dummy errors. Section 2";
+	char data3[] = "Sample error Sample error Sample error Sample error \
+			 Sample error abcdefghijklmnopqrstuvwxyz";
+	int tag;
+
+	printf("ELOG: In machine check report error index: %d\n", index);
+
+	/* To report an error, create an error log with relevant information
+	 * opal_elog_create(). Call returns a pre-allocated buffer of type
+	 * 'struct errorlog' buffer with relevant fields updated.
+	 */
+
+	/* tag -> unqiue ascii tag to identify a particular data dump section */
+	tag = 0x4b4b4b4b;
+	buf = opal_elog_create(&e_info(OPAL_RC_ATTN), tag);
+	if (buf == NULL) {
+		printf("ELOG: Error getting buffer.\n");
+		return;
+	}
+
+	/* Append data or text with log_append_data() or log_append_msg() */
+	log_append_data(buf, data1, sizeof(data1));
+
+	/* In case of user wanting to add multiple sections of various dump data
+	 * for better debug, data sections can be added using this interface
+	 * void log_add_section(struct errorlog *buf, uint32_t tag);
+	 */
+	tag = 0x4c4c4c4c;
+	log_add_section(buf, tag);
+	log_append_data(buf, data2, sizeof(data2));
+	log_append_data(buf, data3, sizeof(data3));
+
+	/* 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:
  ===================================
- $ errl -d -x 0x53D5EA83
- |   00000000     50480030  01004000  20131126  05064700     PH.0..@. .....G.   |
- |   00000010     20131126  05064790  4B000109  00000000      .....G.K.......   |
- |   00000020     00000000  00000000  B0000003  53D5EA83     ............S...   |
- |   00000030     55480018  01004000  20000000  00000000     UH....@. .......   |
- |   00000040     00002000  01005300  50530050  01004000     .. ...S.PS.P..@.   |
- |   00000050     02000008  00000048  00000080  00000000     .......H........   |
- |   00000060     00000000  00000000  01234567  22220222     .........#Eg""."   |
- |   00000070     34560123  98768920  42423832  34303132     4V.#.v. BB824012   |
- |   00000080     20202020  20202020  20202020  20202020                        |
- |   00000090     20202020  20202020  4548004C  01004000             EH.L..@.   |
- |   000000A0     38323436  2D4C3243  30363033  37374100     8246-L2C060377A.   |
- |   000000B0     00000000  00000000  00000000  00000000     ................   |
- |   000000C0     00000000  00000000  00000000  00000000     ................   |
- |   000000D0     00000000  00000000  00000000  05064700     ..............G.   |
- |   000000E0     00000000  4D54001C  01004000  38323436     ....MT....@.8246   |
- |   000000F0     2D4C3243  30363033  37374100  00000000     -L2C060377A.....   |
- |   00000100     5544003C  01004000  4B4B4B4B  00340000     UD....@.KKKK.4..   |
- |   00000110     54686973  20697320  61207361  6D706C65     This is a sample   |
- |   00000120     20757365  72206465  66696E65  64206461      user defined da   |
- |   00000130     74612073  65637469  6F6E3100  55440048     ta section1.UD.H   |
- |   00000140     01004000  4C4C4C4C  00400000  4572726F     ..@.LLLL.@..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  55440071  01004000  4D4D4D4D     n 2.UD.q..@.MMMM   |
- |   00000190     00690000  53616D70  6C652065  72726F72     .i..Sample error   |
- |   000001A0     2053616D  706C6520  6572726F  72205361      Sample error Sa   |
- |   000001B0     6D706C65  20657272  6F722053  616D706C     mple error Sampl   |
- |   000001C0     65206572  726F7220  09090909  2053616D     e error .... Sam   |
- |   000001D0     706C6520  6572726F  72206162  63646566     ple error abcdef   |
- |   000001E0     6768696A  6B6C6D6E  6F707172  73747576     ghijklmnopqrstuv   |
- |   000001F0     7778797A  00                               wxyz.              |
- |------------------------------------------------------------------------------|
- |                       Platform Event Log - 0x53D5EA83                        |
- |------------------------------------------------------------------------------|
- |                                Private Header                                |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Created by               : 4000                                              |
- | Created at               : 11/26/2013 05:06:47                               |
- | Committed at             : 11/26/2013 05:06:47                               |
- | Creator Subsystem        : Unknown - 0x0000004B                              |
- | CSSVER                   :                                                   |
- | Platform Log Id          : 0xB0000003                                        |
- | Entry Id                 : 0x53D5EA83                                        |
- | Total Log Size           : 644                                               |
- |------------------------------------------------------------------------------|
- |                                 User Header                                  |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Log Committed by         : 4000                                              |
- | Subsystem                : Memory Subsystem                                  |
- | Event Scope              : Unknown - 0x00000000                              |
- | Event Severity           : Informational Event                               |
- | Event Type               : Not Applicable                                    |
- | Return Code              : 0x00000000                                        |
- | Action Flags             : Report to Operating System                        |
- | Action Status            : Sent to Hypervisor                                |
- |------------------------------------------------------------------------------|
- |                        Primary System Reference Code                         |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Created by               : 4000                                              |
- | 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           : BB824012                                          |
- | Hex Words 2 - 5          : 00000080 00000000 00000000 00000000               |
- | Hex Words 6 - 9          : 01234567 22220222 34560123 98768920               |
- |                                                                              |
- |------------------------------------------------------------------------------|
- |                             Extended User Header                             |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Created by               : 4000                                              |
- | Reporting Machine Type   : 8246-L2C                                          |
- | Reporting Serial Number  : 060377A                                           |
- | FW Released Ver          :                                                   |
- | FW SubSys Version        :                                                   |
- | Common Ref Time          : 00/00/0000 05:06:47                               |
- | Symptom Id Len           : 0                                                 |
- | Symptom Id               :                                                   |
- |------------------------------------------------------------------------------|
- |                      Machine Type/Model & Serial Number                      |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Created by               : 4000                                              |
- | Machine Type Model       : 8246-L2C                                          |
- | Serial Number            : 060377A                                           |
- |------------------------------------------------------------------------------|
- |                              User Defined Data                               |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Created by               : 4000                                              |
- |                                                                              |
- |   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               : 4000                                              |
- |                                                                              |
- |   00000000     4C4C4C4C  00400000  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.   |
- |                                                                              |
- |------------------------------------------------------------------------------|
- |                              User Defined Data                               |
- |------------------------------------------------------------------------------|
- | Section Version          : 1                                                 |
- | Sub-section type         : 0                                                 |
- | Created by               : 4000                                              |
- |                                                                              |
- |   00000000     4D4D4D4D  00690000  53616D70  6C652065     MMMM.i..Sample e   |
- |   00000010     72726F72  2053616D  706C6520  6572726F     rror Sample erro   |
- |   00000020     72205361  6D706C65  20657272  6F722053     r Sample error S   |
- |   00000030     616D706C  65206572  726F7220  09090909     ample error ....   |
- |   00000040     2053616D  706C6520  6572726F  72206162      Sample error ab   |
- |   00000050     63646566  6768696A  6B6C6D6E  6F707172     cdefghijklmnopqr   |
- |   00000060     73747576  7778797A  00                     stuvwxyz.          |
- |                                                                              |
- |------------------------------------------------------------------------------|
+ $ 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.    |
+|                                                                              |
+|------------------------------------------------------------------------------|