[En-Nut-Discussion] RFA: Nut/OS GPIO API

[Harald Kipp]

The following rules apply to the Gpio API.

1 The main purpose of the Gpio API is to offer a common interface for
target-independent bit-banged drivers, typically located in nut/dev.

2 The Gpio API may be used by portable application samples, typically
located in nut/app.

3 The Gpio API may be used by target-specific drivers, typically located
in nut/app.
3.1 If the driver requires special function, which are not available in
the Gpio API, then this has to be implemented somewhere else. It is not
acceptable to extend the Gpio API in a target-specific way.

3 The parameter bank specifies the GPIO group of bits (aka. port) and
must be specified by index of type int. This fixed type allows callers
to handle them in a common way during runtime.
3.1 The bank index base is target dependent.
3.2 Bank indexes may not be consecutively numbered.
3.3 If the implementation requires a different type, this may be done by
typecasting the integer index type.

4 The parameter bit specifies the bit within a bank and must be
specified by an index of type int.
4.1 The bit index base is 0.
4.2 Bit indexes are consecutively numbered.

5 Functions, which set GPIO output values, are of type void.
5.1 The only way to determine the validity of a bank or related bit is
by configuring it.

6 Functions, which query pin input values, must return a value of type int.
6.1 A value of 0 is returned, if the pin state is low. Any other value
indicates a high state.
6.1 If the requested bank or bit is not available on the target, the
function result is undefined.

7 Functions, which query pin group (aka port) values, must return a
value of type unsigned int.
7.1 This is bad for 8-bitters, but done to preserve compatibility with
the existing API.

8 The Gpio API will guarantee the following pin configuration
capabilities for all supported targets:
8.1 GPIO_CFG_INPUT to switch the pin to input mode
8.2 GPIO_CFG_OUTPUT to switch the pin to output mode
8.3 If the requested capability is not available for the specified
pin/port, the API function must return -1 to indicate an error.
Otherwise 0 is returned.

9 The Gpio API may provide the following pin configuration capabilities:
9.1 GPIO_CFG_PULLUP to enable the internal pull-up
9.2 GPIO_CFG_MULTIDRIVE to enable open drain mode of an output,
otherwise push-pull is assumed
9.3 If the requested capability is not available for the specified
pin/port, the API function must return -1 to indicate an error.
Otherwise 0 is returned.

10 The Gpio API may offer to register an interrupt handler for a
specific bit and to enable and disable this interrupt.
10.1 After registration, interrupts are disabled.
10.2 It is expected, that interrupts are triggered on any pin change.
Level triggering or triggering on specific edges is not supported.
10.3 If the requested interrupt is not available on that target or for
the specified pin/port, the API functions must return -1 to indicate an
error. Otherwise 0 is returned.

11 In order to use this API, dev/gpio.h needs be included only.
Depending on the target, this header may include others.
11.1 The prototypes of all public API functions are:

 extern uint32_t GpioPinConfigGet(int bank, int bit);
 extern int GpioPinConfigSet(int bank, int bit, uint32_t flags);
 extern int GpioPortConfigSet(int bank, unsigned int mask, uint32_t flags);

 extern int GpioPinGet(int bank, int bit);
 extern void GpioPinSet(int bank, int bit, int value);
 extern void GpioPinSetLow(int bank, int bit);
 extern void GpioPinSetHigh(int bank, int bit);

 extern unsigned int GpioPortGet(int bank);
 extern void GpioPortSet(int bank, unsigned int value);
 extern void GpioPortSetLow(int bank, unsigned int mask);
 extern void GpioPortSetHigh(int bank, unsigned int mask);

 extern int GpioRegisterIrqHandler(GPIO_SIGNAL * sig, int bit, void
(*handler) (void *), void *arg);
 extern int GpioIrqEnable(GPIO_SIGNAL * sig, int bit);
 extern int GpioIrqDisable(GPIO_SIGNAL * sig, int bit);

12 Currently there are several features, mainly pin configurations, used
by code in the trunk, which is temporarily accepted.
12.1 These additional feature can be removed from the API only, if the
same patch (revision) includes alternatives for those parts using these
features. In no way it is acceptable to break any existing code in the
trunk, just to please this RFA.


Thanks,

Harald