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, target-newlib-*.c).
25 Common Makefile Support
26 =======================
28 A common configuration framework is available for simulators that want
29 to use it. The common framework exists to remove a lot of duplication
30 in configure.ac and Makefile.in, and it also provides a foundation for
31 enhancing the simulators uniformly (e.g. the more they share in common
32 the easier a feature added to one is added to all).
34 The Makefile.in of a simulator using the common framework should look like:
37 # Makefile for blah ...
40 ## COMMON_PRE_CONFIG_FRAG
42 # These variables are given default values in COMMON_PRE_CONFIG_FRAG.
43 # We override the ones we need to here.
44 # Not all of these need to be mentioned, only the necessary ones.
45 # In fact it is better to *not* mention ones if the value is the default.
47 # List of object files, less common parts.
49 # List of extra dependencies.
50 # Generally this consists of simulator specific files included by sim-main.h.
52 # List of flags to always pass to $(CC).
54 # Dependency of `clean' to clean any extra files.
57 ## COMMON_POST_CONFIG_FRAG
59 # Rules need to build $(SIM_OBJS), plus whatever else the target wants.
61 ... target specific rules ...
64 COMMON_{PRE,POST}_CONFIG_FRAG are markers for configure to tell it
65 where to insert the two pieces of common/Make-common.in.
66 The resulting Makefile is created by doing autoconf substitions on
67 both the target's Makefile.in and Make-common.in, and inserting
68 the two pieces of Make-common.in into the target's Makefile.in at
69 COMMON_{PRE,POST}_CONFIG_FRAG.
71 Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
72 could be used instead. However, it's not clear yet whether "::" targets
78 Many files generate program symbols at compile time.
79 Such symbols can't be found with grep nor do they normally appear in
80 the TAGS file. To get around this, source files can add the comment
84 where foo1, foo2 are program symbols. Symbols found in such comments
85 are greppable and appear in the TAGS file.
87 Generating "configure" files
88 ============================
90 "configure" can be generated by running `autoreconf'.
92 C Language Assumptions
93 ======================
95 An ISO C11 compiler is required, as is an ISO C standard library.
97 "dump" commands under gdb
98 =========================
100 gdbinit.in contains the following
103 set sim_debug_dump ()
106 Simulators that define the sim_debug_dump function can then have their
107 internal state pretty printed from gdb.
109 FIXME: This can obviously be made more elaborate. As needed it will be.
111 Rebuilding target-newlib-* files
112 ================================
114 Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
119 $ cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
121 Configure things for an arbitrary simulator target (d10v is used here for
124 $ mkdir /tmp/$$/build
126 $ /tmp/$$/devo/configure --target=d10v-elf
128 In the sim/ directory rebuild the headers:
133 If the target uses the common syscall table (libgloss/syscall.h), then you're
134 all set! If the target has a custom syscall table, you need to declare it:
136 devo/sim/common/gennltvals.py
138 Add your new processor target (you'll need to grub
139 around to find where your syscall.h lives).
141 devo/sim/<processor>/*.[ch]
143 Include target-newlib-syscall.h instead of syscall.h.
148 For ports based on CGEN, tracing instrumentation should largely be for free,
149 so we will cover the basic non-CGEN setup here. The assumption is that your
150 target is using the common autoconf macros and so the build system already
151 includes the sim-trace configure flag.
153 The full tracing API is covered in sim-trace.h, so this section is an overview.
155 Before calling any trace function, you should make a call to the trace_prefix()
156 function. This is usually done in the main sim_engine_run() loop before
157 simulating the next instruction. You should make this call before every
158 simulated insn. You can probably copy & paste this:
159 if (TRACE_ANY_P (cpu))
160 trace_prefix (sd, cpu, NULL_CIA, oldpc, TRACE_LINENUM_P (cpu), NULL, 0, "");
162 You will then need to instrument your simulator code with calls to the
163 trace_generic() function with the appropriate trace index. Typically, this
164 will take a form similar to the above snippet. So to trace instructions, you
165 would use something like:
166 if (TRACE_INSN_P (cpu))
167 trace_generic (sd, cpu, TRACE_INSN_IDX, "NOP;");
169 The exact output format is up to you. See the trace index enum in sim-trace.h
170 to see the different tracing info available.
172 To utilize the tracing features at runtime, simply use the --trace-xxx flags.
173 run --trace-insn ./some-program
178 Similar to the tracing section, this is merely an overview for non-CGEN based
179 ports. The full API may be found in sim-profile.h. Its API is also similar
182 Note that unlike the tracing command line options, in addition to the profile
183 flags, you have to use the --verbose option to view the summary report after
184 execution. Tracing output is displayed on the fly, but the profile output is
187 To profile core accesses (such as data reads/writes and insn fetches), add
188 calls to PROFILE_COUNT_CORE() to your read/write functions. So in your data
189 fetch function, you'd use something like:
190 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_read);
191 Then in your data write function:
192 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_write);
193 And in your insn fetcher:
194 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_exec);
196 To use the PC profiling code, you simply have to tell the system where to find
197 your simulator's PC. So in your model initialization function:
198 CPU_PC_FETCH (cpu) = function_that_fetches_the_pc;
200 To profile branches, in every location where a branch insn is executed, call
201 one of the related helpers:
202 PROFILE_BRANCH_TAKEN (cpu);
203 PROFILE_BRANCH_UNTAKEN (cpu);
204 If you have stall information, you can utilize the other helpers too.
206 Environment Simulation
207 ======================
209 The simplest simulator doesn't include environment support -- it merely
210 simulates the Instruction Set Architecture (ISA). Once you're ready to move
211 on to the next level, it's time to start handling the --env option. It's
212 enabled by default for all ports already.
214 This will support for the user, virtual, and operating environments. See the
215 sim-config.h header for a more detailed description of them. The former are
216 pretty straight forward as things like exceptions (making system calls) are
217 handled in the simulator. Which is to say, an exception does not trigger an
218 exception handler in the simulator target -- that is what the operating env
219 is about. See the following userspace section for more information.
221 Userspace System Calls
222 ======================
224 By default, the libgloss userspace is simulated. That means the system call
225 numbers and calling convention matches that of libgloss. Simulating other
226 userspaces (such as Linux) is pretty straightforward, but let's first focus
227 on the basics. The basic API is covered in include/sim/callback.h.
229 When an instruction is simulated that invokes the system call method (such as
230 forcing a hardware trap or exception), your simulator code should set up the
231 CB_SYSCALL data structure before calling the common cb_syscall() function.
234 syscall_read_mem (host_callback *cb, struct cb_syscall *sc,
235 unsigned long taddr, char *buf, int bytes)
237 SIM_DESC sd = (SIM_DESC) sc->p1;
238 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
239 return sim_core_read_buffer (sd, cpu, read_map, buf, taddr, bytes);
242 syscall_write_mem (host_callback *cb, struct cb_syscall *sc,
243 unsigned long taddr, const char *buf, int bytes)
245 SIM_DESC sd = (SIM_DESC) sc->p1;
246 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
247 return sim_core_write_buffer (sd, cpu, write_map, buf, taddr, bytes);
249 void target_sim_syscall (SIM_CPU *cpu)
251 SIM_DESC sd = CPU_STATE (cpu);
252 host_callback *cb = STATE_CALLBACK (sd);
255 CB_SYSCALL_INIT (&sc);
257 sc.func = <fetch system call number>;
258 sc.arg1 = <fetch first system call argument>;
259 sc.arg2 = <fetch second system call argument>;
260 sc.arg3 = <fetch third system call argument>;
261 sc.arg4 = <fetch fourth system call argument>;
264 sc.read_mem = syscall_read_mem;
265 sc.write_mem = syscall_write_mem;
267 cb_syscall (cb, &sc);
269 <store system call result from sc.result>;
270 <store system call error from sc.errcode>;
272 Some targets store the result and error code in different places, while others
273 only store the error code when the result is an error.
275 Keep in mind that the CB_SYS_xxx defines are normalized values with no real
276 meaning with respect to the target. They provide a unique map on the host so
277 that it can parse things sanely. For libgloss, the common/target-newlib-syscall
278 file contains the target's system call numbers to the CB_SYS_xxx values.
280 To simulate other userspace targets, you really only need to update the maps
281 pointers that are part of the callback interface. So create CB_TARGET_DEFS_MAP
282 arrays for each set (system calls, errnos, open bits, etc...) and in a place
283 you find useful, do something like:
286 static CB_TARGET_DEFS_MAP cb_linux_syscall_map[] = {
287 # define TARGET_LINUX_SYS_open 5
288 { CB_SYS_open, TARGET_LINUX_SYS_open },
293 host_callback *cb = STATE_CALLBACK (sd);
294 cb->syscall_map = cb_linux_syscall_map;
295 cb->errno_map = cb_linux_errno_map;
296 cb->open_map = cb_linux_open_map;
297 cb->signal_map = cb_linux_signal_map;
298 cb->stat_map = cb_linux_stat_map;
301 Each of these cb_linux_*_map's are manually declared by the arch target.
303 The target_sim_syscall() example above will then work unchanged (ignoring the
304 system call convention) because all of the callback functions go through these
310 Events are scheduled and executed on behalf of either a cpu or hardware devices.
311 The API is pretty much the same and can be found in common/sim-events.h and
314 For simulator targets, you really just have to worry about the schedule and
315 deschedule functions.
320 The device tree model is based on the OpenBoot specification. Since this is
321 largely inherited from the psim code, consult the existing psim documentation
322 for some in-depth details.
323 http://sourceware.org/psim/manual/
328 The simplest simulator doesn't include hardware device support. Once you're
329 ready to move on to the next level, declare in your Makefile.in:
330 SIM_EXTRA_HW_DEVICES = devone devtwo devthree
332 The basic hardware API is documented in common/hw-device.h.
334 Each device has to have a matching file name with a "dv-" prefix. So there has
335 to be a dv-devone.c, dv-devtwo.c, and dv-devthree.c files. Further, each file
336 has to have a matching hw_descriptor structure. So the dv-devone.c file has to
338 const struct hw_descriptor dv_devone_descriptor[] = {
339 {"devone", devone_finish,},
343 The "devone" string as well as the "devone_finish" function are not hard
344 requirements, just common conventions. The structure name is a hard
347 The devone_finish() callback function is used to instantiate this device by
348 parsing the corresponding properties in the device tree.
350 Hardware devices typically attach address ranges to themselves. Then when
351 accesses to those addresses are made, the hardware will have its callback
352 invoked. The exact callback could be a normal I/O read/write access, as
353 well as a DMA access. This makes it easy to simulate memory mapped registers.
355 Keep in mind that like a proper device driver, it may be instantiated many
356 times over. So any device state it needs to be maintained should be allocated
357 during the finish callback and attached to the hardware device via set_hw_data.
358 Any hardware functions can access this private data via the hw_data function.
360 Ports (Interrupts / IRQs)
361 =========================
363 First, a note on terminology. A "port" is an aspect of a hardware device that
364 accepts or generates interrupts. So devices with input ports may be the target
365 of an interrupt (accept it), and/or they have output ports so that they may be
366 the source of an interrupt (generate it).
368 Each port has a symbolic name and a unique number. These are used to identify
369 the port in different contexts. The output port name has no hard relationship
370 to the input port name (same for the unique number). The callback that accepts
371 the interrupt uses the name/id of its input port, while the generator function
372 uses the name/id of its output port.
374 The device tree is used to connect the output port of a device to the input
375 port of another device. There are no limits on the number of inputs connected
376 to an output, or outputs to an input, or the devices attached to the ports.
377 In other words, the input port and output port could be the same device.
380 - each hardware device declares an array of ports (hw_port_descriptor).
381 any mix of input and output ports is allowed.
382 - when setting up the device, attach the array (set_hw_ports).
383 - if the device accepts interrupts, it will have to attach a port callback
384 function (set_hw_port_event)
385 - connect ports with the device tree
386 - handle incoming interrupts with the callback
387 - generate outgoing interrupts with hw_port_event