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