NAME

isa — instruction set analyser

SYNOPSIS

isa

DESCRIPTION

The isa utility is used to generate instruction stream encoders and decoders from a textual description of a CPU instruction set.

The isa utility supports three operational modes, as specified by the use of the -D, -E or -Q options:


Decode: (-D | --decode) In this mode, the isa utility transforms source code, expanding match pattern between the tokens “[ISA[” and “]ISA]” into the appropriate code for matching instruction streams. The section Matching Instructions describes the decode functionality in greater depth.

Encode: (-E | --encode) In this mode, the isa utility generates C code to emit binary instruction streams.

Query: (-Q | --query) In this mode, the isa utility is used to retrieve information from instruction set specifications.

If no operational mode is specified, a default of Query will be used.

Instruction set specifications may be specified using the a option, or by using the command line arguments file ....

The isa utility accepts the following options:


-a architecture | --arch= N architecture: Use instruction set specifications specified by the argument architecture. The isa utility will look for these specifications in the locations specified by the environment variable ISAPATH, in addition to a built-in search location. The default architecture is that for the host the isa utility is being executed on.s

-c cpu | --cpu=cpu: Generate encoders and decoders for the specific instruction set variant supported by CPU cpu. This option may be specified multiple times. If the argument cpu starts with a minus, the CPU specified will be removed from list of CPUs to be supported.

-h | --help: Print a help message and exit.

-i filename | --input=filename: When generating a decoder, read the source to be expanded from the file named in the argument filename. If an input file is not specified, the isa utility will read from its standard input.

-n | --dry-run: Exit without creating any output after checking inputs for errors.

-o filename | --output=filename: When generating encoders and decoders, send the output to the file specified by the argument filename. If an output file is not specified, the isa utility will write to its standard output.

-p string | --prefix=string: When in encode mode, use the string in argument string as a prefix for generated symbols.

-q | --quiet: Suppress warning messages.

-s filename | --spec=filename: Read an instruction set specification from the file named by argument filename. This option may be specified multiple times, in which case the isa utilitiy behaves as if the specifications had been concatenated in the sequence specified.

-v | --verbose: Increase the verbosity level. This option may be specified multiple times.

-D | --decode: Transform sources expanding match patterns in source code to lower-level instruction stream decoding code. By default, the isa utility will read from standard input and write to standard output, unless otherwise specified by the -i and -o options.

-E | --encode: Build an instruction stream encoder.

-L | --list-instructions: When in query mode, generate a list of all known instructions.

-N number | --ntests=number: When in query mode, specify the number of test sequences to be generated if the --T | --test option was specified.

-Q | --query: Retrieve information about an instruction set.

-R number | --random-seed=number: Use the argument number as the seed for pseudorandom number generation. If this option is not specified, the isa utility will initialize the pseudorandom number generator in an implementation-defined manner.

-T | --test: Generate instruction sequences for use in testing tools such as assemblers.

-V | --version: Print a version identifier and exit.

ENVIRONMENT

The behavior of the isa utility is affected by the following environemnt variables:


ISAPATH: Specifies a colon-separated set of directories tp be used when searching for instruction specifications.

FILES


/usr/share/isa/: The default location for instruction set specifications.

EXAMPLES

To check the instruction specifications in file spec.isa, use:

isa -n spec.isa

To expand instruction decoding templates in the file a.m, assuming a generic AVR CPU, and generating a C source file, use:

isa -a avr -D < a.m > a.c

HISTORY

The isa utility is scheduled to appear in a future release from the Elftoolchain project.

AUTHORS

The isa(1) utility was written by Joseph Koshy <jkoshy@users.sourceforge.net>.

BUGS

The isa 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 ⟨elftoolchain-developers@lists.sourceforge.net⟩.