[L] Change in coreboot[master]: Documentation: Update information about intelp2m
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` -- To view, visit https://review.coreboot.org/c/coreboot/+/71757 To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: coreboot Gerrit-Branch: master Gerrit-Change-Id: I80d5fb5d46b50193e8fecc647d9052a2e29af93f Gerrit-Change-Number: 71757 Gerrit-PatchSet: 1 Gerrit-Owner: Maxim Polyakov <max.senia.poliak@gmail.com> Gerrit-MessageType: newchange
participants (1)
-
Maxim Polyakov (Code Review)