erebion/coreboot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Documentation: Update information about intelp2m

Browse source 
Change-Id: I80d5fb5d46b50193e8fecc647d9052a2e29af93f
Signed-off-by: Maxim Polyakov <max.senia.poliak@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/71757
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Filip Lewiński <filip.lewinski@3mdeb.com>
Reviewed-by: David Hendricks <david.hendricks@gmail.com>
This commit is contained in:
Maxim Polyakov 2023-01-09 23:48:04 +03:00 • committed by Felix Singer
commit da54bd60af
4 changed files with 187 additions and 124 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Documentation/util.md
View file

@ -70,8 +70,8 @@ into a format which can be used in coreboot's verb table `Go`
`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__ - Convert the inteltool register dump to gpio.h with GPIO
configuration for porting coreboot to your motherboard. `Go`
* __inteltool__ - Provides information about the Intel CPU/chipset
hardware configuration (register contents, MSRs, etc). `C`
* __intelvbttool__ - Parse VBT from VGA BIOS `C`

BIN
Documentation/util/intelp2m/gopackages.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 11 KiB

359
Documentation/util/intelp2m/index.md
View file

@ -1,210 +1,273 @@
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.
The utility generates `output/gpio.h` with the GPIO configuration for SoC or PCH from intel.
Use it to create coreboot port for your motherboard in the `src/mainboard/your-motherboard`
directory. Depending on the settings, you can create several configuration formats:
- [coreboot macros](../../getting_started/gpio.md);
- [Intel FSP macros](../../soc/intel/fsp/index.md).
Installing the latest version:
```bash
go install review.coreboot.org/coreboot.git/util/intelp2m@master
```
Including in the project as an external library:
```bash
go get review.coreboot.org/coreboot.git/util/intelp2m@master
```
## 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 -version
```
Set automatic argument completion:
```bash
complete -C `pwd`/intelp2m ./intelp2m
```
## Demo
```bash
./intelp2m -platform snr -file parser/testlog/inteltool_test.log
```
## Input data
The chipset register dump obtained using [inteltool](../../util.md) is used as input data.
```bash
cd util/inteltool
make
sudo ./inteltool -G > inteltool.log
```
After this step, you can generate `gpio.h`:
```bash
./intelp2m -file ../inteltool/inteltool.log
```
More details in the help:
```bash
./intelp2m -h
./intelp2m -file /path/to/inteltool.log
```
## Platforms
It is possible to use templates for parsing inteltool.log files.
To specify such a pattern, use the option `-t <template number>`.
The utility supports the following chipsets from Intel:
```text
-t
template type number
0 - inteltool.log (default)
1 - gpio.h
2 - your template
```
* `adl` - Alder Lake PCH
* `apl` - Apollo Lake SoC
* `cnl` - CannonLake-LP or Whiskeylake/Coffeelake/Cometlake-U SoC
* `ebg` - Emmitsburg PCH with Xeon SP
* `jsl` - Jasper Lake SoC
* `lbg` - Lewisburg PCH with Xeon SP
* `mtl` - MeteorLake SoC
* `snr` - Sunrise PCH or Skylake/Kaby Lake SoC
* `tgl` - TigerLake-H SoC
For example, using template type 1, you can parse gpio.h from an
existing board in the coreboot project.
The `-platform` option allows you to identify one of the above platforms:
```bash
./intelp2m -t 1 -file coreboot/src/mainboard/yourboard/gpio.h
./intelp2m -platform <platform> -file path/to/inteltool.log
```
You can also add a template to 'parser/template.go' for your file type
with the configuration of the pads.
Show more details:
platform type is set using the -p option (Sunrise by default):
```bash
./intelp2m -platform ?
```
```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")
## Auto-check macro
The utility automatically checks the bit fields of the GPIO registers before generating the macro.
If the bit is set to 1 in a register but isn't used in the "short" macro, the "long" macro is
generated. This avoids data loss in the configuration.
```c
// the "short" macro:
PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD),
// the "long" macro:
_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
// [*] PAD_TRIG(OFF) isn't used in the "short" macro.
```
The option `-u`, `-unchecked` is used to disable automatic verification.
In this case, all macros in `gpio.h` are generated in the "short" format:
```c
...
PAD_NC(GPP_F18, NONE),
PAD_CFG_NF(GPP_F19, NONE, PLTRST, NF1),
...
```
```bash
./intelp2m -p <platform> -file path/to/inteltool.log
./intelp2m -unchecked -platform apl -file path/to/inteltool.log
```
## Excluding fields from the macro
The utility can generate "long" macros without fields that aren't used in "short" ones.
The `-e`, `-exclude` option is used to exclude these fields from the generated macros in
`gpio.h`:
```bash
./intelp2m -exclude -platform apl -file path/to/inteltool.log
```
```c
_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
// [*] PAD_TRIG(OFF) field was excluded from the "long" macro.
```
## Packages
![][pckgs]
```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 V V
+--------+ +---------+ +---------+ +-----------+ +------------+
| cb | | raw | | fsp | | macro | | register |
+--------+ +---------+ +---------+ +-----------+ +------------+
```
[pckgs]: gopackages.png
## Format
## Bit fields in macros
Use the `-fld=cb` option to only generate a sequence of bit fields in
a new macro:
Depending on the options -i, -ii, -iii, -iiiii (information level),
the utility can generate the configuration in different formats:
```bash
./intelp2m -fld cb -p apl -file ../apollo-inteltool.log
./intelp2m [-i | -ii | -iii | -iiii] -platform apl -file path/to/inteltool.log
```
* i adding a function name:
```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)), /* 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:
```bash
./intelp2m -fld raw -file /path/to/inteltool.log
```
```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
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:
```bash
./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 */
```
```bash
./intelp2m -ii -file /path/to/inteltool.log
./intelp2m -iii -file /path/to/inteltool.log
./intelp2m -iiii -file /path/to/inteltool.log
```
* 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 adds the "short" macro corresponding to the current one (possibly after excluding unused fields):
```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] -platform 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 ?
```
## Unit testing
Please run the tests before creating a new commit:
```bash
make test
```
If successful, all tests contain the PASS prefix.

4
util/README.md
View file

@ -61,8 +61,8 @@ into a format which can be used in coreboot's verb table `Go`
`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`