Noteworthy remarks on GPIOs usage and configuration
***************************************************

GPIOs configurations are set using SysConfig.

This section is aimed to highlight recommendation for
the :ref:`debug_pins_configuration` and the
:ref:`pin_configuration_after_closing_driver`.

.. _debug_pins_configuration:

Debug Pins Configuration
========================

For designs where the debug pins (SWDIO and SWDCK) are left unused,
developers should ensure these pins keep their default configuration
- SWDIO pin should be set as **input** with **pull up**,
SWDCK pin should be set as **input** with **pull down**.
To do so, GPIO instances for the SWDIO and the SWDCK pins should be added
in SysConfig as shown below:

   .. image:: ./resources/SysConfig_swdio_swdck.png

   .. note:: Alternatively, the field ``Do Not Configure`` can be set
             in both GPIOs instances.

For designs where the debug pins are repurposed as GPIO or used by drivers,
developers should ensure the configuration set complies with the hardware
design. In all the cases, floating inputs are discouraged. When left
unused, the SWDIO pin should ideally be set as **input** with **pull up**,
while the SWDCK pin should be set as **input** with **pull down**.

.. warning::
     Incorrect configuration of the debug pins may lead to increased
     leakage current.

.. _pin_configuration_after_closing_driver:

Pin Configuration After Closing A Driver
========================================

After closing a driver instance, the application is responsible to ensure the
pin configuration is reverted to tri-state mode.

The listing below showcases reverting to tri-state the pin used by the ADC
driver in the ``adcsinglechannel`` example available in the SDK. The same
applies to all the driver-instances which are using one or several GPIO(s).
In case a driver instance uses several GPIOs, each pin should be reverted
to tri-state mode individually.

.. code-block:: c
   :caption: Revert the GPIO pin (CONFIG_GPIO_ADC_1_AIN) to tri state after closing the ADC instance that is using it
   :emphasize-lines: 5

   ADC_close(adc);
   // The ADC driver instance "adc" does not use its pin anymore
   
   // Set back the ADC pin in high impedance to reduce leakage current
   GPIO_setConfig(CONFIG_GPIO_ADC_1_AIN, GPIO_CFG_NO_DIR); 

Upon driver instance re-opening, the pins are reconfigured as required 
by the driver itself. 

.. warning::
     Failing to revert the tri-state mode configuration may lead to increased
     leakage current.
