Robust C Library and Utility for GPIO sysfs Interface in Linux

This is a comprehensive and easy to read example C code designed to work alone or included as a library for dealing with general purpose I/O via the sysfs interface in Linux.  It can easily be applied to any computer which utilizes the GPIO sysfs interface (both pro and maker boards).  Getting started is a breeze.  You just need to decide if you’re going to use it as a library, including it into your existing code, or as a stand-alone utility.  We’ll talk about both in this article, but first and foremost, here’s the source code we’ll be working with:

https://github.com/embeddedarm/gpio-sysfs-demo

So, be sure to download this to your board, extract it, and change your directory to it, like so:

The two important files in this repository came from Technologic System’s GitHub pages:

The included Makefile makes quick work out of compiling the example code mentioned in the sections below, as you’ll see soon enough.

Stand-Alone Utility

As a stand-alone utility, you can easily copy the resulting gpioctl program to a directory in your current PATH and include in a script or use it for those one-off commands.

To do this, we’ll simply run sudo make install.  The Makefile will compile using  gcc -D CTL gpiolib.c -o gpioctl and then automatically copy it to /usr/local/bin, which is popularly included in PATH.  Then, you can run gpioctl --help for instructions on how to use it.  For example, say you want to output logical high on DIO #59.  You would first set the DIO to be an output, and then you’d set it.  Here’s an example of toggling it:

That’s it!  If, say, DIO #59 was tied to an LED, you should see the LED turn on and off again.

Now you can easily include these commands into a bash shell script or Python system call or, well, you get the point.

Pro Tip: Keep in mind, the LED may be active low, so you might actually see the opposite (logic high output turns the LED off, logic low output turns the LED on).

Include as Library

Okay, so if you wanted to use this as a library, giving our own C program access to the helpful functions included in gpioctl.c, we need to include it as a source when compiling our program. You’ll find the example source code gpiodemo.c included in the repository you downloaded earlier:

If you simply run make, you’ll get a compiled gpiodemo binary which simply toggles DIO #59, which is connected to an LED on a breadboard.  Referring to the Makefile, you’ll see it’s compiling the example code by running gcc -o gpiodemo gpiolib.c gpiodemo.c.  Now, you can take this knowledge and example and apply it to your own project.

Bonus: Very Fast GPIO

The sysfs API allows for very simple IO access, but it is not very fast.  For example, on the TS-4900 sending out a square wave on a single CPU GPIO through the sysfs API will toggle at around 160 – 170 KHz.  The same IO accessed through registers will toggle at 1.66 – 1.74 MHz.  FPGA GPIO will always be slow at around 700 hz.  If you’re needing higher performance GPIO programming in order to meet very specific timing requirements, you might want to take a look at the gpiolib-fast.c solution.  Basically, instead of going through sysfs, you’ll be using the GPIO memory registers directly.  Take care in doing so, as the operations aren’t atomic and can therefore foul things up in unexpected ways.  Kernel drivers or other processes accessing GPIO in the same bank performing a read/modify/write can rewrite the same register with old values causing unexpected results.  Source code can be found here:

Conclusion

You should now be able to control GPIO through the sysfs interface like a boss!  We hope this article was helpful in getting your project off the ground quickly.  If it made your day, please consider sharing it!  If you have questions, please use the comments below.

Author: Derek Hildreth

eBusiness Manager for Technologic Systems