satip-axe/kernel/Documentation/stm/pad-manager.txt
2015-03-26 17:24:57 +01:00

709 lines
25 KiB
Plaintext

STMicroelectronics platforms pad management
===========================================
This document tries to explain rationale behind and ways of using
pad management API designed for STMicroelectronics platforms.
All the related functions and macros are declared in
"include/linux/stm/pad.h" and implemented in "drivers/stm/pad.c" file.
Table of contents
=================
1. What is it for?
2. Platform devices definition
2.1. PIOs
2.2. sysconfig bits
2.3. Custom calls
2.4. Modifying configurations in runtime
2.5. Building configurations in runtime
3. Driver API
4. GPIO driver relationship
1. What is it for?
==================
Most of the peripheral controller IPs, like UART (aka ASC), I2C cell (SSC),
Ethernet MAC etc., are connected to the external components (connectors,
other ICs...) via chip's pins (or rather "balls" in case of BGA packaging),
known in the "hardware speech" as pads.
Historically some of the pads were dedicated for the particular use
(especially MII pads in older SOCs) but nowadays more and more of the
functions are multiplexed with generic PIOs (and other functions).
When a PIO pad is used in a non-PIO context (eg. TXD/RXD signals driven
directly by the UART), it was traditionally described as an "alternative
function" for the PIO and the driver was supposed to use PIO API to set
this mode (basing on "port/pin" data provided via platform data).
With a rising SOCs complexity came need of assigning more then one
"alternative function" to each of the PIOs, so, for example, a given pad
can now act as a generic PIO, UART's TXD line or I2C SDA signal, depending
on the board design.
As the PIO bank design didn't provide support for more then one option
(and itself was considered as "immutable") additional multiplexers had
to be introduced, controlled by a loosely defined collections of bits
here and there, commonly known as "sysconfigs". Effectively every single
chips family has its own pads configuration scheme, usually very different
to any other.
As the PIO API also wasn't prepared to take additional responsibilities
the "solution" was to leave the PIO configuration in driver, while
the "sysconfig" bits were configured in chip-specific configuration
("BSP" as it is sometimes called). Obviously it was not a perfect solution
(word "hack" seems to be more suitable) and led to a number of problems.
Finally major changes in kernel allowed to rework all this model and
introduced "pad management" API, which role is to separate all the
PIO and other "magic bits" configuration from the IP (as in UART etc.)
driver implementation and provide it a nicely abstracted function which
can be described as:
"Please, do everything what is required so I could talk to a I2C device
potentially connected to SSC controller I am supposed to drive.
I don't care what PIOs are used, I don't want to know what sysconfig
bits should be set. I just want to put some data into SSC's FIFO and
expect the SDA and SCL lines to be changing from low to high level
and back when the SSC decides to do so."
2. Platform devices definition
==============================
All the elements involved in configuring pads in some particular mode
are encapsulated in "stm_pad_config" structure:
--------8<--------8<--------8<--------
struct stm_pad_config {
int gpios_num;
struct stm_pad_gpio *gpios;
int sysconfs_num;
struct stm_pad_sysconf *sysconfs;
int (*custom_claim)(struct stm_pad_state *state, void *priv);
void (*custom_release)(struct stm_pad_state *state, void *priv);
void *custom_priv;
};
--------8<--------8<--------8<--------
An example configuration could look like this:
--------8<--------8<--------8<--------
static struct stm_pad_config fli7510_usb_pad_config = {
.gpios_num = 2,
.gpios = (struct stm_pad_gpio []) {
STM_PAD_PIO_IN(27, 1, -1), /* USB_A_OVRCUR */
STM_PAD_PIO_OUT(27, 2, 1), /* USB_A_PWREN */
},
.sysconfs_num = 2,
.sysconfs = (struct stm_pad_sysconf []) {
/* usba_enable_pad_override */
STM_PAD_SYSCONF(CFG_COMMS_CONFIG_1, 12, 12, 0),
/* usba_ovrcur_polarity */
STM_PAD_SYSCONF(CFG_COMMS_CONFIG_1, 11, 11, 0),
},
.custom_claim = fli7510_usb_xtal_claim,
.custom_release = fli7510_usb_xtal_release,
}
--------8<--------8<--------8<--------
It says that in order to get USB host controller running correctly,
PIO27.1 should be configured as input, PIO27.2 as an "alternative function 1"
output, two sysconfig bits (CFG_COMMS_CONFIG_1.12 and .11) should be set
to 0 and additionally a special function "fli7510_usb_xtal_claim" called.
All used macros are described below.
2.1. PIOs
=========
Traditionally PIO "pins" in ST chips are grouped in "ports", 8 pins each.
Number of available ports, their alternative functions mapping and
configuration scheme differ a lot between SOCs. Therefore the SOC
initialization code is obliged to call pad manager's initialization
function before performing any pad/PIO related operation:
--------8<--------8<--------8<--------
int stm_pad_init(int gpios_num, int gpio_function,
int (*gpio_config)(unsigned gpio,
enum stm_pad_gpio_direction direction,
int function, void *priv));
--------8<--------8<--------8<--------
"gpios_num" parameter simply defines number of available PIO pins.
Effectively it is:
gpios_num = (max(PIO_ports) + 1) * 8
where max(PIO_ports) is the highest number of available PIO ports. Note
that it is _not_ just a number of available ports, as some SOCs (STx7141
and FLi7540 at the time of writing) "lack" a few ports at the beginning.
The first available port in STx7141 is 1 and in case FLi7540 - 5 (sic!).
And in such cases the code requires an explicit "gap" at the beginning
of all related structures.
The "gpio_config" is a callback function pointer that will be called in
order to configure any given PIO pin in one of three possible directions
(input, output or bi-directional) or custom mode (SOC and implementation
specific) and into a particular function.
The "function" numbering is completely SOC-dependent, as is both defined
(in the "stm_pad_config" structures) and used (in the "gpio_config"
callback) by the SOC setup code. The value that should be used to
configure a pin in generic PIO mode (so its value can be read using
"gpio_get_value()" or set using "gpio_set_value()") should be passed
to pad manager core as the "gpio_function" parameter of the above
initialization function.
The pad configuration as described in platform code and pass should
describe every PIO used by a particular IP as an array of "struct
stm_pad_gpio" pointed by field ".gpios" of "stm_pad_config" structure.
For example, in case of UART these are usually RXD, TXD, CTS and RTS
signals while for SSC in I2C mode these should be SCL and SDA lines.
To make the configurations easier to write (and read), the "pad.h" header
provides a family of helper macros. They all use PORT.PIN convention
(internally converted to contiguous "gpio space") to be in line with
SOC specs and board schematics. The function number, as mentioned above,
is SOC-specific. A PIO my be given a name, if it is supposed to be used
by a driver (see p. 3 below) or modified during initialization (see p. 2.4).
--------8<--------8<--------8<--------
#define STM_PAD_PIO_IN(_port, _pin, _function)
#define STM_PAD_PIO_IN_NAMED(_port, _pin, _function, _name)
#define STM_PAD_PIO_OUT(_port, _pin, _function)
#define STM_PAD_PIO_OUT_NAMED(_port, _pin, _function, _name)
#define STM_PAD_PIO_BIDIR(_port, _pin, _function)
#define STM_PAD_PIO_BIDIR_NAMED(_port, _pin, _function, _name)
--------8<--------8<--------8<--------
There is also a special variant, which defines a PIO description
without specified function nor direction - it is intended to create
a named "stub", configured later with methods described in p. 2.4:
--------8<--------8<--------8<--------
#define STM_PAD_PIO_STUB_NAMED(_port, _pin, _name)
--------8<--------8<--------8<--------
There is also a "priv" field in the "stm_pad_gpio" structure, which
is not being set by any of the standard macros. It may be used to pass
some custom information to the "gpio_config" function mentioned above.
The suggested way to use it defining a SOC-specific macro, as in
the example below:
--------8<--------8<--------8<--------
#define STX7108_PIO_ETH_DATA_IN(_gmac, _port, _pin) \
{ \
.gpio = stm_gpio(_port, _pin), \
.direction = stm_pad_gpio_direction_in, \
.function = _gmac + 1, \
.priv = &stx7108_ethernet_retime_data[_gmac], \
}
--------8<--------8<--------8<--------
and then used like this:
--------8<--------8<--------8<--------
static int stx7108_pio_config(unsigned gpio,
enum stm_pad_gpio_direction direction, int function,
void *priv)
{
<...>
struct stx7108_pio_retime_config *retime_config = priv;
<...>
if (retime_config)
stx7108_pio_config_retime(port, pin, retime_config);
return 0;
}
--------8<--------8<--------8<--------
2.2. sysconfig bits
===================
The term "sysconfigs" cover all generic-purpose registers used to set
different IP configurations values. Their location, organization and use
differ a lot between SOCs, but generally three main schemes exist and
are defined in SOC headers (eg. "include/linux/stm/stx7100.h"):
1. Single registers block with registered grouped in three categories:
SYS_DEV, SYS_STA and SYS_CFG (STx5206, STx7100/9, STx7105/6, STx7111,
STx7141, STx7200).
2. Multiple register blocks ("banks") with registered grouped similarly to
above: SYS_CFG_BANKx, SYS_STA_BANKx and SYS_CFG_BANKx (STx7108)
3. Multiple register blocks with registered semi-randomly located here
and there (STx5197, FLIx7510); in this case individual register names
are defined along the bank names, eg:
--------8<--------8<--------8<--------
#define HS_CFG 0
#define HD_CFG 1
#define CFG_CTRL_A HS_CFG, (0x00 / 4)
#define CFG_CTRL_B HS_CFG, (0x04 / 4)
--------8<--------8<--------8<--------
or
--------8<--------8<--------8<--------
#define PRB_PU_CFG_1 0
#define TRS_SPARE_REGS_0 2
#define CFG_RESET_CTL PRB_PU_CFG_1, (0x00 / 4)
#define CFG_COMMS_CONFIG_1 TRS_SPARE_REGS_0, (0x00 / 4)
--------8<--------8<--------8<--------
Different bits of these registers are responsible for a wide selection
of SOC internals, for example: setting bit 16 of SYS_CFG7 register to 1
in STx7105 enables Ethernet controller. Usually there is a few of such
things to be set per individual IP, sometimes in a different way
depending on required configuration, eg. to configure mentioned
Ethernet controller in MII or RMII.
Our kernel provides an API to work with these registers, defined
in "include/linux/stm/sysconf.h" header, however it should not be
used in any of devices drivers to keep them SOC-agnostic. The only
place that "sysconfigs" should be referenced to are SOC setup files,
either directly in some cases, or as arrays of "struct stm_pad_sysconf"
pointed by field ".sysconfs" in "stm_pad_config" structure, as shown
in p. 2.
Similarly to PIOs case, there are macros defined, helping to create an
array of required "sysconfigs" in a reader-friendly way. As the SYS_CFG
groups are most likely to be set (SYS_DEV & SYS_STA are usually read-only)
there are two macros available, to be used in first two of schemes
described above. Their definitions with examples:
--------8<--------8<--------8<--------
#define STM_PAD_SYS_CFG(_regnum, _lsb, _msb, _value)
/* ethernet_interface_on */
STM_PAD_SYS_CFG(7, 16, 16, 1),
/* enMII: 0 = reverse MII mode, 1 = MII mode */
STM_PAD_SYS_CFG(7, 27, 27, 1),
#define STM_PAD_SYS_CFG_BANK(_bank, _regnum, _lsb, _msb, _value)
/* EN_GMAC0 */
STM_PAD_SYS_CFG_BANK(2, 53, 0, 0, 1),
/* MIIx_PHY_SEL */
STM_PAD_SYS_CFG_BANK(2, 27, 2, 4, 0),
--------8<--------8<--------8<--------
SOCs with defined "sysconfig" register names (third scheme) should use
the following macro in similar way:
--------8<--------8<--------8<--------
#define STM_PAD_SYSCONF(_reg, _lsb, _msb, _value)
/* Ethernet interface on */
STM_PAD_SYSCONF(CFG_CTRL_E, 0, 0, 1),
/* RMII/MII pin mode */
STM_PAD_SYSCONF(CFG_CTRL_E, 7, 8, 3),
/* gmac_mii_enable */
STM_PAD_SYSCONF(CFG_COMMS_CONFIG_2, 8, 8, 1),
/* gmac_enable */
STM_PAD_SYSCONF(CFG_COMMS_CONFIG_2, 24, 24, 1),
--------8<--------8<--------8<--------
2.3. Custom calls
=================
In some cases operations required to set up some configuration are too
complex to be described by the fields above. It may be a case of
a configuration bit shared between a number of independent IPs, typical
example is a bit enabling clock driving couple independent
controller IPs.
To handle such situations "custom_claim" and "custom_release" function
pointers may be defined in "stm_pad_config" structure. They will be
called - respectively - after and before PIOs and sysconfig bits
(de)allocation and get pointer to private data, defined as "custom_priv"
field as well as state ("struct stm_pad_state") pointer, which can be
used to obtain "gpio" value (as described in p. 3), what may be necessary
in the most extreme cases.
2.4. Modifying configurations in runtime
====================================================
As mentioned above IPs may require different pad configuration, depending
on use case as defined in board setup code. For example this may be a
matter of configuring Ethernet in RMII or MII mode, or setting up SSC
in I2C vs SPI mode.
In most cases it is possible to prepare a set of different "stm_pad_config"
structures and assign them to platform data depending on data received
from boards setup. Sometimes however it would require a huge number
of variants, which may not be feasible for a number of reasons.
In such case one may go one of two ways: either create a "template"
configuration and modify some of the fields, or build entire configuration
"from scratch" in runtime.
The first possibility is especially suitable for changing small subset
of PIO information. The following helpers are defined:
--------8<--------8<--------8<--------
#define stm_pad_set_pio(config, name, port, pin)
#define stm_pad_set_pio_in(config, name, function)
#define stm_pad_set_pio_out(config, name, function)
#define stm_pad_set_pio_bidir(config, name, function)
#define stm_pad_set_pio_bidir(config, name, function)
--------8<--------8<--------8<--------
PIOs that are supposed to be modified must be defined with "_NAMED" macro.
Typical example is Ethernet's "PHYCLK" PIO direction, which may be
configured as input or output depending on board design. It is also
possible to change alternative function value, if required:
--------8<--------8<--------8<--------
static struct stm_pad_config *stx7105_ethernet_pad_configs[] = {
<...>
.gpios = (struct stm_pad_gpio []) {
<...>
STM_PAD_PIO_OUT_NAMED(9, 5, 1, "PHYCLK"),
},
<...>
void __init stx7105_configure_ethernet(int port,
struct stx7105_ethernet_config *config)
{
<...>
struct stm_pad_config *pad_config
<...>
pad_config = &stx7105_ethernet_pad_configs[port][config->mode];
<...>
if (config->ext_clk)
stm_pad_set_pio_in(pad_config, "PHYCLK", 2 + port);
else
stm_pad_set_pio_out(pad_config, "PHYCLK", 1 + port);
--------8<--------8<--------8<--------
In some cases this PIO may be also set as "ignored", which means that
it will now be claimed at all during "stm_pad_claim()":
--------8<--------8<--------8<--------
if (config->ext_clk)
stm_pad_set_pio_ignored(pad_config, "PHYCLK");
--------8<--------8<--------8<--------
In case when required function may be present on more then one PIO,
it is possible to define a PIO "STUB" and then set its information
in runtime:
--------8<--------8<--------8<--------
static struct stm_pad_config *stx7105_ethernet_pad_configs[] = {
<...>
.gpios = (struct stm_pad_gpio []) {
<...>
STM_PAD_PIO_STUB_NAMED(-1, -1, "MDIO"),
},
<...>
void __init stx7105_configure_ethernet(int port,
struct stx7105_ethernet_config *config)
{
<...>
struct stm_pad_config *pad_config
<...>
pad_config = &stx7105_ethernet_pad_configs[port][config->mode];
<...>
switch (config->routing.mii1.mdio) {
case stx7105_ethernet_mii1_mdio_pio3_4:
stm_pad_set_pio(pad_config, "MDIO", 3, 4);
stm_pad_set_pio_out(pad_config, "MDIO", 4);
break;
case stx7105_ethernet_mii1_mdio_pio11_0:
stm_pad_set_pio(pad_config, "MDIO", 11, 0);
stm_pad_set_pio_out(pad_config, "MDIO", 3);
break;
--------8<--------8<--------8<--------
There is no explicit support for modifying "sysconfig" definitions
in runtime, however it is possible as well:
--------8<--------8<--------8<--------
static struct stm_pad_config *stx7105_ethernet_pad_configs[] = {
<...>
.sysconfs = (struct stm_pad_sysconf []) {
/* eth1_mdiin_src_sel:
* 1 = mdi in is from PIO11(0)
* 0 = mdc in is from PIO3(4) */
STM_PAD_SYS_CFG(16, 4, 4, -1), /* set below */
<...>
void __init stx7105_configure_ethernet(int port,
struct stx7105_ethernet_config *config)
{
<...>
struct stm_pad_config *pad_config
<...>
pad_config = &stx7105_ethernet_pad_configs[port][config->mode];
<...>
switch (config->routing.mii1.mdio) {
case stx7105_ethernet_mii1_mdio_pio3_4:
/* eth1_mdiin_src_sel = 0 */
pad_config->sysconfs[0].value = 0;
break;
case stx7105_ethernet_mii1_mdio_pio11_0:
/* eth1_mdiin_src_sel = 1 */
pad_config->sysconfs[0].value = 1;
break;
--------8<--------8<--------8<--------
2.5. Building configurations in runtime
====================================================
Some of SOCs are "ultimately flexible" regarding PIOs function allocation.
For example, in case of STx7105, each of SSC2 (and SSC3) signals can be
routed to one of four (sic!) different PIOs. This means 4^2 different
configurations for I2C and 4^3 for SPI, all together 80 (!) variants.
Therefore it is more feasible to create required configuration in runtime.
First, such a structure must be allocated using the following function:
--------8<--------8<--------8<--------
struct stm_pad_config *stm_pad_config_alloc(int gpio_values_num,
int sysconf_values_num);
--------8<--------8<--------8<--------
Parameters define _maximum_ number of PIO and sysconfig entries that
may be added using any of the methods described below. Note that
"stm_pad_config_add_sys_cfg()" is a shortcut for defining SYS_CFG-related
bits with "stm_pad_config_add_sysconf()".
--------8<--------8<--------8<--------
int stm_pad_config_add_sysconf(struct stm_pad_config *config,
int regtype, int regnum, int lsb, int msb, int value);
#define stm_pad_config_add_sys_cfg(config, regnum, lsb, msb, value)
#define stm_pad_config_add_pio_in(config, port, pin, function)
#define stm_pad_config_add_pio_in_named(config, port, pin, function, name)
#define stm_pad_config_add_pio_out(config, port, pin, function)
#define stm_pad_config_add_pio_out_named(config, port, pin,
function, name)
#define stm_pad_config_add_pio_bidir(config, port, pin, function)
#define stm_pad_config_add_pio_bidir_named(config, port, pin,
function, name)
--------8<--------8<--------8<--------
An example of use may look like this:
--------8<--------8<--------8<--------
pad_config = stm_pad_config_alloc(2, 2);
/* SCL */
switch (config->routing.ssc2.sclk) {
case stx7105_ssc2_sclk_pio2_4: /* 7106 only! */
BUG_ON(cpu_data->type != CPU_STX7106);
stm_pad_config_add_pio_bidir_named(pad_config,
2, 4, 2, "SCL");
/* ssc2_sclk_in: 00 = PIO2.4 */
stm_pad_config_add_sys_cfg(pad_config, 16, 11, 12, 0);
break;
case stx7105_ssc2_sclk_pio3_4:
stm_pad_config_add_pio_bidir_named(pad_config,
3, 4, 2, "SCL");
/* ssc2_sclk_in: 01 = PIO3.4 */
stm_pad_config_add_sys_cfg(pad_config, 16, 11, 12, 1);
break;
}
/* SDA */
switch (config->routing.ssc2.mtsr) {
case stx7105_ssc2_mtsr_pio2_0:
stm_pad_config_add_pio_bidir_named(pad_config,
2, 0, 3, "SDA");
/* ssc2_mtsr_in: 00 = PIO2.0 */
stm_pad_config_add_sys_cfg(pad_config, 16, 9, 10, 0);
break;
case stx7105_ssc2_mtsr_pio3_5:
stm_pad_config_add_pio_bidir_named(pad_config,
3, 5, 2, "SDA");
/* ssc2_mtsr_in: 01 = PIO3.5 */
stm_pad_config_add_sys_cfg(pad_config, 16, 9, 10, 1);
break;
}
--------8<--------8<--------8<--------
3. Driver API
=============
From a driver developer's point of view the matter looks quite simple.
He can expect a "struct stm_pad_config *" value in a device platform
data, for example:
--------8<--------8<--------8<--------
struct mydevice_plat_data {
/* Some platform-dependent values */
struct stm_pad_config *pad_config;
};
static struct platform_device mydevice = {
.name = "mydevice",
.id = -1,
.dev.platform_data = &(struct mydevice_plat_data) {
.pad_config = &(struct pad_config) {
/* See p. 2 of this document */
}
}
}
--------8<--------8<--------8<--------
And now, all the driver is supposed to do while being "probed" is to call
the following function:
--------8<--------8<--------8<--------
struct stm_pad_state *stm_pad_claim(struct stm_pad_config *config,
const char *owner);
--------8<--------8<--------8<--------
The obtained "struct stm_pad_state *" is supposed to be released when the
device is being removed:
--------8<--------8<--------8<--------
void stm_pad_release(struct stm_pad_state *state);
--------8<--------8<--------8<--------
All together, a "mydevice" driver implementation could look like this:
(all error handling etc. skipped)
--------8<--------8<--------8<--------
struct mydevice {
struct stm_pad_state *pad_state;
};
static int __devinit mydevice_probe(struct platform_device *pdev)
{
struct mydevice_plat_data *plat_data = dev->platform_data;
struct mydevice *mydevice = mydevice_alloc();
mydevice->pad_state = stm_pad_claim(plat_data->pad_config,
dev_name(&pdev->dev));
platform_set_drvdata(pdev, mydevice);
return 0;
}
static int mydevice_remove(struct platform_device *pdev)
{
struct mydevice *mydevice = platform_get_drvdata(pdev);
stm_pad_release(mydevice->pad_state);
return 0;
}
static struct platform_driver mydevice_driver = {
.driver = {
.name = "mydevice",
.owner = THIS_MODULE,
},
.probe = mydevice_probe,
.remove = mydevice_remove,
}
--------8<--------8<--------8<--------
Alternatively one can decide to use "devm" style API, which releases
resources automatically on device removal:
--------8<--------8<--------8<--------
struct stm_pad_state *devm_stm_pad_claim(struct device *dev,
struct stm_pad_config *config, const char *owner);
void devm_stm_pad_release(struct device *dev, struct stm_pad_state *state);
--------8<--------8<--------8<--------
So the "mydevice_probe" would be:
--------8<--------8<--------8<--------
static int __devinit mydevice_probe(struct platform_device *pdev)
{
devm_stm_pad_claim(&pdev->dev, plat_data->pad_config,
dev_name(&pdev->dev));
return 0;
}
--------8<--------8<--------8<--------
and that's it! Calling "devm_stm_pad_release" is not necessary at all
(one may want to use in an error path in "probe").
The "state pointer" is also useful when the drivers temporarily wants
to switch some of the related pads to generic PIO mode.
--------8<--------8<--------8<--------
unsigned stm_pad_gpio_request_input(struct stm_pad_state *state,
const char *name);
unsigned stm_pad_gpio_request_output(struct stm_pad_state *state,
const char *name, int value);
void stm_pad_gpio_free(struct stm_pad_state *state, unsigned gpio);
--------8<--------8<--------8<--------
The "name" is defined by the platform configuration as described in p. 2.1
above, and should shared between the driver and all the BSPs (the "well
known" name, for the I2C signals should be _always_ described as "SCL"
and "SDA"). Value returned by the "request" functions is just a
"generic gpio" number, which can be used with standard "gpio_set_value()"
and "gpio_get_value()" calls.
This may be useful to perform some non-standard "bit-banging" operations,
for example as a hardware issue workaround or to implement operations not
supported by the hardware controller cell. For example, if "mydevice" driver
was supposed to pull the line down for 100us in case of error, as the
hardware wouldn't be doing this on its own:
--------8<--------8<--------8<--------
void mydevice_handle_error(struct mydevice *mydevice)
{
unsigned signal_gpio;
signal_gpio = stm_pad_gpio_request_output(mydevice->pad_state,
"SIGNAL");
gpio_set_value(signal_gpio, 0);
usleep(100);
gpio_set_value(signal_gpio, 1);
stm_pad_gpio_free(mydevice->pad_state, signal_gpio);
}
--------8<--------8<--------8<--------
4. GPIO driver relationship
===========================
As it is clear now, that pad management and PIO interface are closely
related to each other. As the "generic PIO" mode is effectively just
one of possible pad configuration, PIO driver is a pad manager client.
For a number of reasons it is somehow privileged though, and there is
a special, private API, for its sole use only:
--------8<--------8<--------8<--------
int stm_pad_claim_gpio(unsigned gpio);
void stm_pad_release_gpio(unsigned gpio);
const char *stm_pad_get_gpio_owner(unsigned gpio);
--------8<--------8<--------8<--------
*** Please, DO NOT USE THIS API in any other driver! ***