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 # List of main object files for `run'.
90 # Dependency of `all' to build any extra files.
92 # Dependency of `install' to install any extra files.
94 # Dependency of `clean' to clean any extra files.
97 ## COMMON_POST_CONFIG_FRAG
99 # Rules need to build $(SIM_OBJS), plus whatever else the target wants.
101 ... target specific rules ...
104 COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
105 where to insert the two pieces of common/Make-common.in.
106 The resulting Makefile is created by doing autoconf substitions on
107 both the target's Makefile.in and Make-common.in, and inserting
108 the two pieces of Make-common.in into the target's Makefile.in at
109 COMMON_{PRE,POST}_CONFIG_FRAG.
111 Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
112 could be used instead. However, it's not clear yet whether "::" targets
118 Many files generate program symbols at compile time.
119 Such symbols can't be found with grep nor do they normally appear in
120 the TAGS file. To get around this, source files can add the comment
122 /* TAGS: foo1 foo2 */
124 where foo1, foo2 are program symbols. Symbols found in such comments
125 are greppable and appear in the TAGS file.
127 Generating "configure" files
128 ============================
130 For targets using the common framework, "configure" can be generated
131 by running `autoconf'.
133 To regenerate the configure files for all targets using the common framework:
136 $ make -f Makefile.in SHELL=/bin/sh autoconf-common
138 To add a change-log entry to the ChangeLog file for each updated
139 directory (WARNING - check the modified new-ChangeLog files before
142 $ make -f Makefile.in SHELL=/bin/sh autoconf-changelog
143 $ more */new-ChangeLog
144 $ make -f Makefile.in SHELL=/bin/sh autoconf-install
146 In a similar vein, both the configure and config.in files can be
147 updated using the sequence:
150 $ make -f Makefile.in SHELL=/bin/sh autoheader-common
151 $ make -f Makefile.in SHELL=/bin/sh autoheader-changelog
152 $ more */new-ChangeLog
153 $ make -f Makefile.in SHELL=/bin/sh autoheader-install
155 To add the entries to an alternative ChangeLog file, use:
157 $ make ChangeLog=MyChangeLog ....
160 C Language Assumptions
161 ======================
163 An ISO C11 compiler is required, as is an ISO C standard library.
165 "dump" commands under gdb
166 =========================
168 gdbinit.in contains the following
171 set sim_debug_dump ()
174 Simulators that define the sim_debug_dump function can then have their
175 internal state pretty printed from gdb.
177 FIXME: This can obviously be made more elaborate. As needed it will be.
179 Rebuilding nltvals.def
180 ======================
182 Checkout a copy of the SIM and LIBGLOSS modules (Unless you've already
187 $ cvs checkout sim-no-testsuite libgloss-no-testsuite newlib-no-testsuite
189 Configure things for an arbitrary simulator target (I've d10v for
192 $ mkdir /tmp/$$/build
194 $ /tmp/$$/devo/configure --target=d10v-elf
196 In the sim/common directory rebuild the headers:
203 devo/sim/common/gennltvals.sh
205 Add your new processor target (you'll need to grub
206 around to find where your syscall.h lives).
208 devo/sim/<processor>/Makefile.in
212 ``NL_TARGET = -DNL_TARGET_d10v''
214 just before the line COMMON_POST_CONFIG_FRAG.
216 devo/sim/<processor>/*.[ch]
218 Include targ-vals.h instead of syscall.h.
223 For ports based on CGEN, tracing instrumentation should largely be for free,
224 so we will cover the basic non-CGEN setup here. The assumption is that your
225 target is using the common autoconf macros and so the build system already
226 includes the sim-trace configure flag.
228 The full tracing API is covered in sim-trace.h, so this section is an overview.
230 Before calling any trace function, you should make a call to the trace_prefix()
231 function. This is usually done in the main sim_engine_run() loop before
232 simulating the next instruction. You should make this call before every
233 simulated insn. You can probably copy & paste this:
234 if (TRACE_ANY_P (cpu))
235 trace_prefix (sd, cpu, NULL_CIA, oldpc, TRACE_LINENUM_P (cpu), NULL, 0, "");
237 You will then need to instrument your simulator code with calls to the
238 trace_generic() function with the appropriate trace index. Typically, this
239 will take a form similar to the above snippet. So to trace instructions, you
240 would use something like:
241 if (TRACE_INSN_P (cpu))
242 trace_generic (sd, cpu, TRACE_INSN_IDX, "NOP;");
244 The exact output format is up to you. See the trace index enum in sim-trace.h
245 to see the different tracing info available.
247 To utilize the tracing features at runtime, simply use the --trace-xxx flags.
248 run --trace-insn ./some-program
253 Similar to the tracing section, this is merely an overview for non-CGEN based
254 ports. The full API may be found in sim-profile.h. Its API is also similar
257 Note that unlike the tracing command line options, in addition to the profile
258 flags, you have to use the --verbose option to view the summary report after
259 execution. Tracing output is displayed on the fly, but the profile output is
262 To profile core accesses (such as data reads/writes and insn fetches), add
263 calls to PROFILE_COUNT_CORE() to your read/write functions. So in your data
264 fetch function, you'd use something like:
265 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_read);
266 Then in your data write function:
267 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_write);
268 And in your insn fetcher:
269 PROFILE_COUNT_CORE (cpu, target_addr, size_in_bytes, map_exec);
271 To use the PC profiling code, you simply have to tell the system where to find
272 your simulator's PC and its size. So in your sim_open() function:
273 STATE_WATCHPOINTS (sd)->pc = address_of_cpu0_pc;
274 STATE_WATCHPOINTS (sd)->sizeof_pc = number_of_bytes_for_pc_storage;
275 In a typical 32bit system, the sizeof_pc will be 4 bytes.
277 To profile branches, in every location where a branch insn is executed, call
278 one of the related helpers:
279 PROFILE_BRANCH_TAKEN (cpu);
280 PROFILE_BRANCH_UNTAKEN (cpu);
281 If you have stall information, you can utilize the other helpers too.
283 Environment Simulation
284 ======================
286 The simplest simulator doesn't include environment support -- it merely
287 simulates the Instruction Set Architecture (ISA). Once you're ready to move
288 on to the next level, call the common macro in your configure.ac:
289 SIM_AC_OPTION_ENVIRONMENT
291 This will support for the user, virtual, and operating environments. See the
292 sim-config.h header for a more detailed description of them. The former are
293 pretty straight forward as things like exceptions (making system calls) are
294 handled in the simulator. Which is to say, an exception does not trigger an
295 exception handler in the simulator target -- that is what the operating env
296 is about. See the following userspace section for more information.
298 Userspace System Calls
299 ======================
301 By default, the libgloss userspace is simulated. That means the system call
302 numbers and calling convention matches that of libgloss. Simulating other
303 userspaces (such as Linux) is pretty straightforward, but let's first focus
304 on the basics. The basic API is covered in include/gdb/callback.h.
306 When an instruction is simulated that invokes the system call method (such as
307 forcing a hardware trap or exception), your simulator code should set up the
308 CB_SYSCALL data structure before calling the common cb_syscall() function.
311 syscall_read_mem (host_callback *cb, struct cb_syscall *sc,
312 unsigned long taddr, char *buf, int bytes)
314 SIM_DESC sd = (SIM_DESC) sc->p1;
315 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
316 return sim_core_read_buffer (sd, cpu, read_map, buf, taddr, bytes);
319 syscall_write_mem (host_callback *cb, struct cb_syscall *sc,
320 unsigned long taddr, const char *buf, int bytes)
322 SIM_DESC sd = (SIM_DESC) sc->p1;
323 SIM_CPU *cpu = (SIM_CPU *) sc->p2;
324 return sim_core_write_buffer (sd, cpu, write_map, buf, taddr, bytes);
326 void target_sim_syscall (SIM_CPU *cpu)
328 SIM_DESC sd = CPU_STATE (cpu);
329 host_callback *cb = STATE_CALLBACK (sd);
332 CB_SYSCALL_INIT (&sc);
334 sc.func = <fetch system call number>;
335 sc.arg1 = <fetch first system call argument>;
336 sc.arg2 = <fetch second system call argument>;
337 sc.arg3 = <fetch third system call argument>;
338 sc.arg4 = <fetch fourth system call argument>;
341 sc.read_mem = syscall_read_mem;
342 sc.write_mem = syscall_write_mem;
344 cb_syscall (cb, &sc);
346 <store system call result from sc.result>;
347 <store system call error from sc.errcode>;
349 Some targets store the result and error code in different places, while others
350 only store the error code when the result is an error.
352 Keep in mind that the CB_SYS_xxx defines are normalized values with no real
353 meaning with respect to the target. They provide a unique map on the host so
354 that it can parse things sanely. For libgloss, the common/nltvals.def file
355 creates the target's system call numbers to the CB_SYS_xxx values.
357 To simulate other userspace targets, you really only need to update the maps
358 pointers that are part of the callback interface. So create CB_TARGET_DEFS_MAP
359 arrays for each set (system calls, errnos, open bits, etc...) and in a place
360 you find useful, do something like:
363 static CB_TARGET_DEFS_MAP cb_linux_syscall_map[] = {
364 # define TARGET_LINUX_SYS_open 5
365 { CB_SYS_open, TARGET_LINUX_SYS_open },
370 host_callback *cb = STATE_CALLBACK (sd);
371 cb->syscall_map = cb_linux_syscall_map;
372 cb->errno_map = cb_linux_errno_map;
373 cb->open_map = cb_linux_open_map;
374 cb->signal_map = cb_linux_signal_map;
375 cb->stat_map = cb_linux_stat_map;
378 Each of these cb_linux_*_map's are manually declared by the arch target.
380 The target_sim_syscall() example above will then work unchanged (ignoring the
381 system call convention) because all of the callback functions go through these
387 Events are scheduled and executed on behalf of either a cpu or hardware devices.
388 The API is pretty much the same and can be found in common/sim-events.h and
391 For simulator targets, you really just have to worry about the schedule and
392 deschedule functions.
397 The device tree model is based on the OpenBoot specification. Since this is
398 largely inherited from the psim code, consult the existing psim documentation
399 for some in-depth details.
400 http://sourceware.org/psim/manual/
405 The simplest simulator doesn't include hardware device support. Once you're
406 ready to move on to the next level, call the common macro in your configure.ac:
407 SIM_AC_OPTION_HARDWARE(yes,,devone devtwo devthree)
409 The basic hardware API is documented in common/hw-device.h.
411 Each device has to have a matching file name with a "dv-" prefix. So there has
412 to be a dv-devone.c, dv-devtwo.c, and dv-devthree.c files. Further, each file
413 has to have a matching hw_descriptor structure. So the dv-devone.c file has to
415 const struct hw_descriptor dv_devone_descriptor[] = {
416 {"devone", devone_finish,},
420 The "devone" string as well as the "devone_finish" function are not hard
421 requirements, just common conventions. The structure name is a hard
424 The devone_finish() callback function is used to instantiate this device by
425 parsing the corresponding properties in the device tree.
427 Hardware devices typically attach address ranges to themselves. Then when
428 accesses to those addresses are made, the hardware will have its callback
429 invoked. The exact callback could be a normal I/O read/write access, as
430 well as a DMA access. This makes it easy to simulate memory mapped registers.
432 Keep in mind that like a proper device driver, it may be instantiated many
433 times over. So any device state it needs to be maintained should be allocated
434 during the finish callback and attached to the hardware device via set_hw_data.
435 Any hardware functions can access this private data via the hw_data function.
437 Ports (Interrupts / IRQs)
438 =========================
440 First, a note on terminology. A "port" is an aspect of a hardware device that
441 accepts or generates interrupts. So devices with input ports may be the target
442 of an interrupt (accept it), and/or they have output ports so that they may be
443 the source of an interrupt (generate it).
445 Each port has a symbolic name and a unique number. These are used to identify
446 the port in different contexts. The output port name has no hard relationship
447 to the input port name (same for the unique number). The callback that accepts
448 the interrupt uses the name/id of its input port, while the generator function
449 uses the name/id of its output port.
451 The device tree is used to connect the output port of a device to the input
452 port of another device. There are no limits on the number of inputs connected
453 to an output, or outputs to an input, or the devices attached to the ports.
454 In other words, the input port and output port could be the same device.
457 - each hardware device declares an array of ports (hw_port_descriptor).
458 any mix of input and output ports is allowed.
459 - when setting up the device, attach the array (set_hw_ports).
460 - if the device accepts interrupts, it will have to attach a port callback
461 function (set_hw_port_event)
462 - connect ports with the device tree
463 - handle incoming interrupts with the callback
464 - generate outgoing interrupts with hw_port_event