readme
1GDB Stub for DJGPP 0.2 Readme File
2==================================
3
4Copyright
5---------
6GDB Stub for DJGPP is distributed under the terms of the GNU Library
7General Public License (GNU LGPL) - please see the document LICENSE,
8which should be found in the same directory as this file.
9
10Copyright (c) 2000 by Jonathan Brogdon, 2002 by Gordon Schumacher
11
12What It Does
13------------
14The GDB stub is used to debug a DJGPP target remotely over a one of
15the PC COM ports. GDB, running on a host machine, communicates with
16the target using the GDB serial protocol over the serial link. For
17more information on the GDB stub, see "Debugging with GDB, The GNU
18Source-Level Debugger", by Richard M. Stallman and Roland H. Pesch
19(http://sources.redhat.com/gdb/download/onlinedocs/gdb.html)
20
21How It Works
22------------
23
24Exceptions:
25
26The GDB stub needs to handle all processor exceptions. Since these
27exceptions already handled by DJGPP, we cannot handle them directly.
28DJGPP maps all processor exceptions to signals. Therefore, we can
29install the GDB stub handler as the signal handler for those signals
30that represent processor exceptions. The following table shows the
31processor exception to signal mapping:
32
33 Exception/Interrupt: Exception #: Signal:
34 ------------------- ----------- ------
35 Divide Error 0 SIGFPE
36 Debug Exception 1 SIGTRAP
37 NMI Interrupt 2 No signal defined
38 Breakpoint 3 SIGTRAP
39 INTO-detected overflow 4 SIGFPE
40 BOUND Range Exceeded 5 SIGSEGV
41 Invalid Opcode 6 No signal defined
42 Coprocessor not available 7 SIGNOFP
43 Double Fault 8 SIGSEGV
44 Coprocessor Seg overrun 9 SIGSEGV
45 Invalid Task State Seg 10 No signal defined
46 Segment not present 11 SIGSEGV
47 Stack Fault 12 SIGSEGV
48 General Protection Fault 13 SIGSEGV
49 Page Fault 14 SIGSEGV
50 Intel Reserved 15 No signal defined
51 Coprocessor Error 16 SIGFPE
52
53The GDB stub handler services requests from the GDB host. These
54requests are seen by the GDB stub handler as command messages from
55the GDB host. These commands and command formats are defined in
56"Debugging with GDB, The GNU Source-Level Debugger", by Richard M.
57Stallman and Roland H. Pesch (http://sources.redhat.com/gdb/
58download/onlinedocs/gdb.html -- one of many sources).
59
60Serial Interface:
61
62Interface functions for sending and receiving characters from the
63serial interface must be provided by the engineer porting the GDB
64stub. The following funtions must be provided to support the
65implementation.
66
67 int getDebugChar(void);
68 void putDebugChar(int c);
69
70There are a variety of serial libraries for DJGPP. The user may
71already be using one of these libraries in their application, and
72installing more than one serial library often causes conflicts.
73To this end, a modular function layer was written that allows any
74serial library to be used with the GDB stub. Layers have been
75written to support SVAsync, DZComm, and the _bios_serialcom()
76function. At the time of this writing, DZComm appears to work the
77best for serial debugging.
78
79Hard Coded Breakpoint:
80
81A breakpoint() function is provided to manually invoke the stub.
82This function, inserts a breakpoint instruction directly in the code
83to invoke the GDB stub handler.
84
85How You Use It
86--------------
87First, you need to select a serial library. In the i386-supp.c file,
88there are lines of the form
89
90 // #include "some_layer.h"
91
92Uncomment the line for the serial library you intend to use - or add
93a new include line for a file written for some other library.
94In the main() function of your target program, you should initilize
95the GDB serial handlers and the GDB stub. The following functions
96are provided in the GDB stub library for this purpose.
97
98 gdb_serial_init(unsigned int port, unsigned int speed);
99 gdb_target_init(void);
100
101Where, port is the COM port number, and speed is the baud rate for
102the serial link.
103
104After initialing the GDB serial interface and target, you should
105invoke the breakpoint() function somewhere. You may choose to do
106this immediately after initialization, or at a specific location in
107your code where you wish to set a breakpoint. By putting the
108breakpoint() function in the beginning of main(), you can use the
109GDB host to set a breakpoint at any place in your code.
110
111Make sure that you use the '-g' option when compiling your files with
112gcc.
113
114After the target executable is running, start up gdb on the host,
115passing the target executable as an argument.
116
117 Example: gdb demo.exe
118
119Now, tell gdb which serial interface to use for communicating to
120the target.
121
122 Example: (gdb) target remote COM1
123
124This example uses COM1 on the host to communicate with the target.
125GDB is now 'listening' on COM for a valid GDB serial packet.
126
127Once your GDB host finds your target, you may need to tell GDB where
128to find any source files which were used to generate your program.
129Use the directory command to do this.
130
131 Example: (gdb) directory ../src/demo
132
133That's it. You should now be able to single step through code, set
134breakpoints, set variables, examine variables, any anthing else that
135you would normally use GDB to accomplish.
136
137What You Build
138--------------
139Read the INSTALL file for more information on installing the GDB stub
140library. After installing the library, your code should include
141i386-stub.h for function prototypes. In addition, your code should
142link against the libgdb.a library. The source for a demonstration
143program has been included with this distributias an example.
144As an alternative, you can simply include the i386-stub and i386-supp
145files and the layer header for the serial library you plan to use into
146your project and link them in directly.
147
148For More Info
149-------------
150See "Debugging with GDB, The GNU Source-Level Debugger", by Richard
151M. Stallman and Roland H. Pesch (http://sources.redhat.com/gdb/
152download/onlinedocs/gdb.html -- one of many sources).
153
154TODO
155----
156Port for network operation.
157
158Contact Info
159------------
160My contact info is below. If you have any comments, suggestions, bug
161reports or problems, please mail me, and I'll see what I can do.
162
163 Regards,
164 Jonathan Brogdon
165 <brogdon@austin.rr.com>
166 6th June 2000
167
168 Modular update:
169 Gordon Schumacher
170 <gordons@valleyhold.org>
171 12th February 2002