[RFC] ACPI Code First ECR: Pin Number Space vs. GPIO Number Space

[RFC] ACPI Code First ECR: Pin Number Space vs. GPIO Number Space

[Andy Shevchenko]

In the current form of the specification there is a room for misinterpretation
the PinList argument for Pin*() descriptors and Gpio*() descriptors.

When Pin*() descriptors have been introduced the relationship between the GPIO
Number Space and Pin Number Space wasn't clarified, so update the specification
to address this.

# Title: Clarify the Number Space for the Pin*() and Gpio*() descriptors

# Status: Draft

# Document: ACPI Specification 6.5

# License
SPDX-License Identifier: CC-BY-4.0

# Submitter:
* Sponsor: Rafael J. Wysocki, Intel
* Creator/Contributor: Andy Shevchenko, Intel

# Summary of the Change
Clarify the Pin Number Space and GPIO Number Space and their relationship in
the affected sections to reduce a room of possible misinterpretation.

# Benefits of the Change
It will clarify what Pin Number Space and what GPIO Number Space mean.
In particular, when it's appropriate to use one or the other.

# Impact of the Change
Clear understanding by all stakeholders what numbers should be assigned in
the Pin*() and Gpio*() descriptors and how OSPMs will threat them.

# References
Microsoft GPIO Number Space for the Gpio*() descriptors which allows gaps in it.
<https://learn.microsoft.com/en-us/windows-hardware/drivers/gpio/partitioning-a-gpio-controller-into-banks-of-pins>

An example of the DSDT for the Intel Merrifield platform that has separate
GPIO and pin control IP blocks.
<https://github.com/u-boot/u-boot/blob/master/arch/x86/include/asm/arch-tangier/acpi/southcluster.asl>

# Detailed Description of the Change

* Add an additional note at the end of Description in the Sections 19.6.102,
* 19.6.103, and 19.6.104:

> Note: The PinList for the PinConfig/PinFunction/PinGroup descriptors is
> provided in the Pin Number Space. The PinList for the GpioInt/GpioIo
> descriptors is provided in the GPIO Number Space. That is, the certain pins
> may or may not have a GPIO function and the certain GPIOs may or may not be
> connected through a pin multiplexer. In other words the Pin and GPIO number
> spaces are orthogonal to each other. Nevertheless, it's highly recommended
> that the firmware writer will use 1:1 mapping between register index in the
> hardware and the number in the Pin Number Space.

* Add an additional note at the end of Description in the Sections 19.6.56, and
* 19.6.57:

> Note: The PinList for the GpioInt/GpioIo descriptors is provided in the GPIO
> Number Space. The PinList for the PinConfig/PinFunction/PinGroup descriptors
> is provided in the Pin Number Space.

* Replace {2, 3} by {7, 8} in the Pin*() descriptors in the examples in the
* Sections 19.6.102, and 19.6.103.

-- 
With Best Regards,
Andy Shevchenko