Erik - / FastIO

Replacement for regular GPIO (DigitalIn, DigitalOut, DigitalInOut) classes which has superior speed.

Dependents:   Eavesdropper BitstreamGenerator SimpleDecimationFilter 11U68_MP3Player with TFTLCD ... more

Introduction

FastIO is a library which is largely compatible with standard mbed GPIO functions, but which provides superior speed. The code is based on Igor's earlier work (http://mbed.org/users/igorsk/notebook/fast-gpio-with-c-templates/), with three main differences: port functions are currently not available (this might change in the future), it is ported to many more targets than the original, and instead of only DigitalOut, all options from DigitalInOut are implemented.

FastIO uses a template for the pin number which is connected to the FastInOut object instead of an argument to the constructor like the regular DigitalInOut uses. The important difference between those two is that the value of a template is known by the compiler at compile time, while the supplied pin for regular DigitalInOut is only known at run-time. This allows the compiler to add more optimizations. The only limitations this introduces is that you cannot at run-time choose which pin is used (which would be an extremely rare use case).

You can start by trying out the test bench program, this should work for every supported target (you might need to update the FastIO lib):

Currently the following targets are supported:

• LPC1768
• LPC11uXX
• LPC11XX
• LPC81X
• KLXXz
• K20D50M
• KSDK (K22F, K64F)
• NUCLEO F401RE/F411RE
• NUCLEO F030R8
• EFM32 (Gecko's)
• NRF51822

Unsupported targets

This library has the nice feature that it also supports unsupported targets. Obviously these do not get the speed advantage of FastIO, but in case your target is not supported, it will automatically use regular DigitalInOut instead. So if you integrate it in another library it will also work on targets which are not supported by FastIO.

A warning message is printed in the compiler if it reverts back to DigitalInOut.

Performance

The main goal is to have a faster, more efficient alternative to regular mbed GPIO functions, so lets compare that. As of library version 86, the mbed library contains extra debug code that is as of yet not possible to be disabled (in the online compiler in a suitable way). This slows DigitalInOut down compared to older versions, but does not affect FastIO. This is, depending on the function, roughly a factor 2 difference: mbed version 86 is twice as slow as version 85.

Five different performance figures are measured:

• Fixed write(pin.write(1);)
• Variable write (pin.write(val);)
• Reading the pin state and comparing it (if (pin.read() == 0) break;)
• Toggling a pin using operators (pin= !pin;)
• Switching between input and output (pin.output(); pin.input();)

While there are other use cases, these should cover the most used ones. Storing the read value is not included, but should have a fairly similar result. Just comparing it is an easy way to make sure the operation cannot be (partially) optimized away by the compiler, although it results in a longer time than what is actually used by purely the read operation. The main goal of FastIO is to have fast writing, reading, and toggling between input and output (for bidirectional lines), fast construction and mode switching is preferred, but not as important.

The following table shows the time used by fastIO, and also as percentage compared to regular DigitalInOut, this will scale with your clock frequency:

Note that these numbers are from the specific testbench, which highly depends on which optimizations the compiler decides to make. So for your situation it can be different, for example I have seen the write speed change after changes to the read code. Mbed standard write speed also depends on the library version. Since not all targets are supported in older versions I stopped tracking that speed (was also too much effort). If you want to know the comparison for a certain library version, run the testbench on that version.

Usage

The library contains three classes you can use:

FastInOut<PinName> your_name;
FastOut<PinName, initial_state> your_name;
FastIn<PinName, initial_mode> your_name;

Initial_state is by default 0 (so output low) and is optional, initial_mode is by default PullDefault, and is optional. Some examples:

FastOut<LED1> led;             //FastOut object for LED1, will default to output low
FastIn<D5, PullUp> input;    //FastIn object for D5, with by default PullUps enabled

Contrary to regular DigitalIn/DigitalOut, FastIn/FastOut can use all functions available to DigitalInOut/FastInOut. The only difference between the three FastIO classes is the initial conditions: FastInOut doesn't set any initial conditions, and the current state of the uC will be maintained. FastOut sets it as output, either high or low, and FastIn as input, with or without pullups/pulldowns enabled. Afterwards you can change your FastIn to an output using simply .output().

For other examples you can look at the test bench code.

#ifndef __FAST_IO_H
#define __FAST_IO_H

#include "FastIO_LPC1768.h"
#include "FastIO_LPC11UXX.h"
#include "FastIO_LPC81X.h"
#include "FastIO_KLXX.h"
#include "FastIO_K20D50M_KPSDK.h"
#include "FastIO_STM32F4.h"
#include "FastIO_NUCLEO_F030.h"
#include "FastIO_LPC11XX.h"

#ifndef INIT_PIN
#warning Target is not supported by FastIO
#warning Reverting to regular DigitalInOut
#include "FastIO_Unsupported.h"
#endif

#include "mbed.h"

/**
 * Faster alternative compared to regular DigitalInOut
 *
 * Except the constructor it is compatible with regular DigitalInOut.
 * Code is based on Igor Skochinsky's code (http://mbed.org/users/igorsk/code/FastIO/)
 */
template <PinName pin> class FastInOut
{
public:
    /**
     * Construct new FastInOut object
     *
     * @code
     * FastInOut<LED1> led1;
     * @endcode
     *
     * No initialization is done regarding input/output mode,
     * FastIn/FastOut can be used if that is required
     *
     * @param pin pin the FastOut object should be used for
     */
    FastInOut() {
        INIT_PIN;
    }
    
    ~FastInOut() {
        DESTROY_PIN;
    }

    void write(int value) {
        if ( value )
            WRITE_PIN_SET;
        else
            WRITE_PIN_CLR;
    }
    int read() {
        return READ_PIN;
    }

    void mode(PinMode pull) {
        SET_MODE(pull);
    }

    void output() {
        SET_DIR_OUTPUT;
    }

    void input() {
        SET_DIR_INPUT;
    }

    FastInOut& operator= (int value) {
        write(value);
        return *this;
    };
    FastInOut& operator= (FastInOut& rhs) {
        return write(rhs.read());
    };
    operator int() {
        return read();
    };
    
    private:
    fastio_vars container;
};

/**
 * Faster alternative compared to regular DigitalOut
 *
 * Except the constructor it is compatible with regular DigitalOut. Aditionally all
 * functions from DigitalInOut are also available (only initialization is different)
 * Code is based on Igor Skochinsky's code (http://mbed.org/users/igorsk/code/FastIO/)
 */
template <PinName pin, int initial = 0> class FastOut : public FastInOut<pin>
{
public:
    /**
     * Construct new FastOut object
     *
     * @code
     * FastOut<LED1> led1;
     * @endcode
     *
     * @param pin pin the FastOut object should be used for
     * @param initial (optional) initial state of the pin after construction: default is 0 (low)
     */
    FastOut() : FastInOut<pin>::FastInOut() {
        write(initial);
        SET_DIR_OUTPUT;
    }

    FastOut& operator= (int value) {
        this->write(value);
        return *this;
    };
    FastOut& operator= (FastOut& rhs) {
        return this->write(rhs.read());
    };
    operator int() {
        return this->read();
    };
};

/**
 * Faster alternative compared to regular DigitalIn
 *
 * Except the constructor it is compatible with regular DigitalIn. Aditionally all
 * functions from DigitalInOut are also available (only initialization is different)
 * Code is based on Igor Skochinsky's code (http://mbed.org/users/igorsk/code/FastIO/)
 */
template <PinName pin, PinMode pinmode = PullDefault> class FastIn : public FastInOut<pin>
{
public:
    /**
     * Construct new FastIn object
     *
     * @code
     * FastIn<LED1> led1;
     * @endcode
     *
     * @param pin pin the FastIn object should be used for
     * @param pinmode (optional) initial mode of the pin after construction: default is PullDefault
     */
    FastIn() : FastInOut<pin>::FastInOut() {
        SET_MODE(pinmode);
        SET_DIR_INPUT;
    }

    FastIn& operator= (int value) {
        this->write(value);
        return *this;
    };
    FastIn& operator= (FastIn& rhs) {
        return this->write(rhs.read());
    };
    operator int() {
        return this->read();
    };
};

#endif