[RFC] RTEMS GPIO pin references

[André Marques]

Hello,

(sorry for the long email)

I am currently doing an implementation for a generic RTEMS API, and I 
would like to inquire potential users about pin references provided by 
the API to user applications.

Most platforms use a "global" pin number to refer to a GPIO pin in 
documentation, usually in the form of "GPIO_<number>", but in practice 
the pins are organized in banks of pins, meaning that a GPIO driver or 
API has to map those pin numbers to a bank-pin pair to correctly refer 
to a pin.

Because it can be expensive to query the hardware for the current GPIO 
status, and because some information may not be even possible to read 
back (e.g.: the raspberry does not store any information on its 
registers about the pull-resistors state), it makes sense that an GPIO 
API stores/manages the GPIO state during execution.

This state is recorded on a struct per pin, and includes information 
such as:

- pin current function;
- interrupt information (i.e.: if interrupts are enabled on the pin, and 
if so which kind of interrupt; interrupt handler (or handlers in case of 
a shared IRQ line));
- pull-resistor state;
- Gpio utilities (software switch debouncing data; applicational logic 
invertion; ...);
- any relevant platform specific data.

An array/matrix of these structures is used, but the issue now is how to 
deal with the bank-pin pairs. The reason behind this RFC is to evaluate 
how this pair of information should be used/processed. Storing this 
information in the above list (which applies to every pin in the 
system), knowing that for each bank the bank number is the same (if the 
bank has 32 pins, all 32 pins from that bank would waste 32bits of 
memory each to store the same information), and the bank-pin pair has to 
be previously known by the API to retrieve the pin data in the first 
place, is a waste of memory.

However, the API must still have a way of knowing the bank-pin pair, 
which can be directly received (the application uses that information 
directly to refer to a pin), or calculated from the said "global" pin 
reference through a couple of division operations. The problem with the 
pin calculations, or dynamic pin mapping, is that it has to be done 
every time the API is called, but the applications may want to use the 
same pin referencing used by documentation/diagrams, as the BSP can 
provide constants such as GPIO_40 or ACTIVITY_LED.

If they are to use the bank-pin pair directly, it would be trickier for 
the application developer/user to know which combination to use, or 
where to attach wires, so the pin mappings would have to be made 
available through some sort of documentation by each BSP.
In this case the applications would use an hardcoded reference to the 
pin, and developers/users would use the documentation to know which pin 
is being referred.

Input is welcome.

Thank you for your time,
André Marques.