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)
46 ... target specific additions ...
53 - invokes the autoconf macros most often used by the simulators
54 - defines --enable/--with options usable by all simulators
55 - initializes sim_link_files/sim_link_links as the set of symbolic links
60 - creates the symbolic links defined in sim_link_{files,links}
62 - creates the Makefile
64 The Makefile.in of a simulator using the common framework should look like:
67 # Makefile for blah ...
70 ## COMMON_PRE_CONFIG_FRAG
72 # These variables are given default values in COMMON_PRE_CONFIG_FRAG.
73 # We override the ones we need to here.
74 # Not all of these need to be mentioned, only the necessary ones.
75 # In fact it is better to *not* mention ones if the value is the default.
77 # List of object files, less common parts.
79 # List of extra dependencies.
80 # Generally this consists of simulator specific files included by sim-main.h.
82 # List of flags to always pass to $(CC).
84 # List of extra libraries to link with.
86 # List of extra program dependencies.
88 # Dependency of `all' to build any extra files.
90 # Dependency of `install' to install any extra files.
92 # Dependency of `clean' to clean any extra files.
95 ## COMMON_POST_CONFIG_FRAG
97 # Rules need to build $(SIM_OBJS), plus whatever else the target wants.
99 ... target specific rules ...
102 COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
103 where to insert the two pieces of common/Make-common.in.
104 The resulting Makefile is created by doing autoconf substitions on
105 both the target's Makefile.in and Make-common.in, and inserting
106 the two pieces of Make-common.in into the target's Makefile.in at
107 COMMON_{PRE,POST}_CONFIG_FRAG.
109 Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
110 could be used instead. However, it's not clear yet whether "::" targets
116 Many files generate program symbols at compile time.
117 Such symbols can't be found with grep nor do they normally appear in
118 the TAGS file. To get around this, source files can add the comment
120 /* TAGS: foo1 foo2 */
122 where foo1, foo2 are program symbols. Symbols found in such comments
123 are greppable and appear in the TAGS file.
125 Generating "configure" files
126 ============================
128 For targets using the common framework, "configure" can be generated
129 by running `autoconf'.
131 To regenerate the configure files for all targets using the common framework:
134 $ make -f Makefile.in SHELL=/bin/sh autoconf-common
136 To add a change-log entry to the ChangeLog file for each updated
137 directory (WARNING - check the modified new-ChangeLog files before
140 $ make -f Makefile.in SHELL=/bin/sh autoconf-changelog
141 $ more */new-ChangeLog
142 $ make -f Makefile.in SHELL=/bin/sh autoconf-install
144 In a similar vein, both the configure and config.in files can be
145 updated using the sequence:
148 $ make -f Makefile.in SHELL=/bin/sh autoheader-common
149 $ make -f Makefile.in SHELL=/bin/sh autoheader-changelog
150 $ more */new-ChangeLog
151 $ make -f Makefile.in SHELL=/bin/sh autoheader-install
153 To add the entries to an alternative ChangeLog file, use:
155 $ make ChangeLog=MyChangeLog ....
158 C Language Assumptions
159 ======================
161 An ISO C11 compiler is required, as is an ISO C standard library.
163 "dump" commands under gdb
164 =========================
166 gdbinit.in contains the following
169 set sim_debug_dump ()
172 Simulators that define the sim_debug_dump function can then have their
173 internal state pretty printed from gdb.
175 FIXME: This can obviously be made more elaborate. As needed it will be.
177 Rebuilding nltvals.def
178 ======================
180 Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
185 $ cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
187 Configure things for an arbitrary simulator target (I've d10v for
190 $ mkdir /tmp/$$/build
192 $ /tmp/$$/devo/configure --target=d10v-elf
194 In the sim/ directory rebuild the headers:
201 devo/sim/common/gennltvals.sh
203 Add your new processor target (you'll need to grub
204 around to find where your syscall.h lives).
206 devo/sim/<processor>/Makefile.in
210 ``NL_TARGET = -DNL_TARGET_d10v''
212 just before the line COMMON_POST_CONFIG_FRAG.
214 devo/sim/<processor>/*.[ch]
216 Include targ-vals.h instead of syscall.h.
221 For ports based on CGEN, tracing instrumentation should largely be for free,
222 so we will cover the basic non-CGEN setup here. The assumption is that your
223 target is using the common autoconf macros and so the build system already
224 includes the sim-trace configure flag.
226 The full tracing API is covered in sim-trace.h, so this section is an overview.
228 Before calling any trace function, you should make a call to the trace_prefix()
229 function. This is usually done in the main sim_engine_run() loop before
230 simulating the next instruction. You should make this call before every
231 simulated insn. You can probably copy & paste this:
232 if (TRACE_ANY_P (cpu))
233 trace_prefix (sd, cpu, NULL_CIA, oldpc, TRACE_LINENUM_P (cpu), NULL, 0, "");
235 You will then need to instrument your simulator code with calls to the
236 trace_generic() function with the appropriate trace index. Typically, this
237 will take a form similar to the above snippet. So to trace instructions, you
238 would use something like:
239 if (TRACE_INSN_P (cpu))
240 trace_generic (sd, cpu, TRACE_INSN_IDX, "NOP;");
242 The exact output format is up to you. See the trace index enum in sim-trace.h
243 to see the different tracing info available.
245 To utilize the tracing features at runtime, simply use the --trace-xxx flags.
246 run --trace-insn ./some-program
251 Similar to the tracing section, this is merely an overview for non-CGEN based
252 ports. The full API may be found in sim-profile.h. Its API is also similar
255 Note that unlike the tracing command line options, in addition to the profile
256 flags, you have to use the --verbose option to view the summary report after
257 execution. Tracing output is displayed on the fly, but the profile output is
260 To profile core accesses (such as data reads/writes and insn fetches), add
261 calls to PROFILE_COUNT_CORE() to your read/write functions. So in your data
262 fetch function, you'd use something like:
263 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_read);
264 Then in your data write function:
265 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_write);
266 And in your insn fetcher:
267 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_exec);
269 To use the PC profiling code, you simply have to tell the system where to find
270 your simulator's PC and its size. So in your sim_open() function:
271 STATE_WATCHPOINTS (sd)->pc = address_of_cpu0_pc;
272 STATE_WATCHPOINTS (sd)->sizeof_pc = number_of_bytes_for_pc_storage;
273 In a typical 32bit system, the sizeof_pc will be 4 bytes.
275 To profile branches, in every location where a branch insn is executed, call
276 one of the related helpers:
277 PROFILE_BRANCH_TAKEN (cpu);
278 PROFILE_BRANCH_UNTAKEN (cpu);
279 If you have stall information, you can utilize the other helpers too.
281 Environment Simulation
282 ======================
284 The simplest simulator doesn't include environment support -- it merely
285 simulates the Instruction Set Architecture (ISA). Once you're ready to move
286 on to the next level, call the common macro in your configure.ac:
287 SIM_AC_OPTION_ENVIRONMENT
289 This will support for the user, virtual, and operating environments. See the
290 sim-config.h header for a more detailed description of them. The former are
291 pretty straight forward as things like exceptions (making system calls) are
292 handled in the simulator. Which is to say, an exception does not trigger an
293 exception handler in the simulator target -- that is what the operating env
294 is about. See the following userspace section for more information.
296 Userspace System Calls
297 ======================
299 By default, the libgloss userspace is simulated. That means the system call
300 numbers and calling convention matches that of libgloss. Simulating other
301 userspaces (such as Linux) is pretty straightforward, but let's first focus
302 on the basics. The basic API is covered in include/gdb/callback.h.
304 When an instruction is simulated that invokes the system call method (such as
305 forcing a hardware trap or exception), your simulator code should set up the
306 CB_SYSCALL data structure before calling the common cb_syscall() function.
309 syscall_read_mem (host_callback *cb, struct cb_syscall *sc,
310 unsigned long taddr, char *buf, int bytes)
312 SIM_DESC sd = (SIM_DESC) sc->p1;
313 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
314 return sim_core_read_buffer (sd, cpu, read_map, buf, taddr, bytes);
317 syscall_write_mem (host_callback *cb, struct cb_syscall *sc,
318 unsigned long taddr, const char *buf, int bytes)
320 SIM_DESC sd = (SIM_DESC) sc->p1;
321 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
322 return sim_core_write_buffer (sd, cpu, write_map, buf, taddr, bytes);
324 void target_sim_syscall (SIM_CPU *cpu)
326 SIM_DESC sd = CPU_STATE (cpu);
327 host_callback *cb = STATE_CALLBACK (sd);
330 CB_SYSCALL_INIT (&sc);
332 sc.func = <fetch system call number>;
333 sc.arg1 = <fetch first system call argument>;
334 sc.arg2 = <fetch second system call argument>;
335 sc.arg3 = <fetch third system call argument>;
336 sc.arg4 = <fetch fourth system call argument>;
339 sc.read_mem = syscall_read_mem;
340 sc.write_mem = syscall_write_mem;
342 cb_syscall (cb, &sc);
344 <store system call result from sc.result>;
345 <store system call error from sc.errcode>;
347 Some targets store the result and error code in different places, while others
348 only store the error code when the result is an error.
350 Keep in mind that the CB_SYS_xxx defines are normalized values with no real
351 meaning with respect to the target. They provide a unique map on the host so
352 that it can parse things sanely. For libgloss, the common/nltvals.def file
353 creates the target's system call numbers to the CB_SYS_xxx values.
355 To simulate other userspace targets, you really only need to update the maps
356 pointers that are part of the callback interface. So create CB_TARGET_DEFS_MAP
357 arrays for each set (system calls, errnos, open bits, etc...) and in a place
358 you find useful, do something like:
361 static CB_TARGET_DEFS_MAP cb_linux_syscall_map[] = {
362 # define TARGET_LINUX_SYS_open 5
363 { CB_SYS_open, TARGET_LINUX_SYS_open },
368 host_callback *cb = STATE_CALLBACK (sd);
369 cb->syscall_map = cb_linux_syscall_map;
370 cb->errno_map = cb_linux_errno_map;
371 cb->open_map = cb_linux_open_map;
372 cb->signal_map = cb_linux_signal_map;
373 cb->stat_map = cb_linux_stat_map;
376 Each of these cb_linux_*_map's are manually declared by the arch target.
378 The target_sim_syscall() example above will then work unchanged (ignoring the
379 system call convention) because all of the callback functions go through these
385 Events are scheduled and executed on behalf of either a cpu or hardware devices.
386 The API is pretty much the same and can be found in common/sim-events.h and
389 For simulator targets, you really just have to worry about the schedule and
390 deschedule functions.
395 The device tree model is based on the OpenBoot specification. Since this is
396 largely inherited from the psim code, consult the existing psim documentation
397 for some in-depth details.
398 http://sourceware.org/psim/manual/
403 The simplest simulator doesn't include hardware device support. Once you're
404 ready to move on to the next level, call the common macro in your configure.ac:
405 SIM_AC_OPTION_HARDWARE(yes,,devone devtwo devthree)
407 The basic hardware API is documented in common/hw-device.h.
409 Each device has to have a matching file name with a "dv-" prefix. So there has
410 to be a dv-devone.c, dv-devtwo.c, and dv-devthree.c files. Further, each file
411 has to have a matching hw_descriptor structure. So the dv-devone.c file has to
413 const struct hw_descriptor dv_devone_descriptor[] = {
414 {"devone", devone_finish,},
418 The "devone" string as well as the "devone_finish" function are not hard
419 requirements, just common conventions. The structure name is a hard
422 The devone_finish() callback function is used to instantiate this device by
423 parsing the corresponding properties in the device tree.
425 Hardware devices typically attach address ranges to themselves. Then when
426 accesses to those addresses are made, the hardware will have its callback
427 invoked. The exact callback could be a normal I/O read/write access, as
428 well as a DMA access. This makes it easy to simulate memory mapped registers.
430 Keep in mind that like a proper device driver, it may be instantiated many
431 times over. So any device state it needs to be maintained should be allocated
432 during the finish callback and attached to the hardware device via set_hw_data.
433 Any hardware functions can access this private data via the hw_data function.
435 Ports (Interrupts / IRQs)
436 =========================
438 First, a note on terminology. A "port" is an aspect of a hardware device that
439 accepts or generates interrupts. So devices with input ports may be the target
440 of an interrupt (accept it), and/or they have output ports so that they may be
441 the source of an interrupt (generate it).
443 Each port has a symbolic name and a unique number. These are used to identify
444 the port in different contexts. The output port name has no hard relationship
445 to the input port name (same for the unique number). The callback that accepts
446 the interrupt uses the name/id of its input port, while the generator function
447 uses the name/id of its output port.
449 The device tree is used to connect the output port of a device to the input
450 port of another device. There are no limits on the number of inputs connected
451 to an output, or outputs to an input, or the devices attached to the ports.
452 In other words, the input port and output port could be the same device.
455 - each hardware device declares an array of ports (hw_port_descriptor).
456 any mix of input and output ports is allowed.
457 - when setting up the device, attach the array (set_hw_ports).
458 - if the device accepts interrupts, it will have to attach a port callback
459 function (set_hw_port_event)
460 - connect ports with the device tree
461 - handle incoming interrupts with the callback
462 - generate outgoing interrupts with hw_port_event