# Using the Dougg Gilbert GPIO utils

<abstract>
The gpio utils are a small set of Linux utilities written by Dougg Gilbert for some Microchip microcontrollers
useful to check or set the state of each GPIO lines or write and read the CPU registers  
</abstract>

## Compile and build the utilities

Install the xz-utils and build-essential packages on your board (not on your Linux workstation):

	sudo apt install xz-utils build-essential

Download  the latest utilities version from the D.Gilbert server and untar it:

	wget https://www.acmesystems.it/www/dougg_gilbert_gpio_utils/sama5d3_utils-0.92.tar.xz
	tar -xvf sama5d3_utils-0.92.tar.xz

Compile and install 

	cd sama5d3_utils-0.92
	make
	sudo make install

### How to use the GPIO utils

### a5d3_pio_status

Show the help
 
	a5d3_pio_status -h               

Get the PIO attributes of the line Port A8

	sudo a5d3_pio_status -p A -b 8

	PIO status: 0 (peripheral ACTIVE)
	PIO output status: 0 (line pure input)
	input filter status: 0 (glitch filter DISabled)
	output data status: 0
	pin data status: 0
	interrupt mask: 0 (DISabled)
	multi driver status: 0 (pin driven high and low)
	pad pull-up status: 0 (ENabled)
	peripheral A function [sr1:0, sr2:0]
	input filter slow clock status: 0 (master-fast)
	pad pull down status: 0 (ENabled)
	additional interrupt modes mask: 0 (Both edges)
	edge/level status: 0 (edge detection)
	fall/rise - low/high status: 0 (falling edge or low level detection)
	locked status: 0 (not locked)
	write protect mode: WPEN: 1 (ENabled)
	schmitt trigger status: 0 (ENabled )
	IO drive: 0 (LO_DRIVE)

Get the PIO attributes of all the line of Port A

	sudo a5d3_pio_status -a -p A

	PA0:
	  PIO status: 0 (peripheral ACTIVE)
	  PIO output status: 0 (line pure input)
	  input filter status: 0 (glitch filter DISabled)
	  output data status: 0
	  pin data status: 0
	  interrupt mask: 0 (DISabled)
	  multi driver status: 0 (pin driven high and low)
	  pad pull-up status: 0 (ENabled)
	  peripheral A function [sr1:0, sr2:0]
	  input filter slow clock status: 0 (master-fast)
	  pad pull down status: 1 (DISabled)
	  additional interrupt modes mask: 0 (Both edges)
	  edge/level status: 0 (edge detection)
	  fall/rise - low/high status: 0 (falling edge or low level detection)
	  locked status: 0 (not locked)
	  write protect mode: WPEN: 0 (DISabled)
	  schmitt trigger status: 0 (ENabled )
	  IO drive: 0 (HI_DRIVE)
	...

of course it is possible to read all the other ports

	sudo a5d3_pio_status -a -p B
	sudo a5d3_pio_status -a -p C
	sudo a5d3_pio_status -a -p D

### a5d3_pio_set

Show the help
 
	sudo a5d3_pio_set -h

Disable the pull-up resistor on A/D input lines

	sudo a5d3_pio_set -p B -b 11 -u
	sudo a5d3_pio_set -p B -b 12 -u
	sudo a5d3_pio_set -p B -b 13 -u
	sudo a5d3_pio_set -p B -b 14 -u

### mem2io

Enable the low power Suspend To RAM feature on RoadRunner

	sudo mem2io -w -i fc040018,300

## Links

* [Doug Gilbert repository](http://sg.danny.cz/foxg20/) 

The original in-deep explanation on how the GPIO lines work and how to manage them faster is available on:

* [Gpio utils README](http://sg.danny.cz/foxg20/ag25g20_utils-0.97r14/readme.txt)
* [Aria G25 GPIO notes by Dougg Gilbert](http://sg.danny.cz/foxg20/ag25g20_utils/ariag25_gpio.txt)
* [FOX Board G20 GPIO notes by Dougg Gilbert](http://sg.danny.cz/foxg20/foxg20_gpio.txt)


## Help text

###	a5d3_pio_set -h
	
	Usage: a5d3_pio_set [-b <bn>] [-d <div>] [-D <iod>] [-e] [-f|F] [-g|G]
	                    [-h] [-i|I] [-ii|II] [-l|L] [-m|M] [-o|O] [-p <port>]
	                    [-s <P_A_B_C_D>] [-S <n>] [-t|T] [-u|U] [-uu|UU]
	                    [-v] [-V] [-w <wpen>] [-z|Z]
	  where:
	    -b <bn>      bit number within port (0 to 31).Also
	                 accepts prefix like 'pb' or just 'b' for <port>.
	                 Example: '-b PC7' equivalent to '-p c -b 7'
	    -d <div>     slow clock divider [period=2*(<div>+1)*Tslow_clock]
	    -D <iod>     IO drive: 0->LO, 1->LO, 2->ME, 3->HI
	    -e           enumerate pin names with corresponding kernel pin
	    -f           set interrupt source as falling edge or low level event
	    -F           set interrupt source as rising edge or high level event
	    -g           disables glitch input filter
	    -G           enables glitch input filter
	    -h           print usage message; use twice for more help
	    -i           interrupt disable. Use twice to disable
	                 additional interrupt modes
	    -I           interrupt enable. Use twice to enable
	                 additional interrupt modes
	    -l           set interrupt source as edge event
	    -L           set interrupt source as level event
	    -m           disables multi-drive (open drain)
	    -M           enables multi-drive (open drain)
	    -o           output disable (make GPIO input only)
	    -O           output enable (in generic PIO mode only)
	    -p <port>    port bank ('A' to 'D') or gpio kernel line number
	    -s <P_A_B_C_D>    select line mode: P->PIO, A->peripheral_A
	                      B->peripheral_B, C or D)
	    -S <n>       set output data line to [<n> mod 2] (<n> is 0 to 3)
	                 if 0 or 1 then does an output enable if disabled
	    -t           disables Schmitt trigger on input
	    -T           enables Schmitt trigger on input
	    -u           disables internal pull-up. Use twice to disable
	                 internal pull-down
	    -U           enables internal pull-up. Use twice to enable
	                 internal pull-down. Example: switch PC12 from
	                 pull-up to pull-down: '-b PC12 -u -UU'
	    -v           increase verbosity (multiple times for more)
	    -V           print version string then exit
	    -w <wpen>    write protect mode (for whole PIO) set to <wpen>
	                 0->disabled (def, no write protection), 1->enabled
	    -z           disables input filter slow clock
	    -Z           enables input filter slow clock
	
	Set SAMA5D3 SoCs PIO attributes. Uses memory mapped IO to access PIO
	registers directly. Bypasses kernel.