Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | |
2 | eval 'exec $PERL_CMD -S $0 ${1+"$@"}' | |
3 | if 0; # not running under some shell | |
4 | ||
5 | use strict; | |
6 | use Pod::Usage; | |
7 | use File::Temp qw(tempfile); | |
8 | use Midas::MMU::TTEFormat; | |
9 | ||
10 | my ($ofh, $filename) = tempfile(".midasformat.XXXX", UNLINK=>1); | |
11 | ||
12 | my $src = $0; | |
13 | open(SRC, "<$src") || die "Can't open '$src': $!\n"; | |
14 | while(<SRC>) { | |
15 | my $line = $_; | |
16 | ||
17 | if($line =~ /^\%\%TTE\s*DATA\s*(\S+)\s*(\S+)/) { | |
18 | my ($mmu, $format) = ($1, $2); | |
19 | ||
20 | if(exists $TSB_DATA_FORMAT{$mmu}{$format}) { | |
21 | ||
22 | foreach my $key (keys %{$TSB_DATA_FORMAT{$mmu}{$format}}) { | |
23 | my $rec = $TSB_DATA_FORMAT{$mmu}{$format}{$key}; | |
24 | ||
25 | ||
26 | my $bits = ($rec->{hi} == $rec->{lo}) ? | |
27 | "$rec->{hi}" :"$rec->{hi}:$rec->{lo}"; | |
28 | ||
29 | printf $ofh "=item TTE_%-6s Bits %5s ", $key, $bits; | |
30 | ||
31 | if(defined $rec->{descr}) { | |
32 | print $ofh "$rec->{descr}\n"; | |
33 | print $ofh "\n"; | |
34 | } | |
35 | ||
36 | print $ofh "\n"; | |
37 | ||
38 | } | |
39 | } | |
40 | } else { | |
41 | print $ofh $line; | |
42 | } | |
43 | } | |
44 | close SRC; | |
45 | ||
46 | pod2usage(-verbose => 2, | |
47 | -exitval => 0, | |
48 | -input => $filename); | |
49 | ||
50 | exit(0); | |
51 | ||
52 | __END__ | |
53 | ||
54 | =head1 NAME | |
55 | ||
56 | midasformat - Format for diags recognized by B<midas> | |
57 | ||
58 | =head1 DESCRIPTION | |
59 | ||
60 | This document describes the format of diags that can be assembled by | |
61 | B<midas>. Note that this is not a guide for writing diags, since it | |
62 | makes no assumptions about the contents of project-standard include | |
63 | files or boot code. | |
64 | ||
65 | =head2 Source Languages | |
66 | ||
67 | B<Midas> can assemble diags in the following formats: | |
68 | ||
69 | =over 4 | |
70 | ||
71 | =item Augmented Assembly | |
72 | ||
73 | The main supported source language, denoted with a .s extension on the | |
74 | source file, is an augmented SPARC assembly file. By "augmented", we | |
75 | refer to several directives used to program the MMU. These directives | |
76 | are interpreted by B<midas>, and their presence means that the raw diag, | |
77 | even though it ends in .s, would not be acceptable input to a standard | |
78 | assembler. | |
79 | ||
80 | An assembly diag should be one file, though it may #include others. A | |
81 | diag may also contain a perl script, used by the simulation framework | |
82 | to do postprocessing on the diag's output. B<Midas> scans a diag for the | |
83 | symbol "__PERL__" on a line by itself. If it finds such a symbol, | |
84 | then everything after the __PERL__ line is taken to be a perl script | |
85 | and is not assembled. | |
86 | ||
87 | =item PAL (perl augmented language) | |
88 | ||
89 | A diag that ends in a .pal extension is assumed to be written in PAL | |
90 | (perl augmented language). The diag is run through the PAL | |
91 | preprocessor, and the output of PAL should be an augmented assembly | |
92 | file as described above. B<Midas> takes care of running the PAL | |
93 | preprocesing phase if the diag ends in .pal. Since PAL and assembly | |
94 | diags are treated identically after PAL preprocessing, the remainder | |
95 | of the this document discusses only assembly diags. | |
96 | ||
97 | =item C | |
98 | ||
99 | The top-level diag file is always an augmented assembly file (or a PAL | |
100 | script that generated an augmented assembly file), but there are | |
101 | directives to include C programs in a diag. See the L</"High Level | |
102 | Languages"> section. | |
103 | ||
104 | =item Object files (.o) and Library files (.a) | |
105 | ||
106 | As with C files, raw object (.o) files and static library (.a) files | |
107 | may be included in a diag. See the L</"High Level Languages"> | |
108 | section. | |
109 | ||
110 | =item Linked Executables | |
111 | ||
112 | These can be included as-is in a diag. See the L</"APPLICATION"> | |
113 | section. | |
114 | ||
115 | =back | |
116 | ||
117 | =head2 Output Files | |
118 | ||
119 | The following output files are generated by B<midas>: (the names of the | |
120 | output files can be reconfigured, but these are the default names) | |
121 | ||
122 | =over 4 | |
123 | ||
124 | =item F<mem.image> | |
125 | ||
126 | The F<mem.image> file is the main output of B<midas>. It contains the | |
127 | initial contents of physical memory in a verilog memory-image format. | |
128 | The format consists lines containing "@E<lt>physical_addressE<gt>", | |
129 | followed by lines of data to write at that address. | |
130 | ||
131 | =item F<diag.ev> | |
132 | ||
133 | This is an event file generated for vera. Any assembly line that | |
134 | contains a comment that begins with "$EV" will generate an entry in | |
135 | this file. I<XXX - this format should be documented further.> | |
136 | ||
137 | =item F<symbol.tbl> | |
138 | ||
139 | This file contains 4 columns: symbol_name, virtual_addres, real | |
140 | address, and physical_address. It exists to support the simulation | |
141 | framework so it can lookup addresses for symbol names. If any of the | |
142 | addresses are inappropriate (such as real address for unmapped | |
143 | sections), it will be represented by 'X'. | |
144 | ||
145 | =item F<diag.pl> | |
146 | ||
147 | This is a perl script extracted from the diag (i.e., the code after | |
148 | the "__PERL__" directive). It is used by the simulation framework to | |
149 | do diag-specific post-processing. | |
150 | ||
151 | =item F<diag*.exe> | |
152 | ||
153 | This is the linked executable built by B<midas> (the * is the name of | |
154 | the application, if there is a non-default application). It is not | |
155 | used by the simulation framework, but it can be useful, for instance, | |
156 | for disassembly. | |
157 | ||
158 | =back | |
159 | ||
160 | =head1 BUILD PROCESS | |
161 | ||
162 | This section is an overview of how a diag is processed to produce | |
163 | F<mem.image>. | |
164 | ||
165 | =head2 Preprocessing | |
166 | ||
167 | Diags are run through several preprocessing steps that enable complex | |
168 | macro environments to perform diag setup. Such macro environments are | |
169 | not part of B<midas> and are therefore beyond the scope of this document. | |
170 | ||
171 | =over 4 | |
172 | ||
173 | =item Split perl and assembly | |
174 | ||
175 | The first preprocessing step is to split the diag into assembly and | |
176 | perl parts. B<Midas> assumes that the diag is entirely assembly | |
177 | unless it encounters the symbol "__PERL__" on a line by itself. If it | |
178 | sees this symbol, then everything after it assumed to be a perl | |
179 | script. The output of this phase are files in the build directory: | |
180 | F<diag.s> and, if necessary, F<diag.pl>. | |
181 | ||
182 | =item B<cpp> | |
183 | ||
184 | The next step is to run the diag through the C preprocessor. Most | |
185 | diags will #include their boot code and perhaps some project-specific | |
186 | definitions. Diags can also #define symbols before including the boot | |
187 | code to configure its operation. Note that this is a Sun, not a GNU, | |
188 | preprocessor, which means that GNU extensions to cpp (such as | |
189 | preprocessor directives where the '#' isn't in column 1) cannot be | |
190 | used. For information the default include path, consult the B<midas> | |
191 | man page. The output of this stage is a file in the build directory | |
192 | called F<diag.cpp>. | |
193 | ||
194 | =item B<m4> | |
195 | ||
196 | After B<cpp>, the diag is processed by B<m4>. This allows macro | |
197 | preprocessing that is substantially more powerful than what is | |
198 | possible with B<cpp>. The content of these macros is | |
199 | project-specific. The version of B<m4> used by B<midas> is special in | |
200 | that it was compiled to allow 64-bit arithmetic via the C<mpeval> | |
201 | directive. The output of this stage is a file in the build directory | |
202 | called F<diag.m4>. | |
203 | ||
204 | =item Sectioning | |
205 | ||
206 | A diag is made up of sections. Each section may contain a text, data, | |
207 | bss or other segments. The defining characteristic of a section is | |
208 | that each segment is contiguous in the virtual address space (i.e., | |
209 | the text segment is contiguous and so is the data segment, but they | |
210 | need not be contiguous with each other). A section begins with a | |
211 | C<SECTION> directive at the beginning of a line. The C<SECTION> line | |
212 | defines the section's name and optionally some parameters. Any data | |
213 | or code appearing after a C<SECTION> directive belongs to that | |
214 | section, until the next C<SECTION> directive is encountered. Any code | |
215 | or data before the first C<SECTION> directive is part of the first | |
216 | section. | |
217 | ||
218 | If a SECTION line appears for a section that has previously been | |
219 | defined, the meaning is to append to the existing section. It is | |
220 | illegal to have SECTION-line arguments for any but the first | |
221 | definition of a section. Note that it simply appends to the existing | |
222 | section, so be sure to begin your appended version with a .text or | |
223 | .data assembly directive, as appropriate. | |
224 | ||
225 | ||
226 | Sections are linked at a specific, user-defined address. Linker | |
227 | scripts require that each section be in a separte file. The | |
228 | sectioning phase, therefore, extracts the C<SECTION> directives from | |
229 | the assembly file and writes "pure" assembly files for each section. | |
230 | By "pure", we mean that these files have no B<midas>-specific | |
231 | directives and can therefore be assembled directly. | |
232 | ||
233 | The output of this phase are a series of files in the build directory, | |
234 | one for each section. Their names are | |
235 | F<secE<lt>numE<gt>.E<lt>secnameE<gt>.s>. The sectioning phase also | |
236 | produces the file 'diag.midas' which contains all of the midas | |
237 | directives. Midas then parses this file, and leaves the others to the | |
238 | assembler. | |
239 | ||
240 | =back | |
241 | ||
242 | =head2 Assembly | |
243 | ||
244 | Each section written by the sectioning phase above is assembled via | |
245 | the GNU assembler. The output is a .o file. | |
246 | ||
247 | =head2 Link executable | |
248 | ||
249 | All object files are linked, using the GNU loader. Each section is | |
250 | linked at the virtual address defined in its section header. The | |
251 | output of this phase is F<diag.exe>. | |
252 | ||
253 | =head2 PostProcessing | |
254 | ||
255 | After the diag is linked, the following postprocessing is done: | |
256 | ||
257 | =over 4 | |
258 | ||
259 | =item Generate F<mem.image> | |
260 | ||
261 | Generation of F<mem.image> is done a section at a time, not by simply | |
262 | disassembling F<diag.exe>. The reason is that F<mem.image> should | |
263 | represent the initial contents of physical memory, which may or may | |
264 | not be a simple dump of the text and data segments for each section. | |
265 | For most diags, this will simply be a hex dump of F<diag.exe> (with | |
266 | the sections linked at the appropriate physical addresses, as defined | |
267 | by the section header). How exactly the MMU constructs F<mem.image> | |
268 | is controlled by the section header, which is described in detail in | |
269 | the next section. Generation of F<mem.image> is handled by | |
270 | B<goldfinger>. | |
271 | ||
272 | =item Generate F<symbol.tbl> | |
273 | ||
274 | To generate the symbol table, the F<diag.exe> file is examined to find | |
275 | virtual addresses for each symbol. The MMU is then used to do the | |
276 | virtual-to-physical translation and write the F<symbol.tbl> file. | |
277 | Generation of F<symbol.tbl> is handled by B<goldfinger>. | |
278 | ||
279 | =item Generate F<diag.ev> | |
280 | ||
281 | The F<diag.ev> file is generated by examining the diag source for | |
282 | comments containing C<$EV>. These are then cross-referenced with | |
283 | F<symbol.tbl> to producde F<diag.ev>. | |
284 | ||
285 | =back | |
286 | ||
287 | =head1 DIAG FORMAT | |
288 | ||
289 | A diag consists of applications and sections within those | |
290 | applications. Diags may also contain TSBs. | |
291 | ||
292 | =head2 APPLICATION | |
293 | ||
294 | An application begins with: | |
295 | ||
296 | APPLICATION <name> [FILE=<filename>] | |
297 | ||
298 | An application defines a single linked executable. All SECTIONs that | |
299 | follow are linked into this application. A linked executable is just | |
300 | an intermediate file in F<mem.image> generation, so an APPLICATION | |
301 | directive affects only relocation and the scope of labels. All diags | |
302 | have at least one application, even if none is defined, since all | |
303 | diags are treated as if their first line were: | |
304 | ||
305 | APPLICATION default | |
306 | ||
307 | If the optional filename is given, then that file is taken as the | |
308 | linked executable to use. The link path is searched to find a file by | |
309 | this name. This is how you can include a linked executable that was | |
310 | not generated by B<midas>. | |
311 | ||
312 | =head3 goldfinger_cmd blocks | |
313 | ||
314 | There is currently no way to specify address translations and | |
315 | F<mem.image> contents for applications that midas does not generate. | |
316 | As the tool matures, I plan to invent an interface. In the meantime, | |
317 | you can include a goldfinger_cmd block. Such a block begins a line | |
318 | with "goldfinger_cmd" and an open curly-brace. It ends with the | |
319 | closed-curly. The contents of the block are not interpreted B<midas> | |
320 | at all. They are simply copied into F<diag.goldfinger> inside the | |
321 | currently open application. | |
322 | ||
323 | An example: | |
324 | ||
325 | goldfinger_cmd { | |
326 | BLOCK .main_text_0 | |
327 | SECTION_NAME = ".MAIN"; | |
328 | SEGMENT_NAME = "text"; | |
329 | LINK_SECTION = "sec7.maint"; | |
330 | SRC_FILE = "diag.m4"; | |
331 | SRC_LINE = 5398; | |
332 | COMPRESS = 0; | |
333 | VA = 0x0000000020000000; | |
334 | RA = 0x0130000000; | |
335 | PA = 0x1130000000; | |
336 | IN_IMAGE = 1; | |
337 | BLOCK_TSB part_0_i_ctx_nonzero_ps0_tsb | |
338 | page_size = 8192; | |
339 | va_index_bits = 21 : 13; | |
340 | tag_addr_bits = 63 : 13; | |
341 | data_addr_bits = 39 : 13; | |
342 | tag_base = 0x0000000000000044; | |
343 | data_base = 0x8000000000000440; | |
344 | END BLOCK_TSB | |
345 | END BLOCK | |
346 | } | |
347 | ||
348 | Note that until the tool matures, the B<midas>-B<goldfinger> interface | |
349 | may change, so this syntax is deprecated, but it can be useful in a | |
350 | pinch. | |
351 | ||
352 | ||
353 | =head2 SECTION Definitions | |
354 | ||
355 | A SECTION defines a region of the diag that may contain up to 3 | |
356 | segments: text, data, and bss. Each of these segments is contiguous | |
357 | in the virtual address space (but not necessarily in the real or | |
358 | physical address spaces). Note that the B<midas> terminology is | |
359 | different from the B<ELF> terminology. Each segment in B<midas> | |
360 | terminology corresponds to an B<ELF> section. | |
361 | ||
362 | SECTION <name> [section_args] | |
363 | ||
364 | When a section directive is encountered, all assembly code (and data) | |
365 | that follows is placed in that section, until the next SECTION | |
366 | directive is encountered. | |
367 | ||
368 | The C<SECTION> header affects the text and data segments that follow | |
369 | it, until another C<SECTION> header is reached. As a special case, | |
370 | all code and data in the assembly file before the first C<SECTION> | |
371 | header belongs to the first section. A SECTION line may be split | |
372 | across multiple lines of input by escaping the newline with a \. | |
373 | ||
374 | The section_args should define the virtual addresses at which to link | |
375 | the various segments. This is done by a comma-separated list such as: | |
376 | ||
377 | SECTION .MAIN TEXT_VA=0x20000000, DATA_VA=0x60000000, \ | |
378 | BSS_VA=0x68030000 | |
379 | ||
380 | Any of the virtual addresses may be ommitted, but if they are, that | |
381 | segment will not be included in the link. The *_VA symbols are all | |
382 | case-insensitive. The addresses themselves are assumed to be 64-bit | |
383 | decimal numbers, unless they start with 0x (in which case they are | |
384 | 64-bit hex numbers). | |
385 | ||
386 | See the section on L<"ADDRESS TRANSLATIONS"> for details on how | |
387 | address translations can be specified for the segments in a section. | |
388 | Note that unless address translations are specified, there is no | |
389 | physical address to place segments in the F<mem.image> file! | |
390 | ||
391 | =head2 TSB OBJECT DEFINITIONS | |
392 | ||
393 | A TSB object is decared with the following syntax: | |
394 | ||
395 | MIDAS_TSB <name> <register> [args] | |
396 | ||
397 | This defines a TSB with the specified name, which is initialized by | |
398 | the config register E<lt>registerE<gt>. It will be instantiated in | |
399 | the memory image if any attr block tries to use it. All MMU types get | |
400 | a base address and TSB size from the config register as defined in | |
401 | their PRM. Niagara-2, in addition, parses a page size (same meaning | |
402 | as the page_size optional argument below) and sun4u/sun4v, which will | |
403 | be used instead of the global default for ttefmt. Note that if you | |
404 | provide the optional arguments page_size and/or ttefmt for Niagara-2, | |
405 | the optional arguments will override the config register. | |
406 | ||
407 | The optional args can be: | |
408 | ||
409 | =over 4 | |
410 | ||
411 | =item link=E<lt>nameE<gt> | |
412 | ||
413 | Use the specified name as a link area. This is used in the case of | |
414 | TSB collisions to hold a linked list. There must be MIDAS_TSB_LINK | |
415 | declaration by this name. | |
416 | ||
417 | =item force_ctx_zero | |
418 | ||
419 | If this is specified, then any entries added to this TSB will have | |
420 | context bits of zero, regardless of how they are specified in the attr blocks. | |
421 | ||
422 | =item page_size=E<lt>codedSizeE<gt> | |
423 | ||
424 | This defines a default page size for all entries that are added to the | |
425 | TSB. This will be used if no TTE_Size_Ptr values are given for the | |
426 | entries. The coded size is the same encoding used in the TTE_Size | |
427 | field. | |
428 | ||
429 | =item way=E<lt>wayE<gt> | |
430 | ||
431 | If a TSB is split (which only applies to the "ultra2" and "niagara" | |
432 | MMU types), this is specified to midas by creating two TSBs that have | |
433 | the same value of the config register with the split bit set. Midas | |
434 | treats each half of the TSB separately. This makes it easy for diags | |
435 | to control which half of the split TSB gets each translation. The way | |
436 | definition on the TSB line tells midas which half of the split TSB | |
437 | applies to this definition. The only legal settings are "way=0" and | |
438 | "way=1". If way is set to zero, the TSB is configured just as if it | |
439 | were not split. If way is set to one, then the base address is | |
440 | modifed internally so that it starts after the way=0 TSB would end. | |
441 | The way setting is ignored if the TSB is not split or if the MMU type | |
442 | does not support split TSBs. It is the responsibility of the diag | |
443 | writer to make sure that the two halves of a split TSB are configured | |
444 | in a compatible fashion (both sides having split bit on and the same | |
445 | base address). | |
446 | ||
447 | =item ttefmt=E<lt>formatE<gt> | |
448 | ||
449 | Sets the format for this TSB to the specified format (either sun4u or | |
450 | sun4v). This setting will be used instead of the default value of | |
451 | -ttefmt. | |
452 | ||
453 | =back | |
454 | ||
455 | =head2 TSB_LINK OBJECT DEFINITIONS | |
456 | ||
457 | A TSB_LINK object is an area used to store linked lists in the case of | |
458 | collisions in the TSB. Multiple TSBs can share a TSB_LINK. The | |
459 | syntax is: | |
460 | ||
461 | MIDAS_TSB_LINK <name> <pa> | |
462 | ||
463 | This declares a TSB_LINK object that will start at the specified PA. | |
464 | It will be instantiated in the memory image if any TSB that uses it is | |
465 | instantiated. | |
466 | ||
467 | ||
468 | =head2 ADDRESS TRANSLATIONS | |
469 | ||
470 | Address translations are created by attr_ blocks. The name of the | |
471 | block defines the segment on which the block operates. They syntax is: | |
472 | ||
473 | attr_<segment_name> { | |
474 | name|section=<name>, | |
475 | <key>=<val>, <key>=<val>, | |
476 | <key>=<val> | |
477 | ... | |
478 | } | |
479 | ||
480 | The E<lt>segment_nameE<gt> may be "text", "data", or "bss". Each attr | |
481 | block must specify which SECTION they belong to. They do this by | |
482 | setting name= or section= inside the block. This means the attr block | |
483 | itself may appear anywhere in the diag, not necessarily lexically | |
484 | inside the section. The blocks are matched to the sections by name, | |
485 | which is case-insensitive. | |
486 | ||
487 | The contents of the block are a list of key=value pairs (name|section= | |
488 | just being a special case). These pairs can be separated by commas | |
489 | and/or newlines. Key names are case-insensitive. A TSB name may | |
490 | appear as a key with no value. If any other key appears with no | |
491 | =value, the value is assumed to be 1. | |
492 | ||
493 | An example of an attr block is: | |
494 | ||
495 | attr_text { | |
496 | Name = .TRAPS, | |
497 | RA = 0x120000, | |
498 | PA = 0x1000120000, | |
499 | part_0_i_ctx_zero_ps0_tsb, | |
500 | TTE_Context=0, TTE_V=1, TTE_Size=0, | |
501 | TTE_NFO=0, TTE_IE=0, TTE_Soft2=0, TTE_Diag=0, | |
502 | TTE_Soft=0, TTE_L=0, TTE_CP=1, TTE_CV=0, | |
503 | TTE_E=0, TTE_P=1, TTE_W=1 | |
504 | } | |
505 | ||
506 | An attr block has two purposes: setting up TSB mappings and writing to | |
507 | F<mem.image>. It therefore needs to contain enough information to: | |
508 | ||
509 | =over 4 | |
510 | ||
511 | =item Select a subset of the segment | |
512 | ||
513 | An attr block need not define the same translation for an entire | |
514 | segment, and it may define a subset of the segment on which to | |
515 | operated. | |
516 | ||
517 | =item Physical address | |
518 | ||
519 | This defines where to write the segment (or segment subset) in the | |
520 | F<mem.image>. | |
521 | ||
522 | =item Define TSB parameters | |
523 | ||
524 | These include a list of TSBs that should contain translations for this | |
525 | section, an RA (real address) that should be included in the TSB, and | |
526 | TTE elements. The exact details may be processor-specific. It is | |
527 | controlled by the mmu type. Note that for MMUs that do not have | |
528 | two-level address translation (i.e., "ultra2"), there is no RA, so PA | |
529 | is used for TSBs instead. | |
530 | ||
531 | ||
532 | =back | |
533 | ||
534 | =head3 Selecting a subset | |
535 | ||
536 | Selecting a subset consits of defining a starting and stopping virtual | |
537 | address for the block. | |
538 | ||
539 | =head4 Defining the starting virtual address | |
540 | ||
541 | =over 4 | |
542 | ||
543 | =item start_label | |
544 | ||
545 | If the key C<start_label> exists it must be a label inside the | |
546 | segment. It is used as the beginning of the attr block. It must be a | |
547 | page-aligned address unless the block is not being entered into a TSB. | |
548 | ||
549 | =item VA | |
550 | ||
551 | The attr block may explicitly define a starting virtual address using | |
552 | the tag C<VA>. It is an error if this virtual address is not a | |
553 | page-aligned address within the segment (if the block is not writing a | |
554 | TSB entry the alignment contraint is relaxed). For this reason, the | |
555 | start_label syntax is the preferred one for most diags. | |
556 | ||
557 | =item I<default> | |
558 | ||
559 | If neither VA nor start_label are specified for an attr block, the | |
560 | starting VA for the segment is used. | |
561 | ||
562 | =back | |
563 | ||
564 | =head4 Defining the ending virtual address | |
565 | ||
566 | There are three ways to define the ending address for an attr block. | |
567 | ||
568 | =over 4 | |
569 | ||
570 | =item end_label | |
571 | ||
572 | If C<end_label> is defined, it must be label inside the segment (and | |
573 | of course, it must appear after the starting VA). The C<attr_text> | |
574 | definiton ends at the address of the label. The address need not be | |
575 | page-aligned. | |
576 | ||
577 | =item end_va | |
578 | ||
579 | The attr block may explicitly define an ending virtual address. It is | |
580 | an error if this address is not part of this segment. If the special | |
581 | attribute C<uninitialized> is used (see below), then end_va may be | |
582 | specified past the end of the segment. The C<uninitialized> attribute | |
583 | implies C<tsbonly> (i.e., data is written to the TSB but not to the | |
584 | memory image). | |
585 | ||
586 | =item I<default> | |
587 | ||
588 | If neither end_label nor end_va are specified, then the attr block | |
589 | lasts until the end of the section. | |
590 | ||
591 | =back | |
592 | ||
593 | =head3 Physical address | |
594 | ||
595 | An attr block must have one of the following keys to define the | |
596 | physical address. The physical address is used to write F<mem.image> | |
597 | ||
598 | =over 4 | |
599 | ||
600 | =item PA | |
601 | ||
602 | The physical address is specified with the tag "PA". It should be set | |
603 | to an address, and the subset of the segment will be written to the | |
604 | F<mem.image> file at that physical address. It is an error to write | |
605 | to the same physical address twice in the same diag. | |
606 | ||
607 | =item tsbonly | |
608 | ||
609 | This special key tells the attr block not to write anything to | |
610 | F<mem.image>. It can be used if you want to create TSB entries but do | |
611 | not want to overwrite something to F<mem.image>. If the key "PA" is | |
612 | included, it is used only for symbol table generation. | |
613 | ||
614 | =item uninitialized | |
615 | ||
616 | This is exactly the same as tsbonly, except that normally the "end_va" | |
617 | key is checked to make sure that it is contained in the segment. | |
618 | Using uninitialized instead of tsbonly suspends that check. | |
619 | ||
620 | =item hypervisor (or bypass on "ultra2" MMU) | |
621 | ||
622 | The special tag "hypervisor" tells the attr block bypass both VA to RA | |
623 | translation and RA to PA tranlation. The segment will be completely | |
624 | unmapped. Therefore, it will not generate any TSB mappings, and it | |
625 | will write to F<mem.image> at PA=VA (actually, it generates a PA from | |
626 | as many low bits of the VA as will fit in a PA). It is used for | |
627 | segments where the MMU is off. For mmus that have only one level of | |
628 | address translation (i.e., "ultra2"), the key "hypervisor" does not | |
629 | exist, but "bypass" has the same meaning. | |
630 | ||
631 | =item compressimage | |
632 | ||
633 | This does not control the address, but it does affect how F<mem.image> | |
634 | creation is done. If compressimage is given in an attr block then | |
635 | lines of zeros are suppressed in F<mem.image> generation. Each | |
636 | aligned 32-byte chunk is compared against 0. If all bits are 0, then | |
637 | it is not written to mem.image. If the global -env_zero switch is | |
638 | enabled (on by default in Niagara-1), then a backdoor mechanism is | |
639 | used to initialize the memory to zero in the environment. Otherwise, | |
640 | it is left uninitialized. If the environment does not intialize all | |
641 | memory to zero, then this can actually change the meaning of | |
642 | mem.image, since it makes zero-ed memory uninitialized, rather than | |
643 | intialized to zero. If the flag -nocompress_image is given to | |
644 | B<midas>, then no blocks are compressed, regardless of compressimage | |
645 | tags. | |
646 | ||
647 | =head3 TSB parameters | |
648 | ||
649 | The following parameters should be set in each attr block (unless it | |
650 | contains the "hypervisor" key described above, or the "bypass" key for | |
651 | "ultra2"): | |
652 | ||
653 | =over 4 | |
654 | ||
655 | =item RA | |
656 | ||
657 | This defines the real address (middle of the 3-address scheme). It is | |
658 | the address to be written to the TSB data. It must be page-aligned. | |
659 | In the "ultra2" MMU, there is no RA, so the PA gets double-duty: PA is | |
660 | used both for mem.image generation and for TSB data. | |
661 | ||
662 | =item bypass | |
663 | ||
664 | This directive means to bypass VA to RA translation. In an MMU with | |
665 | two levels of address translation (like niagara), it simply sets RA=VA | |
666 | (actually, as many low bits of VA as will fit). It is an error to | |
667 | specify both RA and bypass. In an MMU with one level of translation | |
668 | ("ultra2"), it means to bypass all address translation, so its | |
669 | function is similar to the hypervisor directive described above. | |
670 | ||
671 | =item E<lt>tsb_nameE<gt> | |
672 | ||
673 | Any tsb names that are listed (and there may be more than one) will | |
674 | cause the attr block to add the subset to those TSBs. The tsb_names | |
675 | must be defined somewhere in the diag with a MIDAS_TSB directive. | |
676 | ||
677 | =item notsb | |
678 | ||
679 | Tells the attr block not to do any TSB generation. If RA is provided, | |
680 | it is simply used in the symbol table. | |
681 | ||
682 | =back | |
683 | ||
684 | Unless notsb is defined or the section is completely unmapped (bypass | |
685 | for "ultra2" or hypervisor for other MMUs), the attr block will be | |
686 | writing TSB entries. The following parameters are used to set the | |
687 | appropriate bits of the TSB entry. How exactly the TSB entries are | |
688 | formed is mmu-specific. Check the PRM for your processor. The | |
689 | default value for TTE_V (valid) is 1. The default value for all other | |
690 | fields is 0. | |
691 | ||
692 | =head3 MMU-Specific TTE Settings | |
693 | ||
694 | The fields in the TSB tag and data depend on the MMU type and the | |
695 | currently configured ttefmt setting (sun4u or sun4v). The ttefmt is | |
696 | can be contralled by the TSBs (which is always the case in Niagara-2) | |
697 | or by the global default set by -ttefmt. The MMU specific settings | |
698 | are described below. The default for each TTE setting is 0, except | |
699 | for TTE_V (valid), which defaults to 1. All TTE tags are | |
700 | case-insensitive. | |
701 | ||
702 | =head4 Ultrasparc II MMU "ultra2" | |
703 | ||
704 | The ultra2 MMU type supports only the sun4u TTE data format. | |
705 | ||
706 | =over 4 | |
707 | ||
708 | =item TTE_G Tag: 1 bit Global | |
709 | ||
710 | =item TTE_Context Tag:13 bits Context | |
711 | ||
712 | %%TTE DATA ultra2 sun4u | |
713 | ||
714 | =back | |
715 | ||
716 | =head4 Niagara MMU "niagara" | |
717 | ||
718 | The niagara MMU supports both the sun4u and sun4v TTE data formats. | |
719 | ||
720 | For sun4u, the following fields are valid: | |
721 | ||
722 | =over 4 | |
723 | ||
724 | =item TTE_Context Tag:13 bits Context | |
725 | ||
726 | %%TTE DATA niagara sun4u | |
727 | ||
728 | =back | |
729 | ||
730 | The following fields are valid for sun4v: | |
731 | ||
732 | =over 4 | |
733 | ||
734 | =item TTE_Context Tag:13 bits Context | |
735 | ||
736 | %%TTE DATA niagara sun4v | |
737 | ||
738 | =back | |
739 | ||
740 | =head4 Niagara2 MMU "niagara2" | |
741 | ||
742 | The niagara2 MMU supports both the sun4u and sun4v TTE data format. | |
743 | ||
744 | For sun4u, the following fields are valid: | |
745 | ||
746 | =over 4 | |
747 | ||
748 | =item TTE_Context Tag:13 bits Context | |
749 | ||
750 | %%TTE DATA niagara2 sun4u | |
751 | ||
752 | =back | |
753 | ||
754 | The following fields are valid for sun4v: | |
755 | ||
756 | =over 4 | |
757 | ||
758 | =item TTE_Context Tag:13 bits Context | |
759 | ||
760 | %%TTE DATA niagara2 sun4v | |
761 | ||
762 | =back | |
763 | ||
764 | # =head4 X MMU "X" | |
765 | ||
766 | # The X MMU supports only the sun4v data format. | |
767 | ||
768 | # =over 4 | |
769 | ||
770 | # =item TTE_Context Tag:13 bits Context | |
771 | ||
772 | # %%TTE DATA X sun4v | |
773 | ||
774 | # =back | |
775 | ||
776 | There are a few special cases to be aware of: | |
777 | ||
778 | =over 4 | |
779 | ||
780 | =item TTE_Size | |
781 | ||
782 | This is the size bits field to use in the TSB entry. It is also used | |
783 | to calculate the number of pages the attr block will create. The attr | |
784 | block will create as many pages as it needs to to span the section. | |
785 | The TTE_Size field controls the size of these pages. See the PRM for | |
786 | the exact coding of page size in TTE_Size. For Niagara, and Niagara-2 | |
787 | the encoding is: | |
788 | ||
789 | =over 4 | |
790 | ||
791 | =item 0 -> 8 kB | |
792 | ||
793 | =item 1 -> 64 kB | |
794 | ||
795 | =item 2 -> 512 kB (illegal on Niagara and Niagara-2) | |
796 | ||
797 | =item 3 -> 4 MB | |
798 | ||
799 | =item 5 -> 256 MB | |
800 | ||
801 | =item 6 -> 2 GB (illegal on Niagara and Niagara-2) | |
802 | ||
803 | =item 7 -> 16 GB (illegal on Niagara and Niagara-2) | |
804 | ||
805 | =back | |
806 | ||
807 | The "ultra2" MMU only has a 2-bit size field, so it supports page | |
808 | sizes 0-3 (which are also 8 kB - 4 MB). | |
809 | ||
810 | Note that when the above sections state that VA, RA, and PA must be | |
811 | page-aligned when adding them to a TSB, this is where the page size | |
812 | comes from. | |
813 | ||
814 | =item TTE_Size_Ptr | |
815 | ||
816 | The page size is used in the formula to calculate a TSB pointer. The | |
817 | page size used for pointer calculation is controlled by a hardware | |
818 | register, but B<midas> needs to set up the TSBs statically. By | |
819 | default, the attr block with use TTE_Size when it computes the TSB | |
820 | index (or the TSB page_size parameter/Niagara-2 TSB config, if one is | |
821 | defined), as well as for the uses above. If you set TTE_Size_Ptr, | |
822 | however, it will use this as the page size setting when computing the | |
823 | TSB index. Use this whenever you wish to have a different setting for | |
824 | TTE_Size than the hardware will have in its config register. | |
825 | ||
826 | =back | |
827 | ||
828 | ||
829 | =head2 High Level Languages | |
830 | ||
831 | The output of compilers of high-level languages may be inserted into midas. | |
832 | ||
833 | =head3 Object files | |
834 | ||
835 | The midas directive: | |
836 | ||
837 | MIDAS_OBJ FILE=<something.o> | |
838 | ||
839 | may be placed inside any section. That object file will be linked | |
840 | with the assembly output for the section and will share its attr | |
841 | blocks. No special interpretation is done on the contents of the | |
842 | object file - the text, data, and bss segments are simply linked in | |
843 | with the output of the assembler for that section. The search path | |
844 | for .o files is controlled by the -L switch. The default path is the | |
845 | starting directory, and E<lt>diag_rootE<gt>/verif/diag. | |
846 | ||
847 | =head3 Library files | |
848 | ||
849 | The midas directive: | |
850 | ||
851 | MIDAS_LIB FILE=<something.a> | |
852 | ||
853 | Works just like a MIDAS_OBJ directive, except that it includes a | |
854 | library in the link. Note that the library must be static (i.e., a .a | |
855 | file, and not a .so file), because there is no runtime linker in the | |
856 | diag environment. Other than the file format, the difference between | |
857 | a library file and an object file, is that an object file will include | |
858 | all text/data/bss from the file, but linking with a library file will | |
859 | cause only those symbols that are actually used to be included. | |
860 | ||
861 | Library files will also search the same link path as object files. | |
862 | ||
863 | =head3 C files | |
864 | ||
865 | Simiar to object files, C language files may be included with the | |
866 | directive: | |
867 | ||
868 | MIDAS_CC FILE=<something.c> [OUTPUT=<something.o>] [ARGS=-O2] | |
869 | ||
870 | The OUTPUT and ARGS tags are optional, but the FILE tag is mandatory. | |
871 | The search path for the C source file is controleld by the -C switch, | |
872 | and the default is the starting directory, then | |
873 | E<lt>diag_rootE<gt>/verif/diag/c. The ARGS tag (which must appear | |
874 | last, since the args last until the end of the line) is arguments to | |
875 | gcc. You must not use the -o or -c switches, since midas will provide | |
876 | its own. If "-S" is supplied to gcc through the ARGS tag, then gcc -S | |
877 | will be used to create an assembly file in the Sectioning phase, which | |
878 | will then be assembled like all the other assembly files in the | |
879 | Assembly phase. If -S is not present, then nothing is done in the | |
880 | Sectioning phase (except for finding the C file and copying it to the | |
881 | build directory). Rather, gcc is used to compile the C file directly | |
882 | to an object file during the assembly phase. The object file, | |
883 | generated either by gcc or by the of assembling of gcc -S, is then | |
884 | linked in with the rest of the section. Once the object file is | |
885 | generated, it is treated just as a MIDAS_OBJ directive. | |
886 | ||
887 | =head4 Stack | |
888 | ||
889 | Compiled C code expects the system to set up a stack for it before it | |
890 | runs. Template files are provided for this purpose. Be sure to use | |
891 | them or have some solution for setting up the stack if you are working | |
892 | with compiled code. | |
893 | ||
894 | =head1 AUTHOR | |
895 | ||
896 | ||
897 | =head1 SEE ALSO | |
898 | ||
899 | B<midas>(1), tre_perldoc Midas, B<pal>(1), B<goldfinger>(1). | |
900 |