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