Documentation/util/intelp2m/index.md

   1 Intel Pad to Macro (intelp2m) converter
   2 =======================================
   3
   4 This utility allows one to convert the configuration DW0/1 register
   5 values from an inteltool dump to coreboot macros.
   6
   7 ```bash
   8 cd util/intelp2m
   9 make
  10 ./intelp2m -h
  11 ./intelp2m -file /path/to/inteltool.log
  12 ```
  13
  14 ### Platforms
  15
  16 It is possible to use templates for parsing inteltool.log files.
  17 To specify such a pattern, use the option `-t <template number>`.
  18
  19 ```text
  20     -t
  21     template type number
  22         0 - inteltool.log (default)
  23         1 - gpio.h
  24         2 - your template
  25 ```
  26
  27 For example, using template type 1, you can parse gpio.h from an
  28 existing board in the coreboot project.
  29
  30 ```bash
  31 ./intelp2m -t 1 -file coreboot/src/mainboard/yourboard/gpio.h
  32 ```
  33
  34 You can also add a template to 'parser/template.go' for your file type
  35 with the configuration of the pads.
  36
  37 platform type is set using the -p option (Sunrise by default):
  38
  39 ```text
  40 -p string
  41   set up a platform
  42     snr - Sunrise PCH with Skylake/Kaby Lake CPU
  43     lbg - Lewisburg PCH with Xeon SP CPU
  44     apl - Apollo Lake SoC
  45     cnl - CannonLake-LP or Whiskeylake/Coffeelake/Cometlake-U SoC
  46     adl - AlderLake PCH
  47   (default "snr")
  48 ```
  49
  50 ```bash
  51 ./intelp2m -p <platform> -file path/to/inteltool.log
  52 ```
  53
  54 ### Packages
  55
  56 ![][pckgs]
  57
  58 [pckgs]: gopackages.png
  59
  60 ### Bit fields in macros
  61
  62 Use the `-fld=cb` option to only generate a sequence of bit fields in
  63 a new macro:
  64
  65 ```bash
  66 ./intelp2m -fld cb -p apl -file ../apollo-inteltool.log
  67 ```
  68
  69 ```c
  70 _PAD_CFG_STRUCT(GPIO_37, PAD_FUNC(NF1) | PAD_TRIG(OFF) | PAD_TRIG(OFF), \
  71     PAD_PULL(DN_20K)), /* LPSS_UART0_TXD */
  72 ```
  73
  74 ### Raw DW0, DW1 register value
  75
  76 To generate the gpio.c with raw PAD_CFG_DW0 and PAD_CFG_DW1 register
  77 values you need to use the -fld=raw option:
  78
  79 ```bash
  80 ./intelp2m -fld raw -file /path/to/inteltool.log
  81 ```
  82
  83 ```c
  84 _PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000),
  85 ```
  86
  87 ```bash
  88 ./intelp2m -iiii -fld raw -file /path/to/inteltool.log
  89 ```
  90
  91 ```c
  92 /* GPP_A10 - CLKOUT_LPC1 */
  93 /* DW0: 0x44000500, DW1: 0x00000000 */
  94 /* DW0: 0x04000100 - IGNORED */
  95 /* PAD_CFG_NF(GPP_A10, NONE, DEEP, NF1), */
  96 _PAD_CFG_STRUCT(GPP_A10, 0x44000500, 0x00000000),
  97 ```
  98
  99 ### Macro Check
 100
 101 After generating the macro, the utility checks all used
 102 fields of the configuration registers. If some field has been
 103 ignored, the utility generates field macros. To not check
 104 macros, use the -n option:
 105
 106 ```bash
 107 ./intelp2m -n -file /path/to/inteltool.log
 108 ```
 109
 110 In this case, some fields of the configuration registers
 111 DW0 will be ignored.
 112
 113 ```c
 114 PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_38, UP_20K, DEEP, NF1, HIZCRx1, DISPUPD),
 115 PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, DISPUPD),
 116 ```
 117
 118 ### Information level
 119
 120 The utility can generate additional information about the bit
 121 fields of the DW0 and DW1 configuration registers. Using the
 122 options -i, -ii, -iii, -iiii you can set the info level from
 123 1 to 4:
 124
 125 ```bash
 126 ./intelp2m -i -file /path/to/inteltool.log
 127 ```
 128
 129 ```c
 130 _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF),\
 131     PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),    /* LPSS_UART0_TXD */
 132 ```
 133
 134 ```bash
 135 ./intelp2m -ii -file /path/to/inteltool.log
 136 ./intelp2m -iii -file /path/to/inteltool.log
 137 ./intelp2m -iiii -file /path/to/inteltool.log
 138 ```
 139
 140 ```c
 141 /* GPIO_39 - LPSS_UART0_TXD */
 142 /* DW0: 0x44000400, DW1: 0x00003100 */ --> (ii)
 143 /* DW0 : PAD_TRIG(OFF) - IGNORED */ --> (iii)
 144 /* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE,
 145    DISPUPD), */ --> (iiii)
 146 _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) | PAD_TRIG(OFF),
 147     PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
 148 ```
 149
 150 If the -n switch was used and macros was generated without checking:
 151 ```c
 152 /* GPIO_39 - LPSS_UART0_TXD */ --> (i)
 153 /* DW0: 0x44000400, DW1: 0x00003100 */ --> (ii)
 154 /* DW0: PAD_TRIG(OFF) - IGNORED */ --> (iii)
 155 /* _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP) |
 156   PAD_TRIG(OFF), PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)), */ --> (iiii)
 157 PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1, TxLASTRxE, \
 158     DISPUPD),
 159 ```
 160
 161 ### Ignoring Fields
 162
 163 Utilities can generate the _PAD_CFG_STRUCT macro and exclude fields
 164 from it that are not in the corresponding PAD_CFG_*() macro:
 165
 166 ```bash
 167 ./intelp2m -iiii -fld cb -ign -file /path/to/inteltool.log
 168 ```
 169
 170 ```c
 171 /* GPIO_39 - LPSS_UART0_TXD */
 172 /* DW0: 0x44000400, DW1: 0x00003100 */
 173 /* DW0: PAD_TRIG(OFF) - IGNORED */
 174 /* PAD_CFG_NF_IOSSTATE_IOSTERM(GPIO_39, UP_20K, DEEP, NF1,
 175    TxLASTRxE, DISPUPD), */
 176 _PAD_CFG_STRUCT(GPIO_39, PAD_FUNC(NF1) | PAD_RESET(DEEP), \
 177     PAD_PULL(UP_20K) | PAD_IOSTERM(DISPUPD)),
 178 ```
 179
 180 ### FSP-style macro
 181
 182 The utility allows one to generate macros that include fsp/edk2-platform
 183 style bitfields:
 184
 185 ```bash
 186 ./intelp2m -i -fld fsp -p lbg -file ../crb-inteltool.log
 187 ```
 188
 189 ```c
 190 { GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut,
 191   GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone,
 192   GpioPadConfigLock },    /* GPIO */
 193 ```
 194
 195 ```bash
 196 ./intelp2m -iiii -fld fsp -p lbg -file ../crb-inteltool.log
 197 ```
 198
 199 ```c
 200 /* GPP_A12 - GPIO */
 201 /* DW0: 0x80880102, DW1: 0x00000000 */
 202 /* PAD_CFG_GPI_SCI(GPP_A12, NONE, PLTRST, LEVEL, INVERT), */
 203 { GPIO_SKL_H_GPP_A12, { GpioPadModeGpio, GpioHostOwnAcpi, GpioDirInInvOut,
 204   GpioOutLow, GpioIntSci | GpioIntLvlEdgDis, GpioResetNormal, GpioTermNone,
 205   GpioPadConfigLock },
 206 ```
 207
 208 ### Supported Chipsets
 209
 210   Sunrise PCH, Lewisburg PCH, Apollo Lake SoC, CannonLake-LP SoCs