1This is a loose collection of notes for people hacking on simulators. 2If this document gets big enough it can be prettied up then. 3 4Contents 5 6- The "common" directory 7- Common Makefile Support 8- TAGS support 9- Generating "configure" files 10- C Language Assumptions 11- "dump" commands under gdb 12 13The "common" directory 14====================== 15 16The common directory contains: 17 18- common documentation files (e.g. run.1, and maybe in time .texi files) 19- common source files (e.g. run.c) 20- common Makefile fragment and configury (e.g. Make-common.in, aclocal.m4). 21 22In addition "common" contains portions of the system call support 23(e.g. callback.c, nltvals.def). 24 25Even though no files are built in this directory, it is still configured 26so support for regenerating nltvals.def is present. 27 28Common Makefile Support 29======================= 30 31A common configuration framework is available for simulators that want 32to use it. The common framework exists to remove a lot of duplication 33in configure.ac and Makefile.in, and it also provides a foundation for 34enhancing the simulators uniformly (e.g. the more they share in common 35the easier a feature added to one is added to all). 36 37The configure.ac of a simulator using the common framework should look like: 38 39--- snip --- 40dnl Process this file with autoconf to produce a configure script. 41sinclude(../common/aclocal.m4) 42AC_PREREQ(2.5)dnl 43AC_INIT(Makefile.in) 44 45SIM_AC_COMMON 46 47... target specific additions ... 48 49SIM_AC_OUTPUT 50--- snip --- 51 52SIM_AC_COMMON: 53 54- invokes the autoconf macros most often used by the simulators 55- defines --enable/--with options usable by all simulators 56- initializes sim_link_files/sim_link_links as the set of symbolic links 57 to set up 58 59SIM_AC_OUTPUT: 60 61- creates the symbolic links defined in sim_link_{files,links} 62- creates config.h 63- creates the Makefile 64 65The Makefile.in of a simulator using the common framework should look like: 66 67--- snip --- 68# Makefile for blah ... 69# Copyright blah ... 70 71## COMMON_PRE_CONFIG_FRAG 72 73# These variables are given default values in COMMON_PRE_CONFIG_FRAG. 74# We override the ones we need to here. 75# Not all of these need to be mentioned, only the necessary ones. 76# In fact it is better to *not* mention ones if the value is the default. 77 78# List of object files, less common parts. 79SIM_OBJS = 80# List of extra dependencies. 81# Generally this consists of simulator specific files included by sim-main.h. 82SIM_EXTRA_DEPS = 83# List of flags to always pass to $(CC). 84SIM_EXTRA_CFLAGS = 85# List of extra libraries to link with. 86SIM_EXTRA_LIBS = 87# List of extra program dependencies. 88SIM_EXTRA_LIBDEPS = 89# List of main object files for `run'. 90SIM_RUN_OBJS = run.o 91# Dependency of `all' to build any extra files. 92SIM_EXTRA_ALL = 93# Dependency of `install' to install any extra files. 94SIM_EXTRA_INSTALL = 95# Dependency of `clean' to clean any extra files. 96SIM_EXTRA_CLEAN = 97 98## COMMON_POST_CONFIG_FRAG 99 100# Rules need to build $(SIM_OBJS), plus whatever else the target wants. 101 102... target specific rules ... 103--- snip --- 104 105COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it 106where to insert the two pieces of common/Make-common.in. 107The resulting Makefile is created by doing autoconf substitions on 108both the target's Makefile.in and Make-common.in, and inserting 109the two pieces of Make-common.in into the target's Makefile.in at 110COMMON_{PRE,POST}_CONFIG_FRAG. 111 112Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets 113could be used instead. However, it's not clear yet whether "::" targets 114are portable enough. 115 116TAGS support 117============ 118 119Many files generate program symbols at compile time. 120Such symbols can't be found with grep nor do they normally appear in 121the TAGS file. To get around this, source files can add the comment 122 123/* TAGS: foo1 foo2 */ 124 125where foo1, foo2 are program symbols. Symbols found in such comments 126are greppable and appear in the TAGS file. 127 128Generating "configure" files 129============================ 130 131For targets using the common framework, "configure" can be generated 132by running `autoconf'. 133 134To regenerate the configure files for all targets using the common framework: 135 136 $ cd devo/sim 137 $ make -f Makefile.in SHELL=/bin/sh autoconf-common 138 139To add a change-log entry to the ChangeLog file for each updated 140directory (WARNING - check the modified new-ChangeLog files before 141renaming): 142 143 $ make -f Makefile.in SHELL=/bin/sh autoconf-changelog 144 $ more */new-ChangeLog 145 $ make -f Makefile.in SHELL=/bin/sh autoconf-install 146 147In a similar vein, both the configure and config.in files can be 148updated using the sequence: 149 150 $ cd devo/sim 151 $ make -f Makefile.in SHELL=/bin/sh autoheader-common 152 $ make -f Makefile.in SHELL=/bin/sh autoheader-changelog 153 $ more */new-ChangeLog 154 $ make -f Makefile.in SHELL=/bin/sh autoheader-install 155 156To add the entries to an alternative ChangeLog file, use: 157 158 $ make ChangeLog=MyChangeLog .... 159 160 161C Language Assumptions 162====================== 163 164The programmer may assume that the simulator is being built using an 165ANSI C compiler that supports a 64 bit data type. Consequently: 166 167 o prototypes can be used 168 169 o If sim-types.h is included, the two 170 types signed64 and unsigned64 are 171 available. 172 173 o The type `unsigned' is valid. 174 175However, the user should be aware of the following: 176 177 o GCC's `<number>LL' is NOT acceptable. 178 Microsoft-C doesn't reconize it. 179 180 o MSC's `<number>i64' is NOT acceptable. 181 GCC doesn't reconize it. 182 183 o GCC's `long long' MSC's `_int64' can 184 NOT be used to define 64 bit integer data 185 types. 186 187 o An empty array (eg int a[0]) is not valid. 188 189When building with GCC it is effectivly a requirement that 190--enable-build-warnings=,-Werror be specified during configuration. 191 192"dump" commands under gdb 193========================= 194 195gdbinit.in contains the following 196 197define dump 198set sim_debug_dump () 199end 200 201Simulators that define the sim_debug_dump function can then have their 202internal state pretty printed from gdb. 203 204FIXME: This can obviously be made more elaborate. As needed it will be. 205 206Rebuilding nltvals.def 207====================== 208 209Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already 210got one to hand): 211 212 $ mkdir /tmp/$$ 213 $ cd /tmp/$$ 214 $ cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite 215 216Configure things for an arbitrary simulator target (I've d10v for 217convenience): 218 219 $ mkdir /tmp/$$/build 220 $ cd /tmp/$$/build 221 $ /tmp/$$/devo/configure --target=d10v-elf 222 223In the sim/common directory rebuild the headers: 224 225 $ cd sim/common 226 $ make headers 227 228To add a new target: 229 230 devo/sim/common/gennltvals.sh 231 232 Add your new processor target (you'll need to grub 233 around to find where your syscall.h lives). 234 235 devo/sim/<processor>/Makefile.in 236 237 Add the definition: 238 239 ``NL_TARGET = -DNL_TARGET_d10v'' 240 241 just before the line COMMON_POST_CONFIG_FRAG. 242 243 devo/sim/<processor>/*.[ch] 244 245 Include targ-vals.h instead of syscall.h. 246 247Tracing 248======= 249 250For ports based on CGEN, tracing instrumentation should largely be for free, 251so we will cover the basic non-CGEN setup here. The assumption is that your 252target is using the common autoconf macros and so the build system already 253includes the sim-trace configure flag. 254 255The full tracing API is covered in sim-trace.h, so this section is an overview. 256 257Before calling any trace function, you should make a call to the trace_prefix() 258function. This is usually done in the main sim_engine_run() loop before 259simulating the next instruction. You should make this call before every 260simulated insn. You can probably copy & paste this: 261 if (TRACE_ANY_P (cpu)) 262 trace_prefix (sd, cpu, NULL_CIA, oldpc, TRACE_LINENUM_P (cpu), NULL, 0, ""); 263 264You will then need to instrument your simulator code with calls to the 265trace_generic() function with the appropriate trace index. Typically, this 266will take a form similar to the above snippet. So to trace instructions, you 267would use something like: 268 if (TRACE_INSN_P (cpu)) 269 trace_generic (sd, cpu, TRACE_INSN_IDX, "NOP;"); 270 271The exact output format is up to you. See the trace index enum in sim-trace.h 272to see the different tracing info available. 273 274To utilize the tracing features at runtime, simply use the --trace-xxx flags. 275 run --trace-insn ./some-program 276 277Profiling 278========= 279 280Similar to the tracing section, this is merely an overview for non-CGEN based 281ports. The full API may be found in sim-profile.h. Its API is also similar 282to the tracing API. 283 284Note that unlike the tracing command line options, in addition to the profile 285flags, you have to use the --verbose option to view the summary report after 286execution. Tracing output is displayed on the fly, but the profile output is 287only summarized. 288 289To profile core accesses (such as data reads/writes and insn fetches), add 290calls to PROFILE_COUNT_CORE() to your read/write functions. So in your data 291fetch function, you'd use something like: 292 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_read); 293Then in your data write function: 294 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_write); 295And in your insn fetcher: 296 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_exec); 297 298To use the PC profiling code, you simply have to tell the system where to find 299your simulator's PC and its size. So in your sim_open() function: 300 STATE_WATCHPOINTS (sd)->pc = address_of_cpu0_pc; 301 STATE_WATCHPOINTS (sd)->sizeof_pc = number_of_bytes_for_pc_storage; 302In a typical 32bit system, the sizeof_pc will be 4 bytes. 303 304To profile branches, in every location where a branch insn is executed, call 305one of the related helpers: 306 PROFILE_BRANCH_TAKEN (cpu); 307 PROFILE_BRANCH_UNTAKEN (cpu); 308If you have stall information, you can utilize the other helpers too. 309 310Environment Simulation 311====================== 312 313The simplest simulator doesn't include environment support -- it merely 314simulates the Instruction Set Architecture (ISA). Once you're ready to move 315on to the next level, call the common macro in your configure.ac: 316SIM_AC_OPTION_ENVIRONMENT 317 318This will support for the user, virtual, and operating environments. See the 319sim-config.h header for a more detailed description of them. The former are 320pretty straight forward as things like exceptions (making system calls) are 321handled in the simulator. Which is to say, an exception does not trigger an 322exception handler in the simulator target -- that is what the operating env 323is about. See the following userspace section for more information. 324 325Userspace System Calls 326====================== 327 328By default, the libgloss userspace is simulated. That means the system call 329numbers and calling convention matches that of libgloss. Simulating other 330userspaces (such as Linux) is pretty straightforward, but let's first focus 331on the basics. The basic API is covered in include/gdb/callback.h. 332 333When an instruction is simulated that invokes the system call method (such as 334forcing a hardware trap or exception), your simulator code should set up the 335CB_SYSCALL data structure before calling the common cb_syscall() function. 336For example: 337static int 338syscall_read_mem (host_callback *cb, struct cb_syscall *sc, 339 unsigned long taddr, char *buf, int bytes) 340{ 341 SIM_DESC sd = (SIM_DESC) sc->p1; 342 SIM_CPU *cpu = (SIM_CPU *) sc->p2; 343 return sim_core_read_buffer (sd, cpu, read_map, buf, taddr, bytes); 344} 345static int 346syscall_write_mem (host_callback *cb, struct cb_syscall *sc, 347 unsigned long taddr, const char *buf, int bytes) 348{ 349 SIM_DESC sd = (SIM_DESC) sc->p1; 350 SIM_CPU *cpu = (SIM_CPU *) sc->p2; 351 return sim_core_write_buffer (sd, cpu, write_map, buf, taddr, bytes); 352} 353void target_sim_syscall (SIM_CPU *cpu) 354{ 355 SIM_DESC sd = CPU_STATE (cpu); 356 host_callback *cb = STATE_CALLBACK (sd); 357 CB_SYSCALL sc; 358 359 CB_SYSCALL_INIT (&sc); 360 361 sc.func = <fetch system call number>; 362 sc.arg1 = <fetch first system call argument>; 363 sc.arg2 = <fetch second system call argument>; 364 sc.arg3 = <fetch third system call argument>; 365 sc.arg4 = <fetch fourth system call argument>; 366 sc.p1 = (PTR) sd; 367 sc.p2 = (PTR) cpu; 368 sc.read_mem = syscall_read_mem; 369 sc.write_mem = syscall_write_mem; 370 371 cb_syscall (cb, &sc); 372 373 <store system call result from sc.result>; 374 <store system call error from sc.errcode>; 375} 376Some targets store the result and error code in different places, while others 377only store the error code when the result is an error. 378 379Keep in mind that the CB_SYS_xxx defines are normalized values with no real 380meaning with respect to the target. They provide a unique map on the host so 381that it can parse things sanely. For libgloss, the common/nltvals.def file 382creates the target's system call numbers to the CB_SYS_xxx values. 383 384To simulate other userspace targets, you really only need to update the maps 385pointers that are part of the callback interface. So create CB_TARGET_DEFS_MAP 386arrays for each set (system calls, errnos, open bits, etc...) and in a place 387you find useful, do something like: 388 389... 390static CB_TARGET_DEFS_MAP cb_linux_syscall_map[] = { 391# define TARGET_LINUX_SYS_open 5 392 { CB_SYS_open, TARGET_LINUX_SYS_open }, 393 ... 394 { -1, -1 }, 395}; 396... 397 host_callback *cb = STATE_CALLBACK (sd); 398 cb->syscall_map = cb_linux_syscall_map; 399 cb->errno_map = cb_linux_errno_map; 400 cb->open_map = cb_linux_open_map; 401 cb->signal_map = cb_linux_signal_map; 402 cb->stat_map = cb_linux_stat_map; 403... 404 405Each of these cb_linux_*_map's are manually declared by the arch target. 406 407The target_sim_syscall() example above will then work unchanged (ignoring the 408system call convention) because all of the callback functions go through these 409mapping arrays. 410 411Events 412====== 413 414Events are scheduled and executed on behalf of either a cpu or hardware devices. 415The API is pretty much the same and can be found in common/sim-events.h and 416common/hw-events.h. 417 418For simulator targets, you really just have to worry about the schedule and 419deschedule functions. 420 421Device Trees 422============ 423 424The device tree model is based on the OpenBoot specification. Since this is 425largely inherited from the psim code, consult the existing psim documentation 426for some in-depth details. 427 http://sourceware.org/psim/manual/ 428 429Hardware Devices 430================ 431 432The simplest simulator doesn't include hardware device support. Once you're 433ready to move on to the next level, call the common macro in your configure.ac: 434SIM_AC_OPTION_HARDWARE(yes,,devone devtwo devthree) 435 436The basic hardware API is documented in common/hw-device.h. 437 438Each device has to have a matching file name with a "dv-" prefix. So there has 439to be a dv-devone.c, dv-devtwo.c, and dv-devthree.c files. Further, each file 440has to have a matching hw_descriptor structure. So the dv-devone.c file has to 441have something like: 442 const struct hw_descriptor dv_devone_descriptor[] = { 443 {"devone", devone_finish,}, 444 {NULL, NULL}, 445 }; 446 447The "devone" string as well as the "devone_finish" function are not hard 448requirements, just common conventions. The structure name is a hard 449requirement. 450 451The devone_finish() callback function is used to instantiate this device by 452parsing the corresponding properties in the device tree. 453 454Hardware devices typically attach address ranges to themselves. Then when 455accesses to those addresses are made, the hardware will have its callback 456invoked. The exact callback could be a normal I/O read/write access, as 457well as a DMA access. This makes it easy to simulate memory mapped registers. 458 459Keep in mind that like a proper device driver, it may be instantiated many 460times over. So any device state it needs to be maintained should be allocated 461during the finish callback and attached to the hardware device via set_hw_data. 462Any hardware functions can access this private data via the hw_data function. 463 464Ports (Interrupts / IRQs) 465========================= 466 467First, a note on terminology. A "port" is an aspect of a hardware device that 468accepts or generates interrupts. So devices with input ports may be the target 469of an interrupt (accept it), and/or they have output ports so that they may be 470the source of an interrupt (generate it). 471 472Each port has a symbolic name and a unique number. These are used to identify 473the port in different contexts. The output port name has no hard relationship 474to the input port name (same for the unique number). The callback that accepts 475the interrupt uses the name/id of its input port, while the generator function 476uses the name/id of its output port. 477 478The device tree is used to connect the output port of a device to the input 479port of another device. There are no limits on the number of inputs connected 480to an output, or outputs to an input, or the devices attached to the ports. 481In other words, the input port and output port could be the same device. 482 483The basics are: 484 - each hardware device declares an array of ports (hw_port_descriptor). 485 any mix of input and output ports is allowed. 486 - when setting up the device, attach the array (set_hw_ports). 487 - if the device accepts interrupts, it will have to attach a port callback 488 function (set_hw_port_event) 489 - connect ports with the device tree 490 - handle incoming interrupts with the callback 491 - generate outgoing interrupts with hw_port_event 492