248 lines
7.3 KiB
Groff
248 lines
7.3 KiB
Groff
.\" Copyright (c) 2012,2013 Joseph Koshy.
|
|
.\" 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR AND CONTRIBUTORS 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: isa.1 3642 2018-10-14 14:24:28Z jkoshy $
|
|
.\"
|
|
.Dd January 13, 2013
|
|
.Dt ISA 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm isa
|
|
.Nd instruction set analyser
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl a Ar architecture | Fl -arch Ns = Ns Ar architecture
|
|
.Op Fl c Ar cpu | Fl -cpu Ns = Ns Ar cpu
|
|
.Op Fl h | Fl -help
|
|
.Op Fl i Ar filename | Fl -input Ns = Ns Ar filename
|
|
.Op Fl n | Fl -dry-run
|
|
.Op Fl o Ar filename | Fl -output Ns = Ns Ar filename
|
|
.Op Fl p Ar string | Fl -prefix Ns = Ns Ar string
|
|
.Op Fl s Ar filename | Fl -spec Ns = Ns Ar filename
|
|
.Op Fl q | Fl -quiet
|
|
.Op Fl v | Fl -verbose
|
|
.Op Fl D | Fl -decode
|
|
.Op Fl E | Fl -encode
|
|
.Op Fl L | Fl -list-instructions
|
|
.Op Fl N Ar number | Fl -ntests Ns = Ns Ar number
|
|
.Op Fl Q | Fl -query
|
|
.Op Fl R Ar number | Fl -random-seed Ns = Ns Ar number
|
|
.Op Fl T | Fl -test
|
|
.Op Fl V | Fl -version
|
|
.Ar
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is used to generate instruction stream encoders and decoders
|
|
from a textual description of a CPU instruction set.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility supports three operational modes, as specified by the use of
|
|
the
|
|
.Fl D ,
|
|
.Fl E
|
|
or
|
|
.Fl Q
|
|
options:
|
|
.Bl -tag -width indent
|
|
.It Cm Decode
|
|
.Pq Fl D | Fl -decode
|
|
In this mode, the
|
|
.Nm
|
|
utility transforms source code, expanding match pattern between the
|
|
tokens
|
|
.Dq Li "[ISA["
|
|
and
|
|
.Dq Li "]ISA]"
|
|
into the appropriate code for matching instruction streams.
|
|
The section
|
|
.Sx "Matching Instructions"
|
|
describes the decode functionality in greater depth.
|
|
.It Cm Encode
|
|
.Pq Fl E | Fl -encode
|
|
In this mode, the
|
|
.Nm
|
|
utility generates C code to emit binary instruction streams.
|
|
.It Cm Query
|
|
.Pq Fl Q | Fl -query
|
|
In this mode, the
|
|
.Nm
|
|
utility is used to retrieve information from instruction set
|
|
specifications.
|
|
.El
|
|
.Pp
|
|
If no operational mode is specified, a default of
|
|
.Cm Query
|
|
will be used.
|
|
.Pp
|
|
Instruction set specifications may be specified using the
|
|
.Fa a
|
|
option, or by using the command line arguments
|
|
.Ar .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility accepts the following options:
|
|
.Bl -tag -width indent
|
|
.It Fl a Ar architecture | Fl -arch Ns = N Ar architecture
|
|
Use instruction set specifications specified by the argument
|
|
.Ar architecture .
|
|
The
|
|
.Nm
|
|
utility will look for these specifications in the locations
|
|
specified by the environment variable
|
|
.Ev ISAPATH ,
|
|
in addition to a built-in search location.
|
|
The default architecture is that for the host the
|
|
.Nm
|
|
utility is being executed on.s
|
|
.It Fl c Ar cpu | Fl -cpu Ns = Ns Ar cpu
|
|
Generate encoders and decoders for the specific instruction set
|
|
variant supported by CPU
|
|
.Ar cpu .
|
|
This option may be specified multiple times.
|
|
If the argument
|
|
.Ar cpu
|
|
starts with a minus, the CPU specified will be removed from list of
|
|
CPUs to be supported.
|
|
.It Fl h | Fl -help
|
|
Print a help message and exit.
|
|
.It Fl i Ar filename | Fl -input Ns = Ns Ar filename
|
|
When generating a decoder, read the source to be expanded from the
|
|
file named in the argument
|
|
.Ar filename .
|
|
If an input file is not specified, the
|
|
.Nm
|
|
utility will read from its standard input.
|
|
.It Fl n | Fl -dry-run
|
|
Exit without creating any output after checking inputs for errors.
|
|
.It Fl o Ar filename | Fl -output Ns = Ns Ar filename
|
|
When generating encoders and decoders, send the output to the file
|
|
specified by the argument
|
|
.Ar filename .
|
|
If an output file is not specified, the
|
|
.Nm
|
|
utility will write to its standard output.
|
|
.It Fl p Ar string | Fl -prefix Ns = Ns Ar string
|
|
When in encode mode, use the string in argument
|
|
.Ar string
|
|
as a prefix for generated symbols.
|
|
.It Fl q | Fl -quiet
|
|
Suppress warning messages.
|
|
.It Fl s Ar filename | Fl -spec Ns = Ns Ar filename
|
|
Read an instruction set specification from the file named by argument
|
|
.Ar filename .
|
|
This option may be specified multiple times, in which case the
|
|
.Nm
|
|
utilitiy behaves as if the specifications had been concatenated in the
|
|
sequence specified.
|
|
.It Fl v | Fl -verbose
|
|
Increase the verbosity level.
|
|
This option may be specified multiple times.
|
|
.It Fl D | Fl -decode
|
|
Transform sources expanding match patterns in source code to
|
|
lower-level instruction stream decoding code.
|
|
By default, the
|
|
.Nm
|
|
utility will read from standard input and write to standard output,
|
|
unless otherwise specified by the
|
|
.Fl i
|
|
and
|
|
.Fl o
|
|
options.
|
|
.It Fl E | Fl -encode
|
|
Build an instruction stream encoder.
|
|
.It Fl L | Fl -list-instructions
|
|
When in query mode, generate a list of all known instructions.
|
|
.It Fl N Ar number | Fl -ntests Ns = Ns Ar number
|
|
When in query mode, specify the number of test sequences to be
|
|
generated if the
|
|
.Fl -T | Fl -test
|
|
option was specified.
|
|
.It Fl Q | Fl -query
|
|
Retrieve information about an instruction set.
|
|
.It Fl R Ar number | Fl -random-seed Ns = Ns Ar number
|
|
Use the argument
|
|
.Ar number
|
|
as the seed for pseudorandom number generation.
|
|
If this option is not specified, the
|
|
.Nm
|
|
utility will initialize the pseudorandom number generator in an
|
|
implementation-defined manner.
|
|
.It Fl T | Fl -test
|
|
Generate instruction sequences for use in testing tools such as
|
|
assemblers.
|
|
.It Fl V | Fl -version
|
|
Print a version identifier and exit.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
The behavior of the
|
|
.Nm
|
|
utility is affected by the following environemnt variables:
|
|
.Bl -tag
|
|
.It Ev ISAPATH
|
|
Specifies a colon-separated set of directories tp be used when
|
|
searching for instruction specifications.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width indent
|
|
.It Pa /usr/share/isa/
|
|
The default location for instruction set specifications.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To check the instruction specifications in file
|
|
.Pa spec.isa ,
|
|
use:
|
|
.D1 isa -n "spec.isa"
|
|
.Pp
|
|
To expand instruction decoding templates in the file
|
|
.Pa a.m ,
|
|
assuming a generic
|
|
.Tn AVR
|
|
CPU, and generating a C source file, use:
|
|
.D1 isa -a avr -D < a.m > a.c
|
|
.Sh SEE ALSO
|
|
.Xr elf 3 ,
|
|
.Xr elf 5 ,
|
|
.Xr isa 5
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility is scheduled to appear in a future release from the
|
|
Elftoolchain project.
|
|
.\" TODO Reword the above when the target release is finalized.
|
|
.Sh AUTHORS
|
|
The
|
|
.Xr isa 1
|
|
utility was written by
|
|
.An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net .
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
utility is wildly unstable at this point of time.
|
|
If you intend to use this utility, please get in touch with the
|
|
project's developers at
|
|
.Aq elftoolchain-developers@lists.sourceforge.net .
|