Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perlmod / Midas / 3.32 / man / man1 / midasformat.1

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" 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<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    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
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" 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.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    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 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MIDASFORMAT 1"
.TH MIDASFORMAT 1 "2007-01-08" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
midasformat \- Format for diags recognized by \fBmidas\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document describes the format of diags that can be assembled by
\&\fBmidas\fR.  Note that this is not a guide for writing diags, since it
makes no assumptions about the contents of project-standard include
files or boot code.
.Sh "Source Languages"
.IX Subsection "Source Languages"
\&\fBMidas\fR can assemble diags in the following formats:
.IP "Augmented Assembly" 4
.IX Item "Augmented Assembly"
The main supported source language, denoted with a .s extension on the
source file, is an augmented \s-1SPARC\s0 assembly file.  By \*(L"augmented\*(R", we
refer to several directives used to program the \s-1MMU\s0.  These directives
are interpreted by \fBmidas\fR, and their presence means that the raw diag,
even though it ends in .s, would not be acceptable input to a standard
assembler.
.Sp
An assembly diag should be one file, though it may #include others.  A
diag may also contain a perl script, used by the simulation framework
to do postprocessing on the diag's output.  \fBMidas\fR scans a diag for the
symbol \*(L"_\|_PERL_\|_\*(R" on a line by itself.  If it finds such a symbol,
then everything after the _\|_PERL_\|_ line is taken to be a perl script
and is not assembled.
.IP "\s-1PAL\s0 (perl augmented language)" 4
.IX Item "PAL (perl augmented language)"
A diag that ends in a .pal extension is assumed to be written in \s-1PAL\s0
(perl augmented language).  The diag is run through the \s-1PAL\s0
preprocessor, and the output of \s-1PAL\s0 should be an augmented assembly
file as described above.  \fBMidas\fR takes care of running the \s-1PAL\s0
preprocesing phase if the diag ends in .pal.  Since \s-1PAL\s0 and assembly
diags are treated identically after \s-1PAL\s0 preprocessing, the remainder
of the this document discusses only assembly diags.
.IP "C" 4
.IX Item "C"
The top-level diag file is always an augmented assembly file (or a \s-1PAL\s0
script that generated an augmented assembly file), but there are
directives to include C programs in a diag.  See the \*(L"High Level Languages\*(R" section.
.IP "Object files (.o) and Library files (.a)" 4
.IX Item "Object files (.o) and Library files (.a)"
As with C files, raw object (.o) files and static library (.a) files
may be included in a diag.  See the \*(L"High Level Languages\*(R"
section.
.IP "Linked Executables" 4
.IX Item "Linked Executables"
These can be included as-is in a diag.  See the \*(L"\s-1APPLICATION\s0\*(R"
section.
.Sh "Output Files"
.IX Subsection "Output Files"
The following output files are generated by \fBmidas\fR: (the names of the
output files can be reconfigured, but these are the default names)
.IP "\fImem.image\fR" 4
.IX Item "mem.image"
The \fImem.image\fR file is the main output of \fBmidas\fR.  It contains the
initial contents of physical memory in a verilog memory-image format.
The format consists lines containing "@<physical_address>",
followed by lines of data to write at that address.
.IP "\fIdiag.ev\fR" 4
.IX Item "diag.ev"
This is an event file generated for vera.  Any assembly line that
contains a comment that begins with \*(L"$EV\*(R" will generate an entry in
this file.  \fI\s-1XXX\s0 \- this format should be documented further.\fR
.IP "\fIsymbol.tbl\fR" 4
.IX Item "symbol.tbl"
This file contains 4 columns: symbol_name, virtual_addres, real
address, and physical_address.  It exists to support the simulation
framework so it can lookup addresses for symbol names.  If any of the
addresses are inappropriate (such as real address for unmapped
sections), it will be represented by 'X'.
.IP "\fIdiag.pl\fR" 4
.IX Item "diag.pl"
This is a perl script extracted from the diag (i.e., the code after
the \*(L"_\|_PERL_\|_\*(R" directive).  It is used by the simulation framework to
do diag-specific post\-processing.
.IP "\fIdiag*.exe\fR" 4
.IX Item "diag*.exe"
This is the linked executable built by \fBmidas\fR (the * is the name of
the application, if there is a non-default application).  It is not
used by the simulation framework, but it can be useful, for instance,
for disassembly.
.SH "BUILD PROCESS"
.IX Header "BUILD PROCESS"
This section is an overview of how a diag is processed to produce
\&\fImem.image\fR.
.Sh "Preprocessing"
.IX Subsection "Preprocessing"
Diags are run through several preprocessing steps that enable complex
macro environments to perform diag setup.  Such macro environments are
not part of \fBmidas\fR and are therefore beyond the scope of this document.
.IP "Split perl and assembly" 4
.IX Item "Split perl and assembly"
The first preprocessing step is to split the diag into assembly and
perl parts.  \fBMidas\fR assumes that the diag is entirely assembly
unless it encounters the symbol \*(L"_\|_PERL_\|_\*(R" on a line by itself.  If it
sees this symbol, then everything after it assumed to be a perl
script.  The output of this phase are files in the build directory:
\&\fIdiag.s\fR and, if necessary, \fIdiag.pl\fR.
.IP "\fBcpp\fR" 4
.IX Item "cpp"
The next step is to run the diag through the C preprocessor.  Most
diags will #include their boot code and perhaps some project-specific
definitions.  Diags can also #define symbols before including the boot
code to configure its operation.  Note that this is a Sun, not a \s-1GNU\s0,
preprocessor, which means that \s-1GNU\s0 extensions to cpp (such as
preprocessor directives where the '#' isn't in column 1) cannot be
used.  For information the default include path, consult the \fBmidas\fR
man page.  The output of this stage is a file in the build directory
called \fIdiag.cpp\fR.
.IP "\fBm4\fR" 4
.IX Item "m4"
After \fBcpp\fR, the diag is processed by \fBm4\fR.  This allows macro
preprocessing that is substantially more powerful than what is
possible with \fBcpp\fR.  The content of these macros is
project\-specific.  The version of \fBm4\fR used by \fBmidas\fR is special in
that it was compiled to allow 64\-bit arithmetic via the \f(CW\*(C`mpeval\*(C'\fR
directive.  The output of this stage is a file in the build directory
called \fIdiag.m4\fR.
.IP "Sectioning" 4
.IX Item "Sectioning"
A diag is made up of sections.  Each section may contain a text, data,
bss or other segments.  The defining characteristic of a section is
that each segment is contiguous in the virtual address space (i.e.,
the text segment is contiguous and so is the data segment, but they
need not be contiguous with each other).  A section begins with a
\&\f(CW\*(C`SECTION\*(C'\fR directive at the beginning of a line.  The \f(CW\*(C`SECTION\*(C'\fR line
defines the section's name and optionally some parameters.  Any data
or code appearing after a \f(CW\*(C`SECTION\*(C'\fR directive belongs to that
section, until the next \f(CW\*(C`SECTION\*(C'\fR directive is encountered.  Any code
or data before the first \f(CW\*(C`SECTION\*(C'\fR directive is part of the first
section.
.Sp
If a \s-1SECTION\s0 line appears for a section that has previously been
defined, the meaning is to append to the existing section.  It is
illegal to have SECTION-line arguments for any but the first
definition of a section.  Note that it simply appends to the existing
section, so be sure to begin your appended version with a .text or
\&.data assembly directive, as appropriate.
.Sp
Sections are linked at a specific, user-defined address.  Linker
scripts require that each section be in a separte file.  The
sectioning phase, therefore, extracts the \f(CW\*(C`SECTION\*(C'\fR directives from
the assembly file and writes \*(L"pure\*(R" assembly files for each section.
By \*(L"pure\*(R", we mean that these files have no \fBmidas\fR\-specific
directives and can therefore be assembled directly.
.Sp
The output of this phase are a series of files in the build directory,
one for each section.  Their names are
\&\fIsec<num>.<secname>.s\fR.  The sectioning phase also
produces the file 'diag.midas' which contains all of the midas
directives.  Midas then parses this file, and leaves the others to the
assembler.
.Sh "Assembly"
.IX Subsection "Assembly"
Each section written by the sectioning phase above is assembled via
the \s-1GNU\s0 assembler.  The output is a .o file.
.Sh "Link executable"
.IX Subsection "Link executable"
All object files are linked, using the \s-1GNU\s0 loader.  Each section is
linked at the virtual address defined in its section header.  The
output of this phase is \fIdiag.exe\fR.
.Sh "PostProcessing"
.IX Subsection "PostProcessing"
After the diag is linked, the following postprocessing is done:
.IP "Generate \fImem.image\fR" 4
.IX Item "Generate mem.image"
Generation of \fImem.image\fR is done a section at a time, not by simply
disassembling \fIdiag.exe\fR.  The reason is that \fImem.image\fR should
represent the initial contents of physical memory, which may or may
not be a simple dump of the text and data segments for each section.
For most diags, this will simply be a hex dump of \fIdiag.exe\fR (with
the sections linked at the appropriate physical addresses, as defined
by the section header).  How exactly the \s-1MMU\s0 constructs \fImem.image\fR
is controlled by the section header, which is described in detail in
the next section.  Generation of \fImem.image\fR is handled by
\&\fBgoldfinger\fR.
.IP "Generate \fIsymbol.tbl\fR" 4
.IX Item "Generate symbol.tbl"
To generate the symbol table, the \fIdiag.exe\fR file is examined to find
virtual addresses for each symbol.  The \s-1MMU\s0 is then used to do the
virtual-to-physical translation and write the \fIsymbol.tbl\fR file.
Generation of \fIsymbol.tbl\fR is handled by \fBgoldfinger\fR.
.IP "Generate \fIdiag.ev\fR" 4
.IX Item "Generate diag.ev"
The \fIdiag.ev\fR file is generated by examining the diag source for
comments containing \f(CW$EV\fR.  These are then cross-referenced with
\&\fIsymbol.tbl\fR to producde \fIdiag.ev\fR.
.SH "DIAG FORMAT"
.IX Header "DIAG FORMAT"
A diag consists of applications and sections within those
applications.  Diags may also contain TSBs.
.Sh "\s-1APPLICATION\s0"
.IX Subsection "APPLICATION"
An application begins with:
.PP
.Vb 1
\&  APPLICATION <name> [FILE=<filename>]
.Ve
.PP
An application defines a single linked executable. All SECTIONs that
follow are linked into this application.  A linked executable is just
an intermediate file in \fImem.image\fR generation, so an \s-1APPLICATION\s0
directive affects only relocation and the scope of labels.  All diags
have at least one application, even if none is defined, since all
diags are treated as if their first line were:
.PP
.Vb 1
\&  APPLICATION default
.Ve
.PP
If the optional filename is given, then that file is taken as the
linked executable to use.  The link path is searched to find a file by
this name.  This is how you can include a linked executable that was
not generated by \fBmidas\fR.
.PP
\fIgoldfinger_cmd blocks\fR
.IX Subsection "goldfinger_cmd blocks"
.PP
There is currently no way to specify address translations and
\&\fImem.image\fR contents for applications that midas does not generate.
As the tool matures, I plan to invent an interface.  In the meantime,
you can include a goldfinger_cmd block.  Such a block begins a line
with \*(L"goldfinger_cmd\*(R" and an open curly\-brace.  It ends with the
closed\-curly.  The contents of the block are not interpreted \fBmidas\fR
at all.  They are simply copied into \fIdiag.goldfinger\fR inside the
currently open application.
.PP
An example:
.PP
.Vb 22
\& goldfinger_cmd {
\&   BLOCK .main_text_0
\&     SECTION_NAME = ".MAIN";
\&     SEGMENT_NAME = "text";
\&     LINK_SECTION = "sec7.maint";
\&     SRC_FILE     = "diag.m4";
\&     SRC_LINE     = 5398;
\&     COMPRESS     = 0;
\&     VA           = 0x0000000020000000;
\&     RA           = 0x0130000000;
\&     PA           = 0x1130000000;
\&     IN_IMAGE     = 1;
\&     BLOCK_TSB part_0_i_ctx_nonzero_ps0_tsb
\&       page_size = 8192;
\&       va_index_bits  = 21 : 13;
\&       tag_addr_bits  = 63 : 13;
\&       data_addr_bits = 39 : 13;
\&       tag_base = 0x0000000000000044;
\&       data_base = 0x8000000000000440;
\&     END BLOCK_TSB
\&   END BLOCK
\& }
.Ve
.PP
Note that until the tool matures, the \fBmidas\fR\-\fBgoldfinger\fR interface
may change, so this syntax is deprecated, but it can be useful in a
pinch.
.Sh "\s-1SECTION\s0 Definitions"
.IX Subsection "SECTION Definitions"
A \s-1SECTION\s0 defines a region of the diag that may contain up to 3
segments: text, data, and bss.  Each of these segments is contiguous
in the virtual address space (but not necessarily in the real or
physical address spaces).  Note that the \fBmidas\fR terminology is
different from the \fB\s-1ELF\s0\fR terminology.  Each segment in \fBmidas\fR
terminology corresponds to an \fB\s-1ELF\s0\fR section.
.PP
.Vb 1
\&  SECTION <name> [section_args]
.Ve
.PP
When a section directive is encountered, all assembly code (and data)
that follows is placed in that section, until the next \s-1SECTION\s0
directive is encountered.
.PP
The \f(CW\*(C`SECTION\*(C'\fR header affects the text and data segments that follow
it, until another \f(CW\*(C`SECTION\*(C'\fR header is reached.  As a special case,
all code and data in the assembly file before the first \f(CW\*(C`SECTION\*(C'\fR
header belongs to the first section.  A \s-1SECTION\s0 line may be split
across multiple lines of input by escaping the newline with a \e.
.PP
The section_args should define the virtual addresses at which to link
the various segments.  This is done by a comma-separated list such as:
.PP
.Vb 2
\&  SECTION .MAIN  TEXT_VA=0x20000000, DATA_VA=0x60000000, \e
\&                 BSS_VA=0x68030000
.Ve
.PP
Any of the virtual addresses may be ommitted, but if they are, that
segment will not be included in the link.  The *_VA symbols are all
case\-insensitive.  The addresses themselves are assumed to be 64\-bit
decimal numbers, unless they start with 0x (in which case they are
64\-bit hex numbers).
.PP
See the section on \*(L"\s-1ADDRESS\s0 \s-1TRANSLATIONS\s0\*(R" for details on how
address translations can be specified for the segments in a section.
Note that unless address translations are specified, there is no
physical address to place segments in the \fImem.image\fR file!
.Sh "\s-1TSB\s0 \s-1OBJECT\s0 \s-1DEFINITIONS\s0"
.IX Subsection "TSB OBJECT DEFINITIONS"
A \s-1TSB\s0 object is decared with the following syntax:
.PP
.Vb 1
\&  MIDAS_TSB <name> <register> [args]
.Ve
.PP
This defines a \s-1TSB\s0 with the specified name, which is initialized by
the config register <register>.  It will be instantiated in
the memory image if any attr block tries to use it.  All \s-1MMU\s0 types get
a base address and \s-1TSB\s0 size from the config register as defined in
their \s-1PRM\s0.  Niagara\-2, in addition, parses a page size (same meaning
as the page_size optional argument below) and sun4u/sun4v, which will
be used instead of the global default for ttefmt.  Note that if you
provide the optional arguments page_size and/or ttefmt for Niagara\-2,
the optional arguments will override the config register.
.PP
The optional args can be:
.IP "link=<name>" 4
.IX Item "link=<name>"
Use the specified name as a link area.  This is used in the case of
\&\s-1TSB\s0 collisions to hold a linked list.  There must be \s-1MIDAS_TSB_LINK\s0
declaration by this name.
.IP "force_ctx_zero" 4
.IX Item "force_ctx_zero"
If this is specified, then any entries added to this \s-1TSB\s0 will have
context bits of zero, regardless of how they are specified in the attr blocks.
.IP "page_size=<codedSize>" 4
.IX Item "page_size=<codedSize>"
This defines a default page size for all entries that are added to the
\&\s-1TSB\s0.  This will be used if no TTE_Size_Ptr values are given for the
entries.  The coded size is the same encoding used in the TTE_Size
field.
.IP "way=<way>" 4
.IX Item "way=<way>"
If a \s-1TSB\s0 is split (which only applies to the \*(L"ultra2\*(R" and \*(L"niagara\*(R"
\&\s-1MMU\s0 types), this is specified to midas by creating two TSBs that have
the same value of the config register with the split bit set.  Midas
treats each half of the \s-1TSB\s0 separately.  This makes it easy for diags
to control which half of the split \s-1TSB\s0 gets each translation.  The way
definition on the \s-1TSB\s0 line tells midas which half of the split \s-1TSB\s0
applies to this definition.  The only legal settings are \*(L"way=0\*(R" and
\&\*(L"way=1\*(R".  If way is set to zero, the \s-1TSB\s0 is configured just as if it
were not split.  If way is set to one, then the base address is
modifed internally so that it starts after the way=0 \s-1TSB\s0 would end.
The way setting is ignored if the \s-1TSB\s0 is not split or if the \s-1MMU\s0 type
does not support split TSBs.  It is the responsibility of the diag
writer to make sure that the two halves of a split \s-1TSB\s0 are configured
in a compatible fashion (both sides having split bit on and the same
base address).
.IP "ttefmt=<format>" 4
.IX Item "ttefmt=<format>"
Sets the format for this \s-1TSB\s0 to the specified format (either sun4u or
sun4v).  This setting will be used instead of the default value of
\&\-ttefmt.
.Sh "\s-1TSB_LINK\s0 \s-1OBJECT\s0 \s-1DEFINITIONS\s0"
.IX Subsection "TSB_LINK OBJECT DEFINITIONS"
A \s-1TSB_LINK\s0 object is an area used to store linked lists in the case of
collisions in the \s-1TSB\s0.  Multiple TSBs can share a \s-1TSB_LINK\s0.  The
syntax is:
.PP
.Vb 1
\&  MIDAS_TSB_LINK <name> <pa>
.Ve
.PP
This declares a \s-1TSB_LINK\s0 object that will start at the specified \s-1PA\s0.
It will be instantiated in the memory image if any \s-1TSB\s0 that uses it is
instantiated.
.Sh "\s-1ADDRESS\s0 \s-1TRANSLATIONS\s0"
.IX Subsection "ADDRESS TRANSLATIONS"
Address translations are created by attr_ blocks.  The name of the
block defines the segment on which the block operates.  They syntax is:
.PP
.Vb 6
\&  attr_<segment_name> {
\&     name|section=<name>,
\&     <key>=<val>, <key>=<val>,
\&     <key>=<val>
\&     ...
\&  }
.Ve
.PP
The <segment_name> may be \*(L"text\*(R", \*(L"data\*(R", or \*(L"bss\*(R".  Each attr
block must specify which \s-1SECTION\s0 they belong to.  They do this by
setting name= or section= inside the block.  This means the attr block
itself may appear anywhere in the diag, not necessarily lexically
inside the section.  The blocks are matched to the sections by name,
which is case\-insensitive.
.PP
The contents of the block are a list of key=value pairs (name|section=
just being a special case).  These pairs can be separated by commas
and/or newlines.  Key names are case\-insensitive.  A \s-1TSB\s0 name may
appear as a key with no value.  If any other key appears with no
=value, the value is assumed to be 1.
.PP
An example of an attr block is:
.PP
.Vb 10
\& attr_text {
\&        Name = .TRAPS,
\&        RA = 0x120000,
\&        PA = 0x1000120000,
\&        part_0_i_ctx_zero_ps0_tsb,
\&        TTE_Context=0, TTE_V=1, TTE_Size=0,
\&        TTE_NFO=0, TTE_IE=0, TTE_Soft2=0, TTE_Diag=0,
\&        TTE_Soft=0, TTE_L=0, TTE_CP=1, TTE_CV=0,
\&        TTE_E=0, TTE_P=1, TTE_W=1
\& }
.Ve
.PP
An attr block has two purposes: setting up \s-1TSB\s0 mappings and writing to
\&\fImem.image\fR.  It therefore needs to contain enough information to:
.IP "Select a subset of the segment" 4
.IX Item "Select a subset of the segment"
An attr block need not define the same translation for an entire
segment, and it may define a subset of the segment on which to
operated.
.IP "Physical address" 4
.IX Item "Physical address"
This defines where to write the segment (or segment subset) in the
\&\fImem.image\fR.
.IP "Define \s-1TSB\s0 parameters" 4
.IX Item "Define TSB parameters"
These include a list of TSBs that should contain translations for this
section, an \s-1RA\s0 (real address) that should be included in the \s-1TSB\s0, and
\&\s-1TTE\s0 elements.  The exact details may be processor\-specific.  It is
controlled by the mmu type.  Note that for MMUs that do not have
two-level address translation (i.e., \*(L"ultra2\*(R"), there is no \s-1RA\s0, so \s-1PA\s0
is used for TSBs instead.
.PP
\fISelecting a subset\fR
.IX Subsection "Selecting a subset"
.PP
Selecting a subset consits of defining a starting and stopping virtual
address for the block.
.PP
Defining the starting virtual address
.IX Subsection "Defining the starting virtual address"
.IP "start_label" 4
.IX Item "start_label"
If the key \f(CW\*(C`start_label\*(C'\fR exists it must be a label inside the
segment.  It is used as the beginning of the attr block.  It must be a
page-aligned address unless the block is not being entered into a \s-1TSB\s0.
.IP "\s-1VA\s0" 4
.IX Item "VA"
The attr block may explicitly define a starting virtual address using
the tag \f(CW\*(C`VA\*(C'\fR.  It is an error if this virtual address is not a
page-aligned address within the segment (if the block is not writing a
\&\s-1TSB\s0 entry the alignment contraint is relaxed).  For this reason, the
start_label syntax is the preferred one for most diags.
.IP "\fIdefault\fR" 4
.IX Item "default"
If neither \s-1VA\s0 nor start_label are specified for an attr block, the
starting \s-1VA\s0 for the segment is used.
.PP
Defining the ending virtual address
.IX Subsection "Defining the ending virtual address"
.PP
There are three ways to define the ending address for an attr block.
.IP "end_label" 4
.IX Item "end_label"
If \f(CW\*(C`end_label\*(C'\fR is defined, it must be label inside the segment (and
of course, it must appear after the starting \s-1VA\s0).  The \f(CW\*(C`attr_text\*(C'\fR
definiton ends at the address of the label.  The address need not be
page\-aligned.
.IP "end_va" 4
.IX Item "end_va"
The attr block may explicitly define an ending virtual address.  It is
an error if this address is not part of this segment.  If the special
attribute \f(CW\*(C`uninitialized\*(C'\fR is used (see below), then end_va may be
specified past the end of the segment.  The \f(CW\*(C`uninitialized\*(C'\fR attribute
implies \f(CW\*(C`tsbonly\*(C'\fR (i.e., data is written to the \s-1TSB\s0 but not to the
memory image).
.IP "\fIdefault\fR" 4
.IX Item "default"
If neither end_label nor end_va are specified, then the attr block
lasts until the end of the section.
.PP
\fIPhysical address\fR
.IX Subsection "Physical address"
.PP
An attr block must have one of the following keys to define the
physical address.  The physical address is used to write \fImem.image\fR
.IP "\s-1PA\s0" 4
.IX Item "PA"
The physical address is specified with the tag \*(L"\s-1PA\s0\*(R".  It should be set
to an address, and the subset of the segment will be written to the
\&\fImem.image\fR file at that physical address.  It is an error to write
to the same physical address twice in the same diag.
.IP "tsbonly" 4
.IX Item "tsbonly"
This special key tells the attr block not to write anything to
\&\fImem.image\fR.  It can be used if you want to create \s-1TSB\s0 entries but do
not want to overwrite something to \fImem.image\fR.  If the key \*(L"\s-1PA\s0\*(R" is
included, it is used only for symbol table generation.
.IP "uninitialized" 4
.IX Item "uninitialized"
This is exactly the same as tsbonly, except that normally the \*(L"end_va\*(R"
key is checked to make sure that it is contained in the segment.
Using uninitialized instead of tsbonly suspends that check.
.ie n .IP "hypervisor (or bypass on ""ultra2"" \s-1MMU\s0)" 4
.el .IP "hypervisor (or bypass on ``ultra2'' \s-1MMU\s0)" 4
.IX Item "hypervisor (or bypass on ultra2 MMU)"
The special tag \*(L"hypervisor\*(R" tells the attr block bypass both \s-1VA\s0 to \s-1RA\s0
translation and \s-1RA\s0 to \s-1PA\s0 tranlation.  The segment will be completely
unmapped.  Therefore, it will not generate any \s-1TSB\s0 mappings, and it
will write to \fImem.image\fR at PA=VA (actually, it generates a \s-1PA\s0 from
as many low bits of the \s-1VA\s0 as will fit in a \s-1PA\s0).  It is used for
segments where the \s-1MMU\s0 is off.  For mmus that have only one level of
address translation (i.e., \*(L"ultra2\*(R"), the key \*(L"hypervisor\*(R" does not
exist, but \*(L"bypass\*(R" has the same meaning.
.IP "compressimage" 4
.IX Item "compressimage"
This does not control the address, but it does affect how \fImem.image\fR
creation is done.  If compressimage is given in an attr block then
lines of zeros are suppressed in \fImem.image\fR generation.  Each
aligned 32\-byte chunk is compared against 0.  If all bits are 0, then
it is not written to mem.image.  If the global \-env_zero switch is
enabled (on by default in Niagara\-1), then a backdoor mechanism is
used to initialize the memory to zero in the environment.  Otherwise,
it is left uninitialized.  If the environment does not intialize all
memory to zero, then this can actually change the meaning of
mem.image, since it makes zero-ed memory uninitialized, rather than
intialized to zero.  If the flag \-nocompress_image is given to
\&\fBmidas\fR, then no blocks are compressed, regardless of compressimage
tags.
.Sp
\fI\s-1TSB\s0 parameters\fR
.IX Subsection "TSB parameters"
.Sp
The following parameters should be set in each attr block (unless it
contains the \*(L"hypervisor\*(R" key described above, or the \*(L"bypass\*(R" key for
\&\*(L"ultra2\*(R"):
.RS 4
.IP "\s-1RA\s0" 4
.IX Item "RA"
This defines the real address (middle of the 3\-address scheme).  It is
the address to be written to the \s-1TSB\s0 data.  It must be page\-aligned.
In the \*(L"ultra2\*(R" \s-1MMU\s0, there is no \s-1RA\s0, so the \s-1PA\s0 gets double\-duty: \s-1PA\s0 is
used both for mem.image generation and for \s-1TSB\s0 data.
.IP "bypass" 4
.IX Item "bypass"
This directive means to bypass \s-1VA\s0 to \s-1RA\s0 translation.  In an \s-1MMU\s0 with
two levels of address translation (like niagara), it simply sets RA=VA
(actually, as many low bits of \s-1VA\s0 as will fit).  It is an error to
specify both \s-1RA\s0 and bypass.  In an \s-1MMU\s0 with one level of translation
(\*(L"ultra2\*(R"), it means to bypass all address translation, so its
function is similar to the hypervisor directive described above.
.IP "<tsb_name>" 4
.IX Item "<tsb_name>"
Any tsb names that are listed (and there may be more than one) will
cause the attr block to add the subset to those TSBs.  The tsb_names
must be defined somewhere in the diag with a \s-1MIDAS_TSB\s0 directive.
.IP "notsb" 4
.IX Item "notsb"
Tells the attr block not to do any \s-1TSB\s0 generation.  If \s-1RA\s0 is provided,
it is simply used in the symbol table.
.RE
.RS 4
.Sp
Unless notsb is defined or the section is completely unmapped (bypass
for \*(L"ultra2\*(R" or hypervisor for other MMUs), the attr block will be
writing \s-1TSB\s0 entries.  The following parameters are used to set the
appropriate bits of the \s-1TSB\s0 entry.  How exactly the \s-1TSB\s0 entries are
formed is mmu\-specific.  Check the \s-1PRM\s0 for your processor.  The
default value for \s-1TTE_V\s0 (valid) is 1.  The default value for all other
fields is 0.
.Sp
\fIMMU-Specific \s-1TTE\s0 Settings\fR
.IX Subsection "MMU-Specific TTE Settings"
.Sp
The fields in the \s-1TSB\s0 tag and data depend on the \s-1MMU\s0 type and the
currently configured ttefmt setting (sun4u or sun4v).  The ttefmt is
can be contralled by the TSBs (which is always the case in Niagara\-2)
or by the global default set by \-ttefmt.  The \s-1MMU\s0 specific settings
are described below.  The default for each \s-1TTE\s0 setting is 0, except
for \s-1TTE_V\s0 (valid), which defaults to 1.  All \s-1TTE\s0 tags are
case\-insensitive.
.Sp
Ultrasparc \s-1II\s0 \s-1MMU\s0 \*(L"ultra2\*(R"
.IX Subsection "Ultrasparc II MMU ultra2"
.Sp
The ultra2 \s-1MMU\s0 type supports only the sun4u \s-1TTE\s0 data format.
.IP "\s-1TTE_G\s0         Tag: 1 bit  Global" 4
.IX Item "TTE_G         Tag: 1 bit  Global"
.PD 0
.IP "TTE_Context   Tag:13 bits Context" 4
.IX Item "TTE_Context   Tag:13 bits Context"
.PD
%%TTE \s-1DATA\s0 ultra2 sun4u
.RE
.RS 4
.Sp
Niagara \s-1MMU\s0 \*(L"niagara\*(R"
.IX Subsection "Niagara MMU niagara"
.Sp
The niagara \s-1MMU\s0 supports both the sun4u and sun4v \s-1TTE\s0 data formats.
.Sp
For sun4u, the following fields are valid:
.IP "TTE_Context   Tag:13 bits Context" 4
.IX Item "TTE_Context   Tag:13 bits Context"
%%TTE \s-1DATA\s0 niagara sun4u
.RE
.RS 4
.Sp
The following fields are valid for sun4v:
.IP "TTE_Context   Tag:13 bits Context" 4
.IX Item "TTE_Context   Tag:13 bits Context"
%%TTE \s-1DATA\s0 niagara sun4v
.RE
.RS 4
.Sp
Niagara2 \s-1MMU\s0 \*(L"niagara2\*(R"
.IX Subsection "Niagara2 MMU niagara2"
.Sp
The niagara2 \s-1MMU\s0 supports both the sun4u and sun4v \s-1TTE\s0 data format.
.Sp
For sun4u, the following fields are valid:
.IP "TTE_Context   Tag:13 bits Context" 4
.IX Item "TTE_Context   Tag:13 bits Context"
%%TTE \s-1DATA\s0 niagara2 sun4u
.RE
.RS 4
.Sp
The following fields are valid for sun4v:
.IP "TTE_Context   Tag:13 bits Context" 4
.IX Item "TTE_Context   Tag:13 bits Context"
%%TTE \s-1DATA\s0 niagara2 sun4v
.RE
.RS 4
.IP "TTE_Context   Tag:13 bits Context" 4
.IX Item "TTE_Context   Tag:13 bits Context"
%%TTE \s-1DATA\s0 sun4v
.RE
.RS 4
.Sp
There are a few special cases to be aware of:
.IP "TTE_Size" 4
.IX Item "TTE_Size"
This is the size bits field to use in the \s-1TSB\s0 entry.  It is also used
to calculate the number of pages the attr block will create.  The attr
block will create as many pages as it needs to to span the section.
The TTE_Size field controls the size of these pages.  See the \s-1PRM\s0 for
the exact coding of page size in TTE_Size.  For Niagara, Niagara\-2,
the encoding is:
.RS 4
.IP "0 \-> 8 kB" 4
.IX Item "0 -> 8 kB"
.PD 0
.IP "1 \-> 64 kB" 4
.IX Item "1 -> 64 kB"
.IP "2 \-> 512 kB (illegal on Niagara and Niagara\-2)" 4
.IX Item "2 -> 512 kB (illegal on Niagara and Niagara-2)"
.IP "3 \-> 4 \s-1MB\s0" 4
.IX Item "3 -> 4 MB"
.IP "5 \-> 256 \s-1MB\s0" 4
.IX Item "5 -> 256 MB"
.IP "6 \-> 2 \s-1GB\s0 (illegal on Niagara and Niagara\-2)" 4
.IX Item "6 -> 2 GB (illegal on Niagara and Niagara-2)"
.IP "7 \-> 16 \s-1GB\s0 (illegal on Niagara and Niagara\-2)" 4
.IX Item "7 -> 16 GB (illegal on Niagara and Niagara-2)"
.RE
.RS 4
.PD
.Sp
The \*(L"ultra2\*(R" \s-1MMU\s0 only has a 2\-bit size field, so it supports page
sizes 0\-3 (which are also 8 kB \- 4 \s-1MB\s0).
.Sp
Note that when the above sections state that \s-1VA\s0, \s-1RA\s0, and \s-1PA\s0 must be
page-aligned when adding them to a \s-1TSB\s0, this is where the page size
comes from.
.RE
.IP "TTE_Size_Ptr" 4
.IX Item "TTE_Size_Ptr"
The page size is used in the formula to calculate a \s-1TSB\s0 pointer.  The
page size used for pointer calculation is controlled by a hardware
register, but \fBmidas\fR needs to set up the TSBs statically.  By
default, the attr block with use TTE_Size when it computes the \s-1TSB\s0
index (or the \s-1TSB\s0 page_size parameter/Niagara\-2 \s-1TSB\s0 config, if one is
defined), as well as for the uses above.  If you set TTE_Size_Ptr,
however, it will use this as the page size setting when computing the
\&\s-1TSB\s0 index.  Use this whenever you wish to have a different setting for
TTE_Size than the hardware will have in its config register.
.RE
.RS 4
.Sh "High Level Languages"
.IX Subsection "High Level Languages"
The output of compilers of high-level languages may be inserted into midas.
.Sp
\fIObject files\fR
.IX Subsection "Object files"
.Sp
The midas directive:
.Sp
.Vb 1
\&  MIDAS_OBJ FILE=<something.o>
.Ve
.Sp
may be placed inside any section.  That object file will be linked
with the assembly output for the section and will share its attr
blocks.  No special interpretation is done on the contents of the
object file \- the text, data, and bss segments are simply linked in
with the output of the assembler for that section.  The search path
for .o files is controlled by the \-L switch.  The default path is the
starting directory, and <diag_root>/verif/diag.
.Sp
\fILibrary files\fR
.IX Subsection "Library files"
.Sp
The midas directive:
.Sp
.Vb 1
\&  MIDAS_LIB FILE=<something.a>
.Ve
.Sp
Works just like a \s-1MIDAS_OBJ\s0 directive, except that it includes a
library in the link.  Note that the library must be static (i.e., a .a
file, and not a .so file), because there is no runtime linker in the
diag environment.  Other than the file format, the difference between
a library file and an object file, is that an object file will include
all text/data/bss from the file, but linking with a library file will
cause only those symbols that are actually used to be included.
.Sp
Library files will also search the same link path as object files.
.Sp
\fIC files\fR
.IX Subsection "C files"
.Sp
Simiar to object files, C language files may be included with the
directive:
.Sp
.Vb 1
\&  MIDAS_CC FILE=<something.c>  [OUTPUT=<something.o>] [ARGS=-O2]
.Ve
.Sp
The \s-1OUTPUT\s0 and \s-1ARGS\s0 tags are optional, but the \s-1FILE\s0 tag is mandatory.
The search path for the C source file is controleld by the \-C switch,
and the default is the starting directory, then
<diag_root>/verif/diag/c.  The \s-1ARGS\s0 tag (which must appear
last, since the args last until the end of the line) is arguments to
gcc.  You must not use the \-o or \-c switches, since midas will provide
its own.  If \*(L"\-S\*(R" is supplied to gcc through the \s-1ARGS\s0 tag, then gcc \-S
will be used to create an assembly file in the Sectioning phase, which
will then be assembled like all the other assembly files in the
Assembly phase.  If \-S is not present, then nothing is done in the
Sectioning phase (except for finding the C file and copying it to the
build directory).  Rather, gcc is used to compile the C file directly
to an object file during the assembly phase.  The object file,
generated either by gcc or by the of assembling of gcc \-S, is then
linked in with the rest of the section.  Once the object file is
generated, it is treated just as a \s-1MIDAS_OBJ\s0 directive.
.Sp
Stack
.IX Subsection "Stack"
.Sp
Compiled C code expects the system to set up a stack for it before it
runs.  Template files are provided for this purpose.  Be sure to use
them or have some solution for setting up the stack if you are working
with compiled code.
.SH "AUTHOR"
.IX Header "AUTHOR"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBmidas\fR(1), tre_perldoc Midas, \fBpal\fR(1), \fBgoldfinger\fR(1).