.\" 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 "@", 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..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 [FILE=] .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 [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 [args] .Ve .PP This defines a \s-1TSB\s0 with the specified name, which is initialized by the config 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=" 4 .IX Item "link=" 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=" 4 .IX Item "page_size=" 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=" 4 .IX Item "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=" 4 .IX Item "ttefmt=" 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 .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_ { \& name|section=, \& =, =, \& = \& ... \& } .Ve .PP The 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 "" 4 .IX Item "" 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= .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 /verif/diag. .Sp \fILibrary files\fR .IX Subsection "Library files" .Sp The midas directive: .Sp .Vb 1 \& MIDAS_LIB FILE= .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= [OUTPUT=] [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 /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).