16525 East Laser Drive
Fountain Hills, AZ 85268
Phone (480) 837-5200
Technologic Systems' Logo

Table of Contents


Chapter 1: Introduction


Chapter 2: Getting Started


Chapter 3: TS-SOCKET Macrocontroller Hardware Features


Chapter 4: TS-SOCKET Software Guide


Chapter 5: TS-SOCKET Common Pinouts


Appendix A: FPGA Register Maps


Appendix B: Further References


Appendix C: Revision History



Chapter 1:   Introduction


1.1   About this Manual

This manual documents TS-SOCKET macrocontrollers. Macrocontrollers are 55mm by 75mm computer-on-modules. A complete TS-SOCKET embedded computer is built from a macrocontroller and a TS-SOCKET base board. Features specific to base boards are covered in base board manuals. Designers can also save costs by creating their own base boards in the TS-SOCKET standard, in which case this manual is helpful to make sure all TS-SOCKET specifications are being followed. Users of the TS-4500 should also consult the TS-75xx/TS-4500 manual.


1.2   Feedback and Updates to this Manual

To help our customers make the most of our products, we are continually making additional and updated resources available on the Technologic Systems website at http://www.embeddedarm.com, including manuals, application notes, programming examples, and updated software and firmware.

When we are prioritizing work on these updated resources, feedback from customers (and prospective customers) is the number one influence. If you have questions, comments, or concerns about your embedded computer, please let us know at support@embeddedarm.com.


1.3   Limited Warranty

Technologic Systems warrants this product to be free of defects in material and workmanship for a period of one year from date of purchase. During this warranty period Technologic Systems will repair or replace the defective unit in accordance with the following process:

A copy of the original invoice must be included when returning the defective unit to Technologic Systems, Inc. This limited warranty does not cover damages resulting from lightning or other power surges, misuse, abuse, abnormal conditions of operation, or attempts to alter or modify the function of the product.

This warranty is limited to the repair or replacement of the defective unit. In no event shall Technologic Systems be liable or responsible for any loss or damages, including but not limited to any lost profits, incidental or consequential damages, loss of business, or anticipatory profits arising from the use or inability to use this product.

Repairs made after the expiration of the warranty period are subject to a repair charge and the cost of return shipping. Please contact Technologic Systems to arrange for any repair service and to obtain repair charge information.


1.4   FCC Advisory Statement

This equipment generates, uses, and can radiate radio frequency energy and if not installed and used properly (that is, in strict accordance with the manufacturer's instructions), may cause interference to radio and television reception. It has been type tested and found to comply with the limits for a Class A computing device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are designed to provide reasonable protection against such interference when operated in a commercial environment. Operation of this equipment in a residential area is likely to cause interference, in which case the owner will be required to correct the interference at his own expense.

If this equipment does cause interference, which can be determined by turning the unit on and off, the user is encouraged to try the following measures to correct the interference:

  • Reorient the receiving antenna.
  • Relocate the unit with respect to the receiver.
  • Plug the unit into a different outlet so that the unit and receiver are on different branch circuits.
  • Ensure that mounting screws and connector attachment screws are tightly secured.
  • Ensure that good quality, shielded, and grounded cables are used for all data communications.
  • If necessary, the user should consult the dealer or an experienced radio/television technician for additional suggestions.

The following booklets prepared by the Federal Communications Commission (FCC) may also prove helpful:

  • How to Identify and Resolve Radio-TV Interference Problems (Stock No. 004-000-000345-4)
  • Interface Handbook (Stock No. 004-000-004505-7)

These booklets may be purchased from the Superintendent of Documents, U.S. Government Printing Office, Washington, DC 20402.


1.5   Software and Support

Technologic Systems provides:

  • Free system software and documentation updates available on our website
  • Free technical support by phone, fax, or email
  • 30-day, money back guarantee on evaluation units
  • One-year, full warranty
  • Linux OS Support

1.6   TS-SOCKET Series

The TS-SOCKET form factor is an embedded computing standard created and controlled by Technologic Systems. It defines pinouts on two 100-pin board to board connectors. To emphasize modularity, these connectors are the only connectors on the macrocontroller. TS-SOCKET base boards must provide regulated 5V power and connections to all external devices. TS-SOCKET macrocontrollers feature a powerful embedded SoC CPU, an FPGA, a microSD card slot, XNAND flash storage, a temperature sensor, and a Real Time Clock. Signal lines between the macrocontroller and base board are at TTL (0 to 3.3V) levels, with few exceptions. Many TS-SOCKET base boards are compatible with several or all macrocontrollers. Software support is also consistent between macrocontrollers, so designers can design their system based on one macrocontroller and easily port it to another in order to save cost, save power, or increase performance.

Currently the following macrocontrollers are available:

Macrocontroller Primary Features Specifications
TS-4800 Maximum Performance, Video Playback 800MHz NXP/Freescale i.MX515 ARM Cortex-A8, 256MB RAM
TS-4700 High Performance, Low Cost, Video Playback 800MHz Marvell PXA166 ARM9, 256MB RAM
TS-4500 Lowest Cost 250MHz Cavium ARM9, 64MB RAM
TS-4200 High Performance, Low Power 400MHz Atmel AT91SAM9G20 ARM9, 128MB RAM

1.7   TS-ARM Development Kit

The TS-ARM Development Kit for the TS-SOCKET series includes all equipment necessary to boot into the operating system of choice and start working. The development kit is highly recommended for a quick start on application development. For example, the TS-ARM Development Kit for the TS-4200 (KIT-4200) includes:

  • Development 2GB microSD with USB microSD card reader (MSD-2GB-USB-4200)
    • Debian Linux 5.0 (Lenny) Distribution compiled for ARM
    • Full tool-chains (uclibc and glibc) for cross compiling for ARM
    • Utility source code (ie. nandctl.c) and example programs
  • TS-8200 development platform including low cost plastic enclosure (TS-ENC820)
  • Regulated DC power supply and all cables including NULL Modem cable, etc.

NOTE:

Macrocontroller is not included in the Development Kit, but is sold separately.


1.8   Benefits


Out-of-the-Box Productivity

Technologic Systems Linux products get you to your application quickly. Our macrocontrollers boot directly to Linux as shipped. There is no complicated CMOS setup or configuring of a Linux derivative Operating System to source, define, and load. A TS-SOCKET user can power up the board and immediately begin application development.

Of course, should you wish to configure your own version of Linux or use a different operating system, this is easy too. Technologic Systems provides the solution to fast application development without tedious OS configuration.


Industrial Ruggedness

TS-SOCKET macrocontrollers have 100% solder on components with no moving parts. They work reliably with no heat-sinks from -20 to +70 Celsius.


Fast Bootup

The custom TS-BOOTROM used on all macrocontrollers is optimized for speed. A simple embedded Linux application can be running on a macrocontroller within 3 seconds of powerup.


Small Form Factor

A TS-SOCKET macrocontroller is nearly the same size as a credit card which gives it an advantage when being considered for an application with very tight space limitations or constrictions. Mating high density connectors (available from the TS-4200 website) make it easy for you to design a base board that brings out only the required features, minimizing the size of the system.


Modularity

Modularity is the focus with the TS-SOCKET standard. Base boards designed for one TS-SOCKET macrocontroller will have high drop-in compatibility with the future release of another TS-SOCKET macrocontroller. With this, you don't need to be concerned about being locked into one particular design, giving your application leg room to grow. Modular TS-SOCKET systems are extremely future-proof. Technologic Systems has never discontinued a product, but in the event a CPU for a macrocontroller becomes unavailable, applications can easily be ported to a different macrocontroller. The long lifetimes of Technologic Systems products, and TS-SOCKET systems in particular, save substantial costs in the long term.

With a growing line of TS-SOCKET macrocontrollers and standard base boards available from Technologic Systems, a wide variety of embedded systems with specific needs can be build with inexpensive off the shelf components. If standard base boards don't meet the needs of your application, you can easily design your own base board or contract Technologic Systems to design it.


A Plethora of External Connections

The TS-SOCKET macrocontrollers offer many connections and buses via the high density connectors, such as Ethernet, USB host, USB device, UART, CAN, GPIO, SPI, SD card, I2C, I2S, LCD video, and a configurable 16 bit address/data bus.


FPGA Flexibility

The TS-4500, TS-4700, and TS-4800 have user programmable FPGAs. Custom FPGA bitstreams can be reloaded by software. If your system requires an unusual or custom interface to another device, a TS-SOCKET macrocontroller with an FPGA provides an effective low cost solution. Technologic Systems engineering services are available for FPGA customization.


Excellent Support

At Technologic Systems, our Embedded Systems Engineers answer to both support requests as well as sales inquiries. If you have any questions about the TS-SOCKET standard, Linux kernel or distribution, base board layout, software development, or custom engineering, they are here to help.



Chapter 2:   Getting Started


2.1   Installation Procedure

Before performing any set up or placement procedures, take the precautions outlined in this section.


Handling the Board Safely

The TS-SOCKET macrocontrollers use two high density 100 Pin connectors which are rated for about 100 insertions. Take care to not wear out this connector. If you are to be inserting and removing the modules from the base boards, you may want to consider placing a wear-out board with mating connectors in between the base board and the modules so it can easily thrown out and replaced with a new one.

WARNING:

The TS-SOCKET Connectors are only rated for 100 insertions.

Be sure to take appropriate Electrostatic Discharge (ESD) precautions. Disconnect the power source before moving, cabling, or performing any set up procedures.

WARNING:

Inappropriate handling may cause damage to the board.


Setup and Installation Instructions

Follow these guidelines for safety and maximum product performance:

  • Observe local health and safety requirements and guidelines for manual material handling

Setup Tools

Depending on placement and cabling, you may need the following tools:

  • Small flat-blade screwdriver
  • Small Phillips screwdriver

Setup Procedure

After locating, setting up, grounding, and cabling the TS-SOCKET SBC:

  • Apply power
  • Monitor the TS-SOCKET SBC using a terminal emulator to verify that the board is operating properly

NOTE:

Your TS-SOCKET base board might include a screw power connector on the power input. Notice this connector is removable. Please pull this connector off before applying power.


Disconnecting AC Power

  • Unplug from the power source.
  • Disconnect other cables as required.

2.2   Console and Power Up

An ANSI terminal or a PC running a terminal emulator is required to communicate with your TS-SOCKET single board computer. Simply connect an ANSI terminal (or emulator) to the COM DB-9 header using a null modem cable (these are included in the TS-ARM Development Kit), using serial parameters of 115,200 baud, 8 data bits, no parity, no flow control, 1 stop bit (8N1). If you are running Linux, the minicom program works well, Windows XP users can run the Hyperterm application, and Windows Vista (or later) users can download and run PuTTy. A more detailed explanation is available in "4.1 Connecting via Serial Console".

Depending on your TS-SOCKET base board, connect a regulated power source on the power input connector (ie. TS-8200 requires 5 - 12VDC, minimum 1A). Please note the polarity printed on the board. The boot messages, by default, are all displayed on the DB9 COM port at 115200 baud. The board will also answer telnet connections to IP address 192.168.0.50.

TS-SOCKET macrocontrollers ship with Linux installed on the on-board flash. Upon bootup, The board will boot within 3 seconds to a Linux prompt.

The default fastboot shell has available several standard Linux commands through the busybox program. Technologic Systems has made several modifications to the busybox source code to keep bootup as fast and simple as possible. The modified source code is available to Technologic Systems customers.

Upon bootup, you should see out of your debug port when booting from a properly formatted SD card something similar to:

   >> TS-BOOTROM - built Jan  4 2010 15:26:01
   >> Copyright (c) 2009, Technologic Systems
   >> Booting from onboard NAND flash...
   .
   .
   .
   .
   Finished booting in 3.10 seconds
   Type 'tshelp' for help
   /#

At this point, if you type 'exit' from the serial shell, the TS-SOCKET macrocontroller will then attempt a full Debian Linux bootup from the onboard XNAND flash using partition #3 as the root file system, or from an inserted SD card using partition #4 as the root file system if the SD card is present. The version of Linux located on the SD card is an embedded version of Debian Linux and contains Apache, SSH, PPP, and FTP server and many other common utilities and libraries. The version of Linux located on the XNAND flash is the same as the SD card, but with the larger packages removed so it can be squeezed into the 256MB XNAND Drive. Other community-supported embedded Linux distributions are available. For instance, the "Buildroot" project at http://buildroot.uclibc.org/ allows one to easily build custom filesystems and cross-toolchains.

Should the need arise to automatically bypass the fastboot shell and proceed directly to a different starting point such as SD, NFS, or USB, you can do so by linking the appropriate linuxrc-* file to linuxrc. For example, to boot directly to the microSD card, use the following command:

   ln -sf /linuxrc-sdroot /linuxrc; save

To get back to the fastboot shell at the next boot up, place the file /fastboot in the root directory of the filesystem using touch /fastboot.

The '/linuxrc' file is a shell script that is the very first thing run by the kernel on startup. Several sample startup scripts are included and can either be used directly ("ln -sf /linuxrc-xxx /linuxrc" command) or modified to include custom bootup logic. These shell scripts were designed to be as fast and simple as possible for easy customer modifications. It is anticipated that this shell script be modified from the default to implement things in the customer's product such as backup configurations, software field updates, conditional booting/verification of SD cards, etc. Technologic Systems' professional services are available should you need help in implementing a specific feature.


2.3   Busybox Environment

After booting in under 3 seconds, the TS-SOCKET macrocontroller presents a Linux shell on the serial console. Standard Linux utilities are provided by the busybox program. Type help for a list of provided utilities. Source code for the busybox utility is available on the Technologic Systems FTP site.

A shell subroutine file with a .subr extension is in the root directory. This file is executed at startup and defines several convenient functions. Type tshelp for a list of these features. This can be used from within the Debian environment as well by exporting it with the source command. For example, here is the output after running tshelp on a TS-4500:

   usbload - Load USB kernel drivers
   setdiopin  <1,0,Z> - set DIO header pin 1-44
   getdiopin  - get DIO input state
   setrelay  - turn on/off TS-752 relays according to 3-bit val
   setout  - set 3-bit TS-752 output val
   getin - return 8 bit TS-752 inputs
   gettemp - return Temp. Sensor reading
   save - save initrd back to boot device (NAND, SD or SPI flash)
   sd2nand/nand2sd, sd2flash/flash2sd, nand2flash/flash2nand, etc. -
   (copy initrd image from one media to another)
   recover - recover kernel+initrd images
   sbcTest - run TS production tests
   exit - boot SD card (if present) or filesystem mounted at /mnt/root

In addition, there are several utility programs such as ts4700ctl, sdctl, nandctl, etc. Please refer to 4.16 Standard Driver Utilities.


2.4   Debian Linux

The typical way of doing Linux development on the TS-SOCKET macrocontroller is actually on the board itself (see 4.11 Native and PC Application Development). Since the CPU is a PC-class processor in everything but power consumption and performance, it has no problem running real PC-class operating systems such as Linux. By running the full version of Linux (and not scaled-down microcontroller project OS's such as ucLinux), the TS-SOCKET macrocontroller can run the entire suite of applications contained in the Debian Linux distribution including the compilers. Since almost every open source program available for Linux is contained within the Debian Linux binary distribution, one rarely has to compile the large code-bases that would otherwise have forced integrator to a complicated cross-compilation environment due to the limited RAM/MHz of the embedded computer. All too often, open-source projects do not anticipate the possibility of cross-compilation in their build systems, leaving issues for the system integrator to resolve.

The default microSD card contains compilers and everything needed for developing applications in C, C++, PERL, PHP, and SH. Java, BASIC, TCL, Python and others are available for Debian, but not installed by default.

One can still use cross-compilers hosted on just about any platform if there is a specific need. Technologic Systems includes binary versions of the popular Linux "crosstool" project at http://www.kegel.com/crosstool/ or http://www.codesourcery.com to allow cross-compiling on Windows/cygwin or a Linux/i386 PC on our FTP server.

See "Chapter 4: TS-SOCKET Macrocontroller Software Guide" for more software usage examples.



Chapter 3:   TS-SOCKET Macrocontroller Hardware Features

This chapter gives an overview of TS-SOCKET macrocontroller hardware components. The block diagram below shows a typical macrocontroller. Each model will have minor variations and this diagram does not exactly represent any one particular model. All off-board lines go through the two board to board connectors to the base board.

TS-SOCKET Macrocontroller Hardware Block Diagram

3.1   ARM System-on-Chip CPU

Every TS-SOCKET macrocontroller is built around an ARM System-on-Chip (SoC). These CPUs include all features necessary to run a full-featured operating system such as Linux or Windows CE. They also include a variety of external interfaces, such as UARTs, Ethernet MAC, USB, TWI, and GPIO.


3.2   RAM

Each macrocontroller has 64MB, 128MB, or 256MB of RAM connected to the CPU.


3.3   FPGA

All macrocontrollers feature an FPGA. Any external interfaces called for by the TS-SOCKET specification that are not provided by the CPU are implemented in the FPGA whenever possible. In most cases the FPGA is connected to the CPU by a static memory controller, and as a result the FPGA can provide registers in the CPU memory space. Writing driver software that accesses FPGA registers is not difficult, but in many cases it is also not necessary since Technologic Systems has already done the work. See Chapter 4 for more information on accessing hardware features.

On some macrocontrollers, an FPGA open core source tree is provided. This means that developers can write their own hardware. A custom FPGA load is installed on the TS-4500, for example, with the command ts7500ctl --loadfpga mybitstream.vme.gz. Not all hardware cores are open source. Those that are proprietary property of Technologic Systems are provided as binary netlists in the open core source tree.


3.4   XNAND Flash

All macrocontrollers feature 256MB of XNAND Flash storage. See this white paper for more information on XNAND. Use of XNAND is recommended but not required. Other NAND flash software stacks such as YAFFS2 or JFFS are not supported on macrocontrollers by default. Booting from XNAND is highly recommended for an extremely reliable boot process.


3.5   MicroSD Card Connector

The microSD card socket enables microSD cards to be used as primary storage devices for the TS-SOCKET macrocontroller. On the TS-4500, the hardware core has been implemented by Technologic Systems and is integrated inside the on-board FPGA, in which case the utility sdctl serves as a driver. On other models, the hardware core is integrated inside the CPU, in which case a standard Linux kernel driver is supported.

The SD Card bus also runs to the off-board connectors. This allows for an SD Card, MiniSD Card, or microSD Card connector on a base board. However, only one connector (macrocontroller or base board) can be used at a time.


3.6   Real Time Clock

All macrocontrollers include a Real Time Clock (RTC). This allows the system to keep track of time while powered off. For the RTC to work, a 3.3V battery on the base board must provide a voltage on the V_BAT line. The RTC is an I2C device connected to the CPU TWI bus. See Standard Driver Utilities for information on how to access the RTC.


3.7   Temperature Sensor

All macrocontrollers include a temperature sensor that is accurate to within 1.5 Celsius. The temperature sensor is an I2C device connected to the CPU TWI bus. See Standard Driver Utilities for information on how to access the temperature sensor.


3.8   Ethernet PHY

All macrocontrollers either have an SoC with an integrated Ethernet PHY, or else an Ethernet PHY that is a discrete IC. The developer should not have to worry about the distinction, as the Linux kernel fully supports Ethernet in either case.



Chapter 4:   TS-SOCKET Software Guide

This chapter is a guide for application developers working with the TS-SOCKET platform.

A Linux PC is recommended for development. For developers who use Windows, virtualized Linux using VMWare or virtualbox is recommended in order to make the full power of Linux available. The developer will need to be comfortable with Linux anyway in order to work with embedded Linux on the macrocontroller. The main reasons that Linux is useful are:

  • Linux filesystems on the microSD card can be accessed on the PC.
  • More ARM cross-compilers are available.
  • If recovery is needed, a bootable SD card can be created.
  • A network filesystem can be served.

4.1   Connecting via Serial Console

Connecting to the TS-SOCKET system is done by connecting a RS-232 NULL Modem cable from a development PC running either Linux or Windows to the COM port on the base board. The exact configuration may vary depending on what base board you are using. Many base boards have a "console enable" jumper that must be installed for development. See the manual for your base board for more info.

A terminal emulator utility is required on the development PC. If using Windows, PuTTY or Hyperterminal is suggested. If using Linux, minicom is suggested. Whichever program is chosen, these settings are required to connect:

  • Bps/Par/Bits : 115200 8N1
  • Hardware Flow Control : No
  • Software Flow Control : No

Power on the board, and you should see the boot-up in progress and then the initrd/busybox terminal prompt (within 2 seconds).

If using minicom for Linux, you'll need to modify and save the default configuration page (the created configuration file is generally placed directly into /etc). Do to this, follow these instructions (in terminal):

   1.) apt-get install minicom     [IF NOT YET INSTALLED]
   2.) minicom -s
   3.) [Navigate to 'serial port setup']
   4.) [Type "a" and change location of serial device to '/dev/ttyS0' then hit "enter"]
   5.) [If needed, modify the settings to match this and hit "esc" when done]
      E - Bps/Par/Bits          : 115200 8N1
      F - Hardware Flow Control : No
      G - Software Flow Control : No
   6.) [Navigate to 'Save setup as dfl', hit "enter", and then "esc"]

To use minicom, simply type "minicom" in the terminal and power on the board (you'll need to be root (sudo or su)). You should now see:

   >> TS-BOOTROM - built Oct  1 2008                                               
   >> Copyright (c) 2008, Technologic Systems                                      
   >> Booting from SD card...

Press "Ctrl + A" then "Z" to get the minicom command menu. For example, hitting "Ctrl + A" then "Q" will quit the application and return you to the terminal.


4.2   Connecting via SSH or Telnet

This section will not be comprehensive as to avoid duplicating any documentation which can already be found online or otherwise. To connect via secure shell (SSH), you'll need to set up a password for root since SSH will not allow connections without a password. Use the passwd command to set a password. To connect via SSH in Windows, use an application like PuTTY (which also has telnet support). To connect in Linux, use ssh in the terminal after verifying that you have connectivity using ping. For example: ssh root@192.168.0.50. Likewise, use telnet command for telnet. You may need to change the IP address of the board for it to be recognized on your subnet (common subnet is 192.168.1.xx for example).

If you are having difficulties in using telnet, make sure that 1.) your serial console device (e.g. ttyAM0) is listed in /etc/securetty and 2.) the following line is in the /etc/fstab file:

   devpts         /dev/pts    devpts     gid=4,mode=620 0    0

4.3   Recovery

If you botch a modification during development with the TS-SOCKET macrocontrollers, it is easy to recover it to a previous factory state using the provided shell subroutines provided by default. For example, to restore the TS-4200 XNAND Flash to factory state, boot to a working microSD card and issue the command sd2nand. Another command called recover is smart enough to know where you have booted from and what needs to be recovered. Type tshelp for a list of commands supported.

Alternatively, you may also restore the SD card to the state in which you received it. First, an SD card that has been properly formatted for your TS-SOCKET SBC must be created. The latest images can be downloaded from ftp://ftp.embeddedarm.com/ts-socket-macrocontrollers/. Once the image has been downloaded, it can be copied to the SD card with the following command (assuming /dev/sdb is the device where the SD card is located).

   bzcat ts-sdimage.dd.bz2 | dd of=/dev/sdb

OR

   bunzip2 ts-sdimage.dd.bz2
   dd if=ts-sdimage.dd of=/dev/sdb

4.4   Overview of the Boot Process

This section describes what code is executed when the TS-SOCKET system is powered on or reset. The sequence is:

  • SoC BootROM
  • TS-BOOTROM
  • Linux kernel
  • linuxrc
  • Debian init
  • Embedded application

The Debian init step may be excluded on systems that do not require Debian.


SoC BootROM

When the CPU is powered on, it will typically execute its own hard-coded boot program. This program will look for additional boot code to load and execute, and it will find the TS-BOOTROM.


TS-BOOTROM

TS-SOCKET macrocontrollers do not support u-boot, Redboot, or other standard bootloaders. The TS-BOOTROM is optimized for speed. This makes TS-SOCKET systems ideal for applications that need to start immediately upon power-up. The TS-BOOTROM performs basic register initializations and RAM initialization, and then it selects a boot medium. The selection of boot medium is based on the SD boot jumper. Two boot media are supported: microSD card and XNAND Flash. If the medium indicated by the jumper is clearly not bootable, the bootrom may fall back and boot from the other device.

Once the boot medium is chosen, the TS-BOOTROM passes control to the 446 bytes of code found in the MBR. This code scans the partition table for partitions with an ID of DA hex. The first partition found with this magic ID is loaded into RAM and treated as a kernel binary. If a second partition with this id is found, it is loaded into RAM and treated as an initial ramdisk. When this is done, execution jumps into the kernel.

For the small minority of systems that have a need to perform other behavior at boot time instead of executing a Linux kernel, developers will need to fully understand the functionality of the TS-BOOTROM. Second stage bootloaders, custom microcontroller-style binaries, or other operating systems can be loaded by TS-BOOTROM as long as they have an execution entry point in the same place as the Linux kernel would have on the particular macrocontroller in question. Contact Technologic Systems if you need to execute a binary besides Linux.


Linux Kernel

The kernel performs its own initializations and starts any built-in drivers such as Ethernet. It uses the initrd loaded by the bootrom as a root filesystem. By default, the Linux kernel provided is compiled with several kernel command line switches, including init=/linuxrc. This means that once the kernel is done with its own initialization, it executes /linuxrc.


linuxrc

The /linuxrc (linux run control) file is a shell script which is meant to be easily understood by the developer. By default, several versions of linuxrc are provided, and which one is used can be changed with a simple symlink change. Some systems will use linuxrc to start Debian, while others will use it to immediately start the embedded application.


4.5   Setup a Dynamic/Static IP Address

You can change the default IP address of 192.168.0.50. If you're interested in setting up a dynamic IP address, simply use the dhclient from within Debian or udhcpc from within the busybox/fastboot environment. If you'd like a bit more control over the IP address, you can set up a static IP address. From within Debian, edit /etc/network/interfaces to reflect the changes you'd like to make:

   # Used by ifup(8) and ifdown(8). See the interfaces(5) man page or
   # /usr/share/doc/ifupdown/examples for more information.

   auto eth0
   #iface eth0 inet dhcp
   iface eth0 inet static
           address 192.168.1.100
           network 192.168.1.0
           netmask 255.255.255.0
           broadcast 192.168.1.255
           gateway 192.168.1.1


   #auto eth1
   #iface eth1 inet dhcp

Then, edit the /etc/resolv.conf file to reflect working DNS servers:

   nameserver 208.67.222.222
   nameserver 208.67.220.220

Now, reset the eth0 interface by using ifdown eth0; ifup eth0. Test the connection by using ping google.com.


4.6   Boot Media and Partition Scheme

All macrocontrollers can boot from two sources, XNAND or SD card. Most base boards have an SD boot jumper. If this jumper is installed, the system will first attempt to boot from SD card. If not, it will first attempt to boot from XNAND flash. In either case, the built-in bootloader loads a Linux kernel and an initial ramdisk from the selected boot medium. The default setup is to load an initrd and execute linuxrc. This is specified in the command line passed to the kernel.

The TS-BOOTROM bootloader recognizes a special partition ID of DA hex which is used to indicate partitions that contain a loadable kernel or initrd. So, using this partition ID, these could be in any of the four partitions. (Although the kernel must come first.) However, the scripts provided in the initrd by default assume a standardized partition layout, as follows:


XNAND Drive

   Partition 1 -- kernel binary (0xda)
   Partition 2 -- initrd (0xda)
   Partition 3 -- Debian root filesystem (EXT3)

MicroSD Card

   Partition 1 -- Development tools (FAT32)
   Partition 2 -- kernel binary (0xda)
   Partition 3 -- initrd (0xda)
   Partition 4 -- Debian root filesystem (EXT3)
NOTE:

Note that the MBR installed by default on the TS-SOCKET SBC contains a 446 byte bootloader program that loads the initial power-on kernel and initrd from the first and second partitions. Replacing it with an MBR found on a PC would not work as a PC MBR contains an x86 code bootup program.


4.7   USB Storage Devices

A USB thumb drive can be used to easily move files from a host system. USB memory devices need no extra accessory to connect to the host PC. The flash memory devices can then be hot swapped (inserted or removed without rebooting the host PC). As an example, mounting a USB drive on the TS-4500 in the Debian environment can be done using the command:

   mkdir
   /mnt/usbdrive && mount /dev/sda1 /mnt/usbdrive

Mounting a USB drive on the TS-4500 in the Busybox environment can be done by first inserting the USB drive, applying power, and then using:

   mkdir /mnt/usbdrive
   mount /dev/sda1 /mnt/usbdrive

In the case of the TS-4500 linuxrc file, it automatically detects a USB device and then inserts the necessary modules. Should you need to manually configure the USB thumb drive, the following modules are required to be inserted and then followed up with the mdev -s command:

   scsi_mod
   sd_mod
   ohci_hcd
   usb_storage
   usbserial

4.8   Common Debian Linux Commands and Files

This section will briefly mention some of the most commonly used utilities and files in an embedded Debian environment. If needed, the "Debian GNU/Linux Reference Card" and the Debian home page are great resources for getting started with Debian.


Logging In

After the desired Linux kernel is loaded and executed, the file system loads and networking, logging, Apache web server, etc. are all started. When the login prompt is displayed, type root to login, with no password. A Bash login prompt will then appear. At this point, you are ready to enjoy your TS-SOCKET macrocontroller running Linux.


Shutdown

Use the shutdown -h now command to halt the Linux system when running from SD or USB memory card to avoid corruption issues. The SD card is formatted with a journaled filesystem and is highly tolerant of improper shutdown sequences. The shutdown or poweroff commands are not required but still recommended.


Debian apt-get

When using the Debian Linux file system, adding new packages and removing undesired ones is done all through Debian's package management. apt, dpkg, all behave as expected. With Debian, one can easily install and remove software packages. For a quick demonstration of how easy it is to remove and install programs with Debian, try the following commands:

   apt-get update
   apt-get install hexedit
   hexedit /etc/passwd
   ^C (hit CTRL+C to safely exit)
   apt-get remove hexedit

Disk and Memory Usage Information

   * df -h
      -- Human readable info on space utilization of the SD Card/Filesystem
   * free 
      -- Info on memory/swap usage
   * ps; top; jobs
      -- Provide info about which programs are running (ie. ps aux)
   * mount -o remount,rw /mnt/root
      -- Remount /mnt/root with readwrite permissions (ro for readonly)
   * umount /dev/sda1
      -- Unmount partition 1 of the device at /dev/sda
   * /proc/mounts
      -- File contains additional information about disks

Linux Startup and Shutdown

   * /etc/init.d/
      -- Initialization scripts
   * runlevel
      -- Display default runlevel (also found in /etc/inittab)
   * /etc/rcX.d/XXXxxxxx
      -- Default runlevel scripts ran on system startup (ie. /etc/rc2.d/S99run)
   * /etc/rc0.d/XXXxxxxx
      -- Runlevel 0 (shutdown) scripts ran on system shutdown
   * shutdown -h now; shutdown -r now
      -- Shutdown or restart the system
   * /etc/fstab
      -- Disks mounted on startup
   * /etc/modules
      -- Modules inserted on startup

Navigation of Filesystem

   * ls
      -- List files in directory (use ls -la for more info)
   * cd /dir
      -- Change to directory /dir
   * mkdir /dir
      -- Make directory /dir
   * find /dir -name "*file*"
      -- Locate files in /dir with any filename containing the text "file"
   * echo $PATH
      -- Display where utilities are located
   * /lib/modules/`uname -r`/drivers
      -- Kernel modules and drivers location

System Information

   * dmesg
      -- System messages and logs (see also "/var/log/syslog")
   * ldd --version; gcc --version; /lib/libc.so.6
      -- Linker, Compiler, and other information about compiling environment
   * lsusb
      -- List all USB devices (additional info in /proc/bus/usb)
   * /etc/passwd; /etc/shadow
      -- Contains password information.  Remove second field of the line
         containing "root" delimited by ":" to clear password.
   * history
      -- Display recently used commands
   * man
      -- Manual for programs (ie. man ls)

System Configuration

   * date -s "3 DEC 2009 14:18:00"
      -- Set the time and date (hwclock --systohc will set RTC if available)
      -- Use 'cal' to view calendar
   * ifconfig eth0 192.168.1.111
      -- Set the IP address of eth0 to 192.168.1.111
   * apt-get install package
      -- Install package from Debian repositories
   * dhclient eth0; pump; udhcpc
      -- Obtain an IP address via DHCP
   * /etc/network/interfaces
      -- Network interface configuration
   * /etc/inittab
      -- Describes which processes are started at bootup and during normal 
         operation

Working with Files

   * touch filename
      -- Create a file called filename
   * cat filename; more filename; less filename; head filename; tail filename
      -- View contents of filename
   * cp source/file destination/file
      -- Copy file from source to destination
   * mv source/file destination/file
      -- Move file from source to destination
   * diff file1 file2
      -- View differences between file1 and file2 (use diff -u for cleaner out)
   * cmp file1 file2
      -- Compare two files
   * grep -r string /dir
      -- Recursively search for files in /dir which contain "string"
   * hexdump
      -- Dump ascii, decimal, hexadecimal, octal to terminal
   * sync
      -- Commit any data residing in cache to the disk (SD card). Use liberally.
   * vi; nano; pico
      -- Command line based text editors
   * tar xzvf filename.tar.gz -C /dir ; tar xjvf filename.tar.bz2 -C /dir
      -- Extract a tar.gz file to /dir ; Extract a tar.bz2 file to /dir
   * tar czvf filename.tar.gz /dir ; tar xjvf filename.tar.bz2 /dir
      -- Create a tar.gz file from contents of /dir; create tar.bz2 file from...
   * ftp
      -- File transfer protocol program to download FTP files
   * wget http://www.web.com/filename
      -- Get file from URL (also works with ftp sites)
   * scp root@192.168.1.100:/share/filename /dir
      -- Copy via SSH file filename from user@IP:/share to /dir

Working with Kernel Modules/Drivers

   * insmod module.ko
      -- Manually insert kernel modules (simple; dependency unaware)
   * depmod -a
      -- Build modprobe a list of all modules and dependencies
   * modprobe module
      -- Insert module and any dependencies
   * lsmod
      -- List all inserted modules
   * rmmod module
      -- Remove module from kernel

apt-get install installs a package name, while apt-get remove removes the named package. Visit the Debian home page for further information, since a full in-depth discussion on Debian is outside the scope of this document.


4.9   Loading or Transferring Files

Aside from using a USB thumb drive or SD card to transfer files, three more convenient methods are available for transferring files between a desktop PC and your TS-SOCKET macrocontroller: Ethernet downloads, Zmodem downloads, and NFS server. Full descriptions of each are detailed below. Other programs that use serial ports to transfer should work as well.


Transferring Files via the Ethernet Port

The default Linux root file system includes a small FTP server that can be used for uploading/downloading of files across an Ethernet network. Simply point your preferred FTP client to your TS-SOCKET macrocontroller IP address (default is 192.168.0.50). You can login as root or any valid user previously created from the useradd utility. By default, the TS-SOCKET macrocontrollers will not accept anonymous FTP connections. With the microSD card, a user named "eclipse" is present with password "eclipse".


Zmodem Downloads

Using the Zmodem protocol (not installed by default) to send files to and from the TS-SOCKET macrocontroller is simple and straightforward. The only requirement is a terminal emulation program that supports Zmodem, and virtually all do. If you are using Windows 95 or later for your development work, the HyperTerminal accessory works well.

To download a file to the TS-SOCKET macrocontroller from your host PC, execute lrz at the Linux command line (while using console-redirection from within your terminal emulator) and begin the transfer with your terminal emulator. In HyperTerminal, this is 'Send File...' from the 'Transfer' menu.

To upload a file from the TS-SOCKET macrocontroller to your host PC, execute lsz [FILENAME] at the Linux command line and start the transfer in your terminal emulator. Many emulators, HyperTerminal among them, will automatically begin the transfer themselves.

Occasionally there may be errors in transmission due to background operations. This is not a problem -- Zmodem uses very accurate CRC checks to detect errors and simply resends bad data. Once the file transfer is complete the file is completely error free. For best results when using HyperTerminal, the hardware handshaking must be enabled in HyperTerminal.


NFS Server

Although this method can be a bit more involved, it's the fastest, easiest, and preferred way to transfer files to and from a development PC. Basically, set up a development PC running Linux and set it up as an NFS server to share a directory (see online documentation for accomplishing this such as this one on sourceforge). Mount the NFS server on a folder on the SBC and transfer files to and from that folder. You can even work directly in the folder. The command to mount an NFS server would look similar to this:

   mkdir /mnt/nfsshare && mount -t nfs -o nolock,vers=2 192.168.1.100:/share /mnt/nfsshare

4.10   Application Development Strategy Recommendations

The diagram below illustrates a typical software-hardware stack in a TS-SOCKET application. Actual applications might use all of the pictured layers or only a selection.

Embedded Linux Software/Hardware Stack

Note that development gets more challenging and time-consuming lower in the stack. Scripting is simpler and easier than writing applications in C or C++, which is simpler and easier than Linux kernel development. For quick development of bug-free applications, it is recommended to work as high in the stack as possible. Moving down to more difficult areas is only necessary for performance reasons. The parts of an application that are sensitive to performance should be implemented in the appropriate way, while those that are not should be implemented in scripting languages. In many cases, a complete application can be built out of script wrappers and default driver utilities.

A complete suite of driver applications is provided by Technologic Systems for UARTs, CAN, SPI, and XNAND Flash. In addition, the TS-SOUL library is an excellent resource for TS-SOCKET application developers. It supports GPIO, CAN, SPI, and TWI.

Applications that require response times of approximately 1 millisecond or less must either be implemented in the kernel with interrupt handling, in user space using the /proc/irq subsystem, or in the FPGA in hardware. Technologic Systems specializes in FPGA development, and can often create an FPGA-based solution that completely solves a difficult performance/latency issue for a modest one time engineering charge. Contact Technologic Systems for more information.


4.11   Native and PC Application Development

TS-SOCKET application developers using C or C++ have several options for how to compile code. These are listed below. Note that no matter which compiler is used, an NFS based development setup is recommended. (Linux Journal has a guide on how to do this entitled "Starting Share Files with NFS") With an NFS served by a PC and mounted on the TS-SOCKET system, code can be edited with any PC editor, natively compiled or cross-compiled, and then tested on the target platform, all without moving any files around. Here is the brief set of commands to run after setting up the NFS server in order to access the NFS share and start developing:

   # On-Board development from initrd/fastboot environment
   # Requires NFS server

   udhcpc
   mkdir -p /mnt/root/mnt2
   mount -o nolock,vers=2 192.168.1.101:/home/username /mnt/root/mnt2/
   chroot /mnt/root
   mount /proc
   cd mnt2/

   #EXAMPLE:
   #gcc -g -mcpu=arm9 gettemp.c sbus.c -o gettemp
NOTE:

C or C++ source for the TS-4500 must always be compiled with the -march=armv4 switch. Source for the TS-4200, TS-4700, or TS-4800 must be compiled with the -mcpu=arm9 switch.


Native Compile

A simple .c or .cpp file can be compiled directly on the board by issuing gcc -Wall -mcpu=arm9 tstest.c -o tstest.

  • gcc = C compiler (use gpp for C++ compiler)
  • Wall = print out all warning messages
  • mcpu=arm9 = specify architecture (may vary between processors)
  • tstest.c = file to compile
  • -o tstest = output file name

The on-board Debian distribution also supports gdb for debugging and make for automating a more complex software build.


Linux Cross-Compile

Many developers prefer cross-compiling, particularly if a code base becomes large enough that compiling on a 250MHz platform is slow. Below is a step by step guide to cross-compiling.

WARNING:

The following steps have not been verified and are only presented to demonstrate correct principles.

The following is a step-by-step guide to compiling a simple C++ program for use in the Debian environment. These steps have been verified on a TS-4500 and should work for any of the TS-SOCKET macrocontrollers with the caveat that toolchains might differ slightly. For example, if you would like to compile an application for the busybox environment for the TS-4500, you'll simply need to replace the glibc crosstools with the uclibc crosstools located here and keep in mind that the crosstool directory structure is a little different. Also, for compiling a C program, replace 'g++' with 'gcc'. The same is also true for other compilers.

   Assumptions:
      -- The cross compiler will be located at ~/crosstool (~ is equivalent to $HOME)
	     * mkdir ~/crosstool/   
      -- The program will be located at ~/main.cpp

   01.) Download the cross compile toolchain (EABI)from Technologic Systems:
      *  wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7200-linux/\
      cross-toolchains/crosstool-linux-gcc-4.0.1-glibc-2.3.5.tar.bz2

   02.) Extract to crosstool directory:
      * tar xvf crosstool-linux-gcc-4.0.1-glibc-2.3.5.tar.bz2 -C ~/crosstool

   03.) For cleanliness sake, delete the originally downloaded tar.gz file:
      * rm crosstool-linux-gcc-4.0.1-glibc-2.3.5.tar.bz2

   04.) Change directory to where your program is located:
      * cd ~
      
   05.) Use the following greatest common divisor (gcd.cpp) file as an example if 
	    needed:

   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

     #include <iostream>
     using namespace std;

     int GCD(int a, int b)
     {
         while( 1 )
         {
             a = a % b;
		     if( a == 0 )
			     return b;
		     b = b % a;

             if( b == 0 )
			     return a;
         }
     }

     int main()
     {
	     int x, y;

	     cout << "This program allows calculating the GCD\n";
	     cout << "Value 1: ";
	     cin >> x;
	     cout << "Value 2: ";
	     cin >> y;

	     cout << "\nThe Greatest Common Divisor of "
	          << x << " and " << y << " is " << GCD(x, y) << endl;  

	     return 0;
     }

   =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

   06.) Use the cross compiling toolchain to compile the program:
      * ./crosstool/opt/crosstool/gcc-4.0.1-glibc-2.3.5/\
      arm-unknown-linux-gnu/bin/arm-unknown-linux-gnu-g++ gcd.cpp -o gcd

   07.) Copy the program to the macrocontroller and then test by running it.  You will see:

        ts7500:~# ./gcd 
        This program allows calculating the GCD
        Value 1: 8
        Value 2: 2

        The Greatest Common Divisor of 8 and 2 is 2
        ts7500:~# 

   08.) Additionally, you can include the crosstools in your PATH for less typing:
      * PATH=$HOME/crosstool/opt/crosstool/gcc-4.0.1-glibc-2.3.5/\
      arm-unknown-linux-gnu/bin/:$PATH
      * export PATH
      * arm-linux-uclibc-g++ gcd.cpp -o gcd


Cygwin Cross-Compile

Cross-toolchains are also available for Cygwin users. The usage is very similar to that above.


Eclipse IDE

Technologic Systems supports the Eclipse IDE for TS-SOCKET systems. Eclipse for Linux can also easily be used, but is not officially supported.


4.12   Programming IO Devices

The standard assumption in Linux is that kernel drivers are required in order to control hardware. However, it is also possible to talk to hardware devices from user space. In doing so, one does not have to be aware of the Linux kernel development process. This is the recommended way of accessing hardware on a TS-SOCKET system. The special /dev/mem device implements a way to access the physical memory from the protected user space, allowing reading and writing to any specific memory register. Applications may be allowed temporary access through memory space windows granted by the mmap() system call applied to the /dev/mem device node. The following C code is provided as an example of how to set up user space access to the TS-4700 SYSCON registers at base address 0x80004000:

#include <sys/mman.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <assert.h>
static volatile unsigned short *syscon;
static unsigned short peek16(unsigned int adr) {
	return syscon[adr / 2];
}
static void poke16(unsigned int adr, unsigned short val) {
	syscon[adr / 2] = val;
}

int main(void) {
        int devmem = open("/dev/mem", O_RDWR|O_SYNC);

	assert(devmem != -1);
	syscon = (unsigned short *) mmap(0, 4096,
	  PROT_READ | PROT_WRITE, MAP_SHARED, devmem, 0x80004000);

        poke16(0x6, 0x3); // disable watchdog
        poke16(0x12, peek16(0x12) | 0x1800); // turn on both LEDs

        return 0;
}

Important Notes About the Preceding Code

  • The peek16 and poke16 wrapper functions make the code more readable due to how pointer arithmetic/array indexing works in C, since the same offsets from the register map appear in the code.
  • Make sure to open using O_SYNC, otherwise you may get a cachable MMU mapping which, unless you know what you're doing, probably is not what you want when dealing with hardware registers.
  • mmap() must be called only on pagesize (4096 byte) boundaries and size must at least have pagesize granularity.
  • Only the root user can open '/dev/mem'. For testing, this just means the tester needs to be root, which is normal in embedded Linux. For deployment in the field under Debian, this can be an issue because the init process does not have root privileges. To get around this, make sure the binary is owned by root and has the setuid bit set. The command 'chmod +s mydriver' will set the setuid flag.
  • The pointers into memory space should have the same bit width as the registers they are accessing. In the example above, the TS-4700 FPGA registers are 16 bits wide, so an unsigned short pointer is used. With very few exceptions, FPGA registers on TS-SOCKET macrocontrollers will be 16 bits wide and CPU registers will be 32 bits wide. Unsigned int, unsigned short, and unsigned char pointers should be used for 32, 16, and 8 bit registers, respectively.
  • When compiling ARM code that emits 16 bit or 8 bit hardware register accesses, it is important to add the compiler switch -mcpu=arm9. Otherwise the wrong opcodes may be emitted by the compiler and unexpected behavior will occur.
  • Pointers into memory space must be declared as volatile.
  • FPGA hardware access on the TS-4500 must use the sbus API.

4.13   Running Applications Automatically on Power-Up

In the field, embedded applications will typically be expected to start automatically. The method for doing this in a standard TS-SOCKET system depends on whether Debian is being used.


Debian Environment

In Debian, scripts and/or programs can be run automatically as part of the Linux bootup process by adding them to the /etc/rc2.d runtime folder. For example, if you wanted to immediately print out the IP address on boot, you would follow these simple steps:

   01.) echo "ifconfig eth0" > /etc/init.d/displayip
   02.) chmod +x /etc/init.d/displayip
   03.) ln -sf /etc/init.d/displayip /etc/rc2.d/S01displayip
           * Note: you may need to check your default runlevel with the
             'runlevel' command (default from Technologic Systems is 2)

If you find that your process is being killed, try preceding it with the 'nohup' command, followed by a 'sleep 1' command. For example:

   #!/bin/sh

   echo -n "Initializing my program..."
   nohup myprogram --daemonize &
   sleep 1
   echo "done"

Fastboot Environment

In the fastboot environment, linuxrc is the run control script, which can easily be customized to start applications.


4.14   Dealing with Filesystem Corruption

Embedded Linux developers have to be aware of the danger of filesystem corruption. See this white paper for detailed recommendations. If the system has a filesystem mounted read/write and there is a crash or power loss, corruption on that filesystem is likely. After such an event, running fsck on the affected partition is recommended. With a filesystem on an SD card or USB flash drive, this can be done on-board or on a PC.

The XNAND flash integrity can also be checked and repaired at a lower level. To do this, first unmount any mounted XNAND partitions and kill all XNAND processes. Then execute nandctl --audit --yes. This audit takes several minutes. Auditing the XNAND flash is not strictly necessary, since XNAND is a self-healing medium anyway. If there has been a hang or power loss that may have interrupted an XNAND write, and you anticipate that a similar event is going to happen repeatedly, an XNAND audit will help guarantee the integrity of XNAND data.


4.15   Compiling Linux Kernel with Custom Options

WARNING:

The following steps have not been verified and are only presented to demonstrate correct principles.

The following is a verified step-by-step guide to compiling a custom Linux kernel specifically for the TS-4500. Note that the TS-4500 and TS-7500 run identical software. The principles described below are still valid for other models, but the source tree and compiler may be different for each. Remember to backup file and images so you may revert back to them if something goes wrong.

WARNING:

Back up your files and images.


Prerequisites:

SOFTWARE:

  • Must be logged in as root on a Linux PC separate from the SBC
  • These packages need to be installed for kernel compiling:

    RHEL/Fedora/CentOS:
    yum install ncurses-devel ncurses
    Debian/Ubuntu:
    sudo apt-get install libncurses5-dev libncursesw5-dev

HARDWARE:

  • TS-4500 with 2GB microSD Card inserted
  • TS-8200 or TS-8500 Development Board Connected with SD boot jumper installed
  • MicroSD Card Adapter and USB SD Card Reader
  • Development PC with Linux installed


Procedure:

  
   01.) Download the cross compile toolchain (OABI)from Technologic Systems:
      * wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux\
      /cross-toolchains/crosstool-linux-arm-uclibc-3.4.6.tar.gz

   02.) Extract to current working directory:
      * tar xvf crosstool-linux-arm-uclibc-3.4.6.tar.gz

   03.) Obtain the TS-4500 kernel source tree
      * wget ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/sources/\
      linux-2.6.24-ts-src-aug102009.tar.gz

   04.) Extract the TS-4500 kernel source tree
      * gzip -dc linux-2.6.24-ts-src-aug102009.tar.gz | tar xf -

   05.) Move into the newly extracted directory
      * cd linux-2.6.24-cavium/

   06.) Edit the Makefile at the kernel root dir to point to the appropriate 
        cross-compiler path.  In our case, with the toolchain decompressed into 
        the same directory as the kernel, we'll change line 195 of the Makefile 
        to read:
      * CROSS_COMPILE ?= ../arm-uclibc-3.4.6/bin/arm-linux-

   07.) Type "make ts7500_defconfig" to make the kernel with the options that 
        Technologic Systems uses for the TS-7500/TS-4500

   08.) Type "make menuconfig" and edit the boot command line and other options 
        of interest (optional)
      * For Example, to include CIFS support, use the arrow and Enter keys to 
        navigate to Filesystems -> Network File Systems -> CIFS Support.  Press 
        "y" to include CIFS support into the kernel (alternatively, you could 
        modularize the feature with "m" so you can enable or disable the module 
        on demand which will also enable you to simply copy/paste the cifs.ko 
        into the correct path in the kernel instead of copying the entire kernel 
        (outlined below in appendix)).  Keep hitting "exit" until you're 
        prompted to save changes, choose "yes".

   09.) Type "make" to compile the kernel

   10.) The new kernel will be at "arch/arm/boot" in a compressed format called 
        zImage (the uncompressed version is simply called Image, but it is 
        REQUIRED that it be < 2096640 bytes in size).

   11.) Copy the binary zImage to the second partition (in most cases, this is 
        mounted as /dev/sdb2).  This will erase any data which is on the MiniSD 
        card now, so a backup is advised.
      * TO BACKUP: dd if=/dev/sdb2 of=../zImageBak
      * TO COPY zImage: dd if=arch/arm/boot/zImage of=/dev/sdb2

   12.) At this point, insert the microSD card and try to boot.  

   13.) Explain copying the kernel to XNAND.
        

Compiling TS-Kernel with Custom Options

In order to compile a separate kernel module and come out with a *.ko file for inclusion in the already existing kernel, these are the steps to take following step 08 and ending at step 09 above. Note: Steps after step 02 are unverified/untested. They represent an accurate procedure which one would go through.

   01.) Open menuconfig and modularize the kernel feature using "M".  For 
        example, to modularize cifs.ko, one would use the arrow and Enter keys 
        to navigate to Filesystems -> Network File Systems -> CIFS Support.  
        Press "M" to modularize CIFS support into the kernel then keep hitting 
        "exit" until you're prompted to save changes, choose "yes".
      * make menuconfig
      
   02.) Compile the kernel with the modules and copy the modules to the Linux PC
      * make && make modules && make modules_install  
      
   03.) Retrieve the module which was copied to the Linux PC with a command like
        cp so that it can be installed into the kernel on the MiniSD card.
      * mkdir /mnt/miniSD4
      * mount /dev/sdb4 /mnt/miniSD4
      * cp /lib/modules/2.6.24.4/kernel/fs/cifs/cifs.ko /mnt/miniSD4
      
   04.) Install the module into the kernel by copy and pasting from partition 4 
        of the card to partition 2 on the SBC.
      * cp -r /dev/nbd4/cifs.ko /dev/nbd2/lib/modules/2.6.24.4/kernel/fs/cifs/cifs.ko

   05.) Finally, in order to use the new module, you must enable it.  This can 
         be included in a startup script such as linuxrc.
      * depmod
      * modprobe cifs.ko

Troubleshooting insmod or modprobe Errors

If you're having difficulties inserting your module (e.g. "insmod: error inserting module.ko: -1 Invalid module format"), it could be because either 1.) the kernel which it was compiled against has not been loaded to the microSD and/or 2.) there are module dependencies that are not being satisfied. The dmesg utility is invaluable when trying to troubleshoot these issues.

When compiling additional modules into the kernel, you must use make modules_install as the final step in kernel compiling to install the modules to your development Linux PC. From there, you can create a tarball to copy and then extract to the fourth partition of the microSD card. The example below assumes your microSD card's device node was enumerated to /dev/sdb; use fdisk -l to verify.

   
   tar czvf linuxmodules-2.6.24.tar.gz /lib/modules/2.6.24.4/
   mkdir /mnt/sd_part4
   mount /dev/sdb4 /mnt/sd_part4
   tar xzvf linuxmodules-2.6.24.tar.gz -C /mnt/sd_part4/

After doing this, boot the macrocontroller with the updated microSD card to full Debian and then can use depmod -a to build the module dependency lists that modprobe will use. Once this has been completed, you should then be able to use modprobe to successfully insert the module along with all of its dependencies. For example:

   modprobe usbnet

If you would like your module to be inserted automatically on system startup, then simply include the module name in /etc/modules. For example:

   echo "usbnet" >> /etc/modules

Keep in mind that if anything in the make menuconfig step was required to be compiled as part of the kernel as indicated by [*], then you will need to copy the entire kernel image to the microSD card. For example:

   dd if=arch/arm/boot/Image of=/dev/sdb2

4.16   Standard Driver Utilities

Technologic Systems provides driver utilities for many hardware features and these are installed by default on all TS-SOCKET macrocontrollers. These utilities are written in user space instead of as kernel drivers to provide kernel independence. The utilities for XUARTs, DIO, CAN, and SPI are explained in their respective sections below. These utilities all have names ending in ctl and all have a --help option for users interested in advanced usage.


NBD Drivers

The nandctl utility, along with nbd-client, is used to provide block devices for XNAND. Developers should treat these block devices as normal Linux block devices. If you need more information on XNAND, refer to our XNAND white paper or contact Technologic Systems. If you are not running Linux on your system and would still like to use XNAND, contact Technologic Systems.

On the TS-4500, the sdctl driver serves the same function for the SD card. If you are not running Linux on the TS-4500 and would like to access the SD card, contact Technologic Systems.


Board Control Utilities

There is also a general purpose control utility for each macrocontroller. The name of the utility is usually tsxxxxctl, where xxxx is the model number (e.g. 4200) of the board. However ts7500ctl is used on the TS-4500 since it has the same architecture and software load as the TS-7500.

The board control utility provides simple, scriptable access to DIO, LEDs, the watchdog timer, the Real Time Clock, the temperature sensor, the hardware random number generator, and sometimes other unique features. They also provide a way to reboot the unit.

Board control utilities are open source and serve as excellent sample code for developers who want to write custom functionality in C for DIO or other features.


4.17   UARTs

All macrocontrollers provide 6 UARTs (aside from the debug port) for applications. These UARTs are numbered 0-5. Some UARTs are implemented in the CPU and some in the FPGA. Each model varies in this respect. Also, many UARTs provide an optional TX_EN line, allowing for an RS-485 port. The chart below summarizes the application UART capabilities of each macrocontroller.

UART TS-4200 type TS-4200 TX_EN TS-4500 type TS-4500 TX_EN TS-4700 type TS-4700 TX_EN TS-4800 type TS-4800 TX_EN
UART 0 CPU CN1 pin 67 XUART CN1 pin 67 XUART CN1 pin 67 XUART CN1 pin 67
UART 1 CPU none XUART CN1 pin 65 XUART CN1 pin 77 CPU none
UART 2 CPU none XUART CN1 pin 63 XUART CN1 pin 71 CPU none
UART 3 CPU none XUART none XUART CN1 pin 65 XUART CN1 pin 65
UART 4 CPU none XUART none XUART CN1 pin 63 XUART CN1 pin 63
UART 5 CPU none XUART none XUART CN1 pin 79 XUART CN1 pin 79

XUARTs

XUARTs are extremely flexible high-performance UARTs implemented in the FPGA. They support 7,8,9, or 10 bit mode, and non-standard baud rates. XUARTs are ideal for DMX. Each XUART has a 256 entry transmit buffer. All XUARTs in an XUART block (up to 8) share a 2K entry receive buffer.

The xuartctl utility serves as a driver for XUARTs. It is started automatically in the default software load. Note that on the TS-4500 and TS-4700, FPGA bitstreams that support CAN will have a limited number of XUARTs due to a lack of available FPGA resources.

If TX_EN signals are needed instead of DIO, these must be enabled on most boards. See the Syscon register map for how to do this.


CPU UARTs

UARTs connected to the CPU have standard Linux kernel drivers.


4.18   CAN

The FPGA-based CAN controller on TS-SOCKET macrocontrollers is a SJA1000C compatible controller enhanced with deep FIFOs. The canctl utility serves as a driver for CAN ports. It is open source and can be used as sample code for developers writing applications that are tightly coupled to the CAN port. Also, canctl can run in server mode, allowing the TS-SOCKET system to act as a TCP to CAN bridge with a CAN-based application running on a remote system. Run canctl --help on a TS-SOCKET system for usage information.

NOTE:

The TS-4200 does not support CAN.


4.19   GPIO

TS-SOCKET macrocontrollers can provide as many as 81 GPIO lines to the base board. Many GPIO lines have alternate functions, so the exact number available for a given application depends on what other functions are needed as well as which model of macrocontroller is used.

DIO 0-14, on the high end of CN1, are always available as FPGA-controlled GPIO if needed. However they all also have alternate functions which can be optionally enabled. The list below explains all alternate functions.


DIO 0

  • Off-board IRQ #5

DIO 1

  • Off-board IRQ #6

DIO 2

  • Off-board IRQ #7

DIO 3

  • Base board CLK (For base board CPLD/FPGA)

DIO 4

  • UART 5 CTS#
  • Edge counter 0 input

DIO 5

  • BD_ID_DATA (Standard base boards use this line along with an 8:1 mux chip to provide an 8 bit base board ID code)

DIO 6

  • ADC_DAT (Used for off-board MCP3428 ADC)
  • Edge counter 1 input

DIO 7

  • ADC_CLK (Used for off-board MCP3428 ADC)
  • UART 5 TX_EN

DIO 8

  • AN_SEL (Used for off-board MCP3428 ADC)
  • UART 1 TX_EN

DIO 9

  • PUSH_SW# (Used for reset switch)

DIO 10

  • CAN2_TXD (2nd CAN port is usually not implemented)
  • UART 2 TX_EN

DIO 11

  • CAN2_RXD (2nd CAN port is usually not implemented)

DIO 12

  • UART 0 TX_EN

DIO 13

  • UART 6 RXD (Can be used as a separate RX channel for RS-422)
  • UART 3 TX_EN (TS-4700, TS-4800)
  • UART 1 TX_EN (TS-4500)

DIO 14

  • UART 4 TX_EN (TS-4700, TS-4800)
  • UART 2 TX_EN (TS-4500)

For how to enable/disable these alternate functions, see the syscon register map for each macrocontroller.

CAN pins and XUART pins can also function as DIO. SPI pins can function as DIO on most macrocontrollers.


4.20   SPI

The spictl utility and API serve as an open-source driver for SPI on TS-SOCKET systems. Run spictl --help for usage information. On the TS-4200, the Atmel SoC SPI controller is used. Other models all use the open-source Technologic Systems SPI FPGA core. The register map for this core is available in Section A.10.


4.21   MUXBUS

All TS-SOCKET macrocontrollers have an external bus called the MUXBUS. The bus consists of 16 muxed address/data lines, ALE#, CS#, DIR, BHE#, and WAIT#. The MUXBUS provides a way for TS-SOCKET base board designers to include static memory devices, bridges to other industry standard buses such as PC/104, or an FPGA that implements custom features. Verilog modules ts8100.v and muxbusbridge.v are provided as examples of how to interface with the MUXBUS.

MUXBUS slaves can be 8 bit or 16 bit devices. Each macrocontroller has an 8 bit MUXBUS address space which must be accessed with 8 bit reads and writes, and a 16 bit MUXBUS address space which must be accessed with 16 bit reads and writes. Software that works with the MUXBUS must know whether it is talking to an 8 bit or 16 bit slave device and act accordingly.

The bus cycle speed depends on the FPGA clock speed, which varies from one macrocontroller to another. Thus, the MUXBUS behavior is specified in clock cycles. The bus cycle works as follows:

  • ALE# is asserted, and the address is driven on the bus lines. This condition is held for TP_ALE + 1 clock cycles.
  • ALE# is de-asserted while the address remains valid for TH_ADR + 1 clock cycles.
  • Data is driven on the bus lines (for a write) or the bus lines go high-Z (for a read) for TSU_DAT + 1 clock cycles.
  • CS# is asserted for TP_CS + 1 clock cycles.
  • CS# is de-asserted and data remains valid for TH_DAT + 1 clock cycles.

BHE# and DIR remain valid throughout the whole bus cycle. WAIT# is an input. The external device can assert the WAIT signal during the CS# pulse to extend it. The bus can work in 8 bit or 16 bit modes. In 8 bit mode, mux lines 8-15 are not used for data and BHE# is ignored. In 16 bit mode, byte reads and writes are still supported using BHE# and A0.

WARNING:

The WAIT line is not used on the TS-4500. On the TS-4500, the MUXBUS cycles must be configured to be slow enough for external devices.

Each module will have a 16 bit external bus configuration register in its syscon. The format of that register is as follows:

Bus Config Register Bits Usage
bit 0 Bus enable (otherwise, pins are GPIO or reserved)
bits 2:1 TP_ALE
bits 4:3 TH_ADR
bits 6:5 TSU_DAT
bits 12:7 TP_CS
bits 15:13 TH_DAT
WARNING:

A TP_CS of 0x3f is not supported -- use a value from 0 to 62.

The FPGA clock cycle times for specifying MUXBUS behavior are:

Macrocontroller Cycle Time
TS-4200 20.20 ns
TS-4500 13.33 ns
TS-4700 13.33 ns
TS-4800 10.42 ns

4.22   USB to Serial Devices

WARNING:

The following steps have not been verified and are only presented to demonstrate correct principles.

Additional serial ports can be added to the TS-SOCKET macrocontrollers by using USB to Serial cables through the USB Ports (and even more if a USB hub is used). You will need three modules, all of which are loaded by default. If you are having difficulties locating these drivers, contact Technologic Systems.

   01.) Insert the necessary modules
        * insmod /lib/modules/`uname -r`/kernel/drivers/usb/host/ohci-hcd.ko
        * insmod /lib/modules/`uname -r`/kernel/drivers/usb/serial/usbserial.ko
        * insmod /lib/modules/`uname -r`/kernel/drivers/usb/serial/ftdi_sio.ko
   02.) The kernel should then detect the FTDI device and add device node at
          /dev/ttyUSB0

After successfully installing the USB to Serial adapter, you can then use minicom as described in 3.1 Connecting via Serial Console above.


4.23   USB WiFi

Please refer to this document for information on using the standard USB WiFi device.


4.24   USB Device Port Example Usage

WARNING:

The following steps have not been verified and are only presented to demonstrate correct principles.

Certain Technologic Systems Single Board Computers (SBCs) contain both USB Host and USB Device ports. This section will discuss the configuration and use of the Linux USB device gadgets (http://www.linux-usb.org/). The two supported gadgets are 1.) USB Mass Storage Device and 2.) IP over USB (A.K.A. USB Ethernet).

The USB Mass Storage Device Linux USB gadget will allow you to use your SBC as a storage device, like a USB thumb drive, when connected to a host PC. Subsequently, the SBC can access the saved data through the storage element named usb_storage_file.

The IP over USB (A.K.A. USB Ethernet) Linux USB gadget will allow you to connect to your SBC with a USB cable from a PC like you would with a CAT5 Ethernet cable. You will have access to the SBC via the TCP/IP connection allowing you to use any networking utility (e.g. ping, ssh, ftp, http, etc).

All software modules required for Linux are contained on recent SBCs (those released with the May 18, 2010 or later software load). For Windows, a driver interface configuration file (linux.inf) will need to be downloaded and installed on the host PC. This procedure is described in detail below.


Utilizing TS-SOCKET System as "USB Mass Storage Device"

The TS-SOCKET System must be set up prior to connection to a host PC. These steps are outline below. These steps assume that the g_ether module is unloaded (rmmod g_ether).

   1.) Create a mount point and then mount the first partition of SD card where
       the storage element exists.
      * mkdir /mnt/vfat; mount /dev/nbd1 /mnt/vfat

   2.) Install the g_file_storage driver with storage element details
      * modprobe g_file_storage file=/mnt/vfat/usb_storage_file

After following these steps for preparing the SBC storage element, plug the SBC into the host PC with an A to B USB Cable (ISB Cable). You will see the newly mounted volume and should be able to access it.

When you have completed using the device on the Linux or Windows System, you will need to eject volume using either umount on Linux, or "Safely Remove Hardware" on Windows and then unplug the USB cable.

After transferring data from a host PC to the SBC through the USB Mass Storage Device Linux gadget, you can access the data on the SBC by using the following steps.

   1.) Remove the g_file_storage driver allowing local access to storage element
      * rmmod g_file_storage

   2.) Create a mount point and then mount the storage element (assuming
       "/dev/nbd1" is still mounted to "/mnt/vfat" from steps above)
      * mkdir /mnt/usbdev
      * mount -t vfat -o loop=/dev/loop0,offset=4096 /mnt/vfat/usb_storage_file /mnt/usbdev/
NOTE:

The kernel should already have support for loop block devices. If not, you will need to insert the loop.ko module with modprobe or insmod.

You can now locally access /mnt/usbdev.

When finished with the device, or to allow access via the USB Device port, you must unmount the device using:

   umount /mnt/usbdev

Utilizing IP over USB (USB Ethernet)

The TS-SOCKET system must be set up prior to connection to a host PC. These steps are outline below.

   1.) Install the g_ether driver
      * modprobe g_ether

   2.) Assign an IP address to the new usb0 interface
      * ifconfig usb0 192.168.42.20
NOTE:

The IP address in the above example may be any valid IP address, but should typically not be on the same subnet as the Ethernet network on the SBC (if connected), or the host computer to which the SBC will be connected.


Connecting Linux Host to SBC via IP over USB

Most modern Linux distributions already have all of the required modules (e.g. usbnet.ko) and utilities installed, so the setup steps are minimal. Simply plug in the SBC after it has been prepared for IP over USB (see above) and observe that a new interface has been added named usb0 or similar (use dmesg | tail to verify). You can now assign an IP address to that interface with ifconfig (e.g. ifconfig usb0 192.168.42.21) and begin using the TCP/IP connection. To test your connection, use ping 192.168.42.20. You should also be able to login to the SBC using ssh, e.g. ssh root@192.168.42.40.

NOTE:

The IP address above may be any valid IP address, but must be in the same subnet as the IP address assigned to the SBC IP over USB connection above.


Connecting Windows XP Host to SBC via IP over USB

An additional driver interface configuration file called linux.inf is required for IP over USB connection to a Windows host. First, download this file onto the Windows PC and remember where you placed it. Next, connect the SBC and Windows PC with the A to B USB cable (ISB Cable). You should see the "Found New Hardware Wizard". Answer the prompts as follows:

  • Select "Include this location" in the search and choose the location of the driver you downloaded. Finish running the wizard.
  • Go to the Control Panel and open "Network Connections". Right-click the new connection (labeled "Linux USB Ethernet/RNDIS Gadget") and click "Rename". Rename it to something useful such as "USB Network".
  • Right-click on the newly labeled icon, and select properties.
  • Under the properties General tab, select the item labeled Internet Protocol (TCP/IP).
  • Select Use the following IP Address, and enter 192.168.42.21.
  • Click OK; Click OK.

You may now access the SBC via the TCP/IP connection. Use ping in the Command Prompt window to verify connectivity (e.g. ping 192.168.42.20).

NOTE:

Note that the IP address above may be any valid IP address, but must be in the same subnet as the IP address assigned to the SBC IP over USB connection above.


Connecting Windows Vista Host to SBC via IP over USB

Not yet supported, but currently in progress.


Connecting Windows 7 Host to SBC via IP over USB

Not yet supported, but currently in progress.



Chapter 5:   TS-SOCKET Common Pinouts

All off-board connections on any TS-SOCKET macrocontroller module go through the two high density 100 pin board to board connectors CN1 and CN2. The mating connectors and mechanical layout specification are available from the TS website. The tables below describe how each pin is used. Click on a pin name for more information. The orientation of the pins on a base board is as pictured below.

FPGA_JTAG_TMS 1 2 EXT_RESET#
FPGA_JTAG_TCK 3 C 4 EN_USB_5V
FPGA_JTAG_TDO 5 N 6 SDCARD_D2
FPGA_JTAG_TDI 7 1 8 SDCARD_D3
OFF_BD_RESET# 9 10 SDCARD_CMD
Reserved 11 12 SDCARD_3.3V
Reserved 13 C 14 SDCARD_CLK
POWER 15 N 16 POWER
POWER_FAIL# 17 1 18 SDCARD_D0
LCD_D08 19 20 SDCARD_D1
LCD_D09 21 22 SER_FLASH_WP#
LCD_D10 23 C 24 LCD_D0
LCD_D11 25 N 26 LCD_D1
LCD_D12 27 1 28 LCD_D2
POWER 29 30 LCD_D3
LCD_D13 31 32 LCD_D4
LCD_D14 33 C 34 LCD_D5
LCD_D15 35 N 36 V_BAT
LCD_D16 37 1 38 LCD_D6
LCD_D17 39 40 LCD_D7
LCD_D18 41 42 LCD_D21
LCD_D19 43 C 44 LCD_D22
LCD_D20 45 N 46 LCD_D23
POWER 47 1 48 EN_LCD_3.3V
LCD_CLK 49 50 Reserved
LCD_HSYNC 51 52 Reserved
LCD_VSYNC 53 C 54 Reserved
LCD_DE 55 N 56 Reserved
LCD_PWM 57 1 58 Reserved
Reserved 59 60 Reserved
Reserved 61 62 GND
DIO_14 63 C 64 MUX_AD_15
DIO_13 65 N 66 MUX_AD_14
DIO_12 67 1 68 MUX_AD_13
DIO_11 69 70 MUX_AD_12
DIO_10 71 72 MUX_AD_11
DIO_9 73 C 74 MUX_AD_10
GND 75 N 76 MUX_AD_9
DIO_8 77 1 78 MUX_AD_8
DIO_7 79 80 MUX_AD_7
DIO_6 81 82 MUX_AD_6
DIO_5 83 C 84 MUX_AD_5
DIO_4 85 N 86 MUX_AD_4
DIO_3 87 1 88 MUX_AD_3
DIO_2 89 90 MUX_AD_2
DIO_1 91 92 MUX_AD_1
DIO_0 93 C 94 MUX_AD_0
GND 95 N 96 BUS_ALE#
BUS_WAIT# 97 1 98 BUS_DIR
BUS_BHE# 99 100 BUS_CS#
 
ETH_RX+ 1 2 ETH_LEFT_LED
ETH_RX- 3 C 4 ETH_RIGHT_LED
ETH_CT 5 N 6 RED_LED#
ETH_TX+ 7 2 8 GREEN_LED#
ETH_TX- 9 10 Non-Standard
ETH_CT 11 12 Non-Standard
3.3V 13 C 14 SOC_GPIO
GND 15 N 16 ADC_0
Reserved 17 2 18 ADC_1
Reserved 19 20 ADC_2
GND 21 22 ADC_3
DEV_USB_M 23 C 24 ADC_VREF
DEV_USB_P 25 N 26 SOC_GPIO
1.0V_BU 27 2 28 TWI_CLK
HOST_USB_M 29 30 TWI_DAT
HOST_USB_P 31 32 Non-Standard
CPU_CORE 33 C 34 Non-Standard
USB_OTG_M 35 N 36 AUD_CLK
USB_OTG_P 37 2 38 AUD_FRM
3.3V 39 40 AUD_TXD
Reserved 41 42 AUD_RXD
Reserved 43 C 44 CPU_JTAG_TMS
GND 45 N 46 CPU_JTAG_TCK
Reserved 47 2 48 CPU_JTAG_TDI
Reserved 49 50 CPU_JTAG_TDO
GND 51 52 ONE_WIRE
Reserved 53 C 54 SYS_MCLK
Reserved 55 N 56 SOC_GPIO
1.8V 57 2 58 SOC_GPIO
Reserved 59 60 SOC_GPIO
Reserved 61 62 SOC_GPIO
V_TEST 63 C 64 SOC_GPIO
SPI_FRM 65 N 66 SOC_GPIO
SPI_MOSI 67 2 68 SOC_GPIO
SPI_MISO 69 70 SOC_GPIO
SPI_CLK 71 72 SOC_GPIO
GND 73 C 74 USB_OTG_ID
SOC_GPIO 75 N 76 USB_5V_LINE
SOC_GPIO 77 2 78 UART0_TXD
CPU_JTAG_VCC 79 80 UART0_RXD
SOC_GPIO 81 82 UART1_TXD
SOC_GPIO 83 C 84 UART1_RXD
SOC_GPIO 85 N 86 UART2_TXD
SOC_GPIO 87 2 88 UART2_RXD
SOC_GPIO 89 90 UART3_TXD
SOC_GPIO 91 92 UART3_RXD
DEBUG_TXD 93 C 94 UART4_TXD
DEBUG_RXD 95 N 96 UART4_RXD
CAN_TXD 97 2 98 UART5_TXD
CAN_RXD 99 100 UART5_RXD

1.8V

Maximum load on the 1.8V rail is 10mA.


3.3V

All macrocontrollers have a 3.3V power rail which is provided to the base board on this pin. This is meant to be useful as a Vcc input for any 3.3V logic ICs on the base board. The 3.3V rail can always supply at least 300mA to the base board. On the TS-4800 it is good for 500mA and on the TS-4700 it is good for 700mA.

NOTE:

The TS-4800 uses a 3.2V Vcc rail instead of 3.3V.


ADC Pins

On the TS-4200 only, these pins provide ADC inputs. On the TS-4800, they connect analog touchscreen readings to the PMIC, allowing for wake-on-touch functionality. On the TS-4500 and TS-4700, these are no-connects.


CAN Pins

CAN pins function as GPIO by default. On the TS-4200 they are always GPIO as CAN is not supported. On the TS-4500 and TS-4700, a CAN enabled bitstream must be loaded in order to use CAN, which reduces the number of functioning UARTS. On the TS-4800, CAN need only be enabled in software. The CAN controller on macrocontrollers is emulated in the FPGA by an improved CAN core with deep FIFOs.


Debug Console

These pins are dedicated to a development console. Standard base boards typically have a "Console enable" jumper that makes this console available for development.


CPU JTAG Bus

Most TS-SOCKET systems run Linux, in which case the CPU JTAG bus is not useful and should not be connected. For developers who want to use another operating system, or write "bare-metal" microcontroller-style code, this CPU JTAG debugging interface is made available. If you need to use this interface, please contact Technologic Systems to order a TS-8200 base board with the CPU JTAG connector.


DIO

DIO 0 through DIO 14 are 15 DIO lines that are guaranteed to be available on any macrocontroller. They are FPGA controlled. Many of these lines also offer other functionality via the FPGA, but the GPIO option is always supported. See Section 4.19 for more information.


EN_LCD_3.3V

This is a DIO used to switch power to an LCD display.


EN_USB_5V

This is a DIO used by convention to switch 5V USB power on base boards.


ETH Pins

ETH pins are 10/100 Ethernet pins which are connected directly to an Ethernet connector on the base board.

NOTE:

Ethernet Magnetics should be placed as close to CN2 as possible on the base board.


EXT_RESET#

EXT_RESET# is an input to the macrocontroller that can be used to reset the system. It is open drain.


FPGA JTAG Pins

The four FPGA JTAG pins should be left floating on most base boards. Using these pins to program the macrocontroller FPGA in the field is not supported.


GND

Base boards must connect all GND lines to a common ground.


I2S Audio

These pins can be connected to an I2S CODEC for an audio output channel.


LCD Interface

This interface presents a standard 24 bit LCD video output. This feature is supported on the TS-4800 and TS-4700.


LCD_PWM

A PWM signal on this line is used to control the brightness of the LCD backlight.


LED

All standard base boards connect these lines to LEDs for basic user feedback. See Appendix A: Register Maps for more information.


MUXBUS

All macrocontrollers support the MUXBUS. The MUXBUS is a flexible bus specified by Technologic Systems that can work in 8 bit or 16 bit mode. It can be connected on the base board to memory devices, programmable logic devices, or both. See Section 4.21 this section for more information.


Non-Standard

Pins labeled Non-Standard have different uses on different macrocontrollers. Designers of custom base boards that require compatibility with several macrocontrollers should not use these pins. Consult macrocontroller schematics for more information.


OFF_BD_RESET#

OFF_BD_RESET# is an output from the macrocontroller that automatically sends a reset signal when the unit powers up or reboots. It can be connected to any IC on the base board that requires a reset.


ONE_WIRE

On the TS-4800 and TS-4700, this pin provides a one wire interface. It is a no-connect on the TS-4500 and a GPIO on the TS-4200.


POWER

TS-SOCKET base boards must provide a regulated voltage between 4.5V and 5.5V on POWER pins. All other power rails required by the macrocontroller are provided by regulators on the macrocontroller.


POWER_FAIL#

This functionality is implemented on the TS-4200 only. This power fail input can be asserted by a base board to warn the TS-4200 that power is failing. This is used to protect the integrity of the NVRAM.


Reserved

Pins marked Reserved are reserved for future uses. For compatibility with future macrocontrollers, base boards should leave these pins not connected.


SD Card Interface

SD Card pins are in parallel with the microSD card slot on the macrocontroller. For systems that require a removable SD, MiniSD, or microSD card, the base board connects these lines to the SD connector and the on-board microSD slot cannot be used.


SER_FLASH_WP#

This functionality is implemented on the TS-4200 only. Asserting this signal (active low) eliminates any chance that the bootROM could be overwritten.


System on Chip (CPU) GPIO

Depending on the particular macrocontroller, pins in this category may or may not be connected to CPU GPIO. If not enough GPIO lines are available, they are either no-connects or FPGA GPIO. Base board designers that require GPIO should first use DIO_0 to DIO_14, which are always FPGA GPIO, followed by the CAN and UART pins (which are GPIO if CAN and UARTs are not needed) and then use these lines as a last resort. Study the schematic for the individual macrocontrollers you intend to use before designing around these lines. It is also very important to note that some of these lines use 1.8V logic on some models. This is specified on the schematic.

On the TS-4700, a camera interface is available on these lines. Other unique features may be available -- see the schematics for more information.


SPI Pins

These pins provide an SPI interface. See Section 4.20 for information on SPI software support.


TWI Pins

These pins provide a standard two-wire interface. Typically this bus also connects to an RTC and temperature sensor on the macrocontroller.


UART Pins

All macrocontrollers provide 6 UARTs for application usage. If UARTs are not needed, these pins can also function as GPIO. Base board designers should keep in mind that for software reasons, the set of UARTs used should be contiguous starting with UART0. For information on UART software, please see Section 4.17.


USB Pins

Some macrocontrollers provide two USB host ports and one USB device port. Others have one dedicated host and one USB OTG port.


V_BAT

A base board may include a 3.3V battery. If so, this line provides a battery voltage to the macrocontroller. This battery power is used to maintain the time in the RTC and, in the case of the TS-4200, maintain the integrity of the NVRAM.


V_TEST and CPU_CORE

CPU core voltages are provided for troubleshooting purposes only. On most base boards these should not be connected.


Appendix A:   FPGA Register Maps

This chapter describes FPGA hardware registers for each macrocontroller. One of the hardware cores in each macrocontroller FPGA is a system controller (syscon) block. The system controller contains registers for DIO, LEDs, the watchdog timer, hardware RNG, and more. Also provided here are hardware core register maps for SPI, XUARTs, and other functionalities. Note that in most cases, this information is provided only as a reference, since Technologic Systems provides fully functional drivers or driver utilities for this hardware.


A.1   TS-4200 FPGA Register Map

The TS-4200 provides access to the FPGA in an 8 bit region and a 16 bit region. The 8 bit base address is 0x10000000. The 16 bit base address is 0x30000000. All registers inside the TS-4200 FPGA are 16 bit registers and should be accessed via the 16 bit space. The 8 bit space is only needed for off-board 8 bit devices on the MUXBUS. To access hardware cores in the FPGA, add the offset in the table below to the base address.

Offset Usage
0x0 Syscon registers
0x080 ADC registers (for off-board ADC)
0x100 NAND flash registers
0x200 NVRAM control registers
0x400 1KB MUXBUS space
0x800 2KB Direct blockram access (For NVRAM transfers)

A.2   TS-4500 FPGA Register Map

Unlike other macrocontrollers, the TS-4500 accesses its FPGA through the sbus custom interface. Software developers must use the sbus API to access these registers. The sbus has 128 bytes of address space. Due to limited address space, some functionalities use memory windows.

SBUS Base Address Usage
0x00 SD card registers
0x10 NAND flash controller
0x18 general purpose memory window (opencore only)
0x20 XUART/XUART memwindow
0x40 SPI interface
0x50 CAN controller interface
0x60 Syscon registers

A.3   TS-4700 FPGA Register Map

The TS-4700 provides access to the FPGA in an 8 bit region and a 16 bit region. The 8 bit base address is 0x81000000. The 16 bit base address is 0x80000000. All registers inside the TS-4700 FPGA are 16 bit registers, but both 8 bit and 16 bit reads are possible. Use the one appropriate for the hardware core you are talking to. For example, the CAN core is 8 bit, the 8 bit MUXBUS space is 8 bit, and some 8 bit cycles are needed for the SPI core if you want to do 8 bit SPI transactions. To access hardware cores in the FPGA, add the offset in the table below to the base address.

Offset Usage
0x0000 16KB blockram access (for XUART buffer)
0x4000 Syscon registers
0x4400 ADC registers (for off-board ADC)
0x4800 SPI interface
0x4C00 CAN controller interface
0x4D00 2nd CAN controller (not implemented)
0x5000 Touchscreen registers
0x5400 XUART IO registers
0x8000 32KB MUXBUS space

A.4   TS-4800 FPGA Register Map

The TS-4800 provides access to the FPGA in an 8 bit region and a 16 bit region. The 16 bit base address is 0xb0000000. All registers inside the TS-4800 FPGA are 16 bit registers and should be accessed via the 16 bit space. The 8 bit space is only needed for off-board 8 bit devices on the MUXBUS. To access hardware cores in the FPGA, add the offset in the table below to the base address.

Offset Usage
0x00000 16KB blockram access (for XUART buffer)
0x10000 Syscon registers
0x11000 4KB MUXBUS space
0x12000 Touchscreen registers
0x13000 SPI Interface
0x14000 Motor Controller
0x15000 IRQ Controller
0x18000 XUART Control registers
0x1a000 CAN0 8-bit Window
0x1b000 CAN1 8-bit Window
0x1c000 XUART 32-bit Window

A.5   TS-4200 Syscon Registers

The registers listed below are all 16 bit registers and must be accessed with 16 bit reads and writes. This register block appears at base address 0x30000000.

Offset Bits Usage
0x0 15:0 Model ID: Reads 0x4200
0x2 15 Green LED (1 = on)
14 Red LED (1 = on)
13:8 Reserved
7:4 Board Sub-model: reads 0x0 on standard unit
3:0 FPGA revision
0x4 15:0 DIO direction for DIO 15(MSB)-0(LSB)
0x6 15:0 DIO output data for DIO 15(MSB)-0(LSB)
0x8 15:0 DIO input data for DIO 15(MSB)-0(LSB)
0xa 15:12  Reserved
11 UART0 9 bit mode (so that TX_EN works correctly)
10 1 = use DIO12 for uart0 TX_EN instead of DIO
9 1 = use 512Hz for WDT instead of 200Hz
8 1 = auto reboot when DIO 9 is driven low (enable reset button)
7:6 Scratch Register (used by bootrom)
5:4 Mode strapping inputs Mode2 and Mode1
3 Reserved
2 1 = Enable power to Ethernet PHY
1 1 = Enable power to SD card
0 Offboard reset signal (1 = reset)
0xc 15:0 32-bit 1MHz free running counter (16 LSBs)
0xe 15:0 32-bit 1MHz free running counter (16 MSBs)
0x10 15:0 Watchdog feed register
0x12 15:0 DIO direction for DIO 31(MSB) - 16(LSB)
0x14 15:0 DIO output data for DIO 31(MSB) - 16(LSB)
0x16 15:0 DIO input data for DIO 31(MSB) - 16(LSB)
0x18 15:0 Hardware RNG (16 LSB)
0x1a 15:0 Hardware RNG (16 MSB)
0x1c 15 Embedded FlashROM CLK
14:8 Embedded FlashROM Address
7:0 Embedded FlashROM Data Byte
0x1e 15:0 UART0 baud rate divisor (for UART0 TX_EN)
0x20 15:0 MUXBUS configuration register
0x22 15:0 IRQ register
0x24 15:0 IRQ mask register

The Watchdog feed register is write-only. Valid write values are:

Write ValueEffect
0 Feed watchdog for the next 0.5 sec
1 Feed watchdog for the next 2 sec
2 Feed watchdog for the next 16 sec
3 Disable watchdog

These watchdog timeout times assume that the 512Hz clock is being used as a watchdog clock. At power-up, the 200Hz clock is used, which means that the timeout times would actually be roughly 150% longer. The 512Hz clock signal is not turned on until a time is written to the RTC. The default linuxrc writes the RTC, which enables the 512Hz signal, and then switches the watchdog to the 512Hz signal.

The Linux kernel on the TS-4200 supports up to 16 IRQs from the FPGA. When it receives an IRQ signal, it uses the IRQ register to find out which IRQ is triggering. Currently only three IRQs are used. Off-board IRQs 5, 6, and 7 correspond to FPGA IRQs 0, 1, and 2, respectively. FPGA IRQs 3 to 15 are reserved for future uses. If the DIO pins are not being used as IRQs, they can be masked out by writing 0 to the corresponding bit in the IRQ mask register.

The born-on date of the unit and the MAC address can be read by from the FPGA FlashROM. See ts4200ctl source code for sample usage.


A.6   TS-4500 Syscon Registers

The register block listed below appears at base address 0x60 in sbus space.

Offset Bits Usage
0x0 15:0 Model ID reg - reads 0x4500 on the TS-4500
0x2 15 Green LED (1 = on)
14 Red LED (1 = on)
13 RTC SCL input
12 RTC SDA input
11 RTC SCL direction (1 = output)
10 RTC SDA direction (1 = output)
9 RTC SCL output
8 RTC SDA output
7:4 Board submodel - 0x0 on production TS-4500
3:0 FPGA revision
0x4 15:0 16 bits of random data changed every 1 second
0x6 15:12 DIO input for pins 40(MSB)-37(LSB)
11:8 DIO output for pins 40(MSB)-37(LSB)
7:4 DIO direction for pins 40(MSB)-37(LSB) (1 = output)
3 Lattice tagmem clock
2 Lattice tagmem serial-in
1 Lattice tagmem CSn
0 Lattice tagmem serial-out
0x8 15:0 DIO input for pins 36(MSB)-21(LSB)
0xa 15:0 DIO output for pins 36(MSB)-21(LSB)
0xc 15:0 DIO direction for pins 36(MSB)-21(LSB) (1 = output)
0xe 15:0 DIO input for pins 20(MSB)-5(LSB)
0x10 15:0 DIO output for pins 20(MSB)-5(LSB)
0x12 15:0 DIO direction for pins 20(MSB)-5(LSB) (1 = output)
0x14 15:0 Watchdog feed register (write only)
0x16 15:14 Reserved
13 1 = Use DIO 13 for UART 0 RXD
12 1 = Use DIO 13 for UART 4 RXD
11 CAN bus enable
10:6 SPI PLL phase (set by TS-BOOTROM)
5 Mode3 latched bootstrap bit
4 1 = auto reboot when DIO 9 is driven low (enable reset button)
3:2 Scratch Register (used by bootrom)
1 Mode2 latched bootstrap bit
0 Mode1 latched bootstrap bit
0x18 15 Reserved
14:10 DIO input for pins 4(MSB)-0(LSB)
9:5 DIO output for pins 4(MSB)-0(LSB)
4:0 DIO direction for pins 4(MSB)-0(LSB) (1 = output)
0x1a 15:8 DIO output for pins 48(MSB)-41(LSB)
7:0 DIO direction for pins 48(MSB)-41(LSB) (1 = output)
0x1c 15:12 Reserved
11:0 DIO input for pins 52(MSB)-41(LSB)
0x1e 15:6 Reserved
7:4 DIO output for pints 52(MSB)-49(LSB)
3:0 DIO direction for pins 52(MSB)-49(LSB) (1 = output)

The Watchdog feed register is write-only. Valid write values are:

Write ValueEffect
0 Feed watchdog for the next .338s (approx)
1 Feed watchdog for the next 2.706s (approx)
2 Feed watchdog for the next 10.824 (approx)
3 Disable watchdog

A.7   TS-4700 Syscon Registers

The registers listed below are all 16 bit registers and must be accessed with 16 bit reads and writes. This register block appears at base address 0x80004000.

Offset Bits Usage
0x00 15:0 Model ID: Reads 0x4700
0x02 15 Reset switch enable (Use DIO 9 input)
14 Enable touchscreen (override DIO 30-35)
13 Enable UART4 TXEN (override DIO 14)
12 Enable UART0 TXEN (override DIO 12)
11 Enable 12.5MHz base board clock (override DIO 3)
10 Enable SPI (override DIO 17-20)
9 Enable 2nd CAN (override DIO 10,11)
8 Enable CAN (override DIO 15,16)
7:6 Scratch Register (used by bootrom)
5:4 Mode2, Mode1
3:0 FPGA revision
0x04 15:0 External bus config register
0x06 15:0 Watchdog feed register
0x08 15:0 Free running 1MHz counter LSB
0x0a 15:0 Free running 1MHz counter MSB
0x0c 15:0 Hardware RNG LSB
0x0e 15:0 Hardware RNG MSB
0x10 15 Reserved
14:0 DIO group 1 output data
0x12 15:13 Reserved
12 Red LED (1 = on)
11 Green LED (1 = on)
10:0 DIO group 2 output data
0x14 15:0 DIO group 3 output data
0x16 15 Enable UART2 TXEN (override DIO 10)
14 Enable UART1 TXEN (override DIO 8)
13 Enable UART5 TXEN (override DIO 7)
12 Enable UART3 TXEN (override DIO 13)
11:0 DIO group 4 output data
0x18 15 Reserved
14:0 DIO group 1 data direction
0x1a 15:11 Reserved
10:0 DIO group 2 data direction
0x1c 15:0 DIO group 3 data direction
0x1e 15:12 Reserved
11:0 DIO group 4 data direction
0x20 15 Reserved
14:0 DIO group 1 input data
0x22 15:11 Reserved
10:0 DIO group 2 input data
0x24 15:0 DIO group 3 input data
0x26 15:12 Reserved
11:0 DIO group 4 input data
0x28 15:4 Reserved
3:0 TAG memory access
0x2a 15:0 Custom load ID register (reads 0 on standard load)
0x2c 15:6 Reserved for future IRQs
5 Offboard IRQ 7
4 Offboard IRQ 6
3 Offboard IRQ 5
2 CAN2 IRQ
1 CAN IRQ
0 XUART IRQ
0x2e 15:0 IRQ mask register: 1 disables the corresponding IRQ.
0x30 15:0 Edge Counter 0
0x32 15:0 Edge Counter 1

FPGA DIO pins on the TS-4700 are divided into four groups. Typically, many of these pins will be used for CAN, SPI, XUARTs, the MUXBUS, and various other pin-specific functions. Whether those functionalities override DIO is controlled by the enable bits in the Syscon. When they don't, the pins act as simple DIO, with an output data register, and input data register, and a data direction register. The input register always returns the actual state of the pin no matter how it is being used. The data direction register controls whether the pin is driven or high-impedance. (1 = output). The output data register is ignored for bits where the direction register is zero; otherwise, it controls the state of the pin.

The following table shows which register bits control which pins:

Register Bits TS-SOCKET Pins
Group 1 bits 14:9 CN1 odd pins 73(LSB) to 63(MSB)
Group 1 bits 8:0 CN1 odd pins 93(LSB) to 77(MSB)
Group 2 bits 10:6 CN1 pins 97(LSB), 99, 100, 98, 96(MSB) (MUXBUS control signals)
Group 2 bits 5:2 CN2 odd pins 65(LSB) to 71(MSB) (SPI pins)
Group 2 bits 1:0 CN2 pins 97(LSB) and 99(MSB) (CAN pins)
Group 3 bits 15:8 CN1 even pins 94(LSB) to 80(MSB) (MUXBUS 0 to 7)
Group 3 bits 7:0 CN1 even pins 78(LSB) to 64(MSB) (MUXBUS 8 to 15)
Group 4 bits 11:0 CN2 even pins 78(LSB) to 100(MSB) (UART pins)

The TS-4700 watchdog feed register usage is identical to that of the TS-4500. (See above)


A.8   TS-4800 Syscon Registers

The registers listed below are all 16 bit registers and must be accessed with 16 bit reads and writes. This register block appears at base address 0xb0010000.

Offset Bits Usage
0x0 15:0 Model ID register. Reads 0x4800 on TS-4800
0x2 15 Reset FPGA
14 Strap-Low signal (0 = low)
13 SD Power (1 = on)
12 Boot mode
13:8 Reserved
7:4 board submodel (RO) - 0x0 on production TS-4800
3:0 FPGA revision
0x4 15:0 32-bit 72MHz free running counter (16 LSBs)
0x6 15:0 32-bit 72MHz free running counter (16 MSBs)
0x8 15:0 32-bit 1MHz free running counter (16 LSBs)
0xa 15:0 32-bit 1MHz free running counter (16 MSBs)
0xc 15:0 16-bit random number
0xe 15:0 Watchdog feed register (write only)
0x10 15 Green LED (1 = on)
14 Red LED (1 = on)
13:8 Reserved
7 SPI enable (1 = on)
6 TOUCHSCREEN enable (1 = on)
5 XUART5 enable (1 = on)
4 XUART4 enable (1 = on)
3 XUART3 enable (1 = on)
2 XUART0 enable (1 = on)
1 CAN1 enable (1 = on)
0 CAN0 enable (1 = on)
0x12 15:0 External bus configuration register
0x14 15:4 Reserved
3 Lattice tagmem clock (RW)
2 Lattice tagmem serial-in (RW)
1 Lattice tagmem CSn (RW)
0 Lattice tagmem serial-out (RO)
0x16 15:11 Reserved
10:6 PLL phase (set by TS-BOOTROM) (RW)
5 Mode3 latched bootstrap bit (RO)
4 Reset switch enable (1 = auto reboot when dio_i[9] == 0) (RW)
3:2 Scratch Register (used by bootrom)
1 Mode2 latched bootstrap bit (RO)
0 Mode1 latched bootstrap bit (RO)
0x20 15:0 DIO input data for DIO 15(MSB)-0(LSB) (RO)
0x22 15:0 DIO output data for DIO 15(MSB)-0(LSB)
0x24 15:0 DIO direction for DIO 15(MSB)-0(LSB) (1 = output)
0x28 15:0 DIO input data for DIO 31(MSB)-16(LSB) (RO)
0x2a 15:0 DIO output data for DIO 31(MSB)-16(LSB)
0x2c 15:0 DIO direction for DIO 31(MSB)-16(LSB) (1 = output)
0x30 15:0 DIO input data for DIO 47(MSB)-32(LSB) (RO)
0x32 15:0 DIO output data for DIO 47(MSB)-32(LSB)
0x34 15:0 DIO direction for DIO 47(MSB)-32(LSB) (1 = output)
0x38 15:8 Reserved
7:0 DIO input data for DIO 55(MSB)-48(LSB) (RO)
0x3a 15:8 Reserved
7:0 DIO output data for DIO 55(MSB)-48(LSB)
0x3c 15:8 Reserved
7:0 DIO direction for DIO 55(MSB)-48(LSB) (1 = output)

The TS-4800 watchdog feed register usage is identical to that of the TS-4500. (See above)

The following table defines the mapping between DIO bits and connector pins on the TS-4800:

DIO Bits TS-SOCKET Pins
8:0 CN1 odd pins 93(LSB) to 77(MSB)
14:9 CN1 odd pins 73(LSB) to 63(MSB)
16:15 Reserved
20:17 CN2 pins 70(LSB), 64, 62, 54(MSB)
36:21 CN1 even pins 94(LSB) to 64(MSB) (MUXBUS 0 to 15)
41:37 CN1 pins 96(LSB), 98, 100, 99, 97(MSB) (MUXBUS control signals)
45:42 CN2 pins 69(LSB), 71, 65, 67(MSB) (SPI pins)
47:46 CN2 pins 99(LSB) and 97(MSB) (CAN pins)
49:48 CN2 pins 80(LSB) and 78(MSB) (UART0 pins)
55:50 CN2 pins 92(LSB), 90, 96, 94, 100, 98(MSB) (UART pins)

A.9   XUART Registers

The vast majority of TS-SOCKET application developers working with XUARTs should use the xuartctl driver utility. For DMX applications, dmxctl is also available. For developers with a need to customize these utilities, integrate UART communications tightly into another code base, write an XUART kernel driver, or use XUARTs with other operating systems besides Linux, this section is provided as a reference.

To use XUARTs, software must access control (IO) registers as well as an 8KB FPGA blockram buffer region. Actual UART data is read from and written to the buffer region. On the TS-4500, the 8KB RAM is accessed through a memory window at the end of the IO region. On the TS-4700 and TS-4800, the RAM region has its own directly mapped memory space. Note that in many cases, fewer than 8 XUARTs are enabled due to limited FPGA resources. The IO region memory map is as follows:

Offset Bits Usage
0x0 15:8 UART0 RCNT (read) / RIRQ (write)
7:0 UART0 TXPOS (read) / TXSTOP (write)
0x2 15:8 UART1 RCNT (read) / RIRQ (write)
7:0 UART1 TXPOS (read) / TXSTOP (write)
0x4 15:8 UART2 RCNT (read) / RIRQ (write)
7:0 UART2 TXPOS (read) / TXSTOP (write)
0x6 15:8 UART3 RCNT (read) / RIRQ (write)
7:0 UART3 TXPOS (read) / TXSTOP (write)
0x8 15:8 UART4 RCNT (read) / RIRQ (write)
7:0 UART4 TXPOS (read) / TXSTOP (write)
0xa 15:8 UART5 RCNT (read) / RIRQ (write)
7:0 UART5 TXPOS (read) / TXSTOP (write)
0xc 15:8 UART6 RCNT (read) / RIRQ (write)
7:0 UART6 TXPOS (read) / TXSTOP (write)
0xe 15:8 UART7 RCNT (read) / RIRQ (write)
7:0 UART7 TXPOS (read) / TXSTOP (write)
0x10 15:8 RXIRQ (1 = IRQ pending for corresponding UART)
7:0 TXIRQ (1 = IRQ pending for corresponding UART)
0x12 15:8 1 = RX is enabled for corresponding UART
7:0 1 = TX pending for corresponding UART
0x14 15:0 Next RX blockram address to be written
0x16 15:0 TX config/status (2 bits per channel)

RCNT signifies the current count of entries written to the RX FIFO for the particular UART. This counter will increment every time an entry is written into the RX ring buffer on behalf of this UART and wrap back to 0 on overflow. An interrupt will be flagged on a new received character when RCNT == RIRQ. By this mechanism, protocol request/response latency less than 1 bit time can be achieved by precisely coordinating an interrupt to be generated at end of packet should the packet size be known ahead of time. Due to possible internal synchronization issues, the RCNT cannot be written from the CPU, so even though its reset value is 0, that fact should not be counted on in driver software.

TXPOS is the position in the TX ring buffer of the next character to be sent. When TXPOS == TXSTOP the transmission is complete and the UART will be idle. To transmit characters, breaks, or timed idle periods, the UART TX ring should be loaded with data starting at the current TXPOS and TXSTOP should be updated to point one past the last entry. Similar to RCNT, TXPOS is not writable.

The IRQ signal output is set whenever any of the above bits are set. IRQ will continue to be asserted until all set bits are cleared. Writes will have no effect. To de-assert TX IRQs, respective TX/RX control channel register must be read. Bit 0 corresponds to UART channel #0.

A TX IRQ is set whenever a TX op is loaded in the TX shift register with the most-significant bit set (bit 15). By specifically picking which TX bytes will generate IRQs, IRQ load can be low while still ensuring the transmitter is kept busy and at 100% utilization with no inter-character idle gaps.

A RX IRQ is set either when RCNT == RIRQ as set in registers 0x0 - 0xe, or when a per-UART programmable idle threshold is exceeded. This threshold can be set to generate an IRQ after 1, 2, 4, or 8 bit times of idle allowing an IRQ to be generated only after a string of back-to-back characters has been received. Details on how this idle threshold is set are described below. All RX IRQ bits will be cleared on read of RX address (iobase + 0x14).

When RX is first enabled, the first RX entry may be an idle or break. The time as recorded will not have started from the moment the UART was enabled and should probably be thrown away.

The TX config/status register works as follows: Two bits are used for each UART. On a read, the LSB reads 1 if the TX channel is busy, and the MSB reads 1 if the CTS input is asserted. On a write, the meanings are:

Value Setting
0 TX suspended (TX idle)
1 TX suspended (TX break instead)
2 TX enabled
3 TX enabled with hardware CTS flow control

The blockram buffer memory map is laid out as follows:

Base Address Usage
0x0 RX ring buffer
0x1000 TX ring buffer #0
0x1200 TX ring buffer #1
0x1400 TX ring buffer #2
0x1600 TX ring buffer #3
0x1800 TX ring buffer #4
0x1a00 TX ring buffer #5
0x1c00 TX ring buffer #6
0x1e00 TX ring buffer #7

TX Opcodes

Each transmitter has a dedicated 256 entry ring buffer in an external memory. Each entry is 16 bits and contains not only bytes to be transmitted, but also opcodes for fixed length break/idle and commands to change UART parameters such as baud rate, idle threshold, and mode. TX memory starts at offset 0x1000 of the external UART memory and each ring buffer is laid out contiguously.

The format of TX opcodes follow:

Bits Usage
15:14 Reserved, should be zero.
13 sets TX IRQ at start of TX processing this entry
12:11 opcode type
10:0 opcode data
Opcode Meaning
00 transmit data character
01 transmit timed break
10 transmit timed idle
11 control opcode (updates internal UART regs)

Opcode '00' data bits 10-0 are right justified character data bits. Number of data bits can be 7-10 as configured below.

Opcode '01' and '10' data bits 9-0 represent the number of bit times the chosen line condition is set for (idle or break) until the next character. If bit 10 is set, the 10 bit number is left shifted by 6 to allow for longer periods than could be represented in a 10 bit counter. Two back to back break opcodes will have at least 2 bit times of idle between them.

Opcode '11' is for updating internal 16-bit UART registers. The 11 bit opcode data field is broken down into a 3 bit sub-op and a 8 bit data payload. The 3 bit sub-op represents the address of the internal register to update and is the most-significant 3 bits of the opcode data (bits 10-8). Since each register is 16 bits and there is only room for 8 bits of data, the upper 8 bits must be latched in a previous control opcode by writing to the sub-op field the reserved address of 7 (111). The internal registers are as follows:

Offset Bits Usage
0 15:0 baud prescalar - 16 bit counter to generate 8x baud freq
1 15:4 Unused (don't cares)
3:2 Idle threshold - sets RX irq after set idle time
1:0 Bits/character minus 7
6:2 15:0 Reserved
Idle Setting Idle Threshold
00 1 bit time
01 8 bit times
10 16 bit times
11 32 bit times

All traditional UART modes are possible with 7-10 bit character sizes. The UART does not have special provision for automatically appending/checking parity bits or multiple stop bits; instead these must be handled with software. A single start bit and single stop bit is assumed with each transmit word. Parity and multiple stop bits can be added easily in software with precomputed lookup tables.


RX Processing

The receiver uses 4 Kbytes arranged as a 2048 x 16-bit ring buffer. When a character, break, or period of idle exceeding the set idle threshold is received, an entry is written to the current address in the ring buffer and the current address is incremented. When the address reaches the end of the ring buffer, it rolls over back to 0. The format of each entry into the ring buffer is as follows:

Bits Meaning
15-13 UART# character received from
12-11 RX type
10-0 RX data
RX Type Meaning
00 character
01 break
10 idle
11 Invalid -- will never be written

When RX type is '00', the received character is present in data bits 10-0 left justified. The remaining LSB bits are random and should not be used.

When the RX type is '01' or '10' -- indicating a break condition or an extended period of idle was detected -- the remaining 11 least significant bits represent the length of the condition in bit times. However, if bit 10 is set, the actual 10 bit result should be left shifted by 6. A break of any length will be reported, but an idle RX entry will only be inserted into the ring buffer if it exceeds the programmed idle threshold from above. A break must first exceed the character time before being considered a break and the counter only starts once that happens, e.g. for an 8N1 (8 data bits, 1 start bit, 1 stop bit) 10 should be added to the counted result.

Since an RX type of '11' will never be written, software may choose to write this value to all data bytes as a way to know how much of the RX ring buffer has been updated since the last RX processing event. It is expected that RX processing not only be run in response to an RX interrupt, but also as part of a low speed timer interrupt. By knowing which UARTS are activated and at what baud rates and idle thresholds, worst case ring buffer overflow time can be computed.


A.10   SPI Registers

Offset Bits Usage
0x0 15 spi miso state
14 spi clk state
13:10 speed[3:0] (0- highest, 1- 1/2 speed, 2- 1/4, etc..)
9:8 LUN (0-3 representing the 4 CS# signals)
7 CS (1 = CS# is asserted)
6:1 Reserved
0 speed[4]
0x2 15:0 previous SPI read data from last write
0x4 15:0 Reserved
0x6 15:0 Reserved
0x8 15:0 SPI read/write with CS# to stay asserted
0xa 15:0 SPI pipelined read with CS# to stay asserted
0xc 15:0 SPI read/write with CS# to de-assert post-op
0xe 15:0 Reserved

The SPI CLK state register should be set when CS# is de-asserted. Value 0 makes SPI rising edge (CPOL=0), 1 is falling edge (CPOL=1). This only applies to speed >= 1. For speed == 0, SPI clock polarity/skew must be set from the PLL phase adjust registers in the syscon block.

The SPI bus SCLK frequency is informed by the speed setting. With a speed setting of 0, the global FPGA clock is used as the SPI SCLK. With a speed setting N>= 1, the SCLK frequency will be the global clock divided by 2N. The global clock is 75MHz on the TS-4500 and TS-4700, and 99MHz on the TS-4800. The TS-4200 does not use an FPGA SPI core.

The pipelined read register is for read bursts and will automatically start a subsequent SPI read upon completion of the requested SPI read. Reading from this register infers that another read will shortly follow and allows this SPI controller "a head start" on the next read for optimum read performance. This register should be accessed as long as there will be at least one more SPI read with CS# asserted to take place.


A.11   MCP3428 ADC Registers

Several standard TS-SOCKET base boards feature an MCP3428 ADC, including the TS-8100, TS-8160, and TS-8390. This is a low cost 16 bit ADC. Macrocontrollers include a hardware core to conveniently access this device. The standard base board circuit allows for two differential (1-2) channels with a range of -2.048V to +2.048V, and four singled ended (3-6) channels with a range of 0V to 10.24V. Please refer to a base board schematic for more details.

The ADC core register map is as follows:

Offset Bits Usage
0x0 15:8 Core ID register: reads 0xad.
7:6 Reserved
5:4 0 = Do not use an AN_SEL
1 = Use CN1 pin 77 for AN_SEL (TS-8100)
2 = Use CN1 pin 74 for AN_SEL (TS-8390)
3 = Reserved
3:2 0 = 240Hz, 12 bit resolution
1 = 60Hz, 14 bit resolution
2 = 15Hz, 16 bit resolution
3 = Reserved
1:0 0 = No gain
1 = 2x gain
2 = 4x gain
3 = 8x gain
0x2 15:6 Reserved
5:0 Channel mask
0x4 15:0 Channel 1 most recent conversion value
0x6 15:0 Channel 2 most recent conversion value
0x8 15:0 Channel 3 most recent conversion value
0xa 15:0 Channel 4 most recent conversion value
0xc 15:0 Channel 5 most recent conversion value
0xe 15:0 Channel 6 most recent conversion value

The channel mask register controls which channels are enabled. Bits 0-5 enable channels 1-6 respectively. If a given channel is not enabled, (enable bit == 0) it will not be sampled and its conversion value register will contain an obsolete and meaningless value. The more channels that are enabled, the lower the sampling speed on each channel.


A.12   Touchscreen Registers

The TS-4700 and TS-4800 can drive an LCD touchscreen. Some base boards, such as the TS-8390, have a touchscreen controller which is connected directly to the macrocontroller. These macrocontrollers have an FPGA touchscreen hardware core. This simple core consists of two read-only registers that can be read by software at any time.

Offset Bits Usage
0x0 15:1 X coordinate
0 pen down
0x2 15:1 Y coordinate
0 pen down

If the pendown bit is 1, the screen is being touched and the X and Y values are meaningful. If the pendown bit is 0, the screen is not being touched. This controller is for a resistive touchscreen, and assumes only one touch at a time. Touching the screen in two places at the same time cannot be detected.

The touchscreen will not work accurately without being calibrated. The TS-TPC-8390 will be calibrated at the factory, with calibration values stored in the FPGA TAG memory. The Linux driver will automatically use these calibration values.


A.13   TS-4200 NVRAM Registers

The TS-4200 features an 8KB non-volatile SRAM. If a voltage is supplied on V_BAT, the TS-4200 can shut down without losing SRAM data. To communicate with the SRAM, software must read and write the FPGA blockram region, and use NVRAM control registers to initiate block transfers between the FPGA blockram and the SRAM. The NVRAM control register map is as follows:

Offset Bits Usage
0x0 15:2 Reserved
1 power fail. 1 = further transfers are not permitted.
0 busy flag. Indicates transfer is occurring.
0x2 15:3 Reserved
2:1 NVRAM bank used for copy
0 1 = copy blockram to NVRAM | 0 = copy NVRAM to blockram
0x4 15:1 Reserved
0 transfer enable register
0x6 15:0 Power fail flag can be cleared by writing 0 to this register.

Data transfers between FPGA blockram and SRAM happen in 2KB blocks. The NVRAM consists of 8KB divided into 4 banks of 2KB. The correct software algorithm for a single transfer is as follows:

  • Make sure the busy flag and power fail flag are not set
  • Program the NVRAM bank register and direction register as desired
  • Set the transfer enable flag
  • Poll the busy flag until it goes high
  • Clear the transfer enable flag

The ts4200ctl utility source code includes a function that demonstrates the above algorithm.


A.14   TS-4500 Opencore Memory Window Registers

On the TS-4500, the sbus only provides 64 16 bit registers in the FPGA. Due to this space limitation, the open core version of the TS-4500 FPGA includes a general purpose memory window. This 16 bit core consisting of only 4 registers allows for 32, 16, or 8 bit wishbone cores with up to 27 bits of address space to be connected with minimal loss of performance.

For users of the default open core bitstream, the memory map is as follows:

Offset Usage
0x0 16 bit MUXBUS space
0x10000 8 bit MUXBUS space
0x20000 User core
0x21000 MCP3428 ADC core

The default user core consists of only one register, the MUXBUS config register.


Appendix B:   Further References


Generic TS-SOCKET Resources


TS-SOCKET Macrocontroller Resources


TS-SOCKET Base Board Resources


Appendix C:   Revision History

Date of Issue/Revision Revision Number Comments
Oct 30, 2010 1.0 Released as TS-SOCKET Manual (Preliminary)
Jun 22, 2011 2.0 Released as TS-SOCKET Manual
Feb 20, 2012 2.1 Revised Section A.3 to clear up 8 bit and 16 bit reads.

Contact us!

Search the KB