| blob | 41e9f98dcc529c10ecc429eb9cdd82edb09d9f7e |
1 '\" te
2 .\" Copyright (c) 1998 Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH ADBGEN 1M "Feb 20, 1998"
7 .SH NAME
8 adbgen \- generate adb script
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/lib/adb/adbgen\fR [\fB-m\fR \fImodel\fR] \fIfilename\fR.adb .\|.\|.
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 \fBadbgen\fR makes it possible to write \fBadb\fR(1) scripts that do not
19 contain hard-coded dependencies on structure member offsets. The input to
20 \fBadbgen\fR is a file named \fIfilename\fR\fB\&.adb\fR that contains header
21 information, then a null line, then the name of a structure, and finally an
22 \fBadb\fR script. \fBadbgen\fR only deals with one structure per file; all
23 member names are assumed to be in this structure. The output of \fBadbgen\fR is
24 an \fBadb\fR script in \fIfilename\fR. \fBadbgen\fR operates by generating a C
25 program which determines structure member offsets and sizes, which in turn
26 generate the \fBadb\fR script.
27 .sp
28 .LP
29 The header lines, up to the null line, are copied verbatim into the generated C
30 program. Typically, these are \fB#include\fR statements, which include the
31 headers containing the relevant structure declarations.
32 .sp
33 .LP
34 The \fBadb\fR script part may contain any valid \fBadb\fR commands (see
35 \fBadb\fR(1)), and may also contain \fBadbgen\fR requests, each enclosed in
36 braces (\fB\|{\|}\fR\|). Request types are:
37 .RS +4
38 .TP
39 .ie t \(bu
40 .el o
41 Print a structure member. The request form is
42 \fB{\fR\fImember\fR\fB,\fR\fI\|format\fR\fB}.\fR \fImember\fR is a member name
43 of the \fIstructure\fR given earlier, and \fBformat\fR is any valid \fBadb\fR
44 format request or any of the \fBadbgen\fR format specifiers (such as
45 \fB{POINTER}\fR) listed below. For example, to print the \fBp_pid\fR field of
46 the \fIproc\fR structure as a decimal number, you would write \fB{p_pid,d}\fR.
47 .RE
48 .RS +4
49 .TP
50 .ie t \(bu
51 .el o
52 Print the appropriate \fBadb\fR format character for the given \fBadbgen\fR
53 format specifier. This action takes the data model into consideration. The
54 request form is \fB{\fR\fIformat specifier\fR\fB}.\fR The valid \fBadbgen\fR
55 format specifiers are:
56 .RS
58 .sp
59 .ne 2
60 .na
61 \fB\fB{POINTER}\fR\fR
62 .ad
63 .RS 14n
64 pointer value in hexadecimal
65 .RE
67 .sp
68 .ne 2
69 .na
70 \fB\fB{LONGDEC}\fR\fR
71 .ad
72 .RS 14n
73 long value in decimal
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fB\fB{ULONGDEC}\fR\fR
80 .ad
81 .RS 14n
82 unsigned long value in decimal
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fB{ULONGHEX}\fR\fR
89 .ad
90 .RS 14n
91 unsigned long value in hexadecimal
92 .RE
94 .sp
95 .ne 2
96 .na
97 \fB\fB{LONGOCT}\fR\fR
98 .ad
99 .RS 14n
100 long value in octal
101 .RE
103 .sp
104 .ne 2
105 .na
106 \fB\fB{ULONGOCT}\fR\fR
107 .ad
108 .RS 14n
109 unsigned long value in octal
110 .RE
112 .RE
114 .RE
115 .RS +4
116 .TP
117 .ie t \(bu
118 .el o
119 Reference a structure member. The request form is
120 \fB{*\fR\fImember\fR\fB,\fR\fI\|base\fR\fB}.\fR \fImember\fR is the member name
121 whose value is desired, and \fIbase\fR is an \fBadb\fR register name which
122 contains the base address of the structure. For example, to get the \fBp_pid\fR
123 field of the \fIproc\fR structure, you would get the \fIproc\fR structure
124 address in an \fBadb\fR register, for example \fB<f\fR, and write
125 \fB{*p_pid,<f}\fR.
126 .RE
127 .RS +4
128 .TP
129 .ie t \(bu
130 .el o
131 Tell \fBadbgen\fR that the offset is valid. The request form is
132 \fB{OFFSETOK}\fR. This is useful after invoking another \fBadb\fR script which
133 moves the \fBadb\fR \fIdot\fR.
134 .RE
135 .RS +4
136 .TP
137 .ie t \(bu
138 .el o
139 Get the size of the \fIstructure\fR. The request form is \fB{SIZEOF}\fR.
140 \fBadbgen\fR replaces this request with the size of the structure. This is
141 useful in incrementing a pointer to step through an array of structures.
142 .RE
143 .RS +4
144 .TP
145 .ie t \(bu
146 .el o
147 Calculate an arbitrary C expression. The request form is
148 \fB{EXPR,\fR\fI\|expression\fR\fB}.\fR \fBadbgen\fR replaces this request with
149 the value of the expression. This is useful when more than one structure is
150 involved in the script.
151 .RE
152 .RS +4
153 .TP
154 .ie t \(bu
155 .el o
156 Get the offset to the end of the structure. The request form is \fB{END}\fR.
157 This is useful at the end of the structure to get \fBadb\fR to align the
158 \fIdot\fR for printing the next structure member.
159 .RE
160 .sp
161 .LP
162 \fBadbgen\fR keeps track of the movement of the \fBadb\fR \fIdot\fR and
163 generates \fBadb\fR code to move forward or backward as necessary before
164 printing any structure member in a script. \fBadbgen\fR's model of the behavior
165 of \fBadb\fR's \fIdot\fR is simple: it is assumed that the first line of the
166 script is of the form \fIstruct_address\fR/\fIadb text\fR and that subsequent
167 lines are of the form +/\fIadb text\fR. The \fBadb\fR \fIdot\fR then moves in a
168 sane fashion. \fBadbgen\fR does not check the script to ensure that these
169 limitations are met. \fBadbgen\fR also checks the size of the structure member
170 against the size of the \fBadb\fR format code and warns if they are not equal.
171 .SH OPTIONS
172 .sp
173 .LP
174 The following option is supported:
175 .sp
176 .ne 2
177 .na
178 \fB\fB-m\fR \fImodel\fR\fR
179 .ad
180 .RS 12n
181 Specifies the data type model to be used by \fBadbgen\fR for the macro. This
182 affects the outcome of the \fB{\fR\fIformat specifier\fR\fB}\fR requests
183 described under \fBDESCRIPTION\fR and the offsets and sizes of data types.
184 \fImodel\fR can be \fBilp32\fR or \fBlp64\fR. If the \fB-m\fR option is not
185 given, the data type model defaults to \fBilp32\fR.
186 .RE
188 .SH OPERANDS
189 .sp
190 .LP
191 The following operand is supported:
192 .sp
193 .ne 2
194 .na
195 \fB\fIfilename\fR\fB\&.adb\fR\fR
196 .ad
197 .RS 18n
198 Input file that contains header information, followed by a null line, the name
199 of the structure, and finally an \fBadb\fR script.
200 .RE
202 .SH EXAMPLES
203 .LP
204 \fBExample 1 \fRA sample \fBadbgen\fR file.
205 .sp
206 .LP
207 For an include file \fBx.h\fR which contained
209 .sp
210 .in +2
211 .nf
212 struct x {
213 char *x_cp;
214 char x_c;
215 int x_i;
216 };
217 .fi
218 .in -2
219 .sp
221 .sp
222 .LP
223 then , an \fBadbgen\fR file (call it \fBscript.adb\fR) to print the file
224 \fBx.h\fR would be:
226 .sp
227 .in +2
228 .nf
229 #include "x.h"
230 x
231 \&./"x_cp"16t"x_c"8t"x_i"n{x_cp,{POINTER}}{x_c,C}{x_i,D}
232 .fi
233 .in -2
234 .sp
236 .sp
237 .LP
238 After running \fBadbgen\fR as follows,
240 .sp
241 .in +2
242 .nf
243 % /usr/lib/adb/adbgen \|script.adb
244 .fi
245 .in -2
246 .sp
248 .sp
249 .LP
250 the output file \fBscript\fR contains:
252 .sp
253 .in +2
254 .nf
255 \&./"x_cp"16t"x_c"8t"x_i"nXC3+D
256 .fi
257 .in -2
258 .sp
260 .sp
261 .LP
262 For a macro generated for a 64-bit program using the \fBlp64\fR data model as
263 follows,
265 .sp
266 .in +2
267 .nf
268 \fB% /usr/lib/adb/adbgen/ \fR\fB-m\fR\fB lp64 \|script.adb\fR
269 .fi
270 .in -2
271 .sp
273 .sp
274 .LP
275 the output file \fBscript\fR would contain:
277 .sp
278 .in +2
279 .nf
280 \&./"x_cp"16t"x_c"8t"x_i"nJC3+D
281 .fi
282 .in -2
283 .sp
285 .sp
286 .LP
287 To invoke the script, type:
289 .sp
290 .in +2
291 .nf
292 example% adb program
293 x$<script
294 .fi
295 .in -2
296 .sp
298 .SH FILES
299 .sp
300 .ne 2
301 .na
302 \fB\fB/usr/platform/\fR\fIplatform-name\fR\fB/lib/adb/*\fR\fR
303 .ad
304 .sp .6
305 .RS 4n
306 platform-specific \fBadb\fR scripts for debugging the 32-bit kernel
307 .RE
309 .sp
310 .ne 2
311 .na
312 \fB\fB/usr/platform/\fR\fIplatform-name\fR\fB/lib/adb/sparcv9/*\fR\fR
313 .ad
314 .sp .6
315 .RS 4n
316 platform-specific \fBadb\fR scripts for debugging the 64-bit SPARC V9 kernel
317 .RE
319 .sp
320 .ne 2
321 .na
322 \fB\fB/usr/lib/adb/*\fR\fR
323 .ad
324 .sp .6
325 .RS 4n
326 \fBadb\fR scripts for debugging the 32-bit kernel
327 .RE
329 .sp
330 .ne 2
331 .na
332 \fB\fB/usr/lib/adb/sparcv9/*\fR\fR
333 .ad
334 .sp .6
335 .RS 4n
336 \fBadb\fR scripts for debugging the 64-bit SPARC V9 kernel
337 .RE
339 .SH SEE ALSO
340 .sp
341 .LP
342 \fBadb\fR(1), \fBuname\fR(1), \fBkadb\fR(1M), \fBattributes\fR(5)
343 .SH DIAGNOSTICS
344 .sp
345 .LP
346 Warnings are given about structure member sizes not equal to \fBadb\fR format
347 items and about badly formatted requests. The C compiler complains if a
348 structure member that does not exist is referenced. It also complains about an
349 ampersand before array names; these complaints may be ignored.
350 .SH NOTES
351 .sp
352 .LP
353 \fIplatform-name\fR can be found using the \fB-i\fR option of \fBuname\fR(1).
354 .SH BUGS
355 .sp
356 .LP
357 \fBadb\fR syntax is ugly; there should be a higher level interface for
358 generating scripts.
359 .sp
360 .LP
361 Structure members which are bit fields cannot be handled because C will not
362 give the address of a bit field. The address is needed to determine the offset.