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` `C`
* __intelmetool__ - Dump interesting things about Management Engine * __intelmetool__ - Dump interesting things about Management Engine
even if hidden `C` even if hidden `C`
* __intelp2m__ - convert the configuration DW0/1 registers value from * __intelp2m__ - Convert the inteltool register dump to gpio.h with GPIO
an inteltool dump to coreboot macros. `go` configuration for porting coreboot to your motherboard. `Go`
* __inteltool__ - Provides information about the Intel CPU/chipset * __inteltool__ - Provides information about the Intel CPU/chipset
hardware configuration (register contents, MSRs, etc). `C` hardware configuration (register contents, MSRs, etc). `C`
* __intelvbttool__ - Parse VBT from VGA BIOS `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 Intel Pad to Macro (intelp2m) converter
======================================= =======================================
This utility allows one to convert the configuration DW0/1 register The utility generates `output/gpio.h` with the GPIO configuration for SoC or PCH from intel.
values from an inteltool dump to coreboot macros. 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 ```bash
cd util/intelp2m cd util/intelp2m
make 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 -h
./intelp2m -file /path/to/inteltool.log
``` ```
## Platforms ## Platforms
It is possible to use templates for parsing inteltool.log files. The utility supports the following chipsets from Intel:
To specify such a pattern, use the option `-t <template number>`.
```text * `adl` - Alder Lake PCH
-t * `apl` - Apollo Lake SoC
template type number * `cnl` - CannonLake-LP or Whiskeylake/Coffeelake/Cometlake-U SoC
0 - inteltool.log (default) * `ebg` - Emmitsburg PCH with Xeon SP
1 - gpio.h * `jsl` - Jasper Lake SoC
2 - your template * `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 The `-platform` option allows you to identify one of the above platforms:
existing board in the coreboot project.
```bash ```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 Show more details:
with the configuration of the pads.
platform type is set using the -p option (Sunrise by default): ```bash
./intelp2m -platform ?
```
```text ## Auto-check macro
-p string
set up a platform The utility automatically checks the bit fields of the GPIO registers before generating the macro.
snr - Sunrise PCH with Skylake/Kaby Lake CPU If the bit is set to 1 in a register but isn't used in the "short" macro, the "long" macro is
lbg - Lewisburg PCH with Xeon SP CPU generated. This avoids data loss in the configuration.
apl - Apollo Lake SoC
cnl - CannonLake-LP or Whiskeylake/Coffeelake/Cometlake-U SoC ```c
adl - AlderLake PCH // the "short" macro:
(default "snr") 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 ```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 ## 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 Depending on the options -i, -ii, -iii, -iiiii (information level),
the utility can generate the configuration in different formats:
Use the `-fld=cb` option to only generate a sequence of bit fields in
a new macro:
```bash ```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 ```c
_PAD_CFG_STRUCT(GPIO_37, PAD_FUNC(NF1) | PAD_TRIG(OFF) | PAD_TRIG(OFF), \ _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_PULL(DN_20K)), /* LPSS_UART0_TXD */
``` ```
## Raw DW0, DW1 register value * ii adds configuration register values:
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
```
```c ```c
/* GPIO_39 - LPSS_UART0_TXD */ /* GPIO_39 - LPSS_UART0_TXD */
/* DW0: 0x44000400, DW1: 0x00003100 */ --> (ii) /* DW0: 0x44000400, DW1: 0x00003100 */
/* 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)),
/* 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: * iii adds information about ignored fields:
```c ```c
/* GPIO_39 - LPSS_UART0_TXD */ --> (i) /* GPIO_39 - LPSS_UART0_TXD */
/* DW0: 0x44000400, DW1: 0x00003100 */ --> (ii) /* DW0: 0x44000400, DW1: 0x00003100 */
/* DW0: PAD_TRIG(OFF) - IGNORED */ --> (iii) /* DW0 : PAD_TRIG(OFF) - IGNORED */
/* _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
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 * iiii adds the "short" macro corresponding to the current one (possibly after excluding unused 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
```
```c ```c
/* GPIO_39 - LPSS_UART0_TXD */ /* GPIO_39 - LPSS_UART0_TXD */
/* DW0: 0x44000400, DW1: 0x00003100 */ /* DW0: 0x44000400, DW1: 0x00003100 */
/* DW0: PAD_TRIG(OFF) - IGNORED */ /* DW0: PAD_TRIG(OFF) - IGNORED */
/* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, /* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD), */
TxLASTRxE, DISPUPD), */ _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
_PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP), \
PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
``` ```
## FSP-style macro The same without automatic check:
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
```
```c ```c
{ GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut, /* GPIO_39 - LPSS_UART0_TXD */
GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone, /* DW0: 0x44000400, DW1: 0x00003100 */
GpioPadConfigLock }, /* GPIO */ /* 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 ```bash
./intelp2m -iiii -fld fsp -p lbg -file ../crb-inteltool.log ./intelp2m -fields [fsp | cb | raw] -platform apl -file ../apollo-inteltool.log
``` ```
* fsp
```c ```c
/* GPP_A12 - GPIO */ { GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut, GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal GpioTermNone, GpioPadConfigLock },
/* 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 },
``` ```
## 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` `C`
* __intelmetool__ - Dump interesting things about Management Engine * __intelmetool__ - Dump interesting things about Management Engine
even if hidden `C` even if hidden `C`
* __intelp2m__ - convert the configuration DW0/1 registers value from * __intelp2m__ - Generate a GPIO configuration based on a register dump
an inteltool dump to coreboot macros. `go` obtained using inteltool. `Go`
* __inteltool__ - Provides information about the Intel CPU/chipset * __inteltool__ - Provides information about the Intel CPU/chipset
hardware configuration (register contents, MSRs, etc). `C` hardware configuration (register contents, MSRs, etc). `C`
* __intelvbttool__ - Parse VBT from VGA BIOS `C` * __intelvbttool__ - Parse VBT from VGA BIOS `C`