TS-75XX/TS-4500 Manual

Documentation from February-2010

Table of Contents

1 Introduction

• 1.1 About this Manual
• 1.2 Feedback and Update to this Manual
• 1.3 Limited Warranty
• 1.4 FCC Advisory Statement
• 1.5 Product Overview
• 1.6 Features
• 1.7 Benefits
• 1.7.1 Out-of-the-Box Productivity
• 1.7.2 Manufacturer (Technologic Systems) Benefits
• 1.8 Configuration Options
• 1.8.1 On-Board Options
• 1.8.2 External Accessories
• 1.9 Enclosures
• 1.9.1 TS-ENC750 Enclosure
• 1.9.2 TS-ENC752 Enclosure
• 1.9.3 TS-ENC753 Enclosure
• 1.10 Support
• 1.11 Supplemental Documentation

2 Getting Started

• 2.1 Installation Procedure
• 2.1.1 Handling the Board Safely
• 2.1.2 Setup and Installation Instructions
• 2.1.3 Setup Tools
• 2.1.4 Setup Procedure
• 2.1.5 Disconnecting AC Power
• 2.2 System Bootup
• 2.3 TS-7500/TS-7550/TS-7552/TS-7553/TS-4500 initrd
• 2.4 Debian Linux MicroSD Card
• 2.5 Updating/Recovering the onboard flash Linux kernel
• 2.6 Accessing Internal Registers from Linux Userspace
• 2.7 Default Low-level Bootup Process for the TS-7500
• 2.8 TS Boards Specific Linux Devices
• 2.8.1 Userspace Drivers
• 2.8.2 Network Block Driver and SD Card Partitioning
• 2.8.3 Battery Backed RTC
• 2.8.4 Watchdog
• 2.8.5 Low & High Speed GPIO
• 2.8.6 XUART Control from Userspace
• 2.8.7 CAN Control from Userspace
• 2.8.8 Random Number Generator

3 Interfaces

• 3.1 TS-7500/TS-7550 Interface
• 3.1.1 44-Pin Header
• 3.1.2 DIO
• 3.1.3 UART0 (Console UART)
• 3.1.4 I2C Bus
• 3.1.5 External Reset
• 3.1.6 Temperature Sensor
• 3.1.7 XUARTS
• 3.1.8 Power Supply
• 3.1.9 MicroSD Card
• 3.1.10 DB9 Connector on TS-752
• 3.2 TS-7552/TS-7553 Interface
• 3.3 TS-4500 Interface

4 SBUS SPI to FPGA Protocol

• 4.1 SBUS Burst Mode:
• 4.2 FPGA Verilog Implementation (spi_sbus.v)

5 FPGA SBUS Register Map

• 5.1 Top Level Address Decode
• 5.2 SD Card Core
• 5.3 XUART Register Map
• 5.4 XUART Memory Map
• 5.5 XUART TX Opcodes
• 5.6 XUART RX Processing
• 5.7 SPI Interface (For NOR Flash)
• 5.8 IO Window Core
• 5.9 Syscon Core

6 Hardware/Software Customization

• 6.1 Customizations by Technologic Systems
• 6.2 Custom FPGA Programming by Customer

7 Where to go for Additional Help

8 Environmental Specifications

9 Further References

Appendix A: Document History

Appendix B: Contact Technologic Systems

1 Introduction

1.1 About this Manual

This manual is intended to provide the user with an overview of the board and benefits, complete features specifications, and set up procedures. It contains important safety information as well.

1.2 Feedback and Update 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 (www.embeddedARM.com).

These include manuals, application notes, programming examples, and updated software and firmware. Check in periodically to see what's new!

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 Product Overview

The TS-7500 was released Jul. 2009 is a small embedded board with a CNS2132 250Mhz ARM9 CPU, Lattice XP2 5k FPGA, 64MB DDR SDRAM, and 4MByte SPI NOR flash chip.

The TS-7550 was released Dec. 2009 and is similar to the TS-7500, except that it has no SD card socket or 4MByte SPI NOR flash chip, but instead has a 256MByte XNAND onboard flash drive. Board dimensions and pinout are exactly the same as the TS-7500. The board is slightly more expensive than the TS-7500, but because an SD flash card is not necessary, the total system cost can be less.

The TS-7552 was released Jan. 2010. It is in a larger form factor than the TS-7550/TS-7500 but contains both XNAND and microSD socket, extra USB ports due to the inclusion of a onboard USB hub chip, an optional 802.11bg wifi radio, and a DB9 containing 2 RS232 serial ports, 1 RS485 port, and 1 CAN bus port. A metal enclosure with wifi antenna mount is also available for the TS-7552.

The TS-7553 was released Mar. 2010 and is a smaller form factor and cost reduced version of the TS-7552 without the extra USB ports and 8-28V switching power supply. It was designed to be mated with an inexpensive plastic enclosure and serve as a standalone general purpose embedded server.

The TS-4500 was released Feb. 2010 and is the macrocontroller module version of the Cavium ARM9 CPU/Lattice XP2 core. This board is low profile and about the size of a credit card, but includes no connectors/jacks except for the pair of 100 pin high density board to board connectors. Like the TS-7552/TS-7553, this module has both the 256MByte onboard flash and microSD socket.

1.6 Features

Common hardware features include:

• 250Mhz Cavium ARM9 CPU core (Faraday 526)
• 64MByte 16-bit wide DDR SDRAM running at 125Mhz
• 2 USB 2.0 High speed (480 Mb/s) Host ports
• 1 USB 2.0 slave port
• 1 TTL serial console port (16550) on CPU
• Hardware watchdog on FPGA
• Optional battery backed real time clock
• 10/100 Mbit on-CPU ethernet
• Low power (TS-7500 is 395mA @ 5V or 2.0 Watt)
• Fanless/heatsink-less operation up to 80C temperatures
• Customizable FPGA opencore (with Verilog sources)
• High speed SPI and I2C interfaces

TS-7500 specific hardware features:

• onboard microSD socket
• 4Mbyte onboard SPI flash preloaded with Linux
• rugged 40-pin .1" spacing offboard header
• 8 XUART TTL serial ports
• optional CAN controller (needs TS-752 carrier board)
• 33 3.3V FPGA-controlled GPIOs

TS-7550 specific hardware features:

• 256Mbyte onboard XNAND Drive preloaded with Debian Linux
• 8 XUART TTL serial ports
• rugged 40-pin .1" spacing offboard header
• optional CAN controller (needs TS-752 carrier board)
• 33 3.3V FPGA-controlled GPIOs

TS-7552 specific hardware features:

• 2 additional 480Mb/s USB ports (total 4)
• standard CAN controller on DB9 connector
• standard RS485 XUART serial port on DB9
• 2 RS232 XUART serial ports on DB9
• optional onboard 802.11bg radio
• 8-30V wide input voltage range
• onboard microSD socket
• 256Mbyte onboard XNAND Drive preloaded with Debian Linux
• 12 3.3V CPU/FPGA controlled GPIOs
• Designed to fit in a rugged extruded aluminum enclosure

TS-7553 specific hardware features:

• standard CAN controller on DB9 connector
• standard RS485 XUART serial port on DB9
• 2 RS232 XUART serial ports on DB9
• optional onboard 802.11bg radio
• onboard microSD socket
• 256Mbyte onboard XNAND Drive preloaded with Debian Linux
• 12 3.3V CPU/FPGA controlled GPIOs
• Designed to fit in a low cost plastic enclosure

TS-4500 specific hardware features:

• low profile credit card sized macrocontroller module
• onboard microSD socket
• 53 3.3V GPIOs on TS-socket interface
• 3-8 TTL XUART serial ports
• 1 CAN controller (requires offboard transceiver)
• 256Mbyte onboard XNAND Drive preloaded with Debian Linux

Software features include:

• Boots 2.6.24 Linux out-of-the-box in 2.65 seconds (to shell prompt)
• Flexible booting options (SD card, onboard SPI NOR flash, offboard SPI)
• SD card pre-installed with standard Debian Linux "Lenny" distribution
• Hardware specific functionality via both high level (command line/shell
script) and low level (C language userspace) mechanisms.
• Default software load has hook via USB flash dongle to hijack bootup
for custom production loading.

1.7 Benefits

1.7.1 Out-of-the-Box Productivity

Technologic Systems Linux products get you to your application quickly. Our Single Board Computers 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. The TS-75XX's 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.

1.7.2 Manufacturer (Technologic Systems) Benefits

• Long term availability and short lead-times
• Engineers on free technical support.
• Each board undergoes production tests and burn-in stress tests prior to shipment.
• Board customization is available with no minimum order.

1.8 Configuration Options

The TS-7500 can be configured for your application using the following available on-board options and external accessories:

1.8.1 On-Board Options

TS-7500 options include:

• TS-7500-64-4F: TS-7500 250MHz ARM9 SBC w/ 64MB RAM and 4MB Flash
• OP-BBRTC: Battery Backed Real Time Clock
• OP-ROHS-NC: Requires this board to be built 100% RoHS compliant
• KIT-7500: TS-7500 Development Kit with 2 GB SD Micro Card with USB adapter and ECLIPSE IDE (MSD-2GB-USB-7500), Enclosure and TS-752 main board, regulated DC power supply and all cables (SBC not included)
• MSD-2GB-USB-7500: TS-7500 bootable 2GB MicroSD card with USB reader interface including replication mechanism, out-of-the-box ECLIPSE IDE with debugging, ARM tool chain, Debian Linux filesystem, documentation and further binaries/utilities (included in the KIT-7500)

TS-7550 options include:

• TS-7550-64-256F: TS-7550 250MHz ARM9 SBC w/ 64MB RAM and 256MB XNAND Drive
• OP-BBRTC2: Battery Backed Real Time Clock (separate battery)
• OP-ROHS-NC: Requires this board to be built 100% RoHS compliant
• KIT-7550: TS-7550 Development Kit with development 2GB USB Flash Drive and ECLIPSE IDE (USB-FLASH-2GB), Enclosure and TS-752 main board, regulated DC power supply and all cables (SBC not included)
• 75USB-FLASH-2GB: 2GB USB Flash Drive with full ARM tool chain and Debian installed (included in the KIT-7550)

TS-7552 options include:

• TS-7552-64-256F: TS-7552 250MHz ARM9 SBC w/ 64MB RAM and 256MB XNAND Drive
• WIFI-G-MINIPCI: MiniPCI WIFI 802.11g Radio
• MSD-2GB-USB-7500: TS-7500 bootable 2GB MicroSD card with USB reader interface including replication mechanism, out-of-the-box ECLIPSE IDE with debugging, ARM tool chain, Debian Linux filesystem, documentation and further binaries/utilities

TS-7553 options include:

• TBA

TS-4500 options include:

• TBA

1.8.2 External Accessories

TS-7500 options include:

• CB-USB-AMBM: USB Cable w/ connectors USB-A Male to USB-B Male (also used as power supply cable) (included in the KIT-7500)
• CB7-05: Null modem cable with a DB9F at each end (included in the KIT-7500)
• WIFI-G-USB: USB 802.11g wireless network interface
• PS-5VDC-ENC750: International regulated 5VDC wall mounted Power Supply for the TS-ENC750 (incompatible with TS-7500) (included in the KIT-7500)
• TS-ENC750: Aluminum Enclosure with TS-752 main board for TS-7500 and Power-over-Ethernet (included in the KIT-7500)

TS-7550 options include:

• CB-USB-AMBM: USB Cable w/ connectors USB-A Male to USB-B Male (also used as power supply cable)
• CB7-05: Null modem cable with a DB9F at each end
• WIFI-G-USB: USB 802.11g wireless network interface
• PS-5VDC-ENC750: International regulated 5VDC wall mounted Power Supply for the TS-ENC750 (incompatible with TS-7550) (included in the KIT-7550)
• TS-ENC750: Aluminum Enclosure with TS-752 main board for TS-7500 and Power-over-Ethernet

TS-7552 options include:

• CB-USB-AMBM: USB Cable w/ connectors USB-A Male to USB-B Male (can also used as power supply cable)
• CB7-05: Null modem cable with a DB9F at each end
• TS-9448: Console Mini-Peripheral Board w/ 1 RC-DB9 cable
• PS-18VDC-BC: 18VDC Barrel Connector Power Supply

TS-7553 options include:

• TBA

TS-4500 options include:

• TBA

1.9 Enclosures

1.9.1 TS-ENC750 Enclosure

This rugged metal enclosure is made to house Technologic Systems Single Board Computers in the most hostile environments, protecting the internal electronics and increasing the general system reliability. In addition, it makes board utilization easier by bringing out a regulated power supply and computer's I/O interfaces through standard connectors.

The TS-ENC750 is a Hammond enclosure that houses the TS-7500 or TS-7550 and the TS-752 interface board. (included) The TS-752 demonstrates the flexibility of a Technologic Systems SoM by connecting its FPGA driven IO pins to relays, buffered digital inputs, buffered digital outputs, and RS-485 drivers. It also provides an RS-232 driver for the serial console. A TS-ENC750 with a TS-7500 or TS-7550 can provide a complete solution for many embedded applications. The system can be powered by:

• A regulated 5V through a screw terminal
• A USB device cable
• Power over Ethernet

The end cap for the Hammond enclosure brings out the following:

• Ethernet (POE ready)
• Dual USB slave
• USB device
• DB9 with 2 RS-232 and 1 RS-485
• Screw terminals for 3 relays
• Screw terminals for 8 digital inputs
• Screw terminals for 3 digital outputs
• Two LEDs

The 8 dry contact digital inputs are rated for up to 24V.

1.9.2 TS-ENC752 Enclosure

This rugged metal enclosure is made to house Technologic Systems Single Board Computers in the most hostile environments, protecting the internal electronics and increasing the general system reliability. In addition, it makes board utilization easier by bringing out a regulated power supply and computer's I/O interfaces through standard connectors.

More details of the TS-ENC753 Enclosure TBA

1.9.3 TS-ENC753 Enclosure

This inexpensive plastic enclosure is made to house Technologic Systems Single Board Computers and protect the internal electronics and increase the general system reliability. In addition, it makes board utilization easier by bringing out a regulated power supply and computer's I/O interfaces through standard connectors.

More details of the TS-ENC753 Enclosure TBA

1.10 Support

Technologic Systems provides:

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

1.11 Supplemental Documentation

A supplemental software guide is available which includes step-by-step tutorials, examples, and a more basic explanation of the TS-7500 geared towards users who are new to Technologic Systems SBCs called "TS-7500 Software Guide" located here:

TS-7500 Software Guide

There are many sections of this document that can be applied to TS-75XX products as well.

Additional documentation which is generic to all TS models can be found at http://www.embeddedarm.com including:

• Getting Started with TS-Linux
• Linux for ARM on TS-72XX
• TS-LCD-READY Getting Started Sheet

2 Getting Started

2.1 Installation Procedure

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

2.1.1 Handling the Board Safely

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

2.1.2 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

2.1.3 Setup Tools

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

• Small flat-blade screwdriver
• Small Phillips screwdriver

2.1.4 Setup Procedure

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

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

2.1.5 Disconnecting AC Power

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

2.2 System Bootup

All boards have Linux installed by default on onboard flash. Upon bootup, The board will boot within 2.65 seconds to a Linux prompt on UART #0 (/dev/ttyS0). The Cavium CPU's serial console is at TTL levels and to connect to a PC style serial port external RS232 level converters are necessary. For the TS-7500/TS-7550, this board is the TS-752 and the TS-7552 and TS-7553 it is the TS-9448 (the TS-9448 will hang off of the board, facing away from the CPU). The serial port will be set to 115200 baud, 8N1, with no flow control by default. The board will also answer telnet connections to IP address 192.168.0.50.

The default fastboot shell has available several standard Linux commands accommodated by the "busybox" program. Technologic Systems has used busybox 1.14.2 and has made no custom modifications to its source code. Upon bootup, you should see out of your serial port:

   >> TS-BOOTROM - built Aug 26 2009 13:35:32
   >> Copyright (c) 2009, Technologic Systems
   >> Booting from microSD card...
   .
   .
   .
   Finished booting in 2.65 seconds
   Type 'tshelp' for help
   #

At this point, if you type 'exit' from the serial shell, the TS-7500 will then attempt a full Debian Linux bootup from the SD card on partition #4.

Should you wish to automatically bypass the fastboot and proceed directly into starting the SD card version of Linux, you can do so with the following command issued to the fastboot shell:

   rm linuxrc; ln -sf /linuxrc-sdroot /linuxrc; save

To get back to the fastboot shell, you can do so by placing the file "/fastboot" in the root directory of the filesystem.

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 is available should you need help in implementing a specific feature.

Although it is easy to get a TS-7500 board into an unbootable state during development if you botch a modification, it is equally easy to use the TS-752 to recover the default startup. To do so, place the JP2 jumper on the TS-752 and reset the board. In approximately 3 seconds, the board will have fastbooted to the TS-752 flash and present a shell prompt. To recover the default initrd and linuxrc, enter the command "spisave", remove the JP2 jumper, and reboot back to a restored to factory default TS-7500. The procedure is identical on the TS-7550 except you use the "nandsave" command since the TS-7550 has no SPI flash onboard.

The TS-7552 and TS-7553 have several different boot methods and jumper configurations which may lead to confusion. To make it convenient, they have been laid out in this table:

2.3 TS-7500/TS-7550/TS-7552/TS-7553/TS-4500 initrd

The small default initrd is only 2Mbyte but there is space for approximately 800 Kbyte of additional user applications. The binaries on the initrd are dynamically linked against embedded Linux's "uclibc" library instead of the more common Linux C library "glibc". "uclibc" is a smaller version of the standard C library optimized for embedded systems and requires a different set of GCC compiler tools which are available in the VFAT partition of the default 2GB SD card/USB flash dongle optionally shipped with the boards.

The standard Linux environment is provided by busybox, and the compiled instance of busybox includes several internal commands listed below:

   # /bin/busybox --help
   BusyBox v1.14.2 (2009-08-07 14:43:48 MST) multi-call binary
   Copyright (C) 1998-2008 Erik Andersen, Rob Landley, Denys Vlasenko
   and others. Licensed under GPLv2.
   See source distribution for full notice.

   Usage: busybox [function] [arguments]...
      or: function [arguments]...

           BusyBox is a multi-call binary that combines many common Unix
           utilities into a single executable.  Most people will create a
           link to busybox for each function they wish to use and BusyBox
           will act like whatever it was invoked as!

   Currently defined functions:
           [, [[, ash, basename, cat, chgrp, chmod, chown, chroot, cmp, cp,
           cpio, cttyhack, cut, date, dd, depmod, devmem, df, dirname, dmesg,
           du, echo, egrep, env, expr, false, fdisk, fgrep, find, grep, gunzip,
           gzip, halt, head, hostname, hush, ifconfig, insmod, kill, killall,
           ln, login, ls, lsmod, md5sum, mdev, mkdir, mknod, modprobe, more,
           mount, msh, mv, netstat, ping, pivot_root, poweroff, printf, ps,
           pwd, reboot, rm, rmdir, rmmod, route, rx, sed, setconsole, setsid,
           sh, sleep, stty, sync, tail, tar, telnetd, test, tftp, top, tr,
           true, udhcpc, umount, unzip, usleep, uudecode, uuencode, vi, wget,
           xargs, yes, zcat

Also on the initrd are the TS specific applications: ts7500ctl, sdctl, spiflashctl, canctl, and xuartctl. ts7500ctl, ts7550ctl, ts7552ctl, ts7553ctl and ts4500ctl are all symlinks to the same executable with the same options described below. For purposes of this document, it will be referred to as just ts7500ctl.

	# ts7500ctl --help
	Usage: ts7500ctl [OPTION] ...
	Technologic Systems SBUS manipulation.

	General options:
	  -a, --address=ADR       SBUS address
	  -r, --peek16            16-bit SBUS read
	  -w, --poke16=VAL        16-bit SBUS write
	  -g, --getmac            Display ethernet MAC address
	  -s, --setmac=MAC        Set ethernet MAC address
	  -R, --reboot            Reboot the board
	  -t, --getrtc            Display RTC time/date
	  -S, --setrtc            Set RTC time/date from system time
	  -i, --info              Display board FPGA info
	  -e, --greenledon        Turn green LED on
	  -b, --greenledoff       Turn green LED off
	  -c, --redledon          Turn red LED on
	  -d, --redledoff         Turn red LED off
	  -D, --setdio=LVAL       Set DIO output to LVAL
	  -O, --setdiodir=LVAL    Set DIO direction to LVAL (1 - output)
	  -G, --getdio            Get DIO input
	  -Z, --getdioreg         Get DIO direction and output register values
	  -x, --random            Get 16-bit hardware random number
	  -W, --watchdog          Daemonize and set up /dev/watchdog
	  -A, --autofeed=SETTING  Daemonize and auto feed watchdog
	  -n, --setrng            Seed the kernel random number generator
	  -X, --resetswitchon     Enable reset switch
	  -Y, --resetswitchoff    Disable reset switch
	  -I, --extendedtempon    Enable extended temp (200Mhz CPU)
	  -C, --extendedtempoff   Disable extended temp (250Mhz CPU)
	  -l, --loadfpga=FILE     Load FPGA bitstream from FILE
	  -h, --help              This help

     
	# xuartctl --help
	Usage: xuartctl [OPTION] ...
		  xuartctl --port=PORT [OPTION] ... -- [COMMAND] [ARGS]
	Technologic Systems XUART core userspace driver utility.
	Example: xuartctl --server
		    xuartctl --port=192.168.0.50:7350 --speed=9600 -- /bin/sh -i
		    xuartctl --port=0 --test

	 -i, --irq=N             Use IRQ N as XUART IRQ (32)
	 -r, --regstart=ADD      Use ADD address as regstart (0x600ff100)
	 -m, --memstart=ADD      Use ADD address as memstart (0x60000000)
	 -s, --speed=BAUD        Use BAUD as default baudrate (115200)
	 -o, --mode=MODE         Use MODE as default mode (8n1)
	 -d, --server            Daemonize and run as server
	 -p, --port=PORT         Connect to local or remote XUART port
	 -t, --test              Run loopback and latency test
	 -h, --help              This help

When run as a server, default is to listen at TCP port numbers starting at 7350 with 1 port per XUART channel.

PORT option can be a either a number 0-7, or a HOSTNAME:TCPPORT for a remote TCP socket. When both --port and --server are used, a pseudo-tty is allocated and connected to the XUART channel and pseudo-tty processing continues in the background. When only --port is specified and no command is given, stdin and stdout are connected to the XUART channel, otherwise COMMAND is run as a sub-program with its stdin/stdout/stderr connected to the allocated pseudo-tty.

On the TS-7500/TS-7550/TS-7552/TS-7553/TS-4500 the IRQ the XUART is connected to is irq 29. However, leaving out the irq option causes xuartctl to poll the hardware at 100Hz which often gives lower CPU utilization. At 100Hz, the RX fifo depth is sufficient as long as total aggregate serial receive rate does not exceed approximately 200kbyte/sec. One serial port operating at max throughput 115200 baud, 8N1 is approximately 11kbyte/sec. It is still advantageous to use IRQs if your serial protocol uses a lot of short request/response style traffic where latency is more important than throughput.

   # spiflashctl --help
   Usage: spiflashctl [OPTION] ...
   Technologic Systems SPI flash manipulation.

   General options:
     -R, --read=N            Read N blocks to stdout
     -W, --write=N           Write N blocks
     -x, --writeset=BYTE     Write BYTE as value (default 0)
     -i, --writeimg=FILE     Use FILE as file to write
     -t, --writetest         Run write speed test
     -r, --readtest          Run read speed test
     -n, --random=SEED       Do random seeks for tests
     -z, --blocksize=SZ      Use SZ bytes each read/write call
     -k, --seek=SECTOR       Seek to 512b sector number SECTOR
     -V, --verify            Verify reads and writes
     -e, --erase             Erase entire device
     -d, --nbdserver=NBDSPEC Run NBD userspace block driver server
     -l, --lun=N             Use chip number N
     -h, --help              This help

When running a NBD server, NBDSPEC is a comma separated list of devices and partitions for the NBD servers starting at port 7525. e.g. "lun0:part1,lun1:disc" corresponds to 2 NBD servers, one at port 7525 serving the first partition of chip #0, and the other at TCP port 7526 serving the whole disc device of chip #1.

   # sdctl --help
   Usage: sdctl [OPTION] ...
   Technologic Systems SD core manipulation.

   General options:
     -R, --read=N            Read N blocks to stdout
     -W, --write=N           Write N blocks
     -x, --writeset=BYTE     Write BYTE as value (default 0)
     -i, --writeimg=FILE     Use FILE as file to write
     -t, --writetest         Run write speed test
     -r, --readtest          Run read speed test
     -n, --random=SEED       Do random seeks for tests
     -o, --noparking         Disable write parking optimization
     -z, --blocksize=SZ      Use SZ bytes each read/write call
     -E, --erasehint=SZ      Use SZ bytes as erase hint
     -b, --sdboottoken=TOK   Use TOK as the boot token (to quicken init)
     -a, --address=ADD       Use ADD address instead of 0x13000000
     -k, --seek=SECTOR       Seek to 512b sector number SECTOR
     -l, --lun=N             Use N as numbered card slot (default 0)
     -S, --scanluns          Scan all LUNs for cards
     -m, --nodma             Don't use DMA
     -d, --nbdserver=NBDSPEC Run NBD userspace block driver server
     -h, --help              This help

   Security/SD lock options:
     -p, --password=PASS     Use PASS as password
     -c, --clear             Remove password lock
     -s, --set               Set password lock
     -u, --unlock            Unlock temporarily
     -e, --erase             Erase entire device (clears password)
     -w, --wprot             Enable permanent write protect

When running a NBD server, NBDSPEC is a comma separated list of devices and partitions for the NBD servers starting at port 7500. e.g. "lun0:part1,lun1:disc" corresponds to 2 NBD servers, one at port 7500 serving the first partition of SD lun 0, and the other at TCP port 7501 serving the whole disc device of SD lun #1.

   # canctl --help
   Usage: canctl [OPTION] ...
   Technologic Systems CAN controller manipulation.
   Example: canctl --txid=0x347 --txdat 0x12:0x34:0x56
           canctl --server --baud 125000
           canctl --port 192.168.0.50:7552 --txid 0x1 --txdat 1:2:3:4:5:6:7:8

   General options:
    -a, --address=ADR       CAN register address
    -b, --baud=BAUD         CAN baud rate (7500 to 1000000)
    -r, --peek8             CAN register read
    -w, --poke8=VAL         CAN register write
    -t, --txid=ID           CAN TX packet ID
    -d, --txdat=DAT         TX packet with data DAT
    -s, --server            Daemonize and run as server
    -p, --port=host<:port>  Talk to canctl server
    -R, --txrtr             TX RTR packet
    -D, --dump              Receive and print all CAN packets
    -0, --btr0=BTR0         SJA1000 BTR0 bus timing reg val
    -1, --btr1=BTR1         SJA1000 BTR1 bus timing reg val
    -x, --txtest            Send TX test pattern
    -y, --rxtest            Do RX test
    -h, --help              This help

When running a canctl server, the TCP port used is 7552.

Since this CAN controller is so new, the Lincan project has not yet written in support for the TS-7552 in their source tree. However, we do have documentation and sample code which allows sending/receiving of CAN packets from userspace applications without the necessity of Lincan kernel support. This sample code includes network CAN service and can be automatically started on TS-7552 bootup which makes the writing of CAN enabled applications even simpler and furthermore allows for the possibility of development in languages other than C (Java, Python, etc..) and on systems other than the local Linux SBC (Linux/x86, Windows, etc..)

The primary CAN routines used by the sample code are can_tx_local() and can_rx_local(); these both take a pointer to C structure "canmsg" and either send or receive a packet using that buffer.

The same structure is used to transmit and receive CAN data across the network; this uses can_tx_remote() and can_rx_remote(). By defining "REMOTE_ONLY" (e.g. by passing -DREMOTE_ONLY to the compiler when compiling the source code) the code can be compiled for any operating system such as Linux which provides the required OS functions for talking to (Berkley style) sockets. When compiled this way the program runs only as a client, talking to any "CAN server" via TCP/IP. Multiple clients can connect to a single server; each client can receive all packets from CAN, and can send packets to CAN. (Adding support to receive packets sent to CAN is possible as well but is currently unimplemented - see FLAG_LOCAL.)

This structure is defined as follows:

   UINT8    flags:
            FLAG_CONTROL: control information present
            FLAG_LOCAL: message originates from this node (unused)
            FLAG_EXT_ID: message has extended ID
            FLAG_RTR: remote transmission request (RTR)
            FLAG_ERROR_WARNING: CAN error warning received
            FLAG_RTR: CAN data overrun received
            FLAG_ERROR_PASSIVE: CAN error passive received
            FLAG_BUS_ERROR: CAN bus error received
            FLAG_CMD_RXEN: enable remote reception of packets (only if FLAG_CONTROL set)
   UINT32   id
   UINT32   timestamp in seconds
   UINT32   timestamp in microseconds
   UINT8    bytes
   UINT8[8] data

In contrast to the Lincan API, the above structure allows for error conditions to be signaled to the application through the flags. It is also possible to perform control operations across the network. This is accomplished by setting the FLAG_CONTROL flag in the packet. When this flag is set, the meaning of other parts of the structure changes. Specifically, the other flags and the id, bytes, and data fields all have new, command specific meanings and should not be interpreted as command data.

When FLAG_CONTROL is set, the "bytes" field becomes a "command identifier", and the data field meaning contains arguments to the specific command. Currently one command is defined:

   command=0: set acceptance filter

The data field is redefined as follows:

   UINT32 match_id
   UINT32 match_mask

If the FLAG_CMD_RXEN bit is cleared, then no packets received from CAN will be sent to the client. It is important to clear this bit if your client program does not read the socket, otherwise the RecvQ will fill up and the server will block!

If the FLAG_CMD_RXEN bit is set, then the match_id and match_mask fields are used to determine which packets received from CAN will be sent to the client. All bits in match_id must match the CAN ID unless the corresponding bit in match_mask is cleared, in which case that particular bit will be ignored. This is designed to match the way Lincan does acceptance filtering.

There are several shell functions defined in /ts7500.subr for your convenience that utilize the above TS specific utilities. These are automatically sourced into the initrd's startup interactive shell and can be included in custom shell scripts by inclusion of the line ". /ts7500.subr" at the top of script.

	save - Saves INITRD modifications back to the boot medium
	setdiopin  <1,0,Z> - Changes DIO header pin state to 1, 0, or tristate
	getdiopin  - Returns DIO header pin input state
	setrelay <3-bit-value> - Turns TS-752 relays on or off (0x7 - all on)
	setout <3-bit-value> - Sets TS-752 digital outputs
	getin - Returns 8-bit value of TS-752 inputs
	gettemp - Returns TS-752 temperature sensor temp in Celsius
	sbctest - Runs internal TS production tests

Although Technologic Systems can load the flash with customer supplied software from the factory, it is often more convenient to have a local production process for installing or updating the files and programs that make your product unique. The default software installation enables this by providing a hook to allow customer code to "hijack" the normal fast-boot bootup process. The default linuxrc looks for a script "/tsinit" on the USB mass storage device (USB thumb-drive, or USB hard drive) connected to either USB slot. If this script exists, it is then run automatically as the Linux "root" user-ID. A sample /tsinit script that copies a program "myprogram" to onboard flash, and then changes the default bootup to the SD card follows:

   #!/bin/sh

   ln -sf /linuxrc-sdroot /linuxrc
   cp /mnt/usbdev/myprogram /bin
   save

While the "tsinit" script is run, the red LED will be on. After it is complete, the red LED will go off. A customer could mass-update many hundred TS-7500's easily by using a USB flash dongle with a custom "tsinit" and data files and applying power with the USB dongle on, wait for the LED to go off, then proceed to the next board. The "tsinit" script will begin to execute approximately 3 seconds after power-on.

2.4 Debian Linux MicroSD Card

The typical way of doing Linux development on the TS boards is actually on the board itself. Since the ARM9 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 boards 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 integrators 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 SD 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. More information on using and configuring Debian Linux can be found at http://www.debian.org.

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/ to allow cross-compiling on Windows/cygwin or a Linux/i386 PC on the http://www.embeddedARM.com website.

Out of the box, the TS-7500/TS-7550/TS-7552/TS-7553/TS-4500 does not offer any support for Java developers. In order to provide Java development support, Technologic Systems has made a Debian Etch distribution complete with Java development tools available for download on the TS-7500 FTP Repository or by clicking on this direct link.

Once downloaded, the distribution can then be un-archived to the 4th partition of the MicroSD card.

Also provided in the devkit MicroSD card image is a Windows PC installation of Eclipse preconfigured for TS-7500 cross development.

2.5 Updating/Recovering the Onboard Flash Linux Kernel

Although usually not necessary, customers wanting to build and install their own kernels can do so from the fastboot environment by using NFS and the TS provided utilities "spiflashctl" or "nandctl". To mount an NFS filesystem from the fastboot shell, type:

	mount 192.168.0.1:/tsarm-nfsroot /mnt/root

You may have to change the server IP and server mount point to whats appropriate on your network. The default IP address is 192.168.0.50, but this could be changed with the command:

	ifconfig eth0 

Then, assuming /mnt/root/zImage is your new kernel, if the board is a TS-7500 with onboard SPI NOR flash issue the command:

	spiflashctl -W 4095 -k part1 -z 512 -i /mnt/root/zImage

Or, if the board is a TS-7550, TS-7552, or TS-4500 with onboard XNAND drive instead, issue the command:

	nandctl -X -W 4095 -k part1 -z 512 -i /mnt/root/zImage

This copies the zImage kernel binary to the first partition of the onboard SPI NOR or XNAND drive. Keep in mind the maximum size of kernel in the default partition layout is 2096640 bytes. Uncompressed kernels will always boot faster on the Cavium CPU. The default flash load makes use of an uncompressed kernel and a compressed .tar.gz of USB modules that is extracted to a tmpfs during bootup, loaded, and then unmounted only if a direct test of USB registers implies there may be something connected to a USB port.

2.6 Accessing Internal Registers from Linux Userspace

Linux applications run in a protected and separate environment where they can do no damage to either the kernel or other applications running simultaneously. This protected environment does not allow arbitrary manipulation of hardware registers by default. Applications may be allowed temporary access through memory space windows granted by the mmap() system call applied to the /dev/mem device node.

The FPGA internal registers are accessed via SPI through a TS specific register read/write protocol called "SBUS". This provides 128 bytes of registers where the SD card, SPI flash interface, DIO, and UART channels are implemented. Accessing the SBUS registers from within a C application is most easily accomplished by using the TS provided C routines in the "sbus.c" and "sbus.h" Linux source files. These routines handle the details of manipulating the Cavium CPU SPI interface and SBUS protocol and can do it from Linux userspace. This API consists of the following 5 functions:

	void sbuslock(void);
	void sbusunlock(void);
	void sbuspreempt(void);
	unsigned short sbus_peek16(unsigned int address);
	void sbus_poke16(unsigned int address, unsigned short value);

Here is an example of a userspace application toggling the red LED register bit at address 0x62, bit 14.

   #include "sbus.h"

   void main(void) {
     sbuslock();
     sbus_poke16(0x62, sbus_peek16(0x62) ^ 0x4000);
     sbusunlock();
   }

Here is an example of a userspace application which controls and reads the DIO pins of the TS-752. This program can also be found on the FTP site located here: ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/samples/dio.c

 #include "sbus.h"
#include <assert.h>
#include <string.h>
#include <stdio.h>

#define DIO_Z 2

/*******************************************************************************
* Main: accept input from the command line and act accordingly.
*******************************************************************************/
int main(int argc, char **argv)
{
   int pin;
   int val;
   int returnedValue;
         
   // Check for invalid command line arguments
   if ((argc > 4) | (argc < 3))
   {
       printf("Usage: %s <get|set> <pin#> <set_value (0|1|2)>\n", argv[0]);
       return 1;
   }
   
   // We only want to get val if there are more than 3 command line arguments
   if (argc == 3)
      pin = strtoul(argv[2], NULL, 0);
   else
   {
      pin = strtoul(argv[2], NULL, 0);
      val = strtoul(argv[3], NULL, 0);
   }
   
   // If anything other than pins 5 through 40, fail program
   assert(pin <= 40 && pin >= 5);

   // Parse through the command line arguments, check for valid inputs, and exec
   if (!(strcmp(argv[1], "get")) && (argc == 3))
   {
      sbuslock();
      returnedValue = getdiopin(pin);
      sbusunlock();
      
      printf("pin#%d = %d \n", pin, returnedValue);
   }
   else if(!(strcmp(argv[1], "set")) && (argc == 4) && (val <= 2))
   {
      sbuslock();
      setdiopin(pin, val);
      sbusunlock();
      
      printf("pin#%d set to %d\n", pin, val);
   }   
   else
   {
      printf("Usage: %s <get|set> <pin#> <set_value (0|1|2)>\n", argv[0]);
      return 1;
   }
   return 0;
}

Other examples can be found on the TS-7500 FTP Repository here:

ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/samples/

Since SBUS reads/writes are C routines and not atomic like the CPU load/store opcodes, it is important to implement proper locking/unlocking of the SBUS. The actual implementation of sbuslock()/sbusunlock() uses SysV IPC semaphores to handle userspace synchronization. There is also an API call sbuspreempt() to allow a potential preemption point if another application (such as the watchdog feeder, or XUART daemon) wishes to access the SBUS. It is important to not take exclusive ownership of the SBUS for longer than the watchdog feed interval (by default 10 seconds) otherwise the board will reboot.

Also, it is advisable to not hold the sbuslock during blocking filesystem IO. If the filesystem is on the SD card, it is possible to deadlock the system if the application blocks in a filesystem related syscall and the kernel wakes up the sdctl NBD server process which will also block waiting for the SBUS to be unlocked to access the SD card registers. If this happens and the watchdog is armed, it will eventually cause a system watchdog reboot.

2.7 Default Low-level Bootup Process for the TS-7500

The processor first boots up by running the 8Kbyte TS-BOOTROM stored in the initial configuration of the Lattice XP2 FPGA. TS-BOOTROM sets up DRAM timing, PLLs, and other low-level hardware initialization requirements. After printing the initial bootup message to the serial console, it reads the status of the boot jumpers to determine which of the bootup medium to boot from.

	Jumpers            Mode1 Mode2   Boot mode
	JP1 off, JP2 off   1     1       onboard flash, if flash uninitialized, 
		                             falls back to SD
	JP1 on, JP2 off    1     0       MicroSD card
	JP1 off, JP2 on    0     1       offboard (TS-752 or TS-9448) SPI flash
	JP1 on, JP2 on     0     0       reserved

The first 512 byte sector of the selected bootup medium is loaded into address 0x4000 in SDRAM. The last two bytes of this sector should contain the values 0x55, 0xaa, respectively to be considered valid. The next 128 bytes from 0x4200 are zeroed and then the CPU is jumped to 0x4000. The following ARM CPU registers are set up:

   r0 - pointer to bootup medium read(unsigned int, char *, int) function.
   r1 - pointer serial console puts(char *) function. 
   r2 - pointer to CPU clock scale(void) function.

The read() function takes as arguments the sector number, pointer to memory buffer, and number of sectors to read, respectively.

By default, whats contained in sector 0 of the SPI/SD flash is a DOS-style partition table at offset 446 and a 446 byte Linux-specific kernel bootloader at offset 0. This mini-bootloader contains code to parse the partition table looking for 2 partitions marked with partition ID '0xda'. It uses the start sector and size parameters of the partition table to load the first partition (Linux kernel) at offset 0x8000 and the second partition (if it exists) at 0x1000000 (Linux initrd). Next, it composes up the necessary pre-boot ATAG data structures required by Linux kernels and jumps to address 0x8000 at which point the Linux kernel takes over.

2.8 TS Boards Specific Linux Devices

2.8.1 Userspace Drivers

The TS kernel is built from the same 2.6.24 Linux sources Cavium Networks has tested and used on their CPU evaluation boards. There are no Technologic Systems specific drivers or kernel support implemented. Instead, there has been userspace driver support implemented for the SPI NOR flash, MicroSD cards, XNAND drive, battery-backed real-time clock, XUART serial port channels, watchdog, and GPIO pins. This allows easy migration to newer 2.6 kernels when either Cavium or the mainline Linux kernel community creates them. In the past, constant Linux-internal API redesign required rewriting and revisiting custom drivers with each new kernel revision, in effect locking customers in to whatever kernel version was released and tested during initial product release. Being free to update to newer kernels in the future allows easier support of the new USB devices as those drivers tend to only be developed for the newest kernel sources.

2.8.2 Network Block Driver and SD Card Partitioning

The SPI flash, XNAND drive and SD card can be plugged into Linux's block driver subsystem via the kernel to userspace gateway driver "NBD". NBD stands for Network Block Driver and can actually be used to export the SD/XNAND/SPI flash over the network to another Linux machine, but the way the startup scripts use the mechanism by default is to connect the SD flash via localhost to device nodes /dev/nbdX where X is the number referring to the actual NBD instance. The TS provided utilities "sdctl", "spiflashctl", and "nandctl" have --nbdserver options specially enabling the NBD style attachments to the internal Linux block layer. The default INITRD linuxrc startup script auto attached /dev/nbd0 through /dev/nbd4 as follows:

	/dev/nbd0 - whole disk device of microSD card
	/dev/nbd1 - 1st partition of SD card (Windows VFAT filesystem on devkit card)
	/dev/nbd2 - 2nd partition of SD card (kernel partition on devkit card)
	/dev/nbd3 - 3rd partition of SD card (EXT2 initrd partition on devkit card)
	/dev/nbd4 - 4th partition of SD card (Debian EXT3 filesystem on devkit card)

These device associations are set up in the linuxrc with the following shell commands:

	sdctl -z 65536 \
	  --nbdserver lun0:disc,lun0:part1,lun0:part2,lun0:part3,lun0:part4
	nbd-client 127.0.0.1 7500 /dev/nbd0
	nbd-client 127.0.0.1 7501 /dev/nbd1
	nbd-client 127.0.0.1 7502 /dev/nbd2
	nbd-client 127.0.0.1 7503 /dev/nbd3
	nbd-client 127.0.0.1 7504 /dev/nbd4

If the board has onboard XNAND drive as well as a microSD socket, it will occupy NBD devices 0-4 and the SD devices will be on 5-9.

	/dev/nbd0 - whole disk device of XNAND drive
	/dev/nbd1 - 1st partition (kernel partition)
	/dev/nbd2 - 2nd partition (EXT2 initrd)
	/dev/nbd3 - 3rd partition (252MByte mini Debian EXT3 filesystem)
	/dev/nbd4 - 4th partition (unused)

The XNAND NBD startup in the linuxrc uses the following lines:

	nandctl -X -z 131072 \
	  --nbdserver lun0:disc,lun0:part1,lun0:part2,lun0:part3,lu
	nbd-client 127.0.0.1 7525 /dev/nbd0
	nbd-client 127.0.0.1 7526 /dev/nbd1
	nbd-client 127.0.0.1 7527 /dev/nbd2
	nbd-client 127.0.0.1 7528 /dev/nbd3
	nbd-client 127.0.0.1 7529 /dev/nbd4

Although it is possible, the 4Mbyte SPI flash chips on the TS-7500 and the TS-752/TS-9448 recovery boards are not mounted via NBD in the default linuxrc startup scripts.

One common occurrence is the need to mount the microSD card when booted from XNAND (or visa versa). This can be done by using the following commands:

   # Mount microSD card (fourth partition, Debian)
   mkdir /mnt/sd4; mount /dev/nbd9 /mnt/sd4
   # Mount XNAND flash (third partition, Debian)
   mkdir /mnt/xnand3; mount /dev/nbd3 /mnt/xnand3

2.8.3 Battery Backed RTC

The battery-backed real time clock is set or read in the linuxrc bootup script by the ts7500ctl utility. It is only necessary to read the RTC once per bootup to initialize the Linux time of day. This is done with the command "ts7500ctl --getrtc". To set the RTC time, you simply set the Linux time of day (with e.g. the "date" utility) and then run ts7500ctl --setrtc. RTC's are already set before shipment to atomic UTC time and should hold time within 15 PPM while at room temperature. Be careful when handling board with a battery inserted-- the battery holder leads are through-hole and should you set the board on something conductive even for a millisecond, the RTC will loose its track of time and need to be reset.

2.8.4 Watchdog

The watchdog is also manipulated via the ts7500ctl utility. The default INITRD linuxrc autofeeds the watchdog by daemonizing and feeding it in the background via userspace. It can be armed in 3 modes (0 - .4s, 1- 2.7s, 2 - 10.8s). It can be either auto-fed from a background process that continually feeds the watchdog while running (--autofeed option), or via a /dev/watchdog UNIX named pipe which receives single ASCII characters which are written to feed it from another application: '0' - feed for another .4s, '1' - feed for another 2.7s, '2' - feed for another 10.8s, or '3' - disable watchdog.

2.8.5 Low & High Speed GPIO

Low-speed GPIO and LED manipulation can be done via the ts7500ctl binary also. To turn on the red LED, simply run ts7500ctl --redledon. GPIO manipulation is done through the --getdio, --setdio, and --setdiodir options. ts7500ctl --getdio will return a 64 bit hex number where e.g. bit 15 corresponds to the state of pin 15 on the TS7500 header. The getdiopin and setdiopin shell functions implemented in /ts7500.subr are implemented using this mechanism and the TS-752 functions (gettemp, setrelay, setout, getin) are implemented via the getdiopin/setdiopin functions.

High speed GPIO manipulation is best done via C and using the SBUS API to read/write FPGA GPIO registers directly. Specific register addresses are documented below. For low speed or non-performance critical GPIO access, it may often times be sufficient to use the C system() or popen() function to call the ts7500ctl utility or shell scripts written with the aid of the shell functions in /ts7500.subr:

   #include

   void main(void) {
     system("ts7500ctl --redledon");
     system("fire_laser");
   }

where /sbin/fire_laser is a script:

   #!/bin/sh

   . /ts7500.subr
   if [ -e /etc/laser_enabled ]; then
	   setdiopin 33 1
   fi

2.8.6 XUART Control from Userspace

XUART TTL serial ports are also implemented entirely from userspace. The 8 serial ports have a single shared 4kByte receive FIFO which makes real time interrupt latency response less of a concern and in actual implementation, the serial ports are simply polled at 100Hz and don't even use an IRQ. Even with all 8 ports running at 230400 baud, it is not possible to overflow the receive FIFO in 1/100th of a second. The "xuartctl --server" daemon is started by default in the INITRD linuxrc file which sets up listening TCP/IP ports for all 8 XUART channels on ports 7350-7357. An application may simply connect to these ports via localhost (or via the network) and use the serial ports as if they were network services. The default mode is "8N1" and default baud rate is 115200-- should the default need to be changed, modifying the linuxrc line that invokes the XUART server can be changed from:

   xuartctl --server

to:

   xuartctl --server --speed=9600 --mode=7e1

where the --speed option is any integer baud rate, and the --mode option is any one of the following modes:

  8n1
  8n2
  dmx - when in DMX mode, baudrate arg is not used (hardcoded 250 kbaud)
  8e1
  8o1
  8e2
  8o2
  7n1
  7n2
  7e1
  7o1
  7e2
  7o2

9-bit data modes are also supported "9n1", in which case the TCP stream is 16-bit at-a-time rather than byte at-a-time and the raw XUART TX datums are used (described below) rather than the actual 9-bit serial data.

The XUART channels can also be turned into legacy Linux virtual serial ports via the pseudo-tty driver by means of XUART port servers. XUART port servers are daemons that make the actual connection to the TCP socket (via localhost or the network) and connect it to a pseudo tty in /dev/pts/#. To start a virtual serial port channel for XUART channel #0 on the local board:

   xuartctl --port=0 --server

The pseudo-tty allocated from /dev/pts/ will be printed. This pseudo-tty will behave identically as a real serial port device driver except that the baud rate and parity modes cannot be changed via the standard termios routines. To run a port server for XUART channel #0 at 9600 baud:

   xuartctl --port=0 --server --speed=9600

Remote XUART ports can be attached by replacing the port number 0-7 with a hostname:TCP_port like this:

   xuartctl --port=192.168.0.50:7351 --server --speed=4800 --mode=8n1

The main XUART TCP server is started automatically in the linuxrc but no port servers are. These can be started by adding the appropriate lines to the linuxrc or at any time post bootup by running the utility from the command line.

2.8.7 CAN Control from Userspace

The TS-7552, TS-7553 and TS-4500 also have a CAN bus controller in the default load of the FPGA and the TS-7500/TS-7550 can have their FPGA's reprogrammed by sacrificing 3 seconds during Linux bootup to reload the FPGA with a version that contains 4 less XUARTs but includes CAN.

TS provides the utility "canctl" to both serve as sample C source code on how to send/receive CAN packets and as a simple utility to perform useful and common functions with the CAN bus. This utility, like xuartctl, also provides a simple network service with the --server option that will listen on TCP port 7552 and allow local or remote applications to send and receive CAN packets.

Talking straight to the CAN hardware registers to implement CAN is also not that complicated and fully supported by userspace application code. The CAN controller used in the FPGA is an improved SJA1000C-compatible FPGA opencore available from the open source hardware site at opencores.org. TS has made several bug fixes as well as extended the depth of the receive FIFO to 2kbytes, but is still compatible with all the register level documentation one can find on nxp.com regarding the discrete SJA1000C chip that has been available and has been the reference CAN controller for many years. For example, initializing the CAN controller from userspace:

	sbuslock();
	can_poke8(0, 0x1); /* Enter reset mode */
	can_poke8(31, 0x80); /* Enable PeliCAN mode */
	can_poke8(4, 0xff); /* All interrupts enabled */
	can_poke8(6, 0); /* BTR0 for 500kbps */
	can_poke8(7, 0x7e); /* BTR1 for 500kbps */
	can_poke8(13, 96); /* Error warning limit */
	can_poke8(14, 0); /* Reset RX error counter to 0 */
	can_poke8(15, 0); /* Reset TX error counter to 0 */
	can_poke8(20, 0xff); /* Acceptance msk disabled (all packets rx'ed) */
	can_poke8(21, 0xff);
	can_poke8(22, 0xff);
	can_poke8(23, 0xff);
	can_peek8(3); /* Clear pending interrupts */
	can_poke8(0, 0); /* Enter operational mode */
	sbusunlock();

Sample C code to transmit a CAN packet with CAN id in an int variable 'txid' and 0-8 bytes of data in a char array 'txdat' of length 'txdat_len'. 'txrtr' is set if the CAN packet is to be a CAN RTR packet instead of a data packet:

	sbuslock();
	can_loadtx(txid, txdat, txrtr ? CAN_RTR : txdat_len);
	can_poke8(1, 0x1); /* TX command */
	do {
		    sbusunlock();
		    can_irqwait(); /* pauses until IRQ trig'd */
		    sbuslock();
		    j = can_peek8(2); /* Poll status */
		    can_peek8(3); /* Clear pending interrupts */
	} while ((j & 0x44) == 0);
	sbusunlock();

Sample C source code to receive a CAN packet in a 16-byte char array 'tmp':

        can_irqwait(); /* block until IRQ trig'd */
        sbuslock();
        j = can_peek8(3); /* read IRQ */
        if (j & 0x1) { /* RX packet IRQ? */
                can_rxpacket(tmp);
                can_poke8(1, 0x4); /* Release receive buffer */
        }
        if (j & 0x8) can_poke8(1, 0x8); /* clear possible data overrun */
        sbusunlock();

At the end of the above RX packet routine, 'tmp' is a char buffer that has been filled to contain the CAN packet in the buffer format described on page 39 of the SJA1000 datasheet at ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/docs/SJA1000.pdf.

The routines above make use of userspace IRQ support. This is not standard in mainstream Linux 2.6 kernel sources and requires a patch. This patch is available for download at ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/sources/cavium-userspace-irq.patch but should already be present in default TS kernel binaries. The functionality this provides is a mechanism for a userspace program to block until an IRQ triggers by simply trying to 'read' from a file /proc/irq/IRQNUM/irq. The CAN IRQ is IRQ number 30. The following is the implementation of can_irqwait():

	static void can_irqwait(void) {
		    static int can_irqfd;
		    static int initialized;
		    int dummy;

		    if (!initialized) {
		            can_irqfd = open("/proc/irq/30/irq", O_RDONLY);
		            assert(can_irqfd != -1);
		            initialized = 1;
		    }

		    read(can_irqfd, &dummy, sizeof(dummy));
	}

The routines can_peek8(), can_poke8(), can_rxpacket(), and can_loadtx() use the SBUS peek/poke routines to access SJA1000C registers through the memwindow core at SBUS address 0x50. Please see the canctl.c source code at ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/sources/canctl.c for their definition. As with all TS released sample code, the restrictions of the common open source "GPL" license does not apply and customers may use, modify, or copy it in any form and have the freedom to keep modifications private and proprietary i.e. you will not be forced to open source derivative works.

The canctl application provides a CAN network service. Any application on the network can make use of this service to send or receive CAN packets using the API defined by canctl. Thus, it is possible to develop code written in other languages (java, python, etc.) and/or to run this code under other operating systems.

To start the CAN network service, invoke canctl with the --server option:

canctl --server

The canctl application itself can be a client of any canctl server running on the network. When compiling canctl for a platform which lacks the TS-CAN hardware, use the -DREMOTE_ONLY flag to the compiler to indicate that the executable is to be compiled as a client only. The supplied Makefile defines this flag when the environment variable CLIENT is defined. This has been tested on an X86 Linux box - the following command builds canctl for client use:

CLIENT=1 make

To invoke canctl as a client, specify the --port option. This option requires an argument which is the IP name or address of the server. (The canctl server uses TCP/IP port 7552.) All subsequent command-line arguments will communicate with the specified canctl server using the CAN network service.

Example: Send a CAN packet with the data 01:02:03:04:05:06 on the TS-7552 (it is assumed that the canctl server is running on this board) with IP address 192.168.1.100:

canctl --port=192.168.1.100 --txdat=01:02:03:04:05:06

The canctl application implements network CAN functionality using the can_rx_remote() and can_tx_remote() functions. These are very simple functions which read and write one fixed-size packet of struct canmsg to a TCP socket descriptor. Writing your own canctl client in the language of your choice is as simple as doing the same thing. The format of the each CAN packet sent or received via the network interface is described below. The terms "Rx" and "Tx" are relative to the client, so "Rx" would describe packets read from CAN over the network and "Tx" would describe packets written to CAN over the network.

  UINT8    flags:
           bit 7 - set on Tx if packet is a control packet
                   control packets are intercepted by the
                   canctl server to allow control functionality.
           bit 6 - set if message originates locally (unused)
           bit 5 - set if CAN message has extended ID
           bit 4 - set if remote transmission request (RTR)
           bit 3 - set on Rx if CAN error warning condition occurred
           bit 2 - set on Rx if CAN bus had a data overrun
           bit 1 - set on Rx if CAN bus went error passive
           bit 0 - set on Rx if a CAN bus error occurred
           Error conditions are reported for informational
           purposes.  The server normally handles these errors
           and recovers from them.
               control information present (reserved for future use)
               message originates from this node (unused)
  UINT32   CAN id
  UINT32   timestamp_seconds
  UINT32   timestamp_microseconds
  UINT8    bytes of CAN data which are valid
           if bit 7 of flags is set, this byte is instead interpreted
           as a command number:
             0 = set acceptance filter
               if the acceptance filter has been set, then only
               CAN packets which pass the filter will be received.
               to pass the filter, all bits in the acceptance filter
               which are to be checked (specified by a 1 in the
               corresponding bit of the mask) are compared (filter
               id compared to corresponding bit in received id).
               only if all bits to be checked do match will the
               packet be received.
  UINT8[8] CAN data
           if bit 7 of flags is set, this byte is instead interpreted
           as follows:
             cmd 0:
               UINT32 acceptance filter id
               UINT32 acceptance filter mask

So for example, to send a CAN packet of length 6 with contents 01:02:03:04:05:06 and CAN id 55 it would be necessary to open a TCP connection to port 7552 on the device with the canctl server running, and the write the following packet to the socket:

   00 55 00 00 00 00 00 00 00 00 00 00 00 06 01 02 03 04 05 06 00 00

2.8.8 Random Number Generator

On startup, ts7500ctl is called with the --setrng option to seed Linux's random number generator from the hardware random number generator. Without a good source of entropy, Linux's random number generator will start up in a very predictable state which is undesirable for the security of many cryptography protocols.

3 Interfaces

3.1 TS-7500/TS-7550 Interface

3.1.1 44-Pin Header

Besides the 10/100 ethernet jack, MicroSD card socket(TS-7500 only), and USB host/slave ports, the TS-7500/TS-7550 also includes a .1" pin spacing external header for board to board interfacing. The external interfaces uses a total of 44 pins.

    _________________________________________________________________ 
   | 2  4  6  8 10 12 14 16 18 20 22 24 26 28 30 32 34 36 38 40 42 44|
 * | 1  3  5  7  9 11 13 15 17 19 21 23 25 27 29 31 33 35 37 39 41 43|
   \-----------------------------------------------------------------/

Pin table:

* The SPI_CSn are only available for boards with FPGA revision 4 or higher.

The XUART controller hijacks DIO pins when the respective XUART channel is enabled. This means either the port server (pseudo-tty) is active or a TCP connection is established to the daemon running the command "xuartctl --server"

None of the DIO pins are 5V tolerant. They are 3.3V LVCMOS I/O buffers with approximately 12mA current drive capability.

3.1.2 DIO

Pins named "DIO" in the function column are connected directly to the FPGA. To use these pins, you must first set the data direction registers, and then read or write values from the data registers (see Syscon Core section). When accessing these registers, it is important to do a read-modify-write, as other bits may be used internally.

3.1.3 UART0 (CONSOLE UART)

CONSOLE_TXD (Pin 7) and CONSOLE_RXD (Pin 8) bring out the TTL level signals from the FPGA. By default, this UART provides boot messages and the Linux console (/dev/ttyS0).

3.1.4 I2C Bus

The I2C_SCL and I2C_SDA pins bring out the I2C bus from the CNS2132 CPU. Please refer to the CNS2132 user's guide for more information.

3.1.5 External Reset

Driving the external reset pin low will reset the CPU. While the ext3 file system on the SD card is extremely resilient and is normally not damaged by hard resets, rebooting the board using the reboot command is still recommended if the file system is mounted read/write.

3.1.6 Temperature Sensor

The TS-752 development board has an on-board temperature sensor. The temperature sensor used is a TMP124; a copy of the datasheet can be found here.

The temperature sensor is accessed via SPI pins on the DIO header documented in section 3.1.1. The DATA pin is connected to the SPI_MISO# signal (DIO 12), while the CLK pin is connected to the SPI_CLK pin (DIO 14). In addition there is a chip select signal which must be asserted in order to use the temperature sensor chip (DIO 22). An example program which uses the sbus.c API can be found in the TS-7500 FTP Repository here: ftp://ftp.embeddedarm.com/ts-arm-sbc/ts-7500-linux/samples/gettemp.c

3.1.7 XUARTs

In addition to the serial console there are 8 additional serial ports all implemented in the FGPA core. These can be accessed after issuing the "xuartctl --server" command as described in section 2.8.6. The Linux device names will be /dev/pts/n where n is the "port" number specified. For example:

ts7500:~# xuartctl --port=0 --server --speed=115200 --mode=8n1
ttyname=/dev/pts/0
ts7500:~# xuartctl --port=1 --server --speed=115200 --mode=8n1
ttyname=/dev/pts/1
ts7500:~# 

The xuartctl uses the openpty() function to allocated a pseudo-tty. It will give the first free one out. If your application requires a specific tty port, one suggestion would be to use a symbolic link such as this: "ln -s $portname /dev/pts/0".

3.1.8 Power Supply Connector

The TS-7500 requires regulated 5VDC at 400mA (min). A cushion should be provided to allow more power for additional devices. Recommended power supply is 5VDC @ 1A.

The TS-7500 can be powered via USB Device port or via TS-752 development board with 5VDC connector.

Be sure to use a regulated 5 power supply, preferably with current limiting to 1 to 3 Amps. A current limited supply is very forgiving of common errors during development. A PC power supply that may be capable of supplying 20 Amps or more is not recommended. It is possible to do irreversible damage to the TS-7500 if the polarity on the power leads is reversed.

3.1.9 MicroSD Card Connector

The MicroSD Card socket on the top of the TS-7500 (not available on the TS-7550) enables MicroSD Cards to be used as primary storage devices for the TS-7500. The hardware core implemented by Technologic Systems is integrated inside the on-board FPGA. Technologic Systems has written a binary Linux driver module and a set of generic, OS-independent read/write routines for accessing the MicroSD flash inside of an ARM object (.ko) file. The linuxrc startup script assumes that partition 4 of the SD card contains a ext3 filesystem. The MicroSD socket is bootable and fully supports SDHC cards.

3.1.10 DB9 Connector on TS-752

The DB9 connector on the TS-752 development board brings out 1 CPU serial port on pins 2 (RX) and 3 (TX) (COM1, /dev/ttyS0, by default the Linux console), XUART#0 on pins 7 (TX) and 8 (RX), and 485 differential on pins 1 (X+) and 6 (X-). See section 3.7 for more information on TSUARTs. All signals are at RS-232 levels.

3.2 TS-7552/Ts-7553 Interfaces

Besides the 10/100 ethernet jack, MicroSD card socket, and USB host/slave ports, the TS-7552/TS-7553 also includes a .1" pin spacing external header for board to board interfacing. The external interfaces uses a total of 26 pins.

    ______________________________________ 
   | 2  4  6  8 10 12 14 16 18 20 22 24 26|
 * | 1  3  5  7  9 11 13 15 17 19 21 23 25|
   \--------------------------------------/

None of the DIO pins are 5V tolerant. They are 3.3V LVCMOS I/O buffers with approximately 12mA current drive capability.

The TS-7552 also contains a male DB9 connector. The pins are numbered faintly on the connector itself as follows:

	  =============  
	 1\\+ + + + +//5 
	 6 \\+ + + +// 9 
	    =========    

	Pin #  Name/function
	1      RS485_0+              RS485 serial TX/RX + (XUART #2)
	2      XUART#0_RX            RS232 serial RXD for XUART #0
	3      XUART#0_TX            RS232 serial TXD for XUART #0
	4      CAN_H                 CAN bus high (or second RS485 port +)
	5      GND                   Ground
	6      RS485_0-              RS485 serial TX/RX - (XUART #2)
	7      XUART#1_TX            RS232 serial TXD for XUART #1
	8      XUART#2_RX            RS232 serial RXD for XUART #1
	9      CAN_L                 CAN bus low (or second RS485 port -)

The CAN bus has optional termination resistor enabled by JP2 jumper. The termination resistor is 124 ohms across the CAN_H and CAN_L pins.

There is a mini PCI-Express style card slot for placement of a wifi radio. This slot only supports the USB pins of PCI Express so only cards using these I/Os are supported. If the wifi slot is not used, a pin header labeled USB4 on the silkscreen can be used as a 5th USB port.

The 5x1 pin header labeled USB3 is wired in parallel with the left-most USB host connector. It may be also used as an internal USB port. The 5x1 pin header:

	  ___________
	 | 1 2 3 4 5 |
	 \-----------/
	   *

	Pin #  Name/function
	1      FRAME                  Same as ground
	2      GND                    Ground
	3      USB+
	4      USB-
	5      USB_5V                 USB 5V power

3.3 TS-4500 Interfaces

All offboard connections on the TS-4500 macrocontroller module go through the 2 high density 100 pin board to board connectors CN1 and CN2. The mating connectors and mechanical layout specification are available from the TS website.

Left connector (CN1):

SD card signals on connector are wired in parallel with SD card socket. Only one can be populated with an SD card.

Right connector (CN2):

4 SBUS SPI to FPGA Protocol

For the most part, the application and kernel level programmer will not be interested in the following sections as the below information is completely abstracted away from the user by the SBUS C API and the various TS-specific utilities. Even the FPGA programmer is abstracted from the details of this protocol by the spi_sbus.v Verilog module which turns the SBUS SPI traffic into WISHBONE bus cycles.

The SBUS protocol allows for 16 specific 16 bit registers (32-bytes of register space) to be read or written and has provision for the FPGA internal WISHBONE bus cycles to take any amount of time to be ack'ed through the mechanism of SBUS retries. SPI bandwidth efficient burst register reads/writes are also possible when writing/reading continuously to the same address.

The general protocol consists of a 24-bit SPI transaction framed by the SPI CS#. Bits are clocked in on the rising edge and the first MOSI (input) bit signifies whether the bus cycle is a read or write. This is followed by the 4 address bits MSB first. The remaining 19 bits depend on whether the cycle is a read or write. For reads, the WISHBONE bus cycle is started as soon as the last address bit is clocked in.

The 24-bit SPI SBUS data format - bit 23 (WE) is first on wire:

   16-bit WISHBONE READ operation
      23|22|21|20|19|18|17|16|15|14|13|12|11|10| 9| 8| 7| 6| 5| 4| 3| 2| 1| 0|
      --|--|--|--|--|--|--|--|--|--------------------------------------------|
   SI: 0|A3|A2|A1|A0|  |  |  | B|<------------should be zero---------------->|
   SO:              |X2|X1|X0|MSB<----------returned READ data----------->LSB|

   16-bit WISHBONE WRITE operation:
      23|22|21|20|19|18|17|16|15|14|13|12|11|10| 9| 8| 7| 6| 5| 4| 3| 2| 1| 0|
      --|--|--|--|--|-----------------------------------------------|--|--|--|
   SI: 1|A3|A2|A1|A0|MSB<-----------WRITE data------------------>LSB|N2|N1|N0|
   SO:                                                              |Y2|Y1|Y0|

   * A3-A0: Address bits (sent by CPU)

   * X2-X0: ack bits for reads (sent by FPGA). If any are 1, the following
     data is valid.  If they are all 0, the WISHBONE cycle did not complete in 
     time and must be immediately retried.

   * Y2-Y0: ack bits for write (sent by FPGA). If any are 1, the write
     cycle was completed.  If all are 0, the WISHBONE write did not complete
     and must be immediately retried.

   * B: Burst read.  Setting this to 1 starts another WISHBONE read cycle for
     the same address.  See "SBUS Burst mode" below.

   * N2-N0: For burst writes, this represents bits 15-13 of the next burst 
     write data, otherwise these bits are Dont-Cares.  See "SBUS Burst mode"
     below.  

When the WISHBONE cycle does not assert the wb_ack_i signal in time and the transaction must be retried, it is not necessary to deassert and reassert SPI CS# in between each retry, though it is necessary to start a new bus cycle.

4.1 SBUS Burst Mode

After a normal 24-bit SBUS READ/WRITE cycle takes place, it is possible to continue reading or writing to the same WISHBONE register by keeping CS# asserted and continuing the SPI clock 16 bits at a time. However, once a burst is started, there is no provision to allow for an occasional long WISHBONE cycle and all WISHBONE cycles must be able to complete in 14 SPI clock cycles otherwise results are undefined. The only registers used in TS-7500 implementation for bursts are the SPI and SD card data registers.

For burst WRITEs, one issues a normal WRITE cycle as above with possible retries making sure that the 3 LSB (last) bits sent represent the 3 MSB bits (15-13) of the next WRITE data. Subsequent writes take place 16 bits at a time while CS# is held asserted. The burst stops once CS# is deasserted.

For burst READs, one issues a normal 24-bit READ cycle and 0 or more retries, but with the "B" bit set. Once the burst is started, bit 15 must always be set as long as the read burst is to continue. On the very last READ in the burst, the 16-bit data sent by the FPGA on SO should be all zeros.

4.2 FPGA Verilog Implementation (spi_sbus.v)

The spi_sbus Verilog module WISHBONE clock output is synchronous to the actual SPI clock. This also means when the SPI bus becomes quiet, there are no clocks to the WISHBONE bus.

The sel_i input is used as a byte lane select. On the TS-7500, there are 2 dedicated GPIO pins from the CPU to the FPGA that are used for this. Without the sel_i inputs, it is not possible to have 8-bit reads/writes.

On the TS-7500 implementation, there are 2 extra address lines via GPIO pins on the CPU. This allows a total address space of 4 * 32 bytes == 128 bytes == 64 individual 16-bit registers. For these GPIO lines (and the byte lane selects) it is important that they be setup in advance of the SPI transaction and remain stable during it.

The spi_sbus_resync Verilog module is similar to the spi_sbus module except that it can use an asynchronous WISHBONE clock. This is what is used in the TS-7500 since the common WISHBONE clock is 75Mhz but the SPI clock can be any rate from 32.5Mhz to 50Mhz depending on CPU speed. A side effect of this though is that clock resynchronization overhead can make even the shortest of bus cycles miss the 3 SPI clock window for acknowledgment and force the majority of bus cycles into at least one retry. For this reason, a 2nd WISHBONE master interface is provided for WISHBONE slaves that are okay with using the SPI SCK as their clock -- to use this bus, spiwbm_en_i has to be asserted before the next clock edge after spiwbm_cyc_o, spiwbm_stb_o, and spiwbm_adr_o are asserted and valid.

There is another quirk about the spi_sbus_resync module because burst writes accumulate in a 16-entry write buffer clocked from the SPI clock domain. Flushing of this buffer happens automatically before any subsequent READ or WRITE transaction, but it is possible for there to be writes not yet posted to the asynchronous WISHBONE clock domain at the completion of a WRITE burst. It therefore may be important to follow up any WRITE burst with a READ to insure the last WRITE in the burst completes 100%. This becomes especially significant on the TS-7500 which includes 2 extra GPIO address bits that must remain stable while there are writes pending in the write buffer. For example, it would not be safe to allow users to change those GPIO address bits while there is still pending WRITES in the write buffer.

5 FPGA SBUS Register Map

5.1 Top level address decode

   0x00-0x0f: SD card core
   0x10-0x1f: reserved
   0x20-0x3b: XUART core
   0x3c-0x3f: XUART memwindow
   0x40-0x4f: SPI interface (for NOR flash)
   0x50-0x5f: reserved
   0x60-0x7f: syscon (GPIO/LEDs/revision/etc...)

4 bits of address come from the SBUS interface, 2 bits of address come from GPIO A16 and A15 and each address represents 16-bit registers. Total 128 bytes of address space (64 16-bit regs)

It is possible to do 8-bit writes via GPIO A17 and A3 which act as active high byte lane selects.

5.2 SD Card Core

The SD card core is a black box serviced by the OS independent C API (sdcore2.c) for reading/writing SD cards. This source code is available, but not recommended for modification. Since this core instance not cannot use memory based register access, the generic peek/poke routines need to be overloaded with SBUS specific register access. This happens automatically in the sdctl utility.and sdctl.c source code from the TS FTP site ftp://ftp.embeddedARM.com/ may be consulted as the reference.

XUART core - 8 asynchronous serial RX/TX with extended features:

The XUART core software support is almost completely provided for by the "xuartctl" TS utility which exports XUART channels as either TCP ports or pseudo-tty devices. There is also a low-level OS independent C API provided in xuartcore.c. The "xuartctl" utility uses this API to provide the TCP/pseudo-tty interface, but it is possible to use this API directly if xuartctl is not to be used.

5.3 XUART Register Map

   0x20: TX/RX control channel #0
     bits 15-8: RCNT (read) / RIRQ (write)
     bits 7-0: TXPOS (read) / TXSTOP (write)

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.

   0x22: TX/RX control channel #1
   0x24: TX/RX control channel #2
   0x26: TX/RX control channel #3
   0x28: TX/RX control channel #4
   0x2a: TX/RX control channel #5
   0x2c: TX/RX control channel #6
   0x2e: TX/RX control channel #7
   0x30: IRQ status and acknowledgment
     bits 15-8: RXIRQ (1 - IRQ pending, 0 - IRQ not pending)
     bits 7-0: TXIRQ (1 - IRQ pending, 0 - IRQ not pending)

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 deassert 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 is described below. All RX IRQ bits will be cleared on read of RX address (iobase + 0x14).

   0x32: TX/RX status
     bits 15-8: RX enabled (1 - RX is enabled, 0 - RX is disabled) (RW)
     bits 7-0: TX pending (1 - TX is running, 0 - TX completed) (RO)

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.

   0x34: RX address  (read-only)
     bits 15-0: current RX address (next to be written)
   0x36: TX config (write-only)
     bits 15-0: TX config (2-bits per channel)
       0 - TX suspended (TX idle)
       1 - TX suspended (TX break instead)
       2 - TX enabled
       3 - TX enabled with hardware CTS flow control
   0x36: TX flow control status (read-only)
     bits 15-0: TX flow status (2-bits per channel)
       0 - TX idle, CTS input deasserted
       1 - TX busy, CTS input deasserted
       2 - TX idle, CTS input asserted
       3 - TX busy, CTS input asserted
   0x3c: memwindow address reg (RW)
   0x3e: memwindow data reg (RW)

When the memwindow data reg is read or written, the memwindow address is automatically incremented by 2. In this way, contiguous reads/writes of address space is optimized.

5.4 XUART Memory Map

(Accessed via memwindow regs above)

   0x0000: 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

5.5 XUART 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 15-14: reserved, should be zero.
   bit 13: sets TX IRQ at start of TX processing this entry
   bit 12-11: opcode type
    00 - transmit data character
    01 - transmit timed break
    10 - transmit timed idle
    11 - control opcode (updates internal UART regs)
   bits 10-0: opcode data

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:

   0: baud prescalar - 16 bit counter to generate 8x baud freq
   1: control reg
     bits 15-4: unused (don't cares)
     bits 3-2: idle threshold - sets RX irq after set idle time
       00 - 1 bit time
       01 - 8 bit times
       10 - 16 bit times
       11 - 32 bit times
     bits 1-0: character size
       00 - 7 bits
       01 - 8 bits
       10 - 9 bits
       11 - 10 bits
   2-6: reserved

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.

5.6 XUART RX Processing

The receiver uses 4kbytes 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 15-13: UART# character received from
   bits 12-11: RX type
      00 - character
      01 - break
      10 - idle
      11 - Invalid -- will never be written
   bits 10-0: RX data

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, i.e. for a 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 be not only 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.

5.7 SPI Interface (For NOR Flash or Other)

This core is for high speed SPI with auto-CS#. Starts at offset 0x40 on the TS-7500. LUN#0 goes to onboard SPI NOR flash chip (TS-7500 only) and LUN#1 goes to offboard SPI (TS-752 or TS-9448 flash chip)

SPI interface register map:

   0x40: LUN register (R/W)
     bit 15: spi miso state (RO)
     bit 14: spi clk state (RW)
     bits 13-10: speed (0- highest, 1- 1/2 speed, 2- 1/4, 3- 1/6, etc..) (RW)
     bits 9-8: LUN (0-3 representing the 4 CS# signals) (RW)
     bits 7-0: reserved

   * The SPI clk state register should be set when CS# is deasserted.  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.

   * For the TS-75xx/TS-4500 where the base clock is 75Mhz, speed settings 
     break down as follows:
       0 - 75Mhz (/1)
       1 - 37.5Mhz (/2)
       2 - 18.75Mhz (/4)
       3 - 12.5Mhz (/6)
       4 - 9.375Mhz (/8)
       5 - 7.5Mhz (/10)
       6 - 6.25Mhz (/12)
       7 - 5.36Mhz (/14)
       8 - 4.68Mhz (/16)
       9 - 4.17Mhz (/18)
       ...
       15 - 2.5Mhz (/30)

   * bits 10-15 were not present on TS-7500 FPGA prior to rev 4.  On those
     TS-7500's, SPI speed was hardcoded to 75Mhz and 75Mhz only.

   0x42: previous SPI read data from last write (RO)
   0x44: reserved
   0x46: reserved
   0x48: SPI read/write with CS# to stay asserted (RW)
   0x4a: SPI pipelined read with CS# to stay asserted (RO)

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. This register is an appropriate target address for SBUS burst reads.

   0x4c: SPI read/write with CS# to deassert post-op (RW)
   0x4e: reserved

5.8 IO Window Core

This core is a simple core to allow access to an up to 64Kbyte WISHBONE 8-bit address space via a 4 16-bit register window.

   0x50: IO window address reg (RW)
   0x52: 8-bit IO data reg with auto-increment (RW)

   * When the data reg is read or written, the address is automatically
     incremented by 1.  In this way, contiguous reads/writes of address
     space is optimized.

   0x54: 16-bit IO data reg with auto-increment (RW)

   * When the 16-bit data reg is read or written, 2 read or write 8-bit
     bus cycles are performed and the address is incremented by 2.

   0x56: Combo IO address/data write reg (WO)
     bits 15-8: address bits 7-0 of bus write
     bits 7-0: data bits of bus write cycle.

   * This register is only meaningful write-only.  It encodes the 8 LSBs
     of the address as the 8 MSBs of the written data word.

IO window address map:

   0x0-0xff     - optional SJA1000C compatible CAN controller
   0x100-0xffff - reserved

5.9 Syscon Core

   0x60: Model ID reg (RO) - reads 0x7500 on the TS-7500
   0x62: submodel, fpga revision, RTC and LED control - (RW)
     bit 15: green LED (1 - on)
     bit 14: red LED (1 - on)
     bit 13: RTC SCL input
     bit 12: RTC SDA input
     bit 11: RTC SCL direction (1 - output)
     bit 10: RTC SDA direction (1 - output)
     bit 9: RTC SCL output
     bit 8: RTC SDA output
     bit 7-4: Board submodel (RO) - 0x0 on production TS-7500
     bit 3-0: FPGA revision
   0x64: 16-bits of random data changed every 1 second. (RO)
   0x66: DIO and tagmem control (RW)
     bit 15-12: DIO input for pins 40(MSB)-37(LSB) (RO)
     bit 11-8: DIO output for pins 40(MSB)-37(LSB) (RW)
     bit 7-4: DIO direction for pins 40(MSB)-37(LSB) (1 - output) (RW)
     bit 3: Lattice tagmem clock (RW)
     bit 2: Lattice tagmem serial-in (RW)
     bit 1: Lattice tagmem CSn (RW)
     bit 0: Lattice tagmem serial-out (RO)
   0x68: DIO input for pins 36(MSB)-21(LSB) (RO)  
   0x6a: DIO output for pins 36(MSB)-21(LSB) (RW)
   0x6c: DIO direction for pins 36(MSB)-21(LSB) (1 - output) (RW)
   0x6e: DIO input for pins 20(MSB)-5(LSB) (RO)  
   0x70: DIO output for pins 20(MSB)-5(LSB) (RW)
   0x72: DIO direction for pins 20(MSB)-5(LSB) (1 - output) (RW)
   0x74: Watchdog feed register (write only)
     write value 0x0: feed watchdog for another .338s (approx)
     write value 0x1: feed watchdog for another 2.706s (approx)
     write value 0x2: feed watchdog for another 10.824 (approx)
     write value 0x3: disable watchdog
   0x76: SPI PLL phase, latched mode bits, scratch reg
     bit 15-11: reserved
     bit 10-6: PLL phase (set by TS-BOOTROM) (RW)
     bit 5: mode3 latched bootstrap bit (RO)
     bit 4: Reset switch enable (1 - auto reboot when dio_i[9] == 0) (RW)
     bit 3-2: scratch reg (RW)
     bit 1: mode2 latched bootstrap bit (RO)
     bit 0: mode1 latched bootstrap bit (RO)

Not all DIO pins come out to the external header under FPGA control. Consult schematic for more details -- some are power/grounds or come from the CPU. Attempting to write or read values from these pins will have no effect.

On the TS-7552, USB 5V power can be turned on/off by manipulating the register for DIO pin 7 (address 0x72, bit 3, 1 - USB power on) and the USB hub chip can be reset using DIO pin 8 (address 0x72, bit 4, 0 - reset asserted)

Watchdog by default comes out of reset armed for .338 seconds. TS-BOOTROM firmware feeds for 10.824 and OS code has 10.824 seconds to take over.

6 Hardware/Software Customization

6.1 Customizations by Technologic Systems

Should your embedded project approach quantities between 500-1000 boards per year, it may be a good time to talk to TS engineer about specific hardware or software customization that become available to you. There may be modifications we can do to reduce cost or add specific features to directly accommodate your specific requirements. Several options are available:

1. TS can load your software directly onto the boards you order. Often times this can save you from creating your own production and software loading process. This type of service is available no matter the quantity.
2. CPLD's/FPGA's can be reprogrammed to include specific customer-specified functionality. For instance, a magic register your software can verify before enabling certain features of your product or extra serial ports in the CPLD.
3. Simple daughter-boards can be designed. Often, a low-cost 2-layer companion board can be created to add functionality to the board without actually changing the more expensive multi-layer TS-7XXX circuit board.
4. Any TS board can be given new features and/or physical dimensions. This is the most expensive, but most powerful form of customization. Often times, TS may subsidize the development costs of a new board if it has general appeal to our broader customer base. Much of our COTS product line was a joint development between TS and another company. Allowing TS to generally market a design is a great way to achieve economies of scale (thereby reducing per-unit cost) and to ensure stock and commercial-off-the-shelf (COTS) status for your custom board.

6.2 Custom FPGA Programming by Customer

Technologic Systems has made available a zipped up a Lattice ispLever 7.2 project which allows customers to generate custom TS7500 FPGA projects. It can be found here:

ftp://ftp.embeddedARM.com/misc/ts7500_opencore.zip

Other TS-7550/TS-7552/TS-7553/TS-4500 OpenCore projects will be uploaded to the FTP site as well. Contact Technologic Systems support at support@embeddedARM.com for information.

Once downloaded, open up the project in ispLever (free download from Lattice) and double-click "Generate Data File (JEDEC)"

A few minutes later, a ts7500_opencore.jed will be produced that can be copied over to the SBC and loaded into the FPGA SRAM via the command "ts7500ctl --loadfpga ts7500_opencore.jed". FPGA reloading takes approx 2.8 seconds.

Some notable points about the FPGA opencore:

• The opencore FPGA bitstream has all functionality of the default bitstream including SD, XUARTs, SPI NOR flash, watchdog, etc..
• SD and XUART cores are Lattice .ngo (binary netlists), but Verilog sources to everything else is included.
• You need the newest ts7500ctl just released that has the "--loadfpga" option at ftp://ftp.embeddedARM.com/ts-arm-sbc/ts-7500-linux/binaries/ts-utils/
• You also need jed2vme executable in your path (same FTP location as above) to use ts7500ctl --loadfpga on a .jec file.
• jed2vme can be used to turn the 1.2Mbyte JEDEC .jed file into a 190Kbyte .vme file. This .vme file can also be gzip'ed or bzip2'ed into (~90Kbyte) .vme.bz2 or .vme.gz and "ts7500ctl --loadfpga" will decompress automatically.
• Licensing will be BSD (not GPL) to allow for proprietary closed-source modifications. However, there will be a caveat that you can only use the sources on our own TS hardware. Basically, as long as you do it on our boards, you can do whatever you want with it.
• The intention is to make the default initrd "linuxrc" attempt to automatically load a bitstream at "/ts7500.vme.gz" if it exists since it is best to reload the FPGA as early as possible before userspace driver daemons are all started.

Also, Technologic Systems has released the source code to all the userspace *ctl utilities they have written at ftp://ftp.embeddedARM.com/ts-arm-sbc/ts-7500-linux/sources/.

7 Where to go for Additional Help

Technologic Systems makes available several engineers to provide free technical support regarding the TS-7500 hardware. To request support, email to support@embeddedARM.com or call 480-837-5200. For general Linux questions not specific to the TS-7500 (such as, "How to configure the Apache web server"), you may be referred to the TS professional services group, which is well equipped to research just about any level of question from kernel development to web server configuration.

Since Linux is open-source, support may also be received from the individual development communities throughout the internet. Several projects have internet posted FAQs, HOWTOs, and community supported mailing lists providing users of their authored programs free help. There is also a general web based forum for Technologic Systems customers containing discussions, sample code, and several years of searchable questions and answers on the TS-7000 series of products at http://groups.yahoo.com/group/ts-7000.

8 Environmental Specifications

To ensure optimum product operation you must maintain the operational environmental specifications:

• Ambient Temperature: -20°C to +80°C
• Relative Humidity: 0 to 90% relative humidity. Not to exceed 90% non-condensing.

9 Further References

Documentation

• Linux for ARM on TS-72XX User's Guide
• TS-7500 Schematic
• TS-7500 Mechanical Drawing
• TS-75XX 44-pin Header Pin-Out
• TS-7500 Basic Manual

Articles

• Hardware Reliability
• TS-7250 HALT Report

Software Pages

• Linux for ARM on TS-7000
• Linux-based Bootloader for TS-7000

Downloads

• TS-7500 Linux FTP Repository

Appendix A: Document History

Appendix B: Contact Technologic Systems

Technologic Systems
16525 East Laser Drive
Fountain Hills, AZ 85268
TEL 1.480.837.5200
FAX 1.480.837.5300
www.embeddedARM.com
support@embeddedARM.com

Call us Monday-Friday, from 9 am to 5 pm, Arizona-USA time; or email us at any time.

Our engineers answer tech support calls and are more than happy to talk to you about your needs and help you find the best solution for your project.