1 This is a loose collection of notes for people hacking on simulators.
2 If this document gets big enough it can be prettied up then.
6 - The "common" directory
7 - Common Makefile Support
9 - Generating "configure" files
10 - C Language Assumptions
11 - "dump" commands under gdb
13 The "common" directory
14 ======================
16 The common directory contains:
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).
22 In addition "common" contains portions of the system call support
23 (e.g. callback.c, nltvals.def).
25 Even though no files are built in this directory, it is still configured
26 so support for regenerating nltvals.def is present.
28 Common Makefile Support
29 =======================
31 A common configuration framework is available for simulators that want
32 to use it. The common framework exists to remove a lot of duplication
33 in configure.ac and Makefile.in, and it also provides a foundation for
34 enhancing the simulators uniformly (e.g. the more they share in common
35 the easier a feature added to one is added to all).
37 The configure.ac of a simulator using the common framework should look like:
40 dnl Process this file with autoconf to produce a configure script.
41 sinclude(../common/aclocal.m4)
47 ... target specific additions ...
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
61 - creates the symbolic links defined in sim_link_{files,links}
63 - creates the Makefile
65 The Makefile.in of a simulator using the common framework should look like:
68 # Makefile for blah ...
71 ## COMMON_PRE_CONFIG_FRAG
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.
78 # List of object files, less common parts.
80 # List of extra dependencies.
81 # Generally this consists of simulator specific files included by sim-main.h.
83 # List of flags to always pass to $(CC).
85 # List of extra libraries to link with.
87 # List of extra program dependencies.
89 # List of main object files for `run'.
91 # Dependency of `all' to build any extra files.
93 # Dependency of `install' to install any extra files.
95 # Dependency of `clean' to clean any extra files.
98 ## COMMON_POST_CONFIG_FRAG
100 # Rules need to build $(SIM_OBJS), plus whatever else the target wants.
102 ... target specific rules ...
105 COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
106 where to insert the two pieces of common/Make-common.in.
107 The resulting Makefile is created by doing autoconf substitions on
108 both the target's Makefile.in and Make-common.in, and inserting
109 the two pieces of Make-common.in into the target's Makefile.in at
110 COMMON_{PRE,POST}_CONFIG_FRAG.
112 Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
113 could be used instead. However, it's not clear yet whether "::" targets
119 Many files generate program symbols at compile time.
120 Such symbols can't be found with grep nor do they normally appear in
121 the TAGS file. To get around this, source files can add the comment
123 /* TAGS: foo1 foo2 */
125 where foo1, foo2 are program symbols. Symbols found in such comments
126 are greppable and appear in the TAGS file.
128 Generating "configure" files
129 ============================
131 For targets using the common framework, "configure" can be generated
132 by running `autoconf'.
134 To regenerate the configure files for all targets using the common framework:
137 $ make -f Makefile.in SHELL=/bin/sh autoconf-common
139 To add a change-log entry to the ChangeLog file for each updated
140 directory (WARNING - check the modified new-ChangeLog files before
143 $ make -f Makefile.in SHELL=/bin/sh autoconf-changelog
144 $ more */new-ChangeLog
145 $ make -f Makefile.in SHELL=/bin/sh autoconf-install
147 In a similar vein, both the configure and config.in files can be
148 updated using the sequence:
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
156 To add the entries to an alternative ChangeLog file, use:
158 $ make ChangeLog=MyChangeLog ....
161 C Language Assumptions
162 ======================
164 An ISO C11 compiler is required, as is an ISO C standard library.
166 "dump" commands under gdb
167 =========================
169 gdbinit.in contains the following
172 set sim_debug_dump ()
175 Simulators that define the sim_debug_dump function can then have their
176 internal state pretty printed from gdb.
178 FIXME: This can obviously be made more elaborate. As needed it will be.
180 Rebuilding nltvals.def
181 ======================
183 Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
188 $ cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
190 Configure things for an arbitrary simulator target (I've d10v for
193 $ mkdir /tmp/$$/build
195 $ /tmp/$$/devo/configure --target=d10v-elf
197 In the sim/common directory rebuild the headers:
204 devo/sim/common/gennltvals.sh
206 Add your new processor target (you'll need to grub
207 around to find where your syscall.h lives).
209 devo/sim/<processor>/Makefile.in
213 ``NL_TARGET = -DNL_TARGET_d10v''
215 just before the line COMMON_POST_CONFIG_FRAG.
217 devo/sim/<processor>/*.[ch]
219 Include targ-vals.h instead of syscall.h.
224 For ports based on CGEN, tracing instrumentation should largely be for free,
225 so we will cover the basic non-CGEN setup here. The assumption is that your
226 target is using the common autoconf macros and so the build system already
227 includes the sim-trace configure flag.
229 The full tracing API is covered in sim-trace.h, so this section is an overview.
231 Before calling any trace function, you should make a call to the trace_prefix()
232 function. This is usually done in the main sim_engine_run() loop before
233 simulating the next instruction. You should make this call before every
234 simulated insn. You can probably copy & paste this:
235 if (TRACE_ANY_P (cpu))
236 trace_prefix (sd, cpu, NULL_CIA, oldpc, TRACE_LINENUM_P (cpu), NULL, 0, "");
238 You will then need to instrument your simulator code with calls to the
239 trace_generic() function with the appropriate trace index. Typically, this
240 will take a form similar to the above snippet. So to trace instructions, you
241 would use something like:
242 if (TRACE_INSN_P (cpu))
243 trace_generic (sd, cpu, TRACE_INSN_IDX, "NOP;");
245 The exact output format is up to you. See the trace index enum in sim-trace.h
246 to see the different tracing info available.
248 To utilize the tracing features at runtime, simply use the --trace-xxx flags.
249 run --trace-insn ./some-program
254 Similar to the tracing section, this is merely an overview for non-CGEN based
255 ports. The full API may be found in sim-profile.h. Its API is also similar
258 Note that unlike the tracing command line options, in addition to the profile
259 flags, you have to use the --verbose option to view the summary report after
260 execution. Tracing output is displayed on the fly, but the profile output is
263 To profile core accesses (such as data reads/writes and insn fetches), add
264 calls to PROFILE_COUNT_CORE() to your read/write functions. So in your data
265 fetch function, you'd use something like:
266 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_read);
267 Then in your data write function:
268 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_write);
269 And in your insn fetcher:
270 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_exec);
272 To use the PC profiling code, you simply have to tell the system where to find
273 your simulator's PC and its size. So in your sim_open() function:
274 STATE_WATCHPOINTS (sd)->pc = address_of_cpu0_pc;
275 STATE_WATCHPOINTS (sd)->sizeof_pc = number_of_bytes_for_pc_storage;
276 In a typical 32bit system, the sizeof_pc will be 4 bytes.
278 To profile branches, in every location where a branch insn is executed, call
279 one of the related helpers:
280 PROFILE_BRANCH_TAKEN (cpu);
281 PROFILE_BRANCH_UNTAKEN (cpu);
282 If you have stall information, you can utilize the other helpers too.
284 Environment Simulation
285 ======================
287 The simplest simulator doesn't include environment support -- it merely
288 simulates the Instruction Set Architecture (ISA). Once you're ready to move
289 on to the next level, call the common macro in your configure.ac:
290 SIM_AC_OPTION_ENVIRONMENT
292 This will support for the user, virtual, and operating environments. See the
293 sim-config.h header for a more detailed description of them. The former are
294 pretty straight forward as things like exceptions (making system calls) are
295 handled in the simulator. Which is to say, an exception does not trigger an
296 exception handler in the simulator target -- that is what the operating env
297 is about. See the following userspace section for more information.
299 Userspace System Calls
300 ======================
302 By default, the libgloss userspace is simulated. That means the system call
303 numbers and calling convention matches that of libgloss. Simulating other
304 userspaces (such as Linux) is pretty straightforward, but let's first focus
305 on the basics. The basic API is covered in include/gdb/callback.h.
307 When an instruction is simulated that invokes the system call method (such as
308 forcing a hardware trap or exception), your simulator code should set up the
309 CB_SYSCALL data structure before calling the common cb_syscall() function.
312 syscall_read_mem (host_callback *cb, struct cb_syscall *sc,
313 unsigned long taddr, char *buf, int bytes)
315 SIM_DESC sd = (SIM_DESC) sc->p1;
316 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
317 return sim_core_read_buffer (sd, cpu, read_map, buf, taddr, bytes);
320 syscall_write_mem (host_callback *cb, struct cb_syscall *sc,
321 unsigned long taddr, const char *buf, int bytes)
323 SIM_DESC sd = (SIM_DESC) sc->p1;
324 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
325 return sim_core_write_buffer (sd, cpu, write_map, buf, taddr, bytes);
327 void target_sim_syscall (SIM_CPU *cpu)
329 SIM_DESC sd = CPU_STATE (cpu);
330 host_callback *cb = STATE_CALLBACK (sd);
333 CB_SYSCALL_INIT (&sc);
335 sc.func = <fetch system call number>;
336 sc.arg1 = <fetch first system call argument>;
337 sc.arg2 = <fetch second system call argument>;
338 sc.arg3 = <fetch third system call argument>;
339 sc.arg4 = <fetch fourth system call argument>;
342 sc.read_mem = syscall_read_mem;
343 sc.write_mem = syscall_write_mem;
345 cb_syscall (cb, &sc);
347 <store system call result from sc.result>;
348 <store system call error from sc.errcode>;
350 Some targets store the result and error code in different places, while others
351 only store the error code when the result is an error.
353 Keep in mind that the CB_SYS_xxx defines are normalized values with no real
354 meaning with respect to the target. They provide a unique map on the host so
355 that it can parse things sanely. For libgloss, the common/nltvals.def file
356 creates the target's system call numbers to the CB_SYS_xxx values.
358 To simulate other userspace targets, you really only need to update the maps
359 pointers that are part of the callback interface. So create CB_TARGET_DEFS_MAP
360 arrays for each set (system calls, errnos, open bits, etc...) and in a place
361 you find useful, do something like:
364 static CB_TARGET_DEFS_MAP cb_linux_syscall_map[] = {
365 # define TARGET_LINUX_SYS_open 5
366 { CB_SYS_open, TARGET_LINUX_SYS_open },
371 host_callback *cb = STATE_CALLBACK (sd);
372 cb->syscall_map = cb_linux_syscall_map;
373 cb->errno_map = cb_linux_errno_map;
374 cb->open_map = cb_linux_open_map;
375 cb->signal_map = cb_linux_signal_map;
376 cb->stat_map = cb_linux_stat_map;
379 Each of these cb_linux_*_map's are manually declared by the arch target.
381 The target_sim_syscall() example above will then work unchanged (ignoring the
382 system call convention) because all of the callback functions go through these
388 Events are scheduled and executed on behalf of either a cpu or hardware devices.
389 The API is pretty much the same and can be found in common/sim-events.h and
392 For simulator targets, you really just have to worry about the schedule and
393 deschedule functions.
398 The device tree model is based on the OpenBoot specification. Since this is
399 largely inherited from the psim code, consult the existing psim documentation
400 for some in-depth details.
401 http://sourceware.org/psim/manual/
406 The simplest simulator doesn't include hardware device support. Once you're
407 ready to move on to the next level, call the common macro in your configure.ac:
408 SIM_AC_OPTION_HARDWARE(yes,,devone devtwo devthree)
410 The basic hardware API is documented in common/hw-device.h.
412 Each device has to have a matching file name with a "dv-" prefix. So there has
413 to be a dv-devone.c, dv-devtwo.c, and dv-devthree.c files. Further, each file
414 has to have a matching hw_descriptor structure. So the dv-devone.c file has to
416 const struct hw_descriptor dv_devone_descriptor[] = {
417 {"devone", devone_finish,},
421 The "devone" string as well as the "devone_finish" function are not hard
422 requirements, just common conventions. The structure name is a hard
425 The devone_finish() callback function is used to instantiate this device by
426 parsing the corresponding properties in the device tree.
428 Hardware devices typically attach address ranges to themselves. Then when
429 accesses to those addresses are made, the hardware will have its callback
430 invoked. The exact callback could be a normal I/O read/write access, as
431 well as a DMA access. This makes it easy to simulate memory mapped registers.
433 Keep in mind that like a proper device driver, it may be instantiated many
434 times over. So any device state it needs to be maintained should be allocated
435 during the finish callback and attached to the hardware device via set_hw_data.
436 Any hardware functions can access this private data via the hw_data function.
438 Ports (Interrupts / IRQs)
439 =========================
441 First, a note on terminology. A "port" is an aspect of a hardware device that
442 accepts or generates interrupts. So devices with input ports may be the target
443 of an interrupt (accept it), and/or they have output ports so that they may be
444 the source of an interrupt (generate it).
446 Each port has a symbolic name and a unique number. These are used to identify
447 the port in different contexts. The output port name has no hard relationship
448 to the input port name (same for the unique number). The callback that accepts
449 the interrupt uses the name/id of its input port, while the generator function
450 uses the name/id of its output port.
452 The device tree is used to connect the output port of a device to the input
453 port of another device. There are no limits on the number of inputs connected
454 to an output, or outputs to an input, or the devices attached to the ports.
455 In other words, the input port and output port could be the same device.
458 - each hardware device declares an array of ports (hw_port_descriptor).
459 any mix of input and output ports is allowed.
460 - when setting up the device, attach the array (set_hw_ports).
461 - if the device accepts interrupts, it will have to attach a port callback
462 function (set_hw_port_event)
463 - connect ports with the device tree
464 - handle incoming interrupts with the callback
465 - generate outgoing interrupts with hw_port_event