fix markdownlint issues reported in CI
There are a lot of warnings reported by markdownlint in the CI, this
commit aims at fixing all of them.
Tested :
No more warnings reported by markdownlint in the CI.
Change-Id: I92d24bc0efd230dd0974ff49853ef928caf1febd
Signed-off-by: Manojkiran Eda <manojkiran.eda@gmail.com>
diff --git a/README.md b/README.md
index c7ddc7f..33ede85 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,54 @@
-# To Build
+# PLDM - Platform Level Data Model
-Need `meson` and `ninja`. Alternatively, source an OpenBMC ARM/x86 SDK.
+[](LICENSE)
-```
+## Overview
+
+PLDM (Platform Level Data Model) is a key component of the OpenBMC project,
+providing a standardized data model and message formats for various platform
+management functionalities. It defines a method to manage, monitor, and control
+the firmware and hardware of a system.
+
+The OpenBMC PLDM project aims to implement the specifications defined by the
+Distributed Management Task Force (DMTF), allowing for interoperable management
+interfaces across different hardware and firmware components.
+
+## Features
+
+- **Standardized Messaging:** Adheres to the DMTF's PLDM specifications,
+ enabling consistent and interoperable communication between different
+ components.
+- **Modularity:** Supports multiple PLDM types, including base, FRU,Firmware
+ update, Platform Monitoring and Control, and BIOS Control and Configuration.
+- **Extensibility:** Easily extendable to support new PLDM types and custom OEM
+ commands.
+- **Integration:** Seamlessly integrates with other OpenBMC components for
+ comprehensive system management.
+
+## Getting Started
+
+### Prerequisites
+
+To build and run PLDM, you need the following dependencies:
+
+- `Meson`
+- `Ninja`
+
+Alternatively, source an OpenBMC ARM/x86 SDK.
+
+### Building
+
+To build the PLDM project, follow these steps:
+
+```bash
meson setup build && ninja -C build
```
-## To run unit tests
+### To run unit tests
The simplest way of running the tests is as described by the meson man page:
-```
+```bash
meson setup builddir && meson setup test -C builddir
```
@@ -18,30 +56,30 @@
[these](https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md)
steps.
-## To enable pldm verbosity
+### To enable pldm verbosity
pldm daemon accepts a command line argument `--verbose` or `--v` or `-v` to
enable the daemon to run in verbose mode. It can be done via adding this option
to the environment file that pldm service consumes.
-```
+```bash
echo 'PLDMD_ARGS="--verbose"' > /etc/default/pldmd
systemctl restart pldmd
```
-## To disable pldm verbosity
+### To disable pldm verbosity
-```
+```bash
rm /etc/default/pldmd
systemctl restart pldmd
```
-# Code Organization
+### Code Organization
At a high-level, code in this repository belongs to one of the following three
components.
-## libpldmresponder
+#### libpldmresponder
This library provides handlers for incoming PLDM request messages. It provides
for a registration as well as a plug-in mechanism. The library is implemented in
@@ -49,19 +87,19 @@
The handlers are of the form
-```
+```c
Response handler(Request payload, size_t payloadLen)
```
Source files are named according to the PLDM Type, for eg base.[hpp/cpp],
fru.[hpp/cpp], etc.
-## OEM/vendor-specific functions
+#### OEM/vendor-specific functions
This will support OEM or vendor-specific functions and semantic information.
Following directory structure has to be used:
-```
+```txt
pldm repo
|---- oem
|----<oem_name>
@@ -88,21 +126,21 @@
incorporate the logic of adding its mapped compiler flag to allow conditional
compilation of the code.
-## libpldm
+##### libpldm
pldm daemon links against the libpldm library during compilation, For more
information on libpldm please refer to
[libpldm](https://github.com/openbmc/libpldm)
-## pldmtool
+##### pldmtool
For more information on pldmtool please refer to plmdtool/README.md.
-# Flows
+##### Flows
This section documents important code flow paths.
-## BMC as PLDM responder
+###### BMC as PLDM responder
a) PLDM daemon receives PLDM request message from underlying transport (MCTP).
@@ -122,7 +160,7 @@
f) The PLDM daemon sends the response message prepared at step e) to the remote
PLDM device.
-## BMC as PLDM requester
+##### BMC as PLDM requester
a) A BMC PLDM requester app prepares a PLDM request message. There would be
several requester apps (based on functionality/PLDM remote device). Each of them
@@ -138,7 +176,7 @@
d) The requester app has to work with the response field(s). It can make use of
a decode_foo_resp() API to deserialize the response message.
-# PDR Implementation
+###### PDR Implementation
While PLDM Platform Descriptor Records (PDRs) are mostly static information,
they can vary across platforms and systems. For this reason, platform specific
diff --git a/pldmtool/README.md b/pldmtool/README.md
index afc4c58..0cbccb2 100644
--- a/pldmtool/README.md
+++ b/pldmtool/README.md
@@ -1,4 +1,4 @@
-## Overview of pldmtool
+# Overview of pldmtool
pldmtool is a client tool that acts as a PLDM requester which runs on the BMC.
pldmtool sends the request message and displays the response message also
@@ -13,8 +13,8 @@
- Communicates with pldmd daemon running on BMC.
- Enables writing functional test cases for PLDM stack.
-please refer the DMTF PLDM specifications with respect to the pldm types.
-https://www.dmtf.org/
+please refer the [DMTF PLDM specifications](https://www.dmtf.org/) with respect
+to the pldm types.
## Code organization
@@ -22,7 +22,7 @@
Example:
-```
+```txt
pldm_base_cmd.[hpp/cpp], pldm_fru_cmd.[hpp/cpp]
```
@@ -34,13 +34,13 @@
Given a PLDM command "foo" of PLDM type "base" the pldmtool should consume
following API from the libpldm.
-```
+```c
- encode_foo_req() - Send the required input parameters in the request message.
- decode_foo_resp() - Decode the response message.
```
If PLDM commands are not yet supported in the pldmtool repository user can
-directly send the request message with the help of **pldmtool raw -d <data>**
+directly send the request message with the help of **pldmtool raw -d \<data\>**
option.
## Usage
@@ -48,8 +48,8 @@
User can see the pldmtool supported PLDM types in the usage output available
with the **-h** help option as shown below:
-```
-pldmtool -h
+```bash
+$ pldmtool -h
PLDM requester tool for OpenBMC
Usage: pldmtool [OPTIONS] SUBCOMMAND
@@ -69,13 +69,14 @@
pldmtool command prompt expects a PLDM type to display the list of supported
commands that are already implemented for that particular PLDM type.
-```
-Command format: pldmtool <pldmType> -h
+```bash
+# command format
+pldmtool <pldmType> -h
```
Example:
-```
+```bash
$ pldmtool base -h
base type command
@@ -95,13 +96,14 @@
More help on the command usage can be found by specifying the PLDM type and the
command name with **-h** argument as shown below.
-```
-Command format: pldmtool <pldmType> <commandName> -h
+```bash
+# command format
+pldmtool <pldmType> <commandName> -h
```
Example:
-```
+```bash
$ pldmtool base GetPLDMTypes -h
get pldm supported types
@@ -118,7 +120,7 @@
pldmtool raw command option accepts request message in the hexadecimal bytes and
send the response message in hexadecimal bytes.
-```
+```bash
$ pldmtool raw -h
send a raw request and print response
Usage: pldmtool raw [OPTIONS]
@@ -132,7 +134,7 @@
**pldmtool request message format:**
-```
+```bash
pldmtool raw --data 0x80 <pldmType> <cmdType> <payloadReq>
payloadReq - stream of bytes constructed based on the request message format
@@ -141,7 +143,7 @@
**pldmtool response message format:**
-```
+```txt
<instanceId> <hdrVersion> <pldmType> <cmdType> <completionCode> <payloadResp>
payloadResp - stream of bytes displayed based on the response message format
@@ -150,7 +152,7 @@
Example:
-```
+```bash
$ pldmtool raw -d 0x80 0x00 0x04 0x00 0x00
Request Message:
@@ -167,7 +169,7 @@
Example:
-```
+```bash
$ pldmtool base GetPLDMTypes
[
{
@@ -197,7 +199,7 @@
When the pldmtool receives the wrong response for the request sent it errors out
with a response code and completion code. The completion code represents the
-type of error and is defined in every pldm type `pldm_<type>_completion_codes`
+type of error and is defined in every pldm type `pldm_\<type\>_completion_codes`
enum values.
Example:
@@ -206,7 +208,7 @@
[`libpldm/platform.h`](https://github.com/openbmc/libpldm/blob/a98814fc37a5d59207163cb2fa81f4162eaf69cd/include/libpldm/platform.h#L204)
file.
-```
+```bash
$ pldmtool platform getpdr -d 17
Response Message Error: rc=0 , cc=130
```
@@ -216,19 +218,22 @@
Use **-m** or **--mctp_eid** option to send pldm request message to remote mctp
end point and by default pldmtool consider mctp_eid value as **'08'**.
-```
-Command format:
-
+```bash
+# Command format:
pldmtool <pldmType> <cmdType> -m <mctpId>
+
+# pldmtool raw command format
pldmtool raw -d 0x80 <pldmType> <cmdType> <payloadReq> -m <mctpId>
```
Example:
-```
-$ pldmtool base GetPLDMTypes -m 8
+```bash
+# Get PLDM Types
+pldmtool base GetPLDMTypes -m 8
-$ pldmtool raw -d 0x80 0x00 0x04 0x00 0x00 -m 0x08
+# pldmtool raw command
+pldmtool raw -d 0x80 0x00 0x04 0x00 0x00 -m 0x08
```
@@ -240,6 +245,6 @@
Example:
-```
+```bash
pldmtool base GetPLDMTypes -v
```
diff --git a/requester/README.md b/requester/README.md
index 93d1b4d..f383006 100644
--- a/requester/README.md
+++ b/requester/README.md
@@ -1,4 +1,4 @@
-## Overview
+# Overview
PLDM requester infrastructure enables the requester code in PLDM daemon to meet
the requirements of PLDM requesters. It provides the following features:
@@ -11,7 +11,7 @@
- Request retries based on the time-out waiting for a response.
- Instance ID expiration and marking the instance ID free after expiration.
-Future enhancements:
+## Future enhancements
- A mechanism to queue multiple outstanding requests to the same responder.
- Handle ERROR_NOT_READY completion code and retry the PLDM request after 250ms
@@ -22,7 +22,7 @@
PLDM request message (PLDM header and payload) and response function handler are
passed as parameters to the registerRequest API.
-```
+```c++
int registerRequest(mctp_eid_t eid, uint8_t instanceId, uint8_t type,
uint8_t command, pldm::Request&& requestMsg,
ResponseHandler&& responseHandler)
@@ -30,7 +30,7 @@
The signature of the response function handler:
-```
+```c++
void handler(mctp_eid_t eid, const pldm_msg* response, size_t respMsgLen)
```
diff --git a/tools/fw-update/README.md b/tools/fw-update/README.md
index a320b2b..d14a49e 100644
--- a/tools/fw-update/README.md
+++ b/tools/fw-update/README.md
@@ -4,13 +4,13 @@
firmware image blobs into a PLDM firmware update package, as per the DSP0267
specification v1.1.0 - Section 7.
-# Requirements
+## Requirements
- Python 3.6+
- Python bitarray module
- For example on Ubuntu: sudo pip3 install bitarray
-# Usage
+## Usage
pldm_fwup_pkg_creator.py [-h]
pldmfwuppkgname metadatafile images
@@ -30,7 +30,7 @@
order_ as the entries in the "ComponentImageInformationArea" list in the
metadata json
-# Metadata JSON file
+## Metadata JSON file
Some fields corresponding to the PLDM firmware update package must be specified
in an input metadata file (see the section 'Mapping fields to DSP0267') that's
@@ -42,7 +42,7 @@
preparing a PLDM firmware update package that targets three devices, and there
are a total of three component images.
-# Mapping fields to DSP0267
+## Mapping fields to DSP0267
This section describes the following:
diff --git a/tools/visualize-pdr/README.md b/tools/visualize-pdr/README.md
index 0964ef6..a6e397f 100644
--- a/tools/visualize-pdr/README.md
+++ b/tools/visualize-pdr/README.md
@@ -10,7 +10,7 @@
from the BMC and can parse them to display a full view of available PDR's on
system at any given point in time.
-# Requirements
+## Requirements
- Python 3.6+
- graphviz
@@ -21,9 +21,14 @@
as the debian based systems, it can be installed using :
```bash
- RPM Distro : sudo dnf install graphviz
- Debian Distro : sudo apt install graphviz
- Mac Distro : brew install graphviz
+# RPM based distro
+sudo dnf install graphviz
+
+# Debian based distro
+sudo apt install graphviz
+
+# mac distro
+brew install graphviz
```
- The `requirements.txt` file should list all Python libraries that the tool
@@ -35,10 +40,10 @@
pip3 install -r requirements.txt --user
```
-# Usage
+## Usage
-```ascii
-usage: pldm_visualise_pdrs.py [-h] --bmc BMC --user USER --password PASSWORD [--port PORT]
+```bash
+$ pldm_visualise_pdrs.py [-h] --bmc BMC --user USER --password PASSWORD [--port PORT]
optional arguments:
-h, --help show this help message and exit