Go to the first, previous, next, last section, table of contents.

Using the ARC serial interaction program

The ARC serial interaction program, arc, is the link between the host computer and the target embedded system. After a program has been written and compiled on a host system, arc is used to download the program and interact with it over the serial port.

In normal use, arc is the main program a user of the ARC development system will interact with. Many other programs are involved in process of compiling and executing code, but they mostly work in the background. If you specify a .c source, or .lis list file to any of the arc load commands, arc will automatically invoke arcc to compile the program before download. In the case of compile errors, the errors are reported and the download aborted.

arc also provides an interpreted C interaction environment with the ability to access and modify global variables and call functions on the board which is very helpful for debugging. After reading in the symbols as a side effect of a load or file command, you can type most valid C expressions at the arc> prompt and they will execute interactively on the board.

Overview

The arc program is both the most central part of the ARC Development System, and the most confusing. To explain what arc is, it is perhaps best to go back to the beginning and explain what arc used to be.

The program which has evolved into arc started life as term, a serial-port terminal program similar to kermit, but much simpler, written by Randy Sargent. All that term did was echo characters from the serial port to the screen, and from the keyboard to the serial port. Features were sometimes added to term to do things like download S-records over the serial port when particular escape characters came from the keyboard. term was an excellent tool for dealing with serial interaction to single-threaded processor boards, and stayed largely unchanged for years.

Then I wrote a multitasker for the 68332, and wanted to be able to interact with the various processes, each over an individual serial stream. term was too limited for this task, so Randy made a new version which could deal with input from and output to multiple streams, each in its own X window. The streams were multiplexed onto a common serial port using a simple stream-break protocol. This new program was called multiterm.

Later, we decided to try to interface a process on the board to the gdb remote protocol to allow symbolic debugging. We wanted to be able to interact with the board while at the same time debugging it using the gdb remote protocol. We added to multiterm the ability to create bidirectional streams to other programs over sockets, and multiplex those streams over the serial port to the board as well.

Using multiterm and gdb connected together via sockets like this worked, but it was very confusing to use. We also had problems because gdb was very difficult to modify, and it did not interact well with multitasking. So we set out to integrate the functionality of multiterm and gdb together into a single, easy-to-use program called arc.

Like multiterm, arc is at heart a multi-streamed serial interaction program. However, because arc is also used to load programs and perform many debugging features, it also has a prompt which you interact with as if it were a shell. Balancing these features is somewhat difficult. It would be much easier to understand what is going on if it were not possible to interact directly to different streams and processes, but I believe that the benefits outweigh the problems.

Using ARC

In using arc, there are two modes, prompt and passthrough, and two types of windows, the root window and process windows.

Prompt vs. passthrough mode

In prompt mode, you type commands at the arc> prompt and arc interprets the command. As a result of commands, serial data may be exchanged with the board, or it may not. Any characters which are received from the board are still printed to the screen, even though you are in prompt mode, but characters you type are not sent directly to the board.

In passthrough mode, each character you type is sent straight through to a serial stream to the board, and each character you see printed came from the board.

In any window, you can switch between prompt mode and passthrough mode by typing control-x (hold down control while typing x -- usually denoted as ^x).

ARC root window

The root window is the part of the arc interaction which remains in the window in which you invoked arc. The root window actually interacts with three separate processes on the board and multiplexes their streams all into the same window. The three processes are:

Certain arc commands executed at the prompt in the root window will cause the root window to enter passthrough mode until some completion sequence is received from the board. For example, executing any console commands will place the root window in passthrough mode until the console command completes, and executing interactive functions will place the root window in passthrough mode until the end-of-function message is received from the debugging process.

At any time, you can toggle between passthrough and prompt mode by typing ^x (control-x), but be aware that in the current version, entering passthrough mode manually may result in connecting you to the dummy process, which does not respond when it is not in the process of executing code. If you hit return and do not get a prompt, you are probably in passthrough mode, and you should type ^x to return to prompt mode.

Additionally, if you are executing an interactive function call, you can type ^c (control-c) to halt the dummy process so you can debug it. This will also have the effect of placing you in prompt mode.

Process windows

When arc receives serial from the board on a stream other than the three system streams (see section ARC root window), it brings up an xterm communicating with that stream. By default, when a process window is brought up, it is in passthrough mode.

Because arc and the board are not tightly synchronized (a decision made for runtime performance reasons), arc does not necessarily know that a stream has been created until it says something. If you want to bring up a window to interact with a stream that has not yet said anything, use the window command from the arc> prompt, either from the root window or in prompt mode in any window (see section ARC commands).

If you want to debug a process, go to its window (if it doesn't have one, create it) and type ^c (control-c). This will send a message to the board to halt the process associated with the window. After that, you can use the where command in the halted process' window for a stack backtrace, or the cont command to continue the process and return to passthrough mode.

At any time, you can toggle between passthrough and prompt mode manually by typing ^x (control-x).

ARC commands

Commands recognized by arc as console commands are passed through to the console process on the board. For details on console commands, see section User console.

Additionally the following arc-specific commands can be typed at the arc> prompt:

`ramload <filename> [-addr <start-addr>] [-nosyms] [<arcc args>]'
`romload <filename> [-addr <start-addr>] [-nosyms] [<arcc args>]'
`kernelload <filename>'
`bsload <bootstrap> <loader>'
These commands are all used to download programs to the board. Different commands are appropriate for different uses. See section Loading files in ARC for details.
`file <filename>'
Read the symbol table of the specified executable file, but don't download it to the board. Use this if you want to debug a program which is already on the board. Be careful using this, as there is no way to for arc to check that the symbol table you are reading in is the same as the program which is resident on the board. For this reason, it is generally safer to use the symbol table which is loaded as a side effect of loading the program.
`hostbaud <baudrate>'
Change the host baud rate unilaterally. Default value for the baud rate is 38400.
`baud <baudrate>'
Change the board and the host baud rate. The board and host must already be at the same baud rate for this to work.
`window <pid>'
Create new window talking to the process with the specified process id. Use the ps console command to determine the correct pid to use.
`cd <dir>'
Change current working directory to on the host to <dir>.
`pwd'
Print the current working directory on the host.
`cont'
Continue a process being debugged. If executed in a process window, it continues the process associated with that window. In the root window, it will continue the default interaction process if it is active.
`where'
Print the stack backtrace of a process being debugged. This should be executed at the prompt in a process window in which the process has been broken (either due to a crash or by typing control-c). See section Process windows for more information.
`log <logfile>'
Start logging the window log was executed in to <logfile>.
`endlog'
Turn off logging in the window endlog was executed in.
`help'
Display this list for the version of arc you are using.

Loading files in ARC

There are three different kinds of files which can be downloaded to the board.

User programs and libraries
These are programs compiled using `arcc'. They are linked against kernel, but are placed elsewhere in memory from kernel. Therefore kernel is capable of loading and unloading this kind of program.
Kernel
The kernel contains the operating system and libraries which are shared by all user libraries and programs. See section Kernel for more information. Most programs are downloaded by arc sending download messages to the kernel. Unlike user programs, most of the kernel runs in ROM, and you can only download the kernel on 332 systems with EEPROM. This includes only Tattletale boards and modified Vesta boards. Because the kernel cannot load over top of itself, so you cannot upgrade the kernel using the regular load commands.
Bootstrap
Starting with version 0.980 of the kernel, a bootstrap program is available for EEPROM equipped 68332 systems (Tattletale and modified Vesta boards) which is capable of booting the system and downloading new kernels. A special arc command allows downloading new bootstraps.

These different kinds of files require different programming strategies, and therefore have different arc commands.

Loading user programs and libraries in ARC

ramload <filename> [-addr <start-addr>] [-nosyms] [<arcc args>]
romload <filename> [-addr <start-addr>] [-nosyms] [<arcc args>]

The ramload and romload commands in arc allow loading user programs and libraries. ramload downloads the program only to RAM, which is volatile memory and may not persist across power cycles. romload downloads the program both to non-volatile EEPROM and to RAM. When the board starts after a power cycle, it will find the programs stored in EEPROM aand restore them automatically.

While ramload works for any board, romload only works for boards equipped with EEPROM. This includes all Tattletale 332 boards, and specially modified Vesta 332 boards.

Both of these load commands are capable of loading pre-compiled executables, or calling the compiler and downloading the result. If the file specified is an a.out format executable or S-record file (`.s19' extension), it is downloaded directly (without recompilation).

If the file specified is a .c source, or .lis list file, arcc will be invoked to compile the program before download. In this case, any extra arguments on the command line are assumed to be arcc flags and are passed through to the compilation. See section Compiling programs under ARC for more information about arcc flags. In the case of compile errors, the errors are reported and the download is aborted.

Programs are not relocatable once they have been linked (the final stage of compilation). Therefore, a given program can only be executed when it occupies the particular place in memory at which it was linked. The ramload command reads this location from the executable and downloads it there by default. The romload command, on the other hand, is not constrained to loading to a particular address. The copy of the program in EEPROM is there for nonvolatile storage, and must be copied to RAM before being executed. Therefore arc will communicate with the board to find a free block in EEPROM and download the program there. After download the EEPROM, the program is automatically copied to the appropriate location in RAM and can be executed immediately.

The optional -nosyms flag will prevent the symbol table from being loaded. Symbol tables are somewhat large and slow to load, so this option allows you to speed downloads by skipping this step when you do not intend to debug the program right away.

The optional -addr flag followed by an address is used to specify the memory address to download the program to. In general, you should not need to use this argument, as both load commands should come up with reasonable addresses on their own. You can override the automatic download address with the -addr flag. This is generally pointless in the case of ramload, but it is sometimes useful to override the placement selected by romload with your own choice. Use the memmap and memfree console commands to help you decide what locations would be good (see section Viewing memory usage).

Note that he -addr argument does not affect compilation, only download. See section Using arcc for information on how to set the location at compile time. In particular, look at the the CODE_ADDR environment variable and commandline option.

Loading multiple C files in ARC

There are three different ways to load a program consisting of multiple C files using ARC, listed in order of increasing difficulty and increasing functionality:

Specifying multiple C files in load line in ARC

The simplest way is to specify multiple C files on the same line when you use the `ramload' or `romload' command in ARC. (Both `ramload' and `romload' work the same way with respect to this feature, so the use of ramload in these examples is arbitrary).

arc> ramload file1.c file2.c

Note that including multiple files in the same ramload command as shown above is very different than specifying them in separate commands as below:

arc> ramload file1.c
arc> ramload file2.c

The first example will result in `file1.c' and `file2.c' being linked together into the same executable. The second example will result in `file1.c' and `file2.c' being compiled into separate executables. Unless the CODE_ADDR arcc option is used to link the two files to non-overlapping addresses, `file2' will be written over file1 and `file1' will be lost.

Note that while in other respects the behavior of ramload and romload are similar, at the current time the above example would have a different result if romload were used. In that case, both programs would be downloaded to EEPROM and the overlap would not be noticed until the programs were restored. This aspect of romload behavior is still undergoing specification, so just be aware that this may lead to unexpected results.

Using list files

An even better way of loading multiple files is to create a list file. This is a file with a `.lis' extension which lists the files you want to load together, as well as relevant compile flags and options. For example:

List file prog.c:

file1.c
file2.c
CODE_ADDR=0x108000
KERNEL=vestaboot.986
-O2

In this example, the first two lines contain source files to link together. The next two lines contain arguments to arcc which affect how the program is linked (see section Using arcc), and the last line contains a compiler flag which arcc passes along to gcc.

To load the list file type:

arc>  ramload prog.lis

This will compile `file1.c' and `file2.c' together into an executable named prog and download that program to the board. (You could also have used `romload' to also load a copy to EEPROM).

Using Makefiles

Using `make' and Makefiles is very complex, and a full explanation is outside the scope of this document.

The basic idea behind using `make' is that you set up rules in a file (usually called `Makefile') in your project directory that describe how to convert source files into object files. When you run `make', it checks if any source files are more current than their associated object files. If it finds any more current source files, it executes the specified commands to convert the source files into the object files.

At this point, there is no support inside arc for calling make automatically. Therefore, if you are using makefiles it is necessary to compile the file in a different window, then download the resulting executable using one of the load commands described above.

An example of using `make' with the ARC development system to compile source files `foo.c' and `bar.c' into the executable file `baz' is as follows:

The following text is in a file named `Makefile' in the same directory as `foo.c' and `bar.c'

all: baz

baz: foo.c bar.c
        arcc foo.c bar.c -o baz

To compile baz, you can then type `make' in that directory.

Makefiles are good in that they check modification times and only do the compiles which are necessary. However, they are very hard to use. Unless you are already used to using Makefiles, I recommend that you use list files instead (see section Using list files).

Loading a new kernel using ARC

kernelload <filename>

NOTE: This only works on systems with EEPROM (Tattletale and modified Vesta 332 boards).

The kernelload command uses the bootstrap to download a new kernel. You cannot use the kernelload command until you have installed a bootstrap. If a bootstrap is installed, the board will say something of the following form at 38400 baud at boot time:

BOOTSTRAP 1.0

If your board does not say this, then you need to install a bootstrap. See section Loading a new bootstrap using ARC for details.

The filename provided to kernelload can be either an a.out executable file or an `.s19' file. Generally this would be the same file as you would link your programs against, for example `vestaboot.986'. See section Choosing the kernel which is right for you for details.

Once you know that you have a bootstrap installed and know which kernel you want to load, run arc at 38400 baud. For example, arc -port <port> -baud 38400.

Definitely do not use the -saphira or -saphira_stop options as these will cause the baud rate to be set at 9600, which will not work for this application. Then execute the kernelload command. It will prompt you to ask whether you know what your are doing:

arc> kernelload /usr/local/arc/332libs-0.986/vestaboot.986
This command only works if you've installed a bootstrap
in your eeprom.  If you currently are using a pre-0.981
kernel and haven't loaded a bootstrap with `bsload', please
locate instructions for loading the bootstrap first
Do you wish to download a new kernel at this time? (y/n) 

Answer 'y' to continue. It will prompt you to turn off the processor board and press return to continue.

Please turn the processor board back on.
Download will start when arc has synchronized with the bootstrap
arc> 

When you turn the board back on, the kernel download will begin. (The reason for turning the board off and on agan is that the bootstrap is only active at boot time, and waits for a second to hear whether arc has a program to download to it. After you have turned the board off, arc will start sending download commands so that the board will hear it immediately when it starts back up.)

The download takes a while, during which the bootstrap will print out its progress frequently. Wait until it is done, the turn the board off and back on again. With any luck, it will then be running a new kernel.

Be sure to relink and reload all of your programs after changing the kernel you are using, as all programs link against the kernel and therefore depend upon it. As part of the compilation process arcc includes version information for dependency checking, so the board should catch any version problems and refuse to run the outdated programs.

Loading a new bootstrap using ARC

bsload <bootstrap> <loader>

NOTE: This only works on systems with EEPROM (Tattletale and modified Vesta 332 boards).

It should only be on rare occasions that you would need to download a new bootstrap. It should not change very often. It does not have any dependencies on the kernel version, etc. However, it is necessary to do this once if you have pre-bootstrap EEPROMS, and it may be necessary to upgrade the bootstrap at some point.

The bootstrap and loader programs should be in the main kernel directory (for example, `/usr/local/arc/332libs-0.986'). You will need to cd into that directory (or specify the full paths) to download the bootstrap. The current versions are called `vbs-1.1' (the bootstrap) and `vrbs-1.1' (the loader). The bootstap is loaded to EEPROM and stays resident until another bootstrap is loaded. The loader is temporary and is only needed because you cannot simultaneously write to and run from EEPROM.

Run arc at 38400 baud. For example, arc -port <port> -baud 38400. Definitely do not use the -saphira or -saphira_stop options as these will cause the baud rate to be set at 9600, which will not work for this application.

arc> cd /usr/local/arc/332libs-0.986
arc> bsload vbs-1.1 vrbs-1.1
This command loads a bootstrap into your EEPROM If your
EEPROM already has a bootstrap, you shouldn't need to do this.

If you a kernel version 0.980 or earlier, you are not currently using
a bootstrap in your EEPROM, and will need to install a bootstrap
in order to upgrade your kernel.

Warning:  Don't turn your board off during this download, and
do not attempt this download over a radio modem.  If the download fails
your EEPROMs may no longer boot, and you'll need to get replacements

Do you wish to download a boostrap at this time? (y/n) 

Answer yes. It will then first download the loader to RAM:

Download vrbs-1.1 (a.out file, gdb protocol)
NOT LOADING SYMBOL TABLE.
Downloading code (0x107000-0x107f5f)..............
Downloading global initializers (0x107f60-0x107f7f).
arc> 

Then it will run the loader and use it to load the bootstrap:

Running loader (at address 0x107000)

EEPROM LOADER 1.1
Calling load command
in download_aout_rest
Download vbs-1.1 (a.out file, gdb protocol)
NOT LOADING SYMBOL TABLE.
Downloading code (0x0-0xec3)Writing 0-3F...
.Writing 40-7F...
.Writing 80-BF...

When it is done, it will print:

Bootstrap download completed.

Please reset or power-cycle board.

Now you will have a new bootstrap installed. If you were installing a new bootstrap with a post 0.981 kernel, the kernel will probably start up when you reset. If you were installing the first bootstrap in EEPROMs with a pre 0.981 kernel, you will need to use kernelload to download the kernel first. Until you do this, it will print the boot message ever second or so while on. This is normal, and means that it is ready to receive a new kernel. See section Loading a new kernel using ARC for details.


Go to the first, previous, next, last section, table of contents.