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.
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.
In using arc, there are two modes, prompt and passthrough, and
two types of windows, the root window and process windows.
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).
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:
arc in the background whenever a program is downloaded, a variable
is accessed, or a function is called in the arc interactive
debugging mode
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.
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).
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:
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.
ps console command to determine the correct pid to use.
log was executed in to <logfile>.
endlog was executed in.
arc you are using.
There are three different kinds of files which can be downloaded to the board.
arc command allows downloading new bootstraps.
These different kinds of files require different programming strategies,
and therefore have different arc commands.
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.
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:
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.
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 `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).
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.
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.