Address markdownlint warnings
Addressed markdownlint warnings reported by
"../openbmc-build-scripts/scripts/format-code.sh --enable markdownlint"
Tested: Verified and fixed warnings using
"../openbmc-build-scripts/scripts/format-code.sh --enable markdownlint"
Change-Id: I6f8fe65373c748b907b9ca55c527800583983538
Signed-off-by: Jagpal Singh Gill <paligill@gmail.com>
diff --git a/README.md b/README.md
index c8da8d7..7885353 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@
Example:
-```
+```cpp
#include <phosphor-logging/elog-errors.hpp>
#include <phosphor-logging/elog.hpp>
#include <xyz/openbmc_project/Common/error.hpp>
@@ -103,7 +103,7 @@
Alternatively, to throw, catch, and then commit the error:
-```
+```cpp
try
{
phosphor::logging::elog<InternalFailure>();
@@ -124,7 +124,7 @@
Example:
-```
+```cpp
#include <phosphor-logging/elog-errors.hpp>
#include <phosphor-logging/elog.hpp>
#include <xyz/openbmc_project/Control/Device/error.hpp>
@@ -143,7 +143,7 @@
In the above example, the AdditionalData property would look like:
-```
+```cpp
["CALLOUT_ERRNO=5", "CALLOUT_DEVICE_PATH=some path"]
```
@@ -203,9 +203,9 @@
`xyz.openbmc_project.Logging.Entry` interface, but in a map instead of in
a vector of "KEY=VALUE" strings. Example:
-```
- std::map<std::string, std::string> additionalData;
- additionalData["KEY"] = "VALUE";
+```cpp
+ std::map<std::string, std::string> additionalData;
+ additionalData["KEY"] = "VALUE";
```
Unlike the previous APIs where errors could also act as exceptions that could be
@@ -249,8 +249,6 @@
https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Delete.interface.yaml
[xyz.openbmc_project.software.version]:
https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/Version.errors.yaml
-[elog-errors.hpp]:
- https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/elog.hpp
[openpower-occ-control]: https://github.com/openbmc/openpower-occ-control
[led-link]:
https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/leds
@@ -264,7 +262,7 @@
- Should cater for continuous integration (CI) build, bitbake image build, and
local repository build.
-#### Continuous Integration (CI) build
+### Continuous Integration (CI) build
- Make is called on the repository that is modified.
- Dependent packages are pulled based on the dependency list specified in the
@@ -284,15 +282,13 @@
#### Makefile changes
-**Reference**
+[Reference](https://github.com/openbmc/openpower-debug-collector/blob/master/Makefile.am)
-- https://github.com/openbmc/openpower-debug-collector/blob/master/Makefile.am
+##### Export error YAML to shared location
-###### Export error YAML to shared location
+##### Modify Makefile.am to export newly added error YAML to shared location
-_Modify Makefile.am to export newly added error YAML to shared location_
-
-```
+```make
yamldir = ${datadir}/phosphor-dbus-yaml/yaml
nobase_yaml_DATA = \
org/open_power/Host.errors.yaml
@@ -305,7 +301,7 @@
- Enable it for local repository build
- If "GEN_ERRORS" is enabled, build generates elog-errors.hpp header file.
-```
+```make
# Generate phosphor-logging/elog-errors.hpp
if GEN_ERRORS
ELOG_MAKO ?= elog-gen-template.mako.hpp
@@ -330,7 +326,7 @@
GEN_ERRORS so that the elog-errors.hpp is generated only during local
repository build.
-```
+```make
if GEN_ERRORS
nobase_nodist_include_HEADERS += \
phosphor-logging/elog-errors.hpp
@@ -347,18 +343,16 @@
happens during native build. It is not required to build repository during
native build.
-```
+```make
if !INSTALL_ERROR_YAML
endif
```
#### Autotools changes
-**Reference**
+[Reference](https://github.com/openbmc/openpower-debug-collector/blob/master/configure.ac)
-- https://github.com/openbmc/openpower-debug-collector/blob/master/configure.ac
-
-###### Add option(argument) to enable/disable installing error yaml file
+##### Add option(argument) to enable/disable installing error yaml file
- Install error yaml option(argument) is enabled for native recipe build and
disabled for bitbake build.
@@ -368,7 +362,7 @@
###### Add option(argument) to install error yaml files
-```
+```autoconf
AC_ARG_ENABLE([install_error_yaml],
AS_HELP_STRING([--enable-install_error_yaml],
[Enable installing error yaml file]),[], [install_error_yaml=no])
@@ -382,7 +376,7 @@
###### Add option(argument) to enable/disable generating elog-errors header file
-```
+```autoconf
AC_ARG_ENABLE([gen_errors],
AS_HELP_STRING([--enable-gen_errors], [Enable elog-errors.hpp generation ]),
[],[gen_errors=yes])
@@ -391,16 +385,13 @@
#### Recipe changes
-**Reference**
+[Reference](https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines/meta-openpower/common/recipes-phosphor/debug/openpower-debug-collector.bb)
-- https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines\
- /meta-openpower/common/recipes-phosphor/debug/openpower-debug-collector.bb
-
-###### Extend recipe for native and nativesdk
+##### Extend recipe for native and nativesdk
- Extend the recipe for native and native SDK builds
-```
+```BitBake
BBCLASSEXTEND += "native nativesdk"
```
@@ -412,13 +403,13 @@
###### Remove dependency on phosphor-logging for native build
-```
+```BitBake
DEPENDS_remove_class-native = "phosphor-logging"
```
###### Remove dependency on phosphor-logging for native SDK build
-```
+```BitBake
DEPENDS_remove_class-nativesdk = "phosphor-logging"
```
@@ -428,7 +419,7 @@
###### Add package config to enable/disable install_error_yaml feature
-```
+```BitBake
PACKAGECONFIG ??= "install_error_yaml"
PACKAGECONFIG[install_error_yaml] = " \
--enable-install_error_yaml, \
@@ -438,14 +429,14 @@
###### Enable install_error_yaml check for native build
-```
+```BitBake
PACKAGECONFIG_add_class-native = "install_error_yaml"
PACKAGECONFIG_add_class-nativesdk = "install_error_yaml"
```
###### Disable install_error_yaml during target build
-```
+```BitBake
PACKAGECONFIG_remove_class-target = "install_error_yaml"
```
@@ -456,7 +447,7 @@
- Argument is enabled by default for local repository build in the configure
script of the local repository.
-```
+```BitBake
XTRA_OECONF += "--disable-gen_errors"
```
@@ -464,9 +455,7 @@
- During local build use --prefix=/usr for the configure script.
-**Reference**
-
-- https://github.com/openbmc/openpower-debug-collector/blob/master/README.md
+[Reference](https://github.com/openbmc/openpower-debug-collector/blob/master/README.md)
## Event Log Extensions
@@ -520,59 +509,59 @@
1. Add a new flag to configure.ac to enable the extension:
-```
-AC_ARG_ENABLE([foo-extension],
- AS_HELP_STRING([--enable-foo-extension],
- [Create Foo logs]))
-AM_CONDITIONAL([ENABLE_FOO_EXTENSION],
- [test "x$enable_foo_extension" == "xyes"])
-```
+ ```autoconf
+ AC_ARG_ENABLE([foo-extension],
+ AS_HELP_STRING([--enable-foo-extension],
+ [Create Foo logs]))
+ AM_CONDITIONAL([ENABLE_FOO_EXTENSION],
+ [test "x$enable_foo_extension" == "xyes"])
+ ```
2. Add the code in `extensions/<extension>/`.
3. Create a makefile include to add the new code to phosphor-log-manager:
-```
-phosphor_log_manager_SOURCES += \
- extensions/foo/foo.cpp
-```
+ ```make
+ phosphor_log_manager_SOURCES += \
+ extensions/foo/foo.cpp
+ ```
4. In `extensions/extensions.mk`, add the makefile include:
-```
-if ENABLE_FOO_EXTENSION
-include extensions/foo/foo.mk
-endif
-```
+ ```make
+ if ENABLE_FOO_EXTENSION
+ include extensions/foo/foo.mk
+ endif
+ ```
5. In the extension code, register the functions to call and optionally disable
log capping using the provided macros:
-```
-DISABLE_LOG_ENTRY_CAPS();
+ ```cpp
+ DISABLE_LOG_ENTRY_CAPS();
-void fooStartup(internal::Manager& manager)
-{
- // Initialize
-}
+ void fooStartup(internal::Manager& manager)
+ {
+ // Initialize
+ }
-REGISTER_EXTENSION_FUNCTION(fooStartup);
+ REGISTER_EXTENSION_FUNCTION(fooStartup);
-void fooCreate(const std::string& message, uint32_t id, uint64_t timestamp,
- Entry::Level severity, const AdditionalDataArg& additionalData,
- const AssociationEndpointsArg& assocs)
-{
- // Create a different type of error log based on 'entry'.
-}
+ void fooCreate(const std::string& message, uint32_t id, uint64_t timestamp,
+ Entry::Level severity, const AdditionalDataArg& additionalData,
+ const AssociationEndpointsArg& assocs)
+ {
+ // Create a different type of error log based on 'entry'.
+ }
-REGISTER_EXTENSION_FUNCTION(fooCreate);
+ REGISTER_EXTENSION_FUNCTION(fooCreate);
-void fooRemove(uint32_t id)
-{
- // Delete the extension error log that corresponds to 'id'.
-}
+ void fooRemove(uint32_t id)
+ {
+ // Delete the extension error log that corresponds to 'id'.
+ }
-REGISTER_EXTENSION_FUNCTION(fooRemove);
-```
+ REGISTER_EXTENSION_FUNCTION(fooRemove);
+ ```
### Extension List
@@ -586,27 +575,27 @@
## Remote Logging via Rsyslog
The BMC has the ability to stream out local logs (that go to the systemd
-journal) via rsyslog (https://www.rsyslog.com/).
+journal) via rsyslog (<https://www.rsyslog.com/>).
The BMC will send everything. Any kind of filtering and appropriate storage will
have to be managed on the rsyslog server. Various examples are available on the
internet. Here are few pointers :
-https://www.rsyslog.com/storing-and-forwarding-remote-messages/
-https://www.rsyslog.com/doc/rsyslog%255Fconf%255Ffilter.html
-https://www.thegeekdiary.com/understanding-rsyslog-filter-options/
+<https://www.rsyslog.com/storing-and-forwarding-remote-messages/>
+<https://www.rsyslog.com/doc/rsyslog%255Fconf%255Ffilter.html>
+<https://www.thegeekdiary.com/understanding-rsyslog-filter-options/>
-#### Configuring rsyslog server for remote logging
+### Configuring rsyslog server for remote logging
The BMC is an rsyslog client. To stream out logs, it needs to talk to an rsyslog
server, to which there's connectivity over a network. REST API can be used to
set the remote server's IP address and port number.
The following presumes a user has logged on to the BMC (see
-https://github.com/openbmc/docs/blob/master/rest-api.md).
+<https://github.com/openbmc/docs/blob/master/rest-api.md>).
Set the IP:
-```
+```sh
curl -b cjar -k -H "Content-Type: application/json" -X PUT \
-d '{"data": <IP address>}' \
https://<BMC IP address>/xyz/openbmc_project/logging/config/remote/attr/Address
@@ -614,7 +603,7 @@
Set the port:
-```
+```sh
curl -b cjar -k -H "Content-Type: application/json" -X PUT \
-d '{"data": <port number>}' \
https://<BMC IP address>/xyz/openbmc_project/logging/config/remote/attr/Port
@@ -622,7 +611,7 @@
#### Querying the current configuration
-```
+```sh
curl -b cjar -k \
https://<BMC IP address>/xyz/openbmc_project/logging/config/remote
```
@@ -633,7 +622,7 @@
provide a unique hostname to each managed BMC. Here's how that can be done via a
REST API :
-```
+```sh
curl -b cjar -k -H "Content-Type: application/json" -X PUT \
-d '{"data": "myHostName"}' \
https://<BMC IP address>//xyz/openbmc_project/network/config/attr/HostName
@@ -662,13 +651,13 @@
To enable this function:
-```
+```sh
busctl set-property xyz.openbmc_project.Settings /xyz/openbmc_project/logging/settings xyz.openbmc_project.Logging.Settings QuiesceOnHwError b true
```
To check if an entry is blocking the boot:
-```
+```sh
obmcutil listbootblock
```
diff --git a/docs/structured-logging.md b/docs/structured-logging.md
index ea70463..4c7b992 100644
--- a/docs/structured-logging.md
+++ b/docs/structured-logging.md
@@ -44,7 +44,7 @@
The pre-C++20 logging APIs presented by phosphor-logging are
`phosphor::logging::log`. The basic format of a log call is:
-```
+```cpp
log<level>("A message", entry("TAG0=%s", "value"), entry("TAG1=%x", 2));
```
@@ -67,7 +67,7 @@
The post-C++20 logging APIs presented by phosphor-logging are `lg2::log`. The
basic format of a log call is:
-```
+```cpp
lg2::level("A {TAG0} occured.", "TAG0", "foo"s, "TAG1", lg2::hex, 2);
```
@@ -252,19 +252,18 @@
journal_send used. The only difference is that this is done in our library
rather than in `libsystemd`.
- Utilizing `{fmt}` for each structured data element would impose much greater
- overheads. Either we insert the `{fmt}` calls at the call-site (N calls
- plus N string objects for N structured data elements), or we do them in the
- library side where we lose the compile-time format checking. Also, the
- performance of the more robust formatting would almost certainly be worse,
- especially if we do the formatting library-side.
+Utilizing `{fmt}` for each structured data element would impose much greater
+overheads. Either we insert the `{fmt}` calls at the call-site (N calls plus N
+string objects for N structured data elements), or we do them in the library
+side where we lose the compile-time format checking. Also, the performance of
+the more robust formatting would almost certainly be worse, especially if we do
+the formatting library-side.
- Logging is done often. Shifting a few values onto the stack for a
- printf-type call compared to a kilobyte+ of generated code for inline
- `{fmt}` calls is a significant trade-off. And one with the only major
- advantage being more universally standardized API. The `lg2` API seems
- obvious enough in ergonomics such that this should not be an impediment to
- our community of developers.
+Logging is done often. Shifting a few values onto the stack for a printf-type
+call compared to a kilobyte+ of generated code for inline `{fmt}` calls is a
+significant trade-off. And one with the only major advantage being more
+universally standardized API. The `lg2` API seems obvious enough in ergonomics
+such that this should not be an impediment to our community of developers.
If it is later decided that we need more robust formatting or the `lg2::format`
flags were a bad idea they could be deprecated and replaced. The format flags
diff --git a/extensions/openpower-pels/README.md b/extensions/openpower-pels/README.md
index 4df81ba..b52da68 100644
--- a/extensions/openpower-pels/README.md
+++ b/extensions/openpower-pels/README.md
@@ -28,7 +28,7 @@
This keyword is used to point to an existing PEL in a binary file that should be
associated with this event log. The syntax is:
-```
+```ascii
RAWPEL=<path to PEL File>
e.g.
RAWPEL="/tmp/pels/pel.5"
@@ -41,7 +41,7 @@
This keyword is used to set the power fault bit in PEL. The syntax is:
-```
+```ascii
POWER_THERMAL_CRITICAL_FAULT=<FLAG>
e.g.
POWER_THERMAL_CRITICAL_FAULT=TRUE
@@ -57,7 +57,7 @@
The syntax is:
-```
+```ascii
SEVERITY_DETAIL=<SEVERITY_TYPE>
e.g.
SEVERITY_DETAIL=SYSTEM_TERM
@@ -75,7 +75,7 @@
The syntax is:
-```
+```ascii
ESEL=
"00 00 df 00 00 00 00 20 00 04 12 01 6f aa 00 00 50 48 00 30 01 00 33 00 00..."
```
@@ -94,7 +94,7 @@
The syntax is:
-```
+```ascii
_PID=<PID of application>
e.g.
_PID="12345"
@@ -131,7 +131,7 @@
#### PEL_SUBSYSTEM
This keyword is used to pass in the subsystem that should be associated with
-this event log. The syntax is: PEL_SUBSYSTEM=<subsystem value in hex> e.g.
+this event log. The syntax is: `PEL_SUBSYSTEM=<subsystem value in hex>` e.g.
PEL_SUBSYSTEM=0x20
### FFDC Intended For UserData PEL sections
@@ -143,7 +143,7 @@
That API is the same as the 'Create' one, except it has a new parameter:
-```
+```cpp
std::vector<std::tuple<enum[FFDCFormat],
uint8_t,
uint8_t,
@@ -175,7 +175,7 @@
An example of saving JSON data to a file and getting its file descriptor is:
-```
+```cpp
nlohmann::json json = ...;
auto jsonString = json.dump();
FILE* fp = fopen(filename, "w");
@@ -252,10 +252,10 @@
high priority callout is specified for this error in the message registry and
the FRU callout needs to have a different priority.
- ```
+```ascii
CALLOUT_INVENTORY_PATH=
"/xyz/openbmc_project/inventory/system/chassis/motherboard"
- ```
+```
- CALLOUT_DEVICE_PATH with CALLOUT_ERRNO
@@ -266,10 +266,10 @@
I2C, FSI, FSI-I2C, and FSI-SPI paths are supported.
- ```
+```ascii
CALLOUT_DEVICE_PATH="/sys/bus/i2c/devices/3-0069"
CALLOUT_ERRNO="2"
- ```
+```
- CALLOUT_IIC_BUS with CALLOUT_IIC_ADDR and CALLOUT_ERRNO
@@ -281,11 +281,11 @@
the bus number by itself. CALLOUT_IIC_ADDR is the 7 bit address either as a
decimal or a hex number if preceded with a "0x".
- ```
+```ascii
CALLOUT_IIC_BUS="/dev/i2c-7"
CALLOUT_IIC_ADDR="81"
CALLOUT_ERRNO=62
- ```
+```
### Defining callouts in the message registry
@@ -319,7 +319,7 @@
To specify that an FFDC file contains callouts, the format value for that FFDC
entry must be set to JSON, and the subtype field must be set to 0xCA:
-```
+```cpp
using FFDC = std::tuple<CreateIface::FFDCFormat,
uint8_t,
uint8_t,
@@ -336,7 +336,7 @@
to lowest, with a maximum of 10. Any callouts after the 10th will just be thrown
away as there is no room for them in the PEL. The format looks like:
-```
+```jsonl
[
{
// First callout
@@ -378,7 +378,7 @@
When the inventory path of a sub-FRU is passed in, the PEL code will put the
location code of the parent FRU into the callout.
-```
+```jsonl
{
"LocationCode": "P0-C1",
"Priority": "H"
@@ -402,20 +402,20 @@
Note that since JSON only supports numbers in decimal and not in hex, MRU IDs
will show up as decimal when visually inspecting the JSON.
-```
+```jsonl
{
- "LocationCode": "P0-C1",
- "Priority": "H",
- "MRUs": [
- {
- "ID": 1234,
- "Priority": "H"
- },
- {
- "ID": 5678,
- "Priority": "H"
- }
- ]
+ "LocationCode": "P0-C1",
+ "Priority": "H",
+ "MRUs": [
+ {
+ "ID": 1234,
+ "Priority": "H"
+ },
+ {
+ "ID": 5678,
+ "Priority": "H"
+ }
+ ]
}
```
@@ -424,10 +424,10 @@
The LocationCode field is not used with procedure callouts. Only the first 7
characters of the Procedure field will be used by the PEL.
-```
+```jsonl
{
- "Procedure": "PRONAME",
- "Priority": "H"
+ "Procedure": "PRONAME",
+ "Priority": "H"
}
```
@@ -441,12 +441,12 @@
field is required. If TrustedLocationCode is false or missing, then the
LocationCode field is optional.
-```
+```jsonl
{
- "TrustedLocationCode": true,
- "Location Code": "P0-C1",
- "Priority": "H",
- "SymbolicFRU": "FRUNAME"
+ "TrustedLocationCode": true,
+ "Location Code": "P0-C1",
+ "Priority": "H",
+ "SymbolicFRU": "FRUNAME"
}
```
@@ -524,8 +524,10 @@
PELs with associated guard records will never be deleted. Each step above makes
the following 4 passes, stopping as soon as its limit is reached:
-Pass 1. Remove HMC acknowledged PELs.<br> Pass 2. Remove OS acknowledged
-PELs.<br> Pass 3. Remove PHYP acknowledged PELs.<br> Pass 4. Remove all PELs.
+- Pass 1. Remove HMC acknowledged PELs.
+- Pass 2. Remove OS acknowledged PELs.
+- Pass 3. Remove PHYP acknowledged PELs.
+- Pass 4. Remove all PELs.
After all these steps, disk capacity will be at most 90% (15% + 30% + 15% +
30%).
@@ -536,21 +538,17 @@
and to decode SRC data, setuptools is used to import python3 packages from
external repos to be included in the OpenBMC image.
-```
Sample layout for setuptools:
-setup.py
-src/usr/scom/plugins/ebmc/b0300.py
-src/usr/i2c/plugins/ebmc/b0700.py
+setup.py src/usr/scom/plugins/ebmc/b0300.py src/usr/i2c/plugins/ebmc/b0700.py
src/build/tools/ebmc/errludP_Helpers.py
-```
`setup.py` is the build script for setuptools. It contains information about the
package (such as the name and version) as well as which code files to include.
The setup.py template to be used for eBMC User Data parsers:
-```
+```python3
import os.path
from setuptools import setup
@@ -602,7 +600,8 @@
1. (str) JSON string
- Sample User Data parser module:
- ```
+
+```python3
import json
def parseUDToJson(subType, ver, data):
d = dict()
@@ -611,7 +610,7 @@
...
jsonStr = json.dumps(d)
return jsonStr
- ```
+```
- SRC parser module
@@ -634,7 +633,8 @@
1. (str) JSON string
- Sample SRC parser module:
- ```
+
+ ```python3
import json
def parseSRCToJson(ascii_str, word2, word3, word4, word5, word6, word7, \
word8, word9):
@@ -676,7 +676,7 @@
To specify that an FFDC file contains SBE FFDC, the format value for that FFDC
entry must be set to "custom", and the subtype field must be set to 0xCB:
-```
+```cpp
using FFDC = std::tuple<CreateIface::FFDCFormat,
uint8_t,
uint8_t,