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