From 7b9d08e8498261c0c33f3032c11752e4b75a641b Mon Sep 17 00:00:00 2001
From: Martin Roth <gaumless@gmail.com>
Date: Sun, 22 May 2022 20:11:03 -0600
Subject: [PATCH] Documentation/util/intelp2m: Improve text and update Markdown

There shouldn't be any significant changes in meaning.

- Fix formatting issues
- Reword some text

Change-Id: I4e37605ef2371e6c4affbe6cb6c67e0875e89a1f
Signed-off-by: Martin Roth <gaumless@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/64579
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <felixsinger@posteo.net>
---
 Documentation/util/intelp2m/index.md | 145 ++++++++++++++++-----------
 1 file changed, 89 insertions(+), 56 deletions(-)

diff --git a/Documentation/util/intelp2m/index.md b/Documentation/util/intelp2m/index.md
index 9064817972..6873c1b1ea 100644
--- a/Documentation/util/intelp2m/index.md
+++ b/Documentation/util/intelp2m/index.md
@@ -1,79 +1,93 @@
 Intel Pad to Macro (intelp2m) converter
 =======================================
 
-This utility allows to convert the configuration DW0/1 registers value
-from [inteltool](../inteltool/description.md) dump to coreboot macros.
+This utility allows one to convert the configuration DW0/1 register
+values from an inteltool dump to coreboot macros.
 
 ```bash
-(shell)$ make
-(shell)$ ./intelp2m -h
-(shell)$ ./intelp2m -file /path/to/inteltool.log
+cd util/intelp2m
+make
+./intelp2m -h
+./intelp2m -file /path/to/inteltool.log
 ```
 
 ### Platforms
 
-It is possible to use templates for parsing files of excellent inteltool.log.
-To specify such a pattern, use the option -t <template number>. For example,
-using template type # 1, you can parse gpio.h from an already added board in
-the coreboot project.
-```bash
-(shell)$ ./intelp2m -h
-	-t
-	template type number
-		0 - inteltool.log (default)
-		1 - gpio.h
-		2 - your template
-(shell)$ ./intelp2m -t 1 -file coreboot/src/mainboard/yourboard/gpio.h
+It is possible to use templates for parsing inteltool.log files.
+To specify such a pattern, use the option `-t <template number>`.
+
+```text
+    -t
+    template type number
+        0 - inteltool.log (default)
+        1 - gpio.h
+        2 - your template
 ```
-You can also add a template to 'parser/template.go' for your file type with
-the configuration of the pads.
+
+For example, using template type 1, you can parse gpio.h from an
+existing board in the coreboot project.
+
+```bash
+./intelp2m -t 1 -file coreboot/src/mainboard/yourboard/gpio.h
+```
+
+You can also add a template to 'parser/template.go' for your file type
+with the configuration of the pads.
 
 platform type is set using the -p option (Sunrise by default):
-```bash
-	-p string
-	set up a platform
-		snr - Sunrise PCH with Skylake/Kaby Lake CPU
-		lbg - Lewisburg PCH with Xeon SP CPU
-		apl - Apollo Lake SoC
-		cnl - CannonLake-LP or Whiskeylake/Coffeelake/Cometlake-U SoC
-		adl - AlderLake PCH
-	(default "snr")
 
-(shell)$ ./intelp2m -p <platform> -file path/to/inteltool.log
+```text
+-p string
+  set up a platform
+    snr - Sunrise PCH with Skylake/Kaby Lake CPU
+    lbg - Lewisburg PCH with Xeon SP CPU
+    apl - Apollo Lake SoC
+    cnl - CannonLake-LP or Whiskeylake/Coffeelake/Cometlake-U SoC
+    adl - AlderLake PCH
+  (default "snr")
+```
+
+```bash
+./intelp2m -p <platform> -file path/to/inteltool.log
 ```
 
 ### Packages
 
 ![][pckgs]
 
-[pckgs]: config/gopackages.png
+[pckgs]: gopackages.png
 
 ### Bit fields in macros
 
-Use the -fld=cb option to only generate a sequence of bit fields in a new macro:
+Use the `-fld=cb` option to only generate a sequence of bit fields in
+a new macro:
 
 ```bash
-(shell)$ ./intelp2m -fld cb -p apl -file ../apollo-inteltool.log
+./intelp2m -fld cb -p apl -file ../apollo-inteltool.log
 ```
+
 ```c
-_PAD_CFG_STRUCT(GPIO_37, PAD_FUNC(NF1) | PAD_TRIG(OFF) | PAD_TRIG(OFF), PAD_PULL(DN_20K)), /* LPSS_UART0_TXD */
+_PAD_CFG_STRUCT(GPIO_37, PAD_FUNC(NF1) | PAD_TRIG(OFF) | PAD_TRIG(OFF), \
+    PAD_PULL(DN_20K)), /* LPSS_UART0_TXD */
 ```
 
 ### Raw DW0, DW1 register value
 
-To generate the gpio.c with raw PAD_CFG_DW0 and PAD_CFG_DW1 register values you need
-to use the -fld=raw option:
+To generate the gpio.c with raw PAD_CFG_DW0 and PAD_CFG_DW1 register
+values you need to use the -fld=raw option:
 
 ```bash
-  (shell)$ ./intelp2m -fld raw -file /path/to/inteltool.log
+./intelp2m -fld raw -file /path/to/inteltool.log
 ```
+
 ```c
 _PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000),
 ```
 
 ```bash
-  (shell)$ ./intelp2m -iiii -fld raw -file /path/to/inteltool.log
+./intelp2m -iiii -fld raw -file /path/to/inteltool.log
 ```
+
 ```c
 /* GPP_A10 - CLKOUT_LPC1 */
 /* DW0: 0x44000500, DW1: 0x00000000 */
@@ -88,12 +102,14 @@ After generating the macro, the utility checks all used
 fields of the configuration registers. If some field has been
 ignored, the utility generates field macros. To not check
 macros, use the -n option:
+
 ```bash
-(shell)$ ./intelp2m -n -file /path/to/inteltool.log
+./intelp2m -n -file /path/to/inteltool.log
 ```
 
 In this case, some fields of the configuration registers
 DW0 will be ignored.
+
 ```c
 PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_38, UP_20K, DEEP, NF1, HIZCRx1, DISPUPD),
 PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD),
@@ -107,23 +123,28 @@ options -i, -ii, -iii, -iiii you can set the info level from
 1 to 4:
 
 ```bash
-(shell)$./intelp2m -i -file /path/to/inteltool.log
+./intelp2m -i -file /path/to/inteltool.log
 ```
+
 ```c
-_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),	/* LPSS_UART0_TXD */
+_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF),\
+    PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),    /* LPSS_UART0_TXD */
 ```
 
 ```bash
-(shell)$./intelp2m -ii -file /path/to/inteltool.log
-(shell)$./intelp2m -iii -file /path/to/inteltool.log
-(shell)$./intelp2m -iiii -file /path/to/inteltool.log
+./intelp2m -ii -file /path/to/inteltool.log
+./intelp2m -iii -file /path/to/inteltool.log
+./intelp2m -iiii -file /path/to/inteltool.log
 ```
+
 ```c
 /* GPIO_39 - LPSS_UART0_TXD */
 /* DW0: 0x44000400, DW1: 0x00003100 */ --> (ii)
 /* DW0 : PAD_TRIG(OFF) - IGNORED */ --> (iii)
-/* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD), */ --> (iiii)
-_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
+/* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE,
+   DISPUPD), */ --> (iiii)
+_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF),
+    PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
 ```
 
 If the -n switch was used and macros was generated without checking:
@@ -131,8 +152,10 @@ If the -n switch was used and macros was generated without checking:
 /* GPIO_39 - LPSS_UART0_TXD */ --> (i)
 /* DW0: 0x44000400, DW1: 0x00003100 */ --> (ii)
 /* DW0: PAD_TRIG(OFF) - IGNORED */ --> (iii)
-/* _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), */ --> (iiii)
-PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD),
+/* _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) |
+  PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), */ --> (iiii)
+PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, \
+    DISPUPD),
 ```
 
 ### Ignoring Fields
@@ -141,37 +164,47 @@ Utilities can generate the _PAD_CFG_STRUCT macro and exclude fields
 from it that are not in the corresponding PAD_CFG_*() macro:
 
 ```bash
-(shell)$ ./intelp2m -iiii -fld cb -ign -file /path/to/inteltool.log
+./intelp2m -iiii -fld cb -ign -file /path/to/inteltool.log
 ```
+
 ```c
 /* GPIO_39 - LPSS_UART0_TXD */
 /* DW0: 0x44000400, DW1: 0x00003100 */
 /* DW0: PAD_TRIG(OFF) - IGNORED */
-/* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD), */
-_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
+/* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1,
+   TxLASTRxE, DISPUPD), */
+_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP), \
+    PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
 ```
 
 ### FSP-style macro
 
-The utility allows to generate macros that include fsp/edk2-palforms style bitfields:
+The utility allows one to generate macros that include fsp/edk2-platform
+style bitfields:
 
 ```bash
-(shell)$ ./intelp2m -i -fld fsp -p lbg -file ../crb-inteltool.log
+./intelp2m -i -fld fsp -p lbg -file ../crb-inteltool.log
 ```
+
 ```c
-{ GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut, GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone,  GpioPadConfigLock },	/* GPIO */
+{ GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut,
+  GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone,
+  GpioPadConfigLock },    /* GPIO */
 ```
 
 ```bash
-(shell)$ ./intelp2m -iiii -fld fsp -p lbg -file ../crb-inteltool.log
+./intelp2m -iiii -fld fsp -p lbg -file ../crb-inteltool.log
 ```
+
 ```c
 /* GPP_A12 - GPIO */
 /* DW0: 0x80880102, DW1: 0x00000000 */
 /* PAD_CFG_GPI_SCI(GPP_A12, NONE, PLTRST, LEVEL, INVERT), */
-{ GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut, GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone,  GpioPadConfigLock },
+{ GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut,
+  GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone,
+  GpioPadConfigLock },
 ```
 
-### Supports Chipsets
+### Supported Chipsets
 
   Sunrise PCH, Lewisburg PCH, Apollo Lake SoC, CannonLake-LP SoCs