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