368 lines
11 KiB
Groff
368 lines
11 KiB
Groff
.\" Copyright (c) 2001 Joerg Wunsch
|
|
.\"
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id$
|
|
.\"
|
|
.Dd DATE January 19, 2001
|
|
.Os
|
|
.Dt AVRPROG 1
|
|
.Sh NAME
|
|
.Nm avrprog
|
|
.Nd driver program for ``simple'' Atmel AVR MCU programmer
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl p Ar partno
|
|
.Op Fl c Ar programmer-id
|
|
.Op Fl C Ar config-file
|
|
.Op Fl e
|
|
.Oo Fl E Ar exitspec Ns
|
|
.Op \&, Ns Ar exitspec
|
|
.Oc
|
|
.Op Fl f Ar format
|
|
.Op Fl F
|
|
.Op Fl i Ar filename
|
|
.Op Fl m Ar memtype
|
|
.Op Fl o Ar filename
|
|
.Op Fl n
|
|
.Op Fl P Ar parallel
|
|
.Op Fl t
|
|
.Op Fl v
|
|
.Sh DESCRIPTION
|
|
.Nm Avrprog
|
|
is a driver program for a simple programming hardware that allows one
|
|
to program Atmel AVR microcontrollers, where the programmer is
|
|
connected directly to a
|
|
.Xr ppi 4
|
|
parallel port. In the simplest case, the hardware consists just of a
|
|
cable, connecting the respective AVR signal lines to the parallel port.
|
|
.Pp
|
|
The MCU is programmed in
|
|
.Em serial programming mode ,
|
|
so the MCU signals
|
|
.Ql /RESET ,
|
|
.Ql SCK ,
|
|
.Ql MISO
|
|
and
|
|
.Ql MOSI
|
|
need to be connected to the parallel port. Optionally, some otherwise
|
|
unused output pins of the parallel port can be used to supply power for
|
|
the MCU part, so it is also possible to construct a passive standalone
|
|
programming device.
|
|
Some status LEDs indicating the current operating state of the
|
|
programmer can be connected, and a signal is available to control a
|
|
buffer/driver IC 74LS367 (or 74HCT367). The latter can be useful to
|
|
decouple the parallel port from the MCU when in-system programming is
|
|
used.
|
|
.Pp
|
|
See the file
|
|
.Pa ${PREFIX}/share/doc/avrprog/avrprog.pdf
|
|
for a schematic of the programming hardware.
|
|
.Pp
|
|
Input files can be provided, and output files can be written in
|
|
different file formats, such as raw binary files containing the data
|
|
to download to the chip, Intel hex format, or Motorola S-record
|
|
format. There are a number of tools available to produce those files,
|
|
like
|
|
.Xr asl 1
|
|
as a standalone assembler, or
|
|
.Xr avr-objcopy 1
|
|
for the final stage of the GNU toolchain for the AVR microcontroller.
|
|
.Pp
|
|
Both, EEPROM cells and the flash ROM can be programmed (separately).
|
|
It is also possible to read the chip (provided it has not been
|
|
code-protected previously, of course) and store the data in a file.
|
|
Finally, a ``terminal'' mode is available that allows one to
|
|
interactively communicate with the MCU, and to display or program
|
|
individual memory cells.
|
|
.Ss Options
|
|
In order to control all the different operation modi, a number of options
|
|
need to be specified to
|
|
.Nm avrprog .
|
|
.Bl -tag -offset indent -width indent
|
|
.It Fl p Ar partno
|
|
This is the only option that is mandatory for every invocation of
|
|
.Nm avrprog .
|
|
It specifies the type of the MCU connected to the programmer. These are read from the config file. If
|
|
.Nm avrprog
|
|
does not know about a part that you have, simply add it to the config
|
|
file (be sure and submit a patch back to the author so that it can be
|
|
incorporated for the next version). See the sample config file for
|
|
the format. Currently, the following MCU types are understood:
|
|
.Pp
|
|
.TS
|
|
ll.
|
|
\fBOption tag\fP \fBOfficial part name\fP
|
|
1200 AT90S1200
|
|
2313 AT90S2313
|
|
2333 AT90S2333
|
|
4433 AT90S4433
|
|
4434 AT90S4434
|
|
8515 AT90S8515
|
|
8535 AT90S8535
|
|
103 ATMEGA103
|
|
.TE
|
|
.It Fl c Ar programmer-id
|
|
Use the pin configuration specified by the argument. Pin
|
|
configurations are read from the config file (see the
|
|
.Fl C
|
|
option). New pin configurations can be easily added or modified
|
|
through the use of a config file to make
|
|
.Nm avrprog
|
|
work with different programmers as long as the programmer supports the
|
|
Atmel AVR serial program method.
|
|
.It Fl C Ar config-file
|
|
Use the specified config file to load configuration data. This file
|
|
contains all programmer and part definitions that
|
|
.Nm avrprog
|
|
knows about. If you have a programmer or part that
|
|
.Nm avrprog
|
|
does not know about, you can add it to the config file (be sure and
|
|
submit a patch back to the author so that it can be incorporated for
|
|
the next version). See the sample config file, located at
|
|
.Pa ${PREFIX}/etc/avrprog.conf.sample ,
|
|
which contains a description of the format.
|
|
.It Fl e
|
|
Causes a chip erase to be executed. This will reset the contents of the
|
|
flash ROM and EEPROM to the value
|
|
.Ql 0xff ,
|
|
and is basically a prerequisite command before the flash ROM can be
|
|
reprogrammed again. The only exception would be if the new
|
|
contents would exclusively cause bits to be programmed from the value
|
|
.Ql 1
|
|
to
|
|
.Ql 0 .
|
|
Note that in order to reprogram EERPOM cells, no explicit prior chip
|
|
erase is required since the MCU provides an auto-erase cycle in that
|
|
case before programming the cell.
|
|
.It Xo Fl E Ar exitspec Ns
|
|
.Op \&, Ns Ar exitspec
|
|
.Xc
|
|
By default,
|
|
.Nm
|
|
leaves the parallel port in the same state at exit as it has been
|
|
found at startup. This option modifies the state of the
|
|
.Ql /RESET
|
|
and
|
|
.Ql Vcc
|
|
lines the parallel port is left at, according to the
|
|
.Ar exitspec
|
|
arguments provided, as follows:
|
|
.Bl -tag -width noreset
|
|
.It Ar reset
|
|
The
|
|
.Ql /RESET
|
|
signal will be left activated at program exit, that is it will be held
|
|
.Em low ,
|
|
in order to keep the MCU in reset state afterwards. Note in particular
|
|
that the programming algorithm for the AT90S1200 device mandates that
|
|
the
|
|
.Ql /RESET
|
|
signal is active
|
|
.Em before
|
|
powering up the MCU, so in case an external power supply is used for this
|
|
MCU type, a previous invocation of
|
|
.Nm
|
|
with this option specified is one of the possible ways to guarantee this
|
|
condition.
|
|
.It Ar noreset
|
|
The
|
|
.Ql /RESET
|
|
line will be deactivated at program exit, thus allowing the MCU target
|
|
program to run while the programming hardware remains connected.
|
|
.It Ar vcc
|
|
This option will leave those parallel port pins active
|
|
.Pq \&i. \&e. Em high
|
|
that can be used to supply
|
|
.Ql Vcc
|
|
power to the MCU.
|
|
.It Ar novcc
|
|
This option will pull the
|
|
.Ql Vcc
|
|
pins of the parallel port down at program exit.
|
|
.El
|
|
.Pp
|
|
Multiple
|
|
.Ar exitspec
|
|
arguments can be separated with commas.
|
|
.It Fl f Ar format
|
|
This option specifies the file format for the input or output files
|
|
to be processed.
|
|
.Ar Format
|
|
can be one of:
|
|
.Bl -tag -width sss
|
|
.It Ar i
|
|
Intel Hex
|
|
.It Ar s
|
|
Motorola S-record
|
|
.It Ar r
|
|
raw binary; little-endian byte order, in the case of the flash ROM data
|
|
.It Ar a
|
|
auto detect; valid for input only, and only if the input is not
|
|
provided at
|
|
.Em stdin .
|
|
.El
|
|
.Pp
|
|
The default is to use auto detection for input files, and raw binary
|
|
format for output files.
|
|
.It Fl F
|
|
Normally,
|
|
.Nm
|
|
tries to verify that the device signature read from the part is
|
|
reasonable before continuing. Since it can happen from time to time
|
|
that a device has a broken (erased or overwritten) device signature
|
|
but is otherwise operating normally, this options is provided to
|
|
override the check.
|
|
.It Fl i Ar filename
|
|
Specifies the input file to be programmed into the MCU. Can be specified
|
|
as
|
|
.Ql \&-
|
|
to use
|
|
.Em stdin
|
|
as the input.
|
|
.It Fl m Ar memtype
|
|
Specifies which program area of the MCU to read or write; allowable
|
|
values are
|
|
.Em eeprom
|
|
for the EEPROM, or
|
|
.Em flash
|
|
for the flash ROM, which is also the default.
|
|
.It Fl n
|
|
No-write - disables actually writing data to the MCU (useful for debugging
|
|
.Nm avrprog
|
|
).
|
|
.It Fl o Ar filename
|
|
Specifies the name of the output file to write, and causes the respective
|
|
memory area to be read from the MCU. Can be specified as
|
|
.Ql \&-
|
|
to write to
|
|
.Em stdout .
|
|
.It Fl P Ar parallel
|
|
Use
|
|
.Ar parallel
|
|
as the
|
|
.Xr ppi 4
|
|
device to communicate with, instead of the default
|
|
.Pa /dev/ppi0 .
|
|
.It Fl t
|
|
Tells
|
|
.Nm
|
|
to enter the interactive ``terminal'' mode instead of up- or downloading
|
|
files. See below for a detailed description of the terminal mode.
|
|
.El
|
|
.Ss Terminal mode
|
|
In this mode,
|
|
.Nm
|
|
only initializes communication with the MCU, and then awaits user
|
|
commands on standard input. Commands and parameters may be
|
|
abbreviated to the shortest unambiguous form. Terminal mode provides
|
|
a command history using
|
|
.Xr readline 3 ,
|
|
so previously entered command lines can be recalled and edited. The
|
|
following commands are currently implemented:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar dump eeprom\&|flash addr nbytes
|
|
Read
|
|
.Ar nbytes
|
|
bytes from the specified memory area, and display them in the usual
|
|
hexadecimal and ASCII form.
|
|
.It Ar dump
|
|
Continue dumping the memory contents for another
|
|
.Ar nbytes
|
|
where the previous
|
|
.Ar dump
|
|
command left off.
|
|
.It Ar write eeprom\&|flash addr byte1 ... byteN
|
|
Manually program the respective memory cells, starting at address
|
|
.Ar addr ,
|
|
using the values
|
|
.Ar byte1
|
|
through
|
|
.Ar byteN .
|
|
This feature is not implemented for bank-addressed memories such as
|
|
flash memory of ATMega devices.
|
|
.It Ar erase
|
|
Perform a chip erase.
|
|
.It Ar sig
|
|
Display the device signature bytes.
|
|
.It Ar part
|
|
Display the current part settings.
|
|
.It Ar \&?
|
|
.It Ar help
|
|
Give a short on-line summary of the available commands.
|
|
.It Ar quit
|
|
Leave terminal mode and thus
|
|
.Nm avrprog .
|
|
.El
|
|
.Ss Default Parallel port pin connections
|
|
(these can be changed, see the
|
|
.Fl c
|
|
option)
|
|
.TS
|
|
ll.
|
|
\fBPin number\fP \fBFunction\fP
|
|
2-5 Vcc (optional power supply to MCU)
|
|
7 /RESET (to MCU)
|
|
8 SCK (to MCU)
|
|
9 MOSI (to MCU)
|
|
10 MISO (from MCU)
|
|
18-25 GND
|
|
.TE
|
|
.Sh FILES
|
|
.Bl -tag -offset indent -width /dev/ppi0XXX
|
|
.It Pa /dev/ppi0
|
|
default device to be used for communication with the programming
|
|
hardware
|
|
.It Pa ${PREFIX}/etc/avrprog.conf.sample
|
|
sample pin configuration file
|
|
.It Pa ${PREFIX}/etc/avrprog.conf
|
|
default pin configuration file
|
|
.It Pa ~/.inputrc
|
|
Initialization file for the
|
|
.Xr readline 3
|
|
library
|
|
.It Pa ${PREFIX}/share/doc/avrprog/avrprog.pdf
|
|
Schematic of programming hardware
|
|
.El
|
|
.\" .Sh EXAMPLES
|
|
.\" .Sh DIAGNOSTICS
|
|
.Sh SEE ALSO
|
|
.Xr asl 1 ,
|
|
.Xr avr-objcopy 1 ,
|
|
.Xr ppi 4 ,
|
|
.Xr readline 3
|
|
.Pp
|
|
The AVR microcontroller product description can be found at
|
|
.Pp
|
|
.Dl "http://www.atmel.com/atmel/products/prod23.htm"
|
|
.\" .Sh HISTORY
|
|
.Sh AUTHORS
|
|
.Nm Avrprog
|
|
was written by Brian S. Dean <bsd@bsdhome.com>.
|
|
.Pp
|
|
This man page by
|
|
.ie t J\(:org Wunsch.
|
|
.el Joerg Wunsch.
|
|
.Sh BUGS
|
|
Motorola S-record files are not yet implemented.
|