![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to debug.doc CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Atari MiNT] / MiNT / doc|
Return to debug.doc CVS log | Up to [Atari MiNT] / MiNT / doc |
1.1 root 1: Writing Debuggers for MiNT
2:
3:
4:
5: MiNT provides a special pseudo-drive, U:\PROC, in which processes appear
6:
7: as files. This drive may be used by debuggers much as the Unix /proc
8:
9: file system is used, although the specific details of implementation will
10:
11: be different.
12:
13:
14:
15: The entry for a process in U:\PROC has a name like SOMEPROG.nnn, where
16:
17: "nnn" is a 3 digit number which is the (decimal) process ID of the process,
18:
19: and "SOMEPROG" is the name of the process. When opening a process, only
20:
21: the process ID matters; a process does *not* need to know another process'
22:
23: name in order to open it, only its process id. So, for example,
24:
25: fd = Fopen("U:\\PROC\\FOO.032",2);
26:
27: fd = Fopen("U:\\PROC\\.032",2);
28:
29: and
30:
31: fd = Fopen("U:\\PROC\\TCSH.032",2);
32:
33: will all open the process with process id #32 for reading and writing,
34:
35: regardless of the actual name of that process.
36:
37:
38:
39: Also, note that a process id of -1 refers to the current process, and a
40:
41: process id of -2 refers to the parent of the current process; thus,
42:
43: fd = Fopen("U:\\PROC\\.-1",2);
44:
45: may always be used to open oneself.
46:
47:
48:
49: Before a process may be debugged (or "traced") it must first be marked
50:
51: as a traced process, and a specific process (often its parent) must
52:
53: be marked as the "tracer", the program which will be notified when the
54:
55: traced process receives signals.
56:
57:
58:
59: (1) If the process to be traced is started with Pexec, and the high bit
60:
61: of the Pexec mode is set, then the child process begins
62:
63: as a "traced" process automatically, with its parent as tracer.
64:
65:
66:
67: Example:
68:
69: childpid = Pexec(0x8000|100, "foo.prg", "", 0L);
70:
71:
72:
73: (2) The traced process may indicate that it wishes to be traced by opening
74:
75: its own entry in U:\PROC and performing an Fcntl(...PTRACESFLAGS) call
76:
77: which enables tracing. In this case, the child's parent will become
78:
79: the tracer automatically. Note that if the parent is not prepared to
80:
81: perform debugging functions, there could be undesireable results, so
82:
83: the child must be *certain* that the parent wishes to debug it; for
84:
85: example, this is the case if the child and parent are both executing
86:
87: from the same program image (e.g. the child was started with the
88:
89: Pvfork() system call). This method of indicating tracing is quite
90:
91: similar to Unix's ptrace(0,...) function.
92:
93:
94:
95: Example:
96:
97: if ((pid = Pvfork()) == 0) {
98:
99: short flag = 1;
100:
101: int fd;
102:
103:
104:
105: /* here we are in the child */
106:
107: /* open self; see notes above */
108:
109: fd = Fopen("U:\\PROC\\A.-1",2);
110:
111: /* perform Fcntl */
112:
113: Fcntl(fd, &flag, PTRACESFLAGS);
114:
115: /* close self, we don't need the handle any more */
116:
117: Fclose(fd);
118:
119: /* now overlay the child with a new program image */
120:
121: Pexec(200, "foo.prg", "", 0L);
122:
123: }
124:
125:
126:
127: (3) A process may force another process to be traced by opening that process'
128:
129: entry in U:\PROC, and doing an Fcntl(...PTRACESFLAGS) on it. This is
130:
131: the only way in which to trace a process that is not the
132:
133: child of the debugging process.
134:
135:
136:
137: Example:
138:
139: short flag = 1;
140:
141:
142:
143: /* open process "pid" for tracing */
144:
145: sprintf(name, "U:\\PROC\\A.%03d", pid);
146:
147: fd = Fopen(name, 2);
148:
149: Fcntl(fd, &flag, PTRACESFLAGS);
150:
151: /* leave fd open so that we can read and write it... */
152:
153:
154:
155:
156:
157: What Happens When A Traced Process Receives a Signal
158:
159:
160:
161: If a traced process receives a signal (for example, a bus error), then
162:
163: it is placed into a STOP condition and a SIGCHLD signal is sent to
164:
165: the tracer. If the tracer performs a Pwait3 or Pwaitpid system call,
166:
167: it can then retrieve the pid of the stopped process, and the signal which
168:
169: caused that process to stop. For example:
170:
171:
172:
173: #define WIFSTOPPED(x) (((int)((x) & 0xFF) == 0x7F) && ((int)(((x) >> 8) & 0xFF) != 0))
174:
175: #define WSTOPSIG(x) ((int)(((x) >> 8) & 0xFF))
176:
177: unsigned long r;
178:
179:
180:
181: /* 0x2 is a flag that indicates that we want to see stopped processes */
182:
183: r = Pwait3(0x2, 0L);
184:
185: if (WIFSTOPPED(r)) {
186:
187: pid = r >> 16;
188:
189: signal = WSTOPSIG(r);
190:
191: }
192:
193:
194:
195: The tracer can then examine the stopped process' address space and registers
196:
197: (using the Fread, Fwrite, and Fcntl system calls; see below) and/or make
198:
199: modifications to the stopped process' state. It can then restart that
200:
201: process with either the PTRACEGO, PTRACEFLOW, or PTRACESTEP Fcntl commands.
202:
203: The PTRACEGO command Fcntl(fd, &sig, PTRACEGO), where "sig" is a 16 bit
204:
205: integer, restarts the process. If sig == 0, then all pending signals in
206:
207: the traced process are cleared; otherwise, the signal represented by
208:
209: "sig" will be delivered to the process after it starts again. Normally,
210:
211: this signal would be the same one which caused the process to stop. Note
212:
213: that this second time the signal is delivered it will not cause the
214:
215: process to stop, but rather will cause whatever action is normally associated
216:
217: with the signal (for example, SIGKILL will kill the process).
218:
219:
220:
221: PTRACEFLOW and PTRACESTEP are similar to PTRACEGO, but they also set some
222:
223: bits in the status register of the stopped process which will cause a
224:
225: SIGTRAP (trace trap) signal to be raised either on the next instruction
226:
227: to be executed (PTRACESTEP) or the next branch or jump instruction to
228:
229: be executed (PTRACEFLOW; this only works on a 68030 or 68040 processor).
230:
231: Note that if the traced process was executing a system call at the time
232:
233: it stopped, the trace trap signal will not take effect until the process
234:
235: leaves the kernel. PTRACESTEP, then, makes it possible to single step
236:
237: through the traced program.
238:
239:
240:
241:
242:
243: Reading and Writing the Process' Address Space, and Setting Breakpoints
244:
245:
246:
247: Traditional debuggers for the ST have directly accessed the address space
248:
249: of the debugged process. This is undesireable because it assumes that
250:
251: both processes share a common address space, something which may not be
252:
253: the case if memory protection is enabled; also, in a virtual memory
254:
255: system logical addresses in the child and parent may be translated
256:
257: differently. The U:\PROC file system may be used to avoid both of these
258:
259: difficulties. If the debugger opens the process to be debugged for
260:
261: reading and writing, it may then use Fread and Fwrite system calls to
262:
263: transfer data (e.g. breakpoint instructions) to and from the debugged
264:
265: process' address space.
266:
267:
268:
269: To read 100 bytes from address 0x0123456 in the address space of
270:
271: process 12, for example, one would do:
272:
273: char buf[100];
274:
275:
276:
277: fd = Fopen("U:\\PROC\\A.012", 2);
278:
279: Fseek(0x0123456L, fd, 0);
280:
281: Fread(fd, 100L, buf);
282:
283: (Note that error checking should be performed in any real application;
284:
285: for example, the Fopen could very well fail if the process being
286:
287: opened is another user's process.)
288:
289:
290:
291:
292:
293: Reading and Writing the Process' Registers
294:
295:
296:
297: The registers of the stopped process are also available for inspection.
298:
299: The PPROCADDR and PCTXTSIZE Fcntl commands are used to find the
300:
301: address of the process context block in the traced process' address
302:
303: space; the registers of the process can then be read from the address
304:
305: space with Fread, or written to the address space with Fwrite.
306:
307:
308:
309: Example:
310:
311: long curprocaddr;
312:
313: long ctxtsize;
314:
315: struct context {
316:
317: long regs[15]; /* registers d0-d7, a0-a6 */
318:
319: long usp; /* user stack pointer */
320:
321: short sr; /* status register */
322:
323: long pc; /* program counter */
324:
325: long ssp; /* supervisor stack pointer */
326:
327: long tvec; /* GEMDOS terminate vector */
328:
329: char fstate[216]; /* internal FPU state */
330:
331: long fregs[3*8]; /* registers fp0-fp7 */
332:
333: long fctrl[3]; /* FPCR/FPSR/FPIAR */
334:
335: /* there are some more, undocumented, fields, in the
336:
337: * MiNT context structure
338:
339: */
340:
341: } c;
342:
343:
344:
345: /* get the address of the process control structure */
346:
347: Fcntl(fd, &curprocaddr, PPROCADDR);
348:
349:
350:
351: /* get the size of the process context structure.
352:
353: * there are 2 of these, located immediately before
354:
355: * the process control structure. The first one
356:
357: * is the one we're interested in (the second one
358:
359: * is used by MiNT, and should never be modified).
360:
361: */
362:
363: Fcntl(fd, &ctxtsize, PCTXTSIZE);
364:
365:
366:
367: /* make curprocaddr point to the first context struct */
368:
369: curprocaddr -= 2*ctxtsize;
370:
371:
372:
373: /* now read the context structure */
374:
375: Fseek(curprocaddr, fd, 0);
376:
377: Fread(fd, (long)sizeof(struct context), &c);
378:
379:
380:
381: /* the various fields of c are now set up properly */
382:
383: ... /* code omitted */
384:
385:
386:
387: /* now write back the context to reflect whatever changes
388:
389: * we made
390:
391: */
392:
393: Fseek(curprocaddr, fd, 0);
394:
395: Fwrite(fd, (long)sizeof(struct context), &c);
396:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.