.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.TH MIDAS 1 "2005-06-10" "perl v5.8.0" "User Contributed Perl Documentation"
midas \- assembles diags (Midas Is a Diag ASsembler)
midas [options] <diag_name>
This program builds assembly diags. It is substantially more involved
than simply assembling the diag because it also has to link the diag,
program the \s-1MMU\s0, and generate several output files.
The diag specified on the command line will be built. Pretty much
everything else is configurable.
The following are the options you need to get started:
.IP "\-verbose [level] / \-noverbose (abbreviated \-v / \-nov)" 4
.IX Item "-verbose [level] / -noverbose (abbreviated -v / -nov)"
Sets verbosity level (default=2). \-noverbose (or \-nov) is a synonym
for \-verbose 0, which means to generate no output in the absence of
errors. The highest level of verbosity currently defined is 3.
Return version information and exit.
Display help on the diag format and exit.
.IX Item "-config <file>"
Use this file as the config file instead of the one that is
.IP "\-project <project>" 4
.IX Item "-project <project>"
Use this project for project-specific configuration. Default is the
environment variable \f(CW$PROJECT\fR. Legal values are \s-1BW\s0 and N2.
.IX Subsection "Common Options"
The following are the commonly-used options:
.IP "\-diag_root <path>" 4
.IX Item "-diag_root <path>"
Use the specified path as a base for finding standard include files.
Default is \f(CW$DV_ROOT\fR.
.IP "\-build_dir <path>" 4
.IX Item "-build_dir <path>"
Path (absolute or relative to where command is invoked) to directory
where temporary files are generated and the build is done. Default is
.IP "\-dest_dir <path>" 4
.IX Item "-dest_dir <path>"
Path (absolute or relative to where command is invoked) of where to
store output files. Default is '.'.
.IP "\-find_root <dir>" 4
.IX Item "-find_root <dir>"
Interpret the diag on the command-line as the name of a diag to search
for. It does a breadth-first search under the specified directory.
The default behavior is not to do any search, but to assume that the
specified diag is a full or relative path to the file.
This is a shortcut for "\-find_root <diag_root>/verif/diag".
.IX Item "-mmu <mmu_type>"
Generate programming for the specified \s-1MMU\s0. Recognized options are
\&\*(L"ultra2\*(R", \*(L"niagara\*(R", \*(L"niagara2\*(R", and \*(L"rock\*(R". Default is
project\-specific: \*(L"niagara\*(R" for Niagara\-1 and \*(L"niagara2\*(R" for
.IP "\-ttefmt <tte_format>" 4
.IX Item "-ttefmt <tte_format>"
Specifies \s-1TTE\s0 format for those MMUs that require it. May be \*(L"sun4u\*(R"
or \*(L"sun4v\*(R". Default is project\-specific: \*(L"sun4v\*(R" for Niagara\-1 and
.IP "\-tsbtagfmt <tsbtagfmt>" 4
.IX Item "-tsbtagfmt <tsbtagfmt>"
Specifies the format of the \s-1TSB\s0 tag. Legal values are 'tagaccess' and
\&'tagtarget'. Default is project\-specific: 'tagaccess' for Niagara\-1 and 'tagtarget' for Niagara\-2.
.IP "\-force_build or \-f" 4
.IX Item "-force_build or -f"
Build the diag, even if it looks like we have the same input as before
and the same args as before.
.IP "\-copy_products / \-nocopy_products" 4
.IX Item "-copy_products / -nocopy_products"
By default, the product files generated in the build directory are
hard-linked to the destination directory. The reason they are
hard-linked and not copied is for speed. If the hard link fails, it
will fall back to a copy in case the directories are on different
physical disks. If \-copy_products is given, however, it will always
do a copy, not a hard link. Default is project\-specific:
\&\-nocopy_products for Niagara\-1.
Stop after the preprocessing stage.
.IP "\-cleanup / \-nocleanup" 4
.IX Item "-cleanup / -nocleanup"
If \-cleanup is enabled, then after a successful build, the build
directory is erased if and only if the build directory was created by
this invocation of midas. Default is project\-specific: \-cleanup for
.IP "\-force_cleanup / \-noforce_cleanup" 4
.IX Item "-force_cleanup / -noforce_cleanup"
If \-cleanup is enabled, but this invocation of midas did not create
the build directory, \-force_cleanup will remove the build directory
anyway. Default is project\-specific: \-noforce_cleanup for Niagara\-1.
.IP "\-D<symbol> or \-D<symbol>=<value>" 4
.IX Item "-D<symbol> or -D<symbol>=<value>"
Add a define to the preprocessing line. Option may be repeated.
.IP "\-stddef / \-nostddef" 4
.IX Item "-stddef / -nostddef"
Include standard preprocessor definitions on command\-line. \-nostddef
disables these. Default is \-stddef, but no standard symbols are
Add a directory to the include path used by cpp and m4. Path should
be absolute or relative to the directory where midas was invoked.
.IP "\-stdinc / \-nostdinc" 4
.IX Item "-stdinc / -nostdinc"
With \-stdinc, the standard include paths are used during preprocessing
(both cpp and m4). \-nostdinc disables these. Default is \-stdinc.
The standard include directories are the directory where midas was
invoked, the build directory and
<diag_root>/verif/diag/assembly/include (keep in mind that
<diag_root> defaults to \f(CW$DV_ROOT\fR).
.IP "\-include_build / \-noinclude_build" 4
.IX Item "-include_build / -noinclude_build"
This option is only meaningful with \-nostdinc. If standard includes
are switched off, \-include_build will add the build directory back to
the include path. Default is \-noinclude_build.
.IP "\-include_start / \-noinclude_start" 4
.IX Item "-include_start / -noinclude_start"
This option is only meaningful with \-nostdinc. If standard includes
are switched off, \-include_start will add the start directory (the
directory where midas was invoked) back to the include path.
Default is \-noinclude_start.
Add a directory to the search path when looking for object files in a
\&\s-1MIDAS_OBJ\s0 directive. Option may be repeated.
Add a directory to the search path when looking for C source files in
a \s-1MIDAS_CC\s0 directive. Option may be repeated.
.IP "\-pal_diag_args <args>" 4
.IX Item "-pal_diag_args <args>"
If the diag is run through pal, give these arguments to the pal diag.
Option may be repeated. Note that these arguements are given to the
diag, not pal itself. For instance, \*(L"midas \-pal_args \-abc mydiag.pal
\&\-pal_diag_args def \-pal_diag_args ghi\*(R" will run the pal command-line
\&\*(L"pal \-abc mydiag.pal def ghi\*(R".
.IP "\-build_threads <num_threads>" 4
.IX Item "-build_threads <num_threads>"
When doing work that can be done in parallel (such as assembling a
bunch of files), use <num_threads> to do it. Default is
project\-specific: 3 for Niagara\-1.
.IP "\-print_errors / \-noprint_errors" 4
.IX Item "-print_errors / -noprint_errors"
If \-noprint_errors is defined, then generation of error messages is
turned off. When used with \-verbose 0, midas is completly silent.
This is probalby only useful for the test harness (which is why the
.IP "\-copy_products / \-nocopy_products" 4
.IX Item "-copy_products / -nocopy_products"
If this is set, then copy files from the build directory to the
starting directory. With \-nocopy_products, the files are hard linked
instead. If it tries to create a hard link and fails, it will fall
back to a copy. Default is \-nocopy_products.
.IP "\-compress_image / \-nocompress_image" 4
.IX Item "-compress_image / -nocompress_image"
If \-compress_image is enabled (as it is by default), then allow
compressed mem.images to be generated. By default, all MMU-generated
blocks are compressed when written to mem.image, meaning that instead
of initializing unused sections to zero, they are simply
uninitialized. The \-nocompress_image is equivalent to explicitly
putting a 'compressimage=0' in all attr_text/attr_data blocks.
.IP "\-env_zero / \-noenv_zero" 4
.IX Item "-env_zero / -noenv_zero"
When compressing blocks, if \-env_zero is enabled the blocks will
contain '// zero_image' directives to the environment. These
directives are supported only by Niagara, and they are used to
backdoor initialize large tracts of memory to zero. If \-noenv_zero is
used, then compression will simply leave the data uninitialized.
.IP "\-default_radix <decimal|hex>" 4
.IX Item "-default_radix <decimal|hex>"
Radix to assume for all parameters that do not explicitly start with
\&'0x'. Default is 'decimal'.
.IP "\-gen_all_tsbs / \-nogen_all_tsbs" 4
.IX Item "-gen_all_tsbs / -nogen_all_tsbs"
If \-gen_all_tsbs is given, then all TSBs that are defined are written
to the memory image. If \-nogen_all_tsbs, then generate only the TSBs
that are used. Default is project\-specific: \-nogen_all_tsbs for
.IP "\-allow_tsb_conflicts / \-noallow_tsb_conflicts" 4
.IX Item "-allow_tsb_conflicts / -noallow_tsb_conflicts"
If \-allow_tsb_conflicts is enabled, then it is legal to have mutiple
virtual address map to the same entry in a \s-1TSB\s0. A linked-list will be
created to hold all entries. With \-noallow_tsb_conflicts (which is
the default for N1), collisions in the \s-1TSB\s0 can only happen with the
save \s-1VA\s0 but different contexts. Default is project\-specific.
.IP "\-allow_empty_sections / \-noallow_empty_sections" 4
.IX Item "-allow_empty_sections / -noallow_empty_sections"
If \s-1TEXT_VA\s0 is specified, then at least one attr_text block for the
section has to be specified, and the same is true for \s-1DATA_VA\s0 and
attr_data blocks. If \-allow_empty_sections is specified, then midas
will allow you to specify a \s-1TEXT_VA\s0(\s-1DATA_VA\s0) for the section, even if
the section has no attr_text(attr_data) blocks. Of course, any
text(data) in such a section will be ignored. Default is
project\-specific: \-noallow_empty_sections for Niagara\-1.
.IP "\-allow_duplicate_tags / \-noallow_duplicate_tags" 4
.IX Item "-allow_duplicate_tags / -noallow_duplicate_tags"
When adding to a \s-1TSB\s0 link list, it is an error to add the same tag
twice. \-allow_duplicate_tags suspends the error check. Default is
project\-specific: \-noallow_duplicate_tags for Niagara\-1.
.IP "\-allow_illegal_page_sizes / \-noallow_illegal_page_sizes" 4
.IX Item "-allow_illegal_page_sizes / -noallow_illegal_page_sizes"
If \-allow_illegal_page_sizes, then tte_size attributes are not checked
for valid values, though they are still checked against the width of
the field. For instance, in the Niagara \s-1MMU\s0, there are 3 page bits,
so values can be specified 0\-7. However, the only legal values for
Niagara are 0, 1, 3, and 5, and unless \-allow_illegal_page_sizes is in
effect, setting page bits of 2, 4, 6, or 7 will cause an error. The
default is project\-specific: \-noallow_illegal_page_sizes for
.IP "\-allow_misalgined_tsb_base / \-noallow_misaligned_tsb_base" 4
.IX Item "-allow_misalgined_tsb_base / -noallow_misaligned_tsb_base"
If \-allow_misaligned_tsb_base is set, then a \s-1TSB\s0 base address need not
be aligned with the \s-1TSB\s0 size. Real software will never do this, but I
want it to be possible in diags. If an unalgined address is specified
as the base and \-allow_misaligned_tsb_base is specified, then midas
will forcibly align the address. Default should be
\&\-noallow_misaligned_tsb_base for all projects.
.IP "\-errcode <error_code>" 4
.IX Item "-errcode <error_code>"
Prints a one-line description for the midas error code. Then exits
.Sh "Configuring Commands"
.IX Subsection "Configuring Commands"
midas runs several commands in the course of its operation. Several
of these can be configured. The configurable commands are: pal, cpp,
m4, gcc, as, and ld. Each configurable command has 3 associated options:
.IP "\-std_<command>_args / \-nostd_<command>_args" 4
.IX Item "-std_<command>_args / -nostd_<command>_args"
When \-std_<command>_args is enabled, the standard set of
arguments for <command> are used. Default is
.IP "\-<command>_args <args>" 4
.IX Item "-<command>_args <args>"
Add <args> to the argument list for the specified <command>.
.IP "\-<command>_cmd <custom_command>" 4
.IX Item "-<command>_cmd <custom_command>"
Use <custom_command> to run the specifed <command>
instead of the standard version.
For instance, to add \-foo to the link line, use my_cpp to preprocess, and
not use any standard assembler options, use:
\& midas -ld_args -foo -cpp_cmd my_cpp -nostd_as_args mydiag.s
.Sh "Configuring Filenames"
.IX Subsection "Configuring Filenames"
There are several generated files, and they all have default names.
You can configure the names of many of the files with the following
.IP "\-file <tag>=<name>" 4
.IX Item "-file <tag>=<name>"
Cause midas to name the file whose tag is <tag> to be named
<name> instead of the default. <name> is treated as
the name of a file in the build directory.
The list of valid tags for the \-file option are:
Local version of the original source code for the diag. Default is 'diag.src'.
Assembly portion of diag before any preprocessing. Default is 'diag.s'.
Perl portion of the diag. Deafult is 'diag.pl'.
Output of the C preprocessor. Deafult is 'diag.cpp'.
Output of the m4 preprocessor. Default is 'diag.m4'.
Linker script. Default is 'diag.ls_scr'.
Linked executable. Default is 'diag*.exe' where * is
Verilog memory image. Default is 'mem.image'.
Events file. Default is 'diag.ev'.
Symbol table. Default is 'symbol.tbl'.
Specification to goldfinger on how to create memory image. Default is
File to contain midas directives after section splitting. Default is
File to stash the midas command\-line. Default is '.midas_args'.
File to move old command-line options. Default is '.midas_args.old'.
File to stash m4 output of previous run. Default is '.midas.diag.m4.old'.
.Sh "Running Specific Phases"
.IX Subsection "Running Specific Phases"
The build process is broken into phases: setup, preprocess,
sectioning, assemble, link, postprocess, copydest, cleanup. The
default behavior is to run all phases. You can, however, restrict
operation to a selected set of phases.
.IP "\-start_phase <phase_name>" 4
.IX Item "-start_phase <phase_name>"
Start with the named phase and run all subsequent phase.
.IP "\-phase <phase_name>" 4
.IX Item "-phase <phase_name>"
Run the specified phase. If any \-phase or \-start_phase option exists,
then by default all phases are off (except for the ones that \-phase
and \-start_phase switch on). You can have multiple \-phase options.
This option (mentioned above, which runs the preprocessor only) is just a
shortcut for \*(L"\-phase setup \-phase preprocess\*(R").
Keep in mind that running selected phases is caveat emptor. There are
cases where phases expect data or files from previous phases. You may
get lucky, but don't blame me if it doesn't work.
When midas is unable to run correctly it will exit with one of the
.IP "M_NOERROR (#0): No error." 4
.IX Item "M_NOERROR (#0): No error."
.IP "M_MISC (#1): Miscellaneous error" 4
.IX Item "M_MISC (#1): Miscellaneous error"
.IP "M_CODE (#2): Error in midas code." 4
.IX Item "M_CODE (#2): Error in midas code."
.IP "M_DIR (#3): Directory error." 4
.IX Item "M_DIR (#3): Directory error."
.IP "M_FILE (#4): File error." 4
.IX Item "M_FILE (#4): File error."
.IP "M_CMDFAIL (#5): Command failed." 4
.IX Item "M_CMDFAIL (#5): Command failed."
.IP "M_SECSYNTAX (#6): Error in section syntax." 4
.IX Item "M_SECSYNTAX (#6): Error in section syntax."
.IP "M_ATTRSYNTAX (#7): Error in attr syntax." 4
.IX Item "M_ATTRSYNTAX (#7): Error in attr syntax."
.IP "M_MISSINGPARAM (#8): Missing parameter." 4
.IX Item "M_MISSINGPARAM (#8): Missing parameter."
.IP "M_ILLEGALPARAM (#9): Illegal parameter." 4
.IX Item "M_ILLEGALPARAM (#9): Illegal parameter."
.IP "M_OUTOFRANGE (#10): Out of range." 4
.IX Item "M_OUTOFRANGE (#10): Out of range."
.IP "M_NOTNUM (#11): Not a number." 4
.IX Item "M_NOTNUM (#11): Not a number."
.IP "M_VACOLLIDE (#12): \s-1VA\s0 collision." 4
.IX Item "M_VACOLLIDE (#12): VA collision."
.IP "M_PACOLLIDE (#13): \s-1PA\s0 collision." 4
.IX Item "M_PACOLLIDE (#13): PA collision."
.IP "M_DIRECTIVESYNTAX (#14): Directive syntax error." 4
.IX Item "M_DIRECTIVESYNTAX (#14): Directive syntax error."
.IP "M_GENFAIL (#15): File generation failed." 4
.IX Item "M_GENFAIL (#15): File generation failed."
.IP "M_ASMFAIL (#16): Assembler failed." 4
.IX Item "M_ASMFAIL (#16): Assembler failed."
.IP "M_CCFAIL (#17): C compiler failed." 4
.IX Item "M_CCFAIL (#17): C compiler failed."
.IP "M_LINKFAIL (#18): Linker failed." 4
.IX Item "M_LINKFAIL (#18): Linker failed."
.IP "M_CPPFAIL (#19): \s-1CPP\s0 failed." 4
.IX Item "M_CPPFAIL (#19): CPP failed."
.IP "M_M4FAIL (#20): M4 preprocessor failed." 4
.IX Item "M_M4FAIL (#20): M4 preprocessor failed."
.IP "M_BADCONFIG (#21): Bad configuration." 4
.IX Item "M_BADCONFIG (#21): Bad configuration."
.IP "M_EVENTERR (#22): Event parsing error." 4
.IX Item "M_EVENTERR (#22): Event parsing error."
.IP "M_ARGERR (#23): Argument error." 4
.IX Item "M_ARGERR (#23): Argument error."
.IP "M_NOSEC (#24): Undefined section." 4
.IX Item "M_NOSEC (#24): Undefined section."
.IP "M_BADTSB (#25): Bad \s-1TSB\s0." 4
.IX Item "M_BADTSB (#25): Bad TSB."
.IP "M_BADALIGN (#26): Bad Alignment." 4
.IX Item "M_BADALIGN (#26): Bad Alignment."
.IP "M_EMPTYSECTION (#27): Empty section." 4
.IX Item "M_EMPTYSECTION (#27): Empty section."
.IP "M_TSBSYNTAX (#28): Error in tsb syntax." 4
.IX Item "M_TSBSYNTAX (#28): Error in tsb syntax."
.IP "M_APPSYNTAX (#29): Error in app syntax.'" 4
.IX Item "M_APPSYNTAX (#29): Error in app syntax.'"
.IP "M_MEMORY (#30): Memory error." 4
.IX Item "M_MEMORY (#30): Memory error."
.IP "M_GOLDFINGERPARSE (#31): Goldfinger parse error." 4
.IX Item "M_GOLDFINGERPARSE (#31): Goldfinger parse error."
.IP "M_GOLDFINGERARG (#32): Goldfinger arg error." 4
.IX Item "M_GOLDFINGERARG (#32): Goldfinger arg error."
.IP "M_ELF (#33): \s-1ELF\s0 error." 4
.IX Item "M_ELF (#33): ELF error."
.IP "M_BADLABEL (#34): Bad label." 4
.IX Item "M_BADLABEL (#34): Bad label."
.IP "M_GOLDFINGERMISC (#35): Uncategorized goldfinger error." 4
.IX Item "M_GOLDFINGERMISC (#35): Uncategorized goldfinger error."
.IP "M_GOLDFINGERVERSION (#36): Bad version of goldfinger" 4
.IX Item "M_GOLDFINGERVERSION (#36): Bad version of goldfinger"
.IP "M_DUPLICATETAG (#37): Duplicate tags in \s-1TSB\s0" 4
.IX Item "M_DUPLICATETAG (#37): Duplicate tags in TSB"
.IP "M_BLOCKSYNTAX (#38): Error defining goldfinger \s-1BLOCK\s0" 4
.IX Item "M_BLOCKSYNTAX (#38): Error defining goldfinger BLOCK"
Jeff Gibson <jeff.gibson@sun.com>
\& Midas(3), goldfinger(1).
projects / OpenSPARC-T2-DV / blob