.\" 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 2889 2013-01-13 15:36:04Z jkoshy $ .\" .Dd January 13, 2013 .Os .Dt ISA 1 .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 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 .