~ubuntu-branches/debian/sid/gdb/sid : revision 19

1

\input texinfo @c -*- texinfo -*-

2

@setfilename gdbint.info

3

@include gdb-cfg.texi

4

@settitle @value{GDBN} Internals

5

@setchapternewpage off

6

@dircategory Software development

7

@direntry

8

* Gdb-Internals: (gdbint). The GNU debugger's internals.

9

@end direntry

10

11

@copying

12

Copyright @copyright{} 1990-1994, 1996, 1998-2006, 2008-2012 Free

13

Software Foundation, Inc.

14

Contributed by Cygnus Solutions. Written by John Gilmore.

15

Second Edition by Stan Shebs.

16

17

Permission is granted to copy, distribute and/or modify this document

18

under the terms of the GNU Free Documentation License, Version 1.3 or

19

any later version published by the Free Software Foundation; with no

20

Invariant Sections, with no Front-Cover Texts, and with no Back-Cover

21

Texts. A copy of the license is included in the section entitled ``GNU

22

Free Documentation License''.

23

@end copying

24

25

@ifnottex

26

This file documents the internals of the GNU debugger @value{GDBN}.

27

28

@insertcopying

29

@end ifnottex

30

31

32

@syncodeindex fn cp

33

@syncodeindex vr cp

34

35

@titlepage

36

@title @value{GDBN} Internals

37

@subtitle{A guide to the internals of the GNU debugger}

38

@author John Gilmore

39

@author Cygnus Solutions

40

@author Second Edition:

41

@author Stan Shebs

42

@author Cygnus Solutions

43

@page

44

@tex

45

\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$

46

\xdef\manvers{\$Revision$} % For use in headers, footers too

47

{\parskip=0pt

48

\hfill Cygnus Solutions\par

49

\hfill \manvers\par

50

\hfill \TeX{}info \texinfoversion\par

51

}

52

@end tex

53

54

@vskip 0pt plus 1filll

55

@insertcopying

56

@end titlepage

57

58

@contents

59

60

@node Top

61

@c Perhaps this should be the title of the document (but only for info,

62

@c not for TeX). Existing GNU manuals seem inconsistent on this point.

63

@top Scope of this Document

64

65

This document documents the internals of the GNU debugger, @value{GDBN}. It

66

includes description of @value{GDBN}'s key algorithms and operations, as well

67

as the mechanisms that adapt @value{GDBN} to specific hosts and targets.

68

69

@menu

70

* Summary::

71

* Overall Structure::

72

* Algorithms::

73

* User Interface::

74

* libgdb::

75

* Values::

76

* Stack Frames::

77

* Symbol Handling::

78

* Language Support::

79

* Host Definition::

80

* Target Architecture Definition::

81

* Target Descriptions::

82

* Target Vector Definition::

83

* Native Debugging::

84

* Support Libraries::

85

* Coding Standards::

86

* Misc Guidelines::

87

* Porting GDB::

88

* Versions and Branches::

89

* Start of New Year Procedure::

90

* Releasing GDB::

91

* Testsuite::

92

* Hints::

93

94

* GDB Observers:: @value{GDBN} Currently available observers

95

* GNU Free Documentation License:: The license for this documentation

96

* Index::

97

@end menu

98

99

@node Summary

100

@chapter Summary

101

102

@menu

103

* Requirements::

104

* Contributors::

105

@end menu

106

107

@node Requirements

108

@section Requirements

109

@cindex requirements for @value{GDBN}

110

111

Before diving into the internals, you should understand the formal

112

requirements and other expectations for @value{GDBN}. Although some

113

of these may seem obvious, there have been proposals for @value{GDBN}

114

that have run counter to these requirements.

115

116

First of all, @value{GDBN} is a debugger. It's not designed to be a

117

front panel for embedded systems. It's not a text editor. It's not a

118

shell. It's not a programming environment.

119

120

@value{GDBN} is an interactive tool. Although a batch mode is

121

available, @value{GDBN}'s primary role is to interact with a human

122

programmer.

123

124

@value{GDBN} should be responsive to the user. A programmer hot on

125

the trail of a nasty bug, and operating under a looming deadline, is

126

going to be very impatient of everything, including the response time

127

to debugger commands.

128

129

@value{GDBN} should be relatively permissive, such as for expressions.

130

While the compiler should be picky (or have the option to be made

131

picky), since source code lives for a long time usually, the

132

programmer doing debugging shouldn't be spending time figuring out to

133

mollify the debugger.

134

135

@value{GDBN} will be called upon to deal with really large programs.

136

Executable sizes of 50 to 100 megabytes occur regularly, and we've

137

heard reports of programs approaching 1 gigabyte in size.

138

139

@value{GDBN} should be able to run everywhere. No other debugger is

140

available for even half as many configurations as @value{GDBN}

141

supports.

142

143

@node Contributors

144

@section Contributors

145

146

The first edition of this document was written by John Gilmore of

147

Cygnus Solutions. The current second edition was written by Stan Shebs

148

of Cygnus Solutions, who continues to update the manual.

149

150

Over the years, many others have made additions and changes to this

151

document. This section attempts to record the significant contributors

152

to that effort. One of the virtues of free software is that everyone

153

is free to contribute to it; with regret, we cannot actually

154

acknowledge everyone here.

155

156

@quotation

157

@emph{Plea:} This section has only been added relatively recently (four

158

years after publication of the second edition). Additions to this

159

section are particularly welcome. If you or your friends (or enemies,

160

to be evenhanded) have been unfairly omitted from this list, we would

161

like to add your names!

162

@end quotation

163

164

A document such as this relies on being kept up to date by numerous

165

small updates by contributing engineers as they make changes to the

166

code base. The file @file{ChangeLog} in the @value{GDBN} distribution

167

approximates a blow-by-blow account. The most prolific contributors to

168

this important, but low profile task are Andrew Cagney (responsible

169

for over half the entries), Daniel Jacobowitz, Mark Kettenis, Jim

170

Blandy and Eli Zaretskii.

171

172

Eli Zaretskii and Daniel Jacobowitz wrote the sections documenting

173

watchpoints.

174

175

Jeremy Bennett updated the sections on initializing a new architecture

176

and register representation, and added the section on Frame Interpretation.

177

178

179

@node Overall Structure

180

181

@chapter Overall Structure

182

183

@value{GDBN} consists of three major subsystems: user interface,

184

symbol handling (the @dfn{symbol side}), and target system handling (the

185

@dfn{target side}).

186

187

The user interface consists of several actual interfaces, plus

188

supporting code.

189

190

The symbol side consists of object file readers, debugging info

191

interpreters, symbol table management, source language expression

192

parsing, type and value printing.

193

194

The target side consists of execution control, stack frame analysis, and

195

physical target manipulation.

196

197

The target side/symbol side division is not formal, and there are a

198

number of exceptions. For instance, core file support involves symbolic

199

elements (the basic core file reader is in BFD) and target elements (it

200

supplies the contents of memory and the values of registers). Instead,

201

this division is useful for understanding how the minor subsystems

202

should fit together.

203

204

@section The Symbol Side

205

206

The symbolic side of @value{GDBN} can be thought of as ``everything

207

you can do in @value{GDBN} without having a live program running''.

208

For instance, you can look at the types of variables, and evaluate

209

many kinds of expressions.

210

211

@section The Target Side

212

213

The target side of @value{GDBN} is the ``bits and bytes manipulator''.

214

Although it may make reference to symbolic info here and there, most

215

of the target side will run with only a stripped executable

216

available---or even no executable at all, in remote debugging cases.

217

218

Operations such as disassembly, stack frame crawls, and register

219

display, are able to work with no symbolic info at all. In some cases,

220

such as disassembly, @value{GDBN} will use symbolic info to present addresses

221

relative to symbols rather than as raw numbers, but it will work either

222

way.

223

224

@section Configurations

225

226

@cindex host

227

@cindex target

228

@dfn{Host} refers to attributes of the system where @value{GDBN} runs.

229

@dfn{Target} refers to the system where the program being debugged

230

executes. In most cases they are the same machine, in which case a

231

third type of @dfn{Native} attributes come into play.

232

233

Defines and include files needed to build on the host are host

234

support. Examples are tty support, system defined types, host byte

235

order, host float format. These are all calculated by @code{autoconf}

236

when the debugger is built.

237

238

Defines and information needed to handle the target format are target

239

dependent. Examples are the stack frame format, instruction set,

240

breakpoint instruction, registers, and how to set up and tear down the stack

241

to call a function.

242

243

Information that is only needed when the host and target are the same,

244

is native dependent. One example is Unix child process support; if the

245

host and target are not the same, calling @code{fork} to start the target

246

process is a bad idea. The various macros needed for finding the

247

registers in the @code{upage}, running @code{ptrace}, and such are all

248

in the native-dependent files.

249

250

Another example of native-dependent code is support for features that

251

are really part of the target environment, but which require

252

@code{#include} files that are only available on the host system. Core

253

file handling and @code{setjmp} handling are two common cases.

254

255

When you want to make @value{GDBN} work as the traditional native debugger

256

on a system, you will need to supply both target and native information.

257

258

@section Source Tree Structure

259

@cindex @value{GDBN} source tree structure

260

261

The @value{GDBN} source directory has a mostly flat structure---there

262

are only a few subdirectories. A file's name usually gives a hint as

263

to what it does; for example, @file{stabsread.c} reads stabs,

264

@file{dwarf2read.c} reads @sc{DWARF 2}, etc.

265

266

Files that are related to some common task have names that share

267

common substrings. For example, @file{*-thread.c} files deal with

268

debugging threads on various platforms; @file{*read.c} files deal with

269

reading various kinds of symbol and object files; @file{inf*.c} files

270

deal with direct control of the @dfn{inferior program} (@value{GDBN}

271

parlance for the program being debugged).

272

273

There are several dozens of files in the @file{*-tdep.c} family.

274

@samp{tdep} stands for @dfn{target-dependent code}---each of these

275

files implements debug support for a specific target architecture

276

(sparc, mips, etc). Usually, only one of these will be used in a

277

specific @value{GDBN} configuration (sometimes two, closely related).

278

279

Similarly, there are many @file{*-nat.c} files, each one for native

280

debugging on a specific system (e.g., @file{sparc-linux-nat.c} is for

281

native debugging of Sparc machines running the Linux kernel).

282

283

The few subdirectories of the source tree are:

284

285

@table @file

286

@item cli

287

Code that implements @dfn{CLI}, the @value{GDBN} Command-Line

288

Interpreter. @xref{User Interface, Command Interpreter}.

289

290

@item gdbserver

291

Code for the @value{GDBN} remote server.

292

293

@item gdbtk

294

Code for Insight, the @value{GDBN} TK-based GUI front-end.

295

296

@item mi

297

The @dfn{GDB/MI}, the @value{GDBN} Machine Interface interpreter.

298

299

@item signals

300

Target signal translation code.

301

302

@item tui

303

Code for @dfn{TUI}, the @value{GDBN} Text-mode full-screen User

304

Interface. @xref{User Interface, TUI}.

305

@end table

306

307

@node Algorithms

308

309

@chapter Algorithms

310

@cindex algorithms

311

312

@value{GDBN} uses a number of debugging-specific algorithms. They are

313

often not very complicated, but get lost in the thicket of special

314

cases and real-world issues. This chapter describes the basic

315

algorithms and mentions some of the specific target definitions that

316

they use.

317

318

@section Prologue Analysis

319

320

@cindex prologue analysis

321

@cindex call frame information

322

@cindex CFI (call frame information)

323

To produce a backtrace and allow the user to manipulate older frames'

324

variables and arguments, @value{GDBN} needs to find the base addresses

325

of older frames, and discover where those frames' registers have been

326

saved. Since a frame's ``callee-saves'' registers get saved by

327

younger frames if and when they're reused, a frame's registers may be

328

scattered unpredictably across younger frames. This means that

329

changing the value of a register-allocated variable in an older frame

330

may actually entail writing to a save slot in some younger frame.

331

332

Modern versions of GCC emit Dwarf call frame information (``CFI''),

333

which describes how to find frame base addresses and saved registers.

334

But CFI is not always available, so as a fallback @value{GDBN} uses a

335

technique called @dfn{prologue analysis} to find frame sizes and saved

336

registers. A prologue analyzer disassembles the function's machine

337

code starting from its entry point, and looks for instructions that

338

allocate frame space, save the stack pointer in a frame pointer

339

register, save registers, and so on. Obviously, this can't be done

340

accurately in general, but it's tractable to do well enough to be very

341

helpful. Prologue analysis predates the GNU toolchain's support for

342

CFI; at one time, prologue analysis was the only mechanism

343

@value{GDBN} used for stack unwinding at all, when the function

344

calling conventions didn't specify a fixed frame layout.

345

346

In the olden days, function prologues were generated by hand-written,

347

target-specific code in GCC, and treated as opaque and untouchable by

348

optimizers. Looking at this code, it was usually straightforward to

349

write a prologue analyzer for @value{GDBN} that would accurately

350

understand all the prologues GCC would generate. However, over time

351

GCC became more aggressive about instruction scheduling, and began to

352

understand more about the semantics of the prologue instructions

353

themselves; in response, @value{GDBN}'s analyzers became more complex

354

and fragile. Keeping the prologue analyzers working as GCC (and the

355

instruction sets themselves) evolved became a substantial task.

356

357

@cindex @file{prologue-value.c}

358

@cindex abstract interpretation of function prologues

359

@cindex pseudo-evaluation of function prologues

360

To try to address this problem, the code in @file{prologue-value.h}

361

and @file{prologue-value.c} provides a general framework for writing

362

prologue analyzers that are simpler and more robust than ad-hoc

363

analyzers. When we analyze a prologue using the prologue-value

364

framework, we're really doing ``abstract interpretation'' or

365

``pseudo-evaluation'': running the function's code in simulation, but

366

using conservative approximations of the values registers and memory

367

would hold when the code actually runs. For example, if our function

368

starts with the instruction:

369

370

@example

371

addi r1, 42 # add 42 to r1

372

@end example

373

@noindent

374

we don't know exactly what value will be in @code{r1} after executing

375

this instruction, but we do know it'll be 42 greater than its original

376

value.

377

378

If we then see an instruction like:

379

380

@example

381

addi r1, 22 # add 22 to r1

382

@end example

383

@noindent

384

we still don't know what @code{r1's} value is, but again, we can say

385

it is now 64 greater than its original value.

386

387

If the next instruction were:

388

389

@example

390

mov r2, r1 # set r2 to r1's value

391

@end example

392

@noindent

393

then we can say that @code{r2's} value is now the original value of

394

@code{r1} plus 64.

395

396

It's common for prologues to save registers on the stack, so we'll

397

need to track the values of stack frame slots, as well as the

398

registers. So after an instruction like this:

399

400

@example

401

mov (fp+4), r2

402

@end example

403

@noindent

404

then we'd know that the stack slot four bytes above the frame pointer

405

holds the original value of @code{r1} plus 64.

406

407

And so on.

408

409

Of course, this can only go so far before it gets unreasonable. If we

410

wanted to be able to say anything about the value of @code{r1} after

411

the instruction:

412

413

@example

414

xor r1, r3 # exclusive-or r1 and r3, place result in r1

415

@end example

416

@noindent

417

then things would get pretty complex. But remember, we're just doing

418

a conservative approximation; if exclusive-or instructions aren't

419

relevant to prologues, we can just say @code{r1}'s value is now

420

``unknown''. We can ignore things that are too complex, if that loss of

421

information is acceptable for our application.

422

423

So when we say ``conservative approximation'' here, what we mean is an

424

approximation that is either accurate, or marked ``unknown'', but

425

never inaccurate.

426

427

Using this framework, a prologue analyzer is simply an interpreter for

428

machine code, but one that uses conservative approximations for the

429

contents of registers and memory instead of actual values. Starting

430

from the function's entry point, you simulate instructions up to the

431

current PC, or an instruction that you don't know how to simulate.

432

Now you can examine the state of the registers and stack slots you've

433

kept track of.

434

435

@itemize @bullet

436

437

@item

438

To see how large your stack frame is, just check the value of the

439

stack pointer register; if it's the original value of the SP

440

minus a constant, then that constant is the stack frame's size.

441

If the SP's value has been marked as ``unknown'', then that means

442

the prologue has done something too complex for us to track, and

443

we don't know the frame size.

444

445

@item

446

To see where we've saved the previous frame's registers, we just

447

search the values we've tracked --- stack slots, usually, but

448

registers, too, if you want --- for something equal to the register's

449

original value. If the calling conventions suggest a standard place

450

to save a given register, then we can check there first, but really,

451

anything that will get us back the original value will probably work.

452

@end itemize

453

454

This does take some work. But prologue analyzers aren't

455

quick-and-simple pattern patching to recognize a few fixed prologue

456

forms any more; they're big, hairy functions. Along with inferior

457

function calls, prologue analysis accounts for a substantial portion

458

of the time needed to stabilize a @value{GDBN} port. So it's

459

worthwhile to look for an approach that will be easier to understand

460

and maintain. In the approach described above:

461

462

@itemize @bullet

463

464

@item

465

It's easier to see that the analyzer is correct: you just see

466

whether the analyzer properly (albeit conservatively) simulates

467

the effect of each instruction.

468

469

@item

470

It's easier to extend the analyzer: you can add support for new

471

instructions, and know that you haven't broken anything that

472

wasn't already broken before.

473

474

@item

475

It's orthogonal: to gather new information, you don't need to

476

complicate the code for each instruction. As long as your domain

477

of conservative values is already detailed enough to tell you

478

what you need, then all the existing instruction simulations are

479

already gathering the right data for you.

480

481

@end itemize

482

483

The file @file{prologue-value.h} contains detailed comments explaining

484

the framework and how to use it.

485

486

487

@section Breakpoint Handling

488

489

@cindex breakpoints

490

In general, a breakpoint is a user-designated location in the program

491

where the user wants to regain control if program execution ever reaches

492

that location.

493

494

There are two main ways to implement breakpoints; either as ``hardware''

495

breakpoints or as ``software'' breakpoints.

496

497

@cindex hardware breakpoints

498

@cindex program counter

499

Hardware breakpoints are sometimes available as a builtin debugging

500

features with some chips. Typically these work by having dedicated

501

register into which the breakpoint address may be stored. If the PC

502

(shorthand for @dfn{program counter})

503

ever matches a value in a breakpoint registers, the CPU raises an

504

exception and reports it to @value{GDBN}.

505

506

Another possibility is when an emulator is in use; many emulators

507

include circuitry that watches the address lines coming out from the

508

processor, and force it to stop if the address matches a breakpoint's

509

address.

510

511

A third possibility is that the target already has the ability to do

512

breakpoints somehow; for instance, a ROM monitor may do its own

513

software breakpoints. So although these are not literally ``hardware

514

breakpoints'', from @value{GDBN}'s point of view they work the same;

515

@value{GDBN} need not do anything more than set the breakpoint and wait

516

for something to happen.

517

518

Since they depend on hardware resources, hardware breakpoints may be

519

limited in number; when the user asks for more, @value{GDBN} will

520

start trying to set software breakpoints. (On some architectures,

521

notably the 32-bit x86 platforms, @value{GDBN} cannot always know

522

whether there's enough hardware resources to insert all the hardware

523

breakpoints and watchpoints. On those platforms, @value{GDBN} prints

524

an error message only when the program being debugged is continued.)

525

526

@cindex software breakpoints

527

Software breakpoints require @value{GDBN} to do somewhat more work.

528

The basic theory is that @value{GDBN} will replace a program

529

instruction with a trap, illegal divide, or some other instruction

530

that will cause an exception, and then when it's encountered,

531

@value{GDBN} will take the exception and stop the program. When the

532

user says to continue, @value{GDBN} will restore the original

533

instruction, single-step, re-insert the trap, and continue on.

534

535

Since it literally overwrites the program being tested, the program area

536

must be writable, so this technique won't work on programs in ROM. It

537

can also distort the behavior of programs that examine themselves,

538

although such a situation would be highly unusual.

539

540

Also, the software breakpoint instruction should be the smallest size of

541

instruction, so it doesn't overwrite an instruction that might be a jump

542

target, and cause disaster when the program jumps into the middle of the

543

breakpoint instruction. (Strictly speaking, the breakpoint must be no

544

larger than the smallest interval between instructions that may be jump

545

targets; perhaps there is an architecture where only even-numbered

546

instructions may jumped to.) Note that it's possible for an instruction

547

set not to have any instructions usable for a software breakpoint,

548

although in practice only the ARC has failed to define such an

549

instruction.

550

551

Basic breakpoint object handling is in @file{breakpoint.c}. However,

552

much of the interesting breakpoint action is in @file{infrun.c}.

553

554

@table @code

555

@cindex insert or remove software breakpoint

556

@findex target_remove_breakpoint

557

@findex target_insert_breakpoint

558

@item target_remove_breakpoint (@var{bp_tgt})

559

@itemx target_insert_breakpoint (@var{bp_tgt})

560

Insert or remove a software breakpoint at address

561

@code{@var{bp_tgt}->placed_address}. Returns zero for success,

562

non-zero for failure. On input, @var{bp_tgt} contains the address of the

563

breakpoint, and is otherwise initialized to zero. The fields of the

564

@code{struct bp_target_info} pointed to by @var{bp_tgt} are updated

565

to contain other information about the breakpoint on output. The field

566

@code{placed_address} may be updated if the breakpoint was placed at a

567

related address; the field @code{shadow_contents} contains the real

568

contents of the bytes where the breakpoint has been inserted,

569

if reading memory would return the breakpoint instead of the

570

underlying memory; the field @code{shadow_len} is the length of

571

memory cached in @code{shadow_contents}, if any; and the field

572

@code{placed_size} is optionally set and used by the target, if

573

it could differ from @code{shadow_len}.

574

575

For example, the remote target @samp{Z0} packet does not require

576

shadowing memory, so @code{shadow_len} is left at zero. However,

577

the length reported by @code{gdbarch_breakpoint_from_pc} is cached in

578

@code{placed_size}, so that a matching @samp{z0} packet can be

579

used to remove the breakpoint.

580

581

@cindex insert or remove hardware breakpoint

582

@findex target_remove_hw_breakpoint

583

@findex target_insert_hw_breakpoint

584

@item target_remove_hw_breakpoint (@var{bp_tgt})

585

@itemx target_insert_hw_breakpoint (@var{bp_tgt})

586

Insert or remove a hardware-assisted breakpoint at address

587

@code{@var{bp_tgt}->placed_address}. Returns zero for success,

588

non-zero for failure. See @code{target_insert_breakpoint} for

589

a description of the @code{struct bp_target_info} pointed to by

590

@var{bp_tgt}; the @code{shadow_contents} and

591

@code{shadow_len} members are not used for hardware breakpoints,

592

but @code{placed_size} may be.

593

@end table

594

595

@section Single Stepping

596

597

@section Signal Handling

598

599

@section Thread Handling

600

601

@section Inferior Function Calls

602

603

@section Longjmp Support

604

605

@cindex @code{longjmp} debugging

606

@value{GDBN} has support for figuring out that the target is doing a

607

@code{longjmp} and for stopping at the target of the jump, if we are

608

stepping. This is done with a few specialized internal breakpoints,

609

which are visible in the output of the @samp{maint info breakpoint}

610

command.

611

612

@findex gdbarch_get_longjmp_target

613

To make this work, you need to define a function called

614

@code{gdbarch_get_longjmp_target}, which will examine the

615

@code{jmp_buf} structure and extract the @code{longjmp} target address.

616

Since @code{jmp_buf} is target specific and typically defined in a

617

target header not available to @value{GDBN}, you will need to

618

determine the offset of the PC manually and return that; many targets

619

define a @code{jb_pc_offset} field in the tdep structure to save the

620

value once calculated.

621

622

@section Watchpoints

623

@cindex watchpoints

624

625

Watchpoints are a special kind of breakpoints (@pxref{Algorithms,

626

breakpoints}) which break when data is accessed rather than when some

627

instruction is executed. When you have data which changes without

628

your knowing what code does that, watchpoints are the silver bullet to

629

hunt down and kill such bugs.

630

631

@cindex hardware watchpoints

632

@cindex software watchpoints

633

Watchpoints can be either hardware-assisted or not; the latter type is

634

known as ``software watchpoints.'' @value{GDBN} always uses

635

hardware-assisted watchpoints if they are available, and falls back on

636

software watchpoints otherwise. Typical situations where @value{GDBN}

637

will use software watchpoints are:

638

639

@itemize @bullet

640

@item

641

The watched memory region is too large for the underlying hardware

642

watchpoint support. For example, each x86 debug register can watch up

643

to 4 bytes of memory, so trying to watch data structures whose size is

644

more than 16 bytes will cause @value{GDBN} to use software

645

watchpoints.

646

647

@item

648

The value of the expression to be watched depends on data held in

649

registers (as opposed to memory).

650

651

@item

652

Too many different watchpoints requested. (On some architectures,

653

this situation is impossible to detect until the debugged program is

654

resumed.) Note that x86 debug registers are used both for hardware

655

breakpoints and for watchpoints, so setting too many hardware

656

breakpoints might cause watchpoint insertion to fail.

657

658

@item

659

No hardware-assisted watchpoints provided by the target

660

implementation.

661

@end itemize

662

663

Software watchpoints are very slow, since @value{GDBN} needs to

664

single-step the program being debugged and test the value of the

665

watched expression(s) after each instruction. The rest of this

666

section is mostly irrelevant for software watchpoints.

667

668

When the inferior stops, @value{GDBN} tries to establish, among other

669

possible reasons, whether it stopped due to a watchpoint being hit.

670

It first uses @code{STOPPED_BY_WATCHPOINT} to see if any watchpoint

671

was hit. If not, all watchpoint checking is skipped.

672

673

Then @value{GDBN} calls @code{target_stopped_data_address} exactly

674

once. This method returns the address of the watchpoint which

675

triggered, if the target can determine it. If the triggered address

676

is available, @value{GDBN} compares the address returned by this

677

method with each watched memory address in each active watchpoint.

678

For data-read and data-access watchpoints, @value{GDBN} announces

679

every watchpoint that watches the triggered address as being hit.

680

For this reason, data-read and data-access watchpoints

681

@emph{require} that the triggered address be available; if not, read

682

and access watchpoints will never be considered hit. For data-write

683

watchpoints, if the triggered address is available, @value{GDBN}

684

considers only those watchpoints which match that address;

685

otherwise, @value{GDBN} considers all data-write watchpoints. For

686

each data-write watchpoint that @value{GDBN} considers, it evaluates

687

the expression whose value is being watched, and tests whether the

688

watched value has changed. Watchpoints whose watched values have

689

changed are announced as hit.

690

691

@c FIXME move these to the main lists of target/native defns

692

693

@value{GDBN} uses several macros and primitives to support hardware

694

watchpoints:

695

696

@table @code

697

@findex TARGET_CAN_USE_HARDWARE_WATCHPOINT

698

@item TARGET_CAN_USE_HARDWARE_WATCHPOINT (@var{type}, @var{count}, @var{other})

699

Return the number of hardware watchpoints of type @var{type} that are

700

possible to be set. The value is positive if @var{count} watchpoints

701

of this type can be set, zero if setting watchpoints of this type is

702

not supported, and negative if @var{count} is more than the maximum

703

number of watchpoints of type @var{type} that can be set. @var{other}

704

is non-zero if other types of watchpoints are currently enabled (there

705

are architectures which cannot set watchpoints of different types at

706

the same time).

707

708

@findex TARGET_REGION_OK_FOR_HW_WATCHPOINT

709

@item TARGET_REGION_OK_FOR_HW_WATCHPOINT (@var{addr}, @var{len})

710

Return non-zero if hardware watchpoints can be used to watch a region

711

whose address is @var{addr} and whose length in bytes is @var{len}.

712

713

@cindex insert or remove hardware watchpoint

714

@findex target_insert_watchpoint

715

@findex target_remove_watchpoint

716

@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})

717

@itemx target_remove_watchpoint (@var{addr}, @var{len}, @var{type})

718

Insert or remove a hardware watchpoint starting at @var{addr}, for

719

@var{len} bytes. @var{type} is the watchpoint type, one of the

720

possible values of the enumerated data type @code{target_hw_bp_type},

721

defined by @file{breakpoint.h} as follows:

722

723

@smallexample

724

enum target_hw_bp_type

725

@{

726

hw_write = 0, /* Common (write) HW watchpoint */

727

hw_read = 1, /* Read HW watchpoint */

728

hw_access = 2, /* Access (read or write) HW watchpoint */

729

hw_execute = 3 /* Execute HW breakpoint */

730

@};

731

@end smallexample

732

733

@noindent

734

These two macros should return 0 for success, non-zero for failure.

735

736

@findex target_stopped_data_address

737

@item target_stopped_data_address (@var{addr_p})

738

If the inferior has some watchpoint that triggered, place the address

739

associated with the watchpoint at the location pointed to by

740

@var{addr_p} and return non-zero. Otherwise, return zero. This

741

is required for data-read and data-access watchpoints. It is

742

not required for data-write watchpoints, but @value{GDBN} uses

743

it to improve handling of those also.

744

745

@value{GDBN} will only call this method once per watchpoint stop,

746

immediately after calling @code{STOPPED_BY_WATCHPOINT}. If the

747

target's watchpoint indication is sticky, i.e., stays set after

748

resuming, this method should clear it. For instance, the x86 debug

749

control register has sticky triggered flags.

750

751

@findex target_watchpoint_addr_within_range

752

@item target_watchpoint_addr_within_range (@var{target}, @var{addr}, @var{start}, @var{length})

753

Check whether @var{addr} (as returned by @code{target_stopped_data_address})

754

lies within the hardware-defined watchpoint region described by

755

@var{start} and @var{length}. This only needs to be provided if the

756

granularity of a watchpoint is greater than one byte, i.e., if the

757

watchpoint can also trigger on nearby addresses outside of the watched

758

region.

759

760

@findex HAVE_STEPPABLE_WATCHPOINT

761

@item HAVE_STEPPABLE_WATCHPOINT

762

If defined to a non-zero value, it is not necessary to disable a

763

watchpoint to step over it. Like @code{gdbarch_have_nonsteppable_watchpoint},

764

this is usually set when watchpoints trigger at the instruction

765

which will perform an interesting read or write. It should be

766

set if there is a temporary disable bit which allows the processor

767

to step over the interesting instruction without raising the

768

watchpoint exception again.

769

770

@findex gdbarch_have_nonsteppable_watchpoint

771

@item int gdbarch_have_nonsteppable_watchpoint (@var{gdbarch})

772

If it returns a non-zero value, @value{GDBN} should disable a

773

watchpoint to step the inferior over it. This is usually set when

774

watchpoints trigger at the instruction which will perform an

775

interesting read or write.

776

777

@findex HAVE_CONTINUABLE_WATCHPOINT

778

@item HAVE_CONTINUABLE_WATCHPOINT

779

If defined to a non-zero value, it is possible to continue the

780

inferior after a watchpoint has been hit. This is usually set

781

when watchpoints trigger at the instruction following an interesting

782

read or write.

783

784

@findex STOPPED_BY_WATCHPOINT

785

@item STOPPED_BY_WATCHPOINT (@var{wait_status})

786

Return non-zero if stopped by a watchpoint. @var{wait_status} is of

787

the type @code{struct target_waitstatus}, defined by @file{target.h}.

788

Normally, this macro is defined to invoke the function pointed to by

789

the @code{to_stopped_by_watchpoint} member of the structure (of the

790

type @code{target_ops}, defined on @file{target.h}) that describes the

791

target-specific operations; @code{to_stopped_by_watchpoint} ignores

792

the @var{wait_status} argument.

793

794

@value{GDBN} does not require the non-zero value returned by

795

@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot

796

determine for sure whether the inferior stopped due to a watchpoint,

797

it could return non-zero ``just in case''.

798

@end table

799

800

@subsection Watchpoints and Threads

801

@cindex watchpoints, with threads

802

803

@value{GDBN} only supports process-wide watchpoints, which trigger

804

in all threads. @value{GDBN} uses the thread ID to make watchpoints

805

act as if they were thread-specific, but it cannot set hardware

806

watchpoints that only trigger in a specific thread. Therefore, even

807

if the target supports threads, per-thread debug registers, and

808

watchpoints which only affect a single thread, it should set the

809

per-thread debug registers for all threads to the same value. On

810

@sc{gnu}/Linux native targets, this is accomplished by using

811

@code{ALL_LWPS} in @code{target_insert_watchpoint} and

812

@code{target_remove_watchpoint} and by using

813

@code{linux_set_new_thread} to register a handler for newly created

814

threads.

815

816

@value{GDBN}'s @sc{gnu}/Linux support only reports a single event

817

at a time, although multiple events can trigger simultaneously for

818

multi-threaded programs. When multiple events occur, @file{linux-nat.c}

819

queues subsequent events and returns them the next time the program

820

is resumed. This means that @code{STOPPED_BY_WATCHPOINT} and

821

@code{target_stopped_data_address} only need to consult the current

822

thread's state---the thread indicated by @code{inferior_ptid}. If

823

two threads have hit watchpoints simultaneously, those routines

824

will be called a second time for the second thread.

825

826

@subsection x86 Watchpoints

827

@cindex x86 debug registers

828

@cindex watchpoints, on x86

829

830

The 32-bit Intel x86 (a.k.a.@: ia32) processors feature special debug

831

registers designed to facilitate debugging. @value{GDBN} provides a

832

generic library of functions that x86-based ports can use to implement

833

support for watchpoints and hardware-assisted breakpoints. This

834

subsection documents the x86 watchpoint facilities in @value{GDBN}.

835

836

(At present, the library functions read and write debug registers directly, and are

837

thus only available for native configurations.)

838

839

To use the generic x86 watchpoint support, a port should do the

840

following:

841

842

@itemize @bullet

843

@findex I386_USE_GENERIC_WATCHPOINTS

844

@item

845

Define the macro @code{I386_USE_GENERIC_WATCHPOINTS} somewhere in the

846

target-dependent headers.

847

848

@item

849

Include the @file{config/i386/nm-i386.h} header file @emph{after}

850

defining @code{I386_USE_GENERIC_WATCHPOINTS}.

851

852

@item

853

Add @file{i386-nat.o} to the value of the Make variable

854

@code{NATDEPFILES} (@pxref{Native Debugging, NATDEPFILES}).

855

856

@item

857

Provide implementations for the @code{I386_DR_LOW_*} macros described

858

below. Typically, each macro should call a target-specific function

859

which does the real work.

860

@end itemize

861

862

The x86 watchpoint support works by maintaining mirror images of the

863

debug registers. Values are copied between the mirror images and the

864

real debug registers via a set of macros which each target needs to

865

provide:

866

867

@table @code

868

@findex I386_DR_LOW_SET_CONTROL

869

@item I386_DR_LOW_SET_CONTROL (@var{val})

870

Set the Debug Control (DR7) register to the value @var{val}.

871

872

@findex I386_DR_LOW_SET_ADDR

873

@item I386_DR_LOW_SET_ADDR (@var{idx}, @var{addr})

874

Put the address @var{addr} into the debug register number @var{idx}.

875

876

@findex I386_DR_LOW_RESET_ADDR

877

@item I386_DR_LOW_RESET_ADDR (@var{idx})

878

Reset (i.e.@: zero out) the address stored in the debug register

879

number @var{idx}.

880

881

@findex I386_DR_LOW_GET_STATUS

882

@item I386_DR_LOW_GET_STATUS

883

Return the value of the Debug Status (DR6) register. This value is

884

used immediately after it is returned by

885

@code{I386_DR_LOW_GET_STATUS}, so as to support per-thread status

886

register values.

887

@end table

888

889

For each one of the 4 debug registers (whose indices are from 0 to 3)

890

that store addresses, a reference count is maintained by @value{GDBN},

891

to allow sharing of debug registers by several watchpoints. This

892

allows users to define several watchpoints that watch the same

893

expression, but with different conditions and/or commands, without

894

wasting debug registers which are in short supply. @value{GDBN}

895

maintains the reference counts internally, targets don't have to do

896

anything to use this feature.

897

898

The x86 debug registers can each watch a region that is 1, 2, or 4

899

bytes long. The ia32 architecture requires that each watched region

900

be appropriately aligned: 2-byte region on 2-byte boundary, 4-byte

901

region on 4-byte boundary. However, the x86 watchpoint support in

902

@value{GDBN} can watch unaligned regions and regions larger than 4

903

bytes (up to 16 bytes) by allocating several debug registers to watch

904

a single region. This allocation of several registers per a watched

905

region is also done automatically without target code intervention.

906

907

The generic x86 watchpoint support provides the following API for the

908

@value{GDBN}'s application code:

909

910

@table @code

911

@findex i386_region_ok_for_watchpoint

912

@item i386_region_ok_for_watchpoint (@var{addr}, @var{len})

913

The macro @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is set to call

914

this function. It counts the number of debug registers required to

915

watch a given region, and returns a non-zero value if that number is

916

less than 4, the number of debug registers available to x86

917

processors.

918

919

@findex i386_stopped_data_address

920

@item i386_stopped_data_address (@var{addr_p})

921

The target function

922

@code{target_stopped_data_address} is set to call this function.

923

This

924

function examines the breakpoint condition bits in the DR6 Debug

925

Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}

926

macro, and returns the address associated with the first bit that is

927

set in DR6.

928

929

@findex i386_stopped_by_watchpoint

930

@item i386_stopped_by_watchpoint (void)

931

The macro @code{STOPPED_BY_WATCHPOINT}

932

is set to call this function. The

933

argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This

934

function examines the breakpoint condition bits in the DR6 Debug

935

Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}

936

macro, and returns true if any bit is set. Otherwise, false is

937

returned.

938

939

@findex i386_insert_watchpoint

940

@findex i386_remove_watchpoint

941

@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})

942

@itemx i386_remove_watchpoint (@var{addr}, @var{len}, @var{type})

943

Insert or remove a watchpoint. The macros

944

@code{target_insert_watchpoint} and @code{target_remove_watchpoint}

945

are set to call these functions. @code{i386_insert_watchpoint} first

946

looks for a debug register which is already set to watch the same

947

region for the same access types; if found, it just increments the

948

reference count of that debug register, thus implementing debug

949

register sharing between watchpoints. If no such register is found,

950

the function looks for a vacant debug register, sets its mirrored

951

value to @var{addr}, sets the mirrored value of DR7 Debug Control

952

register as appropriate for the @var{len} and @var{type} parameters,

953

and then passes the new values of the debug register and DR7 to the

954

inferior by calling @code{I386_DR_LOW_SET_ADDR} and

955

@code{I386_DR_LOW_SET_CONTROL}. If more than one debug register is

956

required to cover the given region, the above process is repeated for

957

each debug register.

958

959

@code{i386_remove_watchpoint} does the opposite: it resets the address

960

in the mirrored value of the debug register and its read/write and

961

length bits in the mirrored value of DR7, then passes these new

962

values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and

963

@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several

964

watchpoints, each time a @code{i386_remove_watchpoint} is called, it

965

decrements the reference count, and only calls

966

@code{I386_DR_LOW_RESET_ADDR} and @code{I386_DR_LOW_SET_CONTROL} when

967

the count goes to zero.

968

969

@findex i386_insert_hw_breakpoint

970

@findex i386_remove_hw_breakpoint

971

@item i386_insert_hw_breakpoint (@var{bp_tgt})

972

@itemx i386_remove_hw_breakpoint (@var{bp_tgt})

973

These functions insert and remove hardware-assisted breakpoints. The

974

macros @code{target_insert_hw_breakpoint} and

975

@code{target_remove_hw_breakpoint} are set to call these functions.

976

The argument is a @code{struct bp_target_info *}, as described in

977

the documentation for @code{target_insert_breakpoint}.

978

These functions work like @code{i386_insert_watchpoint} and

979

@code{i386_remove_watchpoint}, respectively, except that they set up

980

the debug registers to watch instruction execution, and each

981

hardware-assisted breakpoint always requires exactly one debug

982

register.

983

984

@findex i386_cleanup_dregs

985

@item i386_cleanup_dregs (void)

986

This function clears all the reference counts, addresses, and control

987

bits in the mirror images of the debug registers. It doesn't affect

988

the actual debug registers in the inferior process.

989

@end table

990

991

@noindent

992

@strong{Notes:}

993

@enumerate 1

994

@item

995

x86 processors support setting watchpoints on I/O reads or writes.

996

However, since no target supports this (as of March 2001), and since

997

@code{enum target_hw_bp_type} doesn't even have an enumeration for I/O

998

watchpoints, this feature is not yet available to @value{GDBN} running

999

on x86.

1000

1001

@item

1002

x86 processors can enable watchpoints locally, for the current task

1003

only, or globally, for all the tasks. For each debug register,

1004

there's a bit in the DR7 Debug Control register that determines

1005

whether the associated address is watched locally or globally. The

1006

current implementation of x86 watchpoint support in @value{GDBN}

1007

always sets watchpoints to be locally enabled, since global

1008

watchpoints might interfere with the underlying OS and are probably

1009

unavailable in many platforms.

1010

@end enumerate

1011

1012

@section Checkpoints

1013

@cindex checkpoints

1014

@cindex restart

1015

In the abstract, a checkpoint is a point in the execution history of

1016

the program, which the user may wish to return to at some later time.

1017

1018

Internally, a checkpoint is a saved copy of the program state, including

1019

whatever information is required in order to restore the program to that

1020

state at a later time. This can be expected to include the state of

1021

registers and memory, and may include external state such as the state

1022

of open files and devices.

1023

1024

There are a number of ways in which checkpoints may be implemented

1025

in gdb, e.g.@: as corefiles, as forked processes, and as some opaque

1026

method implemented on the target side.

1027

1028

A corefile can be used to save an image of target memory and register

1029

state, which can in principle be restored later --- but corefiles do

1030

not typically include information about external entities such as

1031

open files. Currently this method is not implemented in gdb.

1032

1033

A forked process can save the state of user memory and registers,

1034

as well as some subset of external (kernel) state. This method

1035

is used to implement checkpoints on Linux, and in principle might

1036

be used on other systems.

1037

1038

Some targets, e.g.@: simulators, might have their own built-in

1039

method for saving checkpoints, and gdb might be able to take

1040

advantage of that capability without necessarily knowing any

1041

details of how it is done.

1042

1043

1044

@section Observing changes in @value{GDBN} internals

1045

@cindex observer pattern interface

1046

@cindex notifications about changes in internals

1047

1048

In order to function properly, several modules need to be notified when

1049

some changes occur in the @value{GDBN} internals. Traditionally, these

1050

modules have relied on several paradigms, the most common ones being

1051

hooks and gdb-events. Unfortunately, none of these paradigms was

1052

versatile enough to become the standard notification mechanism in

1053

@value{GDBN}. The fact that they only supported one ``client'' was also

1054

a strong limitation.

1055

1056

A new paradigm, based on the Observer pattern of the @cite{Design

1057

Patterns} book, has therefore been implemented. The goal was to provide

1058

a new interface overcoming the issues with the notification mechanisms

1059

previously available. This new interface needed to be strongly typed,

1060

easy to extend, and versatile enough to be used as the standard

1061

interface when adding new notifications.

1062

1063

See @ref{GDB Observers} for a brief description of the observers

1064

currently implemented in GDB. The rationale for the current

1065

implementation is also briefly discussed.

1066

1067

@node User Interface

1068

1069

@chapter User Interface

1070

1071

@value{GDBN} has several user interfaces, of which the traditional

1072

command-line interface is perhaps the most familiar.

1073

1074

@section Command Interpreter

1075

1076

@cindex command interpreter

1077

@cindex CLI

1078

The command interpreter in @value{GDBN} is fairly simple. It is designed to

1079

allow for the set of commands to be augmented dynamically, and also

1080

has a recursive subcommand capability, where the first argument to

1081

a command may itself direct a lookup on a different command list.

1082

1083

For instance, the @samp{set} command just starts a lookup on the

1084

@code{setlist} command list, while @samp{set thread} recurses

1085

to the @code{set_thread_cmd_list}.

1086

1087

@findex add_cmd

1088

@findex add_com

1089

To add commands in general, use @code{add_cmd}. @code{add_com} adds to

1090

the main command list, and should be used for those commands. The usual

1091

place to add commands is in the @code{_initialize_@var{xyz}} routines at

1092

the ends of most source files.

1093

1094

@findex add_setshow_cmd

1095

@findex add_setshow_cmd_full

1096

To add paired @samp{set} and @samp{show} commands, use

1097

@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is

1098

a slightly simpler interface which is useful when you don't need to

1099

further modify the new command structures, while the latter returns

1100

the new command structures for manipulation.

1101

1102

@cindex deprecating commands

1103

@findex deprecate_cmd

1104

Before removing commands from the command set it is a good idea to

1105

deprecate them for some time. Use @code{deprecate_cmd} on commands or

1106

aliases to set the deprecated flag. @code{deprecate_cmd} takes a

1107

@code{struct cmd_list_element} as it's first argument. You can use the

1108

return value from @code{add_com} or @code{add_cmd} to deprecate the

1109

command immediately after it is created.

1110

1111

The first time a command is used the user will be warned and offered a

1112

replacement (if one exists). Note that the replacement string passed to

1113

@code{deprecate_cmd} should be the full name of the command, i.e., the

1114

entire string the user should type at the command line.

1115

1116

@anchor{UI-Independent Output}

1117

@section UI-Independent Output---the @code{ui_out} Functions

1118

@c This section is based on the documentation written by Fernando

1119

@c Nasser <fnasser@redhat.com>.

1120

1121

@cindex @code{ui_out} functions

1122

The @code{ui_out} functions present an abstraction level for the

1123

@value{GDBN} output code. They hide the specifics of different user

1124

interfaces supported by @value{GDBN}, and thus free the programmer

1125

from the need to write several versions of the same code, one each for

1126

every UI, to produce output.

1127

1128

@subsection Overview and Terminology

1129

1130

In general, execution of each @value{GDBN} command produces some sort

1131

of output, and can even generate an input request.

1132

1133

Output can be generated for the following purposes:

1134

1135

@itemize @bullet

1136

@item

1137

to display a @emph{result} of an operation;

1138

1139

@item

1140

to convey @emph{info} or produce side-effects of a requested

1141

operation;

1142

1143

@item

1144

to provide a @emph{notification} of an asynchronous event (including

1145

progress indication of a prolonged asynchronous operation);

1146

1147

@item

1148

to display @emph{error messages} (including warnings);

1149

1150

@item

1151

to show @emph{debug data};

1152

1153

@item

1154

to @emph{query} or prompt a user for input (a special case).

1155

@end itemize

1156

1157

@noindent

1158

This section mainly concentrates on how to build result output,

1159

although some of it also applies to other kinds of output.

1160

1161

Generation of output that displays the results of an operation

1162

involves one or more of the following:

1163

1164

@itemize @bullet

1165

@item

1166

output of the actual data

1167

1168

@item

1169

formatting the output as appropriate for console output, to make it

1170

easily readable by humans

1171

1172

@item

1173

machine oriented formatting--a more terse formatting to allow for easy

1174

parsing by programs which read @value{GDBN}'s output

1175

1176

@item

1177

annotation, whose purpose is to help legacy GUIs to identify interesting

1178

parts in the output

1179

@end itemize

1180

1181

The @code{ui_out} routines take care of the first three aspects.

1182

Annotations are provided by separate annotation routines. Note that use

1183

of annotations for an interface between a GUI and @value{GDBN} is

1184

deprecated.

1185

1186

Output can be in the form of a single item, which we call a @dfn{field};

1187

a @dfn{list} consisting of identical fields; a @dfn{tuple} consisting of

1188

non-identical fields; or a @dfn{table}, which is a tuple consisting of a

1189

header and a body. In a BNF-like form:

1190

1191

@table @code

1192

@item <table> @expansion{}

1193

@code{<header> <body>}

1194

@item <header> @expansion{}

1195

@code{@{ <column> @}}

1196

@item <column> @expansion{}

1197

@code{<width> <alignment> <title>}

1198

@item <body> @expansion{}

1199

@code{@{<row>@}}

1200

@end table

1201

1202

1203

@subsection General Conventions

1204

1205

Most @code{ui_out} routines are of type @code{void}, the exceptions are

1206

@code{ui_out_stream_new} (which returns a pointer to the newly created

1207

object) and the @code{make_cleanup} routines.

1208

1209

The first parameter is always the @code{ui_out} vector object, a pointer

1210

to a @code{struct ui_out}.

1211

1212

The @var{format} parameter is like in @code{printf} family of functions.

1213

When it is present, there must also be a variable list of arguments

1214

sufficient used to satisfy the @code{%} specifiers in the supplied

1215

format.

1216

1217

When a character string argument is not used in a @code{ui_out} function

1218

call, a @code{NULL} pointer has to be supplied instead.

1219

1220

1221

@subsection Table, Tuple and List Functions

1222

1223

@cindex list output functions

1224

@cindex table output functions

1225

@cindex tuple output functions

1226

This section introduces @code{ui_out} routines for building lists,

1227

tuples and tables. The routines to output the actual data items

1228

(fields) are presented in the next section.

1229

1230

To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field

1231

containing information about an object; a @dfn{list} is a sequence of

1232

fields where each field describes an identical object.

1233

1234

Use the @dfn{table} functions when your output consists of a list of

1235

rows (tuples) and the console output should include a heading. Use this

1236

even when you are listing just one object but you still want the header.

1237

1238

@cindex nesting level in @code{ui_out} functions

1239

Tables can not be nested. Tuples and lists can be nested up to a

1240

maximum of five levels.

1241

1242

The overall structure of the table output code is something like this:

1243

1244

@smallexample

1245

ui_out_table_begin

1246

ui_out_table_header

1247

@dots{}

1248

ui_out_table_body

1249

ui_out_tuple_begin

1250

ui_out_field_*

1251

@dots{}

1252

ui_out_tuple_end

1253

@dots{}

1254

ui_out_table_end

1255

@end smallexample

1256

1257

Here is the description of table-, tuple- and list-related @code{ui_out}

1258

functions:

1259

1260

@deftypefun void ui_out_table_begin (struct ui_out *@var{uiout}, int @var{nbrofcols}, int @var{nr_rows}, const char *@var{tblid})

1261

The function @code{ui_out_table_begin} marks the beginning of the output

1262

of a table. It should always be called before any other @code{ui_out}

1263

function for a given table. @var{nbrofcols} is the number of columns in

1264

the table. @var{nr_rows} is the number of rows in the table.

1265

@var{tblid} is an optional string identifying the table. The string

1266

pointed to by @var{tblid} is copied by the implementation of

1267

@code{ui_out_table_begin}, so the application can free the string if it

1268

was @code{malloc}ed.

1269

1270

The companion function @code{ui_out_table_end}, described below, marks

1271

the end of the table's output.

1272

@end deftypefun

1273

1274

@deftypefun void ui_out_table_header (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{colhdr})

1275

@code{ui_out_table_header} provides the header information for a single

1276

table column. You call this function several times, one each for every

1277

column of the table, after @code{ui_out_table_begin}, but before

1278

@code{ui_out_table_body}.

1279

1280

The value of @var{width} gives the column width in characters. The

1281

value of @var{alignment} is one of @code{left}, @code{center}, and

1282

@code{right}, and it specifies how to align the header: left-justify,

1283

center, or right-justify it. @var{colhdr} points to a string that

1284

specifies the column header; the implementation copies that string, so

1285

column header strings in @code{malloc}ed storage can be freed after the

1286

call.

1287

@end deftypefun

1288

1289

@deftypefun void ui_out_table_body (struct ui_out *@var{uiout})

1290

This function delimits the table header from the table body.

1291

@end deftypefun

1292

1293

@deftypefun void ui_out_table_end (struct ui_out *@var{uiout})

1294

This function signals the end of a table's output. It should be called

1295

after the table body has been produced by the list and field output

1296

functions.

1297

1298

There should be exactly one call to @code{ui_out_table_end} for each

1299

call to @code{ui_out_table_begin}, otherwise the @code{ui_out} functions

1300

will signal an internal error.

1301

@end deftypefun

1302

1303

The output of the tuples that represent the table rows must follow the

1304

call to @code{ui_out_table_body} and precede the call to

1305

@code{ui_out_table_end}. You build a tuple by calling

1306

@code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable

1307

calls to functions which actually output fields between them.

1308

1309

@deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{id})

1310

This function marks the beginning of a tuple output. @var{id} points

1311

to an optional string that identifies the tuple; it is copied by the

1312

implementation, and so strings in @code{malloc}ed storage can be freed

1313

after the call.

1314

@end deftypefun

1315

1316

@deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})

1317

This function signals an end of a tuple output. There should be exactly

1318

one call to @code{ui_out_tuple_end} for each call to

1319

@code{ui_out_tuple_begin}, otherwise an internal @value{GDBN} error will

1320

be signaled.

1321

@end deftypefun

1322

1323

@deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})

1324

This function first opens the tuple and then establishes a cleanup

1325

(@pxref{Misc Guidelines, Cleanups}) to close the tuple.

1326

It provides a convenient and correct implementation of the

1327

non-portable@footnote{The function cast is not portable ISO C.} code sequence:

1328

@smallexample

1329

struct cleanup *old_cleanup;

1330

ui_out_tuple_begin (uiout, "...");

1331

old_cleanup = make_cleanup ((void(*)(void *)) ui_out_tuple_end,

1332

uiout);

1333

@end smallexample

1334

@end deftypefun

1335

1336

@deftypefun void ui_out_list_begin (struct ui_out *@var{uiout}, const char *@var{id})

1337

This function marks the beginning of a list output. @var{id} points to

1338

an optional string that identifies the list; it is copied by the

1339

implementation, and so strings in @code{malloc}ed storage can be freed

1340

after the call.

1341

@end deftypefun

1342

1343

@deftypefun void ui_out_list_end (struct ui_out *@var{uiout})

1344

This function signals an end of a list output. There should be exactly

1345

one call to @code{ui_out_list_end} for each call to

1346

@code{ui_out_list_begin}, otherwise an internal @value{GDBN} error will

1347

be signaled.

1348

@end deftypefun

1349

1350

@deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})

1351

Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function

1352

opens a list and then establishes cleanup

1353

(@pxref{Misc Guidelines, Cleanups})

1354

that will close the list.

1355

@end deftypefun

1356

1357

@subsection Item Output Functions

1358

1359

@cindex item output functions

1360

@cindex field output functions

1361

@cindex data output

1362

The functions described below produce output for the actual data

1363

items, or fields, which contain information about the object.

1364

1365

Choose the appropriate function accordingly to your particular needs.

1366

1367

@deftypefun void ui_out_field_fmt (struct ui_out *@var{uiout}, char *@var{fldname}, char *@var{format}, ...)

1368

This is the most general output function. It produces the

1369

representation of the data in the variable-length argument list

1370

according to formatting specifications in @var{format}, a

1371

@code{printf}-like format string. The optional argument @var{fldname}

1372

supplies the name of the field. The data items themselves are

1373

supplied as additional arguments after @var{format}.

1374

1375

This generic function should be used only when it is not possible to

1376

use one of the specialized versions (see below).

1377

@end deftypefun

1378

1379

@deftypefun void ui_out_field_int (struct ui_out *@var{uiout}, const char *@var{fldname}, int @var{value})

1380

This function outputs a value of an @code{int} variable. It uses the

1381

@code{"%d"} output conversion specification. @var{fldname} specifies

1382

the name of the field.

1383

@end deftypefun

1384

1385

@deftypefun void ui_out_field_fmt_int (struct ui_out *@var{uiout}, int @var{width}, enum ui_align @var{alignment}, const char *@var{fldname}, int @var{value})

1386

This function outputs a value of an @code{int} variable. It differs from

1387

@code{ui_out_field_int} in that the caller specifies the desired @var{width} and @var{alignment} of the output.

1388

@var{fldname} specifies

1389

the name of the field.

1390

@end deftypefun

1391

1392

@deftypefun void ui_out_field_core_addr (struct ui_out *@var{uiout}, const char *@var{fldname}, struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address})

1393

This function outputs an address as appropriate for @var{gdbarch}.

1394

@end deftypefun

1395

1396

@deftypefun void ui_out_field_string (struct ui_out *@var{uiout}, const char *@var{fldname}, const char *@var{string})

1397

This function outputs a string using the @code{"%s"} conversion

1398

specification.

1399

@end deftypefun

1400

1401

Sometimes, there's a need to compose your output piece by piece using

1402

functions that operate on a stream, such as @code{value_print} or

1403

@code{fprintf_symbol_filtered}. These functions accept an argument of

1404

the type @code{struct ui_file *}, a pointer to a @code{ui_file} object

1405

used to store the data stream used for the output. When you use one

1406

of these functions, you need a way to pass their results stored in a

1407

@code{ui_file} object to the @code{ui_out} functions. To this end,

1408

you first create a @code{ui_stream} object by calling

1409

@code{ui_out_stream_new}, pass the @code{stream} member of that

1410

@code{ui_stream} object to @code{value_print} and similar functions,

1411

and finally call @code{ui_out_field_stream} to output the field you

1412

constructed. When the @code{ui_stream} object is no longer needed,

1413

you should destroy it and free its memory by calling

1414

@code{ui_out_stream_delete}.

1415

1416

@deftypefun {struct ui_stream *} ui_out_stream_new (struct ui_out *@var{uiout})

1417

This function creates a new @code{ui_stream} object which uses the

1418

same output methods as the @code{ui_out} object whose pointer is

1419

passed in @var{uiout}. It returns a pointer to the newly created

1420

@code{ui_stream} object.

1421

@end deftypefun

1422

1423

@deftypefun void ui_out_stream_delete (struct ui_stream *@var{streambuf})

1424

This functions destroys a @code{ui_stream} object specified by

1425

@var{streambuf}.

1426

@end deftypefun

1427

1428

@deftypefun void ui_out_field_stream (struct ui_out *@var{uiout}, const char *@var{fieldname}, struct ui_stream *@var{streambuf})

1429

This function consumes all the data accumulated in

1430

@code{streambuf->stream} and outputs it like

1431

@code{ui_out_field_string} does. After a call to

1432

@code{ui_out_field_stream}, the accumulated data no longer exists, but

1433

the stream is still valid and may be used for producing more fields.

1434

@end deftypefun

1435

1436

@strong{Important:} If there is any chance that your code could bail

1437

out before completing output generation and reaching the point where

1438

@code{ui_out_stream_delete} is called, it is necessary to set up a

1439

cleanup, to avoid leaking memory and other resources. Here's a

1440

skeleton code to do that:

1441

1442

@smallexample

1443

struct ui_stream *mybuf = ui_out_stream_new (uiout);

1444

struct cleanup *old = make_cleanup (ui_out_stream_delete, mybuf);

1445

...

1446

do_cleanups (old);

1447

@end smallexample

1448

1449

If the function already has the old cleanup chain set (for other kinds

1450

of cleanups), you just have to add your cleanup to it:

1451

1452

@smallexample

1453

mybuf = ui_out_stream_new (uiout);

1454

make_cleanup (ui_out_stream_delete, mybuf);

1455

@end smallexample

1456

1457

Note that with cleanups in place, you should not call

1458

@code{ui_out_stream_delete} directly, or you would attempt to free the

1459

same buffer twice.

1460

1461

@subsection Utility Output Functions

1462

1463

@deftypefun void ui_out_field_skip (struct ui_out *@var{uiout}, const char *@var{fldname})

1464

This function skips a field in a table. Use it if you have to leave

1465

an empty field without disrupting the table alignment. The argument

1466

@var{fldname} specifies a name for the (missing) filed.

1467

@end deftypefun

1468

1469

@deftypefun void ui_out_text (struct ui_out *@var{uiout}, const char *@var{string})

1470

This function outputs the text in @var{string} in a way that makes it

1471

easy to be read by humans. For example, the console implementation of

1472

this method filters the text through a built-in pager, to prevent it

1473

from scrolling off the visible portion of the screen.

1474

1475

Use this function for printing relatively long chunks of text around

1476

the actual field data: the text it produces is not aligned according

1477

to the table's format. Use @code{ui_out_field_string} to output a

1478

string field, and use @code{ui_out_message}, described below, to

1479

output short messages.

1480

@end deftypefun

1481

1482

@deftypefun void ui_out_spaces (struct ui_out *@var{uiout}, int @var{nspaces})

1483

This function outputs @var{nspaces} spaces. It is handy to align the

1484

text produced by @code{ui_out_text} with the rest of the table or

1485

list.

1486

@end deftypefun

1487

1488

@deftypefun void ui_out_message (struct ui_out *@var{uiout}, int @var{verbosity}, const char *@var{format}, ...)

1489

This function produces a formatted message, provided that the current

1490

verbosity level is at least as large as given by @var{verbosity}. The

1491

current verbosity level is specified by the user with the @samp{set

1492

verbositylevel} command.@footnote{As of this writing (April 2001),

1493

setting verbosity level is not yet implemented, and is always returned

1494

as zero. So calling @code{ui_out_message} with a @var{verbosity}

1495

argument more than zero will cause the message to never be printed.}

1496

@end deftypefun

1497

1498

@deftypefun void ui_out_wrap_hint (struct ui_out *@var{uiout}, char *@var{indent})

1499

This function gives the console output filter (a paging filter) a hint

1500

of where to break lines which are too long. Ignored for all other

1501

output consumers. @var{indent}, if non-@code{NULL}, is the string to

1502

be printed to indent the wrapped text on the next line; it must remain

1503

accessible until the next call to @code{ui_out_wrap_hint}, or until an

1504

explicit newline is produced by one of the other functions. If

1505

@var{indent} is @code{NULL}, the wrapped text will not be indented.

1506

@end deftypefun

1507

1508

@deftypefun void ui_out_flush (struct ui_out *@var{uiout})

1509

This function flushes whatever output has been accumulated so far, if

1510

the UI buffers output.

1511

@end deftypefun

1512

1513

1514

@subsection Examples of Use of @code{ui_out} functions

1515

1516

@cindex using @code{ui_out} functions

1517

@cindex @code{ui_out} functions, usage examples

1518

This section gives some practical examples of using the @code{ui_out}

1519

functions to generalize the old console-oriented code in

1520

@value{GDBN}. The examples all come from functions defined on the

1521

@file{breakpoints.c} file.

1522

1523

This example, from the @code{breakpoint_1} function, shows how to

1524

produce a table.

1525

1526

The original code was:

1527

1528

@smallexample

1529

if (!found_a_breakpoint++)

1530

@{

1531

annotate_breakpoints_headers ();

1532

1533

annotate_field (0);

1534

printf_filtered ("Num ");

1535

annotate_field (1);

1536

printf_filtered ("Type ");

1537

annotate_field (2);

1538

printf_filtered ("Disp ");

1539

annotate_field (3);

1540

printf_filtered ("Enb ");

1541

if (addressprint)

1542

@{

1543

annotate_field (4);

1544

printf_filtered ("Address ");

1545

@}

1546

annotate_field (5);

1547

printf_filtered ("What\n");

1548

1549

annotate_breakpoints_table ();

1550

@}

1551

@end smallexample

1552

1553

Here's the new version:

1554

1555

@smallexample

1556

nr_printable_breakpoints = @dots{};

1557

1558

if (addressprint)

1559

ui_out_table_begin (ui, 6, nr_printable_breakpoints, "BreakpointTable");

1560

else

1561

ui_out_table_begin (ui, 5, nr_printable_breakpoints, "BreakpointTable");

1562

1563

if (nr_printable_breakpoints > 0)

1564

annotate_breakpoints_headers ();

1565

if (nr_printable_breakpoints > 0)

1566

annotate_field (0);

1567

ui_out_table_header (uiout, 3, ui_left, "number", "Num"); /* 1 */

1568

if (nr_printable_breakpoints > 0)

1569

annotate_field (1);

1570

ui_out_table_header (uiout, 14, ui_left, "type", "Type"); /* 2 */

1571

if (nr_printable_breakpoints > 0)

1572

annotate_field (2);

1573

ui_out_table_header (uiout, 4, ui_left, "disp", "Disp"); /* 3 */

1574

if (nr_printable_breakpoints > 0)

1575

annotate_field (3);

1576

ui_out_table_header (uiout, 3, ui_left, "enabled", "Enb"); /* 4 */

1577

if (addressprint)

1578

@{

1579

if (nr_printable_breakpoints > 0)

1580

annotate_field (4);

1581

if (print_address_bits <= 32)

1582

ui_out_table_header (uiout, 10, ui_left, "addr", "Address");/* 5 */

1583

else

1584

ui_out_table_header (uiout, 18, ui_left, "addr", "Address");/* 5 */

1585

@}

1586

if (nr_printable_breakpoints > 0)

1587

annotate_field (5);

1588

ui_out_table_header (uiout, 40, ui_noalign, "what", "What"); /* 6 */

1589

ui_out_table_body (uiout);

1590

if (nr_printable_breakpoints > 0)

1591

annotate_breakpoints_table ();

1592

@end smallexample

1593

1594

This example, from the @code{print_one_breakpoint} function, shows how

1595

to produce the actual data for the table whose structure was defined

1596

in the above example. The original code was:

1597

1598

@smallexample

1599

annotate_record ();

1600

annotate_field (0);

1601

printf_filtered ("%-3d ", b->number);

1602

annotate_field (1);

1603

if ((int)b->type > (sizeof(bptypes)/sizeof(bptypes[0]))

1604

|| ((int) b->type != bptypes[(int) b->type].type))

1605

internal_error ("bptypes table does not describe type #%d.",

1606

(int)b->type);

1607

printf_filtered ("%-14s ", bptypes[(int)b->type].description);

1608

annotate_field (2);

1609

printf_filtered ("%-4s ", bpdisps[(int)b->disposition]);

1610

annotate_field (3);

1611

printf_filtered ("%-3c ", bpenables[(int)b->enable]);

1612

@dots{}

1613

@end smallexample

1614

1615

This is the new version:

1616

1617

@smallexample

1618

annotate_record ();

1619

ui_out_tuple_begin (uiout, "bkpt");

1620

annotate_field (0);

1621

ui_out_field_int (uiout, "number", b->number);

1622

annotate_field (1);

1623

if (((int) b->type > (sizeof (bptypes) / sizeof (bptypes[0])))

1624

|| ((int) b->type != bptypes[(int) b->type].type))

1625

internal_error ("bptypes table does not describe type #%d.",

1626

(int) b->type);

1627

ui_out_field_string (uiout, "type", bptypes[(int)b->type].description);

1628

annotate_field (2);

1629

ui_out_field_string (uiout, "disp", bpdisps[(int)b->disposition]);

1630

annotate_field (3);

1631

ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);

1632

@dots{}

1633

@end smallexample

1634

1635

This example, also from @code{print_one_breakpoint}, shows how to

1636

produce a complicated output field using the @code{print_expression}

1637

functions which requires a stream to be passed. It also shows how to

1638

automate stream destruction with cleanups. The original code was:

1639

1640

@smallexample

1641

annotate_field (5);

1642

print_expression (b->exp, gdb_stdout);

1643

@end smallexample

1644

1645

The new version is:

1646

1647

@smallexample

1648

struct ui_stream *stb = ui_out_stream_new (uiout);

1649

struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);

1650

...

1651

annotate_field (5);

1652

print_expression (b->exp, stb->stream);

1653

ui_out_field_stream (uiout, "what", local_stream);

1654

@end smallexample

1655

1656

This example, also from @code{print_one_breakpoint}, shows how to use

1657

@code{ui_out_text} and @code{ui_out_field_string}. The original code

1658

was:

1659

1660

@smallexample

1661

annotate_field (5);

1662

if (b->dll_pathname == NULL)

1663

printf_filtered ("<any library> ");

1664

else

1665

printf_filtered ("library \"%s\" ", b->dll_pathname);

1666

@end smallexample

1667

1668

It became:

1669

1670

@smallexample

1671

annotate_field (5);

1672

if (b->dll_pathname == NULL)

1673

@{

1674

ui_out_field_string (uiout, "what", "<any library>");

1675

ui_out_spaces (uiout, 1);

1676

@}

1677

else

1678

@{

1679

ui_out_text (uiout, "library \"");

1680

ui_out_field_string (uiout, "what", b->dll_pathname);

1681

ui_out_text (uiout, "\" ");

1682

@}

1683

@end smallexample

1684

1685

The following example from @code{print_one_breakpoint} shows how to

1686

use @code{ui_out_field_int} and @code{ui_out_spaces}. The original

1687

code was:

1688

1689

@smallexample

1690

annotate_field (5);

1691

if (b->forked_inferior_pid != 0)

1692

printf_filtered ("process %d ", b->forked_inferior_pid);

1693

@end smallexample

1694

1695

It became:

1696

1697

@smallexample

1698

annotate_field (5);

1699

if (b->forked_inferior_pid != 0)

1700

@{

1701

ui_out_text (uiout, "process ");

1702

ui_out_field_int (uiout, "what", b->forked_inferior_pid);

1703

ui_out_spaces (uiout, 1);

1704

@}

1705

@end smallexample

1706

1707

Here's an example of using @code{ui_out_field_string}. The original

1708

code was:

1709

1710

@smallexample

1711

annotate_field (5);

1712

if (b->exec_pathname != NULL)

1713

printf_filtered ("program \"%s\" ", b->exec_pathname);

1714

@end smallexample

1715

1716

It became:

1717

1718

@smallexample

1719

annotate_field (5);

1720

if (b->exec_pathname != NULL)

1721

@{

1722

ui_out_text (uiout, "program \"");

1723

ui_out_field_string (uiout, "what", b->exec_pathname);

1724

ui_out_text (uiout, "\" ");

1725

@}

1726

@end smallexample

1727

1728

Finally, here's an example of printing an address. The original code:

1729

1730

@smallexample

1731

annotate_field (4);

1732

printf_filtered ("%s ",

1733

hex_string_custom ((unsigned long) b->address, 8));

1734

@end smallexample

1735

1736

It became:

1737

1738

@smallexample

1739

annotate_field (4);

1740

ui_out_field_core_addr (uiout, "Address", b->address);

1741

@end smallexample

1742

1743

1744

@section Console Printing

1745

1746

@section TUI

1747

1748

@node libgdb

1749

1750

@chapter libgdb

1751

1752

@section libgdb 1.0

1753

@cindex @code{libgdb}

1754

@code{libgdb} 1.0 was an abortive project of years ago. The theory was

1755

to provide an API to @value{GDBN}'s functionality.

1756

1757

@section libgdb 2.0

1758

@cindex @code{libgdb}

1759

@code{libgdb} 2.0 is an ongoing effort to update @value{GDBN} so that is

1760

better able to support graphical and other environments.

1761

1762

Since @code{libgdb} development is on-going, its architecture is still

1763

evolving. The following components have so far been identified:

1764

1765

@itemize @bullet

1766

@item

1767

Observer - @file{gdb-events.h}.

1768

@item

1769

Builder - @file{ui-out.h}

1770

@item

1771

Event Loop - @file{event-loop.h}

1772

@item

1773

Library - @file{gdb.h}

1774

@end itemize

1775

1776

The model that ties these components together is described below.

1777

1778

@section The @code{libgdb} Model

1779

1780

A client of @code{libgdb} interacts with the library in two ways.

1781

1782

@itemize @bullet

1783

@item

1784

As an observer (using @file{gdb-events}) receiving notifications from

1785

@code{libgdb} of any internal state changes (break point changes, run

1786

state, etc).

1787

@item

1788

As a client querying @code{libgdb} (using the @file{ui-out} builder) to

1789

obtain various status values from @value{GDBN}.

1790

@end itemize

1791

1792

Since @code{libgdb} could have multiple clients (e.g., a GUI supporting

1793

the existing @value{GDBN} CLI), those clients must co-operate when

1794

controlling @code{libgdb}. In particular, a client must ensure that

1795

@code{libgdb} is idle (i.e.@: no other client is using @code{libgdb})

1796

before responding to a @file{gdb-event} by making a query.

1797

1798

@section CLI support

1799

1800

At present @value{GDBN}'s CLI is very much entangled in with the core of

1801

@code{libgdb}. Consequently, a client wishing to include the CLI in

1802

their interface needs to carefully co-ordinate its own and the CLI's

1803

requirements.

1804

1805

It is suggested that the client set @code{libgdb} up to be bi-modal

1806

(alternate between CLI and client query modes). The notes below sketch

1807

out the theory:

1808

1809

@itemize @bullet

1810

@item

1811

The client registers itself as an observer of @code{libgdb}.

1812

@item

1813

The client create and install @code{cli-out} builder using its own

1814

versions of the @code{ui-file} @code{gdb_stderr}, @code{gdb_stdtarg} and

1815

@code{gdb_stdout} streams.

1816

@item

1817

The client creates a separate custom @code{ui-out} builder that is only

1818

used while making direct queries to @code{libgdb}.

1819

@end itemize

1820

1821

When the client receives input intended for the CLI, it simply passes it

1822

along. Since the @code{cli-out} builder is installed by default, all

1823

the CLI output in response to that command is routed (pronounced rooted)

1824

through to the client controlled @code{gdb_stdout} et.@: al.@: streams.

1825

At the same time, the client is kept abreast of internal changes by

1826

virtue of being a @code{libgdb} observer.

1827

1828

The only restriction on the client is that it must wait until

1829

@code{libgdb} becomes idle before initiating any queries (using the

1830

client's custom builder).

1831

1832

@section @code{libgdb} components

1833

1834

@subheading Observer - @file{gdb-events.h}

1835

@file{gdb-events} provides the client with a very raw mechanism that can

1836

be used to implement an observer. At present it only allows for one

1837

observer and that observer must, internally, handle the need to delay

1838

the processing of any event notifications until after @code{libgdb} has

1839

finished the current command.

1840

1841

@subheading Builder - @file{ui-out.h}

1842

@file{ui-out} provides the infrastructure necessary for a client to

1843

create a builder. That builder is then passed down to @code{libgdb}

1844

when doing any queries.

1845

1846

@subheading Event Loop - @file{event-loop.h}

1847

@c There could be an entire section on the event-loop

1848

@file{event-loop}, currently non-re-entrant, provides a simple event

1849

loop. A client would need to either plug its self into this loop or,

1850

implement a new event-loop that @value{GDBN} would use.

1851

1852

The event-loop will eventually be made re-entrant. This is so that

1853

@value{GDBN} can better handle the problem of some commands blocking

1854

instead of returning.

1855

1856

@subheading Library - @file{gdb.h}

1857

@file{libgdb} is the most obvious component of this system. It provides

1858

the query interface. Each function is parameterized by a @code{ui-out}

1859

builder. The result of the query is constructed using that builder

1860

before the query function returns.

1861

1862

@node Values

1863

@chapter Values

1864

@section Values

1865

1866

@cindex values

1867

@cindex @code{value} structure

1868

@value{GDBN} uses @code{struct value}, or @dfn{values}, as an internal

1869

abstraction for the representation of a variety of inferior objects

1870

and @value{GDBN} convenience objects.

1871

1872

Values have an associated @code{struct type}, that describes a virtual

1873

view of the raw data or object stored in or accessed through the

1874

value.

1875

1876

A value is in addition discriminated by its lvalue-ness, given its

1877

@code{enum lval_type} enumeration type:

1878

1879

@cindex @code{lval_type} enumeration, for values.

1880

@table @code

1881

@item @code{not_lval}

1882

This value is not an lval. It can't be assigned to.

1883

1884

@item @code{lval_memory}

1885

This value represents an object in memory.

1886

1887

@item @code{lval_register}

1888

This value represents an object that lives in a register.

1889

1890

@item @code{lval_internalvar}

1891

Represents the value of an internal variable.

1892

1893

@item @code{lval_internalvar_component}

1894

Represents part of a @value{GDBN} internal variable. E.g., a

1895

structure field.

1896

1897

@cindex computed values

1898

@item @code{lval_computed}

1899

These are ``computed'' values. They allow creating specialized value

1900

objects for specific purposes, all abstracted away from the core value

1901

support code. The creator of such a value writes specialized

1902

functions to handle the reading and writing to/from the value's

1903

backend data, and optionally, a ``copy operator'' and a

1904

``destructor''.

1905

1906

Pointers to these functions are stored in a @code{struct lval_funcs}

1907

instance (declared in @file{value.h}), and passed to the

1908

@code{allocate_computed_value} function, as in the example below.

1909

1910

@smallexample

1911

static void

1912

nil_value_read (struct value *v)

1913

@{

1914

/* This callback reads data from some backend, and stores it in V.

1915

In this case, we always read null data. You'll want to fill in

1916

something more interesting. */

1917

1918

memset (value_contents_all_raw (v),

1919

value_offset (v),

1920

TYPE_LENGTH (value_type (v)));

1921

@}

1922

1923

static void

1924

nil_value_write (struct value *v, struct value *fromval)

1925

@{

1926

/* Takes the data from FROMVAL and stores it in the backend of V. */

1927

1928

to_oblivion (value_contents_all_raw (fromval),

1929

value_offset (v),

1930

TYPE_LENGTH (value_type (fromval)));

1931

@}

1932

1933

static struct lval_funcs nil_value_funcs =

1934

@{

1935

nil_value_read,

1936

nil_value_write

1937

@};

1938

1939

struct value *

1940

make_nil_value (void)

1941

@{

1942

struct type *type;

1943

struct value *v;

1944

1945

type = make_nils_type ();

1946

v = allocate_computed_value (type, &nil_value_funcs, NULL);

1947

1948

return v;

1949

@}

1950

@end smallexample

1951

1952

See the implementation of the @code{$_siginfo} convenience variable in

1953

@file{infrun.c} as a real example use of lval_computed.

1954

1955

@end table

1956

1957

@node Stack Frames

1958

@chapter Stack Frames

1959

1960

@cindex frame

1961

@cindex call stack frame

1962

A frame is a construct that @value{GDBN} uses to keep track of calling

1963

and called functions.

1964

1965

@cindex unwind frame

1966

@value{GDBN}'s frame model, a fresh design, was implemented with the

1967

need to support @sc{dwarf}'s Call Frame Information in mind. In fact,

1968

the term ``unwind'' is taken directly from that specification.

1969

Developers wishing to learn more about unwinders, are encouraged to

1970

read the @sc{dwarf} specification, available from

1971

@url{http://www.dwarfstd.org}.

1972

1973

@findex frame_register_unwind

1974

@findex get_frame_register

1975

@value{GDBN}'s model is that you find a frame's registers by

1976

``unwinding'' them from the next younger frame. That is,

1977

@samp{get_frame_register} which returns the value of a register in

1978

frame #1 (the next-to-youngest frame), is implemented by calling frame

1979

#0's @code{frame_register_unwind} (the youngest frame). But then the

1980

obvious question is: how do you access the registers of the youngest

1981

frame itself?

1982

1983

@cindex sentinel frame

1984

@findex get_frame_type

1985

@vindex SENTINEL_FRAME

1986

To answer this question, @value{GDBN} has the @dfn{sentinel} frame, the

1987

``-1st'' frame. Unwinding registers from the sentinel frame gives you

1988

the current values of the youngest real frame's registers. If @var{f}

1989

is a sentinel frame, then @code{get_frame_type (@var{f}) @equiv{}

1990

SENTINEL_FRAME}.

1991

1992

@section Selecting an Unwinder

1993

1994

@findex frame_unwind_prepend_unwinder

1995

@findex frame_unwind_append_unwinder

1996

The architecture registers a list of frame unwinders (@code{struct

1997

frame_unwind}), using the functions

1998

@code{frame_unwind_prepend_unwinder} and

1999

@code{frame_unwind_append_unwinder}. Each unwinder includes a

2000

sniffer. Whenever @value{GDBN} needs to unwind a frame (to fetch the

2001

previous frame's registers or the current frame's ID), it calls

2002

registered sniffers in order to find one which recognizes the frame.

2003

The first time a sniffer returns non-zero, the corresponding unwinder

2004

is assigned to the frame.

2005

2006

@section Unwinding the Frame ID

2007

@cindex frame ID

2008

2009

Every frame has an associated ID, of type @code{struct frame_id}.

2010

The ID includes the stack base and function start address for

2011

the frame. The ID persists through the entire life of the frame,

2012

including while other called frames are running; it is used to

2013

locate an appropriate @code{struct frame_info} from the cache.

2014

2015

Every time the inferior stops, and at various other times, the frame

2016

cache is flushed. Because of this, parts of @value{GDBN} which need

2017

to keep track of individual frames cannot use pointers to @code{struct

2018

frame_info}. A frame ID provides a stable reference to a frame, even

2019

when the unwinder must be run again to generate a new @code{struct

2020

frame_info} for the same frame.

2021

2022

The frame's unwinder's @code{this_id} method is called to find the ID.

2023

Note that this is different from register unwinding, where the next

2024

frame's @code{prev_register} is called to unwind this frame's

2025

registers.

2026

2027

Both stack base and function address are required to identify the

2028

frame, because a recursive function has the same function address for

2029

two consecutive frames and a leaf function may have the same stack

2030

address as its caller. On some platforms, a third address is part of

2031

the ID to further disambiguate frames---for instance, on IA-64

2032

the separate register stack address is included in the ID.

2033

2034

An invalid frame ID (@code{outer_frame_id}) returned from the

2035

@code{this_id} method means to stop unwinding after this frame.

2036

2037

@code{null_frame_id} is another invalid frame ID which should be used

2038

when there is no frame. For instance, certain breakpoints are attached

2039

to a specific frame, and that frame is identified through its frame ID

2040

(we use this to implement the "finish" command). Using

2041

@code{null_frame_id} as the frame ID for a given breakpoint means

2042

that the breakpoint is not specific to any frame. The @code{this_id}

2043

method should never return @code{null_frame_id}.

2044

2045

@section Unwinding Registers

2046

2047

Each unwinder includes a @code{prev_register} method. This method

2048

takes a frame, an associated cache pointer, and a register number.

2049

It returns a @code{struct value *} describing the requested register,

2050

as saved by this frame. This is the value of the register that is

2051

current in this frame's caller.

2052

2053

The returned value must have the same type as the register. It may

2054

have any lvalue type. In most circumstances one of these routines

2055

will generate the appropriate value:

2056

2057

@table @code

2058

@item frame_unwind_got_optimized

2059

@findex frame_unwind_got_optimized

2060

This register was not saved.

2061

2062

@item frame_unwind_got_register

2063

@findex frame_unwind_got_register

2064

This register was copied into another register in this frame. This

2065

is also used for unchanged registers; they are ``copied'' into the

2066

same register.

2067

2068

@item frame_unwind_got_memory

2069

@findex frame_unwind_got_memory

2070

This register was saved in memory.

2071

2072

@item frame_unwind_got_constant

2073

@findex frame_unwind_got_constant

2074

This register was not saved, but the unwinder can compute the previous

2075

value some other way.

2076

2077

@item frame_unwind_got_address

2078

@findex frame_unwind_got_address

2079

Same as @code{frame_unwind_got_constant}, except that the value is a target

2080

address. This is frequently used for the stack pointer, which is not

2081

explicitly saved but has a known offset from this frame's stack

2082

pointer. For architectures with a flat unified address space, this is

2083

generally the same as @code{frame_unwind_got_constant}.

2084

@end table

2085

2086

@node Symbol Handling

2087

2088

@chapter Symbol Handling

2089

2090

Symbols are a key part of @value{GDBN}'s operation. Symbols include

2091

variables, functions, and types.

2092

2093

Symbol information for a large program can be truly massive, and

2094

reading of symbol information is one of the major performance

2095

bottlenecks in @value{GDBN}; it can take many minutes to process it

2096

all. Studies have shown that nearly all the time spent is

2097

computational, rather than file reading.

2098

2099

One of the ways for @value{GDBN} to provide a good user experience is

2100

to start up quickly, taking no more than a few seconds. It is simply

2101

not possible to process all of a program's debugging info in that

2102

time, and so we attempt to handle symbols incrementally. For instance,

2103

we create @dfn{partial symbol tables} consisting of only selected

2104

symbols, and only expand them to full symbol tables when necessary.

2105

2106

@section Symbol Reading

2107

2108

@cindex symbol reading

2109

@cindex reading of symbols

2110

@cindex symbol files

2111

@value{GDBN} reads symbols from @dfn{symbol files}. The usual symbol

2112

file is the file containing the program which @value{GDBN} is

2113

debugging. @value{GDBN} can be directed to use a different file for

2114

symbols (with the @samp{symbol-file} command), and it can also read

2115

more symbols via the @samp{add-file} and @samp{load} commands. In

2116

addition, it may bring in more symbols while loading shared

2117

libraries.

2118

2119

@findex find_sym_fns

2120

Symbol files are initially opened by code in @file{symfile.c} using

2121

the BFD library (@pxref{Support Libraries}). BFD identifies the type

2122

of the file by examining its header. @code{find_sym_fns} then uses

2123

this identification to locate a set of symbol-reading functions.

2124

2125

@findex add_symtab_fns

2126

@cindex @code{sym_fns} structure

2127

@cindex adding a symbol-reading module

2128

Symbol-reading modules identify themselves to @value{GDBN} by calling

2129

@code{add_symtab_fns} during their module initialization. The argument

2130

to @code{add_symtab_fns} is a @code{struct sym_fns} which contains the

2131

name (or name prefix) of the symbol format, the length of the prefix,

2132

and pointers to four functions. These functions are called at various

2133

times to process symbol files whose identification matches the specified

2134

prefix.

2135

2136

The functions supplied by each module are:

2137

2138

@table @code

2139

@item @var{xyz}_symfile_init(struct sym_fns *sf)

2140

2141

@cindex secondary symbol file

2142

Called from @code{symbol_file_add} when we are about to read a new

2143

symbol file. This function should clean up any internal state (possibly

2144

resulting from half-read previous files, for example) and prepare to

2145

read a new symbol file. Note that the symbol file which we are reading

2146

might be a new ``main'' symbol file, or might be a secondary symbol file

2147

whose symbols are being added to the existing symbol table.

2148

2149

The argument to @code{@var{xyz}_symfile_init} is a newly allocated

2150

@code{struct sym_fns} whose @code{bfd} field contains the BFD for the

2151

new symbol file being read. Its @code{private} field has been zeroed,

2152

and can be modified as desired. Typically, a struct of private

2153

information will be @code{malloc}'d, and a pointer to it will be placed

2154

in the @code{private} field.

2155

2156

There is no result from @code{@var{xyz}_symfile_init}, but it can call

2157

@code{error} if it detects an unavoidable problem.

2158

2159

@item @var{xyz}_new_init()

2160

2161

Called from @code{symbol_file_add} when discarding existing symbols.

2162

This function needs only handle the symbol-reading module's internal

2163

state; the symbol table data structures visible to the rest of

2164

@value{GDBN} will be discarded by @code{symbol_file_add}. It has no

2165

arguments and no result. It may be called after

2166

@code{@var{xyz}_symfile_init}, if a new symbol table is being read, or

2167

may be called alone if all symbols are simply being discarded.

2168

2169

@item @var{xyz}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)

2170

2171

Called from @code{symbol_file_add} to actually read the symbols from a

2172

symbol-file into a set of psymtabs or symtabs.

2173

2174

@code{sf} points to the @code{struct sym_fns} originally passed to

2175

@code{@var{xyz}_sym_init} for possible initialization. @code{addr} is

2176

the offset between the file's specified start address and its true

2177

address in memory. @code{mainline} is 1 if this is the main symbol

2178

table being read, and 0 if a secondary symbol file (e.g., shared library

2179

or dynamically loaded file) is being read.@refill

2180

@end table

2181

2182

In addition, if a symbol-reading module creates psymtabs when

2183

@var{xyz}_symfile_read is called, these psymtabs will contain a pointer

2184

to a function @code{@var{xyz}_psymtab_to_symtab}, which can be called

2185

from any point in the @value{GDBN} symbol-handling code.

2186

2187

@table @code

2188

@item @var{xyz}_psymtab_to_symtab (struct partial_symtab *pst)

2189

2190

Called from @code{psymtab_to_symtab} (or the @code{PSYMTAB_TO_SYMTAB} macro) if

2191

the psymtab has not already been read in and had its @code{pst->symtab}

2192

pointer set. The argument is the psymtab to be fleshed-out into a

2193

symtab. Upon return, @code{pst->readin} should have been set to 1, and

2194

@code{pst->symtab} should contain a pointer to the new corresponding symtab, or

2195

zero if there were no symbols in that part of the symbol file.

2196

@end table

2197

2198

@section Partial Symbol Tables

2199

2200

@value{GDBN} has three types of symbol tables:

2201

2202

@itemize @bullet

2203

@cindex full symbol table

2204

@cindex symtabs

2205

@item

2206

Full symbol tables (@dfn{symtabs}). These contain the main

2207

information about symbols and addresses.

2208

2209

@cindex psymtabs

2210

@item

2211

Partial symbol tables (@dfn{psymtabs}). These contain enough

2212

information to know when to read the corresponding part of the full

2213

symbol table.

2214

2215

@cindex minimal symbol table

2216

@cindex minsymtabs

2217

@item

2218

Minimal symbol tables (@dfn{msymtabs}). These contain information

2219

gleaned from non-debugging symbols.

2220

@end itemize

2221

2222

@cindex partial symbol table

2223

This section describes partial symbol tables.

2224

2225

A psymtab is constructed by doing a very quick pass over an executable

2226

file's debugging information. Small amounts of information are

2227

extracted---enough to identify which parts of the symbol table will

2228

need to be re-read and fully digested later, when the user needs the

2229

information. The speed of this pass causes @value{GDBN} to start up very

2230

quickly. Later, as the detailed rereading occurs, it occurs in small

2231

pieces, at various times, and the delay therefrom is mostly invisible to

2232

the user.

2233

@c (@xref{Symbol Reading}.)

2234

2235

The symbols that show up in a file's psymtab should be, roughly, those

2236

visible to the debugger's user when the program is not running code from

2237

that file. These include external symbols and types, static symbols and

2238

types, and @code{enum} values declared at file scope.

2239

2240

The psymtab also contains the range of instruction addresses that the

2241

full symbol table would represent.

2242

2243

@cindex finding a symbol

2244

@cindex symbol lookup

2245

The idea is that there are only two ways for the user (or much of the

2246

code in the debugger) to reference a symbol:

2247

2248

@itemize @bullet

2249

@findex find_pc_function

2250

@findex find_pc_line

2251

@item

2252

By its address (e.g., execution stops at some address which is inside a

2253

function in this file). The address will be noticed to be in the

2254

range of this psymtab, and the full symtab will be read in.

2255

@code{find_pc_function}, @code{find_pc_line}, and other

2256

@code{find_pc_@dots{}} functions handle this.

2257

2258

@cindex lookup_symbol

2259

@item

2260

By its name

2261

(e.g., the user asks to print a variable, or set a breakpoint on a

2262

function). Global names and file-scope names will be found in the

2263

psymtab, which will cause the symtab to be pulled in. Local names will

2264

have to be qualified by a global name, or a file-scope name, in which

2265

case we will have already read in the symtab as we evaluated the

2266

qualifier. Or, a local symbol can be referenced when we are ``in'' a

2267

local scope, in which case the first case applies. @code{lookup_symbol}

2268

does most of the work here.

2269

@end itemize

2270

2271

The only reason that psymtabs exist is to cause a symtab to be read in

2272

at the right moment. Any symbol that can be elided from a psymtab,

2273

while still causing that to happen, should not appear in it. Since

2274

psymtabs don't have the idea of scope, you can't put local symbols in

2275

them anyway. Psymtabs don't have the idea of the type of a symbol,

2276

either, so types need not appear, unless they will be referenced by

2277

name.

2278

2279

It is a bug for @value{GDBN} to behave one way when only a psymtab has

2280

been read, and another way if the corresponding symtab has been read

2281

in. Such bugs are typically caused by a psymtab that does not contain

2282

all the visible symbols, or which has the wrong instruction address

2283

ranges.

2284

2285

The psymtab for a particular section of a symbol file (objfile) could be

2286

thrown away after the symtab has been read in. The symtab should always

2287

be searched before the psymtab, so the psymtab will never be used (in a

2288

bug-free environment). Currently, psymtabs are allocated on an obstack,

2289

and all the psymbols themselves are allocated in a pair of large arrays

2290

on an obstack, so there is little to be gained by trying to free them

2291

unless you want to do a lot more work.

2292

2293

Whether or not psymtabs are created depends on the objfile's symbol

2294

reader. The core of @value{GDBN} hides the details of partial symbols

2295

and partial symbol tables behind a set of function pointers known as

2296

the @dfn{quick symbol functions}. These are documented in

2297

@file{symfile.h}.

2298

2299

@section Types

2300

2301

@unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}).

2302

2303

@cindex fundamental types

2304

These are the fundamental types that @value{GDBN} uses internally. Fundamental

2305

types from the various debugging formats (stabs, ELF, etc) are mapped

2306

into one of these. They are basically a union of all fundamental types

2307

that @value{GDBN} knows about for all the languages that @value{GDBN}

2308

knows about.

2309

2310

@unnumberedsubsec Type Codes (e.g., @code{TYPE_CODE_PTR}, @code{TYPE_CODE_ARRAY}).

2311

2312

@cindex type codes

2313

Each time @value{GDBN} builds an internal type, it marks it with one

2314

of these types. The type may be a fundamental type, such as

2315

@code{TYPE_CODE_INT}, or a derived type, such as @code{TYPE_CODE_PTR}

2316

which is a pointer to another type. Typically, several @code{FT_*}

2317

types map to one @code{TYPE_CODE_*} type, and are distinguished by

2318

other members of the type struct, such as whether the type is signed

2319

or unsigned, and how many bits it uses.

2320

2321

@unnumberedsubsec Builtin Types (e.g., @code{builtin_type_void}, @code{builtin_type_char}).

2322

2323

These are instances of type structs that roughly correspond to

2324

fundamental types and are created as global types for @value{GDBN} to

2325

use for various ugly historical reasons. We eventually want to

2326

eliminate these. Note for example that @code{builtin_type_int}

2327

initialized in @file{gdbtypes.c} is basically the same as a

2328

@code{TYPE_CODE_INT} type that is initialized in @file{c-lang.c} for

2329

an @code{FT_INTEGER} fundamental type. The difference is that the

2330

@code{builtin_type} is not associated with any particular objfile, and

2331

only one instance exists, while @file{c-lang.c} builds as many

2332

@code{TYPE_CODE_INT} types as needed, with each one associated with

2333

some particular objfile.

2334

2335

@section Object File Formats

2336

@cindex object file formats

2337

2338

@subsection a.out

2339

2340

@cindex @code{a.out} format

2341

The @code{a.out} format is the original file format for Unix. It

2342

consists of three sections: @code{text}, @code{data}, and @code{bss},

2343

which are for program code, initialized data, and uninitialized data,

2344

respectively.

2345

2346

The @code{a.out} format is so simple that it doesn't have any reserved

2347

place for debugging information. (Hey, the original Unix hackers used

2348

@samp{adb}, which is a machine-language debugger!) The only debugging

2349

format for @code{a.out} is stabs, which is encoded as a set of normal

2350

symbols with distinctive attributes.

2351

2352

The basic @code{a.out} reader is in @file{dbxread.c}.

2353

2354

@subsection COFF

2355

2356

@cindex COFF format

2357

The COFF format was introduced with System V Release 3 (SVR3) Unix.

2358

COFF files may have multiple sections, each prefixed by a header. The

2359

number of sections is limited.

2360

2361

The COFF specification includes support for debugging. Although this

2362

was a step forward, the debugging information was woefully limited.

2363

For instance, it was not possible to represent code that came from an

2364

included file. GNU's COFF-using configs often use stabs-type info,

2365

encapsulated in special sections.

2366

2367

The COFF reader is in @file{coffread.c}.

2368

2369

@subsection ECOFF

2370

2371

@cindex ECOFF format

2372

ECOFF is an extended COFF originally introduced for Mips and Alpha

2373

workstations.

2374

2375

The basic ECOFF reader is in @file{mipsread.c}.

2376

2377

@subsection XCOFF

2378

2379

@cindex XCOFF format

2380

The IBM RS/6000 running AIX uses an object file format called XCOFF.

2381

The COFF sections, symbols, and line numbers are used, but debugging

2382

symbols are @code{dbx}-style stabs whose strings are located in the

2383

@code{.debug} section (rather than the string table). For more

2384

information, see @ref{Top,,,stabs,The Stabs Debugging Format}.

2385

2386

The shared library scheme has a clean interface for figuring out what

2387

shared libraries are in use, but the catch is that everything which

2388

refers to addresses (symbol tables and breakpoints at least) needs to be

2389

relocated for both shared libraries and the main executable. At least

2390

using the standard mechanism this can only be done once the program has

2391

been run (or the core file has been read).

2392

2393

@subsection PE

2394

2395

@cindex PE-COFF format

2396

Windows 95 and NT use the PE (@dfn{Portable Executable}) format for their

2397

executables. PE is basically COFF with additional headers.

2398

2399

While BFD includes special PE support, @value{GDBN} needs only the basic

2400

COFF reader.

2401

2402

@subsection ELF

2403

2404

@cindex ELF format

2405

The ELF format came with System V Release 4 (SVR4) Unix. ELF is

2406

similar to COFF in being organized into a number of sections, but it

2407

removes many of COFF's limitations. Debugging info may be either stabs

2408

encapsulated in ELF sections, or more commonly these days, DWARF.

2409

2410

The basic ELF reader is in @file{elfread.c}.

2411

2412

@subsection SOM

2413

2414

@cindex SOM format

2415

SOM is HP's object file and debug format (not to be confused with IBM's

2416

SOM, which is a cross-language ABI).

2417

2418

The SOM reader is in @file{somread.c}.

2419

2420

@section Debugging File Formats

2421

2422

This section describes characteristics of debugging information that

2423

are independent of the object file format.

2424

2425

@subsection stabs

2426

2427

@cindex stabs debugging info

2428

@code{stabs} started out as special symbols within the @code{a.out}

2429

format. Since then, it has been encapsulated into other file

2430

formats, such as COFF and ELF.

2431

2432

While @file{dbxread.c} does some of the basic stab processing,

2433

including for encapsulated versions, @file{stabsread.c} does

2434

the real work.

2435

2436

@subsection COFF

2437

2438

@cindex COFF debugging info

2439

The basic COFF definition includes debugging information. The level

2440

of support is minimal and non-extensible, and is not often used.

2441

2442

@subsection Mips debug (Third Eye)

2443

2444

@cindex ECOFF debugging info

2445

ECOFF includes a definition of a special debug format.

2446

2447

The file @file{mdebugread.c} implements reading for this format.

2448

2449

@c mention DWARF 1 as a formerly-supported format

2450

2451

@subsection DWARF 2

2452

2453

@cindex DWARF 2 debugging info

2454

DWARF 2 is an improved but incompatible version of DWARF 1.

2455

2456

The DWARF 2 reader is in @file{dwarf2read.c}.

2457

2458

@subsection Compressed DWARF 2

2459

2460

@cindex Compressed DWARF 2 debugging info

2461

Compressed DWARF 2 is not technically a separate debugging format, but

2462

merely DWARF 2 debug information that has been compressed. In this

2463

format, every object-file section holding DWARF 2 debugging

2464

information is compressed and prepended with a header. (The section

2465

is also typically renamed, so a section called @code{.debug_info} in a

2466

DWARF 2 binary would be called @code{.zdebug_info} in a compressed

2467

DWARF 2 binary.) The header is 12 bytes long:

2468

2469

@itemize @bullet

2470

@item

2471

4 bytes: the literal string ``ZLIB''

2472

@item

2473

8 bytes: the uncompressed size of the section, in big-endian byte

2474

order.

2475

@end itemize

2476

2477

The same reader is used for both compressed an normal DWARF 2 info.

2478

Section decompression is done in @code{zlib_decompress_section} in

2479

@file{dwarf2read.c}.

2480

2481

@subsection DWARF 3

2482

2483

@cindex DWARF 3 debugging info

2484

DWARF 3 is an improved version of DWARF 2.

2485

2486

@subsection SOM

2487

2488

@cindex SOM debugging info

2489

Like COFF, the SOM definition includes debugging information.

2490

2491

@section Adding a New Symbol Reader to @value{GDBN}

2492

2493

@cindex adding debugging info reader

2494

If you are using an existing object file format (@code{a.out}, COFF, ELF, etc),

2495

there is probably little to be done.

2496

2497

If you need to add a new object file format, you must first add it to

2498

BFD. This is beyond the scope of this document.

2499

2500

You must then arrange for the BFD code to provide access to the

2501

debugging symbols. Generally @value{GDBN} will have to call swapping

2502

routines from BFD and a few other BFD internal routines to locate the

2503

debugging information. As much as possible, @value{GDBN} should not

2504

depend on the BFD internal data structures.

2505

2506

For some targets (e.g., COFF), there is a special transfer vector used

2507

to call swapping routines, since the external data structures on various

2508

platforms have different sizes and layouts. Specialized routines that

2509

will only ever be implemented by one object file format may be called

2510

directly. This interface should be described in a file

2511

@file{bfd/lib@var{xyz}.h}, which is included by @value{GDBN}.

2512

2513

@section Memory Management for Symbol Files

2514

2515

Most memory associated with a loaded symbol file is stored on

2516

its @code{objfile_obstack}. This includes symbols, types,

2517

namespace data, and other information produced by the symbol readers.

2518

2519

Because this data lives on the objfile's obstack, it is automatically

2520

released when the objfile is unloaded or reloaded. Therefore one

2521

objfile must not reference symbol or type data from another objfile;

2522

they could be unloaded at different times.

2523

2524

User convenience variables, et cetera, have associated types. Normally

2525

these types live in the associated objfile. However, when the objfile

2526

is unloaded, those types are deep copied to global memory, so that

2527

the values of the user variables and history items are not lost.

2528

2529

2530

@node Language Support

2531

2532

@chapter Language Support

2533

2534

@cindex language support

2535

@value{GDBN}'s language support is mainly driven by the symbol reader,

2536

although it is possible for the user to set the source language

2537

manually.

2538

2539

@value{GDBN} chooses the source language by looking at the extension

2540

of the file recorded in the debug info; @file{.c} means C, @file{.f}

2541

means Fortran, etc. It may also use a special-purpose language

2542

identifier if the debug format supports it, like with DWARF.

2543

2544

@section Adding a Source Language to @value{GDBN}

2545

2546

@cindex adding source language

2547

To add other languages to @value{GDBN}'s expression parser, follow the

2548

following steps:

2549

2550

@table @emph

2551

@item Create the expression parser.

2552

2553

@cindex expression parser

2554

This should reside in a file @file{@var{lang}-exp.y}. Routines for

2555

building parsed expressions into a @code{union exp_element} list are in

2556

@file{parse.c}.

2557

2558

@cindex language parser

2559

Since we can't depend upon everyone having Bison, and YACC produces

2560

parsers that define a bunch of global names, the following lines

2561

@strong{must} be included at the top of the YACC parser, to prevent the

2562

various parsers from defining the same global names:

2563

2564

@smallexample

2565

#define yyparse @var{lang}_parse

2566

#define yylex @var{lang}_lex

2567

#define yyerror @var{lang}_error

2568

#define yylval @var{lang}_lval

2569

#define yychar @var{lang}_char

2570

#define yydebug @var{lang}_debug

2571

#define yypact @var{lang}_pact

2572

#define yyr1 @var{lang}_r1

2573

#define yyr2 @var{lang}_r2

2574

#define yydef @var{lang}_def

2575

#define yychk @var{lang}_chk

2576

#define yypgo @var{lang}_pgo

2577

#define yyact @var{lang}_act

2578

#define yyexca @var{lang}_exca

2579

#define yyerrflag @var{lang}_errflag

2580

#define yynerrs @var{lang}_nerrs

2581

@end smallexample

2582

2583

At the bottom of your parser, define a @code{struct language_defn} and

2584

initialize it with the right values for your language. Define an

2585

@code{initialize_@var{lang}} routine and have it call

2586

@samp{add_language(@var{lang}_language_defn)} to tell the rest of @value{GDBN}

2587

that your language exists. You'll need some other supporting variables

2588

and functions, which will be used via pointers from your

2589

@code{@var{lang}_language_defn}. See the declaration of @code{struct

2590

language_defn} in @file{language.h}, and the other @file{*-exp.y} files,

2591

for more information.

2592

2593

@item Add any evaluation routines, if necessary

2594

2595

@cindex expression evaluation routines

2596

@findex evaluate_subexp

2597

@findex prefixify_subexp

2598

@findex length_of_subexp

2599

If you need new opcodes (that represent the operations of the language),

2600

add them to the enumerated type in @file{expression.h}. Add support

2601

code for these operations in the @code{evaluate_subexp} function

2602

defined in the file @file{eval.c}. Add cases

2603

for new opcodes in two functions from @file{parse.c}:

2604

@code{prefixify_subexp} and @code{length_of_subexp}. These compute

2605

the number of @code{exp_element}s that a given operation takes up.

2606

2607

@item Update some existing code

2608

2609

Add an enumerated identifier for your language to the enumerated type

2610

@code{enum language} in @file{defs.h}.

2611

2612

Update the routines in @file{language.c} so your language is included.

2613

These routines include type predicates and such, which (in some cases)

2614

are language dependent. If your language does not appear in the switch

2615

statement, an error is reported.

2616

2617

@vindex current_language

2618

Also included in @file{language.c} is the code that updates the variable

2619

@code{current_language}, and the routines that translate the

2620

@code{language_@var{lang}} enumerated identifier into a printable

2621

string.

2622

2623

@findex _initialize_language

2624

Update the function @code{_initialize_language} to include your

2625

language. This function picks the default language upon startup, so is

2626

dependent upon which languages that @value{GDBN} is built for.

2627

2628

@findex allocate_symtab

2629

Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading

2630

code so that the language of each symtab (source file) is set properly.

2631

This is used to determine the language to use at each stack frame level.

2632

Currently, the language is set based upon the extension of the source

2633

file. If the language can be better inferred from the symbol

2634

information, please set the language of the symtab in the symbol-reading

2635

code.

2636

2637

@findex print_subexp

2638

@findex op_print_tab

2639

Add helper code to @code{print_subexp} (in @file{expprint.c}) to handle any new

2640

expression opcodes you have added to @file{expression.h}. Also, add the

2641

printed representations of your operators to @code{op_print_tab}.

2642

2643

@item Add a place of call

2644

2645

@findex parse_exp_1

2646

Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in

2647

@code{parse_exp_1} (defined in @file{parse.c}).

2648

2649

@item Edit @file{Makefile.in}

2650

2651

Add dependencies in @file{Makefile.in}. Make sure you update the macro

2652

variables such as @code{HFILES} and @code{OBJS}, otherwise your code may

2653

not get linked in, or, worse yet, it may not get @code{tar}red into the

2654

distribution!

2655

@end table

2656

2657

2658

@node Host Definition

2659

2660

@chapter Host Definition

2661

2662

With the advent of Autoconf, it's rarely necessary to have host

2663

definition machinery anymore. The following information is provided,

2664

mainly, as an historical reference.

2665

2666

@section Adding a New Host

2667

2668

@cindex adding a new host

2669

@cindex host, adding

2670

@value{GDBN}'s host configuration support normally happens via Autoconf.

2671

New host-specific definitions should not be needed. Older hosts

2672

@value{GDBN} still use the host-specific definitions and files listed

2673

below, but these mostly exist for historical reasons, and will

2674

eventually disappear.

2675

2676

@table @file

2677

@item gdb/config/@var{arch}/@var{xyz}.mh

2678

This file is a Makefile fragment that once contained both host and

2679

native configuration information (@pxref{Native Debugging}) for the

2680

machine @var{xyz}. The host configuration information is now handled

2681

by Autoconf.

2682

2683

Host configuration information included definitions for @code{CC},

2684

@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},

2685

@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.

2686

2687

New host-only configurations do not need this file.

2688

2689

@end table

2690

2691

(Files named @file{gdb/config/@var{arch}/xm-@var{xyz}.h} were once

2692

used to define host-specific macros, but were no longer needed and

2693

have all been removed.)

2694

2695

@subheading Generic Host Support Files

2696

2697

@cindex generic host support

2698

There are some ``generic'' versions of routines that can be used by

2699

various systems.

2700

2701

@table @file

2702

@cindex remote debugging support

2703

@cindex serial line support

2704

@item ser-unix.c

2705

This contains serial line support for Unix systems. It is included by

2706

default on all Unix-like hosts.

2707

2708

@item ser-pipe.c

2709

This contains serial pipe support for Unix systems. It is included by

2710

default on all Unix-like hosts.

2711

2712

@item ser-mingw.c

2713

This contains serial line support for 32-bit programs running under

2714

Windows using MinGW.

2715

2716

@item ser-go32.c

2717

This contains serial line support for 32-bit programs running under DOS,

2718

using the DJGPP (a.k.a.@: GO32) execution environment.

2719

2720

@cindex TCP remote support

2721

@item ser-tcp.c

2722

This contains generic TCP support using sockets. It is included by

2723

default on all Unix-like hosts and with MinGW.

2724

@end table

2725

2726

@section Host Conditionals

2727

2728

When @value{GDBN} is configured and compiled, various macros are

2729

defined or left undefined, to control compilation based on the

2730

attributes of the host system. While formerly they could be set in

2731

host-specific header files, at present they can be changed only by

2732

setting @code{CFLAGS} when building, or by editing the source code.

2733

2734

These macros and their meanings (or if the meaning is not documented

2735

here, then one of the source files where they are used is indicated)

2736

are:

2737

2738

@ftable @code

2739

@item @value{GDBN}INIT_FILENAME

2740

The default name of @value{GDBN}'s initialization file (normally

2741

@file{.gdbinit}).

2742

2743

@item SIGWINCH_HANDLER

2744

If your host defines @code{SIGWINCH}, you can define this to be the name

2745

of a function to be called if @code{SIGWINCH} is received.

2746

2747

@item SIGWINCH_HANDLER_BODY

2748

Define this to expand into code that will define the function named by

2749

the expansion of @code{SIGWINCH_HANDLER}.

2750

2751

@item CRLF_SOURCE_FILES

2752

@cindex DOS text files

2753

Define this if host files use @code{\r\n} rather than @code{\n} as a

2754

line terminator. This will cause source file listings to omit @code{\r}

2755

characters when printing and it will allow @code{\r\n} line endings of files

2756

which are ``sourced'' by gdb. It must be possible to open files in binary

2757

mode using @code{O_BINARY} or, for fopen, @code{"rb"}.

2758

2759

@item DEFAULT_PROMPT

2760

@cindex prompt

2761

The default value of the prompt string (normally @code{"(gdb) "}).

2762

2763

@item DEV_TTY

2764

@cindex terminal device

2765

The name of the generic TTY device, defaults to @code{"/dev/tty"}.

2766

2767

@item ISATTY

2768

Substitute for isatty, if not available.

2769

2770

@item FOPEN_RB

2771

Define this if binary files are opened the same way as text files.

2772

2773

@item CC_HAS_LONG_LONG

2774

@cindex @code{long long} data type

2775

Define this if the host C compiler supports @code{long long}. This is set

2776

by the @code{configure} script.

2777

2778

@item PRINTF_HAS_LONG_LONG

2779

Define this if the host can handle printing of long long integers via

2780

the printf format conversion specifier @code{ll}. This is set by the

2781

@code{configure} script.

2782

2783

@item LSEEK_NOT_LINEAR

2784

Define this if @code{lseek (n)} does not necessarily move to byte number

2785

@code{n} in the file. This is only used when reading source files. It

2786

is normally faster to define @code{CRLF_SOURCE_FILES} when possible.

2787

2788

@item lint

2789

Define this to help placate @code{lint} in some situations.

2790

2791

@item volatile

2792

Define this to override the defaults of @code{__volatile__} or

2793

@code{/**/}.

2794

@end ftable

2795

2796

2797

@node Target Architecture Definition

2798

2799

@chapter Target Architecture Definition

2800

2801

@cindex target architecture definition

2802

@value{GDBN}'s target architecture defines what sort of

2803

machine-language programs @value{GDBN} can work with, and how it works

2804

with them.

2805

2806

The target architecture object is implemented as the C structure

2807

@code{struct gdbarch *}. The structure, and its methods, are generated

2808

using the Bourne shell script @file{gdbarch.sh}.

2809

2810

@menu

2811

* OS ABI Variant Handling::

2812

* Initialize New Architecture::

2813

* Registers and Memory::

2814

* Pointers and Addresses::

2815

* Address Classes::

2816

* Register Representation::

2817

* Frame Interpretation::

2818

* Inferior Call Setup::

2819

* Adding support for debugging core files::

2820

* Defining Other Architecture Features::

2821

* Adding a New Target::

2822

@end menu

2823

2824

@node OS ABI Variant Handling

2825

@section Operating System ABI Variant Handling

2826

@cindex OS ABI variants

2827

2828

@value{GDBN} provides a mechanism for handling variations in OS

2829

ABIs. An OS ABI variant may have influence over any number of

2830

variables in the target architecture definition. There are two major

2831

components in the OS ABI mechanism: sniffers and handlers.

2832

2833

A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair

2834

(the architecture may be wildcarded) in an attempt to determine the

2835

OS ABI of that file. Sniffers with a wildcarded architecture are considered

2836

to be @dfn{generic}, while sniffers for a specific architecture are

2837

considered to be @dfn{specific}. A match from a specific sniffer

2838

overrides a match from a generic sniffer. Multiple sniffers for an

2839

architecture/flavour may exist, in order to differentiate between two

2840

different operating systems which use the same basic file format. The

2841

OS ABI framework provides a generic sniffer for ELF-format files which

2842

examines the @code{EI_OSABI} field of the ELF header, as well as note

2843

sections known to be used by several operating systems.

2844

2845

@cindex fine-tuning @code{gdbarch} structure

2846

A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the

2847

selected OS ABI. There may be only one handler for a given OS ABI

2848

for each BFD architecture.

2849

2850

The following OS ABI variants are defined in @file{defs.h}:

2851

2852

@table @code

2853

2854

@findex GDB_OSABI_UNINITIALIZED

2855

@item GDB_OSABI_UNINITIALIZED

2856

Used for struct gdbarch_info if ABI is still uninitialized.

2857

2858

@findex GDB_OSABI_UNKNOWN

2859

@item GDB_OSABI_UNKNOWN

2860

The ABI of the inferior is unknown. The default @code{gdbarch}

2861

settings for the architecture will be used.

2862

2863

@findex GDB_OSABI_SVR4

2864

@item GDB_OSABI_SVR4

2865

UNIX System V Release 4.

2866

2867

@findex GDB_OSABI_HURD

2868

@item GDB_OSABI_HURD

2869

GNU using the Hurd kernel.

2870

2871

@findex GDB_OSABI_SOLARIS

2872

@item GDB_OSABI_SOLARIS

2873

Sun Solaris.

2874

2875

@findex GDB_OSABI_OSF1

2876

@item GDB_OSABI_OSF1

2877

OSF/1, including Digital UNIX and Compaq Tru64 UNIX.

2878

2879

@findex GDB_OSABI_LINUX

2880

@item GDB_OSABI_LINUX

2881

GNU using the Linux kernel.

2882

2883

@findex GDB_OSABI_FREEBSD_AOUT

2884

@item GDB_OSABI_FREEBSD_AOUT

2885

FreeBSD using the @code{a.out} executable format.

2886

2887

@findex GDB_OSABI_FREEBSD_ELF

2888

@item GDB_OSABI_FREEBSD_ELF

2889

FreeBSD using the ELF executable format.

2890

2891

@findex GDB_OSABI_NETBSD_AOUT

2892

@item GDB_OSABI_NETBSD_AOUT

2893

NetBSD using the @code{a.out} executable format.

2894

2895

@findex GDB_OSABI_NETBSD_ELF

2896

@item GDB_OSABI_NETBSD_ELF

2897

NetBSD using the ELF executable format.

2898

2899

@findex GDB_OSABI_OPENBSD_ELF

2900

@item GDB_OSABI_OPENBSD_ELF

2901

OpenBSD using the ELF executable format.

2902

2903

@findex GDB_OSABI_WINCE

2904

@item GDB_OSABI_WINCE

2905

Windows CE.

2906

2907

@findex GDB_OSABI_GO32

2908

@item GDB_OSABI_GO32

2909

DJGPP.

2910

2911

@findex GDB_OSABI_IRIX

2912

@item GDB_OSABI_IRIX

2913

Irix.

2914

2915

@findex GDB_OSABI_INTERIX

2916

@item GDB_OSABI_INTERIX

2917

Interix (Posix layer for MS-Windows systems).

2918

2919

@findex GDB_OSABI_HPUX_ELF

2920

@item GDB_OSABI_HPUX_ELF

2921

HP/UX using the ELF executable format.

2922

2923

@findex GDB_OSABI_HPUX_SOM

2924

@item GDB_OSABI_HPUX_SOM

2925

HP/UX using the SOM executable format.

2926

2927

@findex GDB_OSABI_QNXNTO

2928

@item GDB_OSABI_QNXNTO

2929

QNX Neutrino.

2930

2931

@findex GDB_OSABI_CYGWIN

2932

@item GDB_OSABI_CYGWIN

2933

Cygwin.

2934

2935

@findex GDB_OSABI_AIX

2936

@item GDB_OSABI_AIX

2937

AIX.

2938

2939

@end table

2940

2941

Here are the functions that make up the OS ABI framework:

2942

2943

@deftypefun {const char *} gdbarch_osabi_name (enum gdb_osabi @var{osabi})

2944

Return the name of the OS ABI corresponding to @var{osabi}.

2945

@end deftypefun

2946

2947

@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, unsigned long @var{machine}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch}))

2948

Register the OS ABI handler specified by @var{init_osabi} for the

2949

architecture, machine type and OS ABI specified by @var{arch},

2950

@var{machine} and @var{osabi}. In most cases, a value of zero for the

2951

machine type, which implies the architecture's default machine type,

2952

will suffice.

2953

@end deftypefun

2954

2955

@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd}))

2956

Register the OS ABI file sniffer specified by @var{sniffer} for the

2957

BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.

2958

If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to

2959

be generic, and is allowed to examine @var{flavour}-flavoured files for

2960

any architecture.

2961

@end deftypefun

2962

2963

@deftypefun {enum gdb_osabi} gdbarch_lookup_osabi (bfd *@var{abfd})

2964

Examine the file described by @var{abfd} to determine its OS ABI.

2965

The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot

2966

be determined.

2967

@end deftypefun

2968

2969

@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi})

2970

Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the

2971

@code{gdbarch} structure specified by @var{gdbarch}. If a handler

2972

corresponding to @var{osabi} has not been registered for @var{gdbarch}'s

2973

architecture, a warning will be issued and the debugging session will continue

2974

with the defaults already established for @var{gdbarch}.

2975

@end deftypefun

2976

2977

@deftypefun void generic_elf_osabi_sniff_abi_tag_sections (bfd *@var{abfd}, asection *@var{sect}, void *@var{obj})

2978

Helper routine for ELF file sniffers. Examine the file described by

2979

@var{abfd} and look at ABI tag note sections to determine the OS ABI

2980

from the note. This function should be called via

2981

@code{bfd_map_over_sections}.

2982

@end deftypefun

2983

2984

@node Initialize New Architecture

2985

@section Initializing a New Architecture

2986

2987

@menu

2988

* How an Architecture is Represented::

2989

* Looking Up an Existing Architecture::

2990

* Creating a New Architecture::

2991

@end menu

2992

2993

@node How an Architecture is Represented

2994

@subsection How an Architecture is Represented

2995

@cindex architecture representation

2996

@cindex representation of architecture

2997

2998

Each @code{gdbarch} is associated with a single @sc{bfd} architecture,

2999

via a @code{bfd_arch_@var{arch}} in the @code{bfd_architecture}

3000

enumeration. The @code{gdbarch} is registered by a call to

3001

@code{register_gdbarch_init}, usually from the file's

3002

@code{_initialize_@var{filename}} routine, which will be automatically

3003

called during @value{GDBN} startup. The arguments are a @sc{bfd}

3004

architecture constant and an initialization function.

3005

3006

@findex _initialize_@var{arch}_tdep

3007

@cindex @file{@var{arch}-tdep.c}

3008

A @value{GDBN} description for a new architecture, @var{arch} is created by

3009

defining a global function @code{_initialize_@var{arch}_tdep}, by

3010

convention in the source file @file{@var{arch}-tdep.c}. For example,

3011

in the case of the OpenRISC 1000, this function is called

3012

@code{_initialize_or1k_tdep} and is found in the file

3013

@file{or1k-tdep.c}.

3014

3015

@cindex @file{configure.tgt}

3016

@cindex @code{gdbarch}

3017

@findex gdbarch_register

3018

The resulting object files containing the implementation of the

3019

@code{_initialize_@var{arch}_tdep} function are specified in the @value{GDBN}

3020

@file{configure.tgt} file, which includes a large case statement

3021

pattern matching against the @code{--target} option of the

3022

@code{configure} script. The new @code{struct gdbarch} is created

3023

within the @code{_initialize_@var{arch}_tdep} function by calling

3024

@code{gdbarch_register}:

3025

3026

@smallexample

3027

void gdbarch_register (enum bfd_architecture @var{architecture},

3028

gdbarch_init_ftype *@var{init_func},

3029

gdbarch_dump_tdep_ftype *@var{tdep_dump_func});

3030

@end smallexample

3031

3032

The @var{architecture} will identify the unique @sc{bfd} to be

3033

associated with this @code{gdbarch}. The @var{init_func} funciton is

3034

called to create and return the new @code{struct gdbarch}. The

3035

@var{tdep_dump_func} function will dump the target specific details

3036

associated with this architecture.

3037

3038

For example the function @code{_initialize_or1k_tdep} creates its

3039

architecture for 32-bit OpenRISC 1000 architectures by calling:

3040

3041

@smallexample

3042

gdbarch_register (bfd_arch_or32, or1k_gdbarch_init, or1k_dump_tdep);

3043

@end smallexample

3044

3045

@node Looking Up an Existing Architecture

3046

@subsection Looking Up an Existing Architecture

3047

@cindex @code{gdbarch} lookup

3048

3049

The initialization function has this prototype:

3050

3051

@smallexample

3052

static struct gdbarch *

3053

@var{arch}_gdbarch_init (struct gdbarch_info @var{info},

3054

struct gdbarch_list *@var{arches})

3055

@end smallexample

3056

3057

The @var{info} argument contains parameters used to select the correct

3058

architecture, and @var{arches} is a list of architectures which

3059

have already been created with the same @code{bfd_arch_@var{arch}}

3060

value.

3061

3062

The initialization function should first make sure that @var{info}

3063

is acceptable, and return @code{NULL} if it is not. Then, it should

3064

search through @var{arches} for an exact match to @var{info}, and

3065

return one if found. Lastly, if no exact match was found, it should

3066

create a new architecture based on @var{info} and return it.

3067

3068

@findex gdbarch_list_lookup_by_info

3069

@cindex @code{gdbarch_info}

3070

The lookup is done using @code{gdbarch_list_lookup_by_info}. It is

3071

passed the list of existing architectures, @var{arches}, and the

3072

@code{struct gdbarch_info}, @var{info}, and returns the first matching

3073

architecture it finds, or @code{NULL} if none are found. If an

3074

architecture is found it can be returned as the result from the

3075

initialization function, otherwise a new @code{struct gdbach} will need

3076

to be created.

3077

3078

The struct gdbarch_info has the following components:

3079

3080

@smallexample

3081

struct gdbarch_info

3082

@{

3083

const struct bfd_arch_info *bfd_arch_info;

3084

int byte_order;

3085

bfd *abfd;

3086

struct gdbarch_tdep_info *tdep_info;

3087

enum gdb_osabi osabi;

3088

const struct target_desc *target_desc;

3089

@};

3090

@end smallexample

3091

3092

@vindex bfd_arch_info

3093

The @code{bfd_arch_info} member holds the key details about the

3094

architecture. The @code{byte_order} member is a value in an

3095

enumeration indicating the endianism. The @code{abfd} member is a

3096

pointer to the full @sc{bfd}, the @code{tdep_info} member is

3097

additional custom target specific information, @code{osabi} identifies

3098

which (if any) of a number of operating specific ABIs are used by this

3099

architecture and the @code{target_desc} member is a set of name-value

3100

pairs with information about register usage in this target.

3101

3102

When the @code{struct gdbarch} initialization function is called, not

3103

all the fields are provided---only those which can be deduced from the

3104

@sc{bfd}. The @code{struct gdbarch_info}, @var{info} is used as a

3105

look-up key with the list of existing architectures, @var{arches} to

3106

see if a suitable architecture already exists. The @var{tdep_info},

3107

@var{osabi} and @var{target_desc} fields may be added before this

3108

lookup to refine the search.

3109

3110

Only information in @var{info} should be used to choose the new

3111

architecture. Historically, @var{info} could be sparse, and

3112

defaults would be collected from the first element on @var{arches}.

3113

However, @value{GDBN} now fills in @var{info} more thoroughly,

3114

so new @code{gdbarch} initialization functions should not take

3115

defaults from @var{arches}.

3116

3117

@node Creating a New Architecture

3118

@subsection Creating a New Architecture

3119

@cindex @code{struct gdbarch} creation

3120

3121

@findex gdbarch_alloc

3122

@cindex @code{gdbarch_tdep} when allocating new @code{gdbarch}

3123

If no architecture is found, then a new architecture must be created,

3124

by calling @code{gdbarch_alloc} using the supplied @code{@w{struct

3125

gdbarch_info}} and any additional custom target specific

3126

information in a @code{struct gdbarch_tdep}. The prototype for

3127

@code{gdbarch_alloc} is:

3128

3129

@smallexample

3130

struct gdbarch *gdbarch_alloc (const struct gdbarch_info *@var{info},

3131

struct gdbarch_tdep *@var{tdep});

3132

@end smallexample

3133

3134

@cindex @code{set_gdbarch} functions

3135

@cindex @code{gdbarch} accessor functions

3136

The newly created struct gdbarch must then be populated. Although

3137

there are default values, in most cases they are not what is

3138

required.

3139

3140

For each element, @var{X}, there is are a pair of corresponding accessor

3141

functions, one to set the value of that element,

3142

@code{set_gdbarch_@var{X}}, the second to either get the value of an

3143

element (if it is a variable) or to apply the element (if it is a

3144

function), @code{gdbarch_@var{X}}. Note that both accessor functions

3145

take a pointer to the @code{@w{struct gdbarch}} as first

3146

argument. Populating the new @code{gdbarch} should use the

3147

@code{set_gdbarch} functions.

3148

3149

The following sections identify the main elements that should be set

3150

in this way. This is not the complete list, but represents the

3151

functions and elements that must commonly be specified for a new

3152

architecture. Many of the functions and variables are described in the

3153

header file @file{gdbarch.h}.

3154

3155

This is the main work in defining a new architecture. Implementing the

3156

set of functions to populate the @code{struct gdbarch}.

3157

3158

@cindex @code{gdbarch_tdep} definition

3159

@code{struct gdbarch_tdep} is not defined within @value{GDBN}---it is up

3160

to the user to define this struct if it is needed to hold custom target

3161

information that is not covered by the standard @code{@w{struct

3162

gdbarch}}. For example with the OpenRISC 1000 architecture it is used to

3163

hold the number of matchpoints available in the target (along with other

3164

information).

3165

3166

If there is no additional target specific information, it can be set to

3167

@code{NULL}.

3168

3169

@node Registers and Memory

3170

@section Registers and Memory

3171

3172

@value{GDBN}'s model of the target machine is rather simple.

3173

@value{GDBN} assumes the machine includes a bank of registers and a

3174

block of memory. Each register may have a different size.

3175

3176

@value{GDBN} does not have a magical way to match up with the

3177

compiler's idea of which registers are which; however, it is critical

3178

that they do match up accurately. The only way to make this work is

3179

to get accurate information about the order that the compiler uses,

3180

and to reflect that in the @code{gdbarch_register_name} and related functions.

3181

3182

@value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.

3183

3184

@node Pointers and Addresses

3185

@section Pointers Are Not Always Addresses

3186

@cindex pointer representation

3187

@cindex address representation

3188

@cindex word-addressed machines

3189

@cindex separate data and code address spaces

3190

@cindex spaces, separate data and code address

3191

@cindex address spaces, separate data and code

3192

@cindex code pointers, word-addressed

3193

@cindex converting between pointers and addresses

3194

@cindex D10V addresses

3195

3196

On almost all 32-bit architectures, the representation of a pointer is

3197

indistinguishable from the representation of some fixed-length number

3198

whose value is the byte address of the object pointed to. On such

3199

machines, the words ``pointer'' and ``address'' can be used interchangeably.

3200

However, architectures with smaller word sizes are often cramped for

3201

address space, so they may choose a pointer representation that breaks this

3202

identity, and allows a larger code address space.

3203

3204

@c D10V is gone from sources - more current example?

3205

3206

For example, the Renesas D10V is a 16-bit VLIW processor whose

3207

instructions are 32 bits long@footnote{Some D10V instructions are

3208

actually pairs of 16-bit sub-instructions. However, since you can't

3209

jump into the middle of such a pair, code addresses can only refer to

3210

full 32 bit instructions, which is what matters in this explanation.}.

3211

If the D10V used ordinary byte addresses to refer to code locations,

3212

then the processor would only be able to address 64kb of instructions.

3213

However, since instructions must be aligned on four-byte boundaries, the

3214

low two bits of any valid instruction's byte address are always

3215

zero---byte addresses waste two bits. So instead of byte addresses,

3216

the D10V uses word addresses---byte addresses shifted right two bits---to

3217

refer to code. Thus, the D10V can use 16-bit words to address 256kb of

3218

code space.

3219

3220

However, this means that code pointers and data pointers have different

3221

forms on the D10V. The 16-bit word @code{0xC020} refers to byte address

3222

@code{0xC020} when used as a data address, but refers to byte address

3223

@code{0x30080} when used as a code address.

3224

3225

(The D10V also uses separate code and data address spaces, which also

3226

affects the correspondence between pointers and addresses, but we're

3227

going to ignore that here; this example is already too long.)

3228

3229

To cope with architectures like this---the D10V is not the only

3230

one!---@value{GDBN} tries to distinguish between @dfn{addresses}, which are

3231

byte numbers, and @dfn{pointers}, which are the target's representation

3232

of an address of a particular type of data. In the example above,

3233

@code{0xC020} is the pointer, which refers to one of the addresses

3234

@code{0xC020} or @code{0x30080}, depending on the type imposed upon it.

3235

@value{GDBN} provides functions for turning a pointer into an address

3236

and vice versa, in the appropriate way for the current architecture.

3237

3238

Unfortunately, since addresses and pointers are identical on almost all

3239

processors, this distinction tends to bit-rot pretty quickly. Thus,

3240

each time you port @value{GDBN} to an architecture which does

3241

distinguish between pointers and addresses, you'll probably need to

3242

clean up some architecture-independent code.

3243

3244

Here are functions which convert between pointers and addresses:

3245

3246

@deftypefun CORE_ADDR extract_typed_address (void *@var{buf}, struct type *@var{type})

3247

Treat the bytes at @var{buf} as a pointer or reference of type

3248

@var{type}, and return the address it represents, in a manner

3249

appropriate for the current architecture. This yields an address

3250

@value{GDBN} can use to read target memory, disassemble, etc. Note that

3251

@var{buf} refers to a buffer in @value{GDBN}'s memory, not the

3252

inferior's.

3253

3254

For example, if the current architecture is the Intel x86, this function

3255

extracts a little-endian integer of the appropriate length from

3256

@var{buf} and returns it. However, if the current architecture is the

3257

D10V, this function will return a 16-bit integer extracted from

3258

@var{buf}, multiplied by four if @var{type} is a pointer to a function.

3259

3260

If @var{type} is not a pointer or reference type, then this function

3261

will signal an internal error.

3262

@end deftypefun

3263

3264

@deftypefun CORE_ADDR store_typed_address (void *@var{buf}, struct type *@var{type}, CORE_ADDR @var{addr})

3265

Store the address @var{addr} in @var{buf}, in the proper format for a

3266

pointer of type @var{type} in the current architecture. Note that

3267

@var{buf} refers to a buffer in @value{GDBN}'s memory, not the

3268

inferior's.

3269

3270

For example, if the current architecture is the Intel x86, this function

3271

stores @var{addr} unmodified as a little-endian integer of the

3272

appropriate length in @var{buf}. However, if the current architecture

3273

is the D10V, this function divides @var{addr} by four if @var{type} is

3274

a pointer to a function, and then stores it in @var{buf}.

3275

3276

If @var{type} is not a pointer or reference type, then this function

3277

will signal an internal error.

3278

@end deftypefun

3279

3280

@deftypefun CORE_ADDR value_as_address (struct value *@var{val})

3281

Assuming that @var{val} is a pointer, return the address it represents,

3282

as appropriate for the current architecture.

3283

3284

This function actually works on integral values, as well as pointers.

3285

For pointers, it performs architecture-specific conversions as

3286

described above for @code{extract_typed_address}.

3287

@end deftypefun

3288

3289

@deftypefun CORE_ADDR value_from_pointer (struct type *@var{type}, CORE_ADDR @var{addr})

3290

Create and return a value representing a pointer of type @var{type} to

3291

the address @var{addr}, as appropriate for the current architecture.

3292

This function performs architecture-specific conversions as described

3293

above for @code{store_typed_address}.

3294

@end deftypefun

3295

3296

Here are two functions which architectures can define to indicate the

3297

relationship between pointers and addresses. These have default

3298

definitions, appropriate for architectures on which all pointers are

3299

simple unsigned byte addresses.

3300

3301

@deftypefun CORE_ADDR gdbarch_pointer_to_address (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf})

3302

Assume that @var{buf} holds a pointer of type @var{type}, in the

3303

appropriate format for the current architecture. Return the byte

3304

address the pointer refers to.

3305

3306

This function may safely assume that @var{type} is either a pointer or a

3307

C@t{++} reference type.

3308

@end deftypefun

3309

3310

@deftypefun void gdbarch_address_to_pointer (struct gdbarch *@var{gdbarch}, struct type *@var{type}, char *@var{buf}, CORE_ADDR @var{addr})

3311

Store in @var{buf} a pointer of type @var{type} representing the address

3312

@var{addr}, in the appropriate format for the current architecture.

3313

3314

This function may safely assume that @var{type} is either a pointer or a

3315

C@t{++} reference type.

3316

@end deftypefun

3317

3318

@node Address Classes

3319

@section Address Classes

3320

@cindex address classes

3321

@cindex DW_AT_byte_size

3322

@cindex DW_AT_address_class

3323

3324

Sometimes information about different kinds of addresses is available

3325

via the debug information. For example, some programming environments

3326

define addresses of several different sizes. If the debug information

3327

distinguishes these kinds of address classes through either the size

3328

info (e.g, @code{DW_AT_byte_size} in @w{DWARF 2}) or through an explicit

3329

address class attribute (e.g, @code{DW_AT_address_class} in @w{DWARF 2}), the

3330

following macros should be defined in order to disambiguate these

3331

types within @value{GDBN} as well as provide the added information to

3332

a @value{GDBN} user when printing type expressions.

3333

3334

@deftypefun int gdbarch_address_class_type_flags (struct gdbarch *@var{gdbarch}, int @var{byte_size}, int @var{dwarf2_addr_class})

3335

Returns the type flags needed to construct a pointer type whose size

3336

is @var{byte_size} and whose address class is @var{dwarf2_addr_class}.

3337

This function is normally called from within a symbol reader. See

3338

@file{dwarf2read.c}.

3339

@end deftypefun

3340

3341

@deftypefun {char *} gdbarch_address_class_type_flags_to_name (struct gdbarch *@var{gdbarch}, int @var{type_flags})

3342

Given the type flags representing an address class qualifier, return

3343

its name.

3344

@end deftypefun

3345

@deftypefun int gdbarch_address_class_name_to_type_flags (struct gdbarch *@var{gdbarch}, int @var{name}, int *@var{type_flags_ptr})

3346

Given an address qualifier name, set the @code{int} referenced by @var{type_flags_ptr} to the type flags

3347

for that address class qualifier.

3348

@end deftypefun

3349

3350

Since the need for address classes is rather rare, none of

3351

the address class functions are defined by default. Predicate

3352

functions are provided to detect when they are defined.

3353

3354

Consider a hypothetical architecture in which addresses are normally

3355

32-bits wide, but 16-bit addresses are also supported. Furthermore,

3356

suppose that the @w{DWARF 2} information for this architecture simply

3357

uses a @code{DW_AT_byte_size} value of 2 to indicate the use of one

3358

of these "short" pointers. The following functions could be defined

3359

to implement the address class functions:

3360

3361

@smallexample

3362

somearch_address_class_type_flags (int byte_size,

3363

int dwarf2_addr_class)

3364

@{

3365

if (byte_size == 2)

3366

return TYPE_FLAG_ADDRESS_CLASS_1;

3367

else

3368

return 0;

3369

@}

3370

3371

static char *

3372

somearch_address_class_type_flags_to_name (int type_flags)

3373

@{

3374

if (type_flags & TYPE_FLAG_ADDRESS_CLASS_1)

3375

return "short";

3376

else

3377

return NULL;

3378

@}

3379

3380

int

3381

somearch_address_class_name_to_type_flags (char *name,

3382

int *type_flags_ptr)

3383

@{

3384

if (strcmp (name, "short") == 0)

3385

@{

3386

*type_flags_ptr = TYPE_FLAG_ADDRESS_CLASS_1;

3387

return 1;

3388

@}

3389

else

3390

return 0;

3391

@}

3392

@end smallexample

3393

3394

The qualifier @code{@@short} is used in @value{GDBN}'s type expressions

3395

to indicate the presence of one of these ``short'' pointers. For

3396

example if the debug information indicates that @code{short_ptr_var} is

3397

one of these short pointers, @value{GDBN} might show the following

3398

behavior:

3399

3400

@smallexample

3401

(gdb) ptype short_ptr_var

3402

type = int * @@short

3403

@end smallexample

3404

3405

3406

@node Register Representation

3407

@section Register Representation

3408

3409

@menu

3410

* Raw and Cooked Registers::

3411

* Register Architecture Functions & Variables::

3412

* Register Information Functions::

3413

* Register and Memory Data::

3414

* Register Caching::

3415

@end menu

3416

3417

@node Raw and Cooked Registers

3418

@subsection Raw and Cooked Registers

3419

@cindex raw register representation

3420

@cindex cooked register representation

3421

@cindex representations, raw and cooked registers

3422

3423

@value{GDBN} considers registers to be a set with members numbered

3424

linearly from 0 upwards. The first part of that set corresponds to real

3425

physical registers, the second part to any @dfn{pseudo-registers}.

3426

Pseudo-registers have no independent physical existence, but are useful

3427

representations of information within the architecture. For example the

3428

OpenRISC 1000 architecture has up to 32 general purpose registers, which

3429

are typically represented as 32-bit (or 64-bit) integers. However the

3430

GPRs are also used as operands to the floating point operations, and it

3431

could be convenient to define a set of pseudo-registers, to show the

3432

GPRs represented as floating point values.

3433

3434

For any architecture, the implementer will decide on a mapping from

3435

hardware to @value{GDBN} register numbers. The registers corresponding to real

3436

hardware are referred to as @dfn{raw} registers, the remaining registers are

3437

@dfn{pseudo-registers}. The total register set (raw and pseudo) is called

3438

the @dfn{cooked} register set.

3439

3440

3441

@node Register Architecture Functions & Variables

3442

@subsection Functions and Variables Specifying the Register Architecture

3443

@cindex @code{gdbarch} register architecture functions

3444

3445

These @code{struct gdbarch} functions and variables specify the number

3446

and type of registers in the architecture.

3447

3448

@deftypefn {Architecture Function} CORE_ADDR read_pc (struct regcache *@var{regcache})

3449

@end deftypefn

3450

@deftypefn {Architecture Function} void write_pc (struct regcache *@var{regcache}, CORE_ADDR @var{val})

3451

3452

Read or write the program counter. The default value of both

3453

functions is @code{NULL} (no function available). If the program

3454

counter is just an ordinary register, it can be specified in

3455

@code{struct gdbarch} instead (see @code{pc_regnum} below) and it will

3456

be read or written using the standard routines to access registers. This

3457

function need only be specified if the program counter is not an

3458

ordinary register.

3459

3460

Any register information can be obtained using the supplied register

3461

cache, @var{regcache}. @xref{Register Caching, , Register Caching}.

3462

3463

@end deftypefn

3464

3465

@deftypefn {Architecture Function} void pseudo_register_read (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf})

3466

@end deftypefn

3467

@deftypefn {Architecture Function} void pseudo_register_write (struct gdbarch *@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const gdb_byte *@var{buf})

3468

3469

These functions should be defined if there are any pseudo-registers.

3470

The default value is @code{NULL}. @var{regnum} is the number of the

3471

register to read or write (which will be a @dfn{cooked} register

3472

number) and @var{buf} is the buffer where the value read will be

3473

placed, or from which the value to be written will be taken. The

3474

value in the buffer may be converted to or from a signed or unsigned

3475

integral value using one of the utility functions (@pxref{Register and

3476

Memory Data, , Using Different Register and Memory Data

3477

Representations}).

3478

3479

The access should be for the specified architecture,

3480

@var{gdbarch}. Any register information can be obtained using the

3481

supplied register cache, @var{regcache}. @xref{Register Caching, ,

3482

Register Caching}.

3483

3484

@end deftypefn

3485

3486

@deftypevr {Architecture Variable} int sp_regnum

3487

@vindex sp_regnum

3488

@cindex stack pointer

3489

@cindex @kbd{$sp}

3490

3491

This specifies the register holding the stack pointer, which may be a

3492

raw or pseudo-register. It defaults to -1 (not defined), but it is an

3493

error for it not to be defined.

3494

3495

The value of the stack pointer register can be accessed withing

3496

@value{GDBN} as the variable @kbd{$sp}.

3497

3498

@end deftypevr

3499

3500

@deftypevr {Architecture Variable} int pc_regnum

3501

@vindex pc_regnum

3502

@cindex program counter

3503

@cindex @kbd{$pc}

3504

3505

This specifies the register holding the program counter, which may be a

3506

raw or pseudo-register. It defaults to -1 (not defined). If

3507

@code{pc_regnum} is not defined, then the functions @code{read_pc} and

3508

@code{write_pc} (see above) must be defined.

3509

3510

The value of the program counter (whether defined as a register, or

3511

through @code{read_pc} and @code{write_pc}) can be accessed withing

3512

@value{GDBN} as the variable @kbd{$pc}.

3513

3514

@end deftypevr

3515

3516

@deftypevr {Architecture Variable} int ps_regnum

3517

@vindex ps_regnum

3518

@cindex processor status register

3519

@cindex status register

3520

@cindex @kbd{$ps}

3521

3522

This specifies the register holding the processor status (often called

3523

the status register), which may be a raw or pseudo-register. It

3524

defaults to -1 (not defined).

3525

3526

If defined, the value of this register can be accessed withing

3527

@value{GDBN} as the variable @kbd{$ps}.

3528

3529

@end deftypevr

3530

3531

@deftypevr {Architecture Variable} int fp0_regnum

3532

@vindex fp0_regnum

3533

@cindex first floating point register

3534

3535

This specifies the first floating point register. It defaults to

3536

0. @code{fp0_regnum} is not needed unless the target offers support

3537

for floating point.

3538

3539

@end deftypevr

3540

3541

@node Register Information Functions

3542

@subsection Functions Giving Register Information

3543

@cindex @code{gdbarch} register information functions

3544

3545

These functions return information about registers.

3546

3547

@deftypefn {Architecture Function} {const char *} register_name (struct gdbarch *@var{gdbarch}, int @var{regnum})

3548

3549

This function should convert a register number (raw or pseudo) to a

3550

register name (as a C @code{const char *}). This is used both to

3551

determine the name of a register for output and to work out the meaning

3552

of any register names used as input. The function may also return

3553

@code{NULL}, to indicate that @var{regnum} is not a valid register.

3554

3555

For example with the OpenRISC 1000, @value{GDBN} registers 0-31 are the

3556

General Purpose Registers, register 32 is the program counter and

3557

register 33 is the supervision register (i.e.@: the processor status

3558

register), which map to the strings @code{"gpr00"} through

3559

@code{"gpr31"}, @code{"pc"} and @code{"sr"} respectively. This means

3560

that the @value{GDBN} command @kbd{print $gpr5} should print the value of

3561

the OR1K general purpose register 5@footnote{

3562

@cindex frame pointer

3563

@cindex @kbd{$fp}

3564

Historically, @value{GDBN} always had a concept of a frame pointer

3565

register, which could be accessed via the @value{GDBN} variable,

3566

@kbd{$fp}. That concept is now deprecated, recognizing that not all

3567

architectures have a frame pointer. However if an architecture does

3568

have a frame pointer register, and defines a register or

3569

pseudo-register with the name @code{"fp"}, then that register will be

3570

used as the value of the @kbd{$fp} variable.}.

3571

3572

The default value for this function is @code{NULL}, meaning

3573

undefined. It should always be defined.

3574

3575

The access should be for the specified architecture, @var{gdbarch}.

3576

3577

@end deftypefn

3578

3579

@deftypefn {Architecture Function} {struct type *} register_type (struct gdbarch *@var{gdbarch}, int @var{regnum})

3580

3581

Given a register number, this function identifies the type of data it

3582

may be holding, specified as a @code{struct type}. @value{GDBN} allows

3583

creation of arbitrary types, but a number of built in types are

3584

provided (@code{builtin_type_void}, @code{builtin_type_int32} etc),

3585

together with functions to derive types from these.

3586

3587

Typically the program counter will have a type of ``pointer to

3588

function'' (it points to code), the frame pointer and stack pointer

3589

will have types of ``pointer to void'' (they point to data on the stack)

3590

and all other integer registers will have a type of 32-bit integer or

3591

64-bit integer.

3592

3593

This information guides the formatting when displaying register

3594

information. The default value is @code{NULL} meaning no information is

3595

available to guide formatting when displaying registers.

3596

3597

@end deftypefn

3598

3599

@deftypefn {Architecture Function} void print_registers_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, int @var{regnum}, int @var{all})

3600

3601

Define this function to print out one or all of the registers for the

3602

@value{GDBN} @kbd{info registers} command. The default value is the

3603

function @code{default_print_registers_info}, which uses the register

3604

type information (see @code{register_type} above) to determine how each

3605

register should be printed. Define a custom version of this function

3606

for fuller control over how the registers are displayed.

3607

3608

The access should be for the specified architecture, @var{gdbarch},

3609

with output to the file specified by the User Interface

3610

Independent Output file handle, @var{file} (@pxref{UI-Independent

3611

Output, , UI-Independent Output---the @code{ui_out}

3612

Functions}).

3613

3614

The registers should show their values in the frame specified by

3615

@var{frame}. If @var{regnum} is -1 and @var{all} is zero, then all

3616

the ``significant'' registers should be shown (the implementer should

3617

decide which registers are ``significant''). Otherwise only the value of

3618

the register specified by @var{regnum} should be output. If

3619

@var{regnum} is -1 and @var{all} is non-zero (true), then the value of

3620

all registers should be shown.

3621

3622

By default @code{default_print_registers_info} prints one register per

3623

line, and if @var{all} is zero omits floating-point registers.

3624

3625

@end deftypefn

3626

3627

@deftypefn {Architecture Function} void print_float_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args})

3628

3629

Define this function to provide output about the floating point unit and

3630

registers for the @value{GDBN} @kbd{info float} command respectively.

3631

The default value is @code{NULL} (not defined), meaning no information

3632

will be provided.

3633

3634

The @var{gdbarch} and @var{file} and @var{frame} arguments have the same

3635

meaning as in the @code{print_registers_info} function above. The string

3636

@var{args} contains any supplementary arguments to the @kbd{info float}

3637

command.

3638

3639

Define this function if the target supports floating point operations.

3640

3641

@end deftypefn

3642

3643

@deftypefn {Architecture Function} void print_vector_info (struct gdbarch *@var{gdbarch}, struct ui_file *@var{file}, struct frame_info *@var{frame}, const char *@var{args})

3644

3645

Define this function to provide output about the vector unit and

3646

registers for the @value{GDBN} @kbd{info vector} command respectively.

3647

The default value is @code{NULL} (not defined), meaning no information

3648

will be provided.

3649

3650

The @var{gdbarch}, @var{file} and @var{frame} arguments have the

3651

same meaning as in the @code{print_registers_info} function above. The

3652

string @var{args} contains any supplementary arguments to the @kbd{info

3653

vector} command.

3654

3655

Define this function if the target supports vector operations.

3656

3657

@end deftypefn

3658

3659

@deftypefn {Architecture Function} int register_reggroup_p (struct gdbarch *@var{gdbarch}, int @var{regnum}, struct reggroup *@var{group})

3660

3661

@value{GDBN} groups registers into different categories (general,

3662

vector, floating point etc). This function, given a register,

3663

@var{regnum}, and group, @var{group}, returns 1 (true) if the register

3664

is in the group and 0 (false) otherwise.

3665

3666

The information should be for the specified architecture,

3667

@var{gdbarch}

3668

3669

The default value is the function @code{default_register_reggroup_p}

3670

which will do a reasonable job based on the type of the register (see

3671

the function @code{register_type} above), with groups for general

3672

purpose registers, floating point registers, vector registers and raw

3673

(i.e not pseudo) registers.

3674

3675

@end deftypefn

3676

3677

@node Register and Memory Data

3678

@subsection Using Different Register and Memory Data Representations

3679

@cindex register representation

3680

@cindex memory representation

3681

@cindex representations, register and memory

3682

@cindex register data formats, converting

3683

@cindex @code{struct value}, converting register contents to

3684

3685

Some architectures have different representations of data objects,

3686

depending whether the object is held in a register or memory. For

3687

example:

3688

3689

@itemize @bullet

3690

3691

@item

3692

The Alpha architecture can represent 32 bit integer values in

3693

floating-point registers.

3694

3695

@item

3696

The x86 architecture supports 80-bit floating-point registers. The

3697

@code{long double} data type occupies 96 bits in memory but only 80

3698

bits when stored in a register.

3699

3700

@end itemize

3701

3702

In general, the register representation of a data type is determined by

3703

the architecture, or @value{GDBN}'s interface to the architecture, while

3704

the memory representation is determined by the Application Binary

3705

Interface.

3706

3707

For almost all data types on almost all architectures, the two

3708

representations are identical, and no special handling is needed.

3709

However, they do occasionally differ. An architecture may define the

3710

following @code{struct gdbarch} functions to request conversions

3711

between the register and memory representations of a data type:

3712

3713

@deftypefn {Architecture Function} int gdbarch_convert_register_p (struct gdbarch *@var{gdbarch}, int @var{reg})

3714

3715

Return non-zero (true) if the representation of a data value stored in

3716

this register may be different to the representation of that same data

3717

value when stored in memory. The default value is @code{NULL}

3718

(undefined).

3719

3720

If this function is defined and returns non-zero, the @code{struct

3721

gdbarch} functions @code{gdbarch_register_to_value} and

3722

@code{gdbarch_value_to_register} (see below) should be used to perform

3723

any necessary conversion.

3724

3725

If defined, this function should return zero for the register's native

3726

type, when no conversion is necessary.

3727

@end deftypefn

3728

3729

@deftypefn {Architecture Function} void gdbarch_register_to_value (struct gdbarch *@var{gdbarch}, int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})

3730

3731

Convert the value of register number @var{reg} to a data object of

3732

type @var{type}. The buffer at @var{from} holds the register's value

3733

in raw format; the converted value should be placed in the buffer at

3734

@var{to}.

3735

3736

@quotation

3737

@emph{Note:} @code{gdbarch_register_to_value} and

3738

@code{gdbarch_value_to_register} take their @var{reg} and @var{type}

3739

arguments in different orders.

3740

@end quotation

3741

3742

@code{gdbarch_register_to_value} should only be used with registers

3743

for which the @code{gdbarch_convert_register_p} function returns a

3744

non-zero value.

3745

3746

@end deftypefn

3747

3748

@deftypefn {Architecture Function} void gdbarch_value_to_register (struct gdbarch *@var{gdbarch}, struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})

3749

3750

Convert a data value of type @var{type} to register number @var{reg}'

3751

raw format.

3752

3753

@quotation

3754

@emph{Note:} @code{gdbarch_register_to_value} and

3755

@code{gdbarch_value_to_register} take their @var{reg} and @var{type}

3756

arguments in different orders.

3757

@end quotation

3758

3759

@code{gdbarch_value_to_register} should only be used with registers

3760

for which the @code{gdbarch_convert_register_p} function returns a

3761

non-zero value.

3762

3763

@end deftypefn

3764

3765

@node Register Caching

3766

@subsection Register Caching

3767

@cindex register caching

3768

3769

Caching of registers is used, so that the target does not need to be

3770

accessed and reanalyzed multiple times for each register in

3771

circumstances where the register value cannot have changed.

3772

3773

@cindex @code{struct regcache}

3774

@value{GDBN} provides @code{struct regcache}, associated with a

3775

particular @code{struct gdbarch} to hold the cached values of the raw

3776

registers. A set of functions is provided to access both the raw

3777

registers (with @code{raw} in their name) and the full set of cooked

3778

registers (with @code{cooked} in their name). Functions are provided

3779

to ensure the register cache is kept synchronized with the values of

3780

the actual registers in the target.

3781

3782

Accessing registers through the @code{struct regcache} routines will

3783

ensure that the appropriate @code{struct gdbarch} functions are called

3784

when necessary to access the underlying target architecture. In general

3785

users should use the @dfn{cooked} functions, since these will map to the

3786

@dfn{raw} functions automatically as appropriate.

3787

3788

@findex regcache_cooked_read

3789

@findex regcache_cooked_write

3790

@cindex @code{gdb_byte}

3791

@findex regcache_cooked_read_signed

3792

@findex regcache_cooked_read_unsigned

3793

@findex regcache_cooked_write_signed

3794

@findex regcache_cooked_write_unsigned

3795

The two key functions are @code{regcache_cooked_read} and

3796

@code{regcache_cooked_write} which read or write a register from or to

3797

a byte buffer (type @code{gdb_byte *}). For convenience the wrapper

3798

functions @code{regcache_cooked_read_signed},

3799

@code{regcache_cooked_read_unsigned},

3800

@code{regcache_cooked_write_signed} and

3801

@code{regcache_cooked_write_unsigned} are provided, which read or

3802

write the value using the buffer and convert to or from an integral

3803

value as appropriate.

3804

3805

@node Frame Interpretation

3806

@section Frame Interpretation

3807

3808

@menu

3809

* All About Stack Frames::

3810

* Frame Handling Terminology::

3811

* Prologue Caches::

3812

* Functions and Variable to Analyze Frames::

3813

* Functions to Access Frame Data::

3814

* Analyzing Stacks---Frame Sniffers::

3815

@end menu

3816

3817

@node All About Stack Frames

3818

@subsection All About Stack Frames

3819

3820

@value{GDBN} needs to understand the stack on which local (automatic)

3821

variables are stored. The area of the stack containing all the local

3822

variables for a function invocation is known as the @dfn{stack frame}

3823

for that function (or colloquially just as the @dfn{frame}). In turn the

3824

function that called the function will have its stack frame, and so on

3825

back through the chain of functions that have been called.

3826

3827

Almost all architectures have one register dedicated to point to the

3828

end of the stack (the @dfn{stack pointer}). Many have a second register

3829

which points to the start of the currently active stack frame (the

3830

@dfn{frame pointer}). The specific arrangements for an architecture are

3831

a key part of the ABI.

3832

3833

A diagram helps to explain this. Here is a simple program to compute

3834

factorials:

3835

3836

@smallexample

3837

#include <stdio.h>

3838

int fact (int n)

3839

@{

3840

if (0 == n)

3841

@{

3842

return 1;

3843

@}

3844

else

3845

@{

3846

return n * fact (n - 1);

3847

@}

3848

@}

3849

3850

main ()

3851

@{

3852

int i;

3853

3854

for (i = 0; i < 10; i++)

3855

@{

3856

int f = fact (i);

3857

printf ("%d! = %d\n", i, f);

3858

@}

3859

@}

3860

@end smallexample

3861

3862

Consider the state of the stack when the code reaches line 6 after the

3863

main program has called @code{fact@w{ }(3)}. The chain of function

3864

calls will be @code{main ()}, @code{fact@w{ }(3)}, @code{fact@w{

3865

}(2)}, @code{@w{fact (1)}} and @code{fact@w{ }(0)}.

3866

3867

In this illustration the stack is falling (as used for example by the

3868

OpenRISC 1000 ABI). The stack pointer (SP) is at the end of the stack

3869

(lowest address) and the frame pointer (FP) is at the highest address

3870

in the current stack frame. The following diagram shows how the stack

3871

looks.

3872

3873

@center @image{stack_frame,14cm}

3874

3875

In each stack frame, offset 0 from the stack pointer is the frame

3876

pointer of the previous frame and offset 4 (this is illustrating a

3877

32-bit architecture) from the stack pointer is the return address.

3878

Local variables are indexed from the frame pointer, with negative

3879

indexes. In the function @code{fact}, offset -4 from the frame

3880

pointer is the argument @var{n}. In the @code{main} function, offset

3881

-4 from the frame pointer is the local variable @var{i} and offset -8

3882

from the frame pointer is the local variable @var{f}@footnote{This is

3883

a simplified example for illustrative purposes only. Good optimizing

3884

compilers would not put anything on the stack for such simple

3885

functions. Indeed they might eliminate the recursion and use of the

3886

stack entirely!}.

3887

3888

It is very easy to get confused when examining stacks. @value{GDBN}

3889

has terminology it uses rigorously throughout. The stack frame of the

3890

function currently executing, or where execution stopped is numbered

3891

zero. In this example frame #0 is the stack frame of the call to

3892

@code{fact@w{ }(0)}. The stack frame of its calling function

3893

(@code{fact@w{ }(1)} in this case) is numbered #1 and so on back

3894

through the chain of calls.

3895

3896

The main @value{GDBN} data structure describing frames is

3897

@code{@w{struct frame_info}}. It is not used directly, but only via

3898

its accessor functions. @code{frame_info} includes information about

3899

the registers in the frame and a pointer to the code of the function

3900

with which the frame is associated. The entire stack is represented as

3901

a linked list of @code{frame_info} structs.

3902

3903

@node Frame Handling Terminology

3904

@subsection Frame Handling Terminology

3905

3906

It is easy to get confused when referencing stack frames. @value{GDBN}

3907

uses some precise terminology.

3908

3909

@itemize @bullet

3910

3911

@item

3912

@cindex THIS frame

3913

@cindex stack frame, definition of THIS frame

3914

@cindex frame, definition of THIS frame

3915

@dfn{THIS} frame is the frame currently under consideration.

3916

3917

@item

3918

@cindex NEXT frame

3919

@cindex stack frame, definition of NEXT frame

3920

@cindex frame, definition of NEXT frame

3921

The @dfn{NEXT} frame, also sometimes called the inner or newer frame is the

3922

frame of the function called by the function of THIS frame.

3923

3924

@item

3925

@cindex PREVIOUS frame

3926

@cindex stack frame, definition of PREVIOUS frame

3927

@cindex frame, definition of PREVIOUS frame

3928

The @dfn{PREVIOUS} frame, also sometimes called the outer or older frame is

3929

the frame of the function which called the function of THIS frame.

3930

3931

@end itemize

3932

3933

So in the example in the previous section (@pxref{All About Stack

3934

Frames, , All About Stack Frames}), if THIS frame is #3 (the call to

3935

@code{fact@w{ }(3)}), the NEXT frame is frame #2 (the call to

3936

@code{fact@w{ }(2)}) and the PREVIOUS frame is frame #4 (the call to

3937

@code{main@w{ }()}).

3938

3939

@cindex innermost frame

3940

@cindex stack frame, definition of innermost frame

3941

@cindex frame, definition of innermost frame

3942

The @dfn{innermost} frame is the frame of the current executing

3943

function, or where the program stopped, in this example, in the middle

3944

of the call to @code{@w{fact (0))}}. It is always numbered frame #0.

3945

3946

@cindex base of a frame

3947

@cindex stack frame, definition of base of a frame

3948

@cindex frame, definition of base of a frame

3949

The @dfn{base} of a frame is the address immediately before the start

3950

of the NEXT frame. For a stack which grows down in memory (a

3951

@dfn{falling} stack) this will be the lowest address and for a stack

3952

which grows up in memory (a @dfn{rising} stack) this will be the

3953

highest address in the frame.

3954

3955

@value{GDBN} functions to analyze the stack are typically given a

3956

pointer to the NEXT frame to determine information about THIS

3957

frame. Information about THIS frame includes data on where the

3958

registers of the PREVIOUS frame are stored in this stack frame. In

3959

this example the frame pointer of the PREVIOUS frame is stored at

3960

offset 0 from the stack pointer of THIS frame.

3961

3962

@cindex unwinding

3963

@cindex stack frame, definition of unwinding

3964

@cindex frame, definition of unwinding

3965

The process whereby a function is given a pointer to the NEXT

3966

frame to work out information about THIS frame is referred to as

3967

@dfn{unwinding}. The @value{GDBN} functions involved in this typically

3968

include unwind in their name.

3969

3970

@cindex sniffing

3971

@cindex stack frame, definition of sniffing

3972

@cindex frame, definition of sniffing

3973

The process of analyzing a target to determine the information that

3974

should go in struct frame_info is called @dfn{sniffing}. The functions

3975

that carry this out are called sniffers and typically include sniffer

3976

in their name. More than one sniffer may be required to extract all

3977

the information for a particular frame.

3978

3979

@cindex sentinel frame

3980

@cindex stack frame, definition of sentinel frame

3981

@cindex frame, definition of sentinel frame

3982

Because so many functions work using the NEXT frame, there is an issue

3983

about addressing the innermost frame---it has no NEXT frame. To solve

3984

this @value{GDBN} creates a dummy frame #-1, known as the

3985

@dfn{sentinel} frame.

3986

3987

@node Prologue Caches

3988

@subsection Prologue Caches

3989

3990

@cindex function prologue

3991

@cindex prologue of a function

3992

All the frame sniffing functions typically examine the code at the

3993

start of the corresponding function, to determine the state of

3994

registers. The ABI will save old values and set new values of key

3995

registers at the start of each function in what is known as the

3996

function @dfn{prologue}.

3997

3998

@cindex prologue cache

3999

For any particular stack frame this data does not change, so all the

4000

standard unwinding functions, in addition to receiving a pointer to

4001

the NEXT frame as their first argument, receive a pointer to a

4002

@dfn{prologue cache} as their second argument. This can be used to store

4003

values associated with a particular frame, for reuse on subsequent

4004

calls involving the same frame.

4005

4006

It is up to the user to define the structure used (it is a

4007

@code{void@w{ }*} pointer) and arrange allocation and deallocation of

4008

storage. However for general use, @value{GDBN} provides

4009

@code{@w{struct trad_frame_cache}}, with a set of accessor

4010

routines. This structure holds the stack and code address of

4011

THIS frame, the base address of the frame, a pointer to the

4012

struct @code{frame_info} for the NEXT frame and details of

4013

where the registers of the PREVIOUS frame may be found in THIS

4014

frame.

4015

4016

Typically the first time any sniffer function is called with NEXT

4017

frame, the prologue sniffer for THIS frame will be @code{NULL}. The

4018

sniffer will analyze the frame, allocate a prologue cache structure

4019

and populate it. Subsequent calls using the same NEXT frame will

4020

pass in this prologue cache, so the data can be returned with no

4021

additional analysis.

4022

4023

@node Functions and Variable to Analyze Frames

4024

@subsection Functions and Variable to Analyze Frames

4025

4026

These struct @code{gdbarch} functions and variable should be defined

4027

to provide analysis of the stack frame and allow it to be adjusted as

4028

required.

4029

4030

@deftypefn {Architecture Function} CORE_ADDR skip_prologue (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{pc})

4031

4032

The prologue of a function is the code at the beginning of the

4033

function which sets up the stack frame, saves the return address

4034

etc. The code representing the behavior of the function starts after

4035

the prologue.

4036

4037

This function skips past the prologue of a function if the program

4038

counter, @var{pc}, is within the prologue of a function. The result is

4039

the program counter immediately after the prologue. With modern

4040

optimizing compilers, this may be a far from trivial exercise. However

4041

the required information may be within the binary as DWARF2 debugging

4042

information, making the job much easier.

4043

4044

The default value is @code{NULL} (not defined). This function should always

4045

be provided, but can take advantage of DWARF2 debugging information,

4046

if that is available.

4047

4048

@end deftypefn

4049

4050

@deftypefn {Architecture Function} int inner_than (CORE_ADDR @var{lhs}, CORE_ADDR @var{rhs})

4051

@findex core_addr_lessthan

4052

@findex core_addr_greaterthan

4053

4054

Given two frame or stack pointers, return non-zero (true) if the first

4055

represents the @dfn{inner} stack frame and 0 (false) otherwise. This

4056

is used to determine whether the target has a stack which grows up in

4057

memory (rising stack) or grows down in memory (falling stack).

4058

@xref{All About Stack Frames, , All About Stack Frames}, for an

4059

explanation of @dfn{inner} frames.

4060

4061

The default value of this function is @code{NULL} and it should always

4062

be defined. However for almost all architectures one of the built-in

4063

functions can be used: @code{core_addr_lessthan} (for stacks growing

4064

down in memory) or @code{core_addr_greaterthan} (for stacks growing up

4065

in memory).

4066

4067

@end deftypefn

4068

4069

@anchor{frame_align}

4070

@deftypefn {Architecture Function} CORE_ADDR frame_align (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{address})

4071

@findex align_down

4072

@findex align_up

4073

4074

The architecture may have constraints on how its frames are

4075

aligned. For example the OpenRISC 1000 ABI requires stack frames to be

4076

double-word aligned, but 32-bit versions of the architecture allocate

4077

single-word values to the stack. Thus extra padding may be needed at

4078

the end of a stack frame.

4079

4080

Given a proposed address for the stack pointer, this function

4081

returns a suitably aligned address (by expanding the stack frame).

4082

4083

The default value is @code{NULL} (undefined). This function should be defined

4084

for any architecture where it is possible the stack could become

4085

misaligned. The utility functions @code{align_down} (for falling

4086

stacks) and @code{align_up} (for rising stacks) will facilitate the

4087

implementation of this function.

4088

4089

@end deftypefn

4090

4091

@deftypevr {Architecture Variable} int frame_red_zone_size

4092

4093

Some ABIs reserve space beyond the end of the stack for use by leaf

4094

functions without prologue or epilogue or by exception handlers (for

4095

example the OpenRISC 1000).

4096

4097

This is known as a @dfn{red zone} (AMD terminology). The @sc{amd64}

4098

(nee x86-64) ABI documentation refers to the @dfn{red zone} when

4099

describing this scratch area.

4100

4101

The default value is 0. Set this field if the architecture has such a

4102

red zone. The value must be aligned as required by the ABI (see

4103

@code{frame_align} above for an explanation of stack frame alignment).

4104

4105

@end deftypevr

4106

4107

@node Functions to Access Frame Data

4108

@subsection Functions to Access Frame Data

4109

4110

These functions provide access to key registers and arguments in the

4111

stack frame.

4112

4113

@deftypefn {Architecture Function} CORE_ADDR unwind_pc (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame})

4114

4115

This function is given a pointer to the NEXT stack frame (@pxref{All

4116

About Stack Frames, , All About Stack Frames}, for how frames are

4117

represented) and returns the value of the program counter in the

4118

PREVIOUS frame (i.e.@: the frame of the function that called THIS

4119

one). This is commonly referred to as the @dfn{return address}.

4120

4121

The implementation, which must be frame agnostic (work with any frame),

4122

is typically no more than:

4123

4124

@smallexample

4125

ULONGEST pc;

4126

pc = frame_unwind_register_unsigned (next_frame, @var{ARCH}_PC_REGNUM);

4127

return gdbarch_addr_bits_remove (gdbarch, pc);

4128

@end smallexample

4129

4130

@end deftypefn

4131

4132

@deftypefn {Architecture Function} CORE_ADDR unwind_sp (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame})

4133

4134

This function is given a pointer to the NEXT stack frame

4135

(@pxref{All About Stack Frames, , All About Stack Frames} for how

4136

frames are represented) and returns the value of the stack pointer in

4137

the PREVIOUS frame (i.e.@: the frame of the function that called

4138

THIS one).

4139

4140

The implementation, which must be frame agnostic (work with any frame),

4141

is typically no more than:

4142

4143

@smallexample

4144

ULONGEST sp;

4145

sp = frame_unwind_register_unsigned (next_frame, @var{ARCH}_SP_REGNUM);

4146

return gdbarch_addr_bits_remove (gdbarch, sp);

4147

@end smallexample

4148

4149

@end deftypefn

4150

4151

@deftypefn {Architecture Function} int frame_num_args (struct gdbarch *@var{gdbarch}, struct frame_info *@var{this_frame})

4152

4153

This function is given a pointer to THIS stack frame (@pxref{All

4154

About Stack Frames, , All About Stack Frames} for how frames are

4155

represented), and returns the number of arguments that are being

4156

passed, or -1 if not known.

4157

4158

The default value is @code{NULL} (undefined), in which case the number of

4159

arguments passed on any stack frame is always unknown. For many

4160

architectures this will be a suitable default.

4161

4162

@end deftypefn

4163

4164

@node Analyzing Stacks---Frame Sniffers

4165

@subsection Analyzing Stacks---Frame Sniffers

4166

4167

When a program stops, @value{GDBN} needs to construct the chain of

4168

struct @code{frame_info} representing the state of the stack using

4169

appropriate @dfn{sniffers}.

4170

4171

Each architecture requires appropriate sniffers, but they do not form

4172

entries in @code{@w{struct gdbarch}}, since more than one sniffer may

4173

be required and a sniffer may be suitable for more than one

4174

@code{@w{struct gdbarch}}. Instead sniffers are associated with

4175

architectures using the following functions.

4176

4177

@itemize @bullet

4178

4179

@item

4180

@findex frame_unwind_append_sniffer

4181

@code{frame_unwind_append_sniffer} is used to add a new sniffer to

4182

analyze THIS frame when given a pointer to the NEXT frame.

4183

4184

@item

4185

@findex frame_base_append_sniffer

4186

@code{frame_base_append_sniffer} is used to add a new sniffer

4187

which can determine information about the base of a stack frame.

4188

4189

@item

4190

@findex frame_base_set_default

4191

@code{frame_base_set_default} is used to specify the default base

4192

sniffer.

4193

4194

@end itemize

4195

4196

These functions all take a reference to @code{@w{struct gdbarch}}, so

4197

they are associated with a specific architecture. They are usually

4198

called in the @code{gdbarch} initialization function, after the

4199

@code{gdbarch} struct has been set up. Unless a default has been set, the

4200

most recently appended sniffer will be tried first.

4201

4202

The main frame unwinding sniffer (as set by

4203

@code{frame_unwind_append_sniffer)} returns a structure specifying

4204

a set of sniffing functions:

4205

4206

@cindex @code{frame_unwind}

4207

@smallexample

4208

struct frame_unwind

4209

@{

4210

enum frame_type type;

4211

frame_this_id_ftype *this_id;

4212

frame_prev_register_ftype *prev_register;

4213

const struct frame_data *unwind_data;

4214

frame_sniffer_ftype *sniffer;

4215

frame_prev_pc_ftype *prev_pc;

4216

frame_dealloc_cache_ftype *dealloc_cache;

4217

@};

4218

@end smallexample

4219

4220

The @code{type} field indicates the type of frame this sniffer can

4221

handle: normal, dummy (@pxref{Functions Creating Dummy Frames, ,

4222

Functions Creating Dummy Frames}), signal handler or sentinel. Signal

4223

handlers sometimes have their own simplified stack structure for

4224

efficiency, so may need their own handlers.

4225

4226

The @code{unwind_data} field holds additional information which may be

4227

relevant to particular types of frame. For example it may hold

4228

additional information for signal handler frames.

4229

4230

The remaining fields define functions that yield different types of

4231

information when given a pointer to the NEXT stack frame. Not all

4232

functions need be provided. If an entry is @code{NULL}, the next sniffer will

4233

be tried instead.

4234

4235

@itemize @bullet

4236

4237

@item

4238

@code{this_id} determines the stack pointer and function (code

4239

entry point) for THIS stack frame.

4240

4241

@item

4242

@code{prev_register} determines where the values of registers for

4243

the PREVIOUS stack frame are stored in THIS stack frame.

4244

4245

@item

4246

@code{sniffer} takes a look at THIS frame's registers to

4247

determine if this is the appropriate unwinder.

4248

4249

@item

4250

@code{prev_pc} determines the program counter for THIS

4251

frame. Only needed if the program counter is not an ordinary register

4252

(@pxref{Register Architecture Functions & Variables,

4253

, Functions and Variables Specifying the Register Architecture}).

4254

4255

@item

4256

@code{dealloc_cache} frees any additional memory associated with

4257

the prologue cache for this frame (@pxref{Prologue Caches, , Prologue

4258

Caches}).

4259

4260

@end itemize

4261

4262

In general it is only the @code{this_id} and @code{prev_register}

4263

fields that need be defined for custom sniffers.

4264

4265

The frame base sniffer is much simpler. It is a @code{@w{struct

4266

frame_base}}, which refers to the corresponding @code{frame_unwind}

4267

struct and whose fields refer to functions yielding various addresses

4268

within the frame.

4269

4270

@cindex @code{frame_base}

4271

@smallexample

4272

struct frame_base

4273

@{

4274

const struct frame_unwind *unwind;

4275

frame_this_base_ftype *this_base;

4276

frame_this_locals_ftype *this_locals;

4277

frame_this_args_ftype *this_args;

4278

@};

4279

@end smallexample

4280

4281

All the functions referred to take a pointer to the NEXT frame as

4282

argument. The function referred to by @code{this_base} returns the

4283

base address of THIS frame, the function referred to by

4284

@code{this_locals} returns the base address of local variables in THIS

4285

frame and the function referred to by @code{this_args} returns the

4286

base address of the function arguments in this frame.

4287

4288

As described above, the base address of a frame is the address

4289

immediately before the start of the NEXT frame. For a falling

4290

stack, this is the lowest address in the frame and for a rising stack

4291

it is the highest address in the frame. For most architectures the

4292

same address is also the base address for local variables and

4293

arguments, in which case the same function can be used for all three

4294

entries@footnote{It is worth noting that if it cannot be determined in any

4295

other way (for example by there being a register with the name

4296

@code{"fp"}), then the result of the @code{this_base} function will be

4297

used as the value of the frame pointer variable @kbd{$fp} in

4298

@value{GDBN}. This is very often not correct (for example with the

4299

OpenRISC 1000, this value is the stack pointer, @kbd{$sp}). In this

4300

case a register (raw or pseudo) with the name @code{"fp"} should be

4301

defined. It will be used in preference as the value of @kbd{$fp}.}.

4302

4303

@node Inferior Call Setup

4304

@section Inferior Call Setup

4305

@cindex calls to the inferior

4306

4307

@menu

4308

* About Dummy Frames::

4309

* Functions Creating Dummy Frames::

4310

@end menu

4311

4312

@node About Dummy Frames

4313

@subsection About Dummy Frames

4314

@cindex dummy frames

4315

4316

@value{GDBN} can call functions in the target code (for example by

4317

using the @kbd{call} or @kbd{print} commands). These functions may be

4318

breakpointed, and it is essential that if a function does hit a

4319

breakpoint, commands like @kbd{backtrace} work correctly.

4320

4321

This is achieved by making the stack look as though the function had

4322

been called from the point where @value{GDBN} had previously stopped.

4323

This requires that @value{GDBN} can set up stack frames appropriate for

4324

such function calls.

4325

4326

@node Functions Creating Dummy Frames

4327

@subsection Functions Creating Dummy Frames

4328

4329

The following functions provide the functionality to set up such

4330

@dfn{dummy} stack frames.

4331

4332

@deftypefn {Architecture Function} CORE_ADDR push_dummy_call (struct gdbarch *@var{gdbarch}, struct value *@var{function}, struct regcache *@var{regcache}, CORE_ADDR @var{bp_addr}, int @var{nargs}, struct value **@var{args}, CORE_ADDR @var{sp}, int @var{struct_return}, CORE_ADDR @var{struct_addr})

4333

4334

This function sets up a dummy stack frame for the function about to be

4335

called. @code{push_dummy_call} is given the arguments to be passed

4336

and must copy them into registers or push them on to the stack as

4337

appropriate for the ABI.

4338

4339

@var{function} is a pointer to the function

4340

that will be called and @var{regcache} the register cache from which

4341

values should be obtained. @var{bp_addr} is the address to which the

4342

function should return (which is breakpointed, so @value{GDBN} can

4343

regain control, hence the name). @var{nargs} is the number of

4344

arguments to pass and @var{args} an array containing the argument

4345

values. @var{struct_return} is non-zero (true) if the function returns

4346

a structure, and if so @var{struct_addr} is the address in which the

4347

structure should be returned.

4348

4349

After calling this function, @value{GDBN} will pass control to the

4350

target at the address of the function, which will find the stack and

4351

registers set up just as expected.

4352

4353

The default value of this function is @code{NULL} (undefined). If the

4354

function is not defined, then @value{GDBN} will not allow the user to

4355

call functions within the target being debugged.

4356

4357

@end deftypefn

4358

4359

@deftypefn {Architecture Function} {struct frame_id} unwind_dummy_id (struct gdbarch *@var{gdbarch}, struct frame_info *@var{next_frame})

4360

4361

This is the inverse of @code{push_dummy_call} which restores the stack

4362

pointer and program counter after a call to evaluate a function using

4363

a dummy stack frame. The result is a @code{@w{struct frame_id}}, which

4364

contains the value of the stack pointer and program counter to be

4365

used.

4366

4367

The NEXT frame pointer is provided as argument,

4368

@var{next_frame}. THIS frame is the frame of the dummy function,

4369

which can be unwound, to yield the required stack pointer and program

4370

counter from the PREVIOUS frame.

4371

4372

The default value is @code{NULL} (undefined). If @code{push_dummy_call} is

4373

defined, then this function should also be defined.

4374

4375

@end deftypefn

4376

4377

@deftypefn {Architecture Function} CORE_ADDR push_dummy_code (struct gdbarch *@var{gdbarch}, CORE_ADDR @var{sp}, CORE_ADDR @var{funaddr}, struct value **@var{args}, int @var{nargs}, struct type *@var{value_type}, CORE_ADDR *@var{real_pc}, CORE_ADDR *@var{bp_addr}, struct regcache *@var{regcache})

4378

4379

If this function is not defined (its default value is @code{NULL}), a dummy

4380

call will use the entry point of the currently loaded code on the

4381

target as its return address. A temporary breakpoint will be set

4382

there, so the location must be writable and have room for a

4383

breakpoint.

4384

4385

It is possible that this default is not suitable. It might not be

4386

writable (in ROM possibly), or the ABI might require code to be

4387

executed on return from a call to unwind the stack before the

4388

breakpoint is encountered.

4389

4390

If either of these is the case, then push_dummy_code should be defined

4391

to push an instruction sequence onto the end of the stack to which the

4392

dummy call should return.

4393

4394

The arguments are essentially the same as those to

4395

@code{push_dummy_call}. However the function is provided with the

4396

type of the function result, @var{value_type}, @var{bp_addr} is used

4397

to return a value (the address at which the breakpoint instruction

4398

should be inserted) and @var{real pc} is used to specify the resume

4399

address when starting the call sequence. The function should return

4400

the updated innermost stack address.

4401

4402

@quotation

4403

@emph{Note:} This does require that code in the stack can be executed.

4404

Some Harvard architectures may not allow this.

4405

@end quotation

4406

4407

@end deftypefn

4408

4409

@node Adding support for debugging core files

4410

@section Adding support for debugging core files

4411

@cindex core files

4412

4413

The prerequisite for adding core file support in @value{GDBN} is to have

4414

core file support in BFD.

4415

4416

Once BFD support is available, writing the apropriate

4417

@code{regset_from_core_section} architecture function should be all

4418

that is needed in order to add support for core files in @value{GDBN}.

4419

4420

@node Defining Other Architecture Features

4421

@section Defining Other Architecture Features

4422

4423

This section describes other functions and values in @code{gdbarch},

4424

together with some useful macros, that you can use to define the

4425

target architecture.

4426

4427

@table @code

4428

4429

@item CORE_ADDR gdbarch_addr_bits_remove (@var{gdbarch}, @var{addr})

4430

@findex gdbarch_addr_bits_remove

4431

If a raw machine instruction address includes any bits that are not

4432

really part of the address, then this function is used to zero those bits in

4433

@var{addr}. This is only used for addresses of instructions, and even then not

4434

in all contexts.

4435

4436

For example, the two low-order bits of the PC on the Hewlett-Packard PA

4437

2.0 architecture contain the privilege level of the corresponding

4438

instruction. Since instructions must always be aligned on four-byte

4439

boundaries, the processor masks out these bits to generate the actual

4440

address of the instruction. @code{gdbarch_addr_bits_remove} would then for

4441

example look like that:

4442

@smallexample

4443

arch_addr_bits_remove (CORE_ADDR addr)

4444

@{

4445

return (addr &= ~0x3);

4446

@}

4447

@end smallexample

4448

4449

@item int address_class_name_to_type_flags (@var{gdbarch}, @var{name}, @var{type_flags_ptr})

4450

@findex address_class_name_to_type_flags

4451

If @var{name} is a valid address class qualifier name, set the @code{int}

4452

referenced by @var{type_flags_ptr} to the mask representing the qualifier

4453

and return 1. If @var{name} is not a valid address class qualifier name,

4454

return 0.

4455

4456

The value for @var{type_flags_ptr} should be one of

4457

@code{TYPE_FLAG_ADDRESS_CLASS_1}, @code{TYPE_FLAG_ADDRESS_CLASS_2}, or

4458

possibly some combination of these values or'd together.

4459

@xref{Target Architecture Definition, , Address Classes}.

4460

4461

@item int address_class_name_to_type_flags_p (@var{gdbarch})

4462

@findex address_class_name_to_type_flags_p

4463

Predicate which indicates whether @code{address_class_name_to_type_flags}

4464

has been defined.

4465

4466

@item int gdbarch_address_class_type_flags (@var{gdbarch}, @var{byte_size}, @var{dwarf2_addr_class})

4467

@findex gdbarch_address_class_type_flags

4468

Given a pointers byte size (as described by the debug information) and

4469

the possible @code{DW_AT_address_class} value, return the type flags

4470

used by @value{GDBN} to represent this address class. The value

4471

returned should be one of @code{TYPE_FLAG_ADDRESS_CLASS_1},

4472

@code{TYPE_FLAG_ADDRESS_CLASS_2}, or possibly some combination of these

4473

values or'd together.

4474

@xref{Target Architecture Definition, , Address Classes}.

4475

4476

@item int gdbarch_address_class_type_flags_p (@var{gdbarch})

4477

@findex gdbarch_address_class_type_flags_p

4478

Predicate which indicates whether @code{gdbarch_address_class_type_flags_p} has

4479

been defined.

4480

4481

@item const char *gdbarch_address_class_type_flags_to_name (@var{gdbarch}, @var{type_flags})

4482

@findex gdbarch_address_class_type_flags_to_name

4483

Return the name of the address class qualifier associated with the type

4484

flags given by @var{type_flags}.

4485

4486

@item int gdbarch_address_class_type_flags_to_name_p (@var{gdbarch})

4487

@findex gdbarch_address_class_type_flags_to_name_p

4488

Predicate which indicates whether @code{gdbarch_address_class_type_flags_to_name} has been defined.

4489

@xref{Target Architecture Definition, , Address Classes}.

4490

4491

@item void gdbarch_address_to_pointer (@var{gdbarch}, @var{type}, @var{buf}, @var{addr})

4492

@findex gdbarch_address_to_pointer

4493

Store in @var{buf} a pointer of type @var{type} representing the address

4494

@var{addr}, in the appropriate format for the current architecture.

4495

This function may safely assume that @var{type} is either a pointer or a

4496

C@t{++} reference type.

4497

@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.

4498

4499

@item int gdbarch_believe_pcc_promotion (@var{gdbarch})

4500

@findex gdbarch_believe_pcc_promotion

4501

Used to notify if the compiler promotes a @code{short} or @code{char}

4502

parameter to an @code{int}, but still reports the parameter as its

4503

original type, rather than the promoted type.

4504

4505

@item gdbarch_bits_big_endian (@var{gdbarch})

4506

@findex gdbarch_bits_big_endian

4507

This is used if the numbering of bits in the targets does @strong{not} match

4508

the endianism of the target byte order. A value of 1 means that the bits

4509

are numbered in a big-endian bit order, 0 means little-endian.

4510

4511

@item set_gdbarch_bits_big_endian (@var{gdbarch}, @var{bits_big_endian})

4512

@findex set_gdbarch_bits_big_endian

4513

Calling set_gdbarch_bits_big_endian with a value of 1 indicates that the

4514

bits in the target are numbered in a big-endian bit order, 0 indicates

4515

little-endian.

4516

4517

@item BREAKPOINT

4518

@findex BREAKPOINT

4519

This is the character array initializer for the bit pattern to put into

4520

memory where a breakpoint is set. Although it's common to use a trap

4521

instruction for a breakpoint, it's not required; for instance, the bit

4522

pattern could be an invalid instruction. The breakpoint must be no

4523

longer than the shortest instruction of the architecture.

4524

4525

@code{BREAKPOINT} has been deprecated in favor of

4526

@code{gdbarch_breakpoint_from_pc}.

4527

4528

@item BIG_BREAKPOINT

4529

@itemx LITTLE_BREAKPOINT

4530

@findex LITTLE_BREAKPOINT

4531

@findex BIG_BREAKPOINT

4532

Similar to BREAKPOINT, but used for bi-endian targets.

4533

4534

@code{BIG_BREAKPOINT} and @code{LITTLE_BREAKPOINT} have been deprecated in

4535

favor of @code{gdbarch_breakpoint_from_pc}.

4536

4537

@item const gdb_byte *gdbarch_breakpoint_from_pc (@var{gdbarch}, @var{pcptr}, @var{lenptr})

4538

@findex gdbarch_breakpoint_from_pc

4539

@anchor{gdbarch_breakpoint_from_pc} Use the program counter to determine the

4540

contents and size of a breakpoint instruction. It returns a pointer to

4541

a static string of bytes that encode a breakpoint instruction, stores the

4542

length of the string to @code{*@var{lenptr}}, and adjusts the program

4543

counter (if necessary) to point to the actual memory location where the

4544

breakpoint should be inserted. May return @code{NULL} to indicate that

4545

software breakpoints are not supported.

4546

4547

Although it is common to use a trap instruction for a breakpoint, it's

4548

not required; for instance, the bit pattern could be an invalid

4549

instruction. The breakpoint must be no longer than the shortest

4550

instruction of the architecture.

4551

4552

Provided breakpoint bytes can be also used by @code{bp_loc_is_permanent} to

4553

detect permanent breakpoints. @code{gdbarch_breakpoint_from_pc} should return

4554

an unchanged memory copy if it was called for a location with permanent

4555

breakpoint as some architectures use breakpoint instructions containing

4556

arbitrary parameter value.

4557

4558

Replaces all the other @var{BREAKPOINT} macros.

4559

4560

@item int gdbarch_memory_insert_breakpoint (@var{gdbarch}, @var{bp_tgt})

4561

@itemx gdbarch_memory_remove_breakpoint (@var{gdbarch}, @var{bp_tgt})

4562

@findex gdbarch_memory_remove_breakpoint

4563

@findex gdbarch_memory_insert_breakpoint

4564

Insert or remove memory based breakpoints. Reasonable defaults

4565

(@code{default_memory_insert_breakpoint} and

4566

@code{default_memory_remove_breakpoint} respectively) have been

4567

provided so that it is not necessary to set these for most

4568

architectures. Architectures which may want to set

4569

@code{gdbarch_memory_insert_breakpoint} and @code{gdbarch_memory_remove_breakpoint} will likely have instructions that are oddly sized or are not stored in a

4570

conventional manner.

4571

4572

It may also be desirable (from an efficiency standpoint) to define

4573

custom breakpoint insertion and removal routines if

4574

@code{gdbarch_breakpoint_from_pc} needs to read the target's memory for some

4575

reason.

4576

4577

@item CORE_ADDR gdbarch_adjust_breakpoint_address (@var{gdbarch}, @var{bpaddr})

4578

@findex gdbarch_adjust_breakpoint_address

4579

@cindex breakpoint address adjusted

4580

Given an address at which a breakpoint is desired, return a breakpoint

4581

address adjusted to account for architectural constraints on

4582

breakpoint placement. This method is not needed by most targets.

4583

4584

The FR-V target (see @file{frv-tdep.c}) requires this method.

4585

The FR-V is a VLIW architecture in which a number of RISC-like

4586

instructions are grouped (packed) together into an aggregate

4587

instruction or instruction bundle. When the processor executes

4588

one of these bundles, the component instructions are executed

4589

in parallel.

4590

4591

In the course of optimization, the compiler may group instructions

4592

from distinct source statements into the same bundle. The line number

4593

information associated with one of the latter statements will likely

4594

refer to some instruction other than the first one in the bundle. So,

4595

if the user attempts to place a breakpoint on one of these latter

4596

statements, @value{GDBN} must be careful to @emph{not} place the break

4597

instruction on any instruction other than the first one in the bundle.

4598

(Remember though that the instructions within a bundle execute

4599

in parallel, so the @emph{first} instruction is the instruction

4600

at the lowest address and has nothing to do with execution order.)

4601

4602

The FR-V's @code{gdbarch_adjust_breakpoint_address} method will adjust a

4603

breakpoint's address by scanning backwards for the beginning of

4604

the bundle, returning the address of the bundle.

4605

4606

Since the adjustment of a breakpoint may significantly alter a user's

4607

expectation, @value{GDBN} prints a warning when an adjusted breakpoint

4608

is initially set and each time that that breakpoint is hit.

4609

4610

@item int gdbarch_call_dummy_location (@var{gdbarch})

4611

@findex gdbarch_call_dummy_location

4612

See the file @file{inferior.h}.

4613

4614

This method has been replaced by @code{gdbarch_push_dummy_code}

4615

(@pxref{gdbarch_push_dummy_code}).

4616

4617

@item int gdbarch_cannot_fetch_register (@var{gdbarch}, @var{regum})

4618

@findex gdbarch_cannot_fetch_register

4619

This function should return nonzero if @var{regno} cannot be fetched

4620

from an inferior process.

4621

4622

@item int gdbarch_cannot_store_register (@var{gdbarch}, @var{regnum})

4623

@findex gdbarch_cannot_store_register

4624

This function should return nonzero if @var{regno} should not be

4625

written to the target. This is often the case for program counters,

4626

status words, and other special registers. This function returns 0 as

4627

default so that @value{GDBN} will assume that all registers may be written.

4628

4629

@item int gdbarch_convert_register_p (@var{gdbarch}, @var{regnum}, struct type *@var{type})

4630

@findex gdbarch_convert_register_p

4631

Return non-zero if register @var{regnum} represents data values of type

4632

@var{type} in a non-standard form.

4633

@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.

4634

4635

@item int gdbarch_fp0_regnum (@var{gdbarch})

4636

@findex gdbarch_fp0_regnum

4637

This function returns the number of the first floating point register,

4638

if the machine has such registers. Otherwise, it returns -1.

4639

4640

@item CORE_ADDR gdbarch_decr_pc_after_break (@var{gdbarch})

4641

@findex gdbarch_decr_pc_after_break

4642

This function shall return the amount by which to decrement the PC after the

4643

program encounters a breakpoint. This is often the number of bytes in

4644

@code{BREAKPOINT}, though not always. For most targets this value will be 0.

4645

4646

@item DISABLE_UNSETTABLE_BREAK (@var{addr})

4647

@findex DISABLE_UNSETTABLE_BREAK

4648

If defined, this should evaluate to 1 if @var{addr} is in a shared

4649

library in which breakpoints cannot be set and so should be disabled.

4650

4651

@item int gdbarch_dwarf2_reg_to_regnum (@var{gdbarch}, @var{dwarf2_regnr})

4652

@findex gdbarch_dwarf2_reg_to_regnum

4653

Convert DWARF2 register number @var{dwarf2_regnr} into @value{GDBN} regnum.

4654

If not defined, no conversion will be performed.

4655

4656

@item int gdbarch_ecoff_reg_to_regnum (@var{gdbarch}, @var{ecoff_regnr})

4657

@findex gdbarch_ecoff_reg_to_regnum

4658

Convert ECOFF register number @var{ecoff_regnr} into @value{GDBN} regnum. If

4659

not defined, no conversion will be performed.

4660

4661

@item GCC_COMPILED_FLAG_SYMBOL

4662

@itemx GCC2_COMPILED_FLAG_SYMBOL

4663

@findex GCC2_COMPILED_FLAG_SYMBOL

4664

@findex GCC_COMPILED_FLAG_SYMBOL

4665

If defined, these are the names of the symbols that @value{GDBN} will

4666

look for to detect that GCC compiled the file. The default symbols

4667

are @code{gcc_compiled.} and @code{gcc2_compiled.},

4668

respectively. (Currently only defined for the Delta 68.)

4669

4670

@item gdbarch_get_longjmp_target

4671

@findex gdbarch_get_longjmp_target

4672

This function determines the target PC address that @code{longjmp}

4673

will jump to, assuming that we have just stopped at a @code{longjmp}

4674

breakpoint. It takes a @code{CORE_ADDR *} as argument, and stores the

4675

target PC value through this pointer. It examines the current state

4676

of the machine as needed, typically by using a manually-determined

4677

offset into the @code{jmp_buf}. (While we might like to get the offset

4678

from the target's @file{jmpbuf.h}, that header file cannot be assumed

4679

to be available when building a cross-debugger.)

4680

4681

@item DEPRECATED_IBM6000_TARGET

4682

@findex DEPRECATED_IBM6000_TARGET

4683

Shows that we are configured for an IBM RS/6000 system. This

4684

conditional should be eliminated (FIXME) and replaced by

4685

feature-specific macros. It was introduced in haste and we are

4686

repenting at leisure.

4687

4688

@item I386_USE_GENERIC_WATCHPOINTS

4689

An x86-based target can define this to use the generic x86 watchpoint

4690

support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.

4691

4692

@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{addr})

4693

@findex gdbarch_in_function_epilogue_p

4694

Returns non-zero if the given @var{addr} is in the epilogue of a function.

4695

The epilogue of a function is defined as the part of a function where

4696

the stack frame of the function already has been destroyed up to the

4697

final `return from function call' instruction.

4698

4699

@item int gdbarch_in_solib_return_trampoline (@var{gdbarch}, @var{pc}, @var{name})

4700

@findex gdbarch_in_solib_return_trampoline

4701

Define this function to return nonzero if the program is stopped in the

4702

trampoline that returns from a shared library.

4703

4704

@item target_so_ops.in_dynsym_resolve_code (@var{pc})

4705

@findex in_dynsym_resolve_code

4706

Define this to return nonzero if the program is stopped in the

4707

dynamic linker.

4708

4709

@item SKIP_SOLIB_RESOLVER (@var{pc})

4710

@findex SKIP_SOLIB_RESOLVER

4711

Define this to evaluate to the (nonzero) address at which execution

4712

should continue to get past the dynamic linker's symbol resolution

4713

function. A zero value indicates that it is not important or necessary

4714

to set a breakpoint to get through the dynamic linker and that single

4715

stepping will suffice.

4716

4717

@item CORE_ADDR gdbarch_integer_to_address (@var{gdbarch}, @var{type}, @var{buf})

4718

@findex gdbarch_integer_to_address

4719

@cindex converting integers to addresses

4720

Define this when the architecture needs to handle non-pointer to address

4721

conversions specially. Converts that value to an address according to

4722

the current architectures conventions.

4723

4724

@emph{Pragmatics: When the user copies a well defined expression from

4725

their source code and passes it, as a parameter, to @value{GDBN}'s

4726

@code{print} command, they should get the same value as would have been

4727

computed by the target program. Any deviation from this rule can cause

4728

major confusion and annoyance, and needs to be justified carefully. In

4729

other words, @value{GDBN} doesn't really have the freedom to do these

4730

conversions in clever and useful ways. It has, however, been pointed

4731

out that users aren't complaining about how @value{GDBN} casts integers

4732

to pointers; they are complaining that they can't take an address from a

4733

disassembly listing and give it to @code{x/i}. Adding an architecture

4734

method like @code{gdbarch_integer_to_address} certainly makes it possible for

4735

@value{GDBN} to ``get it right'' in all circumstances.}

4736

4737

@xref{Target Architecture Definition, , Pointers Are Not Always

4738

Addresses}.

4739

4740

@item CORE_ADDR gdbarch_pointer_to_address (@var{gdbarch}, @var{type}, @var{buf})

4741

@findex gdbarch_pointer_to_address

4742

Assume that @var{buf} holds a pointer of type @var{type}, in the

4743

appropriate format for the current architecture. Return the byte

4744

address the pointer refers to.

4745

@xref{Target Architecture Definition, , Pointers Are Not Always Addresses}.

4746

4747

@item void gdbarch_register_to_value(@var{gdbarch}, @var{frame}, @var{regnum}, @var{type}, @var{fur})

4748

@findex gdbarch_register_to_value

4749

Convert the raw contents of register @var{regnum} into a value of type

4750

@var{type}.

4751

@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.

4752

4753

@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})

4754

@findex REGISTER_CONVERT_TO_VIRTUAL

4755

Convert the value of register @var{reg} from its raw form to its virtual

4756

form.

4757

@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.

4758

4759

@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})

4760

@findex REGISTER_CONVERT_TO_RAW

4761

Convert the value of register @var{reg} from its virtual form to its raw

4762

form.

4763

@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.

4764

4765

@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size})

4766

@findex regset_from_core_section

4767

Return the appropriate register set for a core file section with name

4768

@var{sect_name} and size @var{sect_size}.

4769

4770

@item SOFTWARE_SINGLE_STEP_P()

4771

@findex SOFTWARE_SINGLE_STEP_P

4772

Define this as 1 if the target does not have a hardware single-step

4773

mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.

4774

4775

@item SOFTWARE_SINGLE_STEP(@var{signal}, @var{insert_breakpoints_p})

4776

@findex SOFTWARE_SINGLE_STEP

4777

A function that inserts or removes (depending on

4778

@var{insert_breakpoints_p}) breakpoints at each possible destinations of

4779

the next instruction. See @file{sparc-tdep.c} and @file{rs6000-tdep.c}

4780

for examples.

4781

4782

@item set_gdbarch_sofun_address_maybe_missing (@var{gdbarch}, @var{set})

4783

@findex set_gdbarch_sofun_address_maybe_missing

4784

Somebody clever observed that, the more actual addresses you have in the

4785

debug information, the more time the linker has to spend relocating

4786

them. So whenever there's some other way the debugger could find the

4787

address it needs, you should omit it from the debug info, to make

4788

linking faster.

4789

4790

Calling @code{set_gdbarch_sofun_address_maybe_missing} with a non-zero

4791

argument @var{set} indicates that a particular set of hacks of this sort

4792

are in use, affecting @code{N_SO} and @code{N_FUN} entries in stabs-format

4793

debugging information. @code{N_SO} stabs mark the beginning and ending

4794

addresses of compilation units in the text segment. @code{N_FUN} stabs

4795

mark the starts and ends of functions.

4796

4797

In this case, @value{GDBN} assumes two things:

4798

4799

@itemize @bullet

4800

@item

4801

@code{N_FUN} stabs have an address of zero. Instead of using those

4802

addresses, you should find the address where the function starts by

4803

taking the function name from the stab, and then looking that up in the

4804

minsyms (the linker/assembler symbol table). In other words, the stab

4805

has the name, and the linker/assembler symbol table is the only place

4806

that carries the address.

4807

4808

@item

4809

@code{N_SO} stabs have an address of zero, too. You just look at the

4810

@code{N_FUN} stabs that appear before and after the @code{N_SO} stab, and

4811

guess the starting and ending addresses of the compilation unit from them.

4812

@end itemize

4813

4814

@item int gdbarch_stabs_argument_has_addr (@var{gdbarch}, @var{type})

4815

@findex gdbarch_stabs_argument_has_addr

4816

@anchor{gdbarch_stabs_argument_has_addr} Define this function to return

4817

nonzero if a function argument of type @var{type} is passed by reference

4818

instead of value.

4819

4820

@item CORE_ADDR gdbarch_push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{bp_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})

4821

@findex gdbarch_push_dummy_call

4822

@anchor{gdbarch_push_dummy_call} Define this to push the dummy frame's call to

4823

the inferior function onto the stack. In addition to pushing @var{nargs}, the

4824

code should push @var{struct_addr} (when @var{struct_return} is non-zero), and

4825

the return address (@var{bp_addr}).

4826

4827

@var{function} is a pointer to a @code{struct value}; on architectures that use

4828

function descriptors, this contains the function descriptor value.

4829

4830

Returns the updated top-of-stack pointer.

4831

4832

@item CORE_ADDR gdbarch_push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr}, @var{regcache})

4833

@findex gdbarch_push_dummy_code

4834

@anchor{gdbarch_push_dummy_code} Given a stack based call dummy, push the

4835

instruction sequence (including space for a breakpoint) to which the

4836

called function should return.

4837

4838

Set @var{bp_addr} to the address at which the breakpoint instruction

4839

should be inserted, @var{real_pc} to the resume address when starting

4840

the call sequence, and return the updated inner-most stack address.

4841

4842

By default, the stack is grown sufficient to hold a frame-aligned

4843

(@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address

4844

reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}.

4845

4846

This method replaces @w{@code{gdbarch_call_dummy_location (@var{gdbarch})}}.

4847

4848

@item int gdbarch_sdb_reg_to_regnum (@var{gdbarch}, @var{sdb_regnr})

4849

@findex gdbarch_sdb_reg_to_regnum

4850

Use this function to convert sdb register @var{sdb_regnr} into @value{GDBN}

4851

regnum. If not defined, no conversion will be done.

4852

4853

@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf})

4854

@findex gdbarch_return_value

4855

@anchor{gdbarch_return_value} Given a function with a return-value of

4856

type @var{rettype}, return which return-value convention that function

4857

would use.

4858

4859

@value{GDBN} currently recognizes two function return-value conventions:

4860

@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found

4861

in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return

4862

value is found in memory and the address of that memory location is

4863

passed in as the function's first parameter.

4864

4865

If the register convention is being used, and @var{writebuf} is

4866

non-@code{NULL}, also copy the return-value in @var{writebuf} into

4867

@var{regcache}.

4868

4869

If the register convention is being used, and @var{readbuf} is

4870

non-@code{NULL}, also copy the return value from @var{regcache} into

4871

@var{readbuf} (@var{regcache} contains a copy of the registers from the

4872

just returned function).

4873

4874

@emph{Maintainer note: This method replaces separate predicate, extract,

4875

store methods. By having only one method, the logic needed to determine

4876

the return-value convention need only be implemented in one place. If

4877

@value{GDBN} were written in an @sc{oo} language, this method would

4878

instead return an object that knew how to perform the register

4879

return-value extract and store.}

4880

4881

@emph{Maintainer note: This method does not take a @var{gcc_p}

4882

parameter, and such a parameter should not be added. If an architecture

4883

that requires per-compiler or per-function information be identified,

4884

then the replacement of @var{rettype} with @code{struct value}

4885

@var{function} should be pursued.}

4886

4887

@emph{Maintainer note: The @var{regcache} parameter limits this methods

4888

to the inner most frame. While replacing @var{regcache} with a

4889

@code{struct frame_info} @var{frame} parameter would remove that

4890

limitation there has yet to be a demonstrated need for such a change.}

4891

4892

@item void gdbarch_skip_permanent_breakpoint (@var{gdbarch}, @var{regcache})

4893

@findex gdbarch_skip_permanent_breakpoint

4894

Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally

4895

steps over a breakpoint by removing it, stepping one instruction, and

4896

re-inserting the breakpoint. However, permanent breakpoints are

4897

hardwired into the inferior, and can't be removed, so this strategy

4898

doesn't work. Calling @code{gdbarch_skip_permanent_breakpoint} adjusts the

4899

processor's state so that execution will resume just after the breakpoint.

4900

This function does the right thing even when the breakpoint is in the delay slot

4901

of a branch or jump.

4902

4903

@item CORE_ADDR gdbarch_skip_trampoline_code (@var{gdbarch}, @var{frame}, @var{pc})

4904

@findex gdbarch_skip_trampoline_code

4905

If the target machine has trampoline code that sits between callers and

4906

the functions being called, then define this function to return a new PC

4907

that is at the start of the real function.

4908

4909

@item int gdbarch_deprecated_fp_regnum (@var{gdbarch})

4910

@findex gdbarch_deprecated_fp_regnum

4911

If the frame pointer is in a register, use this function to return the

4912

number of that register.

4913

4914

@item int gdbarch_stab_reg_to_regnum (@var{gdbarch}, @var{stab_regnr})

4915

@findex gdbarch_stab_reg_to_regnum

4916

Use this function to convert stab register @var{stab_regnr} into @value{GDBN}

4917

regnum. If not defined, no conversion will be done.

4918

4919

@item SYMBOL_RELOADING_DEFAULT

4920

@findex SYMBOL_RELOADING_DEFAULT

4921

The default value of the ``symbol-reloading'' variable. (Never defined in

4922

current sources.)

4923

4924

@item TARGET_CHAR_BIT

4925

@findex TARGET_CHAR_BIT

4926

Number of bits in a char; defaults to 8.

4927

4928

@item int gdbarch_char_signed (@var{gdbarch})

4929

@findex gdbarch_char_signed

4930

Non-zero if @code{char} is normally signed on this architecture; zero if

4931

it should be unsigned.

4932

4933

The ISO C standard requires the compiler to treat @code{char} as

4934

equivalent to either @code{signed char} or @code{unsigned char}; any

4935

character in the standard execution set is supposed to be positive.

4936

Most compilers treat @code{char} as signed, but @code{char} is unsigned

4937

on the IBM S/390, RS6000, and PowerPC targets.

4938

4939

@item int gdbarch_double_bit (@var{gdbarch})

4940

@findex gdbarch_double_bit

4941

Number of bits in a double float; defaults to @w{@code{8 * TARGET_CHAR_BIT}}.

4942

4943

@item int gdbarch_float_bit (@var{gdbarch})

4944

@findex gdbarch_float_bit

4945

Number of bits in a float; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.

4946

4947

@item int gdbarch_int_bit (@var{gdbarch})

4948

@findex gdbarch_int_bit

4949

Number of bits in an integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.

4950

4951

@item int gdbarch_long_bit (@var{gdbarch})

4952

@findex gdbarch_long_bit

4953

Number of bits in a long integer; defaults to @w{@code{4 * TARGET_CHAR_BIT}}.

4954

4955

@item int gdbarch_long_double_bit (@var{gdbarch})

4956

@findex gdbarch_long_double_bit

4957

Number of bits in a long double float;

4958

defaults to @w{@code{2 * gdbarch_double_bit (@var{gdbarch})}}.

4959

4960

@item int gdbarch_long_long_bit (@var{gdbarch})

4961

@findex gdbarch_long_long_bit

4962

Number of bits in a long long integer; defaults to

4963

@w{@code{2 * gdbarch_long_bit (@var{gdbarch})}}.

4964

4965

@item int gdbarch_ptr_bit (@var{gdbarch})

4966

@findex gdbarch_ptr_bit

4967

Number of bits in a pointer; defaults to

4968

@w{@code{gdbarch_int_bit (@var{gdbarch})}}.

4969

4970

@item int gdbarch_short_bit (@var{gdbarch})

4971

@findex gdbarch_short_bit

4972

Number of bits in a short integer; defaults to @w{@code{2 * TARGET_CHAR_BIT}}.

4973

4974

@item void gdbarch_virtual_frame_pointer (@var{gdbarch}, @var{pc}, @var{frame_regnum}, @var{frame_offset})

4975

@findex gdbarch_virtual_frame_pointer

4976

Returns a @code{(@var{register}, @var{offset})} pair representing the virtual

4977

frame pointer in use at the code address @var{pc}. If virtual frame

4978

pointers are not used, a default definition simply returns

4979

@code{gdbarch_deprecated_fp_regnum} (or @code{gdbarch_sp_regnum}, if

4980

no frame pointer is defined), with an offset of zero.

4981

4982

@c need to explain virtual frame pointers, they are recorded in agent

4983

@c expressions for tracepoints

4984

4985

@item TARGET_HAS_HARDWARE_WATCHPOINTS

4986

If non-zero, the target has support for hardware-assisted

4987

watchpoints. @xref{Algorithms, watchpoints}, for more details and

4988

other related macros.

4989

4990

@item int gdbarch_print_insn (@var{gdbarch}, @var{vma}, @var{info})

4991

@findex gdbarch_print_insn

4992

This is the function used by @value{GDBN} to print an assembly

4993

instruction. It prints the instruction at address @var{vma} in

4994

debugged memory and returns the length of the instruction, in bytes.

4995

This usually points to a function in the @code{opcodes} library

4996

(@pxref{Support Libraries, ,Opcodes}). @var{info} is a structure (of

4997

type @code{disassemble_info}) defined in the header file

4998

@file{include/dis-asm.h}, and used to pass information to the

4999

instruction decoding routine.

5000

5001

@item frame_id gdbarch_dummy_id (@var{gdbarch}, @var{frame})

5002

@findex gdbarch_dummy_id

5003

@anchor{gdbarch_dummy_id} Given @var{frame} return a @w{@code{struct

5004

frame_id}} that uniquely identifies an inferior function call's dummy

5005

frame. The value returned must match the dummy frame stack value

5006

previously saved by @code{call_function_by_hand}.

5007

5008

@item void gdbarch_value_to_register (@var{gdbarch}, @var{frame}, @var{type}, @var{buf})

5009

@findex gdbarch_value_to_register

5010

Convert a value of type @var{type} into the raw contents of a register.

5011

@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.

5012

5013

@end table

5014

5015

Motorola M68K target conditionals.

5016

5017

@ftable @code

5018

@item BPT_VECTOR

5019

Define this to be the 4-bit location of the breakpoint trap vector. If

5020

not defined, it will default to @code{0xf}.

5021

5022

@item REMOTE_BPT_VECTOR

5023

Defaults to @code{1}.

5024

5025

@end ftable

5026

5027

@node Adding a New Target

5028

@section Adding a New Target

5029

5030

@cindex adding a target

5031

The following files add a target to @value{GDBN}:

5032

5033

@table @file

5034

@cindex target dependent files

5035

5036

@item gdb/@var{ttt}-tdep.c

5037

Contains any miscellaneous code required for this target machine. On

5038

some machines it doesn't exist at all.

5039

5040

@item gdb/@var{arch}-tdep.c

5041

@itemx gdb/@var{arch}-tdep.h

5042

This is required to describe the basic layout of the target machine's

5043

processor chip (registers, stack, etc.). It can be shared among many

5044

targets that use the same processor architecture.

5045

5046

@end table

5047

5048

(Target header files such as

5049

@file{gdb/config/@var{arch}/tm-@var{ttt}.h},

5050

@file{gdb/config/@var{arch}/tm-@var{arch}.h}, and

5051

@file{config/tm-@var{os}.h} are no longer used.)

5052

5053

@findex _initialize_@var{arch}_tdep

5054

A @value{GDBN} description for a new architecture, arch is created by

5055

defining a global function @code{_initialize_@var{arch}_tdep}, by

5056

convention in the source file @file{@var{arch}-tdep.c}. For

5057

example, in the case of the OpenRISC 1000, this function is called

5058

@code{_initialize_or1k_tdep} and is found in the file

5059

@file{or1k-tdep.c}.

5060

5061

The object file resulting from compiling this source file, which will

5062

contain the implementation of the

5063

@code{_initialize_@var{arch}_tdep} function is specified in the

5064

@value{GDBN} @file{configure.tgt} file, which includes a large case

5065

statement pattern matching against the @code{--target} option of the

5066

@kbd{configure} script.

5067

5068

@quotation

5069

@emph{Note:} If the architecture requires multiple source files, the

5070

corresponding binaries should be included in

5071

@file{configure.tgt}. However if there are header files, the

5072

dependencies on these will not be picked up from the entries in

5073

@file{configure.tgt}. The @file{Makefile.in} file will need extending to

5074

show these dependencies.

5075

@end quotation

5076

5077

@findex gdbarch_register

5078

A new struct gdbarch, defining the new architecture, is created within

5079

the @code{_initialize_@var{arch}_tdep} function by calling

5080

@code{gdbarch_register}:

5081

5082

@smallexample

5083

void gdbarch_register (enum bfd_architecture architecture,

5084

gdbarch_init_ftype *init_func,

5085

gdbarch_dump_tdep_ftype *tdep_dump_func);

5086

@end smallexample

5087

5088

This function has been described fully in an earlier

5089

section. @xref{How an Architecture is Represented, , How an

5090

Architecture is Represented}.

5091

5092

The new @code{@w{struct gdbarch}} should contain implementations of

5093

the necessary functions (described in the previous sections) to

5094

describe the basic layout of the target machine's processor chip

5095

(registers, stack, etc.). It can be shared among many targets that use

5096

the same processor architecture.

5097

5098

@node Target Descriptions

5099

@chapter Target Descriptions

5100

@cindex target descriptions

5101

5102

The target architecture definition (@pxref{Target Architecture Definition})

5103

contains @value{GDBN}'s hard-coded knowledge about an architecture. For

5104

some platforms, it is handy to have more flexible knowledge about a specific

5105

instance of the architecture---for instance, a processor or development board.

5106

@dfn{Target descriptions} provide a mechanism for the user to tell @value{GDBN}

5107

more about what their target supports, or for the target to tell @value{GDBN}

5108

directly.

5109

5110

For details on writing, automatically supplying, and manually selecting

5111

target descriptions, see @ref{Target Descriptions, , , gdb,

5112

Debugging with @value{GDBN}}. This section will cover some related

5113

topics about the @value{GDBN} internals.

5114

5115

@menu

5116

* Target Descriptions Implementation::

5117

* Adding Target Described Register Support::

5118

@end menu

5119

5120

@node Target Descriptions Implementation

5121

@section Target Descriptions Implementation

5122

@cindex target descriptions, implementation

5123

5124

Before @value{GDBN} connects to a new target, or runs a new program on

5125

an existing target, it discards any existing target description and

5126

reverts to a default gdbarch. Then, after connecting, it looks for a

5127

new target description by calling @code{target_find_description}.

5128

5129

A description may come from a user specified file (XML), the remote

5130

@samp{qXfer:features:read} packet (also XML), or from any custom

5131

@code{to_read_description} routine in the target vector. For instance,

5132

the remote target supports guessing whether a MIPS target is 32-bit or

5133

64-bit based on the size of the @samp{g} packet.

5134

5135

If any target description is found, @value{GDBN} creates a new gdbarch

5136

incorporating the description by calling @code{gdbarch_update_p}. Any

5137

@samp{<architecture>} element is handled first, to determine which

5138

architecture's gdbarch initialization routine is called to create the

5139

new architecture. Then the initialization routine is called, and has

5140

a chance to adjust the constructed architecture based on the contents

5141

of the target description. For instance, it can recognize any

5142

properties set by a @code{to_read_description} routine. Also

5143

see @ref{Adding Target Described Register Support}.

5144

5145

@node Adding Target Described Register Support

5146

@section Adding Target Described Register Support

5147

@cindex target descriptions, adding register support

5148

5149

Target descriptions can report additional registers specific to an

5150

instance of the target. But it takes a little work in the architecture

5151

specific routines to support this.

5152

5153

A target description must either have no registers or a complete

5154

set---this avoids complexity in trying to merge standard registers

5155

with the target defined registers. It is the architecture's

5156

responsibility to validate that a description with registers has

5157

everything it needs. To keep architecture code simple, the same

5158

mechanism is used to assign fixed internal register numbers to

5159

standard registers.

5160

5161

If @code{tdesc_has_registers} returns 1, the description contains

5162

registers. The architecture's @code{gdbarch_init} routine should:

5163

5164

@itemize @bullet

5165

5166

@item

5167

Call @code{tdesc_data_alloc} to allocate storage, early, before

5168

searching for a matching gdbarch or allocating a new one.

5169

5170

@item

5171

Use @code{tdesc_find_feature} to locate standard features by name.

5172

5173

@item

5174

Use @code{tdesc_numbered_register} and @code{tdesc_numbered_register_choices}

5175

to locate the expected registers in the standard features.

5176

5177

@item

5178

Return @code{NULL} if a required feature is missing, or if any standard

5179

feature is missing expected registers. This will produce a warning that

5180

the description was incomplete.

5181

5182

@item

5183

Free the allocated data before returning, unless @code{tdesc_use_registers}

5184

is called.

5185

5186

@item

5187

Call @code{set_gdbarch_num_regs} as usual, with a number higher than any

5188

fixed number passed to @code{tdesc_numbered_register}.

5189

5190

@item

5191

Call @code{tdesc_use_registers} after creating a new gdbarch, before

5192

returning it.

5193

5194

@end itemize

5195

5196

After @code{tdesc_use_registers} has been called, the architecture's

5197

@code{register_name}, @code{register_type}, and @code{register_reggroup_p}

5198

routines will not be called; that information will be taken from

5199

the target description. @code{num_regs} may be increased to account

5200

for any additional registers in the description.

5201

5202

Pseudo-registers require some extra care:

5203

5204

@itemize @bullet

5205

5206

@item

5207

Using @code{tdesc_numbered_register} allows the architecture to give

5208

constant register numbers to standard architectural registers, e.g.@:

5209

as an @code{enum} in @file{@var{arch}-tdep.h}. But because

5210

pseudo-registers are always numbered above @code{num_regs},

5211

which may be increased by the description, constant numbers

5212

can not be used for pseudos. They must be numbered relative to

5213

@code{num_regs} instead.

5214

5215

@item

5216

The description will not describe pseudo-registers, so the

5217

architecture must call @code{set_tdesc_pseudo_register_name},

5218

@code{set_tdesc_pseudo_register_type}, and

5219

@code{set_tdesc_pseudo_register_reggroup_p} to supply routines

5220

describing pseudo registers. These routines will be passed

5221

internal register numbers, so the same routines used for the

5222

gdbarch equivalents are usually suitable.

5223

5224

@end itemize

5225

5226

5227

@node Target Vector Definition

5228

5229

@chapter Target Vector Definition

5230

@cindex target vector

5231

5232

The target vector defines the interface between @value{GDBN}'s

5233

abstract handling of target systems, and the nitty-gritty code that

5234

actually exercises control over a process or a serial port.

5235

@value{GDBN} includes some 30-40 different target vectors; however,

5236

each configuration of @value{GDBN} includes only a few of them.

5237

5238

@menu

5239

* Managing Execution State::

5240

* Existing Targets::

5241

@end menu

5242

5243

@node Managing Execution State

5244

@section Managing Execution State

5245

@cindex execution state

5246

5247

A target vector can be completely inactive (not pushed on the target

5248

stack), active but not running (pushed, but not connected to a fully

5249

manifested inferior), or completely active (pushed, with an accessible

5250

inferior). Most targets are only completely inactive or completely

5251

active, but some support persistent connections to a target even

5252

when the target has exited or not yet started.

5253

5254

For example, connecting to the simulator using @code{target sim} does

5255

not create a running program. Neither registers nor memory are

5256

accessible until @code{run}. Similarly, after @code{kill}, the

5257

program can not continue executing. But in both cases @value{GDBN}

5258

remains connected to the simulator, and target-specific commands

5259

are directed to the simulator.

5260

5261

A target which only supports complete activation should push itself

5262

onto the stack in its @code{to_open} routine (by calling

5263

@code{push_target}), and unpush itself from the stack in its

5264

@code{to_mourn_inferior} routine (by calling @code{unpush_target}).

5265

5266

A target which supports both partial and complete activation should

5267

still call @code{push_target} in @code{to_open}, but not call

5268

@code{unpush_target} in @code{to_mourn_inferior}. Instead, it should

5269

call either @code{target_mark_running} or @code{target_mark_exited}

5270

in its @code{to_open}, depending on whether the target is fully active

5271

after connection. It should also call @code{target_mark_running} any

5272

time the inferior becomes fully active (e.g.@: in

5273

@code{to_create_inferior} and @code{to_attach}), and

5274

@code{target_mark_exited} when the inferior becomes inactive (in

5275

@code{to_mourn_inferior}). The target should also make sure to call

5276

@code{target_mourn_inferior} from its @code{to_kill}, to return the

5277

target to inactive state.

5278

5279

@node Existing Targets

5280

@section Existing Targets

5281

@cindex targets

5282

5283

@subsection File Targets

5284

5285

Both executables and core files have target vectors.

5286

5287

@subsection Standard Protocol and Remote Stubs

5288

5289

@value{GDBN}'s file @file{remote.c} talks a serial protocol to code that

5290

runs in the target system. @value{GDBN} provides several sample

5291

@dfn{stubs} that can be integrated into target programs or operating

5292

systems for this purpose; they are named @file{@var{cpu}-stub.c}. Many

5293

operating systems, embedded targets, emulators, and simulators already

5294

have a @value{GDBN} stub built into them, and maintenance of the remote

5295

protocol must be careful to preserve compatibility.

5296

5297

The @value{GDBN} user's manual describes how to put such a stub into

5298

your target code. What follows is a discussion of integrating the

5299

SPARC stub into a complicated operating system (rather than a simple

5300

program), by Stu Grossman, the author of this stub.

5301

5302

The trap handling code in the stub assumes the following upon entry to

5303

@code{trap_low}:

5304

5305

@enumerate

5306

@item

5307

%l1 and %l2 contain pc and npc respectively at the time of the trap;

5308

5309

@item

5310

traps are disabled;

5311

5312

@item

5313

you are in the correct trap window.

5314

@end enumerate

5315

5316

As long as your trap handler can guarantee those conditions, then there

5317

is no reason why you shouldn't be able to ``share'' traps with the stub.

5318

The stub has no requirement that it be jumped to directly from the

5319

hardware trap vector. That is why it calls @code{exceptionHandler()},

5320

which is provided by the external environment. For instance, this could

5321

set up the hardware traps to actually execute code which calls the stub

5322

first, and then transfers to its own trap handler.

5323

5324

For the most point, there probably won't be much of an issue with

5325

``sharing'' traps, as the traps we use are usually not used by the kernel,

5326

and often indicate unrecoverable error conditions. Anyway, this is all

5327

controlled by a table, and is trivial to modify. The most important

5328

trap for us is for @code{ta 1}. Without that, we can't single step or

5329

do breakpoints. Everything else is unnecessary for the proper operation

5330

of the debugger/stub.

5331

5332

From reading the stub, it's probably not obvious how breakpoints work.

5333

They are simply done by deposit/examine operations from @value{GDBN}.

5334

5335

@subsection ROM Monitor Interface

5336

5337

@subsection Custom Protocols

5338

5339

@subsection Transport Layer

5340

5341

@subsection Builtin Simulator

5342

5343

5344

@node Native Debugging

5345

5346

@chapter Native Debugging

5347

@cindex native debugging

5348

5349

Several files control @value{GDBN}'s configuration for native support:

5350

5351

@table @file

5352

@vindex NATDEPFILES

5353

@item gdb/config/@var{arch}/@var{xyz}.mh

5354

Specifies Makefile fragments needed by a @emph{native} configuration on

5355

machine @var{xyz}. In particular, this lists the required

5356

native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.

5357

Also specifies the header file which describes native support on

5358

@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also

5359

define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},

5360

@samp{NAT_CDEPS}, @samp{NAT_GENERATED_FILES}, etc.; see @file{Makefile.in}.

5361

5362

@emph{Maintainer's note: The @file{.mh} suffix is because this file

5363

originally contained @file{Makefile} fragments for hosting @value{GDBN}

5364

on machine @var{xyz}. While the file is no longer used for this

5365

purpose, the @file{.mh} suffix remains. Perhaps someone will

5366

eventually rename these fragments so that they have a @file{.mn}

5367

suffix.}

5368

5369

@item gdb/config/@var{arch}/nm-@var{xyz}.h

5370

(@file{nm.h} is a link to this file, created by @code{configure}). Contains C

5371

macro definitions describing the native system environment, such as

5372

child process control and core file support.

5373

5374

@item gdb/@var{xyz}-nat.c

5375

Contains any miscellaneous C code required for this native support of

5376

this machine. On some machines it doesn't exist at all.

5377

@end table

5378

5379

There are some ``generic'' versions of routines that can be used by

5380

various systems. These can be customized in various ways by macros

5381

defined in your @file{nm-@var{xyz}.h} file. If these routines work for

5382

the @var{xyz} host, you can just include the generic file's name (with

5383

@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.

5384

5385

Otherwise, if your machine needs custom support routines, you will need

5386

to write routines that perform the same functions as the generic file.

5387

Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}

5388

into @code{NATDEPFILES}.

5389

5390

@table @file

5391

@item inftarg.c

5392

This contains the @emph{target_ops vector} that supports Unix child

5393

processes on systems which use ptrace and wait to control the child.

5394

5395

@item procfs.c

5396

This contains the @emph{target_ops vector} that supports Unix child

5397

processes on systems which use /proc to control the child.

5398

5399

@item fork-child.c

5400

This does the low-level grunge that uses Unix system calls to do a ``fork

5401

and exec'' to start up a child process.

5402

5403

@item infptrace.c

5404

This is the low level interface to inferior processes for systems using

5405

the Unix @code{ptrace} call in a vanilla way.

5406

@end table

5407

5408

@section ptrace

5409

5410

@section /proc

5411

5412

@section win32

5413

5414

@section shared libraries

5415

5416

@section Native Conditionals

5417

@cindex native conditionals

5418

5419

When @value{GDBN} is configured and compiled, various macros are

5420

defined or left undefined, to control compilation when the host and

5421

target systems are the same. These macros should be defined (or left

5422

undefined) in @file{nm-@var{system}.h}.

5423

5424

@table @code

5425

5426

@item I386_USE_GENERIC_WATCHPOINTS

5427

An x86-based machine can define this to use the generic x86 watchpoint

5428

support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.

5429

5430

@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})

5431

@findex SOLIB_ADD

5432

Define this to expand into an expression that will cause the symbols in

5433

@var{filename} to be added to @value{GDBN}'s symbol table. If

5434

@var{readsyms} is zero symbols are not read but any necessary low level

5435

processing for @var{filename} is still done.

5436

5437

@item SOLIB_CREATE_INFERIOR_HOOK

5438

@findex SOLIB_CREATE_INFERIOR_HOOK

5439

Define this to expand into any shared-library-relocation code that you

5440

want to be run just after the child process has been forked.

5441

5442

@item START_INFERIOR_TRAPS_EXPECTED

5443

@findex START_INFERIOR_TRAPS_EXPECTED

5444

When starting an inferior, @value{GDBN} normally expects to trap

5445

twice; once when

5446

the shell execs, and once when the program itself execs. If the actual

5447

number of traps is something other than 2, then define this macro to

5448

expand into the number expected.

5449

5450

@end table

5451

5452

@node Support Libraries

5453

5454

@chapter Support Libraries

5455

5456

@section BFD

5457

@cindex BFD library

5458

5459

BFD provides support for @value{GDBN} in several ways:

5460

5461

@table @emph

5462

@item identifying executable and core files

5463

BFD will identify a variety of file types, including a.out, coff, and

5464

several variants thereof, as well as several kinds of core files.

5465

5466

@item access to sections of files

5467

BFD parses the file headers to determine the names, virtual addresses,

5468

sizes, and file locations of all the various named sections in files

5469

(such as the text section or the data section). @value{GDBN} simply

5470

calls BFD to read or write section @var{x} at byte offset @var{y} for

5471

length @var{z}.

5472

5473

@item specialized core file support

5474

BFD provides routines to determine the failing command name stored in a

5475

core file, the signal with which the program failed, and whether a core

5476

file matches (i.e.@: could be a core dump of) a particular executable

5477

file.

5478

5479

@item locating the symbol information

5480

@value{GDBN} uses an internal interface of BFD to determine where to find the

5481

symbol information in an executable file or symbol-file. @value{GDBN} itself

5482

handles the reading of symbols, since BFD does not ``understand'' debug

5483

symbols, but @value{GDBN} uses BFD's cached information to find the symbols,

5484

string table, etc.

5485

@end table

5486

5487

@section opcodes

5488

@cindex opcodes library

5489

5490

The opcodes library provides @value{GDBN}'s disassembler. (It's a separate

5491

library because it's also used in binutils, for @file{objdump}).

5492

5493

@section readline

5494

@cindex readline library

5495

The @code{readline} library provides a set of functions for use by applications

5496

that allow users to edit command lines as they are typed in.

5497

5498

@section libiberty

5499

@cindex @code{libiberty} library

5500

5501

The @code{libiberty} library provides a set of functions and features

5502

that integrate and improve on functionality found in modern operating

5503

systems. Broadly speaking, such features can be divided into three

5504

groups: supplemental functions (functions that may be missing in some

5505

environments and operating systems), replacement functions (providing

5506

a uniform and easier to use interface for commonly used standard

5507

functions), and extensions (which provide additional functionality

5508

beyond standard functions).

5509

5510

@value{GDBN} uses various features provided by the @code{libiberty}

5511

library, for instance the C@t{++} demangler, the @acronym{IEEE}

5512

floating format support functions, the input options parser

5513

@samp{getopt}, the @samp{obstack} extension, and other functions.

5514

5515

@subsection @code{obstacks} in @value{GDBN}

5516

@cindex @code{obstacks}

5517

5518

The obstack mechanism provides a convenient way to allocate and free

5519

chunks of memory. Each obstack is a pool of memory that is managed

5520

like a stack. Objects (of any nature, size and alignment) are

5521

allocated and freed in a @acronym{LIFO} fashion on an obstack (see

5522

@code{libiberty}'s documentation for a more detailed explanation of

5523

@code{obstacks}).

5524

5525

The most noticeable use of the @code{obstacks} in @value{GDBN} is in

5526

object files. There is an obstack associated with each internal

5527

representation of an object file. Lots of things get allocated on

5528

these @code{obstacks}: dictionary entries, blocks, blockvectors,

5529

symbols, minimal symbols, types, vectors of fundamental types, class

5530

fields of types, object files section lists, object files section

5531

offset lists, line tables, symbol tables, partial symbol tables,

5532

string tables, symbol table private data, macros tables, debug

5533

information sections and entries, import and export lists (som),

5534

unwind information (hppa), dwarf2 location expressions data. Plus

5535

various strings such as directory names strings, debug format strings,

5536

names of types.

5537

5538

An essential and convenient property of all data on @code{obstacks} is

5539

that memory for it gets allocated (with @code{obstack_alloc}) at

5540

various times during a debugging session, but it is released all at

5541

once using the @code{obstack_free} function. The @code{obstack_free}

5542

function takes a pointer to where in the stack it must start the

5543

deletion from (much like the cleanup chains have a pointer to where to

5544

start the cleanups). Because of the stack like structure of the

5545

@code{obstacks}, this allows to free only a top portion of the

5546

obstack. There are a few instances in @value{GDBN} where such thing

5547

happens. Calls to @code{obstack_free} are done after some local data

5548

is allocated to the obstack. Only the local data is deleted from the

5549

obstack. Of course this assumes that nothing between the

5550

@code{obstack_alloc} and the @code{obstack_free} allocates anything

5551

else on the same obstack. For this reason it is best and safest to

5552

use temporary @code{obstacks}.

5553

5554

Releasing the whole obstack is also not safe per se. It is safe only

5555

under the condition that we know the @code{obstacks} memory is no

5556

longer needed. In @value{GDBN} we get rid of the @code{obstacks} only

5557

when we get rid of the whole objfile(s), for instance upon reading a

5558

new symbol file.

5559

5560

@section gnu-regex

5561

@cindex regular expressions library

5562

5563

Regex conditionals.

5564

5565

@table @code

5566

@item C_ALLOCA

5567

5568

@item NFAILURES

5569

5570

@item RE_NREGS

5571

5572

@item SIGN_EXTEND_CHAR

5573

5574

@item SWITCH_ENUM_BUG

5575

5576

@item SYNTAX_TABLE

5577

5578

@item Sword

5579

5580

@item sparc

5581

@end table

5582

5583

@section Array Containers

5584

@cindex Array Containers

5585

@cindex VEC

5586

5587

Often it is necessary to manipulate a dynamic array of a set of

5588

objects. C forces some bookkeeping on this, which can get cumbersome

5589

and repetitive. The @file{vec.h} file contains macros for defining

5590

and using a typesafe vector type. The functions defined will be

5591

inlined when compiling, and so the abstraction cost should be zero.

5592

Domain checks are added to detect programming errors.

5593

5594

An example use would be an array of symbols or section information.

5595

The array can be grown as symbols are read in (or preallocated), and

5596

the accessor macros provided keep care of all the necessary

5597

bookkeeping. Because the arrays are type safe, there is no danger of

5598

accidentally mixing up the contents. Think of these as C++ templates,

5599

but implemented in C.

5600

5601

Because of the different behavior of structure objects, scalar objects

5602

and of pointers, there are three flavors of vector, one for each of

5603

these variants. Both the structure object and pointer variants pass

5604

pointers to objects around --- in the former case the pointers are

5605

stored into the vector and in the latter case the pointers are

5606

dereferenced and the objects copied into the vector. The scalar

5607

object variant is suitable for @code{int}-like objects, and the vector

5608

elements are returned by value.

5609

5610

There are both @code{index} and @code{iterate} accessors. The iterator

5611

returns a boolean iteration condition and updates the iteration

5612

variable passed by reference. Because the iterator will be inlined,

5613

the address-of can be optimized away.

5614

5615

The vectors are implemented using the trailing array idiom, thus they

5616

are not resizeable without changing the address of the vector object

5617

itself. This means you cannot have variables or fields of vector type

5618

--- always use a pointer to a vector. The one exception is the final

5619

field of a structure, which could be a vector type. You will have to

5620

use the @code{embedded_size} & @code{embedded_init} calls to create

5621

such objects, and they will probably not be resizeable (so don't use

5622

the @dfn{safe} allocation variants). The trailing array idiom is used

5623

(rather than a pointer to an array of data), because, if we allow

5624

@code{NULL} to also represent an empty vector, empty vectors occupy

5625

minimal space in the structure containing them.

5626

5627

Each operation that increases the number of active elements is

5628

available in @dfn{quick} and @dfn{safe} variants. The former presumes

5629

that there is sufficient allocated space for the operation to succeed

5630

(it dies if there is not). The latter will reallocate the vector, if

5631

needed. Reallocation causes an exponential increase in vector size.

5632

If you know you will be adding N elements, it would be more efficient

5633

to use the reserve operation before adding the elements with the

5634

@dfn{quick} operation. This will ensure there are at least as many

5635

elements as you ask for, it will exponentially increase if there are

5636

too few spare slots. If you want reserve a specific number of slots,

5637

but do not want the exponential increase (for instance, you know this

5638

is the last allocation), use a negative number for reservation. You

5639

can also create a vector of a specific size from the get go.

5640

5641

You should prefer the push and pop operations, as they append and

5642

remove from the end of the vector. If you need to remove several items

5643

in one go, use the truncate operation. The insert and remove

5644

operations allow you to change elements in the middle of the vector.

5645

There are two remove operations, one which preserves the element

5646

ordering @code{ordered_remove}, and one which does not

5647

@code{unordered_remove}. The latter function copies the end element

5648

into the removed slot, rather than invoke a memmove operation. The

5649

@code{lower_bound} function will determine where to place an item in

5650

the array using insert that will maintain sorted order.

5651

5652

If you need to directly manipulate a vector, then the @code{address}

5653

accessor will return the address of the start of the vector. Also the

5654

@code{space} predicate will tell you whether there is spare capacity in the

5655

vector. You will not normally need to use these two functions.

5656

5657

Vector types are defined using a

5658

@code{DEF_VEC_@{O,P,I@}(@var{typename})} macro. Variables of vector

5659

type are declared using a @code{VEC(@var{typename})} macro. The

5660

characters @code{O}, @code{P} and @code{I} indicate whether

5661

@var{typename} is an object (@code{O}), pointer (@code{P}) or integral

5662

(@code{I}) type. Be careful to pick the correct one, as you'll get an

5663

awkward and inefficient API if you use the wrong one. There is a

5664

check, which results in a compile-time warning, for the @code{P} and

5665

@code{I} versions, but there is no check for the @code{O} versions, as

5666

that is not possible in plain C.

5667

5668

An example of their use would be,

5669

5670

@smallexample

5671

DEF_VEC_P(tree); // non-managed tree vector.

5672

5673

struct my_struct @{

5674

VEC(tree) *v; // A (pointer to) a vector of tree pointers.

5675

@};

5676

5677

struct my_struct *s;

5678

5679

if (VEC_length(tree, s->v)) @{ we have some contents @}

5680

VEC_safe_push(tree, s->v, decl); // append some decl onto the end

5681

for (ix = 0; VEC_iterate(tree, s->v, ix, elt); ix++)

5682

@{ do something with elt @}

5683

5684

@end smallexample

5685

5686

The @file{vec.h} file provides details on how to invoke the various

5687

accessors provided. They are enumerated here:

5688

5689

@table @code

5690

@item VEC_length

5691

Return the number of items in the array,

5692

5693

@item VEC_empty

5694

Return true if the array has no elements.

5695

5696

@item VEC_last

5697

@itemx VEC_index

5698

Return the last or arbitrary item in the array.

5699

5700

@item VEC_iterate

5701

Access an array element and indicate whether the array has been

5702

traversed.

5703

5704

@item VEC_alloc

5705

@itemx VEC_free

5706

Create and destroy an array.

5707

5708

@item VEC_embedded_size

5709

@itemx VEC_embedded_init

5710

Helpers for embedding an array as the final element of another struct.

5711

5712

@item VEC_copy

5713

Duplicate an array.

5714

5715

@item VEC_space

5716

Return the amount of free space in an array.

5717

5718

@item VEC_reserve

5719

Ensure a certain amount of free space.

5720

5721

@item VEC_quick_push

5722

@itemx VEC_safe_push

5723

Append to an array, either assuming the space is available, or making

5724

sure that it is.

5725

5726

@item VEC_pop

5727

Remove the last item from an array.

5728

5729

@item VEC_truncate

5730

Remove several items from the end of an array.

5731

5732

@item VEC_safe_grow

5733

Add several items to the end of an array.

5734

5735

@item VEC_replace

5736

Overwrite an item in the array.

5737

5738

@item VEC_quick_insert

5739

@itemx VEC_safe_insert

5740

Insert an item into the middle of the array. Either the space must

5741

already exist, or the space is created.

5742

5743

@item VEC_ordered_remove

5744

@itemx VEC_unordered_remove

5745

Remove an item from the array, preserving order or not.

5746

5747

@item VEC_block_remove

5748

Remove a set of items from the array.

5749

5750

@item VEC_address

5751

Provide the address of the first element.

5752

5753

@item VEC_lower_bound

5754

Binary search the array.

5755

5756

@end table

5757

5758

@section include

5759

5760

@node Coding Standards

5761

5762

@chapter Coding Standards

5763

@cindex coding standards

5764

5765

@section @value{GDBN} C Coding Standards

5766

5767

@value{GDBN} follows the GNU coding standards, as described in

5768

@file{etc/standards.texi}. This file is also available for anonymous

5769

FTP from GNU archive sites. @value{GDBN} takes a strict interpretation

5770

of the standard; in general, when the GNU standard recommends a practice

5771

but does not require it, @value{GDBN} requires it.

5772

5773

@value{GDBN} follows an additional set of coding standards specific to

5774

@value{GDBN}, as described in the following sections.

5775

5776

@subsection ISO C

5777

5778

@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant

5779

compiler.

5780

5781

@value{GDBN} does not assume an ISO C or POSIX compliant C library.

5782

5783

@subsection Formatting

5784

5785

@cindex source code formatting

5786

The standard GNU recommendations for formatting must be followed

5787

strictly. Any @value{GDBN}-specific deviation from GNU

5788

recomendations is described below.

5789

5790

A function declaration should not have its name in column zero. A

5791

function definition should have its name in column zero.

5792

5793

@smallexample

5794

/* Declaration */

5795

static void foo (void);

5796

/* Definition */

5797

void

5798

foo (void)

5799

@{

5800

@}

5801

@end smallexample

5802

5803

@emph{Pragmatics: This simplifies scripting. Function definitions can

5804

be found using @samp{^function-name}.}

5805

5806

There must be a space between a function or macro name and the opening

5807

parenthesis of its argument list (except for macro definitions, as

5808

required by C). There must not be a space after an open paren/bracket

5809

or before a close paren/bracket.

5810

5811

While additional whitespace is generally helpful for reading, do not use

5812

more than one blank line to separate blocks, and avoid adding whitespace

5813

after the end of a program line (as of 1/99, some 600 lines had

5814

whitespace after the semicolon). Excess whitespace causes difficulties

5815

for @code{diff} and @code{patch} utilities.

5816

5817

Pointers are declared using the traditional K&R C style:

5818

5819

@smallexample

5820

void *foo;

5821

@end smallexample

5822

5823

@noindent

5824

and not:

5825

5826

@smallexample

5827

void * foo;

5828

void* foo;

5829

@end smallexample

5830

5831

In addition, whitespace around casts and unary operators should follow

5832

the following guidelines:

5833

5834

@multitable @columnfractions .2 .2 .8

5835

@item Use... @tab ...instead of @tab

5836

5837

@item @code{!x}

5838

@tab @code{! x}

5839

@item @code{~x}

5840

@tab @code{~ x}

5841

@item @code{-x}

5842

@tab @code{- x}

5843

@tab (unary minus)

5844

@item @code{(foo) x}

5845

@tab @code{(foo)x}

5846

@tab (cast)

5847

@item @code{*x}

5848

@tab @code{* x}

5849

@tab (pointer dereference)

5850

@end multitable

5851

5852

@subsection Comments

5853

5854

@cindex comment formatting

5855

The standard GNU requirements on comments must be followed strictly.

5856

5857

Block comments must appear in the following form, with no @code{/*}- or

5858

@code{*/}-only lines, and no leading @code{*}:

5859

5860

@smallexample

5861

/* Wait for control to return from inferior to debugger. If inferior

5862

gets a signal, we may decide to start it up again instead of

5863

returning. That is why there is a loop in this function. When

5864

this function actually returns it means the inferior should be left

5865

stopped and @value{GDBN} should read more commands. */

5866

@end smallexample

5867

5868

(Note that this format is encouraged by Emacs; tabbing for a multi-line

5869

comment works correctly, and @kbd{M-q} fills the block consistently.)

5870

5871

Put a blank line between the block comments preceding function or

5872

variable definitions, and the definition itself.

5873

5874

In general, put function-body comments on lines by themselves, rather

5875

than trying to fit them into the 20 characters left at the end of a

5876

line, since either the comment or the code will inevitably get longer

5877

than will fit, and then somebody will have to move it anyhow.

5878

5879

@subsection C Usage

5880

5881

@cindex C data types

5882

Code must not depend on the sizes of C data types, the format of the

5883

host's floating point numbers, the alignment of anything, or the order

5884

of evaluation of expressions.

5885

5886

@cindex function usage

5887

Use functions freely. There are only a handful of compute-bound areas

5888

in @value{GDBN} that might be affected by the overhead of a function

5889

call, mainly in symbol reading. Most of @value{GDBN}'s performance is

5890

limited by the target interface (whether serial line or system call).

5891

5892

However, use functions with moderation. A thousand one-line functions

5893

are just as hard to understand as a single thousand-line function.

5894

5895

@emph{Macros are bad, M'kay.}

5896

(But if you have to use a macro, make sure that the macro arguments are

5897

protected with parentheses.)

5898

5899

@cindex types

5900

5901

Declarations like @samp{struct foo *} should be used in preference to

5902

declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.

5903

5904

@subsection Function Prototypes

5905

@cindex function prototypes

5906

5907

Prototypes must be used when both @emph{declaring} and @emph{defining}

5908

a function. Prototypes for @value{GDBN} functions must include both the

5909

argument type and name, with the name matching that used in the actual

5910

function definition.

5911

5912

All external functions should have a declaration in a header file that

5913

callers include, except for @code{_initialize_*} functions, which must

5914

be external so that @file{init.c} construction works, but shouldn't be

5915

visible to random source files.

5916

5917

Where a source file needs a forward declaration of a static function,

5918

that declaration must appear in a block near the top of the source file.

5919

5920

@subsection File Names

5921

5922

Any file used when building the core of @value{GDBN} must be in lower

5923

case. Any file used when building the core of @value{GDBN} must be 8.3

5924

unique. These requirements apply to both source and generated files.

5925

5926

@emph{Pragmatics: The core of @value{GDBN} must be buildable on many

5927

platforms including DJGPP and MacOS/HFS. Every time an unfriendly file

5928

is introduced to the build process both @file{Makefile.in} and

5929

@file{configure.in} need to be modified accordingly. Compare the

5930

convoluted conversion process needed to transform @file{COPYING} into

5931

@file{copying.c} with the conversion needed to transform

5932

@file{version.in} into @file{version.c}.}

5933

5934

Any file non 8.3 compliant file (that is not used when building the core

5935

of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.

5936

5937

@emph{Pragmatics: This is clearly a compromise.}

5938

5939

When @value{GDBN} has a local version of a system header file (ex

5940

@file{string.h}) the file name based on the POSIX header prefixed with

5941

@file{gdb_} (@file{gdb_string.h}). These headers should be relatively

5942

independent: they should use only macros defined by @file{configure},

5943

the compiler, or the host; they should include only system headers; they

5944

should refer only to system types. They may be shared between multiple

5945

programs, e.g.@: @value{GDBN} and @sc{gdbserver}.

5946

5947

For other files @samp{-} is used as the separator.

5948

5949

@subsection Include Files

5950

5951

A @file{.c} file should include @file{defs.h} first.

5952

5953

A @file{.c} file should directly include the @code{.h} file of every

5954

declaration and/or definition it directly refers to. It cannot rely on

5955

indirect inclusion.

5956

5957

A @file{.h} file should directly include the @code{.h} file of every

5958

declaration and/or definition it directly refers to. It cannot rely on

5959

indirect inclusion. Exception: The file @file{defs.h} does not need to

5960

be directly included.

5961

5962

An external declaration should only appear in one include file.

5963

5964

An external declaration should never appear in a @code{.c} file.

5965

Exception: a declaration for the @code{_initialize} function that

5966

pacifies @option{-Wmissing-declaration}.

5967

5968

A @code{typedef} definition should only appear in one include file.

5969

5970

An opaque @code{struct} declaration can appear in multiple @file{.h}

5971

files. Where possible, a @file{.h} file should use an opaque

5972

@code{struct} declaration instead of an include.

5973

5974

All @file{.h} files should be wrapped in:

5975

5976

@smallexample

5977

#ifndef INCLUDE_FILE_NAME_H

5978

#define INCLUDE_FILE_NAME_H

5979

header body

5980

#endif

5981

@end smallexample

5982

5983

@section @value{GDBN} Python Coding Standards

5984

5985

@value{GDBN} follows the published @code{Python} coding standards in

5986

@uref{http://www.python.org/dev/peps/pep-0008/, @code{PEP008}}.

5987

5988

In addition, the guidelines in the

5989

@uref{http://google-styleguide.googlecode.com/svn/trunk/pyguide.html,

5990

Google Python Style Guide} are also followed where they do not

5991

conflict with @code{PEP008}.

5992

5993

@subsection @value{GDBN}-specific exceptions

5994

5995

There are a few exceptions to the published standards.

5996

They exist mainly for consistency with the @code{C} standards.

5997

5998

@c It is expected that there are a few more exceptions,

5999

@c so we use itemize here.

6000

6001

@itemize @bullet

6002

6003

@item

6004

Use @code{FIXME} instead of @code{TODO}.

6005

6006

@end itemize

6007

6008

@node Misc Guidelines

6009

6010

@chapter Misc Guidelines

6011

6012

This chapter covers topics that are lower-level than the major

6013

algorithms of @value{GDBN}.

6014

6015

@section Cleanups

6016

@cindex cleanups

6017

6018

Cleanups are a structured way to deal with things that need to be done

6019

later.

6020

6021

When your code does something (e.g., @code{xmalloc} some memory, or

6022

@code{open} a file) that needs to be undone later (e.g., @code{xfree}

6023

the memory or @code{close} the file), it can make a cleanup. The

6024

cleanup will be done at some future point: when the command is finished

6025

and control returns to the top level; when an error occurs and the stack

6026

is unwound; or when your code decides it's time to explicitly perform

6027

cleanups. Alternatively you can elect to discard the cleanups you

6028

created.

6029

6030

Syntax:

6031

6032

@table @code

6033

@item struct cleanup *@var{old_chain};

6034

Declare a variable which will hold a cleanup chain handle.

6035

6036

@findex make_cleanup

6037

@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});

6038

Make a cleanup which will cause @var{function} to be called with

6039

@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a

6040

handle that can later be passed to @code{do_cleanups} or

6041

@code{discard_cleanups}. Unless you are going to call

6042

@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result

6043

from @code{make_cleanup}.

6044

6045

@findex do_cleanups

6046

@item do_cleanups (@var{old_chain});

6047

Do all cleanups added to the chain since the corresponding

6048

@code{make_cleanup} call was made.

6049

6050

@findex discard_cleanups

6051

@item discard_cleanups (@var{old_chain});

6052

Same as @code{do_cleanups} except that it just removes the cleanups from

6053

the chain and does not call the specified functions.

6054

@end table

6055

6056

Cleanups are implemented as a chain. The handle returned by

6057

@code{make_cleanups} includes the cleanup passed to the call and any

6058

later cleanups appended to the chain (but not yet discarded or

6059

performed). E.g.:

6060

6061

@smallexample

6062

make_cleanup (a, 0);

6063

@{

6064

struct cleanup *old = make_cleanup (b, 0);

6065

make_cleanup (c, 0)

6066

...

6067

do_cleanups (old);

6068

@}

6069

@end smallexample

6070

6071

@noindent

6072

will call @code{c()} and @code{b()} but will not call @code{a()}. The

6073

cleanup that calls @code{a()} will remain in the cleanup chain, and will

6074

be done later unless otherwise discarded.@refill

6075

6076

Your function should explicitly do or discard the cleanups it creates.

6077

Failing to do this leads to non-deterministic behavior since the caller

6078

will arbitrarily do or discard your functions cleanups. This need leads

6079

to two common cleanup styles.

6080

6081

The first style is try/finally. Before it exits, your code-block calls

6082

@code{do_cleanups} with the old cleanup chain and thus ensures that your

6083

code-block's cleanups are always performed. For instance, the following

6084

code-segment avoids a memory leak problem (even when @code{error} is

6085

called and a forced stack unwind occurs) by ensuring that the

6086

@code{xfree} will always be called:

6087

6088

@smallexample

6089

struct cleanup *old = make_cleanup (null_cleanup, 0);

6090

data = xmalloc (sizeof blah);

6091

make_cleanup (xfree, data);

6092

... blah blah ...

6093

do_cleanups (old);

6094

@end smallexample

6095

6096

The second style is try/except. Before it exits, your code-block calls

6097

@code{discard_cleanups} with the old cleanup chain and thus ensures that

6098

any created cleanups are not performed. For instance, the following

6099

code segment, ensures that the file will be closed but only if there is

6100

an error:

6101

6102

@smallexample

6103

FILE *file = fopen ("afile", "r");

6104

struct cleanup *old = make_cleanup (close_file, file);

6105

... blah blah ...

6106

discard_cleanups (old);

6107

return file;

6108

@end smallexample

6109

6110

Some functions, e.g., @code{fputs_filtered()} or @code{error()}, specify

6111

that they ``should not be called when cleanups are not in place''. This

6112

means that any actions you need to reverse in the case of an error or

6113

interruption must be on the cleanup chain before you call these

6114

functions, since they might never return to your code (they

6115

@samp{longjmp} instead).

6116

6117

@section Per-architecture module data

6118

@cindex per-architecture module data

6119

@cindex multi-arch data

6120

@cindex data-pointer, per-architecture/per-module

6121

6122

The multi-arch framework includes a mechanism for adding module

6123

specific per-architecture data-pointers to the @code{struct gdbarch}

6124

architecture object.

6125

6126

A module registers one or more per-architecture data-pointers using:

6127

6128

@deftypefn {Architecture Function} {struct gdbarch_data *} gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init})

6129

@var{pre_init} is used to, on-demand, allocate an initial value for a

6130

per-architecture data-pointer using the architecture's obstack (passed

6131

in as a parameter). Since @var{pre_init} can be called during

6132

architecture creation, it is not parameterized with the architecture.

6133

and must not call modules that use per-architecture data.

6134

@end deftypefn

6135

6136

@deftypefn {Architecture Function} {struct gdbarch_data *} gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init})

6137

@var{post_init} is used to obtain an initial value for a

6138

per-architecture data-pointer @emph{after}. Since @var{post_init} is

6139

always called after architecture creation, it both receives the fully

6140

initialized architecture and is free to call modules that use

6141

per-architecture data (care needs to be taken to ensure that those

6142

other modules do not try to call back to this module as that will

6143

create in cycles in the initialization call graph).

6144

@end deftypefn

6145

6146

These functions return a @code{struct gdbarch_data} that is used to

6147

identify the per-architecture data-pointer added for that module.

6148

6149

The per-architecture data-pointer is accessed using the function:

6150

6151

@deftypefn {Architecture Function} {void *} gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})

6152

Given the architecture @var{arch} and module data handle

6153

@var{data_handle} (returned by @code{gdbarch_data_register_pre_init}

6154

or @code{gdbarch_data_register_post_init}), this function returns the

6155

current value of the per-architecture data-pointer. If the data

6156

pointer is @code{NULL}, it is first initialized by calling the

6157

corresponding @var{pre_init} or @var{post_init} method.

6158

@end deftypefn

6159

6160

The examples below assume the following definitions:

6161

6162

@smallexample

6163

struct nozel @{ int total; @};

6164

static struct gdbarch_data *nozel_handle;

6165

@end smallexample

6166

6167

A module can extend the architecture vector, adding additional

6168

per-architecture data, using the @var{pre_init} method. The module's

6169

per-architecture data is then initialized during architecture

6170

creation.

6171

6172

In the below, the module's per-architecture @emph{nozel} is added. An

6173

architecture can specify its nozel by calling @code{set_gdbarch_nozel}

6174

from @code{gdbarch_init}.

6175

6176

@smallexample

6177

static void *

6178

nozel_pre_init (struct obstack *obstack)

6179

@{

6180

struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);

6181

return data;

6182

@}

6183

@end smallexample

6184

6185

@smallexample

6186

extern void

6187

set_gdbarch_nozel (struct gdbarch *gdbarch, int total)

6188

@{

6189

struct nozel *data = gdbarch_data (gdbarch, nozel_handle);

6190

data->total = nozel;

6191

@}

6192

@end smallexample

6193

6194

A module can on-demand create architecture dependent data structures

6195

using @code{post_init}.

6196

6197

In the below, the nozel's total is computed on-demand by

6198

@code{nozel_post_init} using information obtained from the

6199

architecture.

6200

6201

@smallexample

6202

static void *

6203

nozel_post_init (struct gdbarch *gdbarch)

6204

@{

6205

struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);

6206

nozel->total = gdbarch@dots{} (gdbarch);

6207

return data;

6208

@}

6209

@end smallexample

6210

6211

@smallexample

6212

extern int

6213

nozel_total (struct gdbarch *gdbarch)

6214

@{

6215

struct nozel *data = gdbarch_data (gdbarch, nozel_handle);

6216

return data->total;

6217

@}

6218

@end smallexample

6219

6220

@section Wrapping Output Lines

6221

@cindex line wrap in output

6222

6223

@findex wrap_here

6224

Output that goes through @code{printf_filtered} or @code{fputs_filtered}

6225

or @code{fputs_demangled} needs only to have calls to @code{wrap_here}

6226

added in places that would be good breaking points. The utility

6227

routines will take care of actually wrapping if the line width is

6228

exceeded.

6229

6230

The argument to @code{wrap_here} is an indentation string which is

6231

printed @emph{only} if the line breaks there. This argument is saved

6232

away and used later. It must remain valid until the next call to

6233

@code{wrap_here} or until a newline has been printed through the

6234

@code{*_filtered} functions. Don't pass in a local variable and then

6235

return!

6236

6237

It is usually best to call @code{wrap_here} after printing a comma or

6238

space. If you call it before printing a space, make sure that your

6239

indentation properly accounts for the leading space that will print if

6240

the line wraps there.

6241

6242

Any function or set of functions that produce filtered output must

6243

finish by printing a newline, to flush the wrap buffer, before switching

6244

to unfiltered (@code{printf}) output. Symbol reading routines that

6245

print warnings are a good example.

6246

6247

@section Memory Management

6248

6249

@value{GDBN} does not use the functions @code{malloc}, @code{realloc},

6250

@code{calloc}, @code{free} and @code{asprintf}.

6251

6252

@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and

6253

@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:

6254

these functions do not return when the memory pool is empty. Instead,

6255

they unwind the stack using cleanups. These functions return

6256

@code{NULL} when requested to allocate a chunk of memory of size zero.

6257

6258

@emph{Pragmatics: By using these functions, the need to check every

6259

memory allocation is removed. These functions provide portable

6260

behavior.}

6261

6262

@value{GDBN} does not use the function @code{free}.

6263

6264

@value{GDBN} uses the function @code{xfree} to return memory to the

6265

memory pool. Consistent with ISO-C, this function ignores a request to

6266

free a @code{NULL} pointer.

6267

6268

@emph{Pragmatics: On some systems @code{free} fails when passed a

6269

@code{NULL} pointer.}

6270

6271

@value{GDBN} can use the non-portable function @code{alloca} for the

6272

allocation of small temporary values (such as strings).

6273

6274

@emph{Pragmatics: This function is very non-portable. Some systems

6275

restrict the memory being allocated to no more than a few kilobytes.}

6276

6277

@value{GDBN} uses the string function @code{xstrdup} and the print

6278

function @code{xstrprintf}.

6279

6280

@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print

6281

functions such as @code{sprintf} are very prone to buffer overflow

6282

errors.}

6283

6284

6285

@section Compiler Warnings

6286

@cindex compiler warnings

6287

6288

With few exceptions, developers should avoid the configuration option

6289

@samp{--disable-werror} when building @value{GDBN}. The exceptions

6290

are listed in the file @file{gdb/MAINTAINERS}. The default, when

6291

building with @sc{gcc}, is @samp{--enable-werror}.

6292

6293

This option causes @value{GDBN} (when built using GCC) to be compiled

6294

with a carefully selected list of compiler warning flags. Any warnings

6295

from those flags are treated as errors.

6296

6297

The current list of warning flags includes:

6298

6299

@table @samp

6300

@item -Wall

6301

Recommended @sc{gcc} warnings.

6302

6303

@item -Wdeclaration-after-statement

6304

6305

@sc{gcc} 3.x (and later) and @sc{c99} allow declarations mixed with

6306

code, but @sc{gcc} 2.x and @sc{c89} do not.

6307

6308

@item -Wpointer-arith

6309

6310

@item -Wformat-nonliteral

6311

Non-literal format strings, with a few exceptions, are bugs - they

6312

might contain unintended user-supplied format specifiers.

6313

Since @value{GDBN} uses the @code{format printf} attribute on all

6314

@code{printf} like functions this checks not just @code{printf} calls

6315

but also calls to functions such as @code{fprintf_unfiltered}.

6316

6317

@item -Wno-pointer-sign

6318

In version 4.0, GCC began warning about pointer argument passing or

6319

assignment even when the source and destination differed only in

6320

signedness. However, most @value{GDBN} code doesn't distinguish

6321

carefully between @code{char} and @code{unsigned char}. In early 2006

6322

the @value{GDBN} developers decided correcting these warnings wasn't

6323

worth the time it would take.

6324

6325

@item -Wno-unused-parameter

6326

Due to the way that @value{GDBN} is implemented many functions have

6327

unused parameters. Consequently this warning is avoided. The macro

6328

@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---

6329

it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that

6330

is being used.

6331

6332

@item -Wno-unused

6333

@itemx -Wno-switch

6334

@itemx -Wno-char-subscripts

6335

These are warnings which might be useful for @value{GDBN}, but are

6336

currently too noisy to enable with @samp{-Werror}.

6337

6338

@end table

6339

6340

@section Internal Error Recovery

6341

6342

During its execution, @value{GDBN} can encounter two types of errors.

6343

User errors and internal errors. User errors include not only a user

6344

entering an incorrect command but also problems arising from corrupt

6345

object files and system errors when interacting with the target.

6346

Internal errors include situations where @value{GDBN} has detected, at

6347

run time, a corrupt or erroneous situation.

6348

6349

When reporting an internal error, @value{GDBN} uses

6350

@code{internal_error} and @code{gdb_assert}.

6351

6352

@value{GDBN} must not call @code{abort} or @code{assert}.

6353

6354

@emph{Pragmatics: There is no @code{internal_warning} function. Either

6355

the code detected a user error, recovered from it and issued a

6356

@code{warning} or the code failed to correctly recover from the user

6357

error and issued an @code{internal_error}.}

6358

6359

@section Command Names

6360

6361

GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}.

6362

6363

@section Clean Design and Portable Implementation

6364

6365

@cindex design

6366

In addition to getting the syntax right, there's the little question of

6367

semantics. Some things are done in certain ways in @value{GDBN} because long

6368

experience has shown that the more obvious ways caused various kinds of

6369

trouble.

6370

6371

@cindex assumptions about targets

6372

You can't assume the byte order of anything that comes from a target

6373

(including @var{value}s, object files, and instructions). Such things

6374

must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in

6375

@value{GDBN}, or one of the swap routines defined in @file{bfd.h},

6376

such as @code{bfd_get_32}.

6377

6378

You can't assume that you know what interface is being used to talk to

6379

the target system. All references to the target must go through the

6380

current @code{target_ops} vector.

6381

6382

You can't assume that the host and target machines are the same machine

6383

(except in the ``native'' support modules). In particular, you can't

6384

assume that the target machine's header files will be available on the

6385

host machine. Target code must bring along its own header files --

6386

written from scratch or explicitly donated by their owner, to avoid

6387

copyright problems.

6388

6389

@cindex portability

6390

Insertion of new @code{#ifdef}'s will be frowned upon. It's much better

6391

to write the code portably than to conditionalize it for various

6392

systems.

6393

6394

@cindex system dependencies

6395

New @code{#ifdef}'s which test for specific compilers or manufacturers

6396

or operating systems are unacceptable. All @code{#ifdef}'s should test

6397

for features. The information about which configurations contain which

6398

features should be segregated into the configuration files. Experience

6399

has proven far too often that a feature unique to one particular system

6400

often creeps into other systems; and that a conditional based on some

6401

predefined macro for your current system will become worthless over

6402

time, as new versions of your system come out that behave differently

6403

with regard to this feature.

6404

6405

Adding code that handles specific architectures, operating systems,

6406

target interfaces, or hosts, is not acceptable in generic code.

6407

6408

@cindex portable file name handling

6409

@cindex file names, portability

6410

One particularly notorious area where system dependencies tend to

6411

creep in is handling of file names. The mainline @value{GDBN} code

6412

assumes Posix semantics of file names: absolute file names begin with

6413

a forward slash @file{/}, slashes are used to separate leading

6414

directories, case-sensitive file names. These assumptions are not

6415

necessarily true on non-Posix systems such as MS-Windows. To avoid

6416

system-dependent code where you need to take apart or construct a file

6417

name, use the following portable macros:

6418

6419

@table @code

6420

@findex HAVE_DOS_BASED_FILE_SYSTEM

6421

@item HAVE_DOS_BASED_FILE_SYSTEM

6422

This preprocessing symbol is defined to a non-zero value on hosts

6423

whose filesystems belong to the MS-DOS/MS-Windows family. Use this

6424

symbol to write conditional code which should only be compiled for

6425

such hosts.

6426

6427

@findex IS_DIR_SEPARATOR

6428

@item IS_DIR_SEPARATOR (@var{c})

6429

Evaluates to a non-zero value if @var{c} is a directory separator

6430

character. On Unix and GNU/Linux systems, only a slash @file{/} is

6431

such a character, but on Windows, both @file{/} and @file{\} will

6432

pass.

6433

6434

@findex IS_ABSOLUTE_PATH

6435

@item IS_ABSOLUTE_PATH (@var{file})

6436

Evaluates to a non-zero value if @var{file} is an absolute file name.

6437

For Unix and GNU/Linux hosts, a name which begins with a slash

6438

@file{/} is absolute. On DOS and Windows, @file{d:/foo} and

6439

@file{x:\bar} are also absolute file names.

6440

6441

@findex FILENAME_CMP

6442

@item FILENAME_CMP (@var{f1}, @var{f2})

6443

Calls a function which compares file names @var{f1} and @var{f2} as

6444

appropriate for the underlying host filesystem. For Posix systems,

6445

this simply calls @code{strcmp}; on case-insensitive filesystems it

6446

will call @code{strcasecmp} instead.

6447

6448

@findex DIRNAME_SEPARATOR

6449

@item DIRNAME_SEPARATOR

6450

Evaluates to a character which separates directories in

6451

@code{PATH}-style lists, typically held in environment variables.

6452

This character is @samp{:} on Unix, @samp{;} on DOS and Windows.

6453

6454

@findex SLASH_STRING

6455

@item SLASH_STRING

6456

This evaluates to a constant string you should use to produce an

6457

absolute filename from leading directories and the file's basename.

6458

@code{SLASH_STRING} is @code{"/"} on most systems, but might be

6459

@code{"\\"} for some Windows-based ports.

6460

@end table

6461

6462

In addition to using these macros, be sure to use portable library

6463

functions whenever possible. For example, to extract a directory or a

6464

basename part from a file name, use the @code{dirname} and

6465

@code{basename} library functions (available in @code{libiberty} for

6466

platforms which don't provide them), instead of searching for a slash

6467

with @code{strrchr}.

6468

6469

Another way to generalize @value{GDBN} along a particular interface is with an

6470

attribute struct. For example, @value{GDBN} has been generalized to handle

6471

multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but

6472

by defining the @code{target_ops} structure and having a current target (as

6473

well as a stack of targets below it, for memory references). Whenever

6474

something needs to be done that depends on which remote interface we are

6475

using, a flag in the current target_ops structure is tested (e.g.,

6476

@code{target_has_stack}), or a function is called through a pointer in the

6477

current target_ops structure. In this way, when a new remote interface

6478

is added, only one module needs to be touched---the one that actually

6479

implements the new remote interface. Other examples of

6480

attribute-structs are BFD access to multiple kinds of object file

6481

formats, or @value{GDBN}'s access to multiple source languages.

6482

6483

Please avoid duplicating code. For example, in @value{GDBN} 3.x all

6484

the code interfacing between @code{ptrace} and the rest of

6485

@value{GDBN} was duplicated in @file{*-dep.c}, and so changing

6486

something was very painful. In @value{GDBN} 4.x, these have all been

6487

consolidated into @file{infptrace.c}. @file{infptrace.c} can deal

6488

with variations between systems the same way any system-independent

6489

file would (hooks, @code{#if defined}, etc.), and machines which are

6490

radically different don't need to use @file{infptrace.c} at all.

6491

6492

All debugging code must be controllable using the @samp{set debug

6493

@var{module}} command. Do not use @code{printf} to print trace

6494

messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use

6495

@code{#ifdef DEBUG}.

6496

6497

@node Porting GDB

6498

6499

@chapter Porting @value{GDBN}

6500

@cindex porting to new machines

6501

6502

Most of the work in making @value{GDBN} compile on a new machine is in

6503

specifying the configuration of the machine. Porting a new

6504

architecture to @value{GDBN} can be broken into a number of steps.

6505

6506

@itemize @bullet

6507

6508

@item

6509

Ensure a @sc{bfd} exists for executables of the target architecture in

6510

the @file{bfd} directory. If one does not exist, create one by

6511

modifying an existing similar one.

6512

6513

@item

6514

Implement a disassembler for the target architecture in the @file{opcodes}

6515

directory.

6516

6517

@item

6518

Define the target architecture in the @file{gdb} directory

6519

(@pxref{Adding a New Target, , Adding a New Target}). Add the pattern

6520

for the new target to @file{configure.tgt} with the names of the files

6521

that contain the code. By convention the target architecture

6522

definition for an architecture @var{arch} is placed in

6523

@file{@var{arch}-tdep.c}.

6524

6525

Within @file{@var{arch}-tdep.c} define the function

6526

@code{_initialize_@var{arch}_tdep} which calls

6527

@code{gdbarch_register} to create the new @code{@w{struct

6528

gdbarch}} for the architecture.

6529

6530

@item

6531

If a new remote target is needed, consider adding a new remote target

6532

by defining a function

6533

@code{_initialize_remote_@var{arch}}. However if at all possible

6534

use the @value{GDBN} @emph{Remote Serial Protocol} for this and implement

6535

the server side protocol independently with the target.

6536

6537

@item

6538

If desired implement a simulator in the @file{sim} directory. This

6539

should create the library @file{libsim.a} implementing the interface

6540

in @file{remote-sim.h} (found in the @file{include} directory).

6541

6542

@item

6543

Build and test. If desired, lobby the @sc{gdb} steering group to

6544

have the new port included in the main distribution!

6545

6546

@item

6547

Add a description of the new architecture to the main @value{GDBN} user

6548

guide (@pxref{Configuration Specific Information, , Configuration

6549

Specific Information, gdb, Debugging with @value{GDBN}}).

6550

6551

@end itemize

6552

6553

@node Versions and Branches

6554

@chapter Versions and Branches

6555

6556

@section Versions

6557

6558

@value{GDBN}'s version is determined by the file

6559

@file{gdb/version.in} and takes one of the following forms:

6560

6561

@table @asis

6562

@item @var{major}.@var{minor}

6563

@itemx @var{major}.@var{minor}.@var{patchlevel}

6564

an official release (e.g., 6.2 or 6.2.1)

6565

@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}

6566

a snapshot taken at @var{YYYY}-@var{MM}-@var{DD}-gmt (e.g.,

6567

6.1.50.20020302, 6.1.90.20020304, or 6.1.0.20020308)

6568

@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}-cvs

6569

a @sc{cvs} check out drawn on @var{YYYY}-@var{MM}-@var{DD} (e.g.,

6570

6.1.50.20020302-cvs, 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)

6571

@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} (@var{vendor})

6572

a vendor specific release of @value{GDBN}, that while based on@*

6573

@var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD},

6574

may include additional changes

6575

@end table

6576

6577

@value{GDBN}'s mainline uses the @var{major} and @var{minor} version

6578

numbers from the most recent release branch, with a @var{patchlevel}

6579

of 50. At the time each new release branch is created, the mainline's

6580

@var{major} and @var{minor} version numbers are updated.

6581

6582

@value{GDBN}'s release branch is similar. When the branch is cut, the

6583

@var{patchlevel} is changed from 50 to 90. As draft releases are

6584

drawn from the branch, the @var{patchlevel} is incremented. Once the

6585

first release (@var{major}.@var{minor}) has been made, the

6586

@var{patchlevel} is set to 0 and updates have an incremented

6587

@var{patchlevel}.

6588

6589

For snapshots, and @sc{cvs} check outs, it is also possible to

6590

identify the @sc{cvs} origin:

6591

6592

@table @asis

6593

@item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD}

6594

drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302)

6595

@item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD}

6596

@itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{}

6597

drawn from a release branch prior to the release (e.g.,

6598

6.1.90.20020304)

6599

@item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD}

6600

@itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{}

6601

drawn from a release branch after the release (e.g., 6.2.0.20020308)

6602

@end table

6603

6604

If the previous @value{GDBN} version is 6.1 and the current version is

6605

6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor},

6606

here's an illustration of a typical sequence:

6607

6608

@smallexample

6609

<HEAD>

6610

|

6611

6.1.50.20020302-cvs

6612

|

6613

+--------------------------.

6614

| <gdb_6_2-branch>

6615

| |

6616

6.2.50.20020303-cvs 6.1.90 (draft #1)

6617

| |

6618

6.2.50.20020304-cvs 6.1.90.20020304-cvs

6619

| |

6620

6.2.50.20020305-cvs 6.1.91 (draft #2)

6621

| |

6622

6.2.50.20020306-cvs 6.1.91.20020306-cvs

6623

| |

6624

6.2.50.20020307-cvs 6.2 (release)

6625

| |

6626

6.2.50.20020308-cvs 6.2.0.20020308-cvs

6627

| |

6628

6.2.50.20020309-cvs 6.2.1 (update)

6629

| |

6630

6.2.50.20020310-cvs <branch closed>

6631

|

6632

6.2.50.20020311-cvs

6633

|

6634

+--------------------------.

6635

| <gdb_6_3-branch>

6636

| |

6637

6.3.50.20020312-cvs 6.2.90 (draft #1)

6638

| |

6639

@end smallexample

6640

6641

@section Release Branches

6642

@cindex Release Branches

6643

6644

@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a

6645

single release branch, and identifies that branch using the @sc{cvs}

6646

branch tags:

6647

6648

@smallexample

6649

gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint

6650

gdb_@var{major}_@var{minor}-branch

6651

gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release

6652

@end smallexample

6653

6654

@emph{Pragmatics: To help identify the date at which a branch or

6655

release is made, both the branchpoint and release tags include the

6656

date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The

6657

branch tag, denoting the head of the branch, does not need this.}

6658

6659

@section Vendor Branches

6660

@cindex vendor branches

6661

6662

To avoid version conflicts, vendors are expected to modify the file

6663

@file{gdb/version.in} to include a vendor unique alphabetic identifier

6664

(an official @value{GDBN} release never uses alphabetic characters in

6665

its version identifier). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit

6666

Inc Patch 2)}.

6667

6668

@section Experimental Branches

6669

@cindex experimental branches

6670

6671

@subsection Guidelines

6672

6673

@value{GDBN} permits the creation of branches, cut from the @sc{cvs}

6674

repository, for experimental development. Branches make it possible

6675

for developers to share preliminary work, and maintainers to examine

6676

significant new developments.

6677

6678

The following are a set of guidelines for creating such branches:

6679

6680

@table @emph

6681

6682

@item a branch has an owner

6683

The owner can set further policy for a branch, but may not change the

6684

ground rules. In particular, they can set a policy for commits (be it

6685

adding more reviewers or deciding who can commit).

6686

6687

@item all commits are posted

6688

All changes committed to a branch shall also be posted to

6689

@email{gdb-patches@@sourceware.org, the @value{GDBN} patches

6690

mailing list}. While commentary on such changes are encouraged, people

6691

should remember that the changes only apply to a branch.

6692

6693

@item all commits are covered by an assignment

6694

This ensures that all changes belong to the Free Software Foundation,

6695

and avoids the possibility that the branch may become contaminated.

6696

6697

@item a branch is focused

6698

A focused branch has a single objective or goal, and does not contain

6699

unnecessary or irrelevant changes. Cleanups, where identified, being

6700

be pushed into the mainline as soon as possible.

6701

6702

@item a branch tracks mainline

6703

This keeps the level of divergence under control. It also keeps the

6704

pressure on developers to push cleanups and other stuff into the

6705

mainline.

6706

6707

@item a branch shall contain the entire @value{GDBN} module

6708

The @value{GDBN} module @code{gdb} should be specified when creating a

6709

branch (branches of individual files should be avoided). @xref{Tags}.

6710

6711

@item a branch shall be branded using @file{version.in}

6712

The file @file{gdb/version.in} shall be modified so that it identifies

6713

the branch @var{owner} and branch @var{name}, e.g.,

6714

@samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}.

6715

6716

@end table

6717

6718

@subsection Tags

6719

@anchor{Tags}

6720

6721

To simplify the identification of @value{GDBN} branches, the following

6722

branch tagging convention is strongly recommended:

6723

6724

@table @code

6725

6726

@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint

6727

@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch

6728

The branch point and corresponding branch tag. @var{YYYYMMDD} is the

6729

date that the branch was created. A branch is created using the

6730

sequence: @anchor{experimental branch tags}

6731

@smallexample

6732

cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb

6733

cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \

6734

@var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb

6735

@end smallexample

6736

6737

@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint

6738

The tagged point, on the mainline, that was used when merging the branch

6739

on @var{yyyymmdd}. To merge in all changes since the branch was cut,

6740

use a command sequence like:

6741

@smallexample

6742

cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb

6743

cvs update \

6744

-j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint

6745

-j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint

6746

@end smallexample

6747

@noindent

6748

Similar sequences can be used to just merge in changes since the last

6749

merge.

6750

6751

@end table

6752

6753

@noindent

6754

For further information on @sc{cvs}, see

6755

@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.

6756

6757

@node Start of New Year Procedure

6758

@chapter Start of New Year Procedure

6759

@cindex new year procedure

6760

6761

At the start of each new year, the following actions should be performed:

6762

6763

@itemize @bullet

6764

@item

6765

Rotate the ChangeLog file

6766

6767

The current @file{ChangeLog} file should be renamed into

6768

@file{ChangeLog-YYYY} where YYYY is the year that has just passed.

6769

A new @file{ChangeLog} file should be created, and its contents should

6770

contain a reference to the previous ChangeLog. The following should

6771

also be preserved at the end of the new ChangeLog, in order to provide

6772

the appropriate settings when editing this file with Emacs:

6773

@smallexample

6774

Local Variables:

6775

mode: change-log

6776

left-margin: 8

6777

fill-column: 74

6778

version-control: never

6779

coding: utf-8

6780

End:

6781

@end smallexample

6782

6783

@item

6784

Add an entry for the newly created ChangeLog file (@file{ChangeLog-YYYY})

6785

in @file{gdb/config/djgpp/fnchange.lst}.

6786

6787

@item

6788

Update the copyright year in the startup message

6789

6790

Update the copyright year in:

6791

@itemize @bullet

6792

@item

6793

file @file{top.c}, function @code{print_gdb_version}

6794

@item

6795

file @file{gdbserver/server.c}, function @code{gdbserver_version}

6796

@item

6797

file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version}

6798

@end itemize

6799

6800

@item

6801

Run the @file{copyright.sh} script to add the new year in the copyright

6802

notices of most source files. This script requires Emacs 22 or later to

6803

be installed.

6804

6805

@item

6806

The new year also needs to be added manually in all other files that

6807

are not already taken care of by the @file{copyright.sh} script:

6808

@itemize @bullet

6809

@item

6810

@file{*.s}

6811

@item

6812

@file{*.f}

6813

@item

6814

@file{*.f90}

6815

@item

6816

@file{*.igen}

6817

@item

6818

@file{*.ac}

6819

@item

6820

@file{*.texi}

6821

@item

6822

@file{*.texinfo}

6823

@item

6824

@file{*.tex}

6825

@item

6826

@file{*.defs}

6827

@item

6828

@file{*.1}

6829

@end itemize

6830

6831

@end itemize

6832

6833

@node Releasing GDB

6834

6835

@chapter Releasing @value{GDBN}

6836

@cindex making a new release of gdb

6837

6838

@section Branch Commit Policy

6839

6840

The branch commit policy is pretty slack. @value{GDBN} releases 5.0,

6841

5.1 and 5.2 all used the below:

6842

6843

@itemize @bullet

6844

@item

6845

The @file{gdb/MAINTAINERS} file still holds.

6846

@item

6847

Don't fix something on the branch unless/until it is also fixed in the

6848

trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}

6849

file is better than committing a hack.

6850

@item

6851

When considering a patch for the branch, suggested criteria include:

6852

Does it fix a build? Does it fix the sequence @kbd{break main; run}

6853

when debugging a static binary?

6854

@item

6855

The further a change is from the core of @value{GDBN}, the less likely

6856

the change will worry anyone (e.g., target specific code).

6857

@item

6858

Only post a proposal to change the core of @value{GDBN} after you've

6859

sent individual bribes to all the people listed in the

6860

@file{MAINTAINERS} file @t{;-)}

6861

@end itemize

6862

6863

@emph{Pragmatics: Provided updates are restricted to non-core

6864

functionality there is little chance that a broken change will be fatal.

6865

This means that changes such as adding a new architectures or (within

6866

reason) support for a new host are considered acceptable.}

6867

6868

6869

@section Obsoleting code

6870

6871

Before anything else, poke the other developers (and around the source

6872

code) to see if there is anything that can be removed from @value{GDBN}

6873

(an old target, an unused file).

6874

6875

Obsolete code is identified by adding an @code{OBSOLETE} prefix to every

6876

line. Doing this means that it is easy to identify something that has

6877

been obsoleted when greping through the sources.

6878

6879

The process is done in stages --- this is mainly to ensure that the

6880

wider @value{GDBN} community has a reasonable opportunity to respond.

6881

Remember, everything on the Internet takes a week.

6882

6883

@enumerate

6884

@item

6885

Post the proposal on @email{gdb@@sourceware.org, the GDB mailing

6886

list} Creating a bug report to track the task's state, is also highly

6887

recommended.

6888

@item

6889

Wait a week or so.

6890

@item

6891

Post the proposal on @email{gdb-announce@@sourceware.org, the GDB

6892

Announcement mailing list}.

6893

@item

6894

Wait a week or so.

6895

@item

6896

Go through and edit all relevant files and lines so that they are

6897

prefixed with the word @code{OBSOLETE}.

6898

@item

6899

Wait until the next GDB version, containing this obsolete code, has been

6900

released.

6901

@item

6902

Remove the obsolete code.

6903

@end enumerate

6904

6905

@noindent

6906

@emph{Maintainer note: While removing old code is regrettable it is

6907

hopefully better for @value{GDBN}'s long term development. Firstly it

6908

helps the developers by removing code that is either no longer relevant

6909

or simply wrong. Secondly since it removes any history associated with

6910

the file (effectively clearing the slate) the developer has a much freer

6911

hand when it comes to fixing broken files.}

6912

6913

6914

6915

@section Before the Branch

6916

6917

The most important objective at this stage is to find and fix simple

6918

changes that become a pain to track once the branch is created. For

6919

instance, configuration problems that stop @value{GDBN} from even

6920

building. If you can't get the problem fixed, document it in the

6921

@file{gdb/PROBLEMS} file.

6922

6923

@subheading Prompt for @file{gdb/NEWS}

6924

6925

People always forget. Send a post reminding them but also if you know

6926

something interesting happened add it yourself. The @code{schedule}

6927

script will mention this in its e-mail.

6928

6929

@subheading Review @file{gdb/README}

6930

6931

Grab one of the nightly snapshots and then walk through the

6932

@file{gdb/README} looking for anything that can be improved. The

6933

@code{schedule} script will mention this in its e-mail.

6934

6935

@subheading Refresh any imported files.

6936

6937

A number of files are taken from external repositories. They include:

6938

6939

@itemize @bullet

6940

@item

6941

@file{texinfo/texinfo.tex}

6942

@item

6943

@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}

6944

file)

6945

@item

6946

@file{etc/standards.texi}, @file{etc/make-stds.texi}

6947

@end itemize

6948

6949

@subheading Check the ARI

6950

6951

@uref{http://sourceware.org/gdb/ari,,A.R.I.} is an @code{awk} script

6952

(Awk Regression Index ;-) that checks for a number of errors and coding

6953

conventions. The checks include things like using @code{malloc} instead

6954

of @code{xmalloc} and file naming problems. There shouldn't be any

6955

regressions.

6956

6957

@subsection Review the bug data base

6958

6959

Close anything obviously fixed.

6960

6961

@subsection Check all cross targets build

6962

6963

The targets are listed in @file{gdb/MAINTAINERS}.

6964

6965

6966

@section Cut the Branch

6967

6968

@subheading Create the branch

6969

6970

@smallexample

6971

$ u=5.1

6972

$ v=5.2

6973

$ V=`echo $v | sed 's/\./_/g'`

6974

$ D=`date -u +%Y-%m-%d`

6975

$ echo $u $V $D

6976

5.1 5_2 2002-03-03

6977

$ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \

6978

-D $D-gmt gdb_$V-$D-branchpoint insight

6979

cvs -f -d :ext:sourceware.org:/cvs/src rtag

6980

-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight

6981

$ ^echo ^^

6982

...

6983

$ echo cvs -f -d :ext:sourceware.org:/cvs/src rtag \

6984

-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight

6985

cvs -f -d :ext:sourceware.org:/cvs/src rtag \

6986

-b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight

6987

$ ^echo ^^

6988

...

6989

$

6990

@end smallexample

6991

6992

@itemize @bullet

6993

@item

6994

By using @kbd{-D YYYY-MM-DD-gmt}, the branch is forced to an exact

6995

date/time.

6996

@item

6997

The trunk is first tagged so that the branch point can easily be found.

6998

@item

6999

Insight, which includes @value{GDBN}, is tagged at the same time.

7000

@item

7001

@file{version.in} gets bumped to avoid version number conflicts.

7002

@item

7003

The reading of @file{.cvsrc} is disabled using @file{-f}.

7004

@end itemize

7005

7006

@subheading Update @file{version.in}

7007

7008

@smallexample

7009

$ u=5.1

7010

$ v=5.2

7011

$ V=`echo $v | sed 's/\./_/g'`

7012

$ echo $u $v$V

7013

5.1 5_2

7014

$ cd /tmp

7015

$ echo cvs -f -d :ext:sourceware.org:/cvs/src co \

7016

-r gdb_$V-branch src/gdb/version.in

7017

cvs -f -d :ext:sourceware.org:/cvs/src co

7018

-r gdb_5_2-branch src/gdb/version.in

7019

$ ^echo ^^

7020

U src/gdb/version.in

7021

$ cd src/gdb

7022

$ echo $u.90-0000-00-00-cvs > version.in

7023

$ cat version.in

7024

5.1.90-0000-00-00-cvs

7025

$ cvs -f commit version.in

7026

@end smallexample

7027

7028

@itemize @bullet

7029

@item

7030

@file{0000-00-00} is used as a date to pump prime the version.in update

7031

mechanism.

7032

@item

7033

@file{.90} and the previous branch version are used as fairly arbitrary

7034

initial branch version number.

7035

@end itemize

7036

7037

7038

@subheading Update the web and news pages

7039

7040

Something?

7041

7042

@subheading Tweak cron to track the new branch

7043

7044

The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table.

7045

This file needs to be updated so that:

7046

7047

@itemize @bullet

7048

@item

7049

A daily timestamp is added to the file @file{version.in}.

7050

@item

7051

The new branch is included in the snapshot process.

7052

@end itemize

7053

7054

@noindent

7055

See the file @file{gdbadmin/cron/README} for how to install the updated

7056

cron table.

7057

7058

The file @file{gdbadmin/ss/README} should also be reviewed to reflect

7059

any changes. That file is copied to both the branch/ and current/

7060

snapshot directories.

7061

7062

7063

@subheading Update the NEWS and README files

7064

7065

The @file{NEWS} file needs to be updated so that on the branch it refers

7066

to @emph{changes in the current release} while on the trunk it also

7067

refers to @emph{changes since the current release}.

7068

7069

The @file{README} file needs to be updated so that it refers to the

7070

current release.

7071

7072

@subheading Post the branch info

7073

7074

Send an announcement to the mailing lists:

7075

7076

@itemize @bullet

7077

@item

7078

@email{gdb-announce@@sourceware.org, GDB Announcement mailing list}

7079

@item

7080

@email{gdb@@sourceware.org, GDB Discussion mailing list} and

7081

@email{gdb-testers@@sourceware.org, GDB Testers mailing list}

7082

@end itemize

7083

7084

@emph{Pragmatics: The branch creation is sent to the announce list to

7085

ensure that people people not subscribed to the higher volume discussion

7086

list are alerted.}

7087

7088

The announcement should include:

7089

7090

@itemize @bullet

7091

@item

7092

The branch tag.

7093

@item

7094

How to check out the branch using CVS.

7095

@item

7096

The date/number of weeks until the release.

7097

@item

7098

The branch commit policy still holds.

7099

@end itemize

7100

7101

@section Stabilize the branch

7102

7103

Something goes here.

7104

7105

@section Create a Release

7106

7107

The process of creating and then making available a release is broken

7108

down into a number of stages. The first part addresses the technical

7109

process of creating a releasable tar ball. The later stages address the

7110

process of releasing that tar ball.

7111

7112

When making a release candidate just the first section is needed.

7113

7114

@subsection Create a release candidate

7115

7116

The objective at this stage is to create a set of tar balls that can be

7117

made available as a formal release (or as a less formal release

7118

candidate).

7119

7120

@subsubheading Freeze the branch

7121

7122

Send out an e-mail notifying everyone that the branch is frozen to

7123

@email{gdb-patches@@sourceware.org}.

7124

7125

@subsubheading Establish a few defaults.

7126

7127

@smallexample

7128

$ b=gdb_5_2-branch

7129

$ v=5.2

7130

$ t=/sourceware/snapshot-tmp/gdbadmin-tmp

7131

$ echo $t/$b/$v

7132

/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2

7133

$ mkdir -p $t/$b/$v

7134

$ cd $t/$b/$v

7135

$ pwd

7136

/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2

7137

$ which autoconf

7138

/home/gdbadmin/bin/autoconf

7139

$

7140

@end smallexample

7141

7142

@noindent

7143

Notes:

7144

7145

@itemize @bullet

7146

@item

7147

Check the @code{autoconf} version carefully. You want to be using the

7148

version documented in the toplevel @file{README-maintainer-mode} file.

7149

It is very unlikely that the version of @code{autoconf} installed in

7150

system directories (e.g., @file{/usr/bin/autoconf}) is correct.

7151

@end itemize

7152

7153

@subsubheading Check out the relevant modules:

7154

7155

@smallexample

7156

$ for m in gdb insight

7157

do

7158

( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )

7159

done

7160

$

7161

@end smallexample

7162

7163

@noindent

7164

Note:

7165

7166

@itemize @bullet

7167

@item

7168

The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't

7169

any confusion between what is written here and what your local

7170

@code{cvs} really does.

7171

@end itemize

7172

7173

@subsubheading Update relevant files.

7174

7175

@table @file

7176

7177

@item gdb/NEWS

7178

7179

Major releases get their comments added as part of the mainline. Minor

7180

releases should probably mention any significant bugs that were fixed.

7181

7182

Don't forget to include the @file{ChangeLog} entry.

7183

7184

@smallexample

7185

$ emacs gdb/src/gdb/NEWS

7186

...

7187

c-x 4 a

7188

...

7189

c-x c-s c-x c-c

7190

$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS

7191

$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog

7192

@end smallexample

7193

7194

@item gdb/README

7195

7196

You'll need to update:

7197

7198

@itemize @bullet

7199

@item

7200

The version.

7201

@item

7202

The update date.

7203

@item

7204

Who did it.

7205

@end itemize

7206

7207

@smallexample

7208

$ emacs gdb/src/gdb/README

7209

...

7210

c-x 4 a

7211

...

7212

c-x c-s c-x c-c

7213

$ cp gdb/src/gdb/README insight/src/gdb/README

7214

$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog

7215

@end smallexample

7216

7217

@emph{Maintainer note: Hopefully the @file{README} file was reviewed

7218

before the initial branch was cut so just a simple substitute is needed

7219

to get it updated.}

7220

7221

@emph{Maintainer note: Other projects generate @file{README} and

7222

@file{INSTALL} from the core documentation. This might be worth

7223

pursuing.}

7224

7225

@item gdb/version.in

7226

7227

@smallexample

7228

$ echo $v > gdb/src/gdb/version.in

7229

$ cat gdb/src/gdb/version.in

7230

5.2

7231

$ emacs gdb/src/gdb/version.in

7232

...

7233

c-x 4 a

7234

... Bump to version ...

7235

c-x c-s c-x c-c

7236

$ cp gdb/src/gdb/version.in insight/src/gdb/version.in

7237

$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog

7238

@end smallexample

7239

7240

@end table

7241

7242

@subsubheading Do the dirty work

7243

7244

This is identical to the process used to create the daily snapshot.

7245

7246

@smallexample

7247

$ for m in gdb insight

7248

do

7249

( cd $m/src && gmake -f src-release $m.tar )

7250

done

7251

@end smallexample

7252

7253

If the top level source directory does not have @file{src-release}

7254

(@value{GDBN} version 5.3.1 or earlier), try these commands instead:

7255

7256

@smallexample

7257

$ for m in gdb insight

7258

do

7259

( cd $m/src && gmake -f Makefile.in $m.tar )

7260

done

7261

@end smallexample

7262

7263

@subsubheading Check the source files

7264

7265

You're looking for files that have mysteriously disappeared.

7266

@kbd{distclean} has the habit of deleting files it shouldn't. Watch out

7267

for the @file{version.in} update @kbd{cronjob}.

7268

7269

@smallexample

7270

$ ( cd gdb/src && cvs -f -q -n update )

7271

M djunpack.bat

7272

? gdb-5.1.91.tar

7273

? proto-toplev

7274

@dots{} lots of generated files @dots{}

7275

M gdb/ChangeLog

7276

M gdb/NEWS

7277

M gdb/README

7278

M gdb/version.in

7279

@dots{} lots of generated files @dots{}

7280

$

7281

@end smallexample

7282

7283

@noindent

7284

@emph{Don't worry about the @file{gdb.info-??} or

7285

@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1}

7286

was also generated only something strange with CVS means that they

7287

didn't get suppressed). Fixing it would be nice though.}

7288

7289

@subsubheading Create compressed versions of the release

7290

7291

@smallexample

7292

$ cp */src/*.tar .

7293

$ cp */src/*.bz2 .

7294

$ ls -F

7295

gdb/ gdb-5.2.tar insight/ insight-5.2.tar

7296

$ for m in gdb insight

7297

do

7298

bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2

7299

gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz

7300

done

7301

$

7302

@end smallexample

7303

7304

@noindent

7305

Note:

7306

7307

@itemize @bullet

7308

@item

7309

A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since,

7310

in that mode, @code{gzip} does not know the name of the file and, hence,

7311

can not include it in the compressed file. This is also why the release

7312

process runs @code{tar} and @code{bzip2} as separate passes.

7313

@end itemize

7314

7315

@subsection Sanity check the tar ball

7316

7317

Pick a popular machine (Solaris/PPC?) and try the build on that.

7318

7319

@smallexample

7320

$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -

7321

$ cd gdb-5.2

7322

$ ./configure

7323

$ make

7324

@dots{}

7325

$ ./gdb/gdb ./gdb/gdb

7326

GNU gdb 5.2

7327

@dots{}

7328

(gdb) b main

7329

Breakpoint 1 at 0x80732bc: file main.c, line 734.

7330

(gdb) run

7331

Starting program: /tmp/gdb-5.2/gdb/gdb

7332

7333

Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734

7334

734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);

7335

(gdb) print args

7336

$1 = @{argc = 136426532, argv = 0x821b7f0@}

7337

(gdb)

7338

@end smallexample

7339

7340

@subsection Make a release candidate available

7341

7342

If this is a release candidate then the only remaining steps are:

7343

7344

@enumerate

7345

@item

7346

Commit @file{version.in} and @file{ChangeLog}

7347

@item

7348

Tweak @file{version.in} (and @file{ChangeLog} to read

7349

@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update

7350

process can restart.

7351

@item

7352

Make the release candidate available in

7353

@uref{ftp://sourceware.org/pub/gdb/snapshots/branch}

7354

@item

7355

Notify the relevant mailing lists ( @email{gdb@@sourceware.org} and

7356

@email{gdb-testers@@sourceware.org} that the candidate is available.

7357

@end enumerate

7358

7359

@subsection Make a formal release available

7360

7361

(And you thought all that was required was to post an e-mail.)

7362

7363

@subsubheading Install on sware

7364

7365

Copy the new files to both the release and the old release directory:

7366

7367

@smallexample

7368

$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/

7369

$ cp *.bz2 *.gz ~ftp/pub/gdb/releases

7370

@end smallexample

7371

7372

@noindent

7373

Clean up the releases directory so that only the most recent releases

7374

are available (e.g.@: keep 5.2 and 5.2.1 but remove 5.1):

7375

7376

@smallexample

7377

$ cd ~ftp/pub/gdb/releases

7378

$ rm @dots{}

7379

@end smallexample

7380

7381

@noindent

7382

Update the file @file{README} and @file{.message} in the releases

7383

directory:

7384

7385

@smallexample

7386

$ vi README

7387

@dots{}

7388

$ rm -f .message

7389

$ ln README .message

7390

@end smallexample

7391

7392

@subsubheading Update the web pages.

7393

7394

@table @file

7395

7396

@item htdocs/download/ANNOUNCEMENT

7397

This file, which is posted as the official announcement, includes:

7398

@itemize @bullet

7399

@item

7400

General announcement.

7401

@item

7402

News. If making an @var{M}.@var{N}.1 release, retain the news from

7403

earlier @var{M}.@var{N} release.

7404

@item

7405

Errata.

7406

@end itemize

7407

7408

@item htdocs/index.html

7409

@itemx htdocs/news/index.html

7410

@itemx htdocs/download/index.html

7411

These files include:

7412

@itemize @bullet

7413

@item

7414

Announcement of the most recent release.

7415

@item

7416

News entry (remember to update both the top level and the news directory).

7417

@end itemize

7418

These pages also need to be regenerate using @code{index.sh}.

7419

7420

@item download/onlinedocs/

7421

You need to find the magic command that is used to generate the online

7422

docs from the @file{.tar.bz2}. The best way is to look in the output

7423

from one of the nightly @code{cron} jobs and then just edit accordingly.

7424

Something like:

7425

7426

@smallexample

7427

$ ~/ss/update-web-docs \

7428

~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \

7429

$PWD/www \

7430

/www/sourceware/htdocs/gdb/download/onlinedocs \

7431

gdb

7432

@end smallexample

7433

7434

@item download/ari/

7435

Just like the online documentation. Something like:

7436

7437

@smallexample

7438

$ /bin/sh ~/ss/update-web-ari \

7439

~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \

7440

$PWD/www \

7441

/www/sourceware/htdocs/gdb/download/ari \

7442

gdb

7443

@end smallexample

7444

7445

@end table

7446

7447

@subsubheading Shadow the pages onto gnu

7448

7449

Something goes here.

7450

7451

7452

@subsubheading Install the @value{GDBN} tar ball on GNU

7453

7454

At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in

7455

@file{~ftp/gnu/gdb}.

7456

7457

@subsubheading Make the @file{ANNOUNCEMENT}

7458

7459

Post the @file{ANNOUNCEMENT} file you created above to:

7460

7461

@itemize @bullet

7462

@item

7463

@email{gdb-announce@@sourceware.org, GDB Announcement mailing list}

7464

@item

7465

@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a

7466

day or so to let things get out)

7467

@item

7468

@email{bug-gdb@@gnu.org, GDB Bug Report mailing list}

7469

@end itemize

7470

7471

@subsection Cleanup

7472

7473

The release is out but you're still not finished.

7474

7475

@subsubheading Commit outstanding changes

7476

7477

In particular you'll need to commit any changes to:

7478

7479

@itemize @bullet

7480

@item

7481

@file{gdb/ChangeLog}

7482

@item

7483

@file{gdb/version.in}

7484

@item

7485

@file{gdb/NEWS}

7486

@item

7487

@file{gdb/README}

7488

@end itemize

7489

7490

@subsubheading Tag the release

7491

7492

Something like:

7493

7494

@smallexample

7495

$ d=`date -u +%Y-%m-%d`

7496

$ echo $d

7497

2002-01-24

7498

$ ( cd insight/src/gdb && cvs -f -q update )

7499

$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )

7500

@end smallexample

7501

7502

Insight is used since that contains more of the release than

7503

@value{GDBN}.

7504

7505

@subsubheading Mention the release on the trunk

7506

7507

Just put something in the @file{ChangeLog} so that the trunk also

7508

indicates when the release was made.

7509

7510

@subsubheading Restart @file{gdb/version.in}

7511

7512

If @file{gdb/version.in} does not contain an ISO date such as

7513

@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having

7514

committed all the release changes it can be set to

7515

@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}

7516

is important - it affects the snapshot process).

7517

7518

Don't forget the @file{ChangeLog}.

7519

7520

@subsubheading Merge into trunk

7521

7522

The files committed to the branch may also need changes merged into the

7523

trunk.

7524

7525

@subsubheading Revise the release schedule

7526

7527

Post a revised release schedule to @email{gdb@@sourceware.org, GDB

7528

Discussion List} with an updated announcement. The schedule can be

7529

generated by running:

7530

7531

@smallexample

7532

$ ~/ss/schedule `date +%s` schedule

7533

@end smallexample

7534

7535

@noindent

7536

The first parameter is approximate date/time in seconds (from the epoch)

7537

of the most recent release.

7538

7539

Also update the schedule @code{cronjob}.

7540

7541

@section Post release

7542

7543

Remove any @code{OBSOLETE} code.

7544

7545

@node Testsuite

7546

7547

@chapter Testsuite

7548

@cindex test suite

7549

7550

The testsuite is an important component of the @value{GDBN} package.

7551

While it is always worthwhile to encourage user testing, in practice

7552

this is rarely sufficient; users typically use only a small subset of

7553

the available commands, and it has proven all too common for a change

7554

to cause a significant regression that went unnoticed for some time.

7555

7556

The @value{GDBN} testsuite uses the DejaGNU testing framework. The

7557

tests themselves are calls to various @code{Tcl} procs; the framework

7558

runs all the procs and summarizes the passes and fails.

7559

7560

@section Using the Testsuite

7561

7562

@cindex running the test suite

7563

To run the testsuite, simply go to the @value{GDBN} object directory (or to the

7564

testsuite's objdir) and type @code{make check}. This just sets up some

7565

environment variables and invokes DejaGNU's @code{runtest} script. While

7566

the testsuite is running, you'll get mentions of which test file is in use,

7567

and a mention of any unexpected passes or fails. When the testsuite is

7568

finished, you'll get a summary that looks like this:

7569

7570

@smallexample

7571

=== gdb Summary ===

7572

7573

# of expected passes 6016

7574

# of unexpected failures 58

7575

# of unexpected successes 5

7576

# of expected failures 183

7577

# of unresolved testcases 3

7578

# of untested testcases 5

7579

@end smallexample

7580

7581

To run a specific test script, type:

7582

@example

7583

make check RUNTESTFLAGS='@var{tests}'

7584

@end example

7585

where @var{tests} is a list of test script file names, separated by

7586

spaces.

7587

7588

If you use GNU make, you can use its @option{-j} option to run the

7589

testsuite in parallel. This can greatly reduce the amount of time it

7590

takes for the testsuite to run. In this case, if you set

7591

@code{RUNTESTFLAGS} then, by default, the tests will be run serially

7592

even under @option{-j}. You can override this and force a parallel run

7593

by setting the @code{make} variable @code{FORCE_PARALLEL} to any

7594

non-empty value. Note that the parallel @kbd{make check} assumes

7595

that you want to run the entire testsuite, so it is not compatible

7596

with some dejagnu options, like @option{--directory}.

7597

7598

The ideal test run consists of expected passes only; however, reality

7599

conspires to keep us from this ideal. Unexpected failures indicate

7600

real problems, whether in @value{GDBN} or in the testsuite. Expected

7601

failures are still failures, but ones which have been decided are too

7602

hard to deal with at the time; for instance, a test case might work

7603

everywhere except on AIX, and there is no prospect of the AIX case

7604

being fixed in the near future. Expected failures should not be added

7605

lightly, since you may be masking serious bugs in @value{GDBN}.

7606

Unexpected successes are expected fails that are passing for some

7607

reason, while unresolved and untested cases often indicate some minor

7608

catastrophe, such as the compiler being unable to deal with a test

7609

program.

7610

7611

When making any significant change to @value{GDBN}, you should run the

7612

testsuite before and after the change, to confirm that there are no

7613

regressions. Note that truly complete testing would require that you

7614

run the testsuite with all supported configurations and a variety of

7615

compilers; however this is more than really necessary. In many cases

7616

testing with a single configuration is sufficient. Other useful

7617

options are to test one big-endian (Sparc) and one little-endian (x86)

7618

host, a cross config with a builtin simulator (powerpc-eabi,

7619

mips-elf), or a 64-bit host (Alpha).

7620

7621

If you add new functionality to @value{GDBN}, please consider adding

7622

tests for it as well; this way future @value{GDBN} hackers can detect

7623

and fix their changes that break the functionality you added.

7624

Similarly, if you fix a bug that was not previously reported as a test

7625

failure, please add a test case for it. Some cases are extremely

7626

difficult to test, such as code that handles host OS failures or bugs

7627

in particular versions of compilers, and it's OK not to try to write

7628

tests for all of those.

7629

7630

DejaGNU supports separate build, host, and target machines. However,

7631

some @value{GDBN} test scripts do not work if the build machine and

7632

the host machine are not the same. In such an environment, these scripts

7633

will give a result of ``UNRESOLVED'', like this:

7634

7635

@smallexample

7636

UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.

7637

@end smallexample

7638

7639

@section Testsuite Parameters

7640

7641

Several variables exist to modify the behavior of the testsuite.

7642

7643

@itemize @bullet

7644

7645

@item @code{TRANSCRIPT}

7646

7647

Sometimes it is convenient to get a transcript of the commands which

7648

the testsuite sends to @value{GDBN}. For example, if @value{GDBN}

7649

crashes during testing, a transcript can be used to more easily

7650

reconstruct the failure when running @value{GDBN} under @value{GDBN}.

7651

7652

You can instruct the @value{GDBN} testsuite to write transcripts by

7653

setting the DejaGNU variable @code{TRANSCRIPT} (to any value)

7654

before invoking @code{runtest} or @kbd{make check}. The transcripts

7655

will be written into DejaGNU's output directory. One transcript will

7656

be made for each invocation of @value{GDBN}; they will be named

7657

@file{transcript.@var{n}}, where @var{n} is an integer. The first

7658

line of the transcript file will show how @value{GDBN} was invoked;

7659

each subsequent line is a command sent as input to @value{GDBN}.

7660

7661

@smallexample

7662

make check RUNTESTFLAGS=TRANSCRIPT=y

7663

@end smallexample

7664

7665

Note that the transcript is not always complete. In particular, tests

7666

of completion can yield partial command lines.

7667

7668

@item @code{GDB}

7669

7670

Sometimes one wishes to test a different @value{GDBN} than the one in the build

7671

directory. For example, one may wish to run the testsuite on

7672

@file{/usr/bin/gdb}.

7673

7674

@smallexample

7675

make check RUNTESTFLAGS=GDB=/usr/bin/gdb

7676

@end smallexample

7677

7678

@item @code{GDBSERVER}

7679

7680

When testing a different @value{GDBN}, it is often useful to also test a

7681

different gdbserver.

7682

7683

@smallexample

7684

make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver"

7685

@end smallexample

7686

7687

@item @code{INTERNAL_GDBFLAGS}

7688

7689

When running the testsuite normally one doesn't want whatever is in

7690

@file{~/.gdbinit} to interfere with the tests, therefore the test harness

7691

passes @option{-nx} to @value{GDBN}. One also doesn't want any windowed

7692

version of @value{GDBN}, e.g., @command{gdbtui}, to run.

7693

This is achieved via @code{INTERNAL_GDBFLAGS}.

7694

7695

@smallexample

7696

set INTERNAL_GDBFLAGS "-nw -nx"

7697

@end smallexample

7698

7699

This is all well and good, except when testing an installed @value{GDBN}

7700

that has been configured with @option{--with-system-gdbinit}. Here one

7701

does not want @file{~/.gdbinit} loaded but one may want the system

7702

@file{.gdbinit} file loaded. This can be achieved by pointing @code{$HOME}

7703

at a directory without a @file{.gdbinit} and by overriding

7704

@code{INTERNAL_GDBFLAGS} and removing @option{-nx}.

7705

7706

@smallexample

7707

cd testsuite

7708

HOME=`pwd` runtest \

7709

GDB=/usr/bin/gdb \

7710

GDBSERVER=/usr/bin/gdbserver \

7711

INTERNAL_GDBFLAGS=-nw

7712

@end smallexample

7713

7714

@end itemize

7715

7716

There are two ways to run the testsuite and pass additional parameters

7717

to DejaGnu. The first is with @kbd{make check} and specifying the

7718

makefile variable @samp{RUNTESTFLAGS}.

7719

7720

@smallexample

7721

make check RUNTESTFLAGS=TRANSCRIPT=y

7722

@end smallexample

7723

7724

The second is to cd to the @file{testsuite} directory and invoke the DejaGnu

7725

@command{runtest} command directly.

7726

7727

@smallexample

7728

cd testsuite

7729

make site.exp

7730

runtest TRANSCRIPT=y

7731

@end smallexample

7732

7733

@section Testsuite Configuration

7734

@cindex Testsuite Configuration

7735

7736

It is possible to adjust the behavior of the testsuite by defining

7737

the global variables listed below, either in a @file{site.exp} file,

7738

or in a board file.

7739

7740

@itemize @bullet

7741

7742

@item @code{gdb_test_timeout}

7743

7744

Defining this variable changes the default timeout duration used during

7745

communication with @value{GDBN}. More specifically, the global variable

7746

used during testing is @code{timeout}, but this variable gets reset to

7747

@code{gdb_test_timeout} at the beginning of each testcase, making sure

7748

that any local change to @code{timeout} in a testcase does not affect

7749

subsequent testcases.

7750

7751

This global variable comes in handy when the debugger is slower than

7752

normal due to the testing environment, triggering unexpected @code{TIMEOUT}

7753

test failures. Examples include when testing on a remote machine, or

7754

against a system where communications are slow.

7755

7756

If not specifically defined, this variable gets automatically defined

7757

to the same value as @code{timeout} during the testsuite initialization.

7758

The default value of the timeout is defined in the file

7759

@file{gdb/testsuite/config/unix.exp} that is part of the @value{GDBN}

7760

test suite@footnote{If you are using a board file, it could override

7761

the test-suite default; search the board file for "timeout".}.

7762

7763

@end itemize

7764

7765

@section Testsuite Organization

7766

7767

@cindex test suite organization

7768

The testsuite is entirely contained in @file{gdb/testsuite}. While the

7769

testsuite includes some makefiles and configury, these are very minimal,

7770

and used for little besides cleaning up, since the tests themselves

7771

handle the compilation of the programs that @value{GDBN} will run. The file

7772

@file{testsuite/lib/gdb.exp} contains common utility procs useful for

7773

all @value{GDBN} tests, while the directory @file{testsuite/config} contains

7774

configuration-specific files, typically used for special-purpose

7775

definitions of procs like @code{gdb_load} and @code{gdb_start}.

7776

7777

The tests themselves are to be found in @file{testsuite/gdb.*} and

7778

subdirectories of those. The names of the test files must always end

7779

with @file{.exp}. DejaGNU collects the test files by wildcarding

7780

in the test directories, so both subdirectories and individual files

7781

get chosen and run in alphabetical order.

7782

7783

The following table lists the main types of subdirectories and what they

7784

are for. Since DejaGNU finds test files no matter where they are

7785

located, and since each test file sets up its own compilation and

7786

execution environment, this organization is simply for convenience and

7787

intelligibility.

7788

7789

@table @file

7790

@item gdb.base

7791

This is the base testsuite. The tests in it should apply to all

7792

configurations of @value{GDBN} (but generic native-only tests may live here).

7793

The test programs should be in the subset of C that is valid K&R,

7794

ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance

7795

for prototypes).

7796

7797

@item gdb.@var{lang}

7798

Language-specific tests for any language @var{lang} besides C. Examples are

7799

@file{gdb.cp} and @file{gdb.java}.

7800

7801

@item gdb.@var{platform}

7802

Non-portable tests. The tests are specific to a specific configuration

7803

(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for

7804

HP-UX.

7805

7806

@item gdb.@var{compiler}

7807

Tests specific to a particular compiler. As of this writing (June

7808

1999), there aren't currently any groups of tests in this category that

7809

couldn't just as sensibly be made platform-specific, but one could

7810

imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC

7811

extensions.

7812

7813

@item gdb.@var{subsystem}

7814

Tests that exercise a specific @value{GDBN} subsystem in more depth. For

7815

instance, @file{gdb.disasm} exercises various disassemblers, while

7816

@file{gdb.stabs} tests pathways through the stabs symbol reader.

7817

@end table

7818

7819

@section Writing Tests

7820

@cindex writing tests

7821

7822

In many areas, the @value{GDBN} tests are already quite comprehensive; you

7823

should be able to copy existing tests to handle new cases.

7824

7825

You should try to use @code{gdb_test} whenever possible, since it

7826

includes cases to handle all the unexpected errors that might happen.

7827

However, it doesn't cost anything to add new test procedures; for

7828

instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that

7829

calls @code{gdb_test} multiple times.

7830

7831

Only use @code{send_gdb} and @code{gdb_expect} when absolutely

7832

necessary. Even if @value{GDBN} has several valid responses to

7833

a command, you can use @code{gdb_test_multiple}. Like @code{gdb_test},

7834

@code{gdb_test_multiple} recognizes internal errors and unexpected

7835

prompts.

7836

7837

Do not write tests which expect a literal tab character from @value{GDBN}.

7838

On some operating systems (e.g.@: OpenBSD) the TTY layer expands tabs to

7839

spaces, so by the time @value{GDBN}'s output reaches expect the tab is gone.

7840

7841

The source language programs do @emph{not} need to be in a consistent

7842

style. Since @value{GDBN} is used to debug programs written in many different

7843

styles, it's worth having a mix of styles in the testsuite; for

7844

instance, some @value{GDBN} bugs involving the display of source lines would

7845

never manifest themselves if the programs used GNU coding style

7846

uniformly.

7847

7848

@node Hints

7849

7850

@chapter Hints

7851

7852

Check the @file{README} file, it often has useful information that does not

7853

appear anywhere else in the directory.

7854

7855

@menu

7856

* Getting Started:: Getting started working on @value{GDBN}

7857

* Debugging GDB:: Debugging @value{GDBN} with itself

7858

@end menu

7859

7860

@node Getting Started

7861

7862

@section Getting Started

7863

7864

@value{GDBN} is a large and complicated program, and if you first starting to

7865

work on it, it can be hard to know where to start. Fortunately, if you

7866

know how to go about it, there are ways to figure out what is going on.

7867

7868

This manual, the @value{GDBN} Internals manual, has information which applies

7869

generally to many parts of @value{GDBN}.

7870

7871

Information about particular functions or data structures are located in

7872

comments with those functions or data structures. If you run across a

7873

function or a global variable which does not have a comment correctly

7874

explaining what is does, this can be thought of as a bug in @value{GDBN}; feel

7875

free to submit a bug report, with a suggested comment if you can figure

7876

out what the comment should say. If you find a comment which is

7877

actually wrong, be especially sure to report that.

7878

7879

Comments explaining the function of macros defined in host, target, or

7880

native dependent files can be in several places. Sometimes they are

7881

repeated every place the macro is defined. Sometimes they are where the

7882

macro is used. Sometimes there is a header file which supplies a

7883

default definition of the macro, and the comment is there. This manual

7884

also documents all the available macros.

7885

@c (@pxref{Host Conditionals}, @pxref{Target

7886

@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete

7887

@c Conditionals})

7888

7889

Start with the header files. Once you have some idea of how

7890

@value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},

7891

@file{gdbtypes.h}), you will find it much easier to understand the

7892

code which uses and creates those symbol tables.

7893

7894

You may wish to process the information you are getting somehow, to

7895

enhance your understanding of it. Summarize it, translate it to another

7896

language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use

7897

the code to predict what a test case would do and write the test case

7898

and verify your prediction, etc. If you are reading code and your eyes

7899

are starting to glaze over, this is a sign you need to use a more active

7900

approach.

7901

7902

Once you have a part of @value{GDBN} to start with, you can find more

7903

specifically the part you are looking for by stepping through each

7904

function with the @code{next} command. Do not use @code{step} or you

7905

will quickly get distracted; when the function you are stepping through

7906

calls another function try only to get a big-picture understanding

7907

(perhaps using the comment at the beginning of the function being

7908

called) of what it does. This way you can identify which of the

7909

functions being called by the function you are stepping through is the

7910

one which you are interested in. You may need to examine the data

7911

structures generated at each stage, with reference to the comments in

7912

the header files explaining what the data structures are supposed to

7913

look like.

7914

7915

Of course, this same technique can be used if you are just reading the

7916

code, rather than actually stepping through it. The same general

7917

principle applies---when the code you are looking at calls something

7918

else, just try to understand generally what the code being called does,

7919

rather than worrying about all its details.

7920

7921

@cindex command implementation

7922

A good place to start when tracking down some particular area is with

7923

a command which invokes that feature. Suppose you want to know how

7924

single-stepping works. As a @value{GDBN} user, you know that the

7925

@code{step} command invokes single-stepping. The command is invoked

7926

via command tables (see @file{command.h}); by convention the function

7927

which actually performs the command is formed by taking the name of

7928

the command and adding @samp{_command}, or in the case of an

7929

@code{info} subcommand, @samp{_info}. For example, the @code{step}

7930

command invokes the @code{step_command} function and the @code{info

7931

display} command invokes @code{display_info}. When this convention is

7932

not followed, you might have to use @code{grep} or @kbd{M-x

7933

tags-search} in emacs, or run @value{GDBN} on itself and set a

7934

breakpoint in @code{execute_command}.

7935

7936

@cindex @code{bug-gdb} mailing list

7937

If all of the above fail, it may be appropriate to ask for information

7938

on @code{bug-gdb}. But @emph{never} post a generic question like ``I was

7939

wondering if anyone could give me some tips about understanding

7940

@value{GDBN}''---if we had some magic secret we would put it in this manual.

7941

Suggestions for improving the manual are always welcome, of course.

7942

7943

@node Debugging GDB

7944

7945

@section Debugging @value{GDBN} with itself

7946

@cindex debugging @value{GDBN}

7947

7948

If @value{GDBN} is limping on your machine, this is the preferred way to get it

7949

fully functional. Be warned that in some ancient Unix systems, like

7950

Ultrix 4.2, a program can't be running in one process while it is being

7951

debugged in another. Rather than typing the command @kbd{@w{./gdb

7952

./gdb}}, which works on Suns and such, you can copy @file{gdb} to

7953

@file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.

7954

7955

When you run @value{GDBN} in the @value{GDBN} source directory, it will read a

7956

@file{.gdbinit} file that sets up some simple things to make debugging

7957

gdb easier. The @code{info} command, when executed without a subcommand

7958

in a @value{GDBN} being debugged by gdb, will pop you back up to the top level

7959

gdb. See @file{.gdbinit} for details.

7960

7961

If you use emacs, you will probably want to do a @code{make TAGS} after

7962

you configure your distribution; this will put the machine dependent

7963

routines for your local machine where they will be accessed first by

7964

@kbd{M-.}

7965

7966

Also, make sure that you've either compiled @value{GDBN} with your local cc, or

7967

have run @code{fixincludes} if you are compiling with gcc.

7968

7969

@section Submitting Patches

7970

7971

@cindex submitting patches

7972

Thanks for thinking of offering your changes back to the community of

7973

@value{GDBN} users. In general we like to get well designed enhancements.

7974

Thanks also for checking in advance about the best way to transfer the

7975

changes.

7976

7977

The @value{GDBN} maintainers will only install ``cleanly designed'' patches.

7978

This manual summarizes what we believe to be clean design for @value{GDBN}.

7979

7980

If the maintainers don't have time to put the patch in when it arrives,

7981

or if there is any question about a patch, it goes into a large queue

7982

with everyone else's patches and bug reports.

7983

7984

@cindex legal papers for code contributions

7985

The legal issue is that to incorporate substantial changes requires a

7986

copyright assignment from you and/or your employer, granting ownership

7987

of the changes to the Free Software Foundation. You can get the

7988

standard documents for doing this by sending mail to @code{gnu@@gnu.org}

7989

and asking for it. We recommend that people write in "All programs

7990

owned by the Free Software Foundation" as "NAME OF PROGRAM", so that

7991

changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,

7992

etc) can be

7993

contributed with only one piece of legalese pushed through the

7994

bureaucracy and filed with the FSF. We can't start merging changes until

7995

this paperwork is received by the FSF (their rules, which we follow

7996

since we maintain it for them).

7997

7998

Technically, the easiest way to receive changes is to receive each

7999

feature as a small context diff or unidiff, suitable for @code{patch}.

8000

Each message sent to me should include the changes to C code and

8001

header files for a single feature, plus @file{ChangeLog} entries for

8002

each directory where files were modified, and diffs for any changes

8003

needed to the manuals (@file{gdb/doc/gdb.texinfo} or

8004

@file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a

8005

single feature, they can be split down into multiple messages.

8006

8007

In this way, if we read and like the feature, we can add it to the

8008

sources with a single patch command, do some testing, and check it in.

8009

If you leave out the @file{ChangeLog}, we have to write one. If you leave

8010

out the doc, we have to puzzle out what needs documenting. Etc., etc.

8011

8012

The reason to send each change in a separate message is that we will not

8013

install some of the changes. They'll be returned to you with questions

8014

or comments. If we're doing our job correctly, the message back to you

8015

will say what you have to fix in order to make the change acceptable.

8016

The reason to have separate messages for separate features is so that

8017

the acceptable changes can be installed while one or more changes are

8018

being reworked. If multiple features are sent in a single message, we

8019

tend to not put in the effort to sort out the acceptable changes from

8020

the unacceptable, so none of the features get installed until all are

8021

acceptable.

8022

8023

If this sounds painful or authoritarian, well, it is. But we get a lot

8024

of bug reports and a lot of patches, and many of them don't get

8025

installed because we don't have the time to finish the job that the bug

8026

reporter or the contributor could have done. Patches that arrive

8027

complete, working, and well designed, tend to get installed on the day

8028

they arrive. The others go into a queue and get installed as time

8029

permits, which, since the maintainers have many demands to meet, may not

8030

be for quite some time.

8031

8032

Please send patches directly to

8033

@email{gdb-patches@@sourceware.org, the @value{GDBN} maintainers}.

8034

8035

@section Build Script

8036

8037

@cindex build script

8038

8039

The script @file{gdb_buildall.sh} builds @value{GDBN} with flag

8040

@option{--enable-targets=all} set. This builds @value{GDBN} with all supported

8041

targets activated. This helps testing @value{GDBN} when doing changes that

8042

affect more than one architecture and is much faster than using

8043

@file{gdb_mbuild.sh}.

8044

8045

After building @value{GDBN} the script checks which architectures are

8046

supported and then switches the current architecture to each of those to get

8047

information about the architecture. The test results are stored in log files

8048

in the directory the script was called from.

8049

8050

@include observer.texi

8051

8052

@node GNU Free Documentation License

8053

@appendix GNU Free Documentation License

8054

@include fdl.texi

8055

8056

@node Index

8057

@unnumbered Index

8058

8059

@printindex cp

8060

8061

@bye

1