Introduction ============ This is a small group of Linux utilities for the Atmel SAMA5D2 family of SoCs (System on a Chip). The SAMA5D2 family could be considered as an enhancement of the SAMA5D3 and SAMA5D4 families and share many macrocells. A macrocell is the term used for a named function, or instance of a function, within the SoC. GPIO lines are grouped in units of 32 and controlled by macrocells named, PIOA, PIOB, PIOC, and PIOD. Depending on the context, the more general name "PIO" may be considered as a macrocell. And that more general sense is how Atmel document the SAMA5D2, with a section (or chapter) for each in their 2642 page "datasheet". Some of these utilities work with the Linux kernel while others bypass the kernel and directly manipulate the macrocell registers which are memory mapped. Mainline "DT" (device tree) kernels since lk 4.2 have support for the SAMA5D2 family. Summary ======= The following executables are built, their source code can be found in the src/ directory. Some of these utilities have man pages and they are found in the doc/ directory. a5d2_pio_set set PIO attributes on given GPIO line a5d2_pio_status fetch PIO status values for given GPIO line a5d2_pmc monitor the Power Management Controller (PMC) a5d2_tc_freq generate squarish waves using the TC macrocell(s) devmem2 read or write to memory address (useful for controlling memory mapped IO) N.B. no longer installed since clashes with Debian/Ubuntu package of same name; can be made be hand gpio_sysfs access and test a GPIO line using sysfs interface hex2tty command/response tester for serial lines i2c_bbtest I2C master using user space GPIO bit banging i2c_devtest I2C master using kernel /dev/i2c-<num> device is_ariag25 script helper, exit status 0 for at91sam9g25 is_arm script helper, exit status 0 for EABI (ARM) is_foxg20 script helper, exit status 0 for at91sam9g20 is_foxglx script helper, exit status 0 for Axis 384LX is_sama5d2 script helper, exit status 0 for sama5d2 family is_sama5d3 script helper, exit status 0 for sama5d3 family is_sama5d4 script helper, exit status 0 for sama5d4 family mem2io read or write multiple 32 bit values from memory. readbits sysfs based GPIO line reader setbits sysfs based GPIO line writer xbee_api specialization of hex2tty for XBee API Build system ============ The SAMA5D2 family is powerful enough to run to do the builds itself. That is simpler than cross building. The following assumes a root file system based on Debian 7, 8 or something similar. Connect the system to the internet via one of the ethernet macrocells (or perhaps a WiFi USB dongle) and make sure the root file system is up to date: # apt-get update # apt-get dist-upgrade To compile and build utilities load the (pseudo) package: # apt-get install build-essential To run the "./build_debian" script to generate a deb binary package that can be installed on other ARM systems; this pakage is required: # apt-get install debhelper Other "-dev" packages may be needed for some peripherals. In the top level directory of this package is a script called build_debian.sh . It will build a Debian binary package and place it in the directory above the current. It can be invoked like this: # ./build_debian.sh RIf that is not suitable, then this should work: # make ; make install You may need to check where the 'make install' places the executables and man pages. Documentation ============= Read the code (and send corrections to me please). There is usage information in each utility accessed with the '-h' option. With some utilities '-hh', '-e' or '-ee' provide extra information (e.g. a5d2_pio_status and a5d2_pio_set). gpio_sysfs and gpio_ioctl ========================= These two utilities have almost identical functionality. They differ in the way the access the gpio lines at the kernel interface. gpio_sysfs uses the sysfs gpio interface documented in the <kernel_source>/Documentation/gpio.txt file in a section titled "Sysfs Interface for Userspace". gpio_ioctl uses ioctls on the /dev/gpio device node and is discussed in the next section. Both utilities can toggle the specified gpio line <num> times with a <usec> delay between each transition (see the '-t', '-n' and '-d' options). The high state may be as a result of an external or internal pull-up resistor (default action) or may be driven high when the '-f' option is used. The accuracy of the <usec> delay depends on several factors (e.g. whether a tickless kernel is used) but it most certainly will not be accurate down to the microsecond level. The gpio_sysfs has an extra '-c' option to count rising, falling or both edges on a gpio line for a given duration (default 1 second). See the gpio.txt kernel documentation file, specifically about the "edge" file. The use of poll() from the user space to detect a level change is quite bizarre and curious readers are encouraged to read the code for the process_count() function in gpio_sysfs.c . Recent "device-tree" Linux kernels (e.g. lk 3.7) have changed the GPIO kernel pin number ordering. In the past it started at 32 (for PA0) to allow other interrupt number to use the numbers 0 to 31. Those two numbering systems have been decoupled so GPIO kernel pin numbers now start at 0 (for PA0). This can be detected at run time by the presence or absence of this directory: /sys/class/gpio/gpiochip0 . If it is present PA0 is GPIO kernel pin number 0. devmem2 and mem2io ================== The devmem2 program allows memory locations to be read and written. The helps access the memory-mapped IO locations used by the Atmel AT91 series of SoCs. It was written by Jan-Derk Bakker <jdb@lartmaker.nl> in 2000. A copy of that source is in this directory The author has added a similar program called mem2io which a few extra features like the ability to read from a script file and change multiple locations in one invocation. Both devmem2 and mem2io were built and installed in earlier versions of this package. However recently a Ubuntu server based system for ARM was found to have the devmem2 program installed from its own package. [Debian 6 does not have a devmem2 package in its standard repositories and devmem2 is flagged as a "requested package" so it may appear in the future.] So to avoid clashes in the future, the devmem2 program is no longer built or installed. It can still be made "by hand" with 'make devmem2'. The mem2io program can be used as a replacement but it has a slightly different command line syntax. Douglas Gilbert dgilbert@interlog.com 21st February 2016