Since Aster Carrier Board doesn't have buttons and LEDs available for debbuging purposes, we present two alternatives to test GPIOs: the first connects two GPIOs configured as input and output respectively; whereas the second alternative uses an external button and LED to achieve a better user experience, however, the following items are required:

1x LED

1x Button

1x Transistor BC548

2x 2k2Ω Resistor

1x 470Ω Resistor

1x Breadboard

Jumper wires

Note: On this getting started we are going to use 2x Resistor 2k2Ω, but you can use anyone between 1kΩ and 10kΩ. For Resistor 470Ω, you can use anyone between 100Ω and 1kΩ. For the transistor BC548, you can use any switch component you want, as MOSFET, just change the circuit according to the component.

To find out which GPIO number to use in the Linux sysfs interface, you have to know the correspondence between available pins in the carrier board, number of the correspondent pins on the SODIMM connector of the Colibri computer on module and number of the pins on Linux.

Download or open in a web browser the Aster Carrier Board and the Colibri VFxx datasheets from the respective products pages of the developer website:

For this introduction guide, some pins configured by default as GPIO in the Toradex BSP were chosen. The choice of pins was made based on their availability on all the carrier boards covered by the getting-started guide. This module will not go through the configuration of other pins as GPIO, although it is possible.

First of all, you need to find the correspondence between the SODIMM and the connectors exposed for the developer on the Aster Carrier Board. Consult the Aster Carrier Board datasheet and fill the table below based in the example provided:

Note: The notation CONNECTOR.PIN will be employed in this lesson, e.g. X16.5 means pin 5 of the X16 connector.

Have a look at the table available in the "List Functions" chapter of the Colibri VFxx datasheet. It provides a list of most of the Vybrid pins available on the SODIMM connector.

The SODIMM pins we are interested at are connected to the Vybrid SoC and have names defined by the ALT0 function. Each pin is multiplexed to have a specific function - among them GPIO, therefore the GPIO pad, GPIO port and ALT0 functions are the columns that we are interested at.

Having a look at the GPIO Alphanumeric to GPIO Numeric Assignment article, the correspondence between ALT0 and the Linux numeric representation of the GPIO pins is provided as a table. The GPIO pad number corresponds to this number, and to find it from the GPIO port it is possible to use the formula below:

PORTx[y]

Linux numeric representation = 32*x+y

Either by consulting the table from the article pointed above or calculating it, the previous table with the correspondence between Aster Carrier Board pins and SODIMM pins can be extended to have the Vybrid pin name (ALT0), formed by GPIO controller, as example PORT0, plus pin at SoC level, as example [27], and the Linux numeric representation. Fill the table below based in the example provided:

The Toradex Linux pre-built image comes with a tool named Toradex GPIO tool meant for debugging pins configuration. It can also be used to determine the correspondences found in the previous step. We will use it to test the hardware connections.

Note: You need a display and a mouse connected to the system in order to use the GPIO tool. Please go to the beginning of the getting-started guide for more information about assembling the peripherals.

The steps below will use the following pins (Linux GPIO number) to toggle an LED and read the value of a switch:

46 for SW

50 for LED

Use jumper wires to connect GPIO 50 to 2k2Ω resistor, connect the resistor to transistor base pin, connect pin X20.1 (3,3V) from Aster to 470Ω resistor, connect the resistor to one LED and connect to transistor collector pin, connect the transistor emitter pin to pin X20.6 (GND) on Aster Carrier Board. Use jumper wires to connect pin X20.17 (3,3V) to 2k2Ω resistor, connect the resistor to one switch and to GPIO 46, and connect the node to pin X20.9 (GND) on Aster Carrier Board.

There is a debug interface provided by the kernel debugfs for GPIO, which holds information about GPIO pins already reserved for drivers, as well as pin configuration and state. See the example below for the Colibri VF61, and try it yourself:

root@colibri-vf:~# cat /sys/kernel/debug/gpio

GPIOs 0-31, platform/40049000.gpio, vf610-gpio:

gpio-8 ( |AC97 link sdata ) out lo

gpio-9 ( |AC97 link sync ) out lo

gpio-13 ( |AC97 link reset ) out hi

GPIOs 32-63, platform/4004a000.gpio, vf610-gpio:

gpio-41 ( |Wake-Up ) in lo IRQ

gpio-42 ( |cd ) in hi IRQ

gpio-45 ( |enable ) out hi

gpio-46 ( |sysfs ) in lo

gpio-50 ( |sysfs ) out lo

GPIOs 64-95, platform/4004b000.gpio, vf610-gpio:

gpio-83 ( |VCC_USB[1-4] ) out lo

GPIOs 96-127, platform/4004c000.gpio, vf610-gpio:

gpio-102 ( |id ) in lo IRQ

GPIOs 128-159, platform/4004d000.gpio, vf610-gpio:

See that the pins 46 and 50, configured as input and output in the previous steps, are the only ones taken by sysfs and are correctly configured as in and out respectively.

Export, unexport, configure and toggle the GPIO pins as you read the debugfs information to see the changes.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of the Toradex nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL Toradex BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The GPIO sysfs interface enables the use of interrupts from user space, as long as it is supported by the underlying hardware. Read the sysfs GPIO documentation, have a look at the poll system call and try to implement an application that handles the interrupt. Have a look at the source code below for reference:

You have to browse the computer on module datasheet and/or device-tree in order to verify that the pin can be configured as GPIO. After that, you must customize the system device-tree in order to change the pin configuration.

If there isn't a kernel driver that suits your needs, you can access GPIO from kernel space rather than user space, and use the gpio.h kernel library.

There are other ways to access GPIO registers directly either from user space (using mmap) or kernel space (using ioremap). Those are problematic since they bypass the kernel handling of the GPIO controllers and might lead to unexpected behavior.

The behavior is not well defined for every module, depending on the provided BSP. If this knowledge is really required, you might verify the kernel GPIO/pinctrl subsystem. See this patch added to the Vybrid family BSP for more details.