Soft-UART Implementation on OMAPL PRU - Software Users Guide

From Texas Instruments Wiki
Jump to: navigation, search



Introduction

This article serves as the User's Guide for the Soft-UART implementation on the Programmable Real-Time Unit (PRU) of the OMAP-L13x and AM1x devices from Texas Instruments. This user's guide will detail the features supported, location of source code, software configuration options and selection method, build procedure, and sample test procedure.

The Soft-UART software emulates a UART protocol on the PRU. The implementation uses the serializers of one on-chip McASP for the UART TX and RX lines. The following high level components create the Soft-UART solution:

  1. PRU Firmware - This firmware is responsible for controlling the physical transmission/reception of data.
  2. Linux Driver - The driver is implemented using the serial subsystem of the Linux kernel as in interface to send and receive data.
  3. OpenEmbedded Recipes - The building of the entire system including bootloaders, kernel, and file system is accomplished using an overlay to the OpenEmbedded project. The OpenEmbedded project is a community effort for building custom embedded distributions. It solves the often complex cross-compilation and linking issues as well and handling generation of file system images. More details for using this overlay can be found in the Build Procedure section below.
   Note: The Linux Driver is implemented on the 2.6.32 kernel.  Currently there no plans to port this driver to a newer kernel version.

Features

The Soft-UART implementation supports the following features:

  • 6 - 8 bits per character (configurable)
  • LSB-first
  • 1 or 2 stop bits
  • Receiver oversampling of x8 and x16 (configurable)
  • Parity generation and error detection (even, odd, or no parity)
  • Configurable FIFO depth from 1 to 16
  • Configurable FIFO timeout
  • Configurable McASP serializer mapping for each TX & RX signal
  • Configurable half or full duplex
  • Independent baud rates supported for Soft-UART ports
    • Configurable maximum baud rate (up to 115200 baud)
    • Dependent baud rate for each Soft-UART based upon software-configurable maximum baud rate divided by 1, 2, 4, 6, 12, 16, 24, 48, 64, 96, 192, & 384
  • Two - four full duplex Soft-UARTS per PRU

Calculating Number of Supported Soft-UARTs

Overview

The number of supported Soft-UARTs depends on user-defined software configuration options and the operating baud rate of each Soft-UART. The Soft-UART Configuration Options section provides additional details on the software configuration options impacting the number of Soft-UARTs (primarily PRU frequency, maximum baud rate, and PRU mode). This section explains the dependency between the software configuration and number of supported Soft-UARTs, outlines how to calculate the maximum number of Soft-UARTs achievable, and advises how to select the optimal software configuration.

In general, the dependency is attributed to a PRU cycle constraint associated with the PRU's single-threaded architecture and requirement of polling for interrupts. The Soft-UART implementation uses the McASP to handle the physical input and output of the data on the Tx and Rx lines. The McASP interrupts the PRU after transmitting and receiving each data frame. Because of the PRU's single-threaded architecture, the PRU core must complete all data processing during the time interval between these interrupts. The rate of McASP Tx and Rx interrupts are explained below.

Tx side:
On the Tx side, the McASP is configured to operate at the same clock as the software configured maximum baud rate. All data is transmitted at this clock rate. Note to achieve slower baud rates, the Soft-UART implementation repeats each transmitted bit the baud rate divisor number of times. For example, if the max baud rate is 57600, 9600 baud is achieved by repeating each bit 6 times (57600 / 9600 = 6). The McASP will interrupt the PRU after each data transmission is complete, or a maximum of every 1/ (Max baud rate) seconds during continuous transmission of data.
Rx side:
On the Rx side, the McASP Rx clock is operating at a higher, or oversampled, clock compared to the software configured maximum baud rate. When configured for 8x over-sampling (default), the receive section of the McASP is clocked eight times the maximum baud rate (that is 8 * Maximum baud-rate). The McASP generates an interrupt every time a serializer receives data. During a continuous stream of data, the McASP would then generate receive interrupts once every 1/ (8 * baud-rate) seconds, where baud-rate is the baud-rate of each Soft-UART.

For successful reception, the PRU must carryout all the data processing and read the new data available on every McASP interrupt. Therefore, by extension, all data processing and read of new data is constrained to the number of PRU cycles available between the McASP interrupts. The available PRU cycles are calculated based on the fastest possible interval between McASP interrupts, 1/ (8 * Maximum Baud-rate), or by

      PRU Cycles = (PRU Frequency)/ (8 * Maximum Baud-rate)

Figure 1 below provides a representation of the PRU Cycles available for different PRU frequency and various maximum or Maximum (or Base) Baud rates.

PRU cycles total.png
Figure 1. PRU cycles available between McASP interrupts


Figure 2 below provides the graphical representation of the PRU Cycles Consumed by single UART for different divide factor. Note, the baud rate divisor = max baud rate / configured UART baud rate.

UART rx tx cycles.png
Figure 2. PRU Cycles Requirement for single UART for various Baud rate divisors ***


***Note: The values in Figure 2 do not include a buffer. Therefore, one should allow for a buffer or extra available PRU cycles when evaluating whether the number of total PRU cycles is within the available PRU cycles. If the sum of cycles consumed by the UARTs is very close to the total available cycles, the system may be prone to data loss.

The number of supported Soft-UARTs calculation depends on the PRU mode. Therefore, the calculation details for Single PRU mode and Both PRU mode are explained separately.

Single PRU Mode Calculation

In Single PRU mode, one PRU core handles both Tx and Rx lines for all Soft-UART ports. This mode can support at most 4 Soft-UARTs.

Using the chart above, the number of UARTs, the PRU Frequency, and the Base or base baud rate can be selected for the desired combination. The total number of cycles consumed by all UART (Tx & Rx) would be sum total of each individual UART. For the UARTs to be able to operate reliably, this sum total needs to be kept within the values identified in Figure 1. Failure to do so may result in data loss.

For example: for the single UART @ baud rate of 115200 while the Base baud rate is set to 115200 the following is true.

  1. The Baud rate divisor is 1
  2. PRU Cycles for Tx is 250
  3. PRU Cycles for Rx is 290
  4. Total PRU Cycles for Tx & Rx is 540

While the PRU is running 150 MHz, the total available cycles for base baud is 1302. In this scenario, one can have up to 2 UARTs in full duplex mode on single PRU following PRU Cycles.

  1. 1080 PRU cycles while both UARTs are at 115200.
  2. 1225 PRU cycles while one UART is at 115200 and other at 57600.
  3. 1195 PRU cycles while one UART is at 115200 and other at 9600.

On the other hand while PRU is running at 150 MHz, the total PRU cycles available at base baud of 57600 is 2604. In this scenario, one can have

  1. Up to 4 UARTs at 57600 requiring 2160 (540 * 4) PRU Cycles.
  2. Up to 3 UARTs at varying baud rate totaling up to 2100 (700 * 3) PRU Cycles.


Thus, with the increased PRU frequency, there will be improvements that can be achieved. The table below provides a summary of possible combinations.

Table 4 1: Soft-UARTs on Single PRU
PRU Frequency
Default Base Baud
Maximum Number Soft UART
Baud Rate Supported
150 115200 1 - 2 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1200, 600, 300
150 57600 and below 3 - 4 * 57600, 19200, 9600, 4800, 2400, 1200, 600, 300
See the Maximum baud rate section for a complete list of baud rates supported for each base baud.
228 115200 2 - 3 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1200, 600, 300
228 57600 and below 4 * 57600, 19200, 9600, 4800, 2400, 1200, 600, 300
See the Maximum baud rate section for a complete list of baud rates supported for each base baud.
* This is based on theoretical calculation. However, validation is carried out with 3 physical ports only.

Both PRU Mode Calculation

In Both PRU mode, one PRU is dedicated to handle the transmit operation while the other is dedicated to handle the receive operations. Thus, while calculating the maximum baud rate and number of UARTs, the PRU cycles are to be applied separately for transmit and receive paths. This mode can support at most 8 Soft-UARTs.

For example with the PRU is running at 150 MHz, and base baud set as 115200, single UART would require following.

  1. 290 PRU Cycles for receive operations on the Receive PRU with Pre-scalar of 1.
  2. 250 PRU Cycles for transmit operations on the Transmit PRU with Pre-scalar of 1.
  3. 280 PRU Cycles for receive operations on the Receive PRU with the Pre-scalar of 2.
  4. 405 PRU cycles for transmit operations on the Transmit PRU with pre-scalar of 2.

So for having three UARTs, the following would be true.

  1. 870 (290 x 3 @ Pre-Scalar 1) cycles are consumed for receive operation on the receive PRU.
  2. 750 (250 x 3 @ Pre-Scalar 1) cycles are consumed for transmit operation on the transmit PRU.
  3. 1060 (250 + 405 + 405) cycles are consumed for transmit operation on the transmit PRU while using the Pre-Scalar of 1, 2, and 6.

Thus, with the increased PRU frequency, there will be improvements that can be achieved. The table below provides a summary of possible combinations for both PRUs enabled.

Table 4-2: Soft-UARTs on Both PRUs
PRU Frequency
Default Base Baud
Maximum Number Soft UART
Baud Rate Supported
150 115200 3 - 4 * 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1200, 600, 300
150 57600 and below 6 * - 8 * 57600, 19200, 9600, 4800, 2400, 1200, 600, 300

See the Maximum baud rate section for a complete list of baud rates supported for each base baud.

228 115200 4* - 6 * 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1200, 600, 300
228 57600 and below 8 * 57600, 19200, 9600, 4800, 2400, 1200, 600, 300

See the Maximum baud rate section for a complete list of baud rates supported for each base baud.

* This is based on theoretical calculation. However, validation is carried out with 3 physical ports only.

Hardware Requirements

This code depends on additional hardware not found in the EVM box. A reference schematic for the soft-UART hardware can be found here.

The hardware to support the Soft-UART implementation requires the following signals and AM1808 pins:

SIGNAL DIRECTION EXPECTED PIN
SUART<n> TX
Output
McASP Serializer (AXR<m>)
SUART<n> RX
Input
McASP Serializer (AXR<k>)

Location of the Source Code

Source code for all the Soft-UART software components are maintained in Gitorious. Following is the list of software components with their repositories and the branch details.

COMPONENT GITORIOUS REPOSITORY GIT CLONE URL LATEST BRANCH
SUART Firmware
pru/pru-uart-fw git://gitorious.org/pru/pru-uart-fw.git master
Linux Kernel and Driver Source pru/pru-linux-drivers git://gitorious.org/pru/pru-linux-drivers.git master
OpenEmbedded Recipes pru/pru-recipes git://gitorious.org/pru/pru-recipes.git master


The source code from the git repository can be pulled into local host using the git commands below replacing the values in <> marks with the value from the table above. Note: Install git if not available on the local host

git clone <GIT CLONE URL>    # Command to pull the repository
git checkout <LATEST BRANCH>  # Command to checkout to the required branch, if needed

Following are the example commands to pull the Linux driver source code

git clone git://gitorious.org/pru/pru-linux-drivers.git

It is also work noting that many of these repositories also have git tags corresponding to particular releases. These tags can be viewed online, or in the checked out repository by using the git tag command.

Soft-UART Configuration Options

The following parameters can be configured within the Soft-UART code. Note some of these configuration options may impact the number of UARTs and baud rates supported. Refer to the Calculating Number of Supported Soft-UARTs section for additional details.

  1. PRU operating frequency *
  2. PRU mode (Both PRU cores or Single PRU core)
  3. McASP serializer to Soft-UART mapping
  4. Soft-UART mode (Full Duplex or Half Duplex)
  5. Maximum baud rate
  6. Receiver over-sampling
  7. McASP instance number
  8. FIFO time-out *
* Indicates run-time configuration options.

PRU operating frequency

The PRU operating frequency is not directly configurable from the SUART driver source code. However, the PRU frequency does have a direct impact on the behavior of the Soft-UART driver. Please refer to the Calculating Number of Supported Soft-UARTs section for details on the number of UARTs that can be supported while operating at a higher PRU frequency.

On AM18x/AM17x/L13x the PRU frequency can be changed by changing the ARM operating frequency. The PRU operating frequency is half of the ARM frequency. Please refer to the Linux-PSP notes (Building_Software_Components_for_L1x/AM1x section) on how to change the ARM operating frequency.

For example in Linux PSP (03.20.00.12) from TI, the ARM (and therefore the PRU) operating frequency can be set to 456 (228 for PRU) by executing the following command:

    # echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
    # echo 456000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed

To change the ARM Frequency to 372 MHz (or the PRU Frequency to 186 MHz), the following command may be executed on Linux Console:

    # echo userspace > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
    # echo 372000 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_setspeed

PRU mode: Both PRU cores or Single PRU core

The Soft-UARTs can use a single PRU core or two (both) PRU cores. Refer to the Calculating Number of Supported Soft-UARTs section for details on the number of UARTs and baud rates that can be supported while operating in each mode.

To modify the PRU mode, edit the macro PRU_ACTIVE in the file pru/hal/uart/include/suart_api.h.

Macro Name
Description
Allowed values
PRU_ACTIVE
PRU mode, defining number of active PRUs.
SINGLE_PRU
BOTH_PRU

McASP serializer to Soft-UART mapping

The McASP serializers numbers mapped to the Soft-UART ports can be updated in the omapl_suart_board.h header file within the SUART driver source code. To assign different serializers, edit the macros: PRU_SUARTn_CONFIG_RX/TX_SER in the file pru/hal/uart/include/omapl_suart_board.h.

It is recommended to mark the unused UARTs DISABLED (refer to the description of PRU_SUARTn_CONFIG_DUPLEX) and corresponding serializer number as PRU_SUART_SERIALIZER_NONE.

Macro Name
Description
Allowed values
PRU_SUART1_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 1.
PRU_SUART_SERIALIZER_NONE
PRU_SUART_SERIALIZER_0
PRU_SUART_SERIALIZER_1
PRU_SUART_SERIALIZER_2
PRU_SUART_SERIALIZER_3
PRU_SUART_SERIALIZER_4
PRU_SUART_SERIALIZER_5
PRU_SUART_SERIALIZER_6
PRU_SUART_SERIALIZER_7
PRU_SUART_SERIALIZER_8
PRU_SUART_SERIALIZER_9
PRU_SUART_SERIALIZER_10
PRU_SUART_SERIALIZER_11
PRU_SUART_SERIALIZER_12
PRU_SUART_SERIALIZER_13
PRU_SUART_SERIALIZER_14
PRU_SUART_SERIALIZER_15
PRU_SUART1_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 1.
PRU_SUART2_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 2.
PRU_SUART2_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 2.
PRU_SUART3_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 3.
PRU_SUART3_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 3.
PRU_SUART4_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 4.
PRU_SUART4_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 4.
PRU_SUART5_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 5.
PRU_SUART5_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 5.
PRU_SUART6_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 6.
PRU_SUART6_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 6.
PRU_SUART7_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 7.
PRU_SUART7_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 7.
PRU_SUART8_CONFIG_RX_SER
Serialzier for Receive pin for Soft-UART 8.
PRU_SUART8_CONFIG_TX_SER
Serialzier for Transmit pin for Soft-UART 8.

Soft-UART mode: Full duplex or Half duplex

To modify the duplex of a Soft-UART port, edit the macros PRU_SUARTn_CONFIG_DUPLEX, in the file pru/hal/uart/include/omapl_suart_board.h.

Possible value
Description
PRU_SUART_HALF_TX_DISABLED | PRU_SUART_HALF_RX_DISABLED UART is disabled for both Tx & Rx operation
PRU_SUART_HALF_TX | PRU_SUART_HALF_RX UART is enabled for both direction Tx & Rx
PRU_SUART_HALF_TX_DISABLED | PRU_SUART_HALF_RX UART is enabled for only Receive operations
PRU_SUART_HALF_RX_DISABLED | PRU_SUART_HALF_TX UART is enabled for only Transmit operations

It is recommended to have the UART disabled if there is no physical serializer and no Soft-UART Port associated with it.

Maximum baud rate

To modify the base baud rate, edit the macro SUART_DEFAULT_BAUD in the file pru/hal/uart/include/suart_api.h. Note that there exist limitations with maximum number of UARTs with different baud rates. Please refer to the Calculating Number of Supported Soft-UARTs section for more details on this limitation.

Possible value
Description
115200
This implies that any Soft-UART can have the maximum baud rate of 115200. The various baud rate supported with this configuration would be 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1200.
57600
This implies that any Soft-UART can have the maximum baud rate of 57600. The various baud rate supported with this configuration would be 57600, 19200, 9600, 4800, 2400, 1200, 300.
38400
This implies that any Soft-UART can have the maximum baud rate of 38400. The various baud rate supported with this configuration would be 38400, 19200, 9600, 2400, 1200.
19200
This implies that any Soft-UART can have the maximum baud rate of 19200. The various baud rate supported with this configuration would be 19200, 9600, 4800, 1200.


The table below provides the list of supported baud-rates for the given maximum baud rate and the baud rate divisor values.

Baud Rate divisor
115200
57600
38400
19200
1
115200
57600
38400
19200
2
57600
28800
19200
9600
3
38400
19200
12800
6400
4
28800
14400
9600
4800
6
19200
9600
6400
3200
12
9600
4800
3200
1600
16
7200
3600
2400
1200
24
4800
2400
1600
800
32
3600
1800
1200
600
48
2400
1200
800
400
96
1200
600
400
200
192
600
300
200
100
384
300
150
100
50
Note: The shaded boxes are not supported by any standard terminal emulation programs like (mini-com, Tera-term; HyperTerminal etc).

Receiver over-sampling

To modify the over sampling, edit the macro SUART_DEFAULT_OVRSMPL in the file pru/hal/uart/include/suart_api.h.


Possible value
Description
SUART_8X_OVRSMPL The receive line is over-sampled 8x times. This is the default setting and is recommended for most of the requirements.
SUART_16X_OVRSMPL The receive line is over-sampled 16x times. Note that having this setting, the maximum baud rate supported would be 57600.

McASP instance number

McASP unit is configurable through the kernel config. This is fixed to “0” for AM18x/L138 and defaults to “1” for AM17x/L137. This is in accordance with the current HW connections.


Possible value
Description
0 The McASP instance 0 on the OMAP is to be used by the firmware implementation. This is tested for AM18x/L138 only.
1 The McASP instance 1 on the OMAP is to be used by the firmware implementation. This is tested for AM17x/L137 only.

FIFO timeout

FIFO timeout is configurable at module init. See the Running the Soft-UART Sample Application section.

Build Procedure

This section will detail both how to build an entire distribution using OpenEmbedded and the overlay contained in the pru-recipes repository as well as building the Linux kernel and PRU firmware stand-alone.

Building using OpenEmbedded

This sections covers using OpenEmbedded and the pru-recipes overlay to build the entire distribution. This is required when building applications that will link with the pcsc-lite library to provide the proper cross-compilation environment and libraries. The pru-recipes overlay was based on the Arago project overlay from arago-project.org and so you will see the use of the arago name throughout.

Prerequisites

Install Required Packages

For an Ubuntu 10.04 host you should install the following packages:

  • build-essential
  • subversion
  • ccache
  • sed
  • wget
  • cvs
  • git-core
  • coreutils
  • unzip
  • texinfo
  • docbook-utils
  • gawk
  • help2man
  • diffstat
  • file
  • g++
  • texi2html
  • bison
  • flex
  • htmldoc
  • chrpath
  • libxext-dev
  • xserver-xorg-dev
  • doxygen
  • corkscrew

You can use the following command to install all of these package:

sudo apt-get install build-essential subversion ccache sed wget cvs git-core coreutils unzip texinfo docbook-utils gawk help2man diffstat file g++ texi2html bison flex htmldoc chrpath libxext-dev xserver-xorg-dev doxygen corkscrew

Install the Toolchain

You will also need to install the codesourcery toolchain. The normal toolchain location to install to is in /opt/arm-2009q1. You can find information on installing the toolchain at this link

NOTE: you may need to install the toolchain using sudo or change permissions of /opt/arm-2009q1 to allow you to write to that directory.

Change Default Shell

OpenEmbedded contains packages that may have shell script that is not Dash shell compliant. To avoid possible issues it is best to change your /bin/sh shell to bash using the following command:

sudo dpkg-reconfigure dash

Select No when prompted

Disk Space Requirements

Building an entire distribution can require a sizeable amount of disk space (Minimum of 19GB).

Obtain the Sources

In order to build with OpenEmbedded you will need to clone three repositories that contain the metadata (recipes) used to build all the packages. NOTE: OpenEmbedded contains recipes for more packages than are required for SmartCard. These packages can be used to add additional functionality to your system but are not built by default.

git clone git://gitorious.org/pru/pru-recipes.git arago
git clone git://arago-project.org/git/arago-oe-dev.git
git clone git://arago-project.org/git/arago-bitbake.git

For the arago-oe-dev and arago-bitbake repositories the last validated revisions are:

  • arago-oe-dev: 1428ddd69c31eb7f9874c8e7941ea614b423904b
  • arago-bitbake: 789382350344a40a3d7c094b5a96bee2a69d01fa

To use these revisions you must do:

  1. cd <repo name>
  2. git checkout <revision>

For example to use the correct revision for arago-oe-dev you would do:

cd arago-oe-dev
git checkout 1428ddd69c31eb7f9874c8e7941ea614b423904b


Setup the Environment File

 cd arago
 cp setenv.sample setenv

Edit setenv and set OEBASE to the location where you cloned the arago repositories above. For example if you made a directory in /home/user/build and cloned the repositories in this directory then OEBASE should be set to:

 export OEBASE=/home/user/build

Setup the Configuration File

 cd arago/conf
 cp local.conf.sample local.conf

Change MACHINE ?= “arago” to MACHINE ?= “am180x-evm”

If you have more than 1 CPU Uncomment the PARALLEL_MAKE and BB_NUMBER_THREADS lines and set the value to the number of CPUs you have

NOTE: If you want to preserve disk space you can also uncomment the line INHERIT += "rm_work". However, if you do this then using the method described below to do custom one-off builds without updating recipes will no longer work since your work directories will be cleaned after each package is built.

Source Environment Script

In the terminal you are going to use for building you will need to source the environment script to set the required variables. This can be done using:

source arago/setenv

Build the Distribution

Using the following command will build the kernel, bootloader, and file system with all required packages for SUART support.

bitbake arago-pcsc-lite-image

NOTE: It can take a long time to do the initial build of the file system depending on your system resources. During this time the build system is downloading the package sources and compiling the packages that make up the system. As long as you do not delete your arago-tmp and downloads directories which are created during the build process, subsequent builds will be done much faster because they will only have to build the delta changes.

Soft-UART Recipes

The following recipes (paths given from the OEBASE directory) were created to build the Soft-UART software components:

  1. arago/recipes/pru/pasm.bb: Stages the pasm executable required to build PRU firmware
  2. arago/recipes/pru/pru-suart-firmware_1.0.bb: Builds the Soft-UART firmware. This is required for the driver to load.
  3. arago/recipes/linux/linux-pru: Build the Linux kernel will support SUART Driver.

Building Firmware

In case you wish to modify the SUART firmware and rebuild outside of the OpenEmbedded flow you can use the following command to build the firmware.

Prerequisites

  1. You will need to have cloned the firmware repositories listed above in order to have access to the SUART firmwares.
  2. You will need to have the pasm tool. You can download the tool from this link

Building SUART Firmware

  1. cd pru-uart-fw
  2. git checkout master
  3. mkdir -p bin
  4. pasm -b -DMCASP0 PRU_SUART_Emulation.p bin/PRU_SUART_Emulation

Building Linux Kernel and Device Driver

Pull the Linux kernel source from the pru-linux-drivers Gitorious repository specified above and go to the latest branch. Execute the following commands in sequence

cd pru-linux-drivers
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- distclean 
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- da850_am18x_pru_defconfig 
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- xconfig

NOTE: In order to use xconfig you may need to install Qt support using sudo apt-get install libqt3-mt-dev. If you do not want to use xconfig you may also use menuconfig to configure the kernel

  1. Enable Device Drivers -> Character devices -> Serial drivers -> PRU based SUART emulation for OMAPL as a module
    EnableSmartCardDriver.png
    NOTE: It is OK to also have the PRU based SmartCard interface for OMAPL driver enabled as a module as well, but it cannot be built statically into the kernel. These two drivers are mutually exclusive and cannot both be loaded at the same time.
    make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- uImage
    make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- modules
    make INSTALL_MOD_PATH=/home/user/target_rootfs modules_install

Any drivers built as modules need to be added to the target root file system.

Components on Target File System

All the software components of the Soft-UART have to be placed at specific directories in the target file sytem. Following table has the list of software components and their location on the target file system.

COMPONENT DESCRIPTION LOCATION ON FILE SYSTEM
SUART Firmware Firmware to run on PRU cores /lib/firmware/PRU_SUART_Emulation.bin
Linux Driver SUART driver. Loads firmware and provides access to the SUART ports /lib/modules/<kernel version>/kernel/drivers/serial/omapl_pru/suart/suart_emu.ko

Running the Soft-UART Sample Application

This section describes the testing steps for a sample Soft-UART application:

  1. Boot the board and login using root
  2. Insert the suart_emu.ko module to load the firmware and provide access to the Soft-UARTs. The suart_timeout parameter can be set at this time (default of 5ms).
    root@am180x-evm:~# modprobe suart_emu suart_timeout=<timeout in ms>
    ti_omapl_pru_suart ti_omapl_pru_suart.1: firmware: requesting PRU_SUART_Emulation.bin
    ti_omapl_pru_suart ti_omapl_pru_suart.1: fw size 3968. downloading...
    ti_omapl_pru_suart.1: ttySU0 at MMIO 0x1d00000 (irq = 3) is a suart_tty
    ti_omapl_pru_suart.1: ttySU1 at MMIO 0x1d00000 (irq = 4) is a suart_tty
    ti_omapl_pru_suart.1: ttySU2 at MMIO 0x1d00000 (irq = 5) is a suart_tty
    ti_omapl_pru_suart.1: ttySU3 at MMIO 0x1d00000 (irq = 6) is a suart_tty
    ti_omapl_pru_suart.1: ttySU4 at MMIO 0x1d00000 (irq = 7) is a suart_tty
    ti_omapl_pru_suart.1: ttySU5 at MMIO 0x1d00000 (irq = 8) is a suart_tty
    ti_omapl_pru_suart.1: ttySU6 at MMIO 0x1d00000 (irq = 9) is a suart_tty
    ti_omapl_pru_suart.1: ttySU7 at MMIO 0x1d00000 (irq = 10) is a suart_tty
    ti_omapl_pru_suart ti_omapl_pru_suart.1: ti_omapl_pru_suart device registered(pru_clk=228000000, asp_clk=132000000)
  3. Connect the SUART port to a PC with a serial cable. Open a terminal progrAam on the PC.
  4. For RX, run the following command on the L138/137 board. Type or transmit a file in the PC terminal program.
    root@am180x-evm:~# microcom -s <baud> /dev/ttySUn
  5. For TX, run the following command on the L138/L137 board.
    root@am180x-evm:~# cat SUART-README_For_Verification.txt > /dev/ttySUn

Refer to the Test Guide under Additional Documentation for other test methods.

Additional Documentation