From 8e1a65399c882472ca219b05f0b9a9e5ffcda8a3 Mon Sep 17 00:00:00 2001
From: bsd <bsd@81a1dc3b-b13d-400b-aceb-764788c761c2>
Date: Sat, 20 Jan 2001 04:14:01 +0000
Subject: [PATCH] Add initial man page graciously contributed by Joerg Wunsch. 
 Thanks Joerg!

git-svn-id: svn://svn.savannah.nongnu.org/avrdude/trunk/avrdude@41 81a1dc3b-b13d-400b-aceb-764788c761c2
---
 avrdude.1 | 304 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 304 insertions(+)
 create mode 100644 avrdude.1

diff --git a/avrdude.1 b/avrdude.1
new file mode 100644
index 00000000..8a7367a1
--- /dev/null
+++ b/avrdude.1
@@ -0,0 +1,304 @@
+.\" 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 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 P Ar parallel
+.Op Fl t
+.Sh DESCRIPTION
+.Nm Avrprog
+is a driver program for a simple programming hardware that allows 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.
+.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 to interactively
+communicate with the MCU, and to display or program individual various
+memory cells even one at a time if desired.
+.Ss Options
+In order to control all the different operation modi, a number of options
+need to be specified to
+.Nm .
+.Bl -tag -offset indent -width indent
+.It Fl p Ar partno
+This is the only option that is mandatory for every invocation of
+.Nm .
+It specifies the type of the MCU connected to the programmer.  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
+.TE
+.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 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 .
+.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
+.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 ~/.inputrc
+Initialization file for the
+.Xr readline 3
+library
+.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.
+.Pp
+This man page by
+.ie t J\(:org Wunsch.
+.el Joerg Wunsch.
+.Sh BUGS
+Motorola S-record files are not yet implemented.
+