Eric Lee / linux-smarc-t335x-v3.2

1

#!/usr/bin/perl -w

1

#!/usr/bin/perl -w

2

3

use strict;

3

use strict;

4

5

6

7

8

## ##

8

## ##

9

## #define enhancements by Armin Kuster <akuster@mvista.com> ##

9

## #define enhancements by Armin Kuster <akuster@mvista.com> ##

10

11

## ##

11

## ##

12

## This software falls under the GNU General Public License. ##

12

## This software falls under the GNU General Public License. ##

13

## Please read the COPYING file for more information ##

13

## Please read the COPYING file for more information ##

14

15

# w.o. 03-11-2000: added the '-filelist' option.

15

# w.o. 03-11-2000: added the '-filelist' option.

16

17

# 18/01/2001 - Cleanups

17

# 18/01/2001 - Cleanups

18

# Functions prototyped as foo(void) same as foo()

18

# Functions prototyped as foo(void) same as foo()

19

# Stop eval'ing where we don't need to.

19

# Stop eval'ing where we don't need to.

20

# -- huggie@earth.li

20

# -- huggie@earth.li

21

22

# 27/06/2001 - Allowed whitespace after initial "/**" and

22

# 27/06/2001 - Allowed whitespace after initial "/**" and

23

# allowed comments before function declarations.

23

# allowed comments before function declarations.

24

# -- Christian Kreibich <ck@whoop.org>

24

# -- Christian Kreibich <ck@whoop.org>

25

26

# Still to do:

26

# Still to do:

27

# - add perldoc documentation

27

# - add perldoc documentation

28

# - Look more closely at some of the scarier bits :)

28

# - Look more closely at some of the scarier bits :)

29

30

# 26/05/2001 - Support for separate source and object trees.

30

# 26/05/2001 - Support for separate source and object trees.

31

# Return error code.

31

# Return error code.

32

# Keith Owens <kaos@ocs.com.au>

32

# Keith Owens <kaos@ocs.com.au>

33

34

# 23/09/2001 - Added support for typedefs, structs, enums and unions

34

# 23/09/2001 - Added support for typedefs, structs, enums and unions

35

# Support for Context section; can be terminated using empty line

35

# Support for Context section; can be terminated using empty line

36

# Small fixes (like spaces vs. \s in regex)

36

# Small fixes (like spaces vs. \s in regex)

37

# -- Tim Jansen <tim@tjansen.de>

37

# -- Tim Jansen <tim@tjansen.de>

38

39

40

#

40

#

41

# This will read a 'c' file and scan for embedded comments in the

41

# This will read a 'c' file and scan for embedded comments in the

42

# style of gnome comments (+minor extensions - see below).

42

# style of gnome comments (+minor extensions - see below).

43

#

43

#

44

45

# Note: This only supports 'c'.

45

# Note: This only supports 'c'.

46

47

# usage:

47

# usage:

48

# kernel-doc [ -docbook | -html | -text | -man ]

48

# kernel-doc [ -docbook | -html | -text | -man ]

49

# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile

49

# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile

50

# or

50

# or

51

# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile

51

# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile

52

#

52

#

53

# Set output format using one of -docbook -html -text or -man. Default is man.

53

# Set output format using one of -docbook -html -text or -man. Default is man.

54

#

54

#

55

# -function funcname

55

# -function funcname

56

# If set, then only generate documentation for the given function(s). All

56

# If set, then only generate documentation for the given function(s). All

57

# other functions are ignored.

57

# other functions are ignored.

58

#

58

#

59

# -nofunction funcname

59

# -nofunction funcname

60

# If set, then only generate documentation for the other function(s).

60

# If set, then only generate documentation for the other function(s).

61

# Cannot be used together with -function

61

# Cannot be used together with -function

62

# (yes, that's a bug -- perl hackers can fix it 8))

62

# (yes, that's a bug -- perl hackers can fix it 8))

63

#

63

#

64

# c files - list of 'c' files to process

64

# c files - list of 'c' files to process

65

#

65

#

66

# All output goes to stdout, with errors to stderr.

66

# All output goes to stdout, with errors to stderr.

67

68

#

68

#

69

# format of comments.

69

# format of comments.

70

# In the following table, (...)? signifies optional structure.

70

# In the following table, (...)? signifies optional structure.

71

# (...)* signifies 0 or more structure elements

71

# (...)* signifies 0 or more structure elements

72

# /**

72

# /**

73

# * function_name(:)? (- short description)?

73

# * function_name(:)? (- short description)?

74

# (* @parameterx: (description of parameter x)?)*

74

# (* @parameterx: (description of parameter x)?)*

75

# (* a blank line)?

75

# (* a blank line)?

76

# * (Description:)? (Description of function)?

76

# * (Description:)? (Description of function)?

77

# * (section header: (section description)? )*

77

# * (section header: (section description)? )*

78

# (*)?*/

78

# (*)?*/

79

#

79

#

80

# So .. the trivial example would be:

80

# So .. the trivial example would be:

81

#

81

#

82

# /**

82

# /**

83

# * my_function

83

# * my_function

84

# **/

84

# **/

85

#

85

#

86

# If the Description: header tag is omitted, then there must be a blank line

86

# If the Description: header tag is omitted, then there must be a blank line

87

# after the last parameter specification.

87

# after the last parameter specification.

88

# e.g.

88

# e.g.

89

# /**

89

# /**

90

# * my_function - does my stuff

90

# * my_function - does my stuff

91

# * @my_arg: its mine damnit

91

# * @my_arg: its mine damnit

92

# *

92

# *

93

# * Does my stuff explained.

93

# * Does my stuff explained.

94

# */

94

# */

95

#

95

#

96

# or, could also use:

96

# or, could also use:

97

# /**

97

# /**

98

# * my_function - does my stuff

98

# * my_function - does my stuff

99

# * @my_arg: its mine damnit

99

# * @my_arg: its mine damnit

100

# * Description: Does my stuff explained.

100

# * Description: Does my stuff explained.

101

# */

101

# */

102

# etc.

102

# etc.

103

#

103

#

104

# Beside functions you can also write documentation for structs, unions,

104

# Beside functions you can also write documentation for structs, unions,

105

# enums and typedefs. Instead of the function name you must write the name

105

# enums and typedefs. Instead of the function name you must write the name

106

# of the declaration; the struct/union/enum/typedef must always precede

106

# of the declaration; the struct/union/enum/typedef must always precede

107

# the name. Nesting of declarations is not supported.

107

# the name. Nesting of declarations is not supported.

108

# Use the argument mechanism to document members or constants.

108

# Use the argument mechanism to document members or constants.

109

# e.g.

109

# e.g.

110

# /**

110

# /**

111

# * struct my_struct - short description

111

# * struct my_struct - short description

112

# * @a: first member

112

# * @a: first member

113

# * @b: second member

113

# * @b: second member

114

# *

114

# *

115

# * Longer description

115

# * Longer description

116

# */

116

# */

117

# struct my_struct {

117

# struct my_struct {

118

# int a;

118

# int a;

119

# int b;

119

# int b;

120

# /* private: */

120

# /* private: */

121

# int c;

121

# int c;

122

# };

122

# };

123

#

123

#

124

# All descriptions can be multiline, except the short function description.

124

# All descriptions can be multiline, except the short function description.

125

#

125

#

126

# You can also add additional sections. When documenting kernel functions you

126

# You can also add additional sections. When documenting kernel functions you

127

# should document the "Context:" of the function, e.g. whether the functions

127

# should document the "Context:" of the function, e.g. whether the functions

128

# can be called form interrupts. Unlike other sections you can end it with an

128

# can be called form interrupts. Unlike other sections you can end it with an

129

# empty line.

129

# empty line.

130

# Example-sections should contain the string EXAMPLE so that they are marked

130

# Example-sections should contain the string EXAMPLE so that they are marked

131

# appropriately in DocBook.

131

# appropriately in DocBook.

132

#

132

#

133

# Example:

133

# Example:

134

# /**

134

# /**

135

# * user_function - function that can only be called in user context

135

# * user_function - function that can only be called in user context

136

# * @a: some argument

136

# * @a: some argument

137

# * Context: !in_interrupt()

137

# * Context: !in_interrupt()

138

# *

138

# *

139

# * Some description

139

# * Some description

140

# * Example:

140

# * Example:

141

# * user_function(22);

141

# * user_function(22);

142

# */

142

# */

143

# ...

143

# ...

144

#

144

#

145

#

145

#

146

# All descriptive text is further processed, scanning for the following special

146

# All descriptive text is further processed, scanning for the following special

147

# patterns, which are highlighted appropriately.

147

# patterns, which are highlighted appropriately.

148

#

148

#

149

# 'funcname()' - function

149

# 'funcname()' - function

150

# '$ENVVAR' - environmental variable

150

# '$ENVVAR' - environmental variable

151

# '&struct_name' - name of a structure (up to two words including 'struct')

151

# '&struct_name' - name of a structure (up to two words including 'struct')

152

# '@parameter' - name of a parameter

152

# '@parameter' - name of a parameter

153

# '%CONST' - name of a constant.

153

# '%CONST' - name of a constant.

154

155

my $errors = 0;

155

my $errors = 0;

156

my $warnings = 0;

156

my $warnings = 0;

157

my $anon_struct_union = 0;

157

my $anon_struct_union = 0;

158

159

# match expressions used to find embedded type information

159

# match expressions used to find embedded type information

160

my $type_constant = '\%([-_\w]+)';

160

my $type_constant = '\%([-_\w]+)';

161

my $type_func = '(\w+)';

161

my $type_func = '(\w+)';

162

my $type_param = '\@(\w+)';

162

my $type_param = '\@(\w+)';

163

my $type_struct = '\&((struct\s*)*[_\w]+)';

163

my $type_struct = '\&((struct\s*)*[_\w]+)';

164

my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';

164

my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';

165

my $type_env = '(\$\w+)';

165

my $type_env = '(\$\w+)';

166

167

# Output conversion substitutions.

167

# Output conversion substitutions.

168

# One for each output format

168

# One for each output format

169

170

# these work fairly well

170

# these work fairly well

171

my %highlights_html = ( $type_constant, "<i>\$1</i>",

171

my %highlights_html = ( $type_constant, "<i>\$1</i>",

172

$type_func, "<b>\$1</b>",

172

$type_func, "<b>\$1</b>",

173

$type_struct_xml, "<i>\$1</i>",

173

$type_struct_xml, "<i>\$1</i>",

174

$type_env, "<b><i>\$1</i></b>",

174

$type_env, "<b><i>\$1</i></b>",

175

$type_param, "<tt><b>\$1</b></tt>" );

175

$type_param, "<tt><b>\$1</b></tt>" );

176

my $blankline_html = "<p>";

176

my $blankline_html = "<p>";

177

178

# XML, docbook format

178

# XML, docbook format

179

my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",

179

my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",

180

$type_constant, "<constant>\$1</constant>",

180

$type_constant, "<constant>\$1</constant>",

181

$type_func, "<function>\$1</function>",

181

$type_func, "<function>\$1</function>",

182

$type_struct, "<structname>\$1</structname>",

182

$type_struct, "<structname>\$1</structname>",

183

$type_env, "<envar>\$1</envar>",

183

$type_env, "<envar>\$1</envar>",

184

$type_param, "<parameter>\$1</parameter>" );

184

$type_param, "<parameter>\$1</parameter>" );

185

my $blankline_xml = "</para><para>\n";

185

my $blankline_xml = "</para><para>\n";

186

187

# gnome, docbook format

187

# gnome, docbook format

188

my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",

188

my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",

189

$type_func, "<function>\$1</function>",

189

$type_func, "<function>\$1</function>",

190

$type_struct, "<structname>\$1</structname>",

190

$type_struct, "<structname>\$1</structname>",

191

$type_env, "<envar>\$1</envar>",

191

$type_env, "<envar>\$1</envar>",

192

$type_param, "<parameter>\$1</parameter>" );

192

$type_param, "<parameter>\$1</parameter>" );

193

my $blankline_gnome = "</para><para>\n";

193

my $blankline_gnome = "</para><para>\n";

194

195

# these are pretty rough

195

# these are pretty rough

196

my %highlights_man = ( $type_constant, "\$1",

196

my %highlights_man = ( $type_constant, "\$1",

197

$type_func, "\\\\fB\$1\\\\fP",

197

$type_func, "\\\\fB\$1\\\\fP",

198

$type_struct, "\\\\fI\$1\\\\fP",

198

$type_struct, "\\\\fI\$1\\\\fP",

199

$type_param, "\\\\fI\$1\\\\fP" );

199

$type_param, "\\\\fI\$1\\\\fP" );

200

my $blankline_man = "";

200

my $blankline_man = "";

201

202

# text-mode

202

# text-mode

203

my %highlights_text = ( $type_constant, "\$1",

203

my %highlights_text = ( $type_constant, "\$1",

204

$type_func, "\$1",

204

$type_func, "\$1",

205

$type_struct, "\$1",

205

$type_struct, "\$1",

206

$type_param, "\$1" );

206

$type_param, "\$1" );

207

my $blankline_text = "";

207

my $blankline_text = "";

208

209

210

sub usage {

210

sub usage {

211

print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";

211

print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";

212

print " [ -function funcname [ -function funcname ...] ]\n";

212

print " [ -function funcname [ -function funcname ...] ]\n";

213

print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";

213

print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";

214

print " c source file(s) > outputfile\n";

214

print " c source file(s) > outputfile\n";

215

exit 1;

215

exit 1;

216

}

216

}

217

218

# read arguments

218

# read arguments

219

if ($#ARGV==-1) {

219

if ($#ARGV==-1) {

220

usage();

220

usage();

221

}

221

}

222

223

my $verbose = 0;

223

my $verbose = 0;

224

my $output_mode = "man";

224

my $output_mode = "man";

225

my %highlights = %highlights_man;

225

my %highlights = %highlights_man;

226

my $blankline = $blankline_man;

226

my $blankline = $blankline_man;

227

my $modulename = "Kernel API";

227

my $modulename = "Kernel API";

228

my $function_only = 0;

228

my $function_only = 0;

229

my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',

229

my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',

230

'July', 'August', 'September', 'October',

230

'July', 'August', 'September', 'October',

231

'November', 'December')[(localtime)[4]] .

231

'November', 'December')[(localtime)[4]] .

232

" " . ((localtime)[5]+1900);

232

" " . ((localtime)[5]+1900);

233

234

# Essentially these are globals

234

# Essentially these are globals

235

# They probably want to be tidied up made more localised or summat.

235

# They probably want to be tidied up made more localised or summat.

236

# CAVEAT EMPTOR! Some of the others I localised may not want to be which

236

# CAVEAT EMPTOR! Some of the others I localised may not want to be which

237

# could cause "use of undefined value" or other bugs.

237

# could cause "use of undefined value" or other bugs.

238

my ($function, %function_table,%parametertypes,$declaration_purpose);

238

my ($function, %function_table,%parametertypes,$declaration_purpose);

239

my ($type,$declaration_name,$return_type);

239

my ($type,$declaration_name,$return_type);

240

my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);

240

my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);

241

242

# Generated docbook code is inserted in a template at a point where

242

# Generated docbook code is inserted in a template at a point where

243

# docbook v3.1 requires a non-zero sequence of RefEntry's; see:

243

# docbook v3.1 requires a non-zero sequence of RefEntry's; see:

244

# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html

244

# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html

245

# We keep track of number of generated entries and generate a dummy

245

# We keep track of number of generated entries and generate a dummy

246

# if needs be to ensure the expanded template can be postprocessed

246

# if needs be to ensure the expanded template can be postprocessed

247

# into html.

247

# into html.

248

my $section_counter = 0;

248

my $section_counter = 0;

249

250

my $lineprefix="";

250

my $lineprefix="";

251

252

# states

252

# states

253

# 0 - normal code

253

# 0 - normal code

254

# 1 - looking for function name

254

# 1 - looking for function name

255

# 2 - scanning field start.

255

# 2 - scanning field start.

256

# 3 - scanning prototype.

256

# 3 - scanning prototype.

257

# 4 - documentation block

257

# 4 - documentation block

258

my $state;

258

my $state;

259

my $in_doc_sect;

259

my $in_doc_sect;

260

261

#declaration types: can be

261

#declaration types: can be

262

# 'function', 'struct', 'union', 'enum', 'typedef'

262

# 'function', 'struct', 'union', 'enum', 'typedef'

263

my $decl_type;

263

my $decl_type;

264

265

my $doc_special = "\@\%\$\&";

265

my $doc_special = "\@\%\$\&";

266

267

my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.

267

my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.

268

my $doc_end = '\*/';

268

my $doc_end = '\*/';

269

my $doc_com = '\s*\*\s*';

269

my $doc_com = '\s*\*\s*';

270

my $doc_decl = $doc_com.'(\w+)';

270

my $doc_decl = $doc_com.'(\w+)';

271

my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';

271

my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';

272

my $doc_content = $doc_com.'(.*)';

272

my $doc_content = $doc_com.'(.*)';

273

my $doc_block = $doc_com.'DOC:\s*(.*)?';

273

my $doc_block = $doc_com.'DOC:\s*(.*)?';

274

275

my %constants;

275

my %constants;

276

my %parameterdescs;

276

my %parameterdescs;

277

my @parameterlist;

277

my @parameterlist;

278

my %sections;

278

my %sections;

279

my @sectionlist;

279

my @sectionlist;

280

281

my $contents = "";

281

my $contents = "";

282

my $section_default = "Description"; # default section

282

my $section_default = "Description"; # default section

283

my $section_intro = "Introduction";

283

my $section_intro = "Introduction";

284

my $section = $section_default;

284

my $section = $section_default;

285

my $section_context = "Context";

285

my $section_context = "Context";

286

287

my $undescribed = "-- undescribed --";

287

my $undescribed = "-- undescribed --";

288

289

reset_state();

289

reset_state();

290

291

while ($ARGV[0] =~ m/^-(.*)/) {

291

while ($ARGV[0] =~ m/^-(.*)/) {

292

my $cmd = shift @ARGV;

292

my $cmd = shift @ARGV;

293

if ($cmd eq "-html") {

293

if ($cmd eq "-html") {

294

$output_mode = "html";

294

$output_mode = "html";

295

%highlights = %highlights_html;

295

%highlights = %highlights_html;

296

$blankline = $blankline_html;

296

$blankline = $blankline_html;

297

} elsif ($cmd eq "-man") {

297

} elsif ($cmd eq "-man") {

298

$output_mode = "man";

298

$output_mode = "man";

299

%highlights = %highlights_man;

299

%highlights = %highlights_man;

300

$blankline = $blankline_man;

300

$blankline = $blankline_man;

301

} elsif ($cmd eq "-text") {

301

} elsif ($cmd eq "-text") {

302

$output_mode = "text";

302

$output_mode = "text";

303

%highlights = %highlights_text;

303

%highlights = %highlights_text;

304

$blankline = $blankline_text;

304

$blankline = $blankline_text;

305

} elsif ($cmd eq "-docbook") {

305

} elsif ($cmd eq "-docbook") {

306

$output_mode = "xml";

306

$output_mode = "xml";

307

%highlights = %highlights_xml;

307

%highlights = %highlights_xml;

308

$blankline = $blankline_xml;

308

$blankline = $blankline_xml;

309

} elsif ($cmd eq "-gnome") {

309

} elsif ($cmd eq "-gnome") {

310

$output_mode = "gnome";

310

$output_mode = "gnome";

311

%highlights = %highlights_gnome;

311

%highlights = %highlights_gnome;

312

$blankline = $blankline_gnome;

312

$blankline = $blankline_gnome;

313

} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document

313

} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document

314

$modulename = shift @ARGV;

314

$modulename = shift @ARGV;

315

} elsif ($cmd eq "-function") { # to only output specific functions

315

} elsif ($cmd eq "-function") { # to only output specific functions

316

$function_only = 1;

316

$function_only = 1;

317

$function = shift @ARGV;

317

$function = shift @ARGV;

318

$function_table{$function} = 1;

318

$function_table{$function} = 1;

319

} elsif ($cmd eq "-nofunction") { # to only output specific functions

319

} elsif ($cmd eq "-nofunction") { # to only output specific functions

320

$function_only = 2;

320

$function_only = 2;

321

$function = shift @ARGV;

321

$function = shift @ARGV;

322

$function_table{$function} = 1;

322

$function_table{$function} = 1;

323

} elsif ($cmd eq "-v") {

323

} elsif ($cmd eq "-v") {

324

$verbose = 1;

324

$verbose = 1;

325

} elsif (($cmd eq "-h") || ($cmd eq "--help")) {

325

} elsif (($cmd eq "-h") || ($cmd eq "--help")) {

326

usage();

326

usage();

327

} elsif ($cmd eq '-filelist') {

327

} elsif ($cmd eq '-filelist') {

328

$filelist = shift @ARGV;

328

$filelist = shift @ARGV;

329

}

329

}

330

}

330

}

331

332

# get kernel version from env

332

# get kernel version from env

333

sub get_kernel_version() {

333

sub get_kernel_version() {

334

my $version;

334

my $version;

335

336

if (defined($ENV{'KERNELVERSION'})) {

336

if (defined($ENV{'KERNELVERSION'})) {

337

$version = $ENV{'KERNELVERSION'};

337

$version = $ENV{'KERNELVERSION'};

338

}

338

}

339

return $version;

339

return $version;

340

}

340

}

341

my $kernelversion = get_kernel_version();

341

my $kernelversion = get_kernel_version();

342

343

# generate a sequence of code that will splice in highlighting information

343

# generate a sequence of code that will splice in highlighting information

344

# using the s// operator.

344

# using the s// operator.

345

my $dohighlight = "";

345

my $dohighlight = "";

346

foreach my $pattern (keys %highlights) {

346

foreach my $pattern (keys %highlights) {

347

# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";

347

# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";

348

$dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";

348

$dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";

349

}

349

}

350

351

##

351

##

352

# dumps section contents to arrays/hashes intended for that purpose.

352

# dumps section contents to arrays/hashes intended for that purpose.

353

#

353

#

354

sub dump_section {

354

sub dump_section {

355

my $name = shift;

355

my $name = shift;

356

my $contents = join "\n", @_;

356

my $contents = join "\n", @_;

357

358

if ($name =~ m/$type_constant/) {

358

if ($name =~ m/$type_constant/) {

359

$name = $1;

359

$name = $1;

360

# print STDERR "constant section '$1' = '$contents'\n";

360

# print STDERR "constant section '$1' = '$contents'\n";

361

$constants{$name} = $contents;

361

$constants{$name} = $contents;

362

} elsif ($name =~ m/$type_param/) {

362

} elsif ($name =~ m/$type_param/) {

363

# print STDERR "parameter def '$1' = '$contents'\n";

363

# print STDERR "parameter def '$1' = '$contents'\n";

364

$name = $1;

364

$name = $1;

365

$parameterdescs{$name} = $contents;

365

$parameterdescs{$name} = $contents;

366

} else {

366

} else {

367

# print STDERR "other section '$name' = '$contents'\n";

367

# print STDERR "other section '$name' = '$contents'\n";

368

$sections{$name} = $contents;

368

$sections{$name} = $contents;

369

push @sectionlist, $name;

369

push @sectionlist, $name;

370

}

370

}

371

}

371

}

372

373

##

373

##

374

# output function

374

# output function

375

#

375

#

376

# parameterdescs, a hash.

376

# parameterdescs, a hash.

377

# function => "function name"

377

# function => "function name"

378

# parameterlist => @list of parameters

378

# parameterlist => @list of parameters

379

# parameterdescs => %parameter descriptions

379

# parameterdescs => %parameter descriptions

380

# sectionlist => @list of sections

380

# sectionlist => @list of sections

381

# sections => %section descriptions

381

# sections => %section descriptions

382

#

382

#

383

384

sub output_highlight {

384

sub output_highlight {

385

my $contents = join "\n",@_;

385

my $contents = join "\n",@_;

386

my $line;

386

my $line;

387

388

# DEBUG

388

# DEBUG

389

# if (!defined $contents) {

389

# if (!defined $contents) {

390

# use Carp;

390

# use Carp;

391

# confess "output_highlight got called with no args?\n";

391

# confess "output_highlight got called with no args?\n";

392

# }

392

# }

393

394

# print STDERR "contents b4:$contents\n";

394

# print STDERR "contents b4:$contents\n";

395

eval $dohighlight;

395

eval $dohighlight;

396

die $@ if $@;

396

die $@ if $@;

397

if ($output_mode eq "html") {

397

if ($output_mode eq "html") {

398

$contents =~ s/\\\\//;

398

$contents =~ s/\\\\//;

399

}

399

}

400

# print STDERR "contents af:$contents\n";

400

# print STDERR "contents af:$contents\n";

401

402

foreach $line (split "\n", $contents) {

402

foreach $line (split "\n", $contents) {

403

if ($line eq ""){

403

if ($line eq ""){

404

print $lineprefix, $blankline;

404

print $lineprefix, $blankline;

405

} else {

405

} else {

406

$line =~ s/\\\\\\/\&/g;

406

$line =~ s/\\\\\\/\&/g;

407

print $lineprefix, $line;

407

if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {

408

print "\\&$line";

409

} else {

410

print $lineprefix, $line;

411

}

408

}

412

}

409

print "\n";

413

print "\n";

410

}

414

}

411

}

415

}

412

416

413

#output sections in html

417

#output sections in html

414

sub output_section_html(%) {

418

sub output_section_html(%) {

415

my %args = %{$_[0]};

419

my %args = %{$_[0]};

416

my $section;

420

my $section;

417

421

418

foreach $section (@{$args{'sectionlist'}}) {

422

foreach $section (@{$args{'sectionlist'}}) {

419

print "<h3>$section</h3>\n";

423

print "<h3>$section</h3>\n";

420

print "<blockquote>\n";

424

print "<blockquote>\n";

421

output_highlight($args{'sections'}{$section});

425

output_highlight($args{'sections'}{$section});

422

print "</blockquote>\n";

426

print "</blockquote>\n";

423

}

427

}

424

}

428

}

425

429

426

# output enum in html

430

# output enum in html

427

sub output_enum_html(%) {

431

sub output_enum_html(%) {

428

my %args = %{$_[0]};

432

my %args = %{$_[0]};

429

my ($parameter);

433

my ($parameter);

430

my $count;

434

my $count;

431

print "<h2>enum ".$args{'enum'}."</h2>\n";

435

print "<h2>enum ".$args{'enum'}."</h2>\n";

432

436

433

print "<b>enum ".$args{'enum'}."</b> {<br>\n";

437

print "<b>enum ".$args{'enum'}."</b> {<br>\n";

434

$count = 0;

438

$count = 0;

435

foreach $parameter (@{$args{'parameterlist'}}) {

439

foreach $parameter (@{$args{'parameterlist'}}) {

436

print " <b>".$parameter."</b>";

440

print " <b>".$parameter."</b>";

437

if ($count != $#{$args{'parameterlist'}}) {

441

if ($count != $#{$args{'parameterlist'}}) {

438

$count++;

442

$count++;

439

print ",\n";

443

print ",\n";

440

}

444

}

441

print "<br>";

445

print "<br>";

442

}

446

}

443

print "};<br>\n";

447

print "};<br>\n";

444

448

445

print "<h3>Constants</h3>\n";

449

print "<h3>Constants</h3>\n";

446

print "<dl>\n";

450

print "<dl>\n";

447

foreach $parameter (@{$args{'parameterlist'}}) {

451

foreach $parameter (@{$args{'parameterlist'}}) {

448

print "<dt><b>".$parameter."</b>\n";

452

print "<dt><b>".$parameter."</b>\n";

449

print "<dd>";

453

print "<dd>";

450

output_highlight($args{'parameterdescs'}{$parameter});

454

output_highlight($args{'parameterdescs'}{$parameter});

451

}

455

}

452

print "</dl>\n";

456

print "</dl>\n";

453

output_section_html(@_);

457

output_section_html(@_);

454

print "<hr>\n";

458

print "<hr>\n";

455

}

459

}

456

460

457

# output typedef in html

461

# output typedef in html

458

sub output_typedef_html(%) {

462

sub output_typedef_html(%) {

459

my %args = %{$_[0]};

463

my %args = %{$_[0]};

460

my ($parameter);

464

my ($parameter);

461

my $count;

465

my $count;

462

print "<h2>typedef ".$args{'typedef'}."</h2>\n";

466

print "<h2>typedef ".$args{'typedef'}."</h2>\n";

463

467

464

print "<b>typedef ".$args{'typedef'}."</b>\n";

468

print "<b>typedef ".$args{'typedef'}."</b>\n";

465

output_section_html(@_);

469

output_section_html(@_);

466

print "<hr>\n";

470

print "<hr>\n";

467

}

471

}

468

472

469

# output struct in html

473

# output struct in html

470

sub output_struct_html(%) {

474

sub output_struct_html(%) {

471

my %args = %{$_[0]};

475

my %args = %{$_[0]};

472

my ($parameter);

476

my ($parameter);

473

477

474

print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";

478

print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";

475

print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";

479

print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";

476

foreach $parameter (@{$args{'parameterlist'}}) {

480

foreach $parameter (@{$args{'parameterlist'}}) {

477

if ($parameter =~ /^#/) {

481

if ($parameter =~ /^#/) {

478

print "$parameter<br>\n";

482

print "$parameter<br>\n";

479

next;

483

next;

480

}

484

}

481

my $parameter_name = $parameter;

485

my $parameter_name = $parameter;

482

$parameter_name =~ s/\[.*//;

486

$parameter_name =~ s/\[.*//;

483

487

484

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

488

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

485

$type = $args{'parametertypes'}{$parameter};

489

$type = $args{'parametertypes'}{$parameter};

486

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

490

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

487

# pointer-to-function

491

# pointer-to-function

488

print "    <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";

492

print "    <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";

489

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

493

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

490

# bitfield

494

# bitfield

491

print "    <i>$1</i> <b>$parameter</b>$2;<br>\n";

495

print "    <i>$1</i> <b>$parameter</b>$2;<br>\n";

492

} else {

496

} else {

493

print "    <i>$type</i> <b>$parameter</b>;<br>\n";

497

print "    <i>$type</i> <b>$parameter</b>;<br>\n";

494

}

498

}

495

}

499

}

496

print "};<br>\n";

500

print "};<br>\n";

497

501

498

print "<h3>Members</h3>\n";

502

print "<h3>Members</h3>\n";

499

print "<dl>\n";

503

print "<dl>\n";

500

foreach $parameter (@{$args{'parameterlist'}}) {

504

foreach $parameter (@{$args{'parameterlist'}}) {

501

($parameter =~ /^#/) && next;

505

($parameter =~ /^#/) && next;

502

506

503

my $parameter_name = $parameter;

507

my $parameter_name = $parameter;

504

$parameter_name =~ s/\[.*//;

508

$parameter_name =~ s/\[.*//;

505

509

506

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

510

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

507

print "<dt><b>".$parameter."</b>\n";

511

print "<dt><b>".$parameter."</b>\n";

508

print "<dd>";

512

print "<dd>";

509

output_highlight($args{'parameterdescs'}{$parameter_name});

513

output_highlight($args{'parameterdescs'}{$parameter_name});

510

}

514

}

511

print "</dl>\n";

515

print "</dl>\n";

512

output_section_html(@_);

516

output_section_html(@_);

513

print "<hr>\n";

517

print "<hr>\n";

514

}

518

}

515

519

516

# output function in html

520

# output function in html

517

sub output_function_html(%) {

521

sub output_function_html(%) {

518

my %args = %{$_[0]};

522

my %args = %{$_[0]};

519

my ($parameter, $section);

523

my ($parameter, $section);

520

my $count;

524

my $count;

521

525

522

print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";

526

print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";

523

print "<i>".$args{'functiontype'}."</i>\n";

527

print "<i>".$args{'functiontype'}."</i>\n";

524

print "<b>".$args{'function'}."</b>\n";

528

print "<b>".$args{'function'}."</b>\n";

525

print "(";

529

print "(";

526

$count = 0;

530

$count = 0;

527

foreach $parameter (@{$args{'parameterlist'}}) {

531

foreach $parameter (@{$args{'parameterlist'}}) {

528

$type = $args{'parametertypes'}{$parameter};

532

$type = $args{'parametertypes'}{$parameter};

529

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

533

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

530

# pointer-to-function

534

# pointer-to-function

531

print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";

535

print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";

532

} else {

536

} else {

533

print "<i>".$type."</i> <b>".$parameter."</b>";

537

print "<i>".$type."</i> <b>".$parameter."</b>";

534

}

538

}

535

if ($count != $#{$args{'parameterlist'}}) {

539

if ($count != $#{$args{'parameterlist'}}) {

536

$count++;

540

$count++;

537

print ",\n";

541

print ",\n";

538

}

542

}

539

}

543

}

540

print ")\n";

544

print ")\n";

541

545

542

print "<h3>Arguments</h3>\n";

546

print "<h3>Arguments</h3>\n";

543

print "<dl>\n";

547

print "<dl>\n";

544

foreach $parameter (@{$args{'parameterlist'}}) {

548

foreach $parameter (@{$args{'parameterlist'}}) {

545

my $parameter_name = $parameter;

549

my $parameter_name = $parameter;

546

$parameter_name =~ s/\[.*//;

550

$parameter_name =~ s/\[.*//;

547

551

548

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

552

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

549

print "<dt><b>".$parameter."</b>\n";

553

print "<dt><b>".$parameter."</b>\n";

550

print "<dd>";

554

print "<dd>";

551

output_highlight($args{'parameterdescs'}{$parameter_name});

555

output_highlight($args{'parameterdescs'}{$parameter_name});

552

}

556

}

553

print "</dl>\n";

557

print "</dl>\n";

554

output_section_html(@_);

558

output_section_html(@_);

555

print "<hr>\n";

559

print "<hr>\n";

556

}

560

}

557

561

558

# output intro in html

562

# output intro in html

559

sub output_intro_html(%) {

563

sub output_intro_html(%) {

560

my %args = %{$_[0]};

564

my %args = %{$_[0]};

561

my ($parameter, $section);

565

my ($parameter, $section);

562

my $count;

566

my $count;

563

567

564

foreach $section (@{$args{'sectionlist'}}) {

568

foreach $section (@{$args{'sectionlist'}}) {

565

print "<h3>$section</h3>\n";

569

print "<h3>$section</h3>\n";

566

print "<ul>\n";

570

print "<ul>\n";

567

output_highlight($args{'sections'}{$section});

571

output_highlight($args{'sections'}{$section});

568

print "</ul>\n";

572

print "</ul>\n";

569

}

573

}

570

print "<hr>\n";

574

print "<hr>\n";

571

}

575

}

572

576

573

sub output_section_xml(%) {

577

sub output_section_xml(%) {

574

my %args = %{$_[0]};

578

my %args = %{$_[0]};

575

my $section;

579

my $section;

576

# print out each section

580

# print out each section

577

$lineprefix=" ";

581

$lineprefix=" ";

578

foreach $section (@{$args{'sectionlist'}}) {

582

foreach $section (@{$args{'sectionlist'}}) {

579

print "<refsect1>\n";

583

print "<refsect1>\n";

580

print "<title>$section</title>\n";

584

print "<title>$section</title>\n";

581

if ($section =~ m/EXAMPLE/i) {

585

if ($section =~ m/EXAMPLE/i) {

582

print "<informalexample><programlisting>\n";

586

print "<informalexample><programlisting>\n";

583

} else {

587

} else {

584

print "<para>\n";

588

print "<para>\n";

585

}

589

}

586

output_highlight($args{'sections'}{$section});

590

output_highlight($args{'sections'}{$section});

587

if ($section =~ m/EXAMPLE/i) {

591

if ($section =~ m/EXAMPLE/i) {

588

print "</programlisting></informalexample>\n";

592

print "</programlisting></informalexample>\n";

589

} else {

593

} else {

590

print "</para>\n";

594

print "</para>\n";

591

}

595

}

592

print "</refsect1>\n";

596

print "</refsect1>\n";

593

}

597

}

594

}

598

}

595

599

596

# output function in XML DocBook

600

# output function in XML DocBook

597

sub output_function_xml(%) {

601

sub output_function_xml(%) {

598

my %args = %{$_[0]};

602

my %args = %{$_[0]};

599

my ($parameter, $section);

603

my ($parameter, $section);

600

my $count;

604

my $count;

601

my $id;

605

my $id;

602

606

603

$id = "API-".$args{'function'};

607

$id = "API-".$args{'function'};

604

$id =~ s/[^A-Za-z0-9]/-/g;

608

$id =~ s/[^A-Za-z0-9]/-/g;

605

609

606

print "<refentry id=\"$id\">\n";

610

print "<refentry id=\"$id\">\n";

607

print "<refentryinfo>\n";

611

print "<refentryinfo>\n";

608

print " <title>LINUX</title>\n";

612

print " <title>LINUX</title>\n";

609

print " <productname>Kernel Hackers Manual</productname>\n";

613

print " <productname>Kernel Hackers Manual</productname>\n";

610

print " <date>$man_date</date>\n";

614

print " <date>$man_date</date>\n";

611

print "</refentryinfo>\n";

615

print "</refentryinfo>\n";

612

print "<refmeta>\n";

616

print "<refmeta>\n";

613

print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";

617

print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";

614

print " <manvolnum>9</manvolnum>\n";

618

print " <manvolnum>9</manvolnum>\n";

615

print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";

619

print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";

616

print "</refmeta>\n";

620

print "</refmeta>\n";

617

print "<refnamediv>\n";

621

print "<refnamediv>\n";

618

print " <refname>".$args{'function'}."</refname>\n";

622

print " <refname>".$args{'function'}."</refname>\n";

619

print " <refpurpose>\n";

623

print " <refpurpose>\n";

620

print " ";

624

print " ";

621

output_highlight ($args{'purpose'});

625

output_highlight ($args{'purpose'});

622

print " </refpurpose>\n";

626

print " </refpurpose>\n";

623

print "</refnamediv>\n";

627

print "</refnamediv>\n";

624

628

625

print "<refsynopsisdiv>\n";

629

print "<refsynopsisdiv>\n";

626

print " <title>Synopsis</title>\n";

630

print " <title>Synopsis</title>\n";

627

print " <funcsynopsis><funcprototype>\n";

631

print " <funcsynopsis><funcprototype>\n";

628

print " <funcdef>".$args{'functiontype'}." ";

632

print " <funcdef>".$args{'functiontype'}." ";

629

print "<function>".$args{'function'}." </function></funcdef>\n";

633

print "<function>".$args{'function'}." </function></funcdef>\n";

630

634

631

$count = 0;

635

$count = 0;

632

if ($#{$args{'parameterlist'}} >= 0) {

636

if ($#{$args{'parameterlist'}} >= 0) {

633

foreach $parameter (@{$args{'parameterlist'}}) {

637

foreach $parameter (@{$args{'parameterlist'}}) {

634

$type = $args{'parametertypes'}{$parameter};

638

$type = $args{'parametertypes'}{$parameter};

635

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

639

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

636

# pointer-to-function

640

# pointer-to-function

637

print " <paramdef>$1<parameter>$parameter</parameter>)\n";

641

print " <paramdef>$1<parameter>$parameter</parameter>)\n";

638

print " <funcparams>$2</funcparams></paramdef>\n";

642

print " <funcparams>$2</funcparams></paramdef>\n";

639

} else {

643

} else {

640

print " <paramdef>".$type;

644

print " <paramdef>".$type;

641

print " <parameter>$parameter</parameter></paramdef>\n";

645

print " <parameter>$parameter</parameter></paramdef>\n";

642

}

646

}

643

}

647

}

644

} else {

648

} else {

645

print " <void/>\n";

649

print " <void/>\n";

646

}

650

}

647

print " </funcprototype></funcsynopsis>\n";

651

print " </funcprototype></funcsynopsis>\n";

648

print "</refsynopsisdiv>\n";

652

print "</refsynopsisdiv>\n";

649

653

650

# print parameters

654

# print parameters

651

print "<refsect1>\n <title>Arguments</title>\n";

655

print "<refsect1>\n <title>Arguments</title>\n";

652

if ($#{$args{'parameterlist'}} >= 0) {

656

if ($#{$args{'parameterlist'}} >= 0) {

653

print " <variablelist>\n";

657

print " <variablelist>\n";

654

foreach $parameter (@{$args{'parameterlist'}}) {

658

foreach $parameter (@{$args{'parameterlist'}}) {

655

my $parameter_name = $parameter;

659

my $parameter_name = $parameter;

656

$parameter_name =~ s/\[.*//;

660

$parameter_name =~ s/\[.*//;

657

661

658

print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";

662

print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";

659

print " <listitem>\n <para>\n";

663

print " <listitem>\n <para>\n";

660

$lineprefix=" ";

664

$lineprefix=" ";

661

output_highlight($args{'parameterdescs'}{$parameter_name});

665

output_highlight($args{'parameterdescs'}{$parameter_name});

662

print " </para>\n </listitem>\n </varlistentry>\n";

666

print " </para>\n </listitem>\n </varlistentry>\n";

663

}

667

}

664

print " </variablelist>\n";

668

print " </variablelist>\n";

665

} else {

669

} else {

666

print " <para>\n None\n </para>\n";

670

print " <para>\n None\n </para>\n";

667

}

671

}

668

print "</refsect1>\n";

672

print "</refsect1>\n";

669

673

670

output_section_xml(@_);

674

output_section_xml(@_);

671

print "</refentry>\n\n";

675

print "</refentry>\n\n";

672

}

676

}

673

677

674

# output struct in XML DocBook

678

# output struct in XML DocBook

675

sub output_struct_xml(%) {

679

sub output_struct_xml(%) {

676

my %args = %{$_[0]};

680

my %args = %{$_[0]};

677

my ($parameter, $section);

681

my ($parameter, $section);

678

my $id;

682

my $id;

679

683

680

$id = "API-struct-".$args{'struct'};

684

$id = "API-struct-".$args{'struct'};

681

$id =~ s/[^A-Za-z0-9]/-/g;

685

$id =~ s/[^A-Za-z0-9]/-/g;

682

686

683

print "<refentry id=\"$id\">\n";

687

print "<refentry id=\"$id\">\n";

684

print "<refentryinfo>\n";

688

print "<refentryinfo>\n";

685

print " <title>LINUX</title>\n";

689

print " <title>LINUX</title>\n";

686

print " <productname>Kernel Hackers Manual</productname>\n";

690

print " <productname>Kernel Hackers Manual</productname>\n";

687

print " <date>$man_date</date>\n";

691

print " <date>$man_date</date>\n";

688

print "</refentryinfo>\n";

692

print "</refentryinfo>\n";

689

print "<refmeta>\n";

693

print "<refmeta>\n";

690

print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";

694

print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";

691

print " <manvolnum>9</manvolnum>\n";

695

print " <manvolnum>9</manvolnum>\n";

692

print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";

696

print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";

693

print "</refmeta>\n";

697

print "</refmeta>\n";

694

print "<refnamediv>\n";

698

print "<refnamediv>\n";

695

print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";

699

print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";

696

print " <refpurpose>\n";

700

print " <refpurpose>\n";

697

print " ";

701

print " ";

698

output_highlight ($args{'purpose'});

702

output_highlight ($args{'purpose'});

699

print " </refpurpose>\n";

703

print " </refpurpose>\n";

700

print "</refnamediv>\n";

704

print "</refnamediv>\n";

701

705

702

print "<refsynopsisdiv>\n";

706

print "<refsynopsisdiv>\n";

703

print " <title>Synopsis</title>\n";

707

print " <title>Synopsis</title>\n";

704

print " <programlisting>\n";

708

print " <programlisting>\n";

705

print $args{'type'}." ".$args{'struct'}." {\n";

709

print $args{'type'}." ".$args{'struct'}." {\n";

706

foreach $parameter (@{$args{'parameterlist'}}) {

710

foreach $parameter (@{$args{'parameterlist'}}) {

707

if ($parameter =~ /^#/) {

711

if ($parameter =~ /^#/) {

708

print "$parameter\n";

712

print "$parameter\n";

709

next;

713

next;

710

}

714

}

711

715

712

my $parameter_name = $parameter;

716

my $parameter_name = $parameter;

713

$parameter_name =~ s/\[.*//;

717

$parameter_name =~ s/\[.*//;

714

718

715

defined($args{'parameterdescs'}{$parameter_name}) || next;

719

defined($args{'parameterdescs'}{$parameter_name}) || next;

716

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

720

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

717

$type = $args{'parametertypes'}{$parameter};

721

$type = $args{'parametertypes'}{$parameter};

718

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

722

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

719

# pointer-to-function

723

# pointer-to-function

720

print " $1 $parameter) ($2);\n";

724

print " $1 $parameter) ($2);\n";

721

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

725

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

722

# bitfield

726

# bitfield

723

print " $1 $parameter$2;\n";

727

print " $1 $parameter$2;\n";

724

} else {

728

} else {

725

print " ".$type." ".$parameter.";\n";

729

print " ".$type." ".$parameter.";\n";

726

}

730

}

727

}

731

}

728

print "};";

732

print "};";

729

print " </programlisting>\n";

733

print " </programlisting>\n";

730

print "</refsynopsisdiv>\n";

734

print "</refsynopsisdiv>\n";

731

735

732

print " <refsect1>\n";

736

print " <refsect1>\n";

733

print " <title>Members</title>\n";

737

print " <title>Members</title>\n";

734

738

735

print " <variablelist>\n";

739

print " <variablelist>\n";

736

foreach $parameter (@{$args{'parameterlist'}}) {

740

foreach $parameter (@{$args{'parameterlist'}}) {

737

($parameter =~ /^#/) && next;

741

($parameter =~ /^#/) && next;

738

742

739

my $parameter_name = $parameter;

743

my $parameter_name = $parameter;

740

$parameter_name =~ s/\[.*//;

744

$parameter_name =~ s/\[.*//;

741

745

742

defined($args{'parameterdescs'}{$parameter_name}) || next;

746

defined($args{'parameterdescs'}{$parameter_name}) || next;

743

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

747

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

744

print " <varlistentry>";

748

print " <varlistentry>";

745

print " <term>$parameter</term>\n";

749

print " <term>$parameter</term>\n";

746

print " <listitem><para>\n";

750

print " <listitem><para>\n";

747

output_highlight($args{'parameterdescs'}{$parameter_name});

751

output_highlight($args{'parameterdescs'}{$parameter_name});

748

print " </para></listitem>\n";

752

print " </para></listitem>\n";

749

print " </varlistentry>\n";

753

print " </varlistentry>\n";

750

}

754

}

751

print " </variablelist>\n";

755

print " </variablelist>\n";

752

print " </refsect1>\n";

756

print " </refsect1>\n";

753

757

754

output_section_xml(@_);

758

output_section_xml(@_);

755

759

756

print "</refentry>\n\n";

760

print "</refentry>\n\n";

757

}

761

}

758

762

759

# output enum in XML DocBook

763

# output enum in XML DocBook

760

sub output_enum_xml(%) {

764

sub output_enum_xml(%) {

761

my %args = %{$_[0]};

765

my %args = %{$_[0]};

762

my ($parameter, $section);

766

my ($parameter, $section);

763

my $count;

767

my $count;

764

my $id;

768

my $id;

765

769

766

$id = "API-enum-".$args{'enum'};

770

$id = "API-enum-".$args{'enum'};

767

$id =~ s/[^A-Za-z0-9]/-/g;

771

$id =~ s/[^A-Za-z0-9]/-/g;

768

772

769

print "<refentry id=\"$id\">\n";

773

print "<refentry id=\"$id\">\n";

770

print "<refentryinfo>\n";

774

print "<refentryinfo>\n";

771

print " <title>LINUX</title>\n";

775

print " <title>LINUX</title>\n";

772

print " <productname>Kernel Hackers Manual</productname>\n";

776

print " <productname>Kernel Hackers Manual</productname>\n";

773

print " <date>$man_date</date>\n";

777

print " <date>$man_date</date>\n";

774

print "</refentryinfo>\n";

778

print "</refentryinfo>\n";

775

print "<refmeta>\n";

779

print "<refmeta>\n";

776

print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";

780

print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";

777

print " <manvolnum>9</manvolnum>\n";

781

print " <manvolnum>9</manvolnum>\n";

778

print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";

782

print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";

779

print "</refmeta>\n";

783

print "</refmeta>\n";

780

print "<refnamediv>\n";

784

print "<refnamediv>\n";

781

print " <refname>enum ".$args{'enum'}."</refname>\n";

785

print " <refname>enum ".$args{'enum'}."</refname>\n";

782

print " <refpurpose>\n";

786

print " <refpurpose>\n";

783

print " ";

787

print " ";

784

output_highlight ($args{'purpose'});

788

output_highlight ($args{'purpose'});

785

print " </refpurpose>\n";

789

print " </refpurpose>\n";

786

print "</refnamediv>\n";

790

print "</refnamediv>\n";

787

791

788

print "<refsynopsisdiv>\n";

792

print "<refsynopsisdiv>\n";

789

print " <title>Synopsis</title>\n";

793

print " <title>Synopsis</title>\n";

790

print " <programlisting>\n";

794

print " <programlisting>\n";

791

print "enum ".$args{'enum'}." {\n";

795

print "enum ".$args{'enum'}." {\n";

792

$count = 0;

796

$count = 0;

793

foreach $parameter (@{$args{'parameterlist'}}) {

797

foreach $parameter (@{$args{'parameterlist'}}) {

794

print " $parameter";

798

print " $parameter";

795

if ($count != $#{$args{'parameterlist'}}) {

799

if ($count != $#{$args{'parameterlist'}}) {

796

$count++;

800

$count++;

797

print ",";

801

print ",";

798

}

802

}

799

print "\n";

803

print "\n";

800

}

804

}

801

print "};";

805

print "};";

802

print " </programlisting>\n";

806

print " </programlisting>\n";

803

print "</refsynopsisdiv>\n";

807

print "</refsynopsisdiv>\n";

804

808

805

print "<refsect1>\n";

809

print "<refsect1>\n";

806

print " <title>Constants</title>\n";

810

print " <title>Constants</title>\n";

807

print " <variablelist>\n";

811

print " <variablelist>\n";

808

foreach $parameter (@{$args{'parameterlist'}}) {

812

foreach $parameter (@{$args{'parameterlist'}}) {

809

my $parameter_name = $parameter;

813

my $parameter_name = $parameter;

810

$parameter_name =~ s/\[.*//;

814

$parameter_name =~ s/\[.*//;

811

815

812

print " <varlistentry>";

816

print " <varlistentry>";

813

print " <term>$parameter</term>\n";

817

print " <term>$parameter</term>\n";

814

print " <listitem><para>\n";

818

print " <listitem><para>\n";

815

output_highlight($args{'parameterdescs'}{$parameter_name});

819

output_highlight($args{'parameterdescs'}{$parameter_name});

816

print " </para></listitem>\n";

820

print " </para></listitem>\n";

817

print " </varlistentry>\n";

821

print " </varlistentry>\n";

818

}

822

}

819

print " </variablelist>\n";

823

print " </variablelist>\n";

820

print "</refsect1>\n";

824

print "</refsect1>\n";

821

825

822

output_section_xml(@_);

826

output_section_xml(@_);

823

827

824

print "</refentry>\n\n";

828

print "</refentry>\n\n";

825

}

829

}

826

830

827

# output typedef in XML DocBook

831

# output typedef in XML DocBook

828

sub output_typedef_xml(%) {

832

sub output_typedef_xml(%) {

829

my %args = %{$_[0]};

833

my %args = %{$_[0]};

830

my ($parameter, $section);

834

my ($parameter, $section);

831

my $id;

835

my $id;

832

836

833

$id = "API-typedef-".$args{'typedef'};

837

$id = "API-typedef-".$args{'typedef'};

834

$id =~ s/[^A-Za-z0-9]/-/g;

838

$id =~ s/[^A-Za-z0-9]/-/g;

835

839

836

print "<refentry id=\"$id\">\n";

840

print "<refentry id=\"$id\">\n";

837

print "<refentryinfo>\n";

841

print "<refentryinfo>\n";

838

print " <title>LINUX</title>\n";

842

print " <title>LINUX</title>\n";

839

print " <productname>Kernel Hackers Manual</productname>\n";

843

print " <productname>Kernel Hackers Manual</productname>\n";

840

print " <date>$man_date</date>\n";

844

print " <date>$man_date</date>\n";

841

print "</refentryinfo>\n";

845

print "</refentryinfo>\n";

842

print "<refmeta>\n";

846

print "<refmeta>\n";

843

print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";

847

print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";

844

print " <manvolnum>9</manvolnum>\n";

848

print " <manvolnum>9</manvolnum>\n";

845

print "</refmeta>\n";

849

print "</refmeta>\n";

846

print "<refnamediv>\n";

850

print "<refnamediv>\n";

847

print " <refname>typedef ".$args{'typedef'}."</refname>\n";

851

print " <refname>typedef ".$args{'typedef'}."</refname>\n";

848

print " <refpurpose>\n";

852

print " <refpurpose>\n";

849

print " ";

853

print " ";

850

output_highlight ($args{'purpose'});

854

output_highlight ($args{'purpose'});

851

print " </refpurpose>\n";

855

print " </refpurpose>\n";

852

print "</refnamediv>\n";

856

print "</refnamediv>\n";

853

857

854

print "<refsynopsisdiv>\n";

858

print "<refsynopsisdiv>\n";

855

print " <title>Synopsis</title>\n";

859

print " <title>Synopsis</title>\n";

856

print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";

860

print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";

857

print "</refsynopsisdiv>\n";

861

print "</refsynopsisdiv>\n";

858

862

859

output_section_xml(@_);

863

output_section_xml(@_);

860

864

861

print "</refentry>\n\n";

865

print "</refentry>\n\n";

862

}

866

}

863

867

864

# output in XML DocBook

868

# output in XML DocBook

865

sub output_intro_xml(%) {

869

sub output_intro_xml(%) {

866

my %args = %{$_[0]};

870

my %args = %{$_[0]};

867

my ($parameter, $section);

871

my ($parameter, $section);

868

my $count;

872

my $count;

869

873

870

my $id = $args{'module'};

874

my $id = $args{'module'};

871

$id =~ s/[^A-Za-z0-9]/-/g;

875

$id =~ s/[^A-Za-z0-9]/-/g;

872

876

873

# print out each section

877

# print out each section

874

$lineprefix=" ";

878

$lineprefix=" ";

875

foreach $section (@{$args{'sectionlist'}}) {

879

foreach $section (@{$args{'sectionlist'}}) {

876

print "<refsect1>\n <title>$section</title>\n <para>\n";

880

print "<refsect1>\n <title>$section</title>\n <para>\n";

877

if ($section =~ m/EXAMPLE/i) {

881

if ($section =~ m/EXAMPLE/i) {

878

print "<example><para>\n";

882

print "<example><para>\n";

879

}

883

}

880

output_highlight($args{'sections'}{$section});

884

output_highlight($args{'sections'}{$section});

881

if ($section =~ m/EXAMPLE/i) {

885

if ($section =~ m/EXAMPLE/i) {

882

print "</para></example>\n";

886

print "</para></example>\n";

883

}

887

}

884

print " </para>\n</refsect1>\n";

888

print " </para>\n</refsect1>\n";

885

}

889

}

886

890

887

print "\n\n";

891

print "\n\n";

888

}

892

}

889

893

890

# output in XML DocBook

894

# output in XML DocBook

891

sub output_function_gnome {

895

sub output_function_gnome {

892

my %args = %{$_[0]};

896

my %args = %{$_[0]};

893

my ($parameter, $section);

897

my ($parameter, $section);

894

my $count;

898

my $count;

895

my $id;

899

my $id;

896

900

897

$id = $args{'module'}."-".$args{'function'};

901

$id = $args{'module'}."-".$args{'function'};

898

$id =~ s/[^A-Za-z0-9]/-/g;

902

$id =~ s/[^A-Za-z0-9]/-/g;

899

903

900

print "<sect2>\n";

904

print "<sect2>\n";

901

print " <title id=\"$id\">".$args{'function'}."</title>\n";

905

print " <title id=\"$id\">".$args{'function'}."</title>\n";

902

906

903

print " <funcsynopsis>\n";

907

print " <funcsynopsis>\n";

904

print " <funcdef>".$args{'functiontype'}." ";

908

print " <funcdef>".$args{'functiontype'}." ";

905

print "<function>".$args{'function'}." ";

909

print "<function>".$args{'function'}." ";

906

print "</function></funcdef>\n";

910

print "</function></funcdef>\n";

907

911

908

$count = 0;

912

$count = 0;

909

if ($#{$args{'parameterlist'}} >= 0) {

913

if ($#{$args{'parameterlist'}} >= 0) {

910

foreach $parameter (@{$args{'parameterlist'}}) {

914

foreach $parameter (@{$args{'parameterlist'}}) {

911

$type = $args{'parametertypes'}{$parameter};

915

$type = $args{'parametertypes'}{$parameter};

912

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

916

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

913

# pointer-to-function

917

# pointer-to-function

914

print " <paramdef>$1 <parameter>$parameter</parameter>)\n";

918

print " <paramdef>$1 <parameter>$parameter</parameter>)\n";

915

print " <funcparams>$2</funcparams></paramdef>\n";

919

print " <funcparams>$2</funcparams></paramdef>\n";

916

} else {

920

} else {

917

print " <paramdef>".$type;

921

print " <paramdef>".$type;

918

print " <parameter>$parameter</parameter></paramdef>\n";

922

print " <parameter>$parameter</parameter></paramdef>\n";

919

}

923

}

920

}

924

}

921

} else {

925

} else {

922

print " <void>\n";

926

print " <void>\n";

923

}

927

}

924

print " </funcsynopsis>\n";

928

print " </funcsynopsis>\n";

925

if ($#{$args{'parameterlist'}} >= 0) {

929

if ($#{$args{'parameterlist'}} >= 0) {

926

print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";

930

print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";

927

print "<tgroup cols=\"2\">\n";

931

print "<tgroup cols=\"2\">\n";

928

print "<colspec colwidth=\"2*\">\n";

932

print "<colspec colwidth=\"2*\">\n";

929

print "<colspec colwidth=\"8*\">\n";

933

print "<colspec colwidth=\"8*\">\n";

930

print "<tbody>\n";

934

print "<tbody>\n";

931

foreach $parameter (@{$args{'parameterlist'}}) {

935

foreach $parameter (@{$args{'parameterlist'}}) {

932

my $parameter_name = $parameter;

936

my $parameter_name = $parameter;

933

$parameter_name =~ s/\[.*//;

937

$parameter_name =~ s/\[.*//;

934

938

935

print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";

939

print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";

936

print " <entry>\n";

940

print " <entry>\n";

937

$lineprefix=" ";

941

$lineprefix=" ";

938

output_highlight($args{'parameterdescs'}{$parameter_name});

942

output_highlight($args{'parameterdescs'}{$parameter_name});

939

print " </entry></row>\n";

943

print " </entry></row>\n";

940

}

944

}

941

print " </tbody></tgroup></informaltable>\n";

945

print " </tbody></tgroup></informaltable>\n";

942

} else {

946

} else {

943

print " <para>\n None\n </para>\n";

947

print " <para>\n None\n </para>\n";

944

}

948

}

945

949

946

# print out each section

950

# print out each section

947

$lineprefix=" ";

951

$lineprefix=" ";

948

foreach $section (@{$args{'sectionlist'}}) {

952

foreach $section (@{$args{'sectionlist'}}) {

949

print "<simplesect>\n <title>$section</title>\n";

953

print "<simplesect>\n <title>$section</title>\n";

950

if ($section =~ m/EXAMPLE/i) {

954

if ($section =~ m/EXAMPLE/i) {

951

print "<example><programlisting>\n";

955

print "<example><programlisting>\n";

952

} else {

956

} else {

953

}

957

}

954

print "<para>\n";

958

print "<para>\n";

955

output_highlight($args{'sections'}{$section});

959

output_highlight($args{'sections'}{$section});

956

print "</para>\n";

960

print "</para>\n";

957

if ($section =~ m/EXAMPLE/i) {

961

if ($section =~ m/EXAMPLE/i) {

958

print "</programlisting></example>\n";

962

print "</programlisting></example>\n";

959

} else {

963

} else {

960

}

964

}

961

print " </simplesect>\n";

965

print " </simplesect>\n";

962

}

966

}

963

967

964

print "</sect2>\n\n";

968

print "</sect2>\n\n";

965

}

969

}

966

970

967

##

971

##

968

# output function in man

972

# output function in man

969

sub output_function_man(%) {

973

sub output_function_man(%) {

970

my %args = %{$_[0]};

974

my %args = %{$_[0]};

971

my ($parameter, $section);

975

my ($parameter, $section);

972

my $count;

976

my $count;

973

977

974

print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";

978

print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";

975

979

976

print ".SH NAME\n";

980

print ".SH NAME\n";

977

print $args{'function'}." \\- ".$args{'purpose'}."\n";

981

print $args{'function'}." \\- ".$args{'purpose'}."\n";

978

982

979

print ".SH SYNOPSIS\n";

983

print ".SH SYNOPSIS\n";

980

if ($args{'functiontype'} ne "") {

984

if ($args{'functiontype'} ne "") {

981

print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";

985

print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";

982

} else {

986

} else {

983

print ".B \"".$args{'function'}."\n";

987

print ".B \"".$args{'function'}."\n";

984

}

988

}

985

$count = 0;

989

$count = 0;

986

my $parenth = "(";

990

my $parenth = "(";

987

my $post = ",";

991

my $post = ",";

988

foreach my $parameter (@{$args{'parameterlist'}}) {

992

foreach my $parameter (@{$args{'parameterlist'}}) {

989

if ($count == $#{$args{'parameterlist'}}) {

993

if ($count == $#{$args{'parameterlist'}}) {

990

$post = ");";

994

$post = ");";

991

}

995

}

992

$type = $args{'parametertypes'}{$parameter};

996

$type = $args{'parametertypes'}{$parameter};

993

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

997

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

994

# pointer-to-function

998

# pointer-to-function

995

print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";

999

print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";

996

} else {

1000

} else {

997

$type =~ s/([^\*])$/$1 /;

1001

$type =~ s/([^\*])$/$1 /;

998

print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";

1002

print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";

999

}

1003

}

1000

$count++;

1004

$count++;

1001

$parenth = "";

1005

$parenth = "";

1002

}

1006

}

1003

1007

1004

print ".SH ARGUMENTS\n";

1008

print ".SH ARGUMENTS\n";

1005

foreach $parameter (@{$args{'parameterlist'}}) {

1009

foreach $parameter (@{$args{'parameterlist'}}) {

1006

my $parameter_name = $parameter;

1010

my $parameter_name = $parameter;

1007

$parameter_name =~ s/\[.*//;

1011

$parameter_name =~ s/\[.*//;

1008

1012

1009

print ".IP \"".$parameter."\" 12\n";

1013

print ".IP \"".$parameter."\" 12\n";

1010

output_highlight($args{'parameterdescs'}{$parameter_name});

1014

output_highlight($args{'parameterdescs'}{$parameter_name});

1011

}

1015

}

1012

foreach $section (@{$args{'sectionlist'}}) {

1016

foreach $section (@{$args{'sectionlist'}}) {

1013

print ".SH \"", uc $section, "\"\n";

1017

print ".SH \"", uc $section, "\"\n";

1014

output_highlight($args{'sections'}{$section});

1018

output_highlight($args{'sections'}{$section});

1015

}

1019

}

1016

}

1020

}

1017

1021

1018

##

1022

##

1019

# output enum in man

1023

# output enum in man

1020

sub output_enum_man(%) {

1024

sub output_enum_man(%) {

1021

my %args = %{$_[0]};

1025

my %args = %{$_[0]};

1022

my ($parameter, $section);

1026

my ($parameter, $section);

1023

my $count;

1027

my $count;

1024

1028

1025

print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";

1029

print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";

1026

1030

1027

print ".SH NAME\n";

1031

print ".SH NAME\n";

1028

print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";

1032

print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";

1029

1033

1030

print ".SH SYNOPSIS\n";

1034

print ".SH SYNOPSIS\n";

1031

print "enum ".$args{'enum'}." {\n";

1035

print "enum ".$args{'enum'}." {\n";

1032

$count = 0;

1036

$count = 0;

1033

foreach my $parameter (@{$args{'parameterlist'}}) {

1037

foreach my $parameter (@{$args{'parameterlist'}}) {

1034

print ".br\n.BI \" $parameter\"\n";

1038

print ".br\n.BI \" $parameter\"\n";

1035

if ($count == $#{$args{'parameterlist'}}) {

1039

if ($count == $#{$args{'parameterlist'}}) {

1036

print "\n};\n";

1040

print "\n};\n";

1037

last;

1041

last;

1038

}

1042

}

1039

else {

1043

else {

1040

print ", \n.br\n";

1044

print ", \n.br\n";

1041

}

1045

}

1042

$count++;

1046

$count++;

1043

}

1047

}

1044

1048

1045

print ".SH Constants\n";

1049

print ".SH Constants\n";

1046

foreach $parameter (@{$args{'parameterlist'}}) {

1050

foreach $parameter (@{$args{'parameterlist'}}) {

1047

my $parameter_name = $parameter;

1051

my $parameter_name = $parameter;

1048

$parameter_name =~ s/\[.*//;

1052

$parameter_name =~ s/\[.*//;

1049

1053

1050

print ".IP \"".$parameter."\" 12\n";

1054

print ".IP \"".$parameter."\" 12\n";

1051

output_highlight($args{'parameterdescs'}{$parameter_name});

1055

output_highlight($args{'parameterdescs'}{$parameter_name});

1052

}

1056

}

1053

foreach $section (@{$args{'sectionlist'}}) {

1057

foreach $section (@{$args{'sectionlist'}}) {

1054

print ".SH \"$section\"\n";

1058

print ".SH \"$section\"\n";

1055

output_highlight($args{'sections'}{$section});

1059

output_highlight($args{'sections'}{$section});

1056

}

1060

}

1057

}

1061

}

1058

1062

1059

##

1063

##

1060

# output struct in man

1064

# output struct in man

1061

sub output_struct_man(%) {

1065

sub output_struct_man(%) {

1062

my %args = %{$_[0]};

1066

my %args = %{$_[0]};

1063

my ($parameter, $section);

1067

my ($parameter, $section);

1064

1068

1065

print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";

1069

print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";

1066

1070

1067

print ".SH NAME\n";

1071

print ".SH NAME\n";

1068

print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";

1072

print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";

1069

1073

1070

print ".SH SYNOPSIS\n";

1074

print ".SH SYNOPSIS\n";

1071

print $args{'type'}." ".$args{'struct'}." {\n.br\n";

1075

print $args{'type'}." ".$args{'struct'}." {\n.br\n";

1072

1076

1073

foreach my $parameter (@{$args{'parameterlist'}}) {

1077

foreach my $parameter (@{$args{'parameterlist'}}) {

1074

if ($parameter =~ /^#/) {

1078

if ($parameter =~ /^#/) {

1075

print ".BI \"$parameter\"\n.br\n";

1079

print ".BI \"$parameter\"\n.br\n";

1076

next;

1080

next;

1077

}

1081

}

1078

my $parameter_name = $parameter;

1082

my $parameter_name = $parameter;

1079

$parameter_name =~ s/\[.*//;

1083

$parameter_name =~ s/\[.*//;

1080

1084

1081

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1085

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1082

$type = $args{'parametertypes'}{$parameter};

1086

$type = $args{'parametertypes'}{$parameter};

1083

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1087

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1084

# pointer-to-function

1088

# pointer-to-function

1085

print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";

1089

print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";

1086

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

1090

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

1087

# bitfield

1091

# bitfield

1088

print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";

1092

print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";

1089

} else {

1093

} else {

1090

$type =~ s/([^\*])$/$1 /;

1094

$type =~ s/([^\*])$/$1 /;

1091

print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";

1095

print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";

1092

}

1096

}

1093

print "\n.br\n";

1097

print "\n.br\n";

1094

}

1098

}

1095

print "};\n.br\n";

1099

print "};\n.br\n";

1096

1100

1097

print ".SH Members\n";

1101

print ".SH Members\n";

1098

foreach $parameter (@{$args{'parameterlist'}}) {

1102

foreach $parameter (@{$args{'parameterlist'}}) {

1099

($parameter =~ /^#/) && next;

1103

($parameter =~ /^#/) && next;

1100

1104

1101

my $parameter_name = $parameter;

1105

my $parameter_name = $parameter;

1102

$parameter_name =~ s/\[.*//;

1106

$parameter_name =~ s/\[.*//;

1103

1107

1104

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1108

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1105

print ".IP \"".$parameter."\" 12\n";

1109

print ".IP \"".$parameter."\" 12\n";

1106

output_highlight($args{'parameterdescs'}{$parameter_name});

1110

output_highlight($args{'parameterdescs'}{$parameter_name});

1107

}

1111

}

1108

foreach $section (@{$args{'sectionlist'}}) {

1112

foreach $section (@{$args{'sectionlist'}}) {

1109

print ".SH \"$section\"\n";

1113

print ".SH \"$section\"\n";

1110

output_highlight($args{'sections'}{$section});

1114

output_highlight($args{'sections'}{$section});

1111

}

1115

}

1112

}

1116

}

1113

1117

1114

##

1118

##

1115

# output typedef in man

1119

# output typedef in man

1116

sub output_typedef_man(%) {

1120

sub output_typedef_man(%) {

1117

my %args = %{$_[0]};

1121

my %args = %{$_[0]};

1118

my ($parameter, $section);

1122

my ($parameter, $section);

1119

1123

1120

print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

1124

print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

1121

1125

1122

print ".SH NAME\n";

1126

print ".SH NAME\n";

1123

print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";

1127

print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";

1124

1128

1125

foreach $section (@{$args{'sectionlist'}}) {

1129

foreach $section (@{$args{'sectionlist'}}) {

1126

print ".SH \"$section\"\n";

1130

print ".SH \"$section\"\n";

1127

output_highlight($args{'sections'}{$section});

1131

output_highlight($args{'sections'}{$section});

1128

}

1132

}

1129

}

1133

}

1130

1134

1131

sub output_intro_man(%) {

1135

sub output_intro_man(%) {

1132

my %args = %{$_[0]};

1136

my %args = %{$_[0]};

1133

my ($parameter, $section);

1137

my ($parameter, $section);

1134

my $count;

1138

my $count;

1135

1139

1136

print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

1140

print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

1137

1141

1138

foreach $section (@{$args{'sectionlist'}}) {

1142

foreach $section (@{$args{'sectionlist'}}) {

1139

print ".SH \"$section\"\n";

1143

print ".SH \"$section\"\n";

1140

output_highlight($args{'sections'}{$section});

1144

output_highlight($args{'sections'}{$section});

1141

}

1145

}

1142

}

1146

}

1143

1147

1144

##

1148

##

1145

# output in text

1149

# output in text

1146

sub output_function_text(%) {

1150

sub output_function_text(%) {

1147

my %args = %{$_[0]};

1151

my %args = %{$_[0]};

1148

my ($parameter, $section);

1152

my ($parameter, $section);

1149

my $start;

1153

my $start;

1150

1154

1151

print "Name:\n\n";

1155

print "Name:\n\n";

1152

print $args{'function'}." - ".$args{'purpose'}."\n";

1156

print $args{'function'}." - ".$args{'purpose'}."\n";

1153

1157

1154

print "\nSynopsis:\n\n";

1158

print "\nSynopsis:\n\n";

1155

if ($args{'functiontype'} ne "") {

1159

if ($args{'functiontype'} ne "") {

1156

$start = $args{'functiontype'}." ".$args{'function'}." (";

1160

$start = $args{'functiontype'}." ".$args{'function'}." (";

1157

} else {

1161

} else {

1158

$start = $args{'function'}." (";

1162

$start = $args{'function'}." (";

1159

}

1163

}

1160

print $start;

1164

print $start;

1161

1165

1162

my $count = 0;

1166

my $count = 0;

1163

foreach my $parameter (@{$args{'parameterlist'}}) {

1167

foreach my $parameter (@{$args{'parameterlist'}}) {

1164

$type = $args{'parametertypes'}{$parameter};

1168

$type = $args{'parametertypes'}{$parameter};

1165

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1169

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1166

# pointer-to-function

1170

# pointer-to-function

1167

print $1.$parameter.") (".$2;

1171

print $1.$parameter.") (".$2;

1168

} else {

1172

} else {

1169

print $type." ".$parameter;

1173

print $type." ".$parameter;

1170

}

1174

}

1171

if ($count != $#{$args{'parameterlist'}}) {

1175

if ($count != $#{$args{'parameterlist'}}) {

1172

$count++;

1176

$count++;

1173

print ",\n";

1177

print ",\n";

1174

print " " x length($start);

1178

print " " x length($start);

1175

} else {

1179

} else {

1176

print ");\n\n";

1180

print ");\n\n";

1177

}

1181

}

1178

}

1182

}

1179

1183

1180

print "Arguments:\n\n";

1184

print "Arguments:\n\n";

1181

foreach $parameter (@{$args{'parameterlist'}}) {

1185

foreach $parameter (@{$args{'parameterlist'}}) {

1182

my $parameter_name = $parameter;

1186

my $parameter_name = $parameter;

1183

$parameter_name =~ s/\[.*//;

1187

$parameter_name =~ s/\[.*//;

1184

1188

1185

print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";

1189

print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";

1186

}

1190

}

1187

output_section_text(@_);

1191

output_section_text(@_);

1188

}

1192

}

1189

1193

1190

#output sections in text

1194

#output sections in text

1191

sub output_section_text(%) {

1195

sub output_section_text(%) {

1192

my %args = %{$_[0]};

1196

my %args = %{$_[0]};

1193

my $section;

1197

my $section;

1194

1198

1195

print "\n";

1199

print "\n";

1196

foreach $section (@{$args{'sectionlist'}}) {

1200

foreach $section (@{$args{'sectionlist'}}) {

1197

print "$section:\n\n";

1201

print "$section:\n\n";

1198

output_highlight($args{'sections'}{$section});

1202

output_highlight($args{'sections'}{$section});

1199

}

1203

}

1200

print "\n\n";

1204

print "\n\n";

1201

}

1205

}

1202

1206

1203

# output enum in text

1207

# output enum in text

1204

sub output_enum_text(%) {

1208

sub output_enum_text(%) {

1205

my %args = %{$_[0]};

1209

my %args = %{$_[0]};

1206

my ($parameter);

1210

my ($parameter);

1207

my $count;

1211

my $count;

1208

print "Enum:\n\n";

1212

print "Enum:\n\n";

1209

1213

1210

print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";

1214

print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";

1211

print "enum ".$args{'enum'}." {\n";

1215

print "enum ".$args{'enum'}." {\n";

1212

$count = 0;

1216

$count = 0;

1213

foreach $parameter (@{$args{'parameterlist'}}) {

1217

foreach $parameter (@{$args{'parameterlist'}}) {

1214

print "\t$parameter";

1218

print "\t$parameter";

1215

if ($count != $#{$args{'parameterlist'}}) {

1219

if ($count != $#{$args{'parameterlist'}}) {

1216

$count++;

1220

$count++;

1217

print ",";

1221

print ",";

1218

}

1222

}

1219

print "\n";

1223

print "\n";

1220

}

1224

}

1221

print "};\n\n";

1225

print "};\n\n";

1222

1226

1223

print "Constants:\n\n";

1227

print "Constants:\n\n";

1224

foreach $parameter (@{$args{'parameterlist'}}) {

1228

foreach $parameter (@{$args{'parameterlist'}}) {

1225

print "$parameter\n\t";

1229

print "$parameter\n\t";

1226

print $args{'parameterdescs'}{$parameter}."\n";

1230

print $args{'parameterdescs'}{$parameter}."\n";

1227

}

1231

}

1228

1232

1229

output_section_text(@_);

1233

output_section_text(@_);

1230

}

1234

}

1231

1235

1232

# output typedef in text

1236

# output typedef in text

1233

sub output_typedef_text(%) {

1237

sub output_typedef_text(%) {

1234

my %args = %{$_[0]};

1238

my %args = %{$_[0]};

1235

my ($parameter);

1239

my ($parameter);

1236

my $count;

1240

my $count;

1237

print "Typedef:\n\n";

1241

print "Typedef:\n\n";

1238

1242

1239

print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";

1243

print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";

1240

output_section_text(@_);

1244

output_section_text(@_);

1241

}

1245

}

1242

1246

1243

# output struct as text

1247

# output struct as text

1244

sub output_struct_text(%) {

1248

sub output_struct_text(%) {

1245

my %args = %{$_[0]};

1249

my %args = %{$_[0]};

1246

my ($parameter);

1250

my ($parameter);

1247

1251

1248

print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";

1252

print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";

1249

print $args{'type'}." ".$args{'struct'}." {\n";

1253

print $args{'type'}." ".$args{'struct'}." {\n";

1250

foreach $parameter (@{$args{'parameterlist'}}) {

1254

foreach $parameter (@{$args{'parameterlist'}}) {

1251

if ($parameter =~ /^#/) {

1255

if ($parameter =~ /^#/) {

1252

print "$parameter\n";

1256

print "$parameter\n";

1253

next;

1257

next;

1254

}

1258

}

1255

1259

1256

my $parameter_name = $parameter;

1260

my $parameter_name = $parameter;

1257

$parameter_name =~ s/\[.*//;

1261

$parameter_name =~ s/\[.*//;

1258

1262

1259

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1263

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1260

$type = $args{'parametertypes'}{$parameter};

1264

$type = $args{'parametertypes'}{$parameter};

1261

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1265

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1262

# pointer-to-function

1266

# pointer-to-function

1263

print "\t$1 $parameter) ($2);\n";

1267

print "\t$1 $parameter) ($2);\n";

1264

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

1268

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

1265

# bitfield

1269

# bitfield

1266

print "\t$1 $parameter$2;\n";

1270

print "\t$1 $parameter$2;\n";

1267

} else {

1271

} else {

1268

print "\t".$type." ".$parameter.";\n";

1272

print "\t".$type." ".$parameter.";\n";

1269

}

1273

}

1270

}

1274

}

1271

print "};\n\n";

1275

print "};\n\n";

1272

1276

1273

print "Members:\n\n";

1277

print "Members:\n\n";

1274

foreach $parameter (@{$args{'parameterlist'}}) {

1278

foreach $parameter (@{$args{'parameterlist'}}) {

1275

($parameter =~ /^#/) && next;

1279

($parameter =~ /^#/) && next;

1276

1280

1277

my $parameter_name = $parameter;

1281

my $parameter_name = $parameter;

1278

$parameter_name =~ s/\[.*//;

1282

$parameter_name =~ s/\[.*//;

1279

1283

1280

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1284

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1281

print "$parameter\n\t";

1285

print "$parameter\n\t";

1282

print $args{'parameterdescs'}{$parameter_name}."\n";

1286

print $args{'parameterdescs'}{$parameter_name}."\n";

1283

}

1287

}

1284

print "\n";

1288

print "\n";

1285

output_section_text(@_);

1289

output_section_text(@_);

1286

}

1290

}

1287

1291

1288

sub output_intro_text(%) {

1292

sub output_intro_text(%) {

1289

my %args = %{$_[0]};

1293

my %args = %{$_[0]};

1290

my ($parameter, $section);

1294

my ($parameter, $section);

1291

1295

1292

foreach $section (@{$args{'sectionlist'}}) {

1296

foreach $section (@{$args{'sectionlist'}}) {

1293

print " $section:\n";

1297

print " $section:\n";

1294

print " -> ";

1298

print " -> ";

1295

output_highlight($args{'sections'}{$section});

1299

output_highlight($args{'sections'}{$section});

1296

}

1300

}

1297

}

1301

}

1298

1302

1299

##

1303

##

1300

# generic output function for all types (function, struct/union, typedef, enum);

1304

# generic output function for all types (function, struct/union, typedef, enum);

1301

# calls the generated, variable output_ function name based on

1305

# calls the generated, variable output_ function name based on

1302

# functype and output_mode

1306

# functype and output_mode

1303

sub output_declaration {

1307

sub output_declaration {

1304

no strict 'refs';

1308

no strict 'refs';

1305

my $name = shift;

1309

my $name = shift;

1306

my $functype = shift;

1310

my $functype = shift;

1307

my $func = "output_${functype}_$output_mode";

1311

my $func = "output_${functype}_$output_mode";

1308

if (($function_only==0) ||

1312

if (($function_only==0) ||

1309

( $function_only == 1 && defined($function_table{$name})) ||

1313

( $function_only == 1 && defined($function_table{$name})) ||

1310

( $function_only == 2 && !defined($function_table{$name})))

1314

( $function_only == 2 && !defined($function_table{$name})))

1311

{

1315

{

1312

&$func(@_);

1316

&$func(@_);

1313

$section_counter++;

1317

$section_counter++;

1314

}

1318

}

1315

}

1319

}

1316

1320

1317

##

1321

##

1318

# generic output function - calls the right one based on current output mode.

1322

# generic output function - calls the right one based on current output mode.

1319

sub output_intro {

1323

sub output_intro {

1320

no strict 'refs';

1324

no strict 'refs';

1321

my $func = "output_intro_".$output_mode;

1325

my $func = "output_intro_".$output_mode;

1322

&$func(@_);

1326

&$func(@_);

1323

$section_counter++;

1327

$section_counter++;

1324

}

1328

}

1325

1329

1326

##

1330

##

1327

# takes a declaration (struct, union, enum, typedef) and

1331

# takes a declaration (struct, union, enum, typedef) and

1328

# invokes the right handler. NOT called for functions.

1332

# invokes the right handler. NOT called for functions.

1329

sub dump_declaration($$) {

1333

sub dump_declaration($$) {

1330

no strict 'refs';

1334

no strict 'refs';

1331

my ($prototype, $file) = @_;

1335

my ($prototype, $file) = @_;

1332

my $func = "dump_".$decl_type;

1336

my $func = "dump_".$decl_type;

1333

&$func(@_);

1337

&$func(@_);

1334

}

1338

}

1335

1339

1336

sub dump_union($$) {

1340

sub dump_union($$) {

1337

dump_struct(@_);

1341

dump_struct(@_);

1338

}

1342

}

1339

1343

1340

sub dump_struct($$) {

1344

sub dump_struct($$) {

1341

my $x = shift;

1345

my $x = shift;

1342

my $file = shift;

1346

my $file = shift;

1343

1347

1344

if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {

1348

if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {

1345

$declaration_name = $2;

1349

$declaration_name = $2;

1346

my $members = $3;

1350

my $members = $3;

1347

1351

1348

# ignore embedded structs or unions

1352

# ignore embedded structs or unions

1349

$members =~ s/{.*?}//g;

1353

$members =~ s/{.*?}//g;

1350

1354

1351

# ignore members marked private:

1355

# ignore members marked private:

1352

$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;

1356

$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;

1353

$members =~ s/\/\*.*?private:.*//gos;

1357

$members =~ s/\/\*.*?private:.*//gos;

1354

# strip comments:

1358

# strip comments:

1355

$members =~ s/\/\*.*?\*\///gos;

1359

$members =~ s/\/\*.*?\*\///gos;

1356

1360

1357

create_parameterlist($members, ';', $file);

1361

create_parameterlist($members, ';', $file);

1358

1362

1359

output_declaration($declaration_name,

1363

output_declaration($declaration_name,

1360

'struct',

1364

'struct',

1361

{'struct' => $declaration_name,

1365

{'struct' => $declaration_name,

1362

'module' => $modulename,

1366

'module' => $modulename,

1363

'parameterlist' => \@parameterlist,

1367

'parameterlist' => \@parameterlist,

1364

'parameterdescs' => \%parameterdescs,

1368

'parameterdescs' => \%parameterdescs,

1365

'parametertypes' => \%parametertypes,

1369

'parametertypes' => \%parametertypes,

1366

'sectionlist' => \@sectionlist,

1370

'sectionlist' => \@sectionlist,

1367

'sections' => \%sections,

1371

'sections' => \%sections,

1368

'purpose' => $declaration_purpose,

1372

'purpose' => $declaration_purpose,

1369

'type' => $decl_type

1373

'type' => $decl_type

1370

});

1374

});

1371

}

1375

}

1372

else {

1376

else {

1373

print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";

1377

print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";

1374

++$errors;

1378

++$errors;

1375

}

1379

}

1376

}

1380

}

1377

1381

1378

sub dump_enum($$) {

1382

sub dump_enum($$) {

1379

my $x = shift;

1383

my $x = shift;

1380

my $file = shift;

1384

my $file = shift;

1381

1385

1382

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1386

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1383

if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {

1387

if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {

1384

$declaration_name = $1;

1388

$declaration_name = $1;

1385

my $members = $2;

1389

my $members = $2;

1386

1390

1387

foreach my $arg (split ',', $members) {

1391

foreach my $arg (split ',', $members) {

1388

$arg =~ s/^\s*(\w+).*/$1/;

1392

$arg =~ s/^\s*(\w+).*/$1/;

1389

push @parameterlist, $arg;

1393

push @parameterlist, $arg;

1390

if (!$parameterdescs{$arg}) {

1394

if (!$parameterdescs{$arg}) {

1391

$parameterdescs{$arg} = $undescribed;

1395

$parameterdescs{$arg} = $undescribed;

1392

print STDERR "Warning(${file}:$.): Enum value '$arg' ".

1396

print STDERR "Warning(${file}:$.): Enum value '$arg' ".

1393

"not described in enum '$declaration_name'\n";

1397

"not described in enum '$declaration_name'\n";

1394

}

1398

}

1395

1399

1396

}

1400

}

1397

1401

1398

output_declaration($declaration_name,

1402

output_declaration($declaration_name,

1399

'enum',

1403

'enum',

1400

{'enum' => $declaration_name,

1404

{'enum' => $declaration_name,

1401

'module' => $modulename,

1405

'module' => $modulename,

1402

'parameterlist' => \@parameterlist,

1406

'parameterlist' => \@parameterlist,

1403

'parameterdescs' => \%parameterdescs,

1407

'parameterdescs' => \%parameterdescs,

1404

'sectionlist' => \@sectionlist,

1408

'sectionlist' => \@sectionlist,

1405

'sections' => \%sections,

1409

'sections' => \%sections,

1406

'purpose' => $declaration_purpose

1410

'purpose' => $declaration_purpose

1407

});

1411

});

1408

}

1412

}

1409

else {

1413

else {

1410

print STDERR "Error(${file}:$.): Cannot parse enum!\n";

1414

print STDERR "Error(${file}:$.): Cannot parse enum!\n";

1411

++$errors;

1415

++$errors;

1412

}

1416

}

1413

}

1417

}

1414

1418

1415

sub dump_typedef($$) {

1419

sub dump_typedef($$) {

1416

my $x = shift;

1420

my $x = shift;

1417

my $file = shift;

1421

my $file = shift;

1418

1422

1419

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1423

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1420

while (($x =~ /$*.$\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {

1424

while (($x =~ /$*.$\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {

1421

$x =~ s/$*.$\s*;$/;/;

1425

$x =~ s/$*.$\s*;$/;/;

1422

$x =~ s/\[*.\]\s*;$/;/;

1426

$x =~ s/\[*.\]\s*;$/;/;

1423

}

1427

}

1424

1428

1425

if ($x =~ /typedef.*\s+(\w+)\s*;/) {

1429

if ($x =~ /typedef.*\s+(\w+)\s*;/) {

1426

$declaration_name = $1;

1430

$declaration_name = $1;

1427

1431

1428

output_declaration($declaration_name,

1432

output_declaration($declaration_name,

1429

'typedef',

1433

'typedef',

1430

{'typedef' => $declaration_name,

1434

{'typedef' => $declaration_name,

1431

'module' => $modulename,

1435

'module' => $modulename,

1432

'sectionlist' => \@sectionlist,

1436

'sectionlist' => \@sectionlist,

1433

'sections' => \%sections,

1437

'sections' => \%sections,

1434

'purpose' => $declaration_purpose

1438

'purpose' => $declaration_purpose

1435

});

1439

});

1436

}

1440

}

1437

else {

1441

else {

1438

print STDERR "Error(${file}:$.): Cannot parse typedef!\n";

1442

print STDERR "Error(${file}:$.): Cannot parse typedef!\n";

1439

++$errors;

1443

++$errors;

1440

}

1444

}

1441

}

1445

}

1442

1446

1443

sub create_parameterlist($$$) {

1447

sub create_parameterlist($$$) {

1444

my $args = shift;

1448

my $args = shift;

1445

my $splitter = shift;

1449

my $splitter = shift;

1446

my $file = shift;

1450

my $file = shift;

1447

my $type;

1451

my $type;

1448

my $param;

1452

my $param;

1449

1453

1450

# temporarily replace commas inside function pointer definition

1454

# temporarily replace commas inside function pointer definition

1451

while ($args =~ /($[^$,]+),/) {

1455

while ($args =~ /($[^$,]+),/) {

1452

$args =~ s/($[^$,]+),/$1#/g;

1456

$args =~ s/($[^$,]+),/$1#/g;

1453

}

1457

}

1454

1458

1455

foreach my $arg (split($splitter, $args)) {

1459

foreach my $arg (split($splitter, $args)) {

1456

# strip comments

1460

# strip comments

1457

$arg =~ s/\/\*.*\*\///;

1461

$arg =~ s/\/\*.*\*\///;

1458

# strip leading/trailing spaces

1462

# strip leading/trailing spaces

1459

$arg =~ s/^\s*//;

1463

$arg =~ s/^\s*//;

1460

$arg =~ s/\s*$//;

1464

$arg =~ s/\s*$//;

1461

$arg =~ s/\s+/ /;

1465

$arg =~ s/\s+/ /;

1462

1466

1463

if ($arg =~ /^#/) {

1467

if ($arg =~ /^#/) {

1464

# Treat preprocessor directive as a typeless variable just to fill

1468

# Treat preprocessor directive as a typeless variable just to fill

1465

# corresponding data structures "correctly". Catch it later in

1469

# corresponding data structures "correctly". Catch it later in

1466

# output_* subs.

1470

# output_* subs.

1467

push_parameter($arg, "", $file);

1471

push_parameter($arg, "", $file);

1468

} elsif ($arg =~ m/\(.*\*/) {

1472

} elsif ($arg =~ m/\(.*\*/) {

1469

# pointer-to-function

1473

# pointer-to-function

1470

$arg =~ tr/#/,/;

1474

$arg =~ tr/#/,/;

1471

$arg =~ m/[^$]+\(\*\s*([^$]+)\)/;

1475

$arg =~ m/[^$]+\(\*\s*([^$]+)\)/;

1472

$param = $1;

1476

$param = $1;

1473

$type = $arg;

1477

$type = $arg;

1474

$type =~ s/([^\(]+\(\*)$param/$1/;

1478

$type =~ s/([^\(]+\(\*)$param/$1/;

1475

push_parameter($param, $type, $file);

1479

push_parameter($param, $type, $file);

1476

} elsif ($arg) {

1480

} elsif ($arg) {

1477

$arg =~ s/\s*:\s*/:/g;

1481

$arg =~ s/\s*:\s*/:/g;

1478

$arg =~ s/\s*\[/\[/g;

1482

$arg =~ s/\s*\[/\[/g;

1479

1483

1480

my @args = split('\s*,\s*', $arg);

1484

my @args = split('\s*,\s*', $arg);

1481

if ($args[0] =~ m/\*/) {

1485

if ($args[0] =~ m/\*/) {

1482

$args[0] =~ s/(\*+)\s*/ $1/;

1486

$args[0] =~ s/(\*+)\s*/ $1/;

1483

}

1487

}

1484

1488

1485

my @first_arg;

1489

my @first_arg;

1486

if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {

1490

if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {

1487

shift @args;

1491

shift @args;

1488

push(@first_arg, split('\s+', $1));

1492

push(@first_arg, split('\s+', $1));

1489

push(@first_arg, $2);

1493

push(@first_arg, $2);

1490

} else {

1494

} else {

1491

@first_arg = split('\s+', shift @args);

1495

@first_arg = split('\s+', shift @args);

1492

}

1496

}

1493

1497

1494

unshift(@args, pop @first_arg);

1498

unshift(@args, pop @first_arg);

1495

$type = join " ", @first_arg;

1499

$type = join " ", @first_arg;

1496

1500

1497

foreach $param (@args) {

1501

foreach $param (@args) {

1498

if ($param =~ m/^(\*+)\s*(.*)/) {

1502

if ($param =~ m/^(\*+)\s*(.*)/) {

1499

push_parameter($2, "$type $1", $file);

1503

push_parameter($2, "$type $1", $file);

1500

}

1504

}

1501

elsif ($param =~ m/(.*?):(\d+)/) {

1505

elsif ($param =~ m/(.*?):(\d+)/) {

1502

push_parameter($1, "$type:$2", $file)

1506

push_parameter($1, "$type:$2", $file)

1503

}

1507

}

1504

else {

1508

else {

1505

push_parameter($param, $type, $file);

1509

push_parameter($param, $type, $file);

1506

}

1510

}

1507

}

1511

}

1508

}

1512

}

1509

}

1513

}

1510

}

1514

}

1511

1515

1512

sub push_parameter($$$) {

1516

sub push_parameter($$$) {

1513

my $param = shift;

1517

my $param = shift;

1514

my $type = shift;

1518

my $type = shift;

1515

my $file = shift;

1519

my $file = shift;

1516

1520

1517

if (($anon_struct_union == 1) && ($type eq "") &&

1521

if (($anon_struct_union == 1) && ($type eq "") &&

1518

($param eq "}")) {

1522

($param eq "}")) {

1519

return; # ignore the ending }; from anon. struct/union

1523

return; # ignore the ending }; from anon. struct/union

1520

}

1524

}

1521

1525

1522

$anon_struct_union = 0;

1526

$anon_struct_union = 0;

1523

my $param_name = $param;

1527

my $param_name = $param;

1524

$param_name =~ s/\[.*//;

1528

$param_name =~ s/\[.*//;

1525

1529

1526

if ($type eq "" && $param =~ /\.\.\.$/)

1530

if ($type eq "" && $param =~ /\.\.\.$/)

1527

{

1531

{

1528

$type="";

1532

$type="";

1529

$parameterdescs{$param} = "variable arguments";

1533

$parameterdescs{$param} = "variable arguments";

1530

}

1534

}

1531

elsif ($type eq "" && ($param eq "" or $param eq "void"))

1535

elsif ($type eq "" && ($param eq "" or $param eq "void"))

1532

{

1536

{

1533

$type="";

1537

$type="";

1534

$param="void";

1538

$param="void";

1535

$parameterdescs{void} = "no arguments";

1539

$parameterdescs{void} = "no arguments";

1536

}

1540

}

1537

elsif ($type eq "" && ($param eq "struct" or $param eq "union"))

1541

elsif ($type eq "" && ($param eq "struct" or $param eq "union"))

1538

# handle unnamed (anonymous) union or struct:

1542

# handle unnamed (anonymous) union or struct:

1539

{

1543

{

1540

$type = $param;

1544

$type = $param;

1541

$param = "{unnamed_" . $param . "}";

1545

$param = "{unnamed_" . $param . "}";

1542

$parameterdescs{$param} = "anonymous\n";

1546

$parameterdescs{$param} = "anonymous\n";

1543

$anon_struct_union = 1;

1547

$anon_struct_union = 1;

1544

}

1548

}

1545

1549

1546

# warn if parameter has no description

1550

# warn if parameter has no description

1547

# (but ignore ones starting with # as these are not parameters

1551

# (but ignore ones starting with # as these are not parameters

1548

# but inline preprocessor statements);

1552

# but inline preprocessor statements);

1549

# also ignore unnamed structs/unions;

1553

# also ignore unnamed structs/unions;

1550

if (!$anon_struct_union) {

1554

if (!$anon_struct_union) {

1551

if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {

1555

if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {

1552

1556

1553

$parameterdescs{$param_name} = $undescribed;

1557

$parameterdescs{$param_name} = $undescribed;

1554

1558

1555

if (($type eq 'function') || ($type eq 'enum')) {

1559

if (($type eq 'function') || ($type eq 'enum')) {

1556

print STDERR "Warning(${file}:$.): Function parameter ".

1560

print STDERR "Warning(${file}:$.): Function parameter ".

1557

"or member '$param' not " .

1561

"or member '$param' not " .

1558

"described in '$declaration_name'\n";

1562

"described in '$declaration_name'\n";

1559

}

1563

}

1560

print STDERR "Warning(${file}:$.):".

1564

print STDERR "Warning(${file}:$.):".

1561

" No description found for parameter '$param'\n";

1565

" No description found for parameter '$param'\n";

1562

++$warnings;

1566

++$warnings;

1563

}

1567

}

1564

}

1568

}

1565

1569

1566

push @parameterlist, $param;

1570

push @parameterlist, $param;

1567

$parametertypes{$param} = $type;

1571

$parametertypes{$param} = $type;

1568

}

1572

}

1569

1573

1570

##

1574

##

1571

# takes a function prototype and the name of the current file being

1575

# takes a function prototype and the name of the current file being

1572

# processed and spits out all the details stored in the global

1576

# processed and spits out all the details stored in the global

1573

# arrays/hashes.

1577

# arrays/hashes.

1574

sub dump_function($$) {

1578

sub dump_function($$) {

1575

my $prototype = shift;

1579

my $prototype = shift;

1576

my $file = shift;

1580

my $file = shift;

1577

1581

1578

$prototype =~ s/^static +//;

1582

$prototype =~ s/^static +//;

1579

$prototype =~ s/^extern +//;

1583

$prototype =~ s/^extern +//;

1580

$prototype =~ s/^fastcall +//;

1584

$prototype =~ s/^fastcall +//;

1581

$prototype =~ s/^asmlinkage +//;

1585

$prototype =~ s/^asmlinkage +//;

1582

$prototype =~ s/^inline +//;

1586

$prototype =~ s/^inline +//;

1583

$prototype =~ s/^__inline__ +//;

1587

$prototype =~ s/^__inline__ +//;

1584

$prototype =~ s/^__inline +//;

1588

$prototype =~ s/^__inline +//;

1585

$prototype =~ s/^__always_inline +//;

1589

$prototype =~ s/^__always_inline +//;

1586

$prototype =~ s/^noinline +//;

1590

$prototype =~ s/^noinline +//;

1587

$prototype =~ s/__devinit +//;

1591

$prototype =~ s/__devinit +//;

1588

$prototype =~ s/^#define\s+//; #ak added

1592

$prototype =~ s/^#define\s+//; #ak added

1589

$prototype =~ s/__attribute__\s*$\([a-z,]*$\)//;

1593

$prototype =~ s/__attribute__\s*$\([a-z,]*$\)//;

1590

1594

1591

# Yes, this truly is vile. We are looking for:

1595

# Yes, this truly is vile. We are looking for:

1592

# 1. Return type (may be nothing if we're looking at a macro)

1596

# 1. Return type (may be nothing if we're looking at a macro)

1593

# 2. Function name

1597

# 2. Function name

1594

# 3. Function parameters.

1598

# 3. Function parameters.

1595

#

1599

#

1596

# All the while we have to watch out for function pointer parameters

1600

# All the while we have to watch out for function pointer parameters

1597

# (which IIRC is what the two sections are for), C types (these

1601

# (which IIRC is what the two sections are for), C types (these

1598

# regexps don't even start to express all the possibilities), and

1602

# regexps don't even start to express all the possibilities), and

1599

# so on.

1603

# so on.

1600

#

1604

#

1601

# If you mess with these regexps, it's a good idea to check that

1605

# If you mess with these regexps, it's a good idea to check that

1602

# the following functions' documentation still comes out right:

1606

# the following functions' documentation still comes out right:

1603

# - parport_register_device (function pointer parameters)

1607

# - parport_register_device (function pointer parameters)

1604

# - atomic_set (macro)

1608

# - atomic_set (macro)

1605

# - pci_match_device, __copy_to_user (long return type)

1609

# - pci_match_device, __copy_to_user (long return type)

1606

1610

1607

if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1611

if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1608

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1612

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1609

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1613

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1610

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1614

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1611

$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1615

$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1612

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1616

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1613

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1617

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1614

$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1618

$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1615

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1619

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1616

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1620

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1617

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1621

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1618

$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1622

$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1619

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1623

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1620

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1624

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1621

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1625

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1622

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1626

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1623

$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/) {

1627

$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/) {

1624

$return_type = $1;

1628

$return_type = $1;

1625

$declaration_name = $2;

1629

$declaration_name = $2;

1626

my $args = $3;

1630

my $args = $3;

1627

1631

1628

create_parameterlist($args, ',', $file);

1632

create_parameterlist($args, ',', $file);

1629

} else {

1633

} else {

1630

print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";

1634

print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";

1631

++$errors;

1635

++$errors;

1632

return;

1636

return;

1633

}

1637

}

1634

1638

1635

output_declaration($declaration_name,

1639

output_declaration($declaration_name,

1636

'function',

1640

'function',

1637

{'function' => $declaration_name,

1641

{'function' => $declaration_name,

1638

'module' => $modulename,

1642

'module' => $modulename,

1639

'functiontype' => $return_type,

1643

'functiontype' => $return_type,

1640

'parameterlist' => \@parameterlist,

1644

'parameterlist' => \@parameterlist,

1641

'parameterdescs' => \%parameterdescs,

1645

'parameterdescs' => \%parameterdescs,

1642

'parametertypes' => \%parametertypes,

1646

'parametertypes' => \%parametertypes,

1643

'sectionlist' => \@sectionlist,

1647

'sectionlist' => \@sectionlist,

1644

'sections' => \%sections,

1648

'sections' => \%sections,

1645

'purpose' => $declaration_purpose

1649

'purpose' => $declaration_purpose

1646

});

1650

});

1647

}

1651

}

1648

1652

1649

sub process_file($);

1653

sub process_file($);

1650

1654

1651

# Read the file that maps relative names to absolute names for

1655

# Read the file that maps relative names to absolute names for

1652

# separate source and object directories and for shadow trees.

1656

# separate source and object directories and for shadow trees.

1653

if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {

1657

if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {

1654

my ($relname, $absname);

1658

my ($relname, $absname);

1655

while(<SOURCE_MAP>) {

1659

while(<SOURCE_MAP>) {

1656

chop();

1660

chop();

1657

($relname, $absname) = (split())[0..1];

1661

($relname, $absname) = (split())[0..1];

1658

$relname =~ s:^/+::;

1662

$relname =~ s:^/+::;

1659

$source_map{$relname} = $absname;

1663

$source_map{$relname} = $absname;

1660

}

1664

}

1661

close(SOURCE_MAP);

1665

close(SOURCE_MAP);

1662

}

1666

}

1663

1667

1664

if ($filelist) {

1668

if ($filelist) {

1665

open(FLIST,"<$filelist") or die "Can't open file list $filelist";

1669

open(FLIST,"<$filelist") or die "Can't open file list $filelist";

1666

while(<FLIST>) {

1670

while(<FLIST>) {

1667

chop;

1671

chop;

1668

process_file($_);

1672

process_file($_);

1669

}

1673

}

1670

}

1674

}

1671

1675

1672

foreach (@ARGV) {

1676

foreach (@ARGV) {

1673

chomp;

1677

chomp;

1674

process_file($_);

1678

process_file($_);

1675

}

1679

}

1676

if ($verbose && $errors) {

1680

if ($verbose && $errors) {

1677

print STDERR "$errors errors\n";

1681

print STDERR "$errors errors\n";

1678

}

1682

}

1679

if ($verbose && $warnings) {

1683

if ($verbose && $warnings) {

1680

print STDERR "$warnings warnings\n";

1684

print STDERR "$warnings warnings\n";

1681

}

1685

}

1682

1686

1683

exit($errors);

1687

exit($errors);

1684

1688

1685

sub reset_state {

1689

sub reset_state {

1686

$function = "";

1690

$function = "";

1687

%constants = ();

1691

%constants = ();

1688

%parameterdescs = ();

1692

%parameterdescs = ();

1689

%parametertypes = ();

1693

%parametertypes = ();

1690

@parameterlist = ();

1694

@parameterlist = ();

1691

%sections = ();

1695

%sections = ();

1692

@sectionlist = ();

1696

@sectionlist = ();

1693

$prototype = "";

1697

$prototype = "";

1694

1698

1695

$state = 0;

1699

$state = 0;

1696

}

1700

}

1697

1701

1698

sub process_state3_function($$) {

1702

sub process_state3_function($$) {

1699

my $x = shift;

1703

my $x = shift;

1700

my $file = shift;

1704

my $file = shift;

1701

1705

1702

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1706

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1703

1707

1704

if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {

1708

if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {

1705

# do nothing

1709

# do nothing

1706

}

1710

}

1707

elsif ($x =~ /([^\{]*)/) {

1711

elsif ($x =~ /([^\{]*)/) {

1708

$prototype .= $1;

1712

$prototype .= $1;

1709

}

1713

}

1710

if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {

1714

if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {

1711

$prototype =~ s@/\*.*?\*/@@gos; # strip comments.

1715

$prototype =~ s@/\*.*?\*/@@gos; # strip comments.

1712

$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1716

$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1713

$prototype =~ s@^\s+@@gos; # strip leading spaces

1717

$prototype =~ s@^\s+@@gos; # strip leading spaces

1714

dump_function($prototype,$file);

1718

dump_function($prototype,$file);

1715

reset_state();

1719

reset_state();

1716

}

1720

}

1717

}

1721

}

1718

1722

1719

sub process_state3_type($$) {

1723

sub process_state3_type($$) {

1720

my $x = shift;

1724

my $x = shift;

1721

my $file = shift;

1725

my $file = shift;

1722

1726

1723

$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1727

$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1724

$x =~ s@^\s+@@gos; # strip leading spaces

1728

$x =~ s@^\s+@@gos; # strip leading spaces

1725

$x =~ s@\s+$@@gos; # strip trailing spaces

1729

$x =~ s@\s+$@@gos; # strip trailing spaces

1726

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1730

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1727

1731

1728

if ($x =~ /^#/) {

1732

if ($x =~ /^#/) {

1729

# To distinguish preprocessor directive from regular declaration later.

1733

# To distinguish preprocessor directive from regular declaration later.

1730

$x .= ";";

1734

$x .= ";";

1731

}

1735

}

1732

1736

1733

while (1) {

1737

while (1) {

1734

if ( $x =~ /([^{};]*)([{};])(.*)/ ) {

1738

if ( $x =~ /([^{};]*)([{};])(.*)/ ) {

1735

$prototype .= $1 . $2;

1739

$prototype .= $1 . $2;

1736

($2 eq '{') && $brcount++;

1740

($2 eq '{') && $brcount++;

1737

($2 eq '}') && $brcount--;

1741

($2 eq '}') && $brcount--;

1738

if (($2 eq ';') && ($brcount == 0)) {

1742

if (($2 eq ';') && ($brcount == 0)) {

1739

dump_declaration($prototype,$file);

1743

dump_declaration($prototype,$file);

1740

reset_state();

1744

reset_state();

1741

last;

1745

last;

1742

}

1746

}

1743

$x = $3;

1747

$x = $3;

1744

} else {

1748

} else {

1745

$prototype .= $x;

1749

$prototype .= $x;

1746

last;

1750

last;

1747

}

1751

}

1748

}

1752

}

1749

}

1753

}

1750

1754

1751

# replace <, >, and &

1755

# replace <, >, and &

1752

sub xml_escape($) {

1756

sub xml_escape($) {

1753

my $text = shift;

1757

my $text = shift;

1754

if (($output_mode eq "text") || ($output_mode eq "man")) {

1758

if (($output_mode eq "text") || ($output_mode eq "man")) {

1755

return $text;

1759

return $text;

1756

}

1760

}

1757

$text =~ s/\&/\\\\\\amp;/g;

1761

$text =~ s/\&/\\\\\\amp;/g;

1758

$text =~ s/\</\\\\\\lt;/g;

1762

$text =~ s/\</\\\\\\lt;/g;

1759

$text =~ s/\>/\\\\\\gt;/g;

1763

$text =~ s/\>/\\\\\\gt;/g;

1760

return $text;

1764

return $text;

1761

}

1765

}

1762

1766

1763

sub process_file($) {

1767

sub process_file($) {

1764

my $file;

1768

my $file;

1765

my $identifier;

1769

my $identifier;

1766

my $func;

1770

my $func;

1767

my $descr;

1771

my $descr;

1768

my $initial_section_counter = $section_counter;

1772

my $initial_section_counter = $section_counter;

1769

1773

1770

if (defined($ENV{'SRCTREE'})) {

1774

if (defined($ENV{'SRCTREE'})) {

1771

$file = "$ENV{'SRCTREE'}" . "/" . "@_";

1775

$file = "$ENV{'SRCTREE'}" . "/" . "@_";

1772

}

1776

}

1773

else {

1777

else {

1774

$file = "@_";

1778

$file = "@_";

1775

}

1779

}

1776

if (defined($source_map{$file})) {

1780

if (defined($source_map{$file})) {

1777

$file = $source_map{$file};

1781

$file = $source_map{$file};

1778

}

1782

}

1779

1783

1780

if (!open(IN,"<$file")) {

1784

if (!open(IN,"<$file")) {

1781

print STDERR "Error: Cannot open file $file\n";

1785

print STDERR "Error: Cannot open file $file\n";

1782

++$errors;

1786

++$errors;

1783

return;

1787

return;

1784

}

1788

}

1785

1789

1786

$section_counter = 0;

1790

$section_counter = 0;

1787

while (<IN>) {

1791

while (<IN>) {

1788

if ($state == 0) {

1792

if ($state == 0) {

1789

if (/$doc_start/o) {

1793

if (/$doc_start/o) {

1790

$state = 1; # next line is always the function name

1794

$state = 1; # next line is always the function name

1791

$in_doc_sect = 0;

1795

$in_doc_sect = 0;

1792

}

1796

}

1793

} elsif ($state == 1) { # this line is the function name (always)

1797

} elsif ($state == 1) { # this line is the function name (always)

1794

if (/$doc_block/o) {

1798

if (/$doc_block/o) {

1795

$state = 4;

1799

$state = 4;

1796

$contents = "";

1800

$contents = "";

1797

if ( $1 eq "" ) {

1801

if ( $1 eq "" ) {

1798

$section = $section_intro;

1802

$section = $section_intro;

1799

} else {

1803

} else {

1800

$section = $1;

1804

$section = $1;

1801

}

1805

}

1802

}

1806

}

1803

elsif (/$doc_decl/o) {

1807

elsif (/$doc_decl/o) {

1804

$identifier = $1;

1808

$identifier = $1;

1805

if (/\s*([\w\s]+?)\s*-/) {

1809

if (/\s*([\w\s]+?)\s*-/) {

1806

$identifier = $1;

1810

$identifier = $1;

1807

}

1811

}

1808

1812

1809

$state = 2;

1813

$state = 2;

1810

if (/-(.*)/) {

1814

if (/-(.*)/) {

1811

# strip leading/trailing/multiple spaces

1815

# strip leading/trailing/multiple spaces

1812

$descr= $1;

1816

$descr= $1;

1813

$descr =~ s/^\s*//;

1817

$descr =~ s/^\s*//;

1814

$descr =~ s/\s*$//;

1818

$descr =~ s/\s*$//;

1815

$descr =~ s/\s+/ /;

1819

$descr =~ s/\s+/ /;

1816

$declaration_purpose = xml_escape($descr);

1820

$declaration_purpose = xml_escape($descr);

1817

} else {

1821

} else {

1818

$declaration_purpose = "";

1822

$declaration_purpose = "";

1819

}

1823

}

1820

if ($identifier =~ m/^struct/) {

1824

if ($identifier =~ m/^struct/) {

1821

$decl_type = 'struct';

1825

$decl_type = 'struct';

1822

} elsif ($identifier =~ m/^union/) {

1826

} elsif ($identifier =~ m/^union/) {

1823

$decl_type = 'union';

1827

$decl_type = 'union';

1824

} elsif ($identifier =~ m/^enum/) {

1828

} elsif ($identifier =~ m/^enum/) {

1825

$decl_type = 'enum';

1829

$decl_type = 'enum';

1826

} elsif ($identifier =~ m/^typedef/) {

1830

} elsif ($identifier =~ m/^typedef/) {

1827

$decl_type = 'typedef';

1831

$decl_type = 'typedef';

1828

} else {

1832

} else {

1829

$decl_type = 'function';

1833

$decl_type = 'function';

1830

}

1834

}

1831

1835

1832

if ($verbose) {

1836

if ($verbose) {

1833

print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";

1837

print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";

1834

}

1838

}

1835

} else {

1839

} else {

1836

print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",

1840

print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",

1837

" - I thought it was a doc line\n";

1841

" - I thought it was a doc line\n";

1838

++$warnings;

1842

++$warnings;

1839

$state = 0;

1843

$state = 0;

1840

}

1844

}

1841

} elsif ($state == 2) { # look for head: lines, and include content

1845

} elsif ($state == 2) { # look for head: lines, and include content

1842

if (/$doc_sect/o) {

1846

if (/$doc_sect/o) {

1843

$newsection = $1;

1847

$newsection = $1;

1844

$newcontents = $2;

1848

$newcontents = $2;

1845

1849

1846

if ($contents ne "") {

1850

if ($contents ne "") {

1847

if (!$in_doc_sect && $verbose) {

1851

if (!$in_doc_sect && $verbose) {

1848

print STDERR "Warning(${file}:$.): contents before sections\n";

1852

print STDERR "Warning(${file}:$.): contents before sections\n";

1849

++$warnings;

1853

++$warnings;

1850

}

1854

}

1851

dump_section($section, xml_escape($contents));

1855

dump_section($section, xml_escape($contents));

1852

$section = $section_default;

1856

$section = $section_default;

1853

}

1857

}

1854

1858

1855

$in_doc_sect = 1;

1859

$in_doc_sect = 1;

1856

$contents = $newcontents;

1860

$contents = $newcontents;

1857

if ($contents ne "") {

1861

if ($contents ne "") {

1858

while ((substr($contents, 0, 1) eq " ") ||

1862

while ((substr($contents, 0, 1) eq " ") ||

1859

substr($contents, 0, 1) eq "\t") {

1863

substr($contents, 0, 1) eq "\t") {

1860

$contents = substr($contents, 1);

1864

$contents = substr($contents, 1);

1861

}

1865

}

1862

$contents .= "\n";

1866

$contents .= "\n";

1863

}

1867

}

1864

$section = $newsection;

1868

$section = $newsection;

1865

} elsif (/$doc_end/) {

1869

} elsif (/$doc_end/) {

1866

1870

1867

if ($contents ne "") {

1871

if ($contents ne "") {

1868

dump_section($section, xml_escape($contents));

1872

dump_section($section, xml_escape($contents));

1869

$section = $section_default;

1873

$section = $section_default;

1870

$contents = "";

1874

$contents = "";

1871

}

1875

}

1872

1876

1873

$prototype = "";

1877

$prototype = "";

1874

$state = 3;

1878

$state = 3;

1875

$brcount = 0;

1879

$brcount = 0;

1876

# print STDERR "end of doc comment, looking for prototype\n";

1880

# print STDERR "end of doc comment, looking for prototype\n";

1877

} elsif (/$doc_content/) {

1881

} elsif (/$doc_content/) {

1878

# miguel-style comment kludge, look for blank lines after

1882

# miguel-style comment kludge, look for blank lines after

1879

# @parameter line to signify start of description

1883

# @parameter line to signify start of description

1880

if ($1 eq "" &&

1884

if ($1 eq "" &&

1881

($section =~ m/^@/ || $section eq $section_context)) {

1885

($section =~ m/^@/ || $section eq $section_context)) {

1882

dump_section($section, xml_escape($contents));

1886

dump_section($section, xml_escape($contents));

1883

$section = $section_default;

1887

$section = $section_default;

1884

$contents = "";

1888

$contents = "";

1885

} else {

1889

} else {

1886

$contents .= $1."\n";

1890

$contents .= $1."\n";

1887

}

1891

}

1888

} else {

1892

} else {

1889

# i dont know - bad line? ignore.

1893

# i dont know - bad line? ignore.

1890

print STDERR "Warning(${file}:$.): bad line: $_";

1894

print STDERR "Warning(${file}:$.): bad line: $_";

1891

++$warnings;

1895

++$warnings;

1892

}

1896

}

1893

} elsif ($state == 3) { # scanning for function '{' (end of prototype)

1897

} elsif ($state == 3) { # scanning for function '{' (end of prototype)

1894

if ($decl_type eq 'function') {

1898

if ($decl_type eq 'function') {

1895

process_state3_function($_, $file);

1899

process_state3_function($_, $file);

1896

} else {

1900

} else {

1897

process_state3_type($_, $file);

1901

process_state3_type($_, $file);

1898

}

1902

}

1899

} elsif ($state == 4) {

1903

} elsif ($state == 4) {

1900

# Documentation block

1904

# Documentation block

1901

if (/$doc_block/) {

1905

if (/$doc_block/) {

1902

dump_section($section, $contents);

1906

dump_section($section, $contents);

1903

output_intro({'sectionlist' => \@sectionlist,

1907

output_intro({'sectionlist' => \@sectionlist,

1904

'sections' => \%sections });

1908

'sections' => \%sections });

1905

$contents = "";

1909

$contents = "";

1906

$function = "";

1910

$function = "";

1907

%constants = ();

1911

%constants = ();

1908

%parameterdescs = ();

1912

%parameterdescs = ();

1909

%parametertypes = ();

1913

%parametertypes = ();

1910

@parameterlist = ();

1914

@parameterlist = ();

1911

%sections = ();

1915

%sections = ();

1912

@sectionlist = ();

1916

@sectionlist = ();

1913

$prototype = "";

1917

$prototype = "";

1914

if ( $1 eq "" ) {

1918

if ( $1 eq "" ) {

1915

$section = $section_intro;

1919

$section = $section_intro;

1916

} else {

1920

} else {

1917

$section = $1;

1921

$section = $1;

1918

}

1922

}

1919

}

1923

}

1920

elsif (/$doc_end/)

1924

elsif (/$doc_end/)

1921

{

1925

{

1922

dump_section($section, $contents);

1926

dump_section($section, $contents);

1923

output_intro({'sectionlist' => \@sectionlist,

1927

output_intro({'sectionlist' => \@sectionlist,

1924

'sections' => \%sections });

1928

'sections' => \%sections });

1925

$contents = "";

1929

$contents = "";

1926

$function = "";

1930

$function = "";

1927

%constants = ();

1931

%constants = ();

1928

%parameterdescs = ();

1932

%parameterdescs = ();

1929

%parametertypes = ();

1933

%parametertypes = ();

1930

@parameterlist = ();

1934

@parameterlist = ();

1931

%sections = ();

1935

%sections = ();

1932

@sectionlist = ();

1936

@sectionlist = ();

1933

$prototype = "";

1937

$prototype = "";

1934

$state = 0;

1938

$state = 0;

1935

}

1939

}

1936

elsif (/$doc_content/)

1940

elsif (/$doc_content/)

1937

{

1941

{

1938

if ( $1 eq "" )

1942

if ( $1 eq "" )

1939

{

1943

{

1940

$contents .= $blankline;

1944

$contents .= $blankline;

1941

}

1945

}

1942

else

1946

else

1943

{

1947

{

1944

$contents .= $1 . "\n";

1948

$contents .= $1 . "\n";

1945

}

1949

}

1946

}

1950

}

1947

}

1951

}

1948

}

1952

}

1949

if ($initial_section_counter == $section_counter) {

1953

if ($initial_section_counter == $section_counter) {

1950

print STDERR "Warning(${file}): no structured comments found\n";

1954

print STDERR "Warning(${file}): no structured comments found\n";

1951

if ($output_mode eq "xml") {

1955

if ($output_mode eq "xml") {

1952

# The template wants at least one RefEntry here; make one.

1956

# The template wants at least one RefEntry here; make one.

1953

print "<refentry>\n";

1957

print "<refentry>\n";

1954

print " <refnamediv>\n";

1958

print " <refnamediv>\n";

1955

print " <refname>\n";

1959

print " <refname>\n";

1956

print " ${file}\n";

1960

print " ${file}\n";

1957

print " </refname>\n";

1961

print " </refname>\n";

1958

print " <refpurpose>\n";

1962

print " <refpurpose>\n";

1959

print " Document generation inconsistency\n";

1963

print " Document generation inconsistency\n";

1960

print " </refpurpose>\n";

1964

print " </refpurpose>\n";

1961

print " </refnamediv>\n";

1965

print " </refnamediv>\n";

1962

print " <refsect1>\n";

1966

print " <refsect1>\n";

1963

print " <title>\n";

1967

print " <title>\n";

1964

print " Oops\n";

1968

print " Oops\n";

1965

print " </title>\n";

1969

print " </title>\n";

1966

print " <warning>\n";

1970

print " <warning>\n";

1967

print " <para>\n";

1971

print " <para>\n";

1968

print " The template for this document tried to insert\n";

1972

print " The template for this document tried to insert\n";

1969

print " the structured comment from the file\n";

1973

print " the structured comment from the file\n";

1970

print " <filename>${file}</filename> at this point,\n";

1974

print " <filename>${file}</filename> at this point,\n";

1971

print " but none was found.\n";

1975

print " but none was found.\n";

1972

print " This dummy section is inserted to allow\n";

1976

print " This dummy section is inserted to allow\n";

1973

print " generation to continue.\n";

1977

print " generation to continue.\n";

1974

print " </para>\n";

1978

print " </para>\n";

1975

print " </warning>\n";

1979

print " </warning>\n";

1976

print " </refsect1>\n";

1980

print " </refsect1>\n";

1977

print "</refentry>\n";

1981

print "</refentry>\n";

1978

}

1982

}

1979

}

1983

}

1980

}

1984

}

1981

1985

GITLAB

Eric Lee / linux-smarc-t335x-v3.2

kernel-doc: fix leading dot in man-mode output

 #!/usr/bin/perl -w
 use strict;
 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
 ## Copyright (C) 2001  Simon Huggins                             ##
 ## 								 ##
 ## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
 ## Copyright (c) 2000 MontaVista Software, Inc.			 ##
 ## 								 ##
 ## This software falls under the GNU General Public License.     ##
 ## Please read the COPYING file for more information             ##
 # w.o. 03-11-2000: added the '-filelist' option.
 # 18/01/2001 - 	Cleanups
 # 		Functions prototyped as foo(void) same as foo()
 # 		Stop eval'ing where we don't need to.
 # -- huggie@earth.li
 # 27/06/2001 -  Allowed whitespace after initial "/**" and
 #               allowed comments before function declarations.
 # -- Christian Kreibich <ck@whoop.org>
 # Still to do:
 # 	- add perldoc documentation
 # 	- Look more closely at some of the scarier bits :)
 # 26/05/2001 - 	Support for separate source and object trees.
 #		Return error code.
 # 		Keith Owens <kaos@ocs.com.au>
 # 23/09/2001 - Added support for typedefs, structs, enums and unions
 #              Support for Context section; can be terminated using empty line
 #              Small fixes (like spaces vs. \s in regex)
 # -- Tim Jansen <tim@tjansen.de>
 #
 # This will read a 'c' file and scan for embedded comments in the
 # style of gnome comments (+minor extensions - see below).
 #
 # Note: This only supports 'c'.
 # usage:
 # kernel-doc [ -docbook | -html | -text | -man ]
 #           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
 # or
 #           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
 #
 #  Set output format using one of -docbook -html -text or -man.  Default is man.
 #
 #  -function funcname
 #	If set, then only generate documentation for the given function(s).  All
 #	other functions are ignored.
 #
 #  -nofunction funcname
 #	If set, then only generate documentation for the other function(s).
 #	Cannot be used together with -function
 #	(yes, that's a bug -- perl hackers can fix it 8))
 #
 #  c files - list of 'c' files to process
 #
 #  All output goes to stdout, with errors to stderr.
 #
 # format of comments.
 # In the following table, (...)? signifies optional structure.
 #                         (...)* signifies 0 or more structure elements
 # /**
 #  * function_name(:)? (- short description)?
 # (* @parameterx: (description of parameter x)?)*
 # (* a blank line)?
 #  * (Description:)? (Description of function)?
 #  * (section header: (section description)? )*
 #  (*)?*/
 #
 # So .. the trivial example would be:
 #
 # /**
 #  * my_function
 #  **/
 #
 # If the Description: header tag is omitted, then there must be a blank line
 # after the last parameter specification.
 # e.g.
 # /**
 #  * my_function - does my stuff
 #  * @my_arg: its mine damnit
 #  *
 #  * Does my stuff explained.
 #  */
 #
 #  or, could also use:
 # /**
 #  * my_function - does my stuff
 #  * @my_arg: its mine damnit
 #  * Description: Does my stuff explained.
 #  */
 # etc.
 #
 # Beside functions you can also write documentation for structs, unions,
 # enums and typedefs. Instead of the function name you must write the name
 # of the declaration;  the struct/union/enum/typedef must always precede
 # the name. Nesting of declarations is not supported.
 # Use the argument mechanism to document members or constants.
 # e.g.
 # /**
 #  * struct my_struct - short description
 #  * @a: first member
 #  * @b: second member
 #  *
 #  * Longer description
 #  */
 # struct my_struct {
 #     int a;
 #     int b;
 # /* private: */
 #     int c;
 # };
 #
 # All descriptions can be multiline, except the short function description.
 #
 # You can also add additional sections. When documenting kernel functions you
 # should document the "Context:" of the function, e.g. whether the functions
 # can be called form interrupts. Unlike other sections you can end it with an
 # empty line.
 # Example-sections should contain the string EXAMPLE so that they are marked
 # appropriately in DocBook.
 #
 # Example:
 # /**
 #  * user_function - function that can only be called in user context
 #  * @a: some argument
 #  * Context: !in_interrupt()
 #  *
 #  * Some description
 #  * Example:
 #  *    user_function(22);
 #  */
 # ...
 #
 #
 # All descriptive text is further processed, scanning for the following special
 # patterns, which are highlighted appropriately.
 #
 # 'funcname()' - function
 # '$ENVVAR' - environmental variable
 # '&struct_name' - name of a structure (up to two words including 'struct')
 # '@parameter' - name of a parameter
 # '%CONST' - name of a constant.
 my $errors = 0;
 my $warnings = 0;
 my $anon_struct_union = 0;
 # match expressions used to find embedded type information
 my $type_constant = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w+)';
 my $type_struct = '\&((struct\s*)*[_\w]+)';
 my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
 # Output conversion substitutions.
 #  One for each output format
 # these work fairly well
 my %highlights_html = ( $type_constant, "<i>\$1</i>",
 			$type_func, "<b>\$1</b>",
 			$type_struct_xml, "<i>\$1</i>",
 			$type_env, "<b><i>\$1</i></b>",
 			$type_param, "<tt><b>\$1</b></tt>" );
 my $blankline_html = "<p>";
 # XML, docbook format
 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
 			$type_constant, "<constant>\$1</constant>",
 			$type_func, "<function>\$1</function>",
 			$type_struct, "<structname>\$1</structname>",
 			$type_env, "<envar>\$1</envar>",
 			$type_param, "<parameter>\$1</parameter>" );
 my $blankline_xml = "</para><para>\n";
 # gnome, docbook format
 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 			 $type_func, "<function>\$1</function>",
 			 $type_struct, "<structname>\$1</structname>",
 			 $type_env, "<envar>\$1</envar>",
 			 $type_param, "<parameter>\$1</parameter>" );
 my $blankline_gnome = "</para><para>\n";
 # these are pretty rough
 my %highlights_man = ( $type_constant, "\$1",
 		       $type_func, "\\\\fB\$1\\\\fP",
 		       $type_struct, "\\\\fI\$1\\\\fP",
 		       $type_param, "\\\\fI\$1\\\\fP" );
 my $blankline_man = "";
 # text-mode
 my %highlights_text = ( $type_constant, "\$1",
 			$type_func, "\$1",
 			$type_struct, "\$1",
 			$type_param, "\$1" );
 my $blankline_text = "";
 sub usage {
     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
     print "         [ -function funcname [ -function funcname ...] ]\n";
     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
     print "         c source file(s) > outputfile\n";
     exit 1;
 }
 # read arguments
 if ($#ARGV==-1) {
     usage();
 }
 my $verbose = 0;
 my $output_mode = "man";
 my %highlights = %highlights_man;
 my $blankline = $blankline_man;
 my $modulename = "Kernel API";
 my $function_only = 0;
 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 		'July', 'August', 'September', 'October',
 		'November', 'December')[(localtime)[4]] .
   " " . ((localtime)[5]+1900);
 # Essentially these are globals
 # They probably want to be tidied up made more localised or summat.
 # CAVEAT EMPTOR!  Some of the others I localised may not want to be which
 # could cause "use of undefined value" or other bugs.
 my ($function, %function_table,%parametertypes,$declaration_purpose);
 my ($type,$declaration_name,$return_type);
 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
 # Generated docbook code is inserted in a template at a point where
 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
 # We keep track of number of generated entries and generate a dummy
 # if needs be to ensure the expanded template can be postprocessed
 # into html.
 my $section_counter = 0;
 my $lineprefix="";
 # states
 # 0 - normal code
 # 1 - looking for function name
 # 2 - scanning field start.
 # 3 - scanning prototype.
 # 4 - documentation block
 my $state;
 my $in_doc_sect;
 #declaration types: can be
 # 'function', 'struct', 'union', 'enum', 'typedef'
 my $decl_type;
 my $doc_special = "\@\%\$\&";
 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_decl = $doc_com.'(\w+)';
 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
 my $doc_content = $doc_com.'(.*)';
 my $doc_block = $doc_com.'DOC:\s*(.*)?';
 my %constants;
 my %parameterdescs;
 my @parameterlist;
 my %sections;
 my @sectionlist;
 my $contents = "";
 my $section_default = "Description";	# default section
 my $section_intro = "Introduction";
 my $section = $section_default;
 my $section_context = "Context";
 my $undescribed = "-- undescribed --";
 reset_state();
 while ($ARGV[0] =~ m/^-(.*)/) {
     my $cmd = shift @ARGV;
     if ($cmd eq "-html") {
 	$output_mode = "html";
 	%highlights = %highlights_html;
 	$blankline = $blankline_html;
     } elsif ($cmd eq "-man") {
 	$output_mode = "man";
 	%highlights = %highlights_man;
 	$blankline = $blankline_man;
     } elsif ($cmd eq "-text") {
 	$output_mode = "text";
 	%highlights = %highlights_text;
 	$blankline = $blankline_text;
     } elsif ($cmd eq "-docbook") {
 	$output_mode = "xml";
 	%highlights = %highlights_xml;
 	$blankline = $blankline_xml;
     } elsif ($cmd eq "-gnome") {
 	$output_mode = "gnome";
 	%highlights = %highlights_gnome;
 	$blankline = $blankline_gnome;
     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
 	$modulename = shift @ARGV;
     } elsif ($cmd eq "-function") { # to only output specific functions
 	$function_only = 1;
 	$function = shift @ARGV;
 	$function_table{$function} = 1;
     } elsif ($cmd eq "-nofunction") { # to only output specific functions
 	$function_only = 2;
 	$function = shift @ARGV;
 	$function_table{$function} = 1;
     } elsif ($cmd eq "-v") {
 	$verbose = 1;
     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 	usage();
     } elsif ($cmd eq '-filelist') {
 	    $filelist = shift @ARGV;
     }
 }
 # get kernel version from env
 sub get_kernel_version() {
     my $version;
     if (defined($ENV{'KERNELVERSION'})) {
 	$version = $ENV{'KERNELVERSION'};
     }
     return $version;
 }
 my $kernelversion = get_kernel_version();
 # generate a sequence of code that will splice in highlighting information
 # using the s// operator.
 my $dohighlight = "";
 foreach my $pattern (keys %highlights) {
 #   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
 }
 ##
 # dumps section contents to arrays/hashes intended for that purpose.
 #
 sub dump_section {
     my $name = shift;
     my $contents = join "\n", @_;
     if ($name =~ m/$type_constant/) {
 	$name = $1;
 #	print STDERR "constant section '$1' = '$contents'\n";
 	$constants{$name} = $contents;
     } elsif ($name =~ m/$type_param/) {
 #	print STDERR "parameter def '$1' = '$contents'\n";
 	$name = $1;
 	$parameterdescs{$name} = $contents;
     } else {
 #	print STDERR "other section '$name' = '$contents'\n";
 	$sections{$name} = $contents;
 	push @sectionlist, $name;
     }
 }
 ##
 # output function
 #
 # parameterdescs, a hash.
 #  function => "function name"
 #  parameterlist => @list of parameters
 #  parameterdescs => %parameter descriptions
 #  sectionlist => @list of sections
 #  sections => %section descriptions
 #
 sub output_highlight {
     my $contents = join "\n",@_;
     my $line;
 #   DEBUG
 #   if (!defined $contents) {
 #	use Carp;
 #	confess "output_highlight got called with no args?\n";
 #   }
 #   print STDERR "contents b4:$contents\n";
     eval $dohighlight;
     die $@ if $@;
     if ($output_mode eq "html") {
 	$contents =~ s/\\\\//;
     }
 #   print STDERR "contents af:$contents\n";
     foreach $line (split "\n", $contents) {
 	if ($line eq ""){
 	    print $lineprefix, $blankline;
 	} else {
 	    $line =~ s/\\\\\\/\&/g;
-	    print $lineprefix, $line;
+	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
+		print "\\&$line";
+	    } else {
+		print $lineprefix, $line;
+	    }
 	}
 	print "\n";
     }
 }
 #output sections in html
 sub output_section_html(%) {
     my %args = %{$_[0]};
     my $section;
     foreach $section (@{$args{'sectionlist'}}) {
 	print "<h3>$section</h3>\n";
 	print "<blockquote>\n";
 	output_highlight($args{'sections'}{$section});
 	print "</blockquote>\n";
     }
 }
 # output enum in html
 sub output_enum_html(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $count;
     print "<h2>enum ".$args{'enum'}."</h2>\n";
     print "<b>enum ".$args{'enum'}."</b> {<br>\n";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print " <b>".$parameter."</b>";
 	if ($count != $#{$args{'parameterlist'}}) {
 	    $count++;
 	    print ",\n";
 	}
 	print "<br>";
     }
     print "};<br>\n";
     print "<h3>Constants</h3>\n";
     print "<dl>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print "<dt><b>".$parameter."</b>\n";
 	print "<dd>";
 	output_highlight($args{'parameterdescs'}{$parameter});
     }
     print "</dl>\n";
     output_section_html(@_);
     print "<hr>\n";
 }
 # output typedef in html
 sub output_typedef_html(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $count;
     print "<h2>typedef ".$args{'typedef'}."</h2>\n";
     print "<b>typedef ".$args{'typedef'}."</b>\n";
     output_section_html(@_);
     print "<hr>\n";
 }
 # output struct in html
 sub output_struct_html(%) {
     my %args = %{$_[0]};
     my ($parameter);
     print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	if ($parameter =~ /^#/) {
 		print "$parameter<br>\n";
 		next;
 	}
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
 	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 	    # bitfield
 	    print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
 	} else {
 	    print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
 	}
     }
     print "};<br>\n";
     print "<h3>Members</h3>\n";
     print "<dl>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	($parameter =~ /^#/) && next;
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print "<dt><b>".$parameter."</b>\n";
 	print "<dd>";
 	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     print "</dl>\n";
     output_section_html(@_);
     print "<hr>\n";
 }
 # output function in html
 sub output_function_html(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
     print "<i>".$args{'functiontype'}."</i>\n";
     print "<b>".$args{'function'}."</b>\n";
     print "(";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
 	} else {
 	    print "<i>".$type."</i> <b>".$parameter."</b>";
 	}
 	if ($count != $#{$args{'parameterlist'}}) {
 	    $count++;
 	    print ",\n";
 	}
     }
     print ")\n";
     print "<h3>Arguments</h3>\n";
     print "<dl>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print "<dt><b>".$parameter."</b>\n";
 	print "<dd>";
 	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     print "</dl>\n";
     output_section_html(@_);
     print "<hr>\n";
 }
 # output intro in html
 sub output_intro_html(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     foreach $section (@{$args{'sectionlist'}}) {
 	print "<h3>$section</h3>\n";
 	print "<ul>\n";
 	output_highlight($args{'sections'}{$section});
 	print "</ul>\n";
     }
     print "<hr>\n";
 }
 sub output_section_xml(%) {
     my %args = %{$_[0]};
     my $section;
     # print out each section
     $lineprefix="   ";
     foreach $section (@{$args{'sectionlist'}}) {
 	print "<refsect1>\n";
 	print "<title>$section</title>\n";
 	if ($section =~ m/EXAMPLE/i) {
 	    print "<informalexample><programlisting>\n";
 	} else {
 	    print "<para>\n";
 	}
 	output_highlight($args{'sections'}{$section});
 	if ($section =~ m/EXAMPLE/i) {
 	    print "</programlisting></informalexample>\n";
 	} else {
 	    print "</para>\n";
 	}
 	print "</refsect1>\n";
     }
 }
 # output function in XML DocBook
 sub output_function_xml(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     my $id;
     $id = "API-".$args{'function'};
     $id =~ s/[^A-Za-z0-9]/-/g;
     print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
     print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>".$args{'function'}."</refname>\n";
     print " <refpurpose>\n";
     print "  ";
     output_highlight ($args{'purpose'});
     print " </refpurpose>\n";
     print "</refnamediv>\n";
     print "<refsynopsisdiv>\n";
     print " <title>Synopsis</title>\n";
     print "  <funcsynopsis><funcprototype>\n";
     print "   <funcdef>".$args{'functiontype'}." ";
     print "<function>".$args{'function'}." </function></funcdef>\n";
     $count = 0;
     if ($#{$args{'parameterlist'}} >= 0) {
 	foreach $parameter (@{$args{'parameterlist'}}) {
 	    $type = $args{'parametertypes'}{$parameter};
 	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 		# pointer-to-function
 		print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
 		print "     <funcparams>$2</funcparams></paramdef>\n";
 	    } else {
 		print "   <paramdef>".$type;
 		print " <parameter>$parameter</parameter></paramdef>\n";
 	    }
 	}
     } else {
 	print "  <void/>\n";
     }
     print "  </funcprototype></funcsynopsis>\n";
     print "</refsynopsisdiv>\n";
     # print parameters
     print "<refsect1>\n <title>Arguments</title>\n";
     if ($#{$args{'parameterlist'}} >= 0) {
 	print " <variablelist>\n";
 	foreach $parameter (@{$args{'parameterlist'}}) {
 	    my $parameter_name = $parameter;
 	    $parameter_name =~ s/\[.*//;
 	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 	    print "   <listitem>\n    <para>\n";
 	    $lineprefix="     ";
 	    output_highlight($args{'parameterdescs'}{$parameter_name});
 	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
 	}
 	print " </variablelist>\n";
     } else {
 	print " <para>\n  None\n </para>\n";
     }
     print "</refsect1>\n";
     output_section_xml(@_);
     print "</refentry>\n\n";
 }
 # output struct in XML DocBook
 sub output_struct_xml(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $id;
     $id = "API-struct-".$args{'struct'};
     $id =~ s/[^A-Za-z0-9]/-/g;
     print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
     print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
     print " <refpurpose>\n";
     print "  ";
     output_highlight ($args{'purpose'});
     print " </refpurpose>\n";
     print "</refnamediv>\n";
     print "<refsynopsisdiv>\n";
     print " <title>Synopsis</title>\n";
     print "  <programlisting>\n";
     print $args{'type'}." ".$args{'struct'}." {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	if ($parameter =~ /^#/) {
 	    print "$parameter\n";
 	    next;
 	}
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	defined($args{'parameterdescs'}{$parameter_name}) || next;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print "  $1 $parameter) ($2);\n";
 	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 	    # bitfield
 	    print "  $1 $parameter$2;\n";
 	} else {
 	    print "  ".$type." ".$parameter.";\n";
 	}
     }
     print "};";
     print "  </programlisting>\n";
     print "</refsynopsisdiv>\n";
     print " <refsect1>\n";
     print "  <title>Members</title>\n";
     print "  <variablelist>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
       ($parameter =~ /^#/) && next;
       my $parameter_name = $parameter;
       $parameter_name =~ s/\[.*//;
       defined($args{'parameterdescs'}{$parameter_name}) || next;
       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
       print "    <varlistentry>";
       print "      <term>$parameter</term>\n";
       print "      <listitem><para>\n";
       output_highlight($args{'parameterdescs'}{$parameter_name});
       print "      </para></listitem>\n";
       print "    </varlistentry>\n";
     }
     print "  </variablelist>\n";
     print " </refsect1>\n";
     output_section_xml(@_);
     print "</refentry>\n\n";
 }
 # output enum in XML DocBook
 sub output_enum_xml(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     my $id;
     $id = "API-enum-".$args{'enum'};
     $id =~ s/[^A-Za-z0-9]/-/g;
     print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
     print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>enum ".$args{'enum'}."</refname>\n";
     print " <refpurpose>\n";
     print "  ";
     output_highlight ($args{'purpose'});
     print " </refpurpose>\n";
     print "</refnamediv>\n";
     print "<refsynopsisdiv>\n";
     print " <title>Synopsis</title>\n";
     print "  <programlisting>\n";
     print "enum ".$args{'enum'}." {\n";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print "  $parameter";
 	if ($count != $#{$args{'parameterlist'}}) {
 	    $count++;
 	    print ",";
 	}
 	print "\n";
     }
     print "};";
     print "  </programlisting>\n";
     print "</refsynopsisdiv>\n";
     print "<refsect1>\n";
     print " <title>Constants</title>\n";
     print "  <variablelist>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
       my $parameter_name = $parameter;
       $parameter_name =~ s/\[.*//;
       print "    <varlistentry>";
       print "      <term>$parameter</term>\n";
       print "      <listitem><para>\n";
       output_highlight($args{'parameterdescs'}{$parameter_name});
       print "      </para></listitem>\n";
       print "    </varlistentry>\n";
     }
     print "  </variablelist>\n";
     print "</refsect1>\n";
     output_section_xml(@_);
     print "</refentry>\n\n";
 }
 # output typedef in XML DocBook
 sub output_typedef_xml(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $id;
     $id = "API-typedef-".$args{'typedef'};
     $id =~ s/[^A-Za-z0-9]/-/g;
     print "<refentry id=\"$id\">\n";
     print "<refentryinfo>\n";
     print " <title>LINUX</title>\n";
     print " <productname>Kernel Hackers Manual</productname>\n";
     print " <date>$man_date</date>\n";
     print "</refentryinfo>\n";
     print "<refmeta>\n";
     print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
     print " <manvolnum>9</manvolnum>\n";
     print "</refmeta>\n";
     print "<refnamediv>\n";
     print " <refname>typedef ".$args{'typedef'}."</refname>\n";
     print " <refpurpose>\n";
     print "  ";
     output_highlight ($args{'purpose'});
     print " </refpurpose>\n";
     print "</refnamediv>\n";
     print "<refsynopsisdiv>\n";
     print " <title>Synopsis</title>\n";
     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
     print "</refsynopsisdiv>\n";
     output_section_xml(@_);
     print "</refentry>\n\n";
 }
 # output in XML DocBook
 sub output_intro_xml(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     my $id = $args{'module'};
     $id =~ s/[^A-Za-z0-9]/-/g;
     # print out each section
     $lineprefix="   ";
     foreach $section (@{$args{'sectionlist'}}) {
 	print "<refsect1>\n <title>$section</title>\n <para>\n";
 	if ($section =~ m/EXAMPLE/i) {
 	    print "<example><para>\n";
 	}
 	output_highlight($args{'sections'}{$section});
 	if ($section =~ m/EXAMPLE/i) {
 	    print "</para></example>\n";
 	}
 	print " </para>\n</refsect1>\n";
     }
     print "\n\n";
 }
 # output in XML DocBook
 sub output_function_gnome {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     my $id;
     $id = $args{'module'}."-".$args{'function'};
     $id =~ s/[^A-Za-z0-9]/-/g;
     print "<sect2>\n";
     print " <title id=\"$id\">".$args{'function'}."</title>\n";
     print "  <funcsynopsis>\n";
     print "   <funcdef>".$args{'functiontype'}." ";
     print "<function>".$args{'function'}." ";
     print "</function></funcdef>\n";
     $count = 0;
     if ($#{$args{'parameterlist'}} >= 0) {
 	foreach $parameter (@{$args{'parameterlist'}}) {
 	    $type = $args{'parametertypes'}{$parameter};
 	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 		# pointer-to-function
 		print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
 		print "     <funcparams>$2</funcparams></paramdef>\n";
 	    } else {
 		print "   <paramdef>".$type;
 		print " <parameter>$parameter</parameter></paramdef>\n";
 	    }
 	}
     } else {
 	print "  <void>\n";
     }
     print "  </funcsynopsis>\n";
     if ($#{$args{'parameterlist'}} >= 0) {
 	print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
 	print "<tgroup cols=\"2\">\n";
 	print "<colspec colwidth=\"2*\">\n";
 	print "<colspec colwidth=\"8*\">\n";
 	print "<tbody>\n";
 	foreach $parameter (@{$args{'parameterlist'}}) {
 	    my $parameter_name = $parameter;
 	    $parameter_name =~ s/\[.*//;
 	    print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
 	    print "   <entry>\n";
 	    $lineprefix="     ";
 	    output_highlight($args{'parameterdescs'}{$parameter_name});
 	    print "    </entry></row>\n";
 	}
 	print " </tbody></tgroup></informaltable>\n";
     } else {
 	print " <para>\n  None\n </para>\n";
     }
     # print out each section
     $lineprefix="   ";
     foreach $section (@{$args{'sectionlist'}}) {
 	print "<simplesect>\n <title>$section</title>\n";
 	if ($section =~ m/EXAMPLE/i) {
 	    print "<example><programlisting>\n";
 	} else {
 	}
 	print "<para>\n";
 	output_highlight($args{'sections'}{$section});
 	print "</para>\n";
 	if ($section =~ m/EXAMPLE/i) {
 	    print "</programlisting></example>\n";
 	} else {
 	}
 	print " </simplesect>\n";
     }
     print "</sect2>\n\n";
 }
 ##
 # output function in man
 sub output_function_man(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
     print ".SH NAME\n";
     print $args{'function'}." \\- ".$args{'purpose'}."\n";
     print ".SH SYNOPSIS\n";
     if ($args{'functiontype'} ne "") {
 	print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
     } else {
 	print ".B \"".$args{'function'}."\n";
     }
     $count = 0;
     my $parenth = "(";
     my $post = ",";
     foreach my $parameter (@{$args{'parameterlist'}}) {
 	if ($count == $#{$args{'parameterlist'}}) {
 	    $post = ");";
 	}
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
 	} else {
 	    $type =~ s/([^\*])$/$1 /;
 	    print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
 	}
 	$count++;
 	$parenth = "";
     }
     print ".SH ARGUMENTS\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	print ".IP \"".$parameter."\" 12\n";
 	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"", uc $section, "\"\n";
 	output_highlight($args{'sections'}{$section});
     }
 }
 ##
 # output enum in man
 sub output_enum_man(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
     print ".SH NAME\n";
     print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
     print ".SH SYNOPSIS\n";
     print "enum ".$args{'enum'}." {\n";
     $count = 0;
     foreach my $parameter (@{$args{'parameterlist'}}) {
 	print ".br\n.BI \"    $parameter\"\n";
 	if ($count == $#{$args{'parameterlist'}}) {
 	    print "\n};\n";
 	    last;
 	}
 	else {
 	    print ", \n.br\n";
 	}
 	$count++;
     }
     print ".SH Constants\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	print ".IP \"".$parameter."\" 12\n";
 	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"$section\"\n";
 	output_highlight($args{'sections'}{$section});
     }
 }
 ##
 # output struct in man
 sub output_struct_man(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
     print ".SH NAME\n";
     print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
     print ".SH SYNOPSIS\n";
     print $args{'type'}." ".$args{'struct'}." {\n.br\n";
     foreach my $parameter (@{$args{'parameterlist'}}) {
 	if ($parameter =~ /^#/) {
 	    print ".BI \"$parameter\"\n.br\n";
 	    next;
 	}
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
 	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 	    # bitfield
 	    print ".BI \"    ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
 	} else {
 	    $type =~ s/([^\*])$/$1 /;
 	    print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
 	}
 	print "\n.br\n";
     }
     print "};\n.br\n";
     print ".SH Members\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	($parameter =~ /^#/) && next;
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print ".IP \"".$parameter."\" 12\n";
 	output_highlight($args{'parameterdescs'}{$parameter_name});
     }
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"$section\"\n";
 	output_highlight($args{'sections'}{$section});
     }
 }
 ##
 # output typedef in man
 sub output_typedef_man(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
     print ".SH NAME\n";
     print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"$section\"\n";
 	output_highlight($args{'sections'}{$section});
     }
 }
 sub output_intro_man(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $count;
     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
     foreach $section (@{$args{'sectionlist'}}) {
 	print ".SH \"$section\"\n";
 	output_highlight($args{'sections'}{$section});
     }
 }
 ##
 # output in text
 sub output_function_text(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $start;
     print "Name:\n\n";
     print $args{'function'}." - ".$args{'purpose'}."\n";
     print "\nSynopsis:\n\n";
     if ($args{'functiontype'} ne "") {
 	$start = $args{'functiontype'}." ".$args{'function'}." (";
     } else {
 	$start = $args{'function'}." (";
     }
     print $start;
     my $count = 0;
     foreach my $parameter (@{$args{'parameterlist'}}) {
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print $1.$parameter.") (".$2;
 	} else {
 	    print $type." ".$parameter;
 	}
 	if ($count != $#{$args{'parameterlist'}}) {
 	    $count++;
 	    print ",\n";
 	    print " " x length($start);
 	} else {
 	    print ");\n\n";
 	}
     }
     print "Arguments:\n\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
     }
     output_section_text(@_);
 }
 #output sections in text
 sub output_section_text(%) {
     my %args = %{$_[0]};
     my $section;
     print "\n";
     foreach $section (@{$args{'sectionlist'}}) {
 	print "$section:\n\n";
 	output_highlight($args{'sections'}{$section});
     }
     print "\n\n";
 }
 # output enum in text
 sub output_enum_text(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $count;
     print "Enum:\n\n";
     print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
     print "enum ".$args{'enum'}." {\n";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print "\t$parameter";
 	if ($count != $#{$args{'parameterlist'}}) {
 	    $count++;
 	    print ",";
 	}
 	print "\n";
     }
     print "};\n\n";
     print "Constants:\n\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print "$parameter\n\t";
 	print $args{'parameterdescs'}{$parameter}."\n";
     }
     output_section_text(@_);
 }
 # output typedef in text
 sub output_typedef_text(%) {
     my %args = %{$_[0]};
     my ($parameter);
     my $count;
     print "Typedef:\n\n";
     print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
     output_section_text(@_);
 }
 # output struct as text
 sub output_struct_text(%) {
     my %args = %{$_[0]};
     my ($parameter);
     print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
     print $args{'type'}." ".$args{'struct'}." {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	if ($parameter =~ /^#/) {
 	    print "$parameter\n";
 	    next;
 	}
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print "\t$1 $parameter) ($2);\n";
 	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 	    # bitfield
 	    print "\t$1 $parameter$2;\n";
 	} else {
 	    print "\t".$type." ".$parameter.";\n";
 	}
     }
     print "};\n\n";
     print "Members:\n\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	($parameter =~ /^#/) && next;
 	my $parameter_name = $parameter;
 	$parameter_name =~ s/\[.*//;
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	print "$parameter\n\t";
 	print $args{'parameterdescs'}{$parameter_name}."\n";
     }
     print "\n";
     output_section_text(@_);
 }
 sub output_intro_text(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     foreach $section (@{$args{'sectionlist'}}) {
 	print " $section:\n";
 	print "    -> ";
 	output_highlight($args{'sections'}{$section});
     }
 }
 ##
 # generic output function for all types (function, struct/union, typedef, enum);
 # calls the generated, variable output_ function name based on
 # functype and output_mode
 sub output_declaration {
     no strict 'refs';
     my $name = shift;
     my $functype = shift;
     my $func = "output_${functype}_$output_mode";
     if (($function_only==0) ||
 	( $function_only == 1 && defined($function_table{$name})) ||
 	( $function_only == 2 && !defined($function_table{$name})))
     {
 	&$func(@_);
 	$section_counter++;
     }
 }
 ##
 # generic output function - calls the right one based on current output mode.
 sub output_intro {
     no strict 'refs';
     my $func = "output_intro_".$output_mode;
     &$func(@_);
     $section_counter++;
 }
 ##
 # takes a declaration (struct, union, enum, typedef) and
 # invokes the right handler. NOT called for functions.
 sub dump_declaration($$) {
     no strict 'refs';
     my ($prototype, $file) = @_;
     my $func = "dump_".$decl_type;
     &$func(@_);
 }
 sub dump_union($$) {
     dump_struct(@_);
 }
 sub dump_struct($$) {
     my $x = shift;
     my $file = shift;
     if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
 	$declaration_name = $2;
 	my $members = $3;
 	# ignore embedded structs or unions
 	$members =~ s/{.*?}//g;
 	# ignore members marked private:
 	$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
 	$members =~ s/\/\*.*?private:.*//gos;
 	# strip comments:
 	$members =~ s/\/\*.*?\*\///gos;
 	create_parameterlist($members, ';', $file);
 	output_declaration($declaration_name,
 			   'struct',
 			   {'struct' => $declaration_name,
 			    'module' => $modulename,
 			    'parameterlist' => \@parameterlist,
 			    'parameterdescs' => \%parameterdescs,
 			    'parametertypes' => \%parametertypes,
 			    'sectionlist' => \@sectionlist,
 			    'sections' => \%sections,
 			    'purpose' => $declaration_purpose,
 			    'type' => $decl_type
 			   });
     }
     else {
 	print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
 	++$errors;
     }
 }
 sub dump_enum($$) {
     my $x = shift;
     my $file = shift;
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
 	$declaration_name = $1;
 	my $members = $2;
 	foreach my $arg (split ',', $members) {
 	    $arg =~ s/^\s*(\w+).*/$1/;
 	    push @parameterlist, $arg;
 	    if (!$parameterdescs{$arg}) {
 		$parameterdescs{$arg} = $undescribed;
 		print STDERR "Warning(${file}:$.): Enum value '$arg' ".
 		    "not described in enum '$declaration_name'\n";
 	    }
 	}
 	output_declaration($declaration_name,
 			   'enum',
 			   {'enum' => $declaration_name,
 			    'module' => $modulename,
 			    'parameterlist' => \@parameterlist,
 			    'parameterdescs' => \%parameterdescs,
 			    'sectionlist' => \@sectionlist,
 			    'sections' => \%sections,
 			    'purpose' => $declaration_purpose
 			   });
     }
     else {
 	print STDERR "Error(${file}:$.): Cannot parse enum!\n";
 	++$errors;
     }
 }
 sub dump_typedef($$) {
     my $x = shift;
     my $file = shift;
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
 	$x =~ s/\(*.\)\s*;$/;/;
 	$x =~ s/\[*.\]\s*;$/;/;
     }
     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
 	$declaration_name = $1;
 	output_declaration($declaration_name,
 			   'typedef',
 			   {'typedef' => $declaration_name,
 			    'module' => $modulename,
 			    'sectionlist' => \@sectionlist,
 			    'sections' => \%sections,
 			    'purpose' => $declaration_purpose
 			   });
     }
     else {
 	print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
 	++$errors;
     }
 }
 sub create_parameterlist($$$) {
     my $args = shift;
     my $splitter = shift;
     my $file = shift;
     my $type;
     my $param;
     # temporarily replace commas inside function pointer definition
     while ($args =~ /(\([^\),]+),/) {
 	$args =~ s/(\([^\),]+),/$1#/g;
     }
     foreach my $arg (split($splitter, $args)) {
 	# strip comments
 	$arg =~ s/\/\*.*\*\///;
 	# strip leading/trailing spaces
 	$arg =~ s/^\s*//;
 	$arg =~ s/\s*$//;
 	$arg =~ s/\s+/ /;
 	if ($arg =~ /^#/) {
 	    # Treat preprocessor directive as a typeless variable just to fill
 	    # corresponding data structures "correctly". Catch it later in
 	    # output_* subs.
 	    push_parameter($arg, "", $file);
 	} elsif ($arg =~ m/\(.*\*/) {
 	    # pointer-to-function
 	    $arg =~ tr/#/,/;
 	    $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
 	    $param = $1;
 	    $type = $arg;
 	    $type =~ s/([^\(]+\(\*)$param/$1/;
 	    push_parameter($param, $type, $file);
 	} elsif ($arg) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;
 	    my @args = split('\s*,\s*', $arg);
 	    if ($args[0] =~ m/\*/) {
 		$args[0] =~ s/(\*+)\s*/ $1/;
 	    }
 	    my @first_arg;
 	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
 		    shift @args;
 		    push(@first_arg, split('\s+', $1));
 		    push(@first_arg, $2);
 	    } else {
 		    @first_arg = split('\s+', shift @args);
 	    }
 	    unshift(@args, pop @first_arg);
 	    $type = join " ", @first_arg;
 	    foreach $param (@args) {
 		if ($param =~ m/^(\*+)\s*(.*)/) {
 		    push_parameter($2, "$type $1", $file);
 		}
 		elsif ($param =~ m/(.*?):(\d+)/) {
 		    push_parameter($1, "$type:$2", $file)
 		}
 		else {
 		    push_parameter($param, $type, $file);
 		}
 	    }
 	}
     }
 }
 sub push_parameter($$$) {
 	my $param = shift;
 	my $type = shift;
 	my $file = shift;
 	if (($anon_struct_union == 1) && ($type eq "") &&
 	    ($param eq "}")) {
 		return;		# ignore the ending }; from anon. struct/union
 	}
 	$anon_struct_union = 0;
 	my $param_name = $param;
 	$param_name =~ s/\[.*//;
 	if ($type eq "" && $param =~ /\.\.\.$/)
 	{
 	    $type="";
 	    $parameterdescs{$param} = "variable arguments";
 	}
 	elsif ($type eq "" && ($param eq "" or $param eq "void"))
 	{
 	    $type="";
 	    $param="void";
 	    $parameterdescs{void} = "no arguments";
 	}
 	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
 	# handle unnamed (anonymous) union or struct:
 	{
 		$type = $param;
 		$param = "{unnamed_" . $param . "}";
 		$parameterdescs{$param} = "anonymous\n";
 		$anon_struct_union = 1;
 	}
 	# warn if parameter has no description
 	# (but ignore ones starting with # as these are not parameters
 	# but inline preprocessor statements);
 	# also ignore unnamed structs/unions;
 	if (!$anon_struct_union) {
 	if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
 	    $parameterdescs{$param_name} = $undescribed;
 	    if (($type eq 'function') || ($type eq 'enum')) {
 		print STDERR "Warning(${file}:$.): Function parameter ".
 		    "or member '$param' not " .
 		    "described in '$declaration_name'\n";
 	    }
 	    print STDERR "Warning(${file}:$.):".
 			 " No description found for parameter '$param'\n";
 	    ++$warnings;
 	}
 	}
 	push @parameterlist, $param;
 	$parametertypes{$param} = $type;
 }
 ##
 # takes a function prototype and the name of the current file being
 # processed and spits out all the details stored in the global
 # arrays/hashes.
 sub dump_function($$) {
     my $prototype = shift;
     my $file = shift;
     $prototype =~ s/^static +//;
     $prototype =~ s/^extern +//;
     $prototype =~ s/^fastcall +//;
     $prototype =~ s/^asmlinkage +//;
     $prototype =~ s/^inline +//;
     $prototype =~ s/^__inline__ +//;
     $prototype =~ s/^__inline +//;
     $prototype =~ s/^__always_inline +//;
     $prototype =~ s/^noinline +//;
     $prototype =~ s/__devinit +//;
     $prototype =~ s/^#define\s+//; #ak added
     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
     # Yes, this truly is vile.  We are looking for:
     # 1. Return type (may be nothing if we're looking at a macro)
     # 2. Function name
     # 3. Function parameters.
     #
     # All the while we have to watch out for function pointer parameters
     # (which IIRC is what the two sections are for), C types (these
     # regexps don't even start to express all the possibilities), and
     # so on.
     #
     # If you mess with these regexps, it's a good idea to check that
     # the following functions' documentation still comes out right:
     # - parport_register_device (function pointer parameters)
     # - atomic_set (macro)
     # - pci_match_device, __copy_to_user (long return type)
     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
 	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
 	$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
 	$return_type = $1;
 	$declaration_name = $2;
 	my $args = $3;
 	create_parameterlist($args, ',', $file);
     } else {
 	print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
 	++$errors;
 	return;
     }
     output_declaration($declaration_name,
 		       'function',
 		       {'function' => $declaration_name,
 			'module' => $modulename,
 			'functiontype' => $return_type,
 			'parameterlist' => \@parameterlist,
 			'parameterdescs' => \%parameterdescs,
 			'parametertypes' => \%parametertypes,
 			'sectionlist' => \@sectionlist,
 			'sections' => \%sections,
 			'purpose' => $declaration_purpose
 		       });
 }
 sub process_file($);
 # Read the file that maps relative names to absolute names for
 # separate source and object directories and for shadow trees.
 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
 	my ($relname, $absname);
 	while(<SOURCE_MAP>) {
 		chop();
 		($relname, $absname) = (split())[0..1];
 		$relname =~ s:^/+::;
 		$source_map{$relname} = $absname;
 	}
 	close(SOURCE_MAP);
 }
 if ($filelist) {
 	open(FLIST,"<$filelist") or die "Can't open file list $filelist";
 	while(<FLIST>) {
 		chop;
 		process_file($_);
 	}
 }
 foreach (@ARGV) {
     chomp;
     process_file($_);
 }
 if ($verbose && $errors) {
   print STDERR "$errors errors\n";
 }
 if ($verbose && $warnings) {
   print STDERR "$warnings warnings\n";
 }
 exit($errors);
 sub reset_state {
     $function = "";
     %constants = ();
     %parameterdescs = ();
     %parametertypes = ();
     @parameterlist = ();
     %sections = ();
     @sectionlist = ();
     $prototype = "";
     $state = 0;
 }
 sub process_state3_function($$) {
     my $x = shift;
     my $file = shift;
     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
 	# do nothing
     }
     elsif ($x =~ /([^\{]*)/) {
 	$prototype .= $1;
     }
     if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
 	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
 	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
 	$prototype =~ s@^\s+@@gos; # strip leading spaces
 	dump_function($prototype,$file);
 	reset_state();
     }
 }
 sub process_state3_type($$) {
     my $x = shift;
     my $file = shift;
     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
     $x =~ s@^\s+@@gos; # strip leading spaces
     $x =~ s@\s+$@@gos; # strip trailing spaces
     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
     if ($x =~ /^#/) {
 	# To distinguish preprocessor directive from regular declaration later.
 	$x .= ";";
     }
     while (1) {
 	if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
 	    $prototype .= $1 . $2;
 	    ($2 eq '{') && $brcount++;
 	    ($2 eq '}') && $brcount--;
 	    if (($2 eq ';') && ($brcount == 0)) {
 		dump_declaration($prototype,$file);
 		reset_state();
 		last;
 	    }
 	    $x = $3;
 	} else {
 	    $prototype .= $x;
 	    last;
 	}
     }
 }
 # replace <, >, and &
 sub xml_escape($) {
 	my $text = shift;
 	if (($output_mode eq "text") || ($output_mode eq "man")) {
 		return $text;
 	}
 	$text =~ s/\&/\\\\\\amp;/g;
 	$text =~ s/\</\\\\\\lt;/g;
 	$text =~ s/\>/\\\\\\gt;/g;
 	return $text;
 }
 sub process_file($) {
     my $file;
     my $identifier;
     my $func;
     my $descr;
     my $initial_section_counter = $section_counter;
     if (defined($ENV{'SRCTREE'})) {
 	$file = "$ENV{'SRCTREE'}" . "/" . "@_";
     }
     else {
 	$file = "@_";
     }
     if (defined($source_map{$file})) {
 	$file = $source_map{$file};
     }
     if (!open(IN,"<$file")) {
 	print STDERR "Error: Cannot open file $file\n";
 	++$errors;
 	return;
     }
     $section_counter = 0;
     while (<IN>) {
 	if ($state == 0) {
 	    if (/$doc_start/o) {
 		$state = 1;		# next line is always the function name
 		$in_doc_sect = 0;
 	    }
 	} elsif ($state == 1) {	# this line is the function name (always)
 	    if (/$doc_block/o) {
 		$state = 4;
 		$contents = "";
 		if ( $1 eq "" ) {
 			$section = $section_intro;
 		} else {
 			$section = $1;
 		}
 	    }
 	    elsif (/$doc_decl/o) {
 		$identifier = $1;
 		if (/\s*([\w\s]+?)\s*-/) {
 		    $identifier = $1;
 		}
 		$state = 2;
 		if (/-(.*)/) {
 		    # strip leading/trailing/multiple spaces
 		    $descr= $1;
 		    $descr =~ s/^\s*//;
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /;
 		    $declaration_purpose = xml_escape($descr);
 		} else {
 		    $declaration_purpose = "";
 		}
 		if ($identifier =~ m/^struct/) {
 		    $decl_type = 'struct';
 		} elsif ($identifier =~ m/^union/) {
 		    $decl_type = 'union';
 		} elsif ($identifier =~ m/^enum/) {
 		    $decl_type = 'enum';
 		} elsif ($identifier =~ m/^typedef/) {
 		    $decl_type = 'typedef';
 		} else {
 		    $decl_type = 'function';
 		}
 		if ($verbose) {
 		    print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
 		}
 	    } else {
 		print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
 		" - I thought it was a doc line\n";
 		++$warnings;
 		$state = 0;
 	    }
 	} elsif ($state == 2) {	# look for head: lines, and include content
 	    if (/$doc_sect/o) {
 		$newsection = $1;
 		$newcontents = $2;
 		if ($contents ne "") {
 		    if (!$in_doc_sect && $verbose) {
 			print STDERR "Warning(${file}:$.): contents before sections\n";
 			++$warnings;
 		    }
 		    dump_section($section, xml_escape($contents));
 		    $section = $section_default;
 		}
 		$in_doc_sect = 1;
 		$contents = $newcontents;
 		if ($contents ne "") {
 		    while ((substr($contents, 0, 1) eq " ") ||
 			substr($contents, 0, 1) eq "\t") {
 			    $contents = substr($contents, 1);
 		    }
 		    $contents .= "\n";
 		}
 		$section = $newsection;
 	    } elsif (/$doc_end/) {
 		if ($contents ne "") {
 		    dump_section($section, xml_escape($contents));
 		    $section = $section_default;
 		    $contents = "";
 		}
 		$prototype = "";
 		$state = 3;
 		$brcount = 0;
 #		print STDERR "end of doc comment, looking for prototype\n";
 	    } elsif (/$doc_content/) {
 		# miguel-style comment kludge, look for blank lines after
 		# @parameter line to signify start of description
 		if ($1 eq "" &&
 			($section =~ m/^@/ || $section eq $section_context)) {
 		    dump_section($section, xml_escape($contents));
 		    $section = $section_default;
 		    $contents = "";
 		} else {
 		    $contents .= $1."\n";
 		}
 	    } else {
 		# i dont know - bad line?  ignore.
 		print STDERR "Warning(${file}:$.): bad line: $_";
 		++$warnings;
 	    }
 	} elsif ($state == 3) {	# scanning for function '{' (end of prototype)
 	    if ($decl_type eq 'function') {
 		process_state3_function($_, $file);
 	    } else {
 		process_state3_type($_, $file);
 	    }
 	} elsif ($state == 4) {
 		# Documentation block
 		if (/$doc_block/) {
 			dump_section($section, $contents);
 			output_intro({'sectionlist' => \@sectionlist,
 				      'sections' => \%sections });
 			$contents = "";
 			$function = "";
 			%constants = ();
 			%parameterdescs = ();
 			%parametertypes = ();
 			@parameterlist = ();
 			%sections = ();
 			@sectionlist = ();
 			$prototype = "";
 			if ( $1 eq "" ) {
 				$section = $section_intro;
 			} else {
 				$section = $1;
 			}
 		}
 		elsif (/$doc_end/)
 		{
 			dump_section($section, $contents);
 			output_intro({'sectionlist' => \@sectionlist,
 				      'sections' => \%sections });
 			$contents = "";
 			$function = "";
 			%constants = ();
 			%parameterdescs = ();
 			%parametertypes = ();
 			@parameterlist = ();
 			%sections = ();
 			@sectionlist = ();
 			$prototype = "";
 			$state = 0;
 		}
 		elsif (/$doc_content/)
 		{
 			if ( $1 eq "" )
 			{
 				$contents .= $blankline;
 			}
 			else
 			{
 				$contents .= $1 . "\n";
 			}
 		}
 	}
     }
     if ($initial_section_counter == $section_counter) {
 	print STDERR "Warning(${file}): no structured comments found\n";
 	if ($output_mode eq "xml") {
 	    # The template wants at least one RefEntry here; make one.
 	    print "<refentry>\n";
 	    print " <refnamediv>\n";
 	    print "  <refname>\n";
 	    print "   ${file}\n";
 	    print "  </refname>\n";
 	    print "  <refpurpose>\n";
 	    print "   Document generation inconsistency\n";
 	    print "  </refpurpose>\n";
 	    print " </refnamediv>\n";
 	    print " <refsect1>\n";
 	    print "  <title>\n";
 	    print "   Oops\n";
 	    print "  </title>\n";
 	    print "  <warning>\n";
 	    print "   <para>\n";
 	    print "    The template for this document tried to insert\n";
 	    print "    the structured comment from the file\n";
 	    print "    <filename>${file}</filename> at this point,\n";
 	    print "    but none was found.\n";
 	    print "    This dummy section is inserted to allow\n";
 	    print "    generation to continue.\n";
 	    print "   </para>\n";
 	    print "  </warning>\n";
 	    print " </refsect1>\n";
 	    print "</refentry>\n";
 	}
     }
 }