Maxim Polyakov has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/71757 )
Change subject: Documentation: Update information about intelp2m ......................................................................
Documentation: Update information about intelp2m
Change-Id: I80d5fb5d46b50193e8fecc647d9052a2e29af93f Signed-off-by: Maxim Polyakov m.polyakov@yadro.com --- M Documentation/util.md D Documentation/util/intelp2m/gopackages.png M Documentation/util/intelp2m/index.md M util/README.md 4 files changed, 163 insertions(+), 140 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/57/71757/1
diff --git a/Documentation/util.md b/Documentation/util.md index 9823a14..3d9cbc5 100644 --- a/Documentation/util.md +++ b/Documentation/util.md @@ -70,8 +70,8 @@ `C` * __intelmetool__ - Dump interesting things about Management Engine even if hidden `C` -* __intelp2m__ - convert the configuration DW0/1 registers value from -an inteltool dump to coreboot macros. `go` +* __intelp2m__ - Generate a GPIO configuration based on a register dump +obtained using inteltool. `Go` * __inteltool__ - Provides information about the Intel CPU/chipset hardware configuration (register contents, MSRs, etc). `C` * __intelvbttool__ - Parse VBT from VGA BIOS `C` diff --git a/Documentation/util/intelp2m/gopackages.png b/Documentation/util/intelp2m/gopackages.png deleted file mode 100644 index fb81a1c..0000000 --- a/Documentation/util/intelp2m/gopackages.png +++ /dev/null Binary files differ diff --git a/Documentation/util/intelp2m/index.md b/Documentation/util/intelp2m/index.md index 6873c1b..d1dc191 100644 --- a/Documentation/util/intelp2m/index.md +++ b/Documentation/util/intelp2m/index.md @@ -1,210 +1,223 @@ Intel Pad to Macro (intelp2m) converter =======================================
-This utility allows one to convert the configuration DW0/1 register -values from an inteltool dump to coreboot macros. +This utility is used to generate a GPIO configuration based on a +register dump obtained using [inteltool](util.md). Depending on the +settings, you can create several configuration formats [for coreboot](getting_started/gpio.md) +or [Intel FSP](soc/intel/fsp/index.md). The result is output/gpio.h +with pad configuration for your motherboard. + +## Build + +Since the utility is written in Go, you need to install the official +[go-compiler and go-tools](https://go.dev/dl/) to build the executive +image.
```bash cd util/intelp2m make -./intelp2m -h -./intelp2m -file /path/to/inteltool.log +./intelp2m -version ```
-### Platforms - -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 -``` - -For example, using template type 1, you can parse gpio.h from an -existing board in the coreboot project. +Set automatic argument completion:
```bash -./intelp2m -t 1 -file coreboot/src/mainboard/yourboard/gpio.h +complete -C `pwd`/intelp2m ./intelp2m ```
-You can also add a template to 'parser/template.go' for your file type -with the configuration of the pads. +## Unit testing
-platform type is set using the -p option (Sunrise by default): +Run testing of the changes you have made
-```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 +make test ```
+If successful, all tests contain the PASS prefix. + +## Platforms + +Set the platform and file + ```bash ./intelp2m -p <platform> -file path/to/inteltool.log ```
-### Packages +Supports several modern PCH families from Intel:
-![][pckgs] +* Alder Lake PCH +* Apollo Lake SoC +* CannonLake-LP / Whiskeylake / Coffeelake / Cometlake-U SoC +* Lewisburg PCH +* Sunrise Point PCH
-[pckgs]: gopackages.png - -### Bit fields in macros - -Use the `-fld=cb` option to only generate a sequence of bit fields in -a new macro: +Show more details:
```bash -./intelp2m -fld cb -p apl -file ../apollo-inteltool.log +./intelp2m -platform ? ```
+## Auto-check macro + +If not all bit fields in the configuration registers have been used for +conversion, then the utility generates a long macro of fields +_PAD_CFG_STRUCT(): + ```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_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), ```
-### Raw DW0, DW1 register value +There are several ways to disable this check:
-To generate the gpio.c with raw PAD_CFG_DW0 and PAD_CFG_DW1 register -values you need to use the -fld=raw option: +* add the required bits to the platform mask; +* use the -unchecked option:
```bash -./intelp2m -fld raw -file /path/to/inteltool.log +./intelp2m -unchecked -p apl -file path/to/inteltool.log ```
+In this case, unused bits are ignored and a short macro PAD_CFG_**() +is generated without checking: + ```c -_PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000), -``` - -```bash -./intelp2m -iiii -fld raw -file /path/to/inteltool.log -``` - -```c -/* GPP_A10 - CLKOUT_LPC1 */ -/* DW0: 0x44000500, DW1: 0x00000000 */ -/* DW0: 0x04000100 - IGNORED */ -/* PAD_CFG_NF(GPP_A10, NONE, DEEP, NF1), */ -_PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000), -``` - -### Macro Check - -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 -./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), ```
-### Information level +This only works for coreboot macros.
-The utility can generate additional information about the bit -fields of the DW0 and DW1 configuration registers. Using the -options -i, -ii, -iii, -iiii you can set the info level from -1 to 4: +Exclude unused bits before conversion:
```bash -./intelp2m -i -file /path/to/inteltool.log +./intelp2m -exclude -p apl -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_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), ```
-```bash -./intelp2m -ii -file /path/to/inteltool.log -./intelp2m -iii -file /path/to/inteltool.log -./intelp2m -iiii -file /path/to/inteltool.log + +## Internal packages + +```text ++-------------------------------------------------------------------+ +| main | ++-------------------------------------------------------------------+ + | | | + V V V ++------------+ +--------------+ +-------------+ +-------------+ +| template |<--| parser | | generator | | printer | ++------------+ +--------------+ +-------------+ +-------------+ + | + V ++-------------------------------------------------------------------+ +| platforms | ++-------------------------------------------------------------------+ + | | | | | | + V V V V V V ++-------+ +-------+ +-------+ +-------+ +-------+ +-------+ +| adl | | apl | | cnl | | lbg | | snr | * * * | other | ++-------+ +-------+ +-------+ +-------+ +-------+ +-------+ + | | | | | | + V V V V V V ++-------------------------------------------------------------------+ +| common | ++-------------------------------------------------------------------+ + | + V ++-------------------------------------------------------------------+ +| fields | ++-------------------------------------------------------------------+ + | | | + V V V ++-------------------+ +-------------------+ +-------------------+ +| cb | | raw | | fsp | ++-------------------+ +-------------------+ +-------------------+ ```
+## Format + +Depending on the options -i, -ii, -iii, -iiiii (information level), +the utility can generate the configuration in different formats: + +```bash +./intelp2m [-i, -ii, -iii, -iiii] -p apl -file path/to/inteltool.log +``` + +* i adding a function name: + +```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 */ +``` + +* ii adds configuration register values: + ```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)), +/* DW0: 0x44000400, DW1: 0x00003100 */ +_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: +* iii adds information about ignored fields: + ```c -/* 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), +/* GPIO_39 - LPSS_UART0_TXD */ +/* DW0: 0x44000400, DW1: 0x00003100 */ +/* DW0 : PAD_TRIG(OFF) - IGNORED */ +_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), ```
-### Ignoring Fields - -Utilities can generate the _PAD_CFG_STRUCT macro and exclude fields -from it that are not in the corresponding PAD_CFG_*() macro: - -```bash -./intelp2m -iiii -fld cb -ign -file /path/to/inteltool.log -``` +* iiii add a macro that is obtained after ignoring some bits that +interfere with the conversion:
```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_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), ```
-### FSP-style macro - -The utility allows one to generate macros that include fsp/edk2-platform -style bitfields: - -```bash -./intelp2m -i -fld fsp -p lbg -file ../crb-inteltool.log -``` +The same without automatic check:
```c -{ GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut, - GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone, - GpioPadConfigLock }, /* GPIO */ +/* GPIO_39 - LPSS_UART0_TXD */ +/* DW0: 0x44000400, DW1: 0x00003100 */ +/* DW0: PAD_TRIG(OFF) - IGNORED */ +/* _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 generates an original macro in the comments. + +## Long macros with fields collection + +Depending on the value of the option -fields, the utility can generate +long macros with different styles of the field collection: + ```bash -./intelp2m -iiii -fld fsp -p lbg -file ../crb-inteltool.log +./intelp2m -fields [fsp, cb, raw] -p apl -file ../apollo-inteltool.log ```
+* fsp + ```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 }, ```
-### Supported Chipsets +* cb
- Sunrise PCH, Lewisburg PCH, Apollo Lake SoC, CannonLake-LP SoCs +```c +_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), +``` + +* raw + +```c +_PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000), +``` + +Show more details: + +```bash +./intelp2m -fields ? +``` diff --git a/util/README.md b/util/README.md index 8946bf2..02ad365 100644 --- a/util/README.md +++ b/util/README.md @@ -59,8 +59,8 @@ `C` * __intelmetool__ - Dump interesting things about Management Engine even if hidden `C` -* __intelp2m__ - convert the configuration DW0/1 registers value from -an inteltool dump to coreboot macros. `go` +* __intelp2m__ - Generate a GPIO configuration based on a register dump +obtained using inteltool. `Go` * __inteltool__ - Provides information about the Intel CPU/chipset hardware configuration (register contents, MSRs, etc). `C` * __intelvbttool__ - Parse VBT from VGA BIOS `C`
-
Maxim Polyakov (Code Review)