[M] Change in coreboot[main]: Documentation/util/intelp2m: Add info for developers

[Maxim Polyakov (Code Review)]

Maxim Polyakov has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/85791?usp=email )

Change subject: Documentation/util/intelp2m: Add info for developers
......................................................................

Documentation/util/intelp2m: Add info for developers

Change-Id: I9cc886e607c1aba92b94e06419d45d9581371065
Signed-off-by: Maxim Polyakov 
---
M Documentation/util/intelp2m/index.md
1 file changed, 102 insertions(+), 2 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/91/85791/1

diff --git a/Documentation/util/intelp2m/index.md b/Documentation/util/intelp2m/index.md
index 758f8c4..af689cb 100644
--- a/Documentation/util/intelp2m/index.md
+++ b/Documentation/util/intelp2m/index.md
@@ -28,7 +28,6 @@
 ```bash
 cd util/intelp2m
 make
-./intelp2m -version
 ```

Set automatic argument completion:
@@ -263,7 +262,108 @@
 ./intelp2m -fields ?
 ```

-## Unit testing
+## For developers
+
+### Version
+
+The version string includes several parts:
+
+```text
+{major}.{minor}-{last commit in the intelp2m directory}-{?dirty}
+```
+It depends on the changes: the `major` is incremented if a new platform is added, `minor` - if
+changes in functionality are made. Add `dirty` if the changes were not taken into account using
+git.
+
+The version is added to the generated `gpio.h` file and it is necessary to support the project.
+
+The version can also be printed in the console using the following command:
+
+```bash
+./intelp2m -version
+```
+
+### Adding support for new platforms
+
+The platform-dependent code is located in `./platforms/`. Each PCH and SoC is in a separate
+package with a name corresponding to this platform (adl, apl, snr, ...). The macro generation
+code for all platforms is in the `common` directory.
+
+The package file must contain the structure `BasePlatform struct{}` with methods for the
+`PlatformIf interface{}` from the `common` package:
+
+```Go
+type PlatformIf interface {
+	RemapResetSource(*Macro)
+	Pull(*Macro)
+	AddGpiMacro(*Macro)
+	AddGpoMacro(*Macro)
+	AddNativeFunctionMacro(*Macro)
+	AddNoConnMacro(*Macro)
+	GetRegisterDW0() *register.DW0
+	GetRegisterDW1() *register.DW1
+}
+```
+
+Some methods (for example, register access methods: `GetRegisterDW0()` and `GetRegisterDW1()`)
+are already defined in the base platform from `common`. Therefore, embedding should be used in
+the basic platform structure to avoid code duplication:
+
+```Go
+type BasePlatform struct {
+	common.BasePlatform
+}
+```
+
+Since GPIO controllers are similar across intel platforms, the macro generation code can also be
+reused. You can use any platform instead of `common.BasePlatform` from the catalog to reuse its
+methods and redefine those that differ in logic.
+
+The platform file should also contain the slice `GPPGroups[]` with templates for pad names from
+`inteltool.log`, register masks `DW0` and `DW1` (the analysis will be only for the bits in these
+masks), the base platform constructor - `InitBasePlatform()`, and `GetPlatform()` that provides
+the platform interface.
+
+```Go
+const (
+	DW0Mask = (0b1 << 27) | (0b1 << 18) | (0b00111111 << 11) | (0b00111111 << 2) | (0b1 << 1)
+	DW1Mask = 0b11111101111111111100001111111111
+)
+
+// "GPP_A", "GPP_B", "GPP_C", "GPP_D", "GPP_E", "GPP_F", "GPP_G", "GPP_H", "GPP_R", "GPP_S",
+// "GPP_T", "GPD", "HVMOS", "VGPIO5"
+var GPPGroups = []string{"GPP_", "GPD", "VGPIO"}
+
+type BasePlatform struct {
+	// based on the Cannon Lake platform
+	cnl.BasePlatform
+}
+
+func InitBasePlatform(dw0, dw0mask uint32, dw1, dw1mask uint32) BasePlatform {
+	return BasePlatform{cnl.InitBasePlatform(dw0, dw0mask, dw1, dw1mask)}
+}
+
+func GetPlatform(dw0, dw1 uint32) common.PlatformIf {
+	p := InitBasePlatform(dw0, DW0Mask, dw1, DW1Mask)
+	return &p
+}
+
+// Override BasePlatform.RemapResetSource()
+func (p *BasePlatform) RemapResetSource(m *common.Macro) {
+    // Some code is here
+}
+```
+
+- Use `GetPlatform()` and `GPPGroups[]` in the file `./platform/platform.go` to define the
+  resources for the parser.
+- Add the platform argument for the options `-p` (`-platform`) to `cli/options.go`.
+- Update the documentation in `Documentation/util/intelp2m/index.md`.
+- Add unit tests.
+
+[Here](https://review.coreboot.org/c/coreboot/+/84191) is an example of porting the Intel
+Jasper lake platform.
+
+### Unit testing

Please run the tests before creating a new commit: