Overview

As described above on the title page, the PROG C2 programmer consists of a Silicon Laboratories (SL) chip programmed to implement most of the C2 programming protocol, as described in the SL Application Note AN127, titled "Flash Programming via the C2 Interface."

The chip acts as an "InterPose Processor" (IPP) that interposes between the Host PC, the Host, and the chip to be programmed, the Target. The IPP connects to the PC's serial port to talk to the Host. The IPP also connects to the Target's data and clock lines (C2D and C2CK) to program it using the C2 protocol. Thus, programming data is transmitted on a serial link from the Host to the IPP and the IPP uses this data to program the Target with a three-wire C2 connection. The IPP can read the Target chip and the send readout data back to the Host for verification.

The myforth 8051 programming software was used to develop the programmer applications. The application for the 'F300 chip is named PROG and the application for the 850 Toolstick processor is named PROG-850. The programmer software runs under Gforth, a free Forth system that is widely available for most Linux distrubutions.

Presently, the programmer can only be used comfortably in a Linux environment. It could be readily adapted to a Windows environment but, not to much purpose considering the availablity of the SL IDE for Windows.

In its most basic configuration, the programmer consists of a system board (i.e., an AGEN or 850 Toolstick board), a three-wire serial connection to the PC Host and a three-wire connection to the Target programming pins.

Design Considerations

Why not use the myforth Bootloader? -- The myforth bootloader is capable of downloading a program image to flash. This capability wasn't used for several reasons. One drawback is that the bootloader image needs to be initially programmed on the Target using the SL IDE. But, thereafter, the Target can reprogram its flash program memory via a serial connection to the Host. Although this doesn't eliminate the need for the SL IDE and Debug Adapter somewhere in the chain, this is not a compeling reason for not using the myforth bootloader for programming.

The serial port problem -- Unfortunately, the myforth bootloader has not worked well with modern PCs lacking hardwired serial ports. Most PCs now use a USB to serial converter to provide a serial link. We have found that these have not performed reliably (or at all) with the single-character binary handshaking used by the myforth bootloader. The main problem appears to be bootloader timeouts or hangups due to delays in the adapters. This is discussed in the Implementation section and is the main justification for using a standalone C2 programmer.

The programmer works with both hardware serial ports and USB to serial adapters, although programming throughput often suffers when using the USB to serial adapters. As noted above, this is discussed in more detail in the Implemention section.

Other considerations -- Another argument in favor of eliminating the dependency on a bootloader is that a standalone programmer does not require the re-mapping of the 8051 jump vectors (i.e., for the bootloader). Further, it eliminates the need to initially load a bootloader on the chip with the IDE. The programmer can write Target images containing the bootloader, however.

Page 4

Alternatives

Before launching into the C2 programmer project, it may be useful to consider several alternatives to programming SL chips with Linux that were investigated.

EC2DRV -- The first alternative was to use the "EC2DRV" software for Linux. It promised to allow the use of the SL USB Debug Adapter. Being a Linux newbie, the author could not get this (somewhat older) software to work, although it is likely that a more experienced Linux programmer could make it work.

Windows Emulator -- Another alternative was to use the Wine (or some other) Windows emulator to run the Windows IDE with the USB Debug Adapter. Although some thought this might work, others thought that the USB support for Wine was limited. It was difficult confirm whether or not Wine would support the SL programming environment. Again, being a Linux newbie, this appeared to be more of a research project than a straightforward solution.

Also, the myforth manual is in the process of being re-written to be Linux-centric. Describing the chip programming procedure with the requirement of first installing Wine seemed like an unneccessary complication for programming with myforth on a Linux Host.

Page 5

Features

The programmer features include the following:

• Environment -- The programmer is designed to operate on a wide variety of Linux platforms, including those with hardware serial ports and those using only USB to serial adapters. The system has been tried with a Pentium PC using four different USB to serial adapters and with a Raspberry Pi using its hardware serial port. Both systems are Debian-based but it is likely that the programmer will operate satisfactorily with most Linux distributions. The only required program is Gforth, which is available for almost all distributions and a wide variety of processor platforms.


• Ease of Use -- Although capable of being used interactively, most programming can be performed by executing a single command from the user's project development directory. The programmer is compiled in and executed from its own myforth project directory each time a chip is programmed. The only project overhead is a command script that must be added to the project directory for each application.


• Status Reporting -- The status of each programming session is displayed at the end of the session. Information includes the date, start and stop times, and errors encountered while programming (if any). Errors can be tracked to individual blocks. The Target is read back and compared with the original programming file and the location and number of errors are shown. The programming summary includes the Target chip detected and its ID and revision codes.


• Reasonably Fast Programming Times -- With a hardware-based serial port (e.g., Raspberry Pi), the programming and readout times for an 8K byte image is approximately five seconds (19.2K baud link). For a 32K image on the same system, the programming and readout times are each about 20 seconds.

  For systems using USB to serial adapters, the readout times are approximately the same. Programming, however, may take as long as 35 seconds for an 8K image. The programmer detects empty programming blocks and skips over them to reduce programming times for chips with small programming images.



• Single Character Command Format -- Mostly, the programmer automatically programs and verifies the Target. But, it can also be used interactively. To make interactive commanding easier, most commands consist of a single character. For example, the "p" command initiates a programming sequence and a "g" (get) command initiates a Target readout. Some commands use multiple characters, such as "rst" to reset the interposer and "diff" which compares the programming file and Target chip. But, multi-character commands have been minimized for the most frequently performed operations.


• Baud Rate -- The serial connection uses a rate of 19.2K baud but can be changed as needed.


• Low Power & 5-Volt Operation -- The AGEN module has an on-board 3.3 Volt regulator to allow it to operate from the 5 Volt supply. The AGEN module typically requires less than 10 milliamperes. The 850 Toolstick programmer operates from 5 Volts using an external 3.3 Volt regulator. It draws approximately 5 ma. Both programmers can be easily powered from the 5 Volt output on most USB to serial adapters or from the 5 Volt supply of boards such as the BeagleBone Black or Raspberry Pi.

---

Page 6

Features (Cont.)



• Reset -- If active, the interposer can be reset with an interactive command. Lockup of the IPP processor is rare. Host stalls are more common but also rare. Host lockups are easily remedied, even when operating over a SSH link, by issuing a Ctl-C, exiting Gforth and restarting the application.


• Target ID and Revision -- The "i" command provides processor information such as the Target ID and revision number, as read from the Target at startup. The current revision of the IPP firmware is also displayed at startup.


• Command or Interactive Modes -- Normally programming is performed by executing a command script and results are displayed automatically. But, the programmer can be exercised interactively with a large repertoire of commands, including utility functions that are useful for programming extensions.


• Assembled and Tested -- An assembled, tested and programmed PROG module is available as a BOBZ product. We can also furnish a pre-programmed Toolstick daughter card.


• Easy Firmware Updates -- Program updates for both versions of the programmer are available as a binary image and Intel HEX files. These can be used with the PROG programmer and a second programmer module to produce new programmers. The Intel HEX file can be used with the SL IDE and Debug Adapter on a Windows PC to program a PROG module. Similarly, the Toolstick adapter can be used with the SL environment to program the 850 Toolstick daughter card.

Physical

The AGEN system board used for the IPP programmer measures approximately 3/4 by 7/8 inches (~ 2 by 2.5 cm). The first page of this manual shows the programmer and Target modules mounted on a Parallax 3x5 inch prototyping board. The 850 Toolstick daughter card is approximately 2 by 2 inches (~ 5 by 5 cm), as shown in later sections.

Schematics

Power

Because of the low power requirements for both versions of the programmer, most USB to serial adapters can easily power the programmer.

Serial Data Link

The serial data link can be provided by a USB to serial adapter or by a direct connection to a hardwired TTL-level serial port (e.g., as shown for the Raspberry Pi). Connection to a hardwired port that operates at true RS-232 voltage levels will require a TTL to RS-232 adapter. These are inexpensive and commonly-available. These are discussed and shown in the manual for the BOBZ DCON product.

The data directions and designations for transmit (TXD) and receive (RXD) can be confusing because the perspective it is not often clear (e.g., is this to or from the PC or the chip?). To help clarify this, the schematic provides direction arrows and notes. Also, many USB to serial adapters have arrow designations. If your connections do not work, you might try reversing the connections. Although we are obligated to warn that this may damage some types of hardware, we have done this on several adapters and on the Raspberry Pi without damage (your mileage may vary).

For now, the serial data link operates at 19.2K baud. Assuming you are using minicom, we suggest you bring it up as root in the configuration mode (i.e., "sudo minicom -s"). This will allow you to set the com port and baud rate and save it in the default file. You can also specify that the current configuration be saved as a configuration file. These are named "minirc.xxx", where the "xxx" is a name you supply. Configuration files are normall stored in /etc/minicom and can be furnished as a command line parameter at startup (e.g., "minicom sb1" for a configuration file named /etc/minirc.sb1 specifying /dev/ttyUSB1 as the serial port).

Serial device mappings vary between Linux distributions but, using a USB to serial adapter, our large PC maps the first com device as /dev/ttyUSB0. The Pi has only a single port which maps to /dev/ttyAMA0. You can change these in minicom and save as the default or custom startup file, as above, so that you come up on the right device.

To find what devices you system has mapped at startup, use something like "dmesg | grep "ttyUSB" or "dmesg | grep "tty" .

Once you have a power and a serial connection to the programmed processor, we suggest changing to the programmer's project directory (e.g., ~/myforth/projects/prog-850) and executing the "p" command file (e.g., "./p") to see if the chip is alive. Without a Target connection, the operation will abort but it will still provide serial output to verify the connection.

Page 15

Target Programming Connection

Programmer Programming Connection

If you have a way to program the programmer using another C2 programmer, you may want to install a programming connection for the programmer.

Programming Cables

Two different programming cables may be required, depending on your development environment. In many cases, only one cable is needed.

If you are developing with one of the SL Target Boards (TBs), the programming cable consists of a ten-wire straight through cable with sockets on each end. This cable connects between the 10-pin programming connector on the Target Board and the corresponding 10-pin plug on the programmer. The length should be initially limited to six inches, although a length of eight inches worked for all of the Target Boards we tried (i.e., 'F300, 'F310 and 'F336 TBs).

A custom cable is required for development with application boards, where the Target may be in-circuit with only a 3-wire programming interface. The wiring for the custom C2 programming cable is shown in both schematics.

One easy way to make this cable is to first press a ten pin socket onto a six inch piece of 10-wire ribbon cable. Alternatively you can cut an end off of an existing cable. Because pre-made cables are commonly available, this is perhaps the easiest way to start.

Next, strip out the wires for pins 4, 7 and 9. These are usually color coded as yellow, violet and white, respectively. You can cut off the other wires close to the socket body, but we recommend leaving a small group of wires sticking out to provide a small pull tab. This makes it easier to pull the socket out of the shrouded (keyed) pin header.

Trim the three remaining wires to a length of 6 inches. These solder to the four- pin socket header. Prepare the header by cutting off one of the two inner pins. This is pin 3 and is used for keying. To key the header, insert a non conducting nib into the socket. The traditional way to do this is to insert the small end of a flat toothpick and break it off flush with the connector edge. Small plastic inserts are sold for this purpose, but are not readily available.

To ensure the header connections are not exposed, push some heat shrink on to each wire before soldering it to the socket pins. Thus, the heat shrink can be slid down over the socket/wire connection and shrunk to provide a neat insulated connection. You may also want to slide a larger piece of heat shrink over all three wires before wiring. This can be slid down on top of the three wires to provide some strain relief.

The easiest way to connect the socket header to the wires is to first tape the header down flat on a work surface and wet each pin and each wire with solder. Solder the white wire (the pin 9 ground connection) to the only remaining inside pin. Solder the yellow wire to the outside terminal next to the white wire. Solder the purple wire to the remaining outside pin (next to the keying pin).

The most common mistake made in assembling a ribbon cable for use with a shrouded (keyed) pin header is accidently reversing the cable when pressing it on the socket. To avoid this, we recommend performing a continuity check between the brown wire and pin 1 of the header. Pin one is identified by a small triangle molded into the shroud. For cables that are not color coded, the first wire is usually identified with a red or black stripe. If coding your own wire, use a permanent marker to put a stripe on the wire that connects to pin 1.

Page 18

Overview

Operational

The programmer commands and capabilities can be grouped as follows:

• Programming Commands -- These commands are directly related to programming a Target and include the "e" (erase) command, the "p" (program) command, the "g" (get Target data) command and the "diff" command to compare the programming data with the data read from the Target after it is programmed. An alternative programming command, "d" (download) is provided for buffered programming (e.g., at fast data rates).


• Option Commands -- The option commands allow the user to directly view the chip and Target buffers, copy the Target buffer to an image file, reset the programming interposer and reset the Target. Commands are also available to read the Target's ID, revision number and chip type. A command is also available to read out the version number of the interpose processor (IPP).


• Utility Commands -- These commands are mostly artifacts of the development effort and include primitives to read and write individual buffers, display pointers, etc.

The commands outline above can be executed interactively or as part of a bash shell script (herein called a command script). By integrating several primitives, programming operations can be bundled to provide ad hoc high-level functions that can be executed with a single command.

The prime example of this high-level functionality is the "pc" command script that is used to program the Target chip, read out the programmed chip and verify the programming, all in a single command. Other commands included within the "pc" script include checking for the presence of a Target, reading out its ID and revision and reseting both the IPP chip and the Target. The command script also adds date/time stamping for each operation and saves the programming results in a local file.

Other command scripts allow for interactive use of the programmer and performance of common operations such as chip cloning.

Page 19

Functional

The operational capabilities described above are implemented by combining the functionality available in Linux, Gforth and myforth. The role of each is described in following sections with supplemental notes in the Implementation section.

Linux -- The programmer is designed to operate in a Linux environment. The current system was implemented using the Debian distribution but should be easily adaptable to other distros such as Ubuntu which is Debian based.

The rationale for using Linux is that we have recently migrated our real-time work to Linux because Windows was a less suitable environment for what we wanted to do. The current project is the first Linux project and was necessitated by the apparent lack of SL programming capabilities on Linux. Also, the motherboard on our Windows PC died in a puff of smoke. Hello Linux!

One reason to use Linux was to take advantage of the inexpensive functionality provided by Linux-based products such as the Raspberry Pi. One direction for BOBZ products is to provide simple serial peripherals that will work with processors such as the Pi and the BeagleBone Black.

The availability of Debian (or closely related) distributions on many of these products is also convenient. To develop new products using our existing environment of myforth and SL chips requires a convenient way of developing new products without having to use a Windows machine for programming. The loss of productivity in going back and forth between two machines is unacceptable (as this project demonstrated).

One of the advantages of using Linux is the availability of Gforth on a wide variety of systems, spanning desktop PCs to small machines such as the Raspberry Pi. As Gforth is the basis for the myforth compiler and tether, this was essential.

Another important advantage of the Linux OS for a project of this type is the availability of many powerful system tools. The most important of these is the ability to use bash shell scripts to control the operation of Gforth and to provide system-level utilities such as I/O redirection, directory and file manipulation and other operations that do not make sense to do under program control.

Although the Linux learning curve was steep, once the basics were mastered, development became much easier and faster than in a Windows environment.

Page 20

Functional (Cont.)

Gforth -- Although Gforth was essential for using myforth on Linux, several features of Gforth in a Linux environment made the programmer much easier to develop. In fact, Gforth seems to be designed for such an environment. The ability of Gforth to compile source and execute commands from command line parameters makes the writing command scripts much easier. Although this capability is also available on Windows, the flexibility and functionality of bash scripts is much greater than with batch files, allowing complex operations to be performed in conjunction with Gforth. Gforth also supports input and output from standard system files such as STDIN, STDOUT and STDERR.

The primary disadvantage to using GForth on this project was a deficiency in the Word used to check for the availability serial characters. This formerly-working capability was evidently broken in a recent release and presently has to be corrected by recompiling the latest source from a git archive. This is discussed in more detail in the Implementation section.

For experienced Linux hands, fixing the Gforth serial problem is not a particularly onerous task. In fact, our "big" Linux machine was remotely updated by Bill Kibler (this site's host). Bill also provided step by step instructions for the Raspberry Pi and BeagleBone Black (see his Blogs at this site). But, we did not want to develop a project that requires an update of Gforth.

Accordingly, the programmer uses only "blocking I/O" for responses from the IPP. With blocking I/O, the Host waits forever for a character, if necessary. This limitation has not caused any major development problems and allows the use of any Gforth version that is commonly available (e.g., that for the Raspberry Pi).

myforthThere is little to say about myforth except that it was originally designed to operate in a Linux environment. Functionally, myforth is used to implement the Interpose Processor (IPP) that "interposes" between the PC Host (Host) and the chip to be programmed (Target). The IPP uses Charley Shattuck's standalone interpreter (~450 bytes) to execute commands sent from the Host by a Gforth program.

The design approach for the programmer is somewhat different from other BOBZ projects using a standalone interpreter on the chip connected to the PC. Interactive commands are not sent directly to the IPP by the user. Gforth controls the serial port and issues commands as part of executing a Gforth Word (usually one of the same name as that defined in the IPP).

The final result is that the IPP does not do very much but issue C2 commands, manage buffers and report errors. The IPP program is only 3.1K bytes, including interrupt vectors and a few hundred bytes of on-chip dictionary entries.

Page 21

Commands

Introduction

The following describes the primary programmer commands. There are a number of other commands that the programmer can execute that are not specifically described but may be mentioned as they relate to primary commands. All programmer commands are listed in the Help menu and the Utilities menu. These menus are displayed with the "h" and and "u" commands, respectively.

The brief descriptions provided in these menus are, hopefully, sufficient to understand their purpose and operation. For further understanding of how they work, refer to the source code.

The following not only describes the functions of the various commands but also provides some detail on how they are implemented. High level implementation requirements and details are described in more detail in the Implementation section and in the source code.

There are two ways of implementing commands. The first method directly invokes a command by executing a Gforth routine (Word). The second method issues a command by calling a command script.

The the most-used command is the "pc" command which programs the Target, reads it back and compares the Target programming with the chip programming data. This command is implemented using the second "command script" method: it combines several programmer primitives within a command script, along with system commands to control output and adds system information (e.g., date & time) to the results file. Many of the primitives used in the command scripts are introduced in the "pc" command Section. The direct primitives are also described individually in later sections.

Page 22

pc (program chip)

The "pc" command is the primary command used to program a Target chip. It is implemented as a command script. A copy of the "pc" command script resides in each of the user's project directories and is executed from that directory during application development.

The "pc" command can be executed by entering "./pc" at a console prompt. The "./" part of the command tells the shell to look for the command script in the current working directory. Because the "pc" command is so commonly executed, we advise creating an alias for this command and putting it in the .bashrc (or the .bash_aliases) file in your home directory. The alias definition is: alias pc='./pc' .

The contents of the pc script are shown in the inset below. The script copies the binary image of the compiled application, chip.bin, to the programmer's directory as target.bin . At startup, the programmer reads target.bin into a "chip" buffer and uses this buffer image to program the Target.

Note: compile your myforth application (e.g., using "./c") just prior to issuing a "pc" command to ensure that the latest version of your application is programmed into the Target. You may also want to define an alias for the "./c" command.

# pc -- program chip  -- 10Aug13 rjn
# 
# put this script in your project development directory
#
# set -x
# 
declare -x PROJ="/home/bob/myforth/projects"
cp ./chip.bin ${PROJ}/prog/target.bin
# cp ./chip.bin ${PROJ}/prog-850/target.bin
echo "Start PROG Programming Session: " > ./pc.txt
date >> ./pc.txt
echo "PLEASE WAIT: programming and verifying Target chip"
${PROJ}/prog/pcx >> ./pc.txt
# ${PROJ}/prog-850/pcx >> ./pc.txt
# date '+%T' >> ./pc.txt
cat ./pc.txt

After copying the programming file, the pc script sends startup text to a file in the current project directory, named pc.txt . This file is populated with other programming status information and eventually displayed to show the results of the current programming session.

After writing the startup message to the status file, the pc script calls another script, pcx, in the programmer's directory, that does the actual programming. Lastly, the pc script displays the pc.txt file to show the results of the programming.

Note that the results of the last programming session are always available in the pc.txt file. To display the programming results, execute "cat ./pc.txt" at the terminal's prompt.

Page 23

pc (program chip) Command (Cont.)

To understand how the "pc" command is implemented, refer to the inset below that shows the contents of the pcx command script.

# pcx -- PROG C2 programmer -- 17Aug13 rjn
# 
# calls Gforth -- executed by "pc" command in user's project dev directory
#
# set -x
# declared exportable in pc script:
# declare -x PROJ="/home/bob/myforth/projects"
#
cd ${PROJ}/prog
# cd ${PROJ}/prog-850
/usr/local/bin/gforth-0.7.9-20121007 \
        -e "fpath path+ ./ " \
        -e " 1 value com? " \
        -e " 19200 value current-baudrate " \
        ./serial-linux.fs  ./job.fs  \
        -e " open-comm  read-chip .chip-size  cr rst" \
        -e " cr cr v .(  C2 Programmer: enter h for help)" \
        -e " cr ?target space i" \
        -e " cr p  cr g cr diff cr .fin  tr bye "
# use this line instead of the one above for buffered programming:
#       -e " cr d  cr g cr diff cr .fin  tr bye "

The first line of the pcx script changes the working directory to the programmer directory. The next line calls Gforth. Following lines are continuations of the Gforth command line. The continuation lines starting with "-e" are commands for Gforth to execute at startup. The lines consisting of file names specify source code to be compiled by Gforth. Here is a breakdown of what each of the lines do:

• -e "fpath path+ ./" -- add the current directory to the Gforth path
• -e " 1 value com?" -- maps the serial port that communicates with the IPP (also see the Implementation section)
• -e " 19200 value current-baudrate" -- establishes the baud rate
• ./serial-linux ./job.fs -- compiles the source code for the serial port driver and for the programmer itself. The myforth job.fs file is the master "include" file for the programmer application. Note that this includes both Gforth source and source for the IPP.
• -e " open-comm read-chip .chip-size cr rst" -- opens the comm port, reads the Target programming file (target.bin), sends the size information to the pc.txt file (in the user's directory) and adds a carriage return and reset the IPP.
• -e " cr cr v .( C2 Programmer: enter h for help)" -- sends two carriage returns to the pc.txt file, adds the IPP chip's version number and adds a program startup string.
• -e " cr ?target space i " -- sends a carriage return to pc.txt, checks for the presence of a Target chip (with ?target), sends a space to pc.txt and adds information read from the Target such as chip ID, name and revision.
• -e " cr p cr g cr diff cr .fin tr bye " -- sends a carriage return to pc.txt, programs the chip ("p" command), sends a carriage return, gets the Target contents (the "g" command), compares the programming file's image with the Target's image (the "diff" command), adds a carriage return, adds the current time, resets the Target (with "tr") and exits Gforth (with "bye"). Whew!

Page 24

pc (program chip) Command (Cont.)

Photo 3 shows the results of programming session after the above commands have been executed.

p (program) and d (download)

The "p" command is used to directly program the chip. It is defined as a Gforth command and can be executed interactively or as part of a command script, as described in the "pc" Section above.

There is also a "p" command script to start up the programmer in interactive mode. This is a bit confusing at first, but becomes more natural with use -- the command script invokes the standalone programming mode in preparation for using "p" command to program the chip.

The inset below shows the contents of the "p" command script.

# PROG C2 programmer -- 19Aug13 rjn
# 
# set -x
/usr/local/bin/gforth-0.7.9-20121007 \
        -e "fpath path+ ./ " \
        -e " 1 value com? " \
        -e " 19200 value current-baudrate " \
        ./serial-linux.fs  ./job.fs  \
        -e " open-comm  read-chip .chip-size  cr rst" \
        -e " cr cr v .(  C2 Programmer: enter h for help)" \
        -e " cr ?target space i tr"

The script given above is similar to the one used for the "pc" command. It starts up Gforth, compiles the programmer application, initializes serial communications, reads the programming image, resets the IPP, displays the current revision, checks for the Target and reads out its ID information.

The main difference between the scripts is that the "p" script does not perform any programming, readout or verification. More importantly, it does not exit from Gforth: it is left available for directly executing programmer commands. Typically, the first direct command executed after startup is the "p" command.

Photo 4 shows the startup screen produced by the command script in the inset above.

g (get), f (fetch), idump and cdump

The "g" command gets the contents of the Target chip. Normally, the command is used by the "pc" script to get the Target contents for verification. It can also be used during interactive programming to get and save a Target image. Both of these uses are described in previous sections.

When the "g" command executes, it saves the bytes downloaded from the Target in a Target image buffer. This buffer is used by the "diff" command to compare against the contents of the programming buffer. It is also used by the "save-image" command to write a Target image to the target.img file.

The "f" command is similar in operation to the "g" command but it performs a buffered read of the Target. The "f" command is of limited usefulness because buffering is never required on output from the IPP to the Host PC. Buffering is useful only on input and only if the Host transmits characters faster than the programming algorithm can handle. Programming an entire block takes just over 2 milliseconds, or approximately two character intervals at 9600 baud.

Because of the questionable usefulnees of the "f" command, it is not available on the 850 programmer.

It is sometimes useful to directly examine the Target image buffer. One such use is to examine bytes for ASCII-coded messages such as the program name and revision. We commonly embed the program name and rev (date) near the start of the first flash code block. For the 300 and 850, this is near $233, just after the interrupt vectors. Photo 6 shows a dump starting near this offset in the Target image buffer. In this example, the program name is "ITEST" and the revision is "130819" (August 19th, 2013).

diff

The "diff" command compares the contents of the Target and chip buffers, byte by byte, producing a results display with the total number of buffer bytes, the total number of matches and the total number of errors. The results are displayed in both decimal and hexadecimal.

If there are mismatches, the "diff" command displays the address of the mismatch, in addition to the normal summary information. This sometimes produces a large screen full of addresses, especially if the Target image has not been loaded with the "g" or "f" commands. Of course, you can save the target image to target.img and use the Linux diff command to compare it to the target.bin file. You can do this at a Gforth command prompt by shelling out with the "sh" Word.

i (info) and v (version)

The "i" command reads the ID and revision information from the Target and displays it. Also displayed is the chip type, if it can be decoded. The programmer can decode all of the chip families given in Table 10 in the SL application note AN127 with exception of the few chips that have FPDAT addresses other than $b4 (0xB4).

The chip families not decoded are 'F34x, 'F38x, 'T62x (OTP) and 'T32x (OTP). Adding support for these chips is straightforward (see the C2.fs and commands.fs source code files). Although the C2 primitives defined in the C2 source code can be used to modify the rom in the One Time Programmable (OTP) chips, this has not been done.

Note that the "i" command is normally executed after it has been determined that a Target is present. In the "pc" script, this is done by the "?target" command. It is also done whenever an interactive session is started. The "?target" command can be executed from the Gforth command line but is not much use after an interactive session is in progress. If a Target is not detected, in either command or interactive mode, the program aborts with an error message (manual intervention is required).

The "v" command reads the program name (PROG or PROG-850) and revision number (coded date) from the IPP. This is displayed in both interactive and command modes. A typical revision number would be 130817 indicating an IPP compilation date of August 17th, 2013.

Page 29

e (erase)

The "e" command erases the Target chip. The "p" and "d" commands both erase the chip before programming. All flash bytes in an erased chip are $ff. The "p" command examines the next block to be programmed and, if it consists of all $ff bytes, does not send the block to the IPP. However, it does send data to the IPP to adjust its current programming address. On the 850 programmer, both the "p" and "d" commands check for blocks (or partial blocks) that do not need to be programmed.

The ".adr" command can be used to display the current value of this address, although this function is primarily of use when transmitting individual blocks (see the commands.fs source code file and the "u" menu).

rst (reset IPP) and tr (Target reset)

The "rst" command sends a command to the IPP telling it to reset itself. The IPP does this by jumping to its cold start vector. This command is executed to ensure that the IPP is in a known state before starting a programming session.

The "tr" requests the IPP to reset the Target. This reset is performed with a C2 reset command (i.e., the Target's reset line is held low for approximately 40 microseconds to force a reset). When the Target is being programmed in-circuit, the "tr" command may be needed to force the Target to restart and perform normal initialization after programming. Note that powering down the IPP also resets the Target.

Page 30

clone (copy chip)

The "clone" command is implemented as a command script. The inset below lists the contents of the clone script. Note that it resides in programmer application directory (e.g., the ~/myforth/projects/prog directory).

# clone -- clone a chip from target.img  -- 13Aug13 rjn
# 
# resides only in the PROG directory
#
# ======================== CLONING A CHIP ===================================
#
# 1. Put the chip to be cloned in the Target socket.
# 2. Change to the prog directory (e.g., using the "prog" alias).
# 3. Bring up the programmer in the interactive mode with the "p" command
#    and execute either the "g" or "f" commands.  This copies the Target 
#    image to the image buffer.  Execute the save-image command tos save the
#    buffer image to the target.img file in the prog directory.
# 4. Remove the chip to be cloned from the Target socket and insert a
#    new Target.
# 5. Execute this script to rename target.img to target.bin and program
#    the new Target with the cloned image.
# 6. You can repeat the cloning process by inserting another new Target chip
#    and executing "clone" again.
# 7. Note: Many chips now have the version number embedded at the start of rom
#    (e.g., $233 for the 300 chip).  See the job.fs file in the prog directory
#    to see how to do this.  If the revision string is present at the start of
#    rom, you can execute "$233 idump" after executing the "g" or "f" commands 
#    to see a decoded dump of the revision string.
#    This is generally a good idea so that you can confirm the revision number 
#    of the chip you are cloning.
#
# set -x
# 
declare -x PROJ="/home/bob/myforth/projects"
cp ./target.img ${PROJ}/prog/chip.bin
./pc
echo " Target cloned from target.img"

The above command script provides the information needed to clone a chip. To clone a chip, first use the interactive mode ("p" command) to read the Target to be cloned with the "g" command. Save the Target image to the target.img file using the "save-image" command. Once the Target image is saved, exit the interactive mode (with "bye") and insert a new Target chip in the Target socket.

Executing the clone command (e.g., "./clone" from the programmer directory) programs the new chip with the copied Target. The "clone" command copies the target.img file to the programming file, chip.bin, and programs a new Target by calling the "pc" script. If you have the binary programming image of the Target to be cloned, copy it to chip.bin, executing "clone" as many times as needed to program the new Targets. After cloning, you may want to recompile the programmer source (e.g., using ./c or ./p) to ensure that chip.bin contains the latest version of the IPP.

Page 31

Command Summary

Page 32

Command Summary (Cont.)

Page 33

Requirements

The development and execution environment for the programmer requires both Gforth and myforth.

Serial Connection

The serial data link to the IPP is normally made with a USB to serial adapter or a hardwired connection.

Most newer PCs lack a dedicated serial port. It is relatively easy to install a USB to serial adapter on a PC without a hardwired serial connection. Normally you only need to plug in the adapter and the operating system will find it. In rare cases you need to reboot.

Assuming you have rebooted with the adapter plugged in, you find out how it was mapped to a device file by executing something like "dmesg | grep "ttyUSB*" at a console prompt. On my "big" system the two adapters that I have connected were mapped to ttyUSB0 and ttyUSB1.

Whatever the mapping, you must edit the ~/projects/prog/serial-linux.fs file to agree with the serial device you are using. In the file around line 41 you will see: here ," /dev/ttyUSB0". Replace the "ttyUSB0" with the device name you are using.

If you are using a processor with a hardwired serial port, the device name must also be changed to agree with the startup mapping. For the Raspberry Pi, the serial port is hardwired and mapped to "/dev/AMA0" -- there is a line that is commented out in the serial-linux.fs file to make it easier to change to the Pi.

Four different USB to serial adapters were tried with my (somewhat older) Linux PC. All have worked without problems. These adapters all use either the FTDI or CP2102 chips. The one I like best is the FTDI Friend from Adafruit but it costs around $15.

Page 34

We include a USB to serial adapter with one of our products. We buy these on EBay from Chinese suppliers for about $3 each. We have tried two different kinds and both work. We have also tried (and like) the FT-232R Breakout board from Sparkfun but it is a bit of overkill for this simple application.

No matter what USB adapter you use, be prepared for somewhat slower downloads. All of the adapters we have used seem to be slow in delivering bytes to the programmer. The receive speed is what you would normally expect.

The slow delivery may be related to on-chip buffering or to the USB drivers. We are confident that the problem is not with Gforth, although it does have its own serial "issues" (see below).

Examining the startup messages associated with some of the adapters we have noted a mention of a 64 byte buffer on some of them. Even with buffering, the serial rate should not be more than twice as slow, as we have observed it to be.

The cure for this is to use real serial ports but this is not always an option on newer PCs. We solved the problem by using the Raspberry Pi to run the programmer. We now routinely program applications by establishing a SSH link to the Pi and executing the programming commands from the "big" machine.

On the Pi, both programming and readout are as fast as one would expect for the baud rate. Thus, without skipping any blocks, a 'F300 chip can be programmed and verified in 10 to 12 seconds. With a USB to serial adapter and no block skipping, just programming a 'F300 can take around 35 seconds at 19.2K baud.

Here are the approximate times we recorded for various operations using Raspberry Pi:

• p (direct program) -- 5 seconds
• f (buffered read) -- 7 seconds
• g (unbuffered read) -- 5-6 seconds
• d (buffered program) -- 7 seconds

For the sake of completeness, here are the typical times for a USB to serial adapter at 19.2K baud:

• p (direct program) -- 31-33 seconds
• f (buffered read) -- 9 seconds
• g (unbuffered read) -- 5-6 seconds
• d (buffered program) -- 33-35 seconds

Page 35

Gforth Problem

As mentioned earlier, there is a problem with the Gforth Word to check for a serial character being ready. The problem is in the definition of key?-file. If a Word using this is used to check for a serial character being ready, it will hang. The normal serial input works, but it uses blocking I/O and will wait as long as needed for a character.

To avoid this problem, the PROG software was designed to only use blocking I/O. We have not had any major problems using this, but IPP Words were designed to always return a single character response (except for some Words such as "v" which expects a fixed number of bytes). This design allows the programmer to be built that is compatible with any verision of Gforth.

Fortunately, this problem has been fixed and the next release should work. Also, the fix can be applied to existing systems using the latest files in the git archive. Bill Kibler has done this for several PCs, including my "big" system and for his BeagleBone Black. The fix requires recompilation from source and a working Gforth (any revision). Although the serial problem does not affect the PROG programmer, users interested in the fix may contact the author for assistance.

Page 36