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. Hardware features include: *) 250Mhz Cavium ARM9 CPU core (Faraday 526) *) 64MByte 16-bit wide DDR SDRAM running at 125Mhz *) micro SD slot *) 4MByte SPI NOR flash chip *) DIO pins on the 40 pin header *) 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 *) 8 XUART TTL serial ports on FPGA *) Hardware watchdog on FPGA *) Optional battery backed real time clock *) 10/100 Mbit on-CPU ethernet *) Low power (395mA @ 5V or 2.0 Watt) *) rugged 40 pin .1" header expansion connector *) Fanless/heatsink-less operation up to 80C temperatures 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. Manufacturer (Technologic Systems) features include: *) 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 customizations available with no minimum order. Getting Started: ================ The TS-7500 board has 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). Note that the TS-7500 only has TTL uarts and to connect to the serial console with a PC's serial port you need to use the TS-752 or external RS232 level converters. 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 accomodated by the "busybox" program. Technologic Systems has used busybox 1.14.2 on the TS-7500 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: 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 your 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. TS-7500 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 shipped with the TS-7500 kit. 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-7500 specific applications: ts7500ctl, sdctl, spiflashctl, and xuartctl. # 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 -X, --resetswitchon Enable reset switch -Y, --resetswitchoff Disable reset switch -I, --extendedtempon Enable extended temp (200Mhz CPU) -C, --extendedtempoff Disable extended temp (250Mhz CPU) -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. # spiflashctl --help Usage: spiflashctl [OPTION] ... Technologic Systems SPI flash manipulation. General options: -R, --read=N Read N blocks of SD to stdout -W, --write=N Write N blocks to SD -x, --writeset=BYTE Write BYTE as value (default 0) -i, --writeimg=FILE Use FILE as file to write to SD -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 sdread/sdwrite 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 of SD to stdout -W, --write=N Write N blocks to SD -x, --writeset=BYTE Write BYTE as value (default 0) -i, --writeimg=FILE Use FILE as file to write to SD -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 sdread/sdwrite 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. 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. Debian Linux SD card: ===================== The typical way of doing Linux development on the TS-7500 is actually on the board itself. Since the TS-7500 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-7500 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. Also provided in the devkit SD card image is a Windows PC installation of Eclipse preconfigured for TS-7500 cross development. 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 utility "spiflashctl". 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 TS-7500 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, issue the command: spiflashctl -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 flash. Keep in mind the maximum size of kernel in the default partition layout is 2096640 bytes. Uncompressed kernels will always boot faster on the TS-7500. 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. 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(); } 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 adviseable 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. 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. JP1 off, JP2 off - onboard SPI flash, if flash unitilized, falls back to SD JP1 on, JP2 off - micro SD card JP1 off, JP2 on - offboard (TS-752) SPI flash JP1 on, JP2 on - 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. TS-7500 specific Linux devices: =============================== The TS-7500 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 TS-7500 specific drivers or kernel support implemented. Instead, there has been userspace driver support implemented for the SPI NOR flash, micro SD cards, 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. Both the SPI flash 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 or 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" or "spiflashctl" 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 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. 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. 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 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. Interfaces: =========== Besides the 10/100 ethernet jack, micro SD card socket, and USB host/slave ports, the TS-7500 also includes a .1" pin spacing external header for board to board interfacing. The TS-7500 externel 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: Pin # Name/function 1 JTAG_DOUT 2 JTAG_TMS 4.7k pull-up 3 JTAG_CLK 2.2k pull-up 4 JTAG_DIN 4.7k pull-up 5 DIO_05 DIO, XUART#0 TX, RS232 RTS on TS-752, 4.7k pull-up 6 DIO_06 DIO, XUART#0 RX, RS232 CTS on TS-752 7 DIO_07 Console TX, DB9 RS232 TXD on TS-752, 4.7k pull-up 8 DIO_08 Console RX, DB9 RS232 RXD on TS-752, 4.7k pull-up 9 DIO_09 DIO or ext_reset# 10 3.3V 3.3V power 11 DIO_11 DIO or flash_cs# 12 DIO_12 DIO or spi_miso 13 DIO_13 DIO or spi_mosi 14 DIO_14 DIO or spi_clk 15 5V 5V power 16 GND Ground 17 SCL I2C/DIO - driven by CPU, 2.2k pull-up 18 SDA I2C/DIO - driven by CPU, 2.2k pull-up 19 DIO_19 DIO, XUART#1 TX, RS485 TXD on TS-752 20 DIO_20 DIO, XUART#1 RX, RS485 RXD on TS-752 21 DIO_21 DIO, XUART#2 TX 22 DIO_22 DIO, XUART#2 RX, temp sensor CS# on TS-752 23 DIO_23 DIO, XUART#3 TX, CAN TXD on TS-752 24 DIO_24 DIO, XUART#3 RX, CAN RXD on TS-752 25 DIO_25 DIO, XUART#4 TX 26 DIO_26 DIO, XUART#4 RX, input#8 on TS-752 27 DIO_27 DIO, XUART#1 TXEN, RS485 TXEN on TS-752 28 DIO_28 DIO, XUART#2 TXEN, input#7 on TS-752 29 DIO_29 DIO, XUART#3 TXEN, out#3 on TS-752 30 DIO_30 DIO, input#6 on TS-752 31 DIO_31 DIO, XUART#5 TX, out#2 on TS-752 32 DIO_32 DIO, XUART#5 RX, input#5 on TS-752 33 DIO_33 DIO, XUART#6 TX, out#1 on TS-752 34 DIO_34 DIO, XUART#6 RX, input#4 on TS-752 35 DIO_35 DIO, XUART#7 TX, relay#3 on TS-752 36 DIO_36 DIO, XUART#7 RX, input#3 on TS-752 37 DIO_37 DIO, relay#2 on TS-752 38 DIO_38 DIO, input#2 on TS-752 39 DIO_39 DIO, relay#1 on TS-752 40 DIO_40 DIO, input#1 on TS-752 41 POE_RX Power over ethernet (see schematic) 42 POE_78 Power over ethernet (see schematic) 43 POE_45 Power over ethernet (see schematic) 44 POE_TX Power over ethernet (see schematic) 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. 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. 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 zeroes. 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 acknowledgement 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. FPGA SBUS Register Map: ====================== 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. 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. 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 acheived 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 writeable. 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 acknowledgement 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. 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 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 contigously. 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. 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. SPI interface (for NOR flash): 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 and LUN#1 goes to offboard SPI (TS-752 flash chip) SPI interface Register map: 0x40: LUN register (R/W) bits 15-10: reserved bits 9-8: LUN (0-3 representing the 4 CS# signals) (RW) bits 7-0: reserved 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 optimimum 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 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 TS-7500 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. Watchdog by default comes out of reset armed for .338 seconds. TS-BOOTROM firmwarm feeds for 10.824 and OS code has 10.824 seconds to take over. 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. Hardware/Software Customization: ================================ Should your embedded project approach quantites between 500-1000 boards per year, it may be a good time to talk to TS engineer about specific hardware or software customizations that become available to you. There may be modifications we can do to reduce cost or add specific features to directly accomodate 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-7500 circuit board. 4) The TS-7500 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 acheive economies of scale (thereby reducing per-unit cost) and to ensure stock and commercial-off-the-shelf (COTS) status for your custom board.