Package: ava
Version: 0.3b.19990815-3
Severity: normal
Tags: patch
Hi!
ava had no manpage, so I've written one, both in English and Spanish. I'm
attaching the two files to this mail.
The information was taken mainly from the --help output and the ava.ps.gz
manual included in the package.
Please review and include this manpages in the next Debian Release of ava
if you feel they are useful.
Love,
Margarita Manterola.
-- System Information:
Debian Release: 3.1
APT prefers testing
APT policy: (500, 'testing')
Architecture: i386 (i686)
Kernel: Linux 2.6.9-2-686-smp
Locale: LANG=es_AR, LC_CTYPE=es_AR (charmap=ISO-8859-1)
Versions of packages ava depends on:
ii libc6 2.3.2.ds1-18 GNU C Library: Shared libraries an
ii libgcc1 1:4.0-0pre2 GCC support library
ii libstdc++5 1:3.3.4-13 The GNU Standard C++ Library v3
ii uisp 20040311-1 Micro In-System Programmer for Atm
-- no debconf information
.TH "Ava" "1" "January 21, 2005" "Margarita Manterola" ""
.SH "NAME"
ava \- Algebraical Virtual Assembler for Atmel's AVR MCUs
.SH "SYNOPSIS"
.B ava
.RB "[ " -pLv " ] "
.RB "[ " \-A\fIdevice\fR " ] "
.RB "[ " \-lI\fIfilename\fR " ] "
.RB "[ " \-I\fIdirname\fR " ] "
.RB "[ " \-T\fIfilename\fR " ] "
.RB "[ " \-D\fImacro\fR=\fIval\fR " ] "
.RB "[ " \-f\fImacro\fR=\fIval\fR " ] "
.RB "[ " "\-o \fIoutfile\fR" " ] "
.RB "[ " \-\-version " ] "
.RB "[ " \-\-multiple\-output\-files " ] "
.RB "[ " \-\-motorola " ] "
.RB "[ " \-\-intel " ] "
.I files libraries
.SH "DESCRIPTION"
.B AVA
is an advanced assembler and linker for Atmel's family of 8 bit and
16 bit AVR microcontrollers, but can be extended to 32 bit families also.
It offers a C\-like preprocessor, powerful segments, and virtual symbols.
These two features improve modular programming and allow objects to be
completely independent from each other.
The assembler is not compatible with Atmel's assembler syntax.
.B AVA
integrates two functions: assembler and linker. Depending on the command
line it executes either the first or the second one. Libraries are
supported by the ordinary objects where each function can be declared in
its own segment which is removed if not needed.
.SH "USAGE"
.B AVA
is a console application running in batch mode. It reads input either from
a file or from the standard input (\fBstdin\fR). Output is written to
another file or to the standard output (\fBstdout\fR). By default, error
messages are printed to the standard error (\fBstderr\fR).
Assembler and linker are integrated, which of them is invoked is identified
by the source filename extension. If
.BR stdin " or " stdout
are specified,
.B AVA
automatically invokes the assembler, since the linker cannot used these two
streams as input or output. See the
.B "FILES"
section for a description of the supported formats.
Assembler can only assemble one file at a time.
The order of the options (beginning with \fB\-\fR) does not matter. The
order of the filenames, however, is very important: files are linked in
exactly the same sequence as listed in the command line. This has a strong
effect on virtual symbols.
.B Examples
.TP
.B ava -o project main.o print.o
This command links the files
.BR main.o " and " print.o " into one " project " file.
.TP
.B ava -p < file.s | gzip > file.o.gz
This command assemblies
.BR file.s .
The assembled code is directed towards
.BR stdout ,
where the
.B gzip
command processes it.
.TP
.B ava -v -v -o example example.o mylib
This command links the file
.BR example.o " with the libraries contained in " mylib ,
.RB " into the " example " file, with extra verbose level. "
.SH "OPTIONS"
Many options can be specified, regarding the assembler and linker, the
report format or the output format. A summary of the options supported by
\fBAVA\fR is included below.
.B General Options
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-\-version
output version information and exit
.TP
.BI "\-o " file
Redirect the output to
.IR file ,
if you want to redirect it to standard output, use
.B \-o stdout
\.
.TP
.B \-p
Use \fIstdin\fR for input and \fIstdout\fR for output, if \fB\-o\fR is not
set.
.PP
.B Assembler and linker options
.TP
.B \-D\fImacro\fB=\fIval\fR
Define macro with value
.IR val ,
if
.I val
is not given 1 is assumed.
.B Examples:
.br
ava -DVER=2 main.s
.br
ava -DSTR="string" main.s
.TP
.B \-f \fImacro\fB=\fIval\fR
Define public macro of the form
.B __macro{=val}
.B Example:
.br
ava -favr_noskipbug main.s
.TP
.BI \-T file
Auto-include the
.IR file ,
if no filename is given, then
.B target.inc
is included.
The file specifed by this option is always first in the queue, before those
specified by the
.B \-I
option. It is searched in the default directory and then on the predefined
list.
.TP
.BI \-A device
Declare target device; same as: \fB-D\fIdevice\fR \fB\-T\fIarch.inc\fR
.TP
.BI \-I name
Add the directory
.I name
to the search list or include the file
.I name
to the source.
.PP
.B Report Options
.TP
.B \-v
Verbose output. More than one
.B \-v
can be specified to increase the verbose level.
.TP
.B \-L
Generate listing report for the file being assembled.
.TP
.BI \-l logfile
Append segment tree information and status reports to the
.IR logfile .
Errors and warnings are reported both to
.B stderr
and
.IR logfile .
.PP
.B Output Formats
.TP
.B \-\-multiple-output-files
Saves each segment in a separate file. File name is extended with the name
base segment. For example:
.BR a.out.flash ", " a.out.eeprom ", ..."
.TP
.B \-\-intel
Set Intel standard 16 bit output format (sets
.B \-\- multiple-output-files
by default).
.TP
.B \-\-motorola
Set Motorola S-record S1/S2 (16/24) bit output format. Address is limited
to 24 bits.
.TP
.B \-\-uasm
Set Micro Assembler output format (default)
.PP
.B AVR specific options
.TP
.B \-favr_noskipbug
Do not check bad return address.
.TP
.B \-favr_noendianbug
Do not swap bytes in the flash segment. (this will be the default in future
releases)
.SH "FILES"
The files types that
.B AVA
understands are:
.TP
.B file.s
Assembler source. This is an input file, that will cause
.B AVA
to work as assembler.
.TP
.B file.o
Object. This is an input/output file, that will cause
.B AVA
to work as linker.
.TP
.B a.out
Linker default output file name. This is an output file to be used when
linking.
.TP
.B a.out.name
Linker extended file name if
.B --multiple-output-files
is given. The extension
.I name
is replaced with segment name.
.TP
.B file.lst
Listing report. This is an output file, generated when using the
.B \-L
parameter.
.TP
.B libraries
A library is a directory of object files. It may also contain other files
as long as they do not have the suffix of the object file.
Each function should be placed in separate
.BR "removable segments" .
Only in this case can the linker check function dependencies and remove
unused pieces of code.
.SH "VERSION"
0.3b
.SH "SEE ALSO"
.BR uisp (1),
.BR avra (1),
.BR avrp (1),
and the
.BR "AVA's User Manual" .
.SH "AUTHOR"
Uros Platise <[EMAIL PROTECTED]>
This man\-page was written by Margarita Manterola <[EMAIL PROTECTED]> for the
Version 0.3b of the
.B ava
program.
.TH "Ava" "1" "22 de enero de 2005" "Margarita Manterola" ""
.SH "NOMBRE"
ava \- Ensamblador virtual algebraico para microcontroladores AVR de Atmel
.SH "SINOPSIS"
.B ava
.RB "[ " -pLv " ] "
.RB "[ " \-A\fIdispositivo\fR " ] "
.RB "[ " \-lI\fIarchivo\fR " ] "
.RB "[ " \-I\fIdirectorio\fR " ] "
.RB "[ " \-T\fIarchivo\fR " ] "
.RB "[ " \-D\fImacro\fR=\fIval\fR " ] "
.RB "[ " \-f\fImacro\fR=\fIval\fR " ] "
.RB "[ " "\-o \fIarchivo\fR" " ] "
.RB "[ " \-\-version " ] "
.RB "[ " \-\-multiple\-output\-files " ] "
.RB "[ " \-\-motorola " ] "
.RB "[ " \-\-intel " ] "
.I archivos bibliotecas
.SH "DESCRIPCIÃN"
.B AVA
es un ensablador y enlazador avanzado para los microcontroladores de la
familia AVR de 8 y 16 bits, aunque tambiÃn puede ser extendido para las
familias de 32 bits. Tiene un preprocesador estilo C, segmentos poderosos
y sÃmbolos virtuales. Estas dos caracterÃsticas especiales mejoran la
programaciÃn modular y permiten que los objetos sean completamente
independientes entre sÃ.
La sintaxis del ensamblador no es compatible con la sintaxis de Atmel.
.B AVA
agrupa dos funciones: ensambador y enlazador. SegÃn los archivos con que se
lo invoque, se ejecutarà uno u otro. Dentro de los objetos comunes se pueden
utilizar bibliotecas, en las que cada funciÃn puede ser declarada en su
propio segmento que luego es quitado si no se utiliza.
.SH "UTILIZACIÃN"
.B AVA
es una aplicaciÃn de consola, que puede leer la entrada desde un archivo o
desde entrada estÃndar (\fBstdin\fR). La salida puede guardarse en otro
archivo o bien redirigirse a la salida estÃndar (\fBstdout\fR). Por
omisiÃn, los mensajes de error se imprimen por la salida de errores
(\fBstderr\fR).
El ensamblador y el enlazador estÃn integrados, el programa selecciona cuÃl
de los dos invocar segÃn la extensiÃn de los archivos. Si se utiliza
.BR stdin " o " stdout , " AVA "
automÃticamente llama al ensamblador, ya que el enlazador no puede ser
usado sobre ninguno de ellos. Para mÃs informaciÃn acerca de los formatos
de archivo soportados, vea la secciÃn
.BR "ARCHIVOS" .
El ensamblador puede ensamblar un solo archivo a la vez.
El orden de las opciÃnes (las que comienzan con \fB\-\fR), no importa. El
orden de los archivos, por otro lado, es muy importante: los archivos son
enlazados exactamente en el mismo orden que se indica en la lÃnea de
comados. Esto tiene un efecto muy importante en los sÃmbolos virtuales.
.B Ejemplos
.TP
.B ava -o proyecto main.o print.o
Este comando enlaza los archivos
.BR main.o " y " print.o " en un archivo llamado " proyecto" .
.TP
.B ava -p < archivo.s | gzip > archivo.o.gz
Este comando ensambla
.BR archivo.s .
El cÃdigo ensamblado se redirige a la salida estÃndar, donde el
.B gzip
lo procesa.
.TP
.B ava -v -v -o ejemplo ejemplo.o mis-bibliotecas
Este comando enlaza el archivo
.BR ejemplo.o " con las bibliotecas contenidas en " mis-bibliotecas ,
.RB " generando el archivo " ejemplo ", imprimiendo informaciÃn adicional.
.SH "OPCIONES"
Se pueden especificar muchas opciones, tanto para el ensamblador como el
enlazador, el formato de los reportes y de la salida. A continuaciÃn se
incluye un resumen de las opciones soportadas por
.BR AVA .
.B Opciones generales
.TP
.B \-h, \-\-help
Muestra un resumen de las opciones soportadas.
.TP
.B \-\-version
Muestra informaciÃn sobre la versiÃn actual y sale.
.TP
.BI "\-o " archivo
Redirije la salida a
.IR archivo ,
si quiere redirigir a salida estÃndar, utilice
.B \-o stdout
\.
.TP
.B \-p
Utiliza entrada estÃndar, y salida estÃndar si no se especificà la opciÃn
\fB\-o\fR.
.PP
.B Opciones de ensamblador y enlazador
.TP
.B \-D\fImacro\fB=\fIval\fR
Define una macro con valor
.IR val ,
si no se indica un valor
.IR val ,
se asume 1.
.B Ejemplos:
.br
ava -DVER=2 main.s
.br
ava -DSTR="cadena" main.s
.TP
.B \-f \fImacro\fB=\fIval\fR
Define una macro pÃblica, de la forma
.BR __macro{=val} .
.B Ejemplo:
.br
ava -favr_noskipbug main.s
.TP
.BI \-T archivo
Incluye
.I archivo
dentro del cÃdigo fuente, si no se proporciona ningÃn nombre de archivo, se
incluye el archivo
.BR target.inc .
El archivo especificado por esta opciÃn es siempre el primero en la cola, y
se procesa antes que los especificados por la opciÃn
.BR \-I .
Se lo busca en el directorio predeterminado y luego en la lista
predefinida.
.TP
.BI \-A dispositivo
Declara el dispositivo de destino. Es equivalente a \fB-D\fIdispositivo\fR
\fB\-T\fIarch.inc\fR
.TP
.BI \-I nombre
Agrega el directorio
.I nombre
a la lista de bÃsqueda, o bien incluye el archivo
.I nombre
al cÃdigo fuente.
.PP
.B Opciones de los reportes
.TP
.B \-v
Salida con mÃs informaciÃn. MÃs de un
.B \-v
puede ser especificado, para aumentar la cantidad de informaciÃn que se
imprime.
.TP
.B \-L
Genera el reporte del archivo que se està ensamblando.
.TP
.BI \-l archivo-log
Agrega la informaciÃn del Ãrbol de segmentos y los reportes de estados al
.IR archivo-log .
Los errores y advertencias se mostrarÃn tanto por la salida de errores como
.IR archivo-log .
.PP
.B Formatos de salida
.TP
.B \-\-multiple-output-files
Guarda cada segmento en un archivo separado. Los nombres de los archivos se
generan concatenando el nombre de salida con el segmento base. Ej:
.BR a.out.flash ", " a.out.eeprom ", ..."
.TP
.B \-\-intel
Selecciona una salida con formato estÃndar de Intel de 16 bit
(en este caso, se toma el parÃmetro
.B \-\- multiple-output-files
por omisiÃn).
.TP
.B \-\-motorola
Selecciona una salida con formato Motorola S-record S1/S2 (16/24) bit.
Las direcciones estÃn limitadas a 24 bits.
.TP
.B \-\-uasm
Selecciona una salida con formato Micro Assembler (predeterminada)
.PP
.B Opciones especÃficas de AVR
.TP
.B \-favr_noskipbug
No verificar direcciones de retorno incorrectas.
.TP
.B \-favr_noendianbug
No cambiar los bytes en el segmento de flash (esto se tomarà por omisiÃn en
las prÃximas versiones).
.SH "ARCHIVOS"
Los tipos de archivos que
.B AVA
soporta son:
.TP
.B file.s
CÃdigo fuente assembler. Es un archivo de entrada que harà que
.B AVA
funcione como ensamblador.
.TP
.B file.o
Archivo objecto. Es un archivo de entrada/salida, que harà que
.B AVA
funcione como enlazador.
.TP
.B a.out
Nombre de archivo predeterminado para la salida del enlazador. Este es el
archivo de salida que se utiliza al enlazar.
.TP
.B a.out.segmento
Nombre de archivo para la salida del enlazador si se seleccionà la opciÃn
.BR --multiple-output-files .
El nombre
.I segmento
es el que corresponde al nombre del segmento enlazado.
.TP
.B archivo.lst
Reporte de assembler. Este es el archivo de salida generado al seleccionar
la opciÃn
.BR \-L .
.TP
.B bibliotecas
Una biblioteca es un directorio de archivos objeto. Puede contener otros
archivos, siempre y cuando no tengan la misma extensiÃn que los archivos
objeto.
Cada funciÃn debe estar posicionada en
.B segmentos removibles
separados. Ya que sÃlo de esta manera puede verificar el enlazador las
dependencias de las funciones y quitar las porciones de cÃdigo que no se
utilicen.
.SH "VERSION"
0.3b
.SH "VEA TAMBIÃN"
.BR uisp (1),
.BR avra (1),
.BR avrp (1),
y el
.BR "Manual de Usuario de AVA" .
.SH "AUTOR"
Uros Platise <[EMAIL PROTECTED]>
Esta pÃgina de manual fue escrita y traducida por Margarita Manterola
<[EMAIL PROTECTED]>, para la versiÃn 0.3b del programa
.BR ava .
