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 warnings; | |
7 | ||
8 | use Midas; | |
9 | use Midas::Error; | |
10 | ||
11 | my $status = midas(@ARGV); | |
12 | ||
13 | if($status == M_ARGERR) { | |
14 | ||
15 | my $code = qq{ | |
16 | use Pod::Usage; | |
17 | ||
18 | pod2usage(-exitval => $status, | |
19 | -verbose => 1); | |
20 | ||
21 | }; | |
22 | ||
23 | eval $code; | |
24 | if($@) { | |
25 | print STDERR "Midas having trouble reporting argument error.\n"; | |
26 | exit -1; | |
27 | } | |
28 | } | |
29 | ||
30 | exit($status); | |
31 | ||
32 | ############################################################################## | |
33 | ||
34 | __END__ | |
35 | ||
36 | =head1 NAME | |
37 | ||
38 | midas - assembles diags (Midas Is a Diag ASsembler) | |
39 | ||
40 | =head1 SYNOPSIS | |
41 | ||
42 | midas [options] <diag_name> | |
43 | ||
44 | =head1 DESCRIPTION | |
45 | ||
46 | This program builds assembly diags. It is substantially more involved | |
47 | than simply assembling the diag because it also has to link the diag, | |
48 | program the MMU, and generate several output files. | |
49 | ||
50 | The diag specified on the command line will be built. Pretty much | |
51 | everything else is configurable. | |
52 | ||
53 | =head2 Options | |
54 | ||
55 | The following are the options you need to get started: | |
56 | ||
57 | =over 4 | |
58 | ||
59 | =item -h | |
60 | ||
61 | Display man page. | |
62 | ||
63 | =item -verbose [level] / -noverbose (abbreviated -v / -nov) | |
64 | ||
65 | Sets verbosity level (default=2). -noverbose (or -nov) is a synonym | |
66 | for -verbose 0, which means to generate no output in the absence of | |
67 | errors. The highest level of verbosity currently defined is 3. | |
68 | ||
69 | =item -version | |
70 | ||
71 | Return version information and exit. | |
72 | ||
73 | =item -format | |
74 | ||
75 | Display help on the diag format and exit. | |
76 | ||
77 | =item -config E<lt>fileE<gt> | |
78 | ||
79 | Use this file as the config file instead of the one that is | |
80 | distributed with Midas. | |
81 | ||
82 | =item -project E<lt>projectE<gt> | |
83 | ||
84 | Use this project for project-specific configuration. Default is the | |
85 | environment variable $PROJECT. Legal values are BW and N2. | |
86 | ||
87 | =back | |
88 | ||
89 | =head2 Common Options | |
90 | ||
91 | The following are the commonly-used options: | |
92 | ||
93 | =over 4 | |
94 | ||
95 | =item -diag_root E<lt>pathE<gt> | |
96 | ||
97 | Use the specified path as a base for finding standard include files. | |
98 | Default is $DV_ROOT. | |
99 | ||
100 | =item -build_dir E<lt>pathE<gt> | |
101 | ||
102 | Path (absolute or relative to where command is invoked) to directory | |
103 | where temporary files are generated and the build is done. Default is | |
104 | './build'. | |
105 | ||
106 | =item -dest_dir E<lt>pathE<gt> | |
107 | ||
108 | Path (absolute or relative to where command is invoked) of where to | |
109 | store output files. Default is '.'. | |
110 | ||
111 | =item -find_root E<lt>dirE<gt> | |
112 | ||
113 | Interpret the diag on the command-line as the name of a diag to search | |
114 | for. It does a breadth-first search under the specified directory. | |
115 | The default behavior is not to do any search, but to assume that the | |
116 | specified diag is a full or relative path to the file. | |
117 | ||
118 | =item -find | |
119 | ||
120 | This is a shortcut for "-find_root E<lt>diag_rootE<gt>/verif/diag". | |
121 | ||
122 | =item -mmu E<lt>mmu_typeE<gt> | |
123 | ||
124 | Generate programming for the specified MMU. Recognized options are | |
125 | "ultra2", "niagara", and "niagara2". Default is | |
126 | project-specific: "niagara" for Niagara-1 and "niagara2" for | |
127 | Niagara-2. | |
128 | ||
129 | =item -ttefmt E<lt>tte_formatE<gt> | |
130 | ||
131 | Specifies TTE format for those MMUs that require it. May be "sun4u" | |
132 | or "sun4v". Default is project-specific: "sun4v" for Niagara-1 and | |
133 | Niagara-2. | |
134 | ||
135 | =item -tsbtagfmt E<lt>tsbtagfmtE<gt> | |
136 | ||
137 | Specifies the format of the TSB tag. Legal values are 'tagaccess' and | |
138 | 'tagtarget'. Default is project-specific: 'tagaccess' for Niagara-1 and 'tagtarget' for Niagara-2. | |
139 | ||
140 | =item -force_build or -f | |
141 | ||
142 | Build the diag, even if it looks like we have the same input as before | |
143 | and the same args as before. | |
144 | ||
145 | =item -copy_products / -nocopy_products | |
146 | ||
147 | By default, the product files generated in the build directory are | |
148 | hard-linked to the destination directory. The reason they are | |
149 | hard-linked and not copied is for speed. If the hard link fails, it | |
150 | will fall back to a copy in case the directories are on different | |
151 | physical disks. If -copy_products is given, however, it will always | |
152 | do a copy, not a hard link. Default is project-specific: | |
153 | -nocopy_products for Niagara-1. | |
154 | ||
155 | =item -E | |
156 | ||
157 | Stop after the preprocessing stage. | |
158 | ||
159 | =item -addphdr / -noaddphdr | |
160 | ||
161 | If -addphdr is enabled and the project env variable is N2, Midas will | |
162 | add PHDR commands into the diag.ld_scr ( linker script file ). This | |
163 | option is currently by default disabled. N2 needs this option to optimize | |
164 | the size of the diag.exe file. | |
165 | ||
166 | =item -cleanup / -nocleanup | |
167 | ||
168 | If -cleanup is enabled, then after a successful build, the build | |
169 | directory is erased if and only if the build directory was created by | |
170 | this invocation of midas. Default is project-specific: -cleanup for | |
171 | Niagara-1. | |
172 | ||
173 | =item -force_cleanup / -noforce_cleanup | |
174 | ||
175 | If -cleanup is enabled, but this invocation of midas did not create | |
176 | the build directory, -force_cleanup will remove the build directory | |
177 | anyway. Default is project-specific: -noforce_cleanup for Niagara-1. | |
178 | ||
179 | =item -DE<lt>symbolE<gt> or -DE<lt>symbolE<gt>=E<lt>valueE<gt> | |
180 | ||
181 | Add a define to the preprocessing line. Option may be repeated. | |
182 | ||
183 | =item -stddef / -nostddef | |
184 | ||
185 | Include standard preprocessor definitions on command-line. -nostddef | |
186 | disables these. Default is -stddef, but no standard symbols are | |
187 | currently defined. | |
188 | ||
189 | =item -IE<lt>dirE<gt> | |
190 | ||
191 | Add a directory to the include path used by cpp and m4. Path should | |
192 | be absolute or relative to the directory where midas was invoked. | |
193 | Option may be repeated. | |
194 | ||
195 | =item -stdinc / -nostdinc | |
196 | ||
197 | With -stdinc, the standard include paths are used during preprocessing | |
198 | (both cpp and m4). -nostdinc disables these. Default is -stdinc. | |
199 | The standard include directories are the directory where midas was | |
200 | invoked, the build directory and | |
201 | E<lt>diag_rootE<gt>/verif/diag/assembly/include (keep in mind that | |
202 | E<lt>diag_rootE<gt> defaults to $DV_ROOT). | |
203 | ||
204 | =item -include_build / -noinclude_build | |
205 | ||
206 | This option is only meaningful with -nostdinc. If standard includes | |
207 | are switched off, -include_build will add the build directory back to | |
208 | the include path. Default is -noinclude_build. | |
209 | ||
210 | =item -include_start / -noinclude_start | |
211 | ||
212 | This option is only meaningful with -nostdinc. If standard includes | |
213 | are switched off, -include_start will add the start directory (the | |
214 | directory where midas was invoked) back to the include path. | |
215 | Default is -noinclude_start. | |
216 | ||
217 | =item -LE<lt>dirE<gt> | |
218 | ||
219 | Add a directory to the search path when looking for object files in a | |
220 | MIDAS_OBJ directive. Option may be repeated. | |
221 | ||
222 | =item -CE<lt>dirE<gt> | |
223 | ||
224 | Add a directory to the search path when looking for C source files in | |
225 | a MIDAS_CC directive. Option may be repeated. | |
226 | ||
227 | =item -pal_diag_args E<lt>argsE<gt> | |
228 | ||
229 | If the diag is run through pal, give these arguments to the pal diag. | |
230 | Option may be repeated. Note that these arguements are given to the | |
231 | diag, not pal itself. For instance, "midas -pal_args -abc mydiag.pal | |
232 | -pal_diag_args def -pal_diag_args ghi" will run the pal command-line | |
233 | "pal -abc mydiag.pal def ghi". | |
234 | ||
235 | ||
236 | =item -build_threads E<lt>num_threadsE<gt> | |
237 | ||
238 | When doing work that can be done in parallel (such as assembling a | |
239 | bunch of files), use E<lt>num_threadsE<gt> to do it. Default is | |
240 | project-specific: 3 for Niagara-1. | |
241 | ||
242 | =item -print_errors / -noprint_errors | |
243 | ||
244 | If -noprint_errors is defined, then generation of error messages is | |
245 | turned off. When used with -verbose 0, midas is completly silent. | |
246 | This is probalby only useful for the test harness (which is why the | |
247 | switch is there). | |
248 | ||
249 | =item -copy_products / -nocopy_products | |
250 | ||
251 | If this is set, then copy files from the build directory to the | |
252 | starting directory. With -nocopy_products, the files are hard linked | |
253 | instead. If it tries to create a hard link and fails, it will fall | |
254 | back to a copy. Default is -nocopy_products. | |
255 | ||
256 | =item -compress_image / -nocompress_image | |
257 | ||
258 | If -compress_image is enabled (as it is by default), then allow | |
259 | compressed mem.images to be generated. By default, all MMU-generated | |
260 | blocks are compressed when written to mem.image, meaning that instead | |
261 | of initializing unused sections to zero, they are simply | |
262 | uninitialized. The -nocompress_image is equivalent to explicitly | |
263 | putting a 'compressimage=0' in all attr_text/attr_data blocks. | |
264 | ||
265 | =item -env_zero / -noenv_zero | |
266 | ||
267 | When compressing blocks, if -env_zero is enabled the blocks will | |
268 | contain '// zero_image' directives to the environment. These | |
269 | directives are supported only by Niagara, and they are used to | |
270 | backdoor initialize large tracts of memory to zero. If -noenv_zero is | |
271 | used, then compression will simply leave the data uninitialized. | |
272 | ||
273 | ||
274 | =item -default_radix E<lt>decimal|hexE<gt> | |
275 | ||
276 | Radix to assume for all parameters that do not explicitly start with | |
277 | '0x'. Default is 'decimal'. | |
278 | ||
279 | =item -gen_all_tsbs / -nogen_all_tsbs | |
280 | ||
281 | If -gen_all_tsbs is given, then all TSBs that are defined are written | |
282 | to the memory image. If -nogen_all_tsbs, then generate only the TSBs | |
283 | that are used. Default is project-specific: -nogen_all_tsbs for | |
284 | Niagara-1. | |
285 | ||
286 | =item -allow_tsb_conflicts / -noallow_tsb_conflicts | |
287 | ||
288 | If -allow_tsb_conflicts is enabled, then it is legal to have mutiple | |
289 | virtual address map to the same entry in a TSB. A linked-list will be | |
290 | created to hold all entries. With -noallow_tsb_conflicts (which is | |
291 | the default for N1), collisions in the TSB can only happen with the | |
292 | save VA but different contexts. Default is project-specific. | |
293 | ||
294 | =item -allow_empty_sections / -noallow_empty_sections | |
295 | ||
296 | If TEXT_VA is specified, then at least one attr_text block for the | |
297 | section has to be specified, and the same is true for DATA_VA and | |
298 | attr_data blocks. If -allow_empty_sections is specified, then midas | |
299 | will allow you to specify a TEXT_VA(DATA_VA) for the section, even if | |
300 | the section has no attr_text(attr_data) blocks. Of course, any | |
301 | text(data) in such a section will be ignored. Default is | |
302 | project-specific: -noallow_empty_sections for Niagara-1. | |
303 | ||
304 | =item -allow_duplicate_tags / -noallow_duplicate_tags | |
305 | ||
306 | When adding to a TSB link list, it is an error to add the same tag | |
307 | twice. -allow_duplicate_tags suspends the error check. Default is | |
308 | project-specific: -noallow_duplicate_tags for Niagara-1. | |
309 | ||
310 | =item -allow_illegal_page_sizes / -noallow_illegal_page_sizes | |
311 | ||
312 | If -allow_illegal_page_sizes, then tte_size attributes are not checked | |
313 | for valid values, though they are still checked against the width of | |
314 | the field. For instance, in the Niagara MMU, there are 3 page bits, | |
315 | so values can be specified 0-7. However, the only legal values for | |
316 | Niagara are 0, 1, 3, and 5, and unless -allow_illegal_page_sizes is in | |
317 | effect, setting page bits of 2, 4, 6, or 7 will cause an error. The | |
318 | default is project-specific: -noallow_illegal_page_sizes for | |
319 | Niagara-1. | |
320 | ||
321 | =item -allow_misalgined_tsb_base / -noallow_misaligned_tsb_base | |
322 | ||
323 | If -allow_misaligned_tsb_base is set, then a TSB base address need not | |
324 | be aligned with the TSB size. Real software will never do this, but I | |
325 | want it to be possible in diags. If an unalgined address is specified | |
326 | as the base and -allow_misaligned_tsb_base is specified, then midas | |
327 | will forcibly align the address. Default should be | |
328 | -noallow_misaligned_tsb_base for all projects. | |
329 | ||
330 | ||
331 | =item -errcode E<lt>error_codeE<gt> | |
332 | ||
333 | Prints a one-line description for the midas error code. Then exits | |
334 | with status 0. | |
335 | ||
336 | =back | |
337 | ||
338 | =head2 Configuring Commands | |
339 | ||
340 | midas runs several commands in the course of its operation. Several | |
341 | of these can be configured. The configurable commands are: pal, cpp, | |
342 | m4, gcc, as, and ld. Each configurable command has 3 associated options: | |
343 | ||
344 | =over 4 | |
345 | ||
346 | =item -std_E<lt>commandE<gt>_args / -nostd_E<lt>commandE<gt>_args | |
347 | ||
348 | When -std_E<lt>commandE<gt>_args is enabled, the standard set of | |
349 | arguments for E<lt>commandE<gt> are used. Default is | |
350 | -std_E<lt>commandE<gt>_args | |
351 | ||
352 | =item -E<lt>commandE<gt>_args E<lt>argsE<gt> | |
353 | ||
354 | Add E<lt>argsE<gt> to the argument list for the specified E<lt>commandE<gt>. | |
355 | ||
356 | =item -E<lt>commandE<gt>_cmd E<lt>custom_commandE<gt> | |
357 | ||
358 | Use E<lt>custom_commandE<gt> to run the specifed E<lt>commandE<gt> | |
359 | instead of the standard version. | |
360 | ||
361 | =back | |
362 | ||
363 | =head3 Example | |
364 | ||
365 | For instance, to add -foo to the link line, use my_cpp to preprocess, and | |
366 | not use any standard assembler options, use: | |
367 | ||
368 | midas -ld_args -foo -cpp_cmd my_cpp -nostd_as_args mydiag.s | |
369 | ||
370 | ||
371 | =head2 Configuring Filenames | |
372 | ||
373 | There are several generated files, and they all have default names. | |
374 | You can configure the names of many of the files with the following | |
375 | option. | |
376 | ||
377 | =over 4 | |
378 | ||
379 | =item -file E<lt>tagE<gt>=E<lt>nameE<gt> | |
380 | ||
381 | Cause midas to name the file whose tag is E<lt>tagE<gt> to be named | |
382 | E<lt>nameE<gt> instead of the default. E<lt>nameE<gt> is treated as | |
383 | the name of a file in the build directory. | |
384 | ||
385 | =back | |
386 | ||
387 | The list of valid tags for the -file option are: | |
388 | ||
389 | =over 4 | |
390 | ||
391 | =item src | |
392 | ||
393 | Local version of the original source code for the diag. Default is 'diag.src'. | |
394 | ||
395 | =item s | |
396 | ||
397 | Assembly portion of diag before any preprocessing. Default is 'diag.s'. | |
398 | ||
399 | =item pl | |
400 | ||
401 | Perl portion of the diag. Deafult is 'diag.pl'. | |
402 | ||
403 | =item cpp | |
404 | ||
405 | Output of the C preprocessor. Deafult is 'diag.cpp'. | |
406 | ||
407 | =item m4 | |
408 | ||
409 | Output of the m4 preprocessor. Default is 'diag.m4'. | |
410 | ||
411 | =item ldscr | |
412 | ||
413 | Linker script. Default is 'diag.ls_scr'. | |
414 | ||
415 | =item exe | |
416 | ||
417 | Linked executable. Default is 'diag*.exe' where * is | |
418 | application name. | |
419 | ||
420 | =item image | |
421 | ||
422 | Verilog memory image. Default is 'mem.image'. | |
423 | ||
424 | =item events | |
425 | ||
426 | Events file. Default is 'diag.ev'. | |
427 | ||
428 | =item symtab | |
429 | ||
430 | Symbol table. Default is 'symbol.tbl'. | |
431 | ||
432 | =item goldfinger | |
433 | ||
434 | Specification to goldfinger on how to create memory image. Default is | |
435 | 'diag.goldfinger'. | |
436 | ||
437 | =item directives | |
438 | ||
439 | File to contain midas directives after section splitting. Default is | |
440 | 'diag.midas'. | |
441 | ||
442 | =item cmdfile | |
443 | ||
444 | File to stash the midas command-line. Default is '.midas_args'. | |
445 | ||
446 | =item oldcmdfile | |
447 | ||
448 | File to move old command-line options. Default is '.midas_args.old'. | |
449 | ||
450 | =item oldm4 | |
451 | ||
452 | File to stash m4 output of previous run. Default is '.midas.diag.m4.old'. | |
453 | ||
454 | =back | |
455 | ||
456 | =head2 Running Specific Phases | |
457 | ||
458 | The build process is broken into phases: setup, preprocess, | |
459 | sectioning, assemble, link, postprocess, copydest, cleanup. The | |
460 | default behavior is to run all phases. You can, however, restrict | |
461 | operation to a selected set of phases. | |
462 | ||
463 | =over 4 | |
464 | ||
465 | =item -start_phase E<lt>phase_nameE<gt> | |
466 | ||
467 | Start with the named phase and run all subsequent phase. | |
468 | ||
469 | =item -phase E<lt>phase_nameE<gt> | |
470 | ||
471 | Run the specified phase. If any -phase or -start_phase option exists, | |
472 | then by default all phases are off (except for the ones that -phase | |
473 | and -start_phase switch on). You can have multiple -phase options. | |
474 | ||
475 | =item -E | |
476 | ||
477 | This option (mentioned above, which runs the preprocessor only) is just a | |
478 | shortcut for "-phase setup -phase preprocess"). | |
479 | ||
480 | =back | |
481 | ||
482 | Keep in mind that running selected phases is caveat emptor. There are | |
483 | cases where phases expect data or files from previous phases. You may | |
484 | get lucky, but don't blame me if it doesn't work. | |
485 | ||
486 | =head2 Errors | |
487 | ||
488 | When midas is unable to run correctly it will exit with one of the | |
489 | folllowing error codes. | |
490 | ||
491 | =over 4 | |
492 | ||
493 | ||
494 | =item M_NOERROR (#0): No error. | |
495 | ||
496 | ||
497 | =item M_MISC (#1): Miscellaneous error | |
498 | ||
499 | =item M_CODE (#2): Error in midas code. | |
500 | ||
501 | =item M_DIR (#3): Directory error. | |
502 | ||
503 | =item M_FILE (#4): File error. | |
504 | ||
505 | =item M_CMDFAIL (#5): Command failed. | |
506 | ||
507 | =item M_SECSYNTAX (#6): Error in section syntax. | |
508 | ||
509 | =item M_ATTRSYNTAX (#7): Error in attr syntax. | |
510 | ||
511 | =item M_MISSINGPARAM (#8): Missing parameter. | |
512 | ||
513 | =item M_ILLEGALPARAM (#9): Illegal parameter. | |
514 | ||
515 | =item M_OUTOFRANGE (#10): Out of range. | |
516 | ||
517 | =item M_NOTNUM (#11): Not a number. | |
518 | ||
519 | =item M_VACOLLIDE (#12): VA collision. | |
520 | ||
521 | =item M_PACOLLIDE (#13): PA collision. | |
522 | ||
523 | =item M_DIRECTIVESYNTAX (#14): Directive syntax error. | |
524 | ||
525 | =item M_GENFAIL (#15): File generation failed. | |
526 | ||
527 | =item M_ASMFAIL (#16): Assembler failed. | |
528 | ||
529 | =item M_CCFAIL (#17): C compiler failed. | |
530 | ||
531 | =item M_LINKFAIL (#18): Linker failed. | |
532 | ||
533 | =item M_CPPFAIL (#19): CPP failed. | |
534 | ||
535 | =item M_M4FAIL (#20): M4 preprocessor failed. | |
536 | ||
537 | =item M_BADCONFIG (#21): Bad configuration. | |
538 | ||
539 | =item M_EVENTERR (#22): Event parsing error. | |
540 | ||
541 | =item M_ARGERR (#23): Argument error. | |
542 | ||
543 | =item M_NOSEC (#24): Undefined section. | |
544 | ||
545 | =item M_BADTSB (#25): Bad TSB. | |
546 | ||
547 | =item M_BADALIGN (#26): Bad Alignment. | |
548 | ||
549 | =item M_EMPTYSECTION (#27): Empty section. | |
550 | ||
551 | =item M_TSBSYNTAX (#28): Error in tsb syntax. | |
552 | ||
553 | =item M_APPSYNTAX (#29): Error in app syntax.' | |
554 | ||
555 | =item M_MEMORY (#30): Memory error. | |
556 | ||
557 | =item M_GOLDFINGERPARSE (#31): Goldfinger parse error. | |
558 | ||
559 | =item M_GOLDFINGERARG (#32): Goldfinger arg error. | |
560 | ||
561 | =item M_ELF (#33): ELF error. | |
562 | ||
563 | =item M_BADLABEL (#34): Bad label. | |
564 | ||
565 | =item M_GOLDFINGERMISC (#35): Uncategorized goldfinger error. | |
566 | ||
567 | =item M_GOLDFINGERVERSION (#36): Bad version of goldfinger | |
568 | ||
569 | =item M_DUPLICATETAG (#37): Duplicate tags in TSB | |
570 | ||
571 | =item M_BLOCKSYNTAX (#38): Error defining goldfinger BLOCK | |
572 | ||
573 | ||
574 | =back | |
575 | ||
576 | =head1 AUTHOR | |
577 | ||
578 | ||
579 | =head1 SEE ALSO | |
580 | ||
581 | Midas(3), goldfinger(1). | |
582 |