1 /* Table of supported options, their meanings, and defaults. 2 Copyright 2001, 2003 Brian R. Gaeke. 3 Copyright 2002 Paul Twohey. 4 5 This file is part of VMIPS. 6 7 VMIPS is free software; you can redistribute it and/or modify it 8 under the terms of the GNU General Public License as published by the 9 Free Software Foundation; either version 2 of the License, or (at your 10 option) any later version. 11 12 VMIPS is distributed in the hope that it will be useful, but 13 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 14 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 for more details. 16 17 You should have received a copy of the GNU General Public License along 18 with VMIPS; if not, write to the Free Software Foundation, Inc., 19 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ 20 21 #ifndef _OPTIONTBL_H_ 22 #define _OPTIONTBL_H_ 23 24 /* WARNING! 25 * This file is parsed by a Perl script (doc/makeoptdoc.pl), and 26 * that script is not as smart as the C compiler and preprocessor. 27 * Therefore, the format of this file must be as follows... 28 * <junk> 29 * nametable [] = { // no space btwn nametable and [] 30 * { "option-name", TYPE }, 31 * Comment explaining option, delimited by slash star star and 32 * star star slash 33 * (repeat as necessary) 34 * { NULL, ... } 35 * } 36 * <junk> 37 * defaults_table [] = { // no space 38 * "default", "default", ... 39 * NULL 40 * } 41 * <junk> 42 * Whitespace is ignored. Stuff marked as <junk> is ignored. 43 * In the individual tables, anything after NULL is ignored. 44 */ 45 46 /* This is the official table of options. Each one has a name 47 * (an arbitrary character string) and a type, which 48 * may be FLAG (i.e., Boolean), STR (string), or NUM (number). 49 */ 50 51 static Option nametable[] = { 52 { "haltdumpcpu", FLAG }, 53 /** Controls whether the CPU registers and stack will be dumped 54 on halt. For the output format, please see the description of the 55 @option{dumpcpu} option, below. **/ 56 57 { "haltdumpcp0", FLAG }, 58 /** Controls whether the system control coprocessor (CP0) registers 59 and the contents of the translation lookaside buffer (TLB) will be 60 dumped on halt. For the output format, please see the description 61 of the @option{dumpcp0} option, below. **/ 62 63 { "excpriomsg", FLAG }, 64 /** Controls whether exception prioritizing messages will 65 be printed. These messages attempt to explain which of 66 a number of exceptions caused by the same instruction 67 will be reported. **/ 68 69 { "excmsg", FLAG }, 70 /** Controls whether every exception will cause a message 71 to be printed. The message gives the exception code, a 72 short explanation of the exception code, its priority, 73 the delay slot state of the virtual CPU, and states 74 what type of memory access the exception was caused by, 75 if applicable. Interrupt exceptions are only printed if 76 @option{reportirq} is also set; when they occur, they also have Cause 77 and Status register information printed. TLB misses will have fault 78 address and user/kernel mode information printed. **/ 79 80 { "bootmsg", FLAG }, 81 /** Controls whether boot-time and halt-time messages will be printed. 82 These include ROM image size, self test messages, reset and halt 83 announcements, and possibly other messages. **/ 84 85 { "instdump", FLAG }, 86 /** Controls whether every instruction executed will be disassembled 87 and printed. DEFAULT GOES HERE. The output is in the following format: 88 @example 89 PC=0xbfc00000 [1fc00000] 24000000 li $zero,0 90 @end example 91 The first column contains the PC (program counter), followed by 92 the physical translation of that address in brackets. The third 93 column contains the machine instruction word at that address, 94 followed by the assembly language corresponding to that word. 95 All of the constants except for the assembly language are in 96 hexadecimal. **/ 97 98 { "dumpcpu", FLAG }, 99 /** Controls whether the CPU registers and stack will be dumped after every 100 instruction. DEFAULT GOES HERE. The output is in the following format: 101 @example 102 Reg Dump: [ PC=bfc00180 LastInstr=0000000d HI=00000000 LO=00000000 103 DelayState=NORMAL DelayPC=bfc00308 NextEPC=bfc00308 104 R00=00000000 R01=00000000 R02=00000000 R03=a00c000e R04=0000000a 105 ... 106 R30=00000000 R31=bfc00308 ] 107 Stack: 00000000 00000000 00000000 00000000 a2000008 a2000008 ... 108 @end example 109 110 (Some values have been omitted for brevity.) 111 Here, PC is the program counter, LastInstr is the last instruction 112 executed, HI and LO are the multiplication/division result registers, 113 DelayState and DelayPC are used in delay slot processing, NextEPC 114 is what the Exception PC would be if an exception were to occur, and 115 R00 ... R31 are the CPU general purpose registers. Stack represents 116 the top few words on the stack. All values are in hexadecimal. **/ 117 118 { "dumpcp0", FLAG }, 119 /** Controls whether the system control coprocessor (CP0) 120 registers and the contents of the translation lookaside buffer 121 (TLB) will be dumped after every instruction. DEFAULT GOES HERE. 122 The output is in the following format: 123 @example 124 CP0 Dump Registers: [ R00=00000000 R01=00003200 125 R02=00000000 R03=00000000 R04=001fca10 R05=00000000 126 R06=00000000 R07=00000000 R08=7fb7e0aa R09=00000000 127 R10=00000000 R11=00000000 R12=00485e60 R13=f0002124 128 R14=bfc00308 R15=0000703b ] 129 Dump TLB: [ 130 Entry 00: (00000fc000000000) V=00000 A=3f P=00000 ndvg 131 Entry 01: (00000fc000000000) V=00000 A=3f P=00000 ndvg 132 Entry 02: (00000fc000000000) V=00000 A=3f P=00000 ndvg 133 Entry 03: (00000fc000000000) V=00000 A=3f P=00000 ndvg 134 Entry 04: (00000fc000000000) V=00000 A=3f P=00000 ndvg 135 Entry 05: (00000fc000000000) V=00000 A=3f P=00000 ndvg 136 ... 137 Entry 63: (00000fc000000000) V=00000 A=3f P=00000 ndvg 138 ] 139 @end example 140 Each of the R00 .. R15 are coprocessor zero registers, in 141 hexadecimal. The Entry 00 .. 63 lines are TLB entries. The 64-bit 142 number in parentheses is the hexadecimal raw value of the entry. V 143 is the virtual page number. A is the ASID. P is the physical page 144 number. NDVG are the Non-cacheable, Dirty, Valid, and Global bits, 145 uppercase if on, lowercase if off. **/ 146 147 { "haltibe", FLAG }, 148 /** If @option{haltibe} is set to TRUE, the virtual machine will halt 149 after an instruction fetch causes a bus error (exception 150 code 6, Instruction bus error). This is useful if you 151 are expecting execution to jump to nonexistent addresses in 152 memory, and you want it to stop instead of calling the 153 exception handler. It is important to note that the machine 154 halts after the exception is processed. **/ 155 156 { "haltbreak", FLAG }, 157 /** If @option{haltbreak} is set to TRUE, the virtual machine will halt 158 when a breakpoint exception is encountered (exception 159 code 9). This is equivalent to halting when a @code{break} 160 instruction is encountered. It is important to note that the 161 machine halts after the breakpoint exception is processed. **/ 162 163 { "haltdevice", FLAG }, 164 /** If @option{haltdevice} is set to TRUE, the halt device is mapped into 165 physical memory, otherwise it is not. **/ 166 167 { "instcounts", FLAG }, 168 /** Set @option{instcounts} to TRUE if you want to see instruction 169 counts, a rough estimate of total runtime, and execution 170 speed in instructions per second when the virtual 171 machine halts. DEFAULT GOES HERE. The output is printed 172 at the end of the run, and is in the following format: 173 @example 174 7337 instructions in 0.0581 seconds (126282.271 instructions per second) 175 @end example 176 **/ 177 178 { "romfile", STR }, 179 /** This is the name of the file which will be initially 180 loaded into memory (at the address given in @option{loadaddr}, 181 typically 0xbfc00000) and executed when the virtual 182 machine is reset. **/ 183 184 { "loadaddr", NUM }, 185 /** This is the virtual address where the ROM will be loaded. 186 Note that the MIPS reset exception vector is always 0xbfc00000 187 so unless you're doing something incredibly clever you should 188 plan to have some executable code at that address. Since the 189 caches and TLB are in an indeterminate state at the time of 190 reset, the load address must be in uncacheable memory which 191 is not mapped through the TLB (kernel segment "kseg1"). This 192 effectively constrains the valid range of load addresses to 193 between 0xa0000000 and 0xc0000000. **/ 194 195 { "memsize", NUM }, 196 /** This variable controls the size of the virtual CPU's "physical" 197 memory in bytes. **/ 198 199 { "memdump", FLAG }, 200 /** If @option{memdump} is set, then the virtual machine will dump its RAM 201 into a file, whose name is given by the @option{memdumpfile} option, 202 at the end of the simulation run. **/ 203 204 { "memdumpfile", STR }, 205 /** This is the name of the file to which a RAM dump will be 206 written at the end of the simulation run. **/ 207 208 { "reportirq", FLAG }, 209 /** If @option{reportirq} is set, then any change in the interrupt 210 inputs from a device will be reported on stderr. Also, any 211 Interrupt exception will be reported, if @option{excmsg} is also 212 set. **/ 213 214 { "spimconsole", FLAG }, 215 /** When set, configure the SPIM-compatible console device. 216 This is incompatible with @option{decserial}. **/ 217 218 { "ttydev", STR }, 219 /** This pathname will be used as the device from which reads from the 220 SPIM-compatible console device's Keyboard 1 will take their data, and 221 to which writes to Display 1 will send their data. If the OS supports 222 ttyname(3), that call will be used to guess the default pathname. 223 If the pathname is the single word @samp{off}, then the device will be 224 disconnected. 225 If the pathname is the single word @samp{stdout}, then the device 226 will be connected to standard output, and input will be disabled. **/ 227 228 { "ttydev2", STR }, 229 /** See @option{ttydev} option; this one is just like it, but pertains 230 to Keyboard 2 and Display 2. **/ 231 232 { "debug", FLAG }, 233 /** If debug is set, then the gdb remote serial protocol backend will 234 be enabled in the virtual machine. This will cause the machine to 235 wait for gdb to attach and @samp{continue} before booting the ROM file. 236 If debug is not set, then the machine will boot the ROM file 237 without pausing. **/ 238 239 { "debugport", NUM }, 240 /** If debugport is set to something nonzero, then the gdb remote 241 serial protocol backend will use the specified TCP port. **/ 242 243 { "realtime", FLAG }, 244 /** If @option{realtime} is set, then the clock device will cause simulated 245 time to run at some fraction of real time, determined by the 246 @option{timeratio} option. If realtime is not set, then simulated time 247 will run at the speed given by the @option{clockspeed} option. **/ 248 249 { "timeratio", NUM }, 250 /** If the @option{realtime} option is set, this option gives the 251 number of times slower than real time at which simulated time will 252 run. It has no effect if @option{realtime} is not set. **/ 253 254 { "clockspeed", NUM }, 255 /** If the @option{realtime} option is not set, you should set this 256 option to the average speed in MIPS instructions per second at which 257 your system runs VMIPS. You can get suitable values from turning 258 on the @option{instcounts} option and running some of your favorite 259 programs. If you increase the value of @option{clockspeed}, time will 260 appear to pass more slowly for the simulated machine; if you decrease 261 it, time will pass more quickly. (To be precise, one instruction is 262 assumed to take 1.0e9/@option{clockspeed} nanoseconds.) This option 263 has no effect if @option{realtime} is set. **/ 264 265 { "clockintr", NUM }, 266 /** This option gives the frequency of clock interrupts, in nanoseconds 267 of simulated time, for the clock device. It does not affect the 268 DECstation-compatible realtime clock. **/ 269 270 { "clockdeviceirq", NUM }, 271 /** This option gives the interrupt line to which the clock device is 272 connected. Values must be a number 2-7 corresponding to an interrupt 273 line reserved for use by hardware. **/ 274 275 { "clockdevice", FLAG }, 276 /** If this option is set, then the clock device is enabled. This will 277 allow MIPS programs to take advantage of a high precision clock. **/ 278 279 { "dbemsg", FLAG }, 280 /** If this option is set, then the physical addresses of accesses 281 that cause data bus errors (DBE exceptions) will be printed. **/ 282 283 { "decrtc", FLAG }, 284 /** If this option is set, then the DEC RTC device will be 285 configured. **/ 286 287 { "deccsr", FLAG }, 288 /** If this option is set, then the DEC CSR (Control/Status Register) 289 will be configured. **/ 290 291 { "decstat", FLAG }, 292 /** If this option is set, then the DEC CHKSYN and ERRADR registers 293 will be configured. **/ 294 295 { "decserial", FLAG }, 296 /** If this option is set, then the DEC DZ11 serial device 297 will be configured. This is incompatible with @option{spimconsole}. **/ 298 299 { "tracing", FLAG }, 300 /** If this option is set, VMIPS will keep a trace of the last few 301 instructions executed in memory, and write it out when the machine 302 halts. This incurs a substantial performance penalty. Use the 303 @option{tracesize} option to set the size of the trace you want. **/ 304 305 { "tracesize", NUM }, 306 /** Set this option to the maximum number of instructions to keep in the 307 dynamic instruction trace. This has no effect if @option{tracing} is 308 not set. **/ 309 310 { "bigendian", FLAG }, 311 /** If this option is set, then the emulated MIPS CPU will be in 312 Big-Endian mode. Otherwise, it will be in Little-Endian mode. You 313 must set it to correspond to the type of binaries that your 314 assembler and compiler are configured to produce, which is not 315 necessarily the same as the endianness of the CPU on which you 316 are running VMIPS. (The default may not be meaningful for your 317 setup!) **/ 318 319 { "tracestartpc", NUM }, 320 /** If the tracing option is set, then this is the PC value which will 321 trigger the start of tracing. Otherwise it has no effect. **/ 322 323 { "traceendpc", NUM }, 324 /** If the tracing option is set, then this is the PC value which will 325 trigger the end of tracing. Otherwise it has no effect. **/ 326 327 { "mipstoolprefix", STR }, 328 /** vmipstool uses this option to locate your MIPS-targetted cross 329 compilation tools, if you have them installed. If your MIPS GCC 330 is installed as /opt/mips/bin/mips-elf-gcc, then you should set 331 this option to "/opt/mips/bin/mips-elf-". vmipstool looks for 332 the "gcc", "ld", "objcopy" and "objdump" programs starting with 333 this prefix. This option should be set in your installed 334 system-wide VMIPS configuration file (vmipsrc) by the "configure" 335 script; the compiled-in default is designed to cause an error. **/ 336 337 { "execname", STR }, 338 /** Name of executable to be loaded by automatic kernel loader. This 339 is an experimental, unfinished feature. The option value 340 must be the name of a MIPS ECOFF executable file, or 'none' 341 to disable the option. The executable's headers must specify 342 load addresses in KSEG0 or KSEG1 (0x80000000 through 343 0xbfffffff). **/ 344 345 { "fpu", FLAG }, 346 /** True to enable hooks in the CPU to communicate with a 347 floating-point unit as coprocessor 1. The floating-point unit 348 is not implemented; only the hooks in the CPU are. This is an 349 experimental, unfinished feature. **/ 350 351 { "testdev", FLAG }, 352 /** True to enable a memory-mapped device that is used to test 353 the memory-mapped device interface. The VMIPS test suite turns 354 this device on as necessary; you should not normally need 355 to enable it. **/ 356 357 { NULL, 0 } 358 }; 359 360 /* This is the official default options list. */ 361 static const char *defaults_table[] = { 362 "nohaltdumpcpu", "nohaltdumpcp0", "noexcpriomsg", 363 "noexcmsg", "bootmsg", "noinstdump", "nodumpcpu", "nodumpcp0", 364 "haltibe", "haltbreak", "haltdevice", "romfile=romfile.rom", 365 "loadaddr=0xbfc00000", "noinstcounts", 366 "memsize=0x100000", "nomemdump", "memdumpfile=memdump.bin", 367 "noreportirq", "ttydev=/dev/tty", "ttydev2=off", 368 "nodebug", "debugport=0", "norealtime", "timeratio=1", "clockspeed=250000", 369 "clockintr=200000000", "clockdeviceirq=7", "clockdevice", 370 "nodbemsg", "nodecrtc", "nodeccsr", "nodecstat", "nodecserial", 371 "spimconsole", "notracing", "tracesize=100000", "nobigendian", 372 "tracestartpc=0", "traceendpc=0", 373 "mipstoolprefix=/nonexistent/mips/bin/mipsel-ecoff-", 374 "execname=none", "nofpu", "notestdev", 375 NULL 376 }; 377 378 /* If you add or remove an option, or modify an option's default value, 379 * you should update vmipsrc.in to match. */ 380 381 #endif /* _OPTIONTBL_H_ */ 382