READBITS(8)

NAME
readbits - Read GPIO bit value using sysfs

SYNOPSIS
readbits [-b BN] [-h] [-i] [-p PORT] [-r] [-u] [-U] [-v] [-V]

DESCRIPTION

Reads a GPIO line (single bit) specified by BN via the Linux kernel's gpiolib interface in sysfs.

The Atmel AT91 family (including the SAMA5 family) name each GPIO line as follows: P<letter><num> where <letter> starts with 'A' and continues to 'C', 'D' or 'E' depending on the SoC. And <num> is a number starting at 0 up to 31, with the maximum value sometimes less than 31 depending on the SoC. So examples include: PA0, PB31, PD5 and PE31.

GPIO lines can have many controls and be multiplexed with input and output lines of other macrocells in a SoC. The Linux kernel provides the gpiolib subsystem to hide individual SoC GPIO complexity and provide general functionality. A relatively simple sysfs interface is provided by gpiolib under the /sys/class/gpio directory. The interface is described in <kernel_src>/Documentation/gpio.txt in the section titled: "Sysfs Interface for Userspace (OPTIONAL)".

A GPIO line can be specified in one of three ways to this utility:

-b BN only
    Use the manufacturer's name (Atmel in this case) for the -b BN option. The letters can be in upper or lower case and the leading 'P' can be omitted. Examples: '-b PA5', '-b pa5', '-b a5' and '-b PC31' .

-b BN plus -p PORT
    In this form the bank letter is given to -p PORT (e.g. '-p B') and the GPIO line number within that bank is given to -b BN (e.g. '-b 5') . Combining these examples PB5 is the specified GPIO line.

-p PORT where PORT is a number
    In this form the number given to -p PORT (e.g. '-p 35') is a kernel GPIO number. Kernel GPIO numbers can be considered as a Linux kernel experiment that failed in the case of Atmel SoCs. Worse, the mapping between kernel GPIO numbers and Atmel GPIO naming has changed. Best to avoid this form.

Since this utility uses a generic interface within the Linux kernel, it should work with any processors that have GPIOs. The user's challenge is to work out how that processor's GPIO naming conventions map to the Linux kernel's GPIO numbers.

OPTIONS

-b BN
    where BN either starts with a letter and is the manufacturer's GPIO name (Atmel in this case) or it starts with a number. In the letter case a leading 'P' is assumed if not given. The letter can be in upper or lower case and must be followed by a number; examples: '-b PA3', '-b a3' and '-b PC31'. In the case where a number is given first (e.g. '-b 3') then that number is assumed to be the GPIO line within the bank specified by the accompanying -p PORT option.

-h  print out usage message then exit.

-i  ignore setting the line direction to input prior to reading the GPIO line value. The default action is to set the line direction to input prior to reading the GPIO line value. If that GPIO line is known to already be set for input (e.g. due to a successful, prior call to readbits for the same GPIO line) then a little time can be saved by not setting the line direction again.

-p PORT
    if PORT is a letter then it is assumed to be a PIO bank. For example if PORT is 'B' or 'b' then that is Atmel PIO bank 'PB'. In this case the -b BN option is also expected where BN is a number, for example '-b 3'. Together these examples would specify PIO line PB3. If PORT is a number then it is interpreted as a Linux kernel GPIO number. Prior to the lk 3.4 series PA0 mapped to the kernel GPIO number of 32; thereafter is mapped to 0 . If practise, kernel GPIO numbers should be avoided.

-r  if successful this utility either prints out '0' or '1' reflecting the logical state of the GPIO line. If -r option is given once (and this is also the default action) the exit status is 0 in both cases. The exit status will typically be 1 if the utility is unsuccessful. If -r option is used twice then the exit status also reflects the logical state of the GPIO line (i.e. either 0 (for low) or 1 (for high)).

-u  this option causes the specified GPIO line to be "unexported" prior to other operations by this utility. This may be required if the specified GPIO line was left in the "exported" state (e.g. a previous incantation of this utility used the -U option). If this operation fails then an error message is output and the utility continues. See the kernel documentation file (gpio.txt) for more information about exported and unexported states. At boot up typically all available GPIO lines are in the "unexported" state.

-U  this option causes the specified GPIO line to be left "exported" when this utility exits. The default action is to "unexport" the specified GPIO line prior to this utility exiting.

-v  increase the level of verbosity, (i.e. debug output). Additional output caused by this option is sent to stderr.

-V  print the version string and then exit.

NOTES
Atmel generic GPIO lines may be multiplexed with other functions. Examples of these other functions include GPIO lines used for serial ports (e.g. TXD, RXD and RTS), I2C, SPI, 100_Mbps_ethernet and interrupt lines. The readbits utility should be used with care since if the given GPIO line is "in use" then after an invocation of readbits is finished then that GPIO line will be left in generic mode as an input. That may cause the previous function that the GPIO line was being used for to fail. Some versions of the Linux kernel prohibit utilities like readbits touching reserved GPIO lines. However in recent kernels (which have recently introduced "Device Tree" (open firmware) configuration) everything seems to be allowed. That may (and should) change to impose restrictions on other utilities interfering with reserved GPIO lines.

EXAMPLES
First check if some GPIO lines are in use:

   a5d3_pio_status -S
       PIN PIO_A PIO_B PIO_C PIO_D PIO_E
       0: GPIO GTX0 ETX0 MCI0_CDA A0/NBS0
       .....
       31: GPIO DTXD GPIO GPIO GPIO

This indicates the PB31 is being used for the debug serial port TXD line and the other GPIO lines are "free". It is possible that some of those other GPIO lines are in use, for example driving small LEDs or reading the state of a switch. So more checking may be warranted. Let us assume PA31 is free:

   readbits -b pa31
     1

Note that since the Atmel boot sequence sets most GPIO lines to have an internal pull-up resistor, most disconnected GPIO lines will yield 1 when read. To help script writers, the value output to stdout (i.e. '1' or '0') can also be set as the exit status value by using the -r option:

   readbits -b PA31 -r
     1

   echo $?
     1

EXIT STATUS
The exit status of readbits is 0 when it is successful except if the -r option is given. If readbits is successful and the -r option has been given then the exit status is 0 or 1 reflecting the GPIO line state that has been read. If readbits fails then the exit status is most likely to be 1.

AUTHORS
Written by Douglas Gilbert.

REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
Copyright © 2013 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
setbits(sama5d3_utils)