Eric Lee / smarc-fsl-linux-kernel

1

#!/usr/bin/perl -w

1

#!/usr/bin/perl -w

2

3

use strict;

3

use strict;

4

5

6

7

8

9

## ##

9

## ##

10

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

10

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

11

12

## ##

12

## ##

13

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

13

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

14

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

14

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

15

16

# 18/01/2001 - Cleanups

16

# 18/01/2001 - Cleanups

17

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

17

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

18

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

18

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

19

# -- huggie@earth.li

19

# -- huggie@earth.li

20

21

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

21

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

22

# allowed comments before function declarations.

22

# allowed comments before function declarations.

23

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

23

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

24

25

# Still to do:

25

# Still to do:

26

# - add perldoc documentation

26

# - add perldoc documentation

27

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

27

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

28

29

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

29

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

30

# Return error code.

30

# Return error code.

31

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

31

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

32

33

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

33

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

34

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

34

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

35

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

35

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

36

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

36

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

37

38

39

#

39

#

40

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

40

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

41

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

41

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

42

#

42

#

43

44

# Note: This only supports 'c'.

44

# Note: This only supports 'c'.

45

46

# usage:

46

# usage:

47

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

47

# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ]

48

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

48

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

49

# or

49

# or

50

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

50

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

51

#

51

#

52

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

52

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

53

# The -list format is for internal use by docproc.

53

#

54

#

54

# -no-doc-sections

55

# -no-doc-sections

55

# Do not output DOC: sections

56

# Do not output DOC: sections

56

#

57

#

57

# -function funcname

58

# -function funcname

58

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

59

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

59

# DOC: section titles. All other functions and DOC: sections are ignored.

60

# DOC: section titles. All other functions and DOC: sections are ignored.

60

#

61

#

61

# -nofunction funcname

62

# -nofunction funcname

62

# If set, then only generate documentation for the other function(s)/DOC:

63

# If set, then only generate documentation for the other function(s)/DOC:

63

# sections. Cannot be used together with -function (yes, that's a bug --

64

# sections. Cannot be used together with -function (yes, that's a bug --

64

# perl hackers can fix it 8))

65

# perl hackers can fix it 8))

65

#

66

#

66

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

67

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

67

#

68

#

68

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

69

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

69

70

#

71

#

71

# format of comments.

72

# format of comments.

72

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

73

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

73

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

74

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

74

# /**

75

# /**

75

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

76

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

76

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

77

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

77

# (* a blank line)?

78

# (* a blank line)?

78

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

79

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

79

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

80

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

80

# (*)?*/

81

# (*)?*/

81

#

82

#

82

# So .. the trivial example would be:

83

# So .. the trivial example would be:

83

#

84

#

84

# /**

85

# /**

85

# * my_function

86

# * my_function

86

# */

87

# */

87

#

88

#

88

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

89

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

89

# after the last parameter specification.

90

# after the last parameter specification.

90

# e.g.

91

# e.g.

91

# /**

92

# /**

92

# * my_function - does my stuff

93

# * my_function - does my stuff

93

# * @my_arg: its mine damnit

94

# * @my_arg: its mine damnit

94

# *

95

# *

95

# * Does my stuff explained.

96

# * Does my stuff explained.

96

# */

97

# */

97

#

98

#

98

# or, could also use:

99

# or, could also use:

99

# /**

100

# /**

100

# * my_function - does my stuff

101

# * my_function - does my stuff

101

# * @my_arg: its mine damnit

102

# * @my_arg: its mine damnit

102

# * Description: Does my stuff explained.

103

# * Description: Does my stuff explained.

103

# */

104

# */

104

# etc.

105

# etc.

105

#

106

#

106

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

107

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

107

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

108

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

108

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

109

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

109

# the name. Nesting of declarations is not supported.

110

# the name. Nesting of declarations is not supported.

110

# Use the argument mechanism to document members or constants.

111

# Use the argument mechanism to document members or constants.

111

# e.g.

112

# e.g.

112

# /**

113

# /**

113

# * struct my_struct - short description

114

# * struct my_struct - short description

114

# * @a: first member

115

# * @a: first member

115

# * @b: second member

116

# * @b: second member

116

# *

117

# *

117

# * Longer description

118

# * Longer description

118

# */

119

# */

119

# struct my_struct {

120

# struct my_struct {

120

# int a;

121

# int a;

121

# int b;

122

# int b;

122

# /* private: */

123

# /* private: */

123

# int c;

124

# int c;

124

# };

125

# };

125

#

126

#

126

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

127

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

127

#

128

#

128

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

129

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

129

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

130

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

130

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

131

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

131

# empty line.

132

# empty line.

132

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

133

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

133

# appropriately in DocBook.

134

# appropriately in DocBook.

134

#

135

#

135

# Example:

136

# Example:

136

# /**

137

# /**

137

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

138

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

138

# * @a: some argument

139

# * @a: some argument

139

# * Context: !in_interrupt()

140

# * Context: !in_interrupt()

140

# *

141

# *

141

# * Some description

142

# * Some description

142

# * Example:

143

# * Example:

143

# * user_function(22);

144

# * user_function(22);

144

# */

145

# */

145

# ...

146

# ...

146

#

147

#

147

#

148

#

148

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

149

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

149

# patterns, which are highlighted appropriately.

150

# patterns, which are highlighted appropriately.

150

#

151

#

151

# 'funcname()' - function

152

# 'funcname()' - function

152

# '$ENVVAR' - environmental variable

153

# '$ENVVAR' - environmental variable

153

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

154

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

154

# '@parameter' - name of a parameter

155

# '@parameter' - name of a parameter

155

# '%CONST' - name of a constant.

156

# '%CONST' - name of a constant.

156

157

my $errors = 0;

158

my $errors = 0;

158

my $warnings = 0;

159

my $warnings = 0;

159

my $anon_struct_union = 0;

160

my $anon_struct_union = 0;

160

161

# match expressions used to find embedded type information

162

# match expressions used to find embedded type information

162

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

163

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

163

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

164

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

164

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

165

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

165

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

166

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

166

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

167

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

167

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

168

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

168

169

# Output conversion substitutions.

170

# Output conversion substitutions.

170

# One for each output format

171

# One for each output format

171

172

# these work fairly well

173

# these work fairly well

173

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

174

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

174

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

175

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

175

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

176

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

176

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

177

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

177

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

178

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

178

my $local_lt = "\\\\\\\\lt:";

179

my $local_lt = "\\\\\\\\lt:";

179

my $local_gt = "\\\\\\\\gt:";

180

my $local_gt = "\\\\\\\\gt:";

180

my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"

181

my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"

181

182

# XML, docbook format

183

# XML, docbook format

183

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

184

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

184

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

185

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

185

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

186

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

186

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

187

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

187

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

188

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

188

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

189

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

189

my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";

190

my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";

190

191

# gnome, docbook format

192

# gnome, docbook format

192

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

193

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

193

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

194

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

194

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

195

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

195

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

196

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

196

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

197

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

197

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

198

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

198

199

# these are pretty rough

200

# these are pretty rough

200

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

201

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

201

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

202

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

202

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

203

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

203

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

204

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

204

my $blankline_man = "";

205

my $blankline_man = "";

205

206

# text-mode

207

# text-mode

207

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

208

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

208

$type_func, "\$1",

209

$type_func, "\$1",

209

$type_struct, "\$1",

210

$type_struct, "\$1",

210

$type_param, "\$1" );

211

$type_param, "\$1" );

211

my $blankline_text = "";

212

my $blankline_text = "";

212

213

214

# list mode

215

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

216

$type_func, "\$1",

217

$type_struct, "\$1",

218

$type_param, "\$1" );

219

my $blankline_list = "";

213

220

214

sub usage {

221

sub usage {

215

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

222

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

223

print " [ -no-doc-sections ]\n";

216

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

224

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

217

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

225

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

218

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

226

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

219

print " -v : verbose output, more warnings & other info listed\n";

227

print " -v : verbose output, more warnings & other info listed\n";

220

exit 1;

228

exit 1;

221

}

229

}

222

230

223

# read arguments

231

# read arguments

224

if ($#ARGV == -1) {

232

if ($#ARGV == -1) {

225

usage();

233

usage();

226

}

234

}

227

235

228

my $verbose = 0;

236

my $verbose = 0;

229

my $output_mode = "man";

237

my $output_mode = "man";

230

my $no_doc_sections = 0;

238

my $no_doc_sections = 0;

231

my %highlights = %highlights_man;

239

my %highlights = %highlights_man;

232

my $blankline = $blankline_man;

240

my $blankline = $blankline_man;

233

my $modulename = "Kernel API";

241

my $modulename = "Kernel API";

234

my $function_only = 0;

242

my $function_only = 0;

235

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

243

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

236

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

244

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

237

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

245

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

238

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

246

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

239

247

240

# Essentially these are globals

248

# Essentially these are globals

241

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

249

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

242

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

250

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

243

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

251

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

244

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

252

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

245

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

253

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

246

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

254

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

247

255

248

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

256

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

249

$verbose = "$ENV{'KBUILD_VERBOSE'}";

257

$verbose = "$ENV{'KBUILD_VERBOSE'}";

250

}

258

}

251

259

252

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

260

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

253

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

261

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

254

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

262

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

255

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

263

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

256

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

264

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

257

# into html.

265

# into html.

258

my $section_counter = 0;

266

my $section_counter = 0;

259

267

260

my $lineprefix="";

268

my $lineprefix="";

261

269

262

# states

270

# states

263

# 0 - normal code

271

# 0 - normal code

264

# 1 - looking for function name

272

# 1 - looking for function name

265

# 2 - scanning field start.

273

# 2 - scanning field start.

266

# 3 - scanning prototype.

274

# 3 - scanning prototype.

267

# 4 - documentation block

275

# 4 - documentation block

268

my $state;

276

my $state;

269

my $in_doc_sect;

277

my $in_doc_sect;

270

278

271

#declaration types: can be

279

#declaration types: can be

272

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

280

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

273

my $decl_type;

281

my $decl_type;

274

282

275

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

283

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

276

284

277

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

285

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

278

my $doc_end = '\*/';

286

my $doc_end = '\*/';

279

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

287

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

280

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

288

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

281

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

289

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

282

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

290

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

283

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

291

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

284

292

285

my %constants;

293

my %constants;

286

my %parameterdescs;

294

my %parameterdescs;

287

my @parameterlist;

295

my @parameterlist;

288

my %sections;

296

my %sections;

289

my @sectionlist;

297

my @sectionlist;

290

my $sectcheck;

298

my $sectcheck;

291

my $struct_actual;

299

my $struct_actual;

292

300

293

my $contents = "";

301

my $contents = "";

294

my $section_default = "Description"; # default section

302

my $section_default = "Description"; # default section

295

my $section_intro = "Introduction";

303

my $section_intro = "Introduction";

296

my $section = $section_default;

304

my $section = $section_default;

297

my $section_context = "Context";

305

my $section_context = "Context";

298

306

299

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

307

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

300

308

301

reset_state();

309

reset_state();

302

310

303

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

311

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

304

my $cmd = shift @ARGV;

312

my $cmd = shift @ARGV;

305

if ($cmd eq "-html") {

313

if ($cmd eq "-html") {

306

$output_mode = "html";

314

$output_mode = "html";

307

%highlights = %highlights_html;

315

%highlights = %highlights_html;

308

$blankline = $blankline_html;

316

$blankline = $blankline_html;

309

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

317

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

310

$output_mode = "man";

318

$output_mode = "man";

311

%highlights = %highlights_man;

319

%highlights = %highlights_man;

312

$blankline = $blankline_man;

320

$blankline = $blankline_man;

313

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

321

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

314

$output_mode = "text";

322

$output_mode = "text";

315

%highlights = %highlights_text;

323

%highlights = %highlights_text;

316

$blankline = $blankline_text;

324

$blankline = $blankline_text;

317

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

325

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

318

$output_mode = "xml";

326

$output_mode = "xml";

319

%highlights = %highlights_xml;

327

%highlights = %highlights_xml;

320

$blankline = $blankline_xml;

328

$blankline = $blankline_xml;

329

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

330

$output_mode = "list";

331

%highlights = %highlights_list;

332

$blankline = $blankline_list;

321

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

333

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

322

$output_mode = "gnome";

334

$output_mode = "gnome";

323

%highlights = %highlights_gnome;

335

%highlights = %highlights_gnome;

324

$blankline = $blankline_gnome;

336

$blankline = $blankline_gnome;

325

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

337

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

326

$modulename = shift @ARGV;

338

$modulename = shift @ARGV;

327

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

339

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

328

$function_only = 1;

340

$function_only = 1;

329

$function = shift @ARGV;

341

$function = shift @ARGV;

330

$function_table{$function} = 1;

342

$function_table{$function} = 1;

331

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

343

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

332

$function_only = 2;

344

$function_only = 2;

333

$function = shift @ARGV;

345

$function = shift @ARGV;

334

$function_table{$function} = 1;

346

$function_table{$function} = 1;

335

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

347

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

336

$verbose = 1;

348

$verbose = 1;

337

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

349

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

338

usage();

350

usage();

339

} elsif ($cmd eq '-no-doc-sections') {

351

} elsif ($cmd eq '-no-doc-sections') {

340

$no_doc_sections = 1;

352

$no_doc_sections = 1;

341

}

353

}

342

}

354

}

343

355

344

# get kernel version from env

356

# get kernel version from env

345

sub get_kernel_version() {

357

sub get_kernel_version() {

346

my $version = 'unknown kernel version';

358

my $version = 'unknown kernel version';

347

359

348

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

360

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

349

$version = $ENV{'KERNELVERSION'};

361

$version = $ENV{'KERNELVERSION'};

350

}

362

}

351

return $version;

363

return $version;

352

}

364

}

353

my $kernelversion = get_kernel_version();

365

my $kernelversion = get_kernel_version();

354

366

355

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

367

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

356

# using the s// operator.

368

# using the s// operator.

357

my $dohighlight = "";

369

my $dohighlight = "";

358

foreach my $pattern (keys %highlights) {

370

foreach my $pattern (keys %highlights) {

359

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

371

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

360

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

372

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

361

}

373

}

362

374

363

##

375

##

364

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

376

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

365

#

377

#

366

sub dump_section {

378

sub dump_section {

367

my $file = shift;

379

my $file = shift;

368

my $name = shift;

380

my $name = shift;

369

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

381

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

370

382

371

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

383

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

372

$name = $1;

384

$name = $1;

373

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

385

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

374

$constants{$name} = $contents;

386

$constants{$name} = $contents;

375

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

387

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

376

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

388

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

377

$name = $1;

389

$name = $1;

378

$parameterdescs{$name} = $contents;

390

$parameterdescs{$name} = $contents;

379

$sectcheck = $sectcheck . $name . " ";

391

$sectcheck = $sectcheck . $name . " ";

380

} elsif ($name eq "@\.\.\.") {

392

} elsif ($name eq "@\.\.\.") {

381

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

393

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

382

$name = "...";

394

$name = "...";

383

$parameterdescs{$name} = $contents;

395

$parameterdescs{$name} = $contents;

384

$sectcheck = $sectcheck . $name . " ";

396

$sectcheck = $sectcheck . $name . " ";

385

} else {

397

} else {

386

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

398

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

387

if (defined($sections{$name}) && ($sections{$name} ne "")) {

399

if (defined($sections{$name}) && ($sections{$name} ne "")) {

388

print STDERR "Error(${file}:$.): duplicate section name '$name'\n";

400

print STDERR "Error(${file}:$.): duplicate section name '$name'\n";

389

++$errors;

401

++$errors;

390

}

402

}

391

$sections{$name} = $contents;

403

$sections{$name} = $contents;

392

push @sectionlist, $name;

404

push @sectionlist, $name;

393

}

405

}

394

}

406

}

395

407

396

##

408

##

397

# dump DOC: section after checking that it should go out

409

# dump DOC: section after checking that it should go out

398

#

410

#

399

sub dump_doc_section {

411

sub dump_doc_section {

400

my $file = shift;

412

my $file = shift;

401

my $name = shift;

413

my $name = shift;

402

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

414

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

403

415

404

if ($no_doc_sections) {

416

if ($no_doc_sections) {

405

return;

417

return;

406

}

418

}

407

419

408

if (($function_only == 0) ||

420

if (($function_only == 0) ||

409

( $function_only == 1 && defined($function_table{$name})) ||

421

( $function_only == 1 && defined($function_table{$name})) ||

410

( $function_only == 2 && !defined($function_table{$name})))

422

( $function_only == 2 && !defined($function_table{$name})))

411

{

423

{

412

dump_section($file, $name, $contents);

424

dump_section($file, $name, $contents);

413

output_blockhead({'sectionlist' => \@sectionlist,

425

output_blockhead({'sectionlist' => \@sectionlist,

414

'sections' => \%sections,

426

'sections' => \%sections,

415

'module' => $modulename,

427

'module' => $modulename,

416

'content-only' => ($function_only != 0), });

428

'content-only' => ($function_only != 0), });

417

}

429

}

418

}

430

}

419

431

420

##

432

##

421

# output function

433

# output function

422

#

434

#

423

# parameterdescs, a hash.

435

# parameterdescs, a hash.

424

# function => "function name"

436

# function => "function name"

425

# parameterlist => @list of parameters

437

# parameterlist => @list of parameters

426

# parameterdescs => %parameter descriptions

438

# parameterdescs => %parameter descriptions

427

# sectionlist => @list of sections

439

# sectionlist => @list of sections

428

# sections => %section descriptions

440

# sections => %section descriptions

429

#

441

#

430

442

431

sub output_highlight {

443

sub output_highlight {

432

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

444

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

433

my $line;

445

my $line;

434

446

435

# DEBUG

447

# DEBUG

436

# if (!defined $contents) {

448

# if (!defined $contents) {

437

# use Carp;

449

# use Carp;

438

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

450

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

439

# }

451

# }

440

452

441

if ($output_mode eq "html" || $output_mode eq "xml") {

453

if ($output_mode eq "html" || $output_mode eq "xml") {

442

$contents = local_unescape($contents);

454

$contents = local_unescape($contents);

443

# convert data read & converted thru xml_escape() into &xyz; format:

455

# convert data read & converted thru xml_escape() into &xyz; format:

444

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

456

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

445

}

457

}

446

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

458

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

447

eval $dohighlight;

459

eval $dohighlight;

448

die $@ if $@;

460

die $@ if $@;

449

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

461

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

450

462

451

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

463

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

452

if ($line eq ""){

464

if ($line eq ""){

453

print $lineprefix, local_unescape($blankline);

465

print $lineprefix, local_unescape($blankline);

454

} else {

466

} else {

455

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

467

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

456

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

468

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

457

print "\\&$line";

469

print "\\&$line";

458

} else {

470

} else {

459

print $lineprefix, $line;

471

print $lineprefix, $line;

460

}

472

}

461

}

473

}

462

print "\n";

474

print "\n";

463

}

475

}

464

}

476

}

465

477

466

#output sections in html

478

#output sections in html

467

sub output_section_html(%) {

479

sub output_section_html(%) {

468

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

480

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

469

my $section;

481

my $section;

470

482

471

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

483

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

472

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

484

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

473

print "<blockquote>\n";

485

print "<blockquote>\n";

474

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

486

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

475

print "</blockquote>\n";

487

print "</blockquote>\n";

476

}

488

}

477

}

489

}

478

490

479

# output enum in html

491

# output enum in html

480

sub output_enum_html(%) {

492

sub output_enum_html(%) {

481

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

493

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

482

my ($parameter);

494

my ($parameter);

483

my $count;

495

my $count;

484

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

496

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

485

497

486

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

498

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

487

$count = 0;

499

$count = 0;

488

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

500

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

489

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

501

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

490

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

502

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

491

$count++;

503

$count++;

492

print ",\n";

504

print ",\n";

493

}

505

}

494

print "<br>";

506

print "<br>";

495

}

507

}

496

print "};<br>\n";

508

print "};<br>\n";

497

509

498

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

510

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

499

print "<dl>\n";

511

print "<dl>\n";

500

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

512

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

501

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

513

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

502

print "<dd>";

514

print "<dd>";

503

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

515

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

504

}

516

}

505

print "</dl>\n";

517

print "</dl>\n";

506

output_section_html(@_);

518

output_section_html(@_);

507

print "<hr>\n";

519

print "<hr>\n";

508

}

520

}

509

521

510

# output typedef in html

522

# output typedef in html

511

sub output_typedef_html(%) {

523

sub output_typedef_html(%) {

512

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

524

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

513

my ($parameter);

525

my ($parameter);

514

my $count;

526

my $count;

515

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

527

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

516

528

517

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

529

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

518

output_section_html(@_);

530

output_section_html(@_);

519

print "<hr>\n";

531

print "<hr>\n";

520

}

532

}

521

533

522

# output struct in html

534

# output struct in html

523

sub output_struct_html(%) {

535

sub output_struct_html(%) {

524

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

536

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

525

my ($parameter);

537

my ($parameter);

526

538

527

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

539

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

528

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

540

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

529

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

541

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

530

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

542

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

531

print "$parameter<br>\n";

543

print "$parameter<br>\n";

532

next;

544

next;

533

}

545

}

534

my $parameter_name = $parameter;

546

my $parameter_name = $parameter;

535

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

547

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

536

548

537

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

549

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

538

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

550

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

539

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

551

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

540

# pointer-to-function

552

# pointer-to-function

541

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

553

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

542

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

554

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

543

# bitfield

555

# bitfield

544

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

556

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

545

} else {

557

} else {

546

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

558

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

547

}

559

}

548

}

560

}

549

print "};<br>\n";

561

print "};<br>\n";

550

562

551

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

563

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

552

print "<dl>\n";

564

print "<dl>\n";

553

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

565

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

554

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

566

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

555

567

556

my $parameter_name = $parameter;

568

my $parameter_name = $parameter;

557

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

569

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

558

570

559

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

571

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

560

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

572

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

561

print "<dd>";

573

print "<dd>";

562

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

574

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

563

}

575

}

564

print "</dl>\n";

576

print "</dl>\n";

565

output_section_html(@_);

577

output_section_html(@_);

566

print "<hr>\n";

578

print "<hr>\n";

567

}

579

}

568

580

569

# output function in html

581

# output function in html

570

sub output_function_html(%) {

582

sub output_function_html(%) {

571

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

583

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

572

my ($parameter, $section);

584

my ($parameter, $section);

573

my $count;

585

my $count;

574

586

575

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

587

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

576

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

588

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

577

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

589

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

578

print "(";

590

print "(";

579

$count = 0;

591

$count = 0;

580

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

592

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

581

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

593

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

582

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

594

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

583

# pointer-to-function

595

# pointer-to-function

584

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

596

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

585

} else {

597

} else {

586

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

598

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

587

}

599

}

588

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

600

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

589

$count++;

601

$count++;

590

print ",\n";

602

print ",\n";

591

}

603

}

592

}

604

}

593

print ")\n";

605

print ")\n";

594

606

595

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

607

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

596

print "<dl>\n";

608

print "<dl>\n";

597

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

609

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

598

my $parameter_name = $parameter;

610

my $parameter_name = $parameter;

599

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

611

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

600

612

601

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

613

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

602

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

614

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

603

print "<dd>";

615

print "<dd>";

604

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

616

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

605

}

617

}

606

print "</dl>\n";

618

print "</dl>\n";

607

output_section_html(@_);

619

output_section_html(@_);

608

print "<hr>\n";

620

print "<hr>\n";

609

}

621

}

610

622

611

# output DOC: block header in html

623

# output DOC: block header in html

612

sub output_blockhead_html(%) {

624

sub output_blockhead_html(%) {

613

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

625

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

614

my ($parameter, $section);

626

my ($parameter, $section);

615

my $count;

627

my $count;

616

628

617

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

629

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

618

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

630

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

619

print "<ul>\n";

631

print "<ul>\n";

620

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

632

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

621

print "</ul>\n";

633

print "</ul>\n";

622

}

634

}

623

print "<hr>\n";

635

print "<hr>\n";

624

}

636

}

625

637

626

sub output_section_xml(%) {

638

sub output_section_xml(%) {

627

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

639

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

628

my $section;

640

my $section;

629

# print out each section

641

# print out each section

630

$lineprefix=" ";

642

$lineprefix=" ";

631

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

643

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

632

print "<refsect1>\n";

644

print "<refsect1>\n";

633

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

645

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

634

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

646

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

635

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

647

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

636

} else {

648

} else {

637

print "<para>\n";

649

print "<para>\n";

638

}

650

}

639

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

651

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

640

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

652

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

641

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

653

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

642

} else {

654

} else {

643

print "</para>\n";

655

print "</para>\n";

644

}

656

}

645

print "</refsect1>\n";

657

print "</refsect1>\n";

646

}

658

}

647

}

659

}

648

660

649

# output function in XML DocBook

661

# output function in XML DocBook

650

sub output_function_xml(%) {

662

sub output_function_xml(%) {

651

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

663

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

652

my ($parameter, $section);

664

my ($parameter, $section);

653

my $count;

665

my $count;

654

my $id;

666

my $id;

655

667

656

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

668

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

657

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

669

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

658

670

659

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

671

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

660

print "<refentryinfo>\n";

672

print "<refentryinfo>\n";

661

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

673

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

662

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

674

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

663

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

675

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

664

print "</refentryinfo>\n";

676

print "</refentryinfo>\n";

665

print "<refmeta>\n";

677

print "<refmeta>\n";

666

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

678

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

667

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

679

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

668

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

680

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

669

print "</refmeta>\n";

681

print "</refmeta>\n";

670

print "<refnamediv>\n";

682

print "<refnamediv>\n";

671

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

683

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

672

print " <refpurpose>\n";

684

print " <refpurpose>\n";

673

print " ";

685

print " ";

674

output_highlight ($args{'purpose'});

686

output_highlight ($args{'purpose'});

675

print " </refpurpose>\n";

687

print " </refpurpose>\n";

676

print "</refnamediv>\n";

688

print "</refnamediv>\n";

677

689

678

print "<refsynopsisdiv>\n";

690

print "<refsynopsisdiv>\n";

679

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

691

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

680

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

692

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

681

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

693

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

682

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

694

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

683

695

684

$count = 0;

696

$count = 0;

685

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

697

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

686

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

698

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

687

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

699

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

688

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

700

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

689

# pointer-to-function

701

# pointer-to-function

690

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

702

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

691

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

703

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

692

} else {

704

} else {

693

print " <paramdef>" . $type;

705

print " <paramdef>" . $type;

694

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

706

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

695

}

707

}

696

}

708

}

697

} else {

709

} else {

698

print " <void/>\n";

710

print " <void/>\n";

699

}

711

}

700

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

712

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

701

print "</refsynopsisdiv>\n";

713

print "</refsynopsisdiv>\n";

702

714

703

# print parameters

715

# print parameters

704

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

716

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

705

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

717

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

706

print " <variablelist>\n";

718

print " <variablelist>\n";

707

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

719

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

708

my $parameter_name = $parameter;

720

my $parameter_name = $parameter;

709

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

721

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

710

722

711

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

723

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

712

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

724

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

713

$lineprefix=" ";

725

$lineprefix=" ";

714

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

726

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

715

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

727

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

716

}

728

}

717

print " </variablelist>\n";

729

print " </variablelist>\n";

718

} else {

730

} else {

719

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

731

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

720

}

732

}

721

print "</refsect1>\n";

733

print "</refsect1>\n";

722

734

723

output_section_xml(@_);

735

output_section_xml(@_);

724

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

736

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

725

}

737

}

726

738

727

# output struct in XML DocBook

739

# output struct in XML DocBook

728

sub output_struct_xml(%) {

740

sub output_struct_xml(%) {

729

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

741

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

730

my ($parameter, $section);

742

my ($parameter, $section);

731

my $id;

743

my $id;

732

744

733

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

745

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

734

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

746

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

735

747

736

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

748

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

737

print "<refentryinfo>\n";

749

print "<refentryinfo>\n";

738

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

750

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

739

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

751

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

740

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

752

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

741

print "</refentryinfo>\n";

753

print "</refentryinfo>\n";

742

print "<refmeta>\n";

754

print "<refmeta>\n";

743

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

755

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

744

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

756

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

745

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

757

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

746

print "</refmeta>\n";

758

print "</refmeta>\n";

747

print "<refnamediv>\n";

759

print "<refnamediv>\n";

748

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

760

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

749

print " <refpurpose>\n";

761

print " <refpurpose>\n";

750

print " ";

762

print " ";

751

output_highlight ($args{'purpose'});

763

output_highlight ($args{'purpose'});

752

print " </refpurpose>\n";

764

print " </refpurpose>\n";

753

print "</refnamediv>\n";

765

print "</refnamediv>\n";

754

766

755

print "<refsynopsisdiv>\n";

767

print "<refsynopsisdiv>\n";

756

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

768

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

757

print " <programlisting>\n";

769

print " <programlisting>\n";

758

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

770

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

759

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

771

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

760

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

772

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

761

print "$parameter\n";

773

print "$parameter\n";

762

next;

774

next;

763

}

775

}

764

776

765

my $parameter_name = $parameter;

777

my $parameter_name = $parameter;

766

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

778

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

767

779

768

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

780

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

769

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

781

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

770

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

782

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

771

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

783

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

772

# pointer-to-function

784

# pointer-to-function

773

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

785

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

774

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

786

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

775

# bitfield

787

# bitfield

776

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

788

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

777

} else {

789

} else {

778

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

790

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

779

}

791

}

780

}

792

}

781

print "};";

793

print "};";

782

print " </programlisting>\n";

794

print " </programlisting>\n";

783

print "</refsynopsisdiv>\n";

795

print "</refsynopsisdiv>\n";

784

796

785

print " <refsect1>\n";

797

print " <refsect1>\n";

786

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

798

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

787

799

788

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

800

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

789

print " <variablelist>\n";

801

print " <variablelist>\n";

790

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

802

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

791

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

803

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

792

804

793

my $parameter_name = $parameter;

805

my $parameter_name = $parameter;

794

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

806

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

795

807

796

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

808

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

797

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

809

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

798

print " <varlistentry>";

810

print " <varlistentry>";

799

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

811

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

800

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

812

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

801

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

813

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

802

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

814

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

803

print " </varlistentry>\n";

815

print " </varlistentry>\n";

804

}

816

}

805

print " </variablelist>\n";

817

print " </variablelist>\n";

806

} else {

818

} else {

807

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

819

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

808

}

820

}

809

print " </refsect1>\n";

821

print " </refsect1>\n";

810

822

811

output_section_xml(@_);

823

output_section_xml(@_);

812

824

813

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

825

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

814

}

826

}

815

827

816

# output enum in XML DocBook

828

# output enum in XML DocBook

817

sub output_enum_xml(%) {

829

sub output_enum_xml(%) {

818

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

830

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

819

my ($parameter, $section);

831

my ($parameter, $section);

820

my $count;

832

my $count;

821

my $id;

833

my $id;

822

834

823

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

835

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

824

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

836

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

825

837

826

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

838

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

827

print "<refentryinfo>\n";

839

print "<refentryinfo>\n";

828

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

840

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

829

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

841

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

830

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

842

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

831

print "</refentryinfo>\n";

843

print "</refentryinfo>\n";

832

print "<refmeta>\n";

844

print "<refmeta>\n";

833

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

845

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

834

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

846

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

835

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

847

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

836

print "</refmeta>\n";

848

print "</refmeta>\n";

837

print "<refnamediv>\n";

849

print "<refnamediv>\n";

838

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

850

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

839

print " <refpurpose>\n";

851

print " <refpurpose>\n";

840

print " ";

852

print " ";

841

output_highlight ($args{'purpose'});

853

output_highlight ($args{'purpose'});

842

print " </refpurpose>\n";

854

print " </refpurpose>\n";

843

print "</refnamediv>\n";

855

print "</refnamediv>\n";

844

856

845

print "<refsynopsisdiv>\n";

857

print "<refsynopsisdiv>\n";

846

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

858

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

847

print " <programlisting>\n";

859

print " <programlisting>\n";

848

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

860

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

849

$count = 0;

861

$count = 0;

850

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

862

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

851

print " $parameter";

863

print " $parameter";

852

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

864

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

853

$count++;

865

$count++;

854

print ",";

866

print ",";

855

}

867

}

856

print "\n";

868

print "\n";

857

}

869

}

858

print "};";

870

print "};";

859

print " </programlisting>\n";

871

print " </programlisting>\n";

860

print "</refsynopsisdiv>\n";

872

print "</refsynopsisdiv>\n";

861

873

862

print "<refsect1>\n";

874

print "<refsect1>\n";

863

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

875

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

864

print " <variablelist>\n";

876

print " <variablelist>\n";

865

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

877

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

866

my $parameter_name = $parameter;

878

my $parameter_name = $parameter;

867

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

879

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

868

880

869

print " <varlistentry>";

881

print " <varlistentry>";

870

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

882

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

871

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

883

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

872

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

884

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

873

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

885

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

874

print " </varlistentry>\n";

886

print " </varlistentry>\n";

875

}

887

}

876

print " </variablelist>\n";

888

print " </variablelist>\n";

877

print "</refsect1>\n";

889

print "</refsect1>\n";

878

890

879

output_section_xml(@_);

891

output_section_xml(@_);

880

892

881

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

893

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

882

}

894

}

883

895

884

# output typedef in XML DocBook

896

# output typedef in XML DocBook

885

sub output_typedef_xml(%) {

897

sub output_typedef_xml(%) {

886

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

898

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

887

my ($parameter, $section);

899

my ($parameter, $section);

888

my $id;

900

my $id;

889

901

890

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

902

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

891

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

903

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

892

904

893

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

905

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

894

print "<refentryinfo>\n";

906

print "<refentryinfo>\n";

895

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

907

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

896

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

908

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

897

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

909

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

898

print "</refentryinfo>\n";

910

print "</refentryinfo>\n";

899

print "<refmeta>\n";

911

print "<refmeta>\n";

900

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

912

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

901

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

913

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

902

print "</refmeta>\n";

914

print "</refmeta>\n";

903

print "<refnamediv>\n";

915

print "<refnamediv>\n";

904

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

916

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

905

print " <refpurpose>\n";

917

print " <refpurpose>\n";

906

print " ";

918

print " ";

907

output_highlight ($args{'purpose'});

919

output_highlight ($args{'purpose'});

908

print " </refpurpose>\n";

920

print " </refpurpose>\n";

909

print "</refnamediv>\n";

921

print "</refnamediv>\n";

910

922

911

print "<refsynopsisdiv>\n";

923

print "<refsynopsisdiv>\n";

912

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

924

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

913

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

925

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

914

print "</refsynopsisdiv>\n";

926

print "</refsynopsisdiv>\n";

915

927

916

output_section_xml(@_);

928

output_section_xml(@_);

917

929

918

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

930

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

919

}

931

}

920

932

921

# output in XML DocBook

933

# output in XML DocBook

922

sub output_blockhead_xml(%) {

934

sub output_blockhead_xml(%) {

923

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

935

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

924

my ($parameter, $section);

936

my ($parameter, $section);

925

my $count;

937

my $count;

926

938

927

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

939

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

928

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

940

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

929

941

930

# print out each section

942

# print out each section

931

$lineprefix=" ";

943

$lineprefix=" ";

932

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

944

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

933

if (!$args{'content-only'}) {

945

if (!$args{'content-only'}) {

934

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

946

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

935

}

947

}

936

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

948

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

937

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

949

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

938

} else {

950

} else {

939

print "<para>\n";

951

print "<para>\n";

940

}

952

}

941

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

953

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

942

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

954

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

943

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

955

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

944

} else {

956

} else {

945

print "</para>";

957

print "</para>";

946

}

958

}

947

if (!$args{'content-only'}) {

959

if (!$args{'content-only'}) {

948

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

960

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

949

}

961

}

950

}

962

}

951

963

952

print "\n\n";

964

print "\n\n";

953

}

965

}

954

966

955

# output in XML DocBook

967

# output in XML DocBook

956

sub output_function_gnome {

968

sub output_function_gnome {

957

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

969

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

958

my ($parameter, $section);

970

my ($parameter, $section);

959

my $count;

971

my $count;

960

my $id;

972

my $id;

961

973

962

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

974

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

963

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

975

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

964

976

965

print "<sect2>\n";

977

print "<sect2>\n";

966

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

978

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

967

979

968

print " <funcsynopsis>\n";

980

print " <funcsynopsis>\n";

969

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

981

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

970

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

982

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

971

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

983

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

972

984

973

$count = 0;

985

$count = 0;

974

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

986

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

975

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

987

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

976

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

988

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

977

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

989

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

978

# pointer-to-function

990

# pointer-to-function

979

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

991

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

980

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

992

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

981

} else {

993

} else {

982

print " <paramdef>" . $type;

994

print " <paramdef>" . $type;

983

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

995

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

984

}

996

}

985

}

997

}

986

} else {

998

} else {

987

print " <void>\n";

999

print " <void>\n";

988

}

1000

}

989

print " </funcsynopsis>\n";

1001

print " </funcsynopsis>\n";

990

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

1002

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

991

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

1003

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

992

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

1004

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

993

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

1005

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

994

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

1006

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

995

print "<tbody>\n";

1007

print "<tbody>\n";

996

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

1008

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

997

my $parameter_name = $parameter;

1009

my $parameter_name = $parameter;

998

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

1010

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

999

1011

1000

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

1012

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

1001

print " <entry>\n";

1013

print " <entry>\n";

1002

$lineprefix=" ";

1014

$lineprefix=" ";

1003

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

1015

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

1004

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

1016

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

1005

}

1017

}

1006

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

1018

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

1007

} else {

1019

} else {

1008

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

1020

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

1009

}

1021

}

1010

1022

1011

# print out each section

1023

# print out each section

1012

$lineprefix=" ";

1024

$lineprefix=" ";

1013

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

1025

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

1014

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

1026

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

1015

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

1027

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

1016

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

1028

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

1017

} else {

1029

} else {

1018

}

1030

}

1019

print "<para>\n";

1031

print "<para>\n";

1020

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

1032

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

1021

print "</para>\n";

1033

print "</para>\n";

1022

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

1034

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

1023

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

1035

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

1024

} else {

1036

} else {

1025

}

1037

}

1026

print " </simplesect>\n";

1038

print " </simplesect>\n";

1027

}

1039

}

1028

1040

1029

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

1041

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

1030

}

1042

}

1031

1043

1032

##

1044

##

1033

# output function in man

1045

# output function in man

1034

sub output_function_man(%) {

1046

sub output_function_man(%) {

1035

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

1047

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

1036

my ($parameter, $section);

1048

my ($parameter, $section);

1037

my $count;

1049

my $count;

1038

1050

1039

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

1051

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

1040

1052

1041

print ".SH NAME\n";

1053

print ".SH NAME\n";

1042

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

1054

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

1043

1055

1044

print ".SH SYNOPSIS\n";

1056

print ".SH SYNOPSIS\n";

1045

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

1057

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

1046

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

1058

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

1047

} else {

1059

} else {

1048

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

1060

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

1049

}

1061

}

1050

$count = 0;

1062

$count = 0;

1051

my $parenth = "(";

1063

my $parenth = "(";

1052

my $post = ",";

1064

my $post = ",";

1053

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

1065

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

1054

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

1066

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

1055

$post = ");";

1067

$post = ");";

1056

}

1068

}

1057

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

1069

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

1058

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

1070

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

1059

# pointer-to-function

1071

# pointer-to-function

1060

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

1072

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

1061

} else {

1073

} else {

1062

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

1074

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

1063

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

1075

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

1064

}

1076

}

1065

$count++;

1077

$count++;

1066

$parenth = "";

1078

$parenth = "";

1067

}

1079

}

1068

1080

1069

print ".SH ARGUMENTS\n";

1081

print ".SH ARGUMENTS\n";

1070

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

1082

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

1071

my $parameter_name = $parameter;

1083

my $parameter_name = $parameter;

1072

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

1084

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

1073

1085

1074

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

1086

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

1075

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

1087

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

1076

}

1088

}

1077

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

1089

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

1078

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

1090

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

1079

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

1091

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

1080

}

1092

}

1081

}

1093

}

1082

1094

1083

##

1095

##

1084

# output enum in man

1096

# output enum in man

1085

sub output_enum_man(%) {

1097

sub output_enum_man(%) {

1086

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

1098

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

1087

my ($parameter, $section);

1099

my ($parameter, $section);

1088

my $count;

1100

my $count;

1089

1101

1090

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

1102

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

1091

1103

1092

print ".SH NAME\n";

1104

print ".SH NAME\n";

1093

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

1105

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

1094

1106

1095

print ".SH SYNOPSIS\n";

1107

print ".SH SYNOPSIS\n";

1096

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

1108

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

1097

$count = 0;

1109

$count = 0;

1098

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

1110

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

1099

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

1111

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

1100

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

1112

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

1101

print "\n};\n";

1113

print "\n};\n";

1102

last;

1114

last;

1103

}

1115

}

1104

else {

1116

else {

1105

print ", \n.br\n";

1117

print ", \n.br\n";

1106

}

1118

}

1107

$count++;

1119

$count++;

1108

}

1120

}

1109

1121

1110

print ".SH Constants\n";

1122

print ".SH Constants\n";

1111

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

1123

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

1112

my $parameter_name = $parameter;

1124

my $parameter_name = $parameter;

1113

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

1125

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

1114

1126

1115

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

1127

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

1116

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

1128

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

1117

}

1129

}

1118

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

1130

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

1119

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

1131

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

1120

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

1132

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

1121

}

1133

}

1122

}

1134

}

1123

1135

1124

##

1136

##

1125

# output struct in man

1137

# output struct in man

1126

sub output_struct_man(%) {

1138

sub output_struct_man(%) {

1127

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

1139

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

1128

my ($parameter, $section);

1140

my ($parameter, $section);

1129

1141

1130

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

1142

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

1131

1143

1132

print ".SH NAME\n";

1144

print ".SH NAME\n";

1133

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

1145

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

1134

1146

1135

print ".SH SYNOPSIS\n";

1147

print ".SH SYNOPSIS\n";

1136

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

1148

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

1137

1149

1138

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

1150

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

1139

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

1151

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

1140

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

1152

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

1141

next;

1153

next;

1142

}

1154

}

1143

my $parameter_name = $parameter;

1155

my $parameter_name = $parameter;

1144

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

1156

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

1145

1157

1146

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

1158

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

1147

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

1159

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

1148

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

1160

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

1149

# pointer-to-function

1161

# pointer-to-function

1150

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

1162

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

1151

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

1163

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

1152

# bitfield

1164

# bitfield

1153

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

1165

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

1154

} else {

1166

} else {

1155

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

1167

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

1156

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

1168

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

1157

}

1169

}

1158

print "\n.br\n";

1170

print "\n.br\n";

1159

}

1171

}

1160

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

1172

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

1161

1173

1162

print ".SH Members\n";

1174

print ".SH Members\n";

1163

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

1175

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

1164

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

1176

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

1165

1177

1166

my $parameter_name = $parameter;

1178

my $parameter_name = $parameter;

1167

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

1179

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

1168

1180

1169

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

1181

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1170

print ".IP \"" . $parameter . "\" 12\n";

1182

print ".IP \"" . $parameter . "\" 12\n";

1171

output_highlight($args{'parameterdescs'}{$parameter_name});

1183

output_highlight($args{'parameterdescs'}{$parameter_name});

1172

}

1184

}

1173

foreach $section (@{$args{'sectionlist'}}) {

1185

foreach $section (@{$args{'sectionlist'}}) {

1174

print ".SH \"$section\"\n";

1186

print ".SH \"$section\"\n";

1175

output_highlight($args{'sections'}{$section});

1187

output_highlight($args{'sections'}{$section});

1176

}

1188

}

1177

}

1189

}

1178

1190

1179

##

1191

##

1180

# output typedef in man

1192

# output typedef in man

1181

sub output_typedef_man(%) {

1193

sub output_typedef_man(%) {

1182

my %args = %{$_[0]};

1194

my %args = %{$_[0]};

1183

my ($parameter, $section);

1195

my ($parameter, $section);

1184

1196

1185

print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

1197

print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

1186

1198

1187

print ".SH NAME\n";

1199

print ".SH NAME\n";

1188

print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";

1200

print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";

1189

1201

1190

foreach $section (@{$args{'sectionlist'}}) {

1202

foreach $section (@{$args{'sectionlist'}}) {

1191

print ".SH \"$section\"\n";

1203

print ".SH \"$section\"\n";

1192

output_highlight($args{'sections'}{$section});

1204

output_highlight($args{'sections'}{$section});

1193

}

1205

}

1194

}

1206

}

1195

1207

1196

sub output_blockhead_man(%) {

1208

sub output_blockhead_man(%) {

1197

my %args = %{$_[0]};

1209

my %args = %{$_[0]};

1198

my ($parameter, $section);

1210

my ($parameter, $section);

1199

my $count;

1211

my $count;

1200

1212

1201

print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

1213

print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

1202

1214

1203

foreach $section (@{$args{'sectionlist'}}) {

1215

foreach $section (@{$args{'sectionlist'}}) {

1204

print ".SH \"$section\"\n";

1216

print ".SH \"$section\"\n";

1205

output_highlight($args{'sections'}{$section});

1217

output_highlight($args{'sections'}{$section});

1206

}

1218

}

1207

}

1219

}

1208

1220

1209

##

1221

##

1210

# output in text

1222

# output in text

1211

sub output_function_text(%) {

1223

sub output_function_text(%) {

1212

my %args = %{$_[0]};

1224

my %args = %{$_[0]};

1213

my ($parameter, $section);

1225

my ($parameter, $section);

1214

my $start;

1226

my $start;

1215

1227

1216

print "Name:\n\n";

1228

print "Name:\n\n";

1217

print $args{'function'} . " - " . $args{'purpose'} . "\n";

1229

print $args{'function'} . " - " . $args{'purpose'} . "\n";

1218

1230

1219

print "\nSynopsis:\n\n";

1231

print "\nSynopsis:\n\n";

1220

if ($args{'functiontype'} ne "") {

1232

if ($args{'functiontype'} ne "") {

1221

$start = $args{'functiontype'} . " " . $args{'function'} . " (";

1233

$start = $args{'functiontype'} . " " . $args{'function'} . " (";

1222

} else {

1234

} else {

1223

$start = $args{'function'} . " (";

1235

$start = $args{'function'} . " (";

1224

}

1236

}

1225

print $start;

1237

print $start;

1226

1238

1227

my $count = 0;

1239

my $count = 0;

1228

foreach my $parameter (@{$args{'parameterlist'}}) {

1240

foreach my $parameter (@{$args{'parameterlist'}}) {

1229

$type = $args{'parametertypes'}{$parameter};

1241

$type = $args{'parametertypes'}{$parameter};

1230

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1242

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1231

# pointer-to-function

1243

# pointer-to-function

1232

print $1 . $parameter . ") (" . $2;

1244

print $1 . $parameter . ") (" . $2;

1233

} else {

1245

} else {

1234

print $type . " " . $parameter;

1246

print $type . " " . $parameter;

1235

}

1247

}

1236

if ($count != $#{$args{'parameterlist'}}) {

1248

if ($count != $#{$args{'parameterlist'}}) {

1237

$count++;

1249

$count++;

1238

print ",\n";

1250

print ",\n";

1239

print " " x length($start);

1251

print " " x length($start);

1240

} else {

1252

} else {

1241

print ");\n\n";

1253

print ");\n\n";

1242

}

1254

}

1243

}

1255

}

1244

1256

1245

print "Arguments:\n\n";

1257

print "Arguments:\n\n";

1246

foreach $parameter (@{$args{'parameterlist'}}) {

1258

foreach $parameter (@{$args{'parameterlist'}}) {

1247

my $parameter_name = $parameter;

1259

my $parameter_name = $parameter;

1248

$parameter_name =~ s/\[.*//;

1260

$parameter_name =~ s/\[.*//;

1249

1261

1250

print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";

1262

print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";

1251

}

1263

}

1252

output_section_text(@_);

1264

output_section_text(@_);

1253

}

1265

}

1254

1266

1255

#output sections in text

1267

#output sections in text

1256

sub output_section_text(%) {

1268

sub output_section_text(%) {

1257

my %args = %{$_[0]};

1269

my %args = %{$_[0]};

1258

my $section;

1270

my $section;

1259

1271

1260

print "\n";

1272

print "\n";

1261

foreach $section (@{$args{'sectionlist'}}) {

1273

foreach $section (@{$args{'sectionlist'}}) {

1262

print "$section:\n\n";

1274

print "$section:\n\n";

1263

output_highlight($args{'sections'}{$section});

1275

output_highlight($args{'sections'}{$section});

1264

}

1276

}

1265

print "\n\n";

1277

print "\n\n";

1266

}

1278

}

1267

1279

1268

# output enum in text

1280

# output enum in text

1269

sub output_enum_text(%) {

1281

sub output_enum_text(%) {

1270

my %args = %{$_[0]};

1282

my %args = %{$_[0]};

1271

my ($parameter);

1283

my ($parameter);

1272

my $count;

1284

my $count;

1273

print "Enum:\n\n";

1285

print "Enum:\n\n";

1274

1286

1275

print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";

1287

print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";

1276

print "enum " . $args{'enum'} . " {\n";

1288

print "enum " . $args{'enum'} . " {\n";

1277

$count = 0;

1289

$count = 0;

1278

foreach $parameter (@{$args{'parameterlist'}}) {

1290

foreach $parameter (@{$args{'parameterlist'}}) {

1279

print "\t$parameter";

1291

print "\t$parameter";

1280

if ($count != $#{$args{'parameterlist'}}) {

1292

if ($count != $#{$args{'parameterlist'}}) {

1281

$count++;

1293

$count++;

1282

print ",";

1294

print ",";

1283

}

1295

}

1284

print "\n";

1296

print "\n";

1285

}

1297

}

1286

print "};\n\n";

1298

print "};\n\n";

1287

1299

1288

print "Constants:\n\n";

1300

print "Constants:\n\n";

1289

foreach $parameter (@{$args{'parameterlist'}}) {

1301

foreach $parameter (@{$args{'parameterlist'}}) {

1290

print "$parameter\n\t";

1302

print "$parameter\n\t";

1291

print $args{'parameterdescs'}{$parameter} . "\n";

1303

print $args{'parameterdescs'}{$parameter} . "\n";

1292

}

1304

}

1293

1305

1294

output_section_text(@_);

1306

output_section_text(@_);

1295

}

1307

}

1296

1308

1297

# output typedef in text

1309

# output typedef in text

1298

sub output_typedef_text(%) {

1310

sub output_typedef_text(%) {

1299

my %args = %{$_[0]};

1311

my %args = %{$_[0]};

1300

my ($parameter);

1312

my ($parameter);

1301

my $count;

1313

my $count;

1302

print "Typedef:\n\n";

1314

print "Typedef:\n\n";

1303

1315

1304

print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";

1316

print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";

1305

output_section_text(@_);

1317

output_section_text(@_);

1306

}

1318

}

1307

1319

1308

# output struct as text

1320

# output struct as text

1309

sub output_struct_text(%) {

1321

sub output_struct_text(%) {

1310

my %args = %{$_[0]};

1322

my %args = %{$_[0]};

1311

my ($parameter);

1323

my ($parameter);

1312

1324

1313

print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";

1325

print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";

1314

print $args{'type'} . " " . $args{'struct'} . " {\n";

1326

print $args{'type'} . " " . $args{'struct'} . " {\n";

1315

foreach $parameter (@{$args{'parameterlist'}}) {

1327

foreach $parameter (@{$args{'parameterlist'}}) {

1316

if ($parameter =~ /^#/) {

1328

if ($parameter =~ /^#/) {

1317

print "$parameter\n";

1329

print "$parameter\n";

1318

next;

1330

next;

1319

}

1331

}

1320

1332

1321

my $parameter_name = $parameter;

1333

my $parameter_name = $parameter;

1322

$parameter_name =~ s/\[.*//;

1334

$parameter_name =~ s/\[.*//;

1323

1335

1324

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1336

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1325

$type = $args{'parametertypes'}{$parameter};

1337

$type = $args{'parametertypes'}{$parameter};

1326

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1338

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

1327

# pointer-to-function

1339

# pointer-to-function

1328

print "\t$1 $parameter) ($2);\n";

1340

print "\t$1 $parameter) ($2);\n";

1329

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

1341

} elsif ($type =~ m/^(.*?)\s*(:.*)/) {

1330

# bitfield

1342

# bitfield

1331

print "\t$1 $parameter$2;\n";

1343

print "\t$1 $parameter$2;\n";

1332

} else {

1344

} else {

1333

print "\t" . $type . " " . $parameter . ";\n";

1345

print "\t" . $type . " " . $parameter . ";\n";

1334

}

1346

}

1335

}

1347

}

1336

print "};\n\n";

1348

print "};\n\n";

1337

1349

1338

print "Members:\n\n";

1350

print "Members:\n\n";

1339

foreach $parameter (@{$args{'parameterlist'}}) {

1351

foreach $parameter (@{$args{'parameterlist'}}) {

1340

($parameter =~ /^#/) && next;

1352

($parameter =~ /^#/) && next;

1341

1353

1342

my $parameter_name = $parameter;

1354

my $parameter_name = $parameter;

1343

$parameter_name =~ s/\[.*//;

1355

$parameter_name =~ s/\[.*//;

1344

1356

1345

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1357

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

1346

print "$parameter\n\t";

1358

print "$parameter\n\t";

1347

print $args{'parameterdescs'}{$parameter_name} . "\n";

1359

print $args{'parameterdescs'}{$parameter_name} . "\n";

1348

}

1360

}

1349

print "\n";

1361

print "\n";

1350

output_section_text(@_);

1362

output_section_text(@_);

1351

}

1363

}

1352

1364

1353

sub output_blockhead_text(%) {

1365

sub output_blockhead_text(%) {

1354

my %args = %{$_[0]};

1366

my %args = %{$_[0]};

1355

my ($parameter, $section);

1367

my ($parameter, $section);

1356

1368

1357

foreach $section (@{$args{'sectionlist'}}) {

1369

foreach $section (@{$args{'sectionlist'}}) {

1358

print " $section:\n";

1370

print " $section:\n";

1359

print " -> ";

1371

print " -> ";

1360

output_highlight($args{'sections'}{$section});

1372

output_highlight($args{'sections'}{$section});

1373

}

1374

}

1375

1376

## list mode output functions

1377

1378

sub output_function_list(%) {

1379

my %args = %{$_[0]};

1380

1381

print $args{'function'} . "\n";

1382

}

1383

1384

# output enum in list

1385

sub output_enum_list(%) {

1386

my %args = %{$_[0]};

1387

print $args{'enum'} . "\n";

1388

}

1389

1390

# output typedef in list

1391

sub output_typedef_list(%) {

1392

my %args = %{$_[0]};

1393

print $args{'typedef'} . "\n";

1394

}

1395

1396

# output struct as list

1397

sub output_struct_list(%) {

1398

my %args = %{$_[0]};

1399

1400

print $args{'struct'} . "\n";

1401

}

1402

1403

sub output_blockhead_list(%) {

1404

my %args = %{$_[0]};

1405

my ($parameter, $section);

1406

1407

foreach $section (@{$args{'sectionlist'}}) {

1408

print "DOC: $section\n";

1361

}

1409

}

1362

}

1410

}

1363

1411

1364

##

1412

##

1365

# generic output function for all types (function, struct/union, typedef, enum);

1413

# generic output function for all types (function, struct/union, typedef, enum);

1366

# calls the generated, variable output_ function name based on

1414

# calls the generated, variable output_ function name based on

1367

# functype and output_mode

1415

# functype and output_mode

1368

sub output_declaration {

1416

sub output_declaration {

1369

no strict 'refs';

1417

no strict 'refs';

1370

my $name = shift;

1418

my $name = shift;

1371

my $functype = shift;

1419

my $functype = shift;

1372

my $func = "output_${functype}_$output_mode";

1420

my $func = "output_${functype}_$output_mode";

1373

if (($function_only==0) ||

1421

if (($function_only==0) ||

1374

( $function_only == 1 && defined($function_table{$name})) ||

1422

( $function_only == 1 && defined($function_table{$name})) ||

1375

( $function_only == 2 && !defined($function_table{$name})))

1423

( $function_only == 2 && !defined($function_table{$name})))

1376

{

1424

{

1377

&$func(@_);

1425

&$func(@_);

1378

$section_counter++;

1426

$section_counter++;

1379

}

1427

}

1380

}

1428

}

1381

1429

1382

##

1430

##

1383

# generic output function - calls the right one based on current output mode.

1431

# generic output function - calls the right one based on current output mode.

1384

sub output_blockhead {

1432

sub output_blockhead {

1385

no strict 'refs';

1433

no strict 'refs';

1386

my $func = "output_blockhead_" . $output_mode;

1434

my $func = "output_blockhead_" . $output_mode;

1387

&$func(@_);

1435

&$func(@_);

1388

$section_counter++;

1436

$section_counter++;

1389

}

1437

}

1390

1438

1391

##

1439

##

1392

# takes a declaration (struct, union, enum, typedef) and

1440

# takes a declaration (struct, union, enum, typedef) and

1393

# invokes the right handler. NOT called for functions.

1441

# invokes the right handler. NOT called for functions.

1394

sub dump_declaration($$) {

1442

sub dump_declaration($$) {

1395

no strict 'refs';

1443

no strict 'refs';

1396

my ($prototype, $file) = @_;

1444

my ($prototype, $file) = @_;

1397

my $func = "dump_" . $decl_type;

1445

my $func = "dump_" . $decl_type;

1398

&$func(@_);

1446

&$func(@_);

1399

}

1447

}

1400

1448

1401

sub dump_union($$) {

1449

sub dump_union($$) {

1402

dump_struct(@_);

1450

dump_struct(@_);

1403

}

1451

}

1404

1452

1405

sub dump_struct($$) {

1453

sub dump_struct($$) {

1406

my $x = shift;

1454

my $x = shift;

1407

my $file = shift;

1455

my $file = shift;

1408

my $nested;

1456

my $nested;

1409

1457

1410

if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {

1458

if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {

1411

#my $decl_type = $1;

1459

#my $decl_type = $1;

1412

$declaration_name = $2;

1460

$declaration_name = $2;

1413

my $members = $3;

1461

my $members = $3;

1414

1462

1415

# ignore embedded structs or unions

1463

# ignore embedded structs or unions

1416

$members =~ s/({.*})//g;

1464

$members =~ s/({.*})//g;

1417

$nested = $1;

1465

$nested = $1;

1418

1466

1419

# ignore members marked private:

1467

# ignore members marked private:

1420

$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;

1468

$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;

1421

$members =~ s/\/\*\s*private:.*//gos;

1469

$members =~ s/\/\*\s*private:.*//gos;

1422

# strip comments:

1470

# strip comments:

1423

$members =~ s/\/\*.*?\*\///gos;

1471

$members =~ s/\/\*.*?\*\///gos;

1424

$nested =~ s/\/\*.*?\*\///gos;

1472

$nested =~ s/\/\*.*?\*\///gos;

1425

# strip kmemcheck_bitfield_{begin,end}.*;

1473

# strip kmemcheck_bitfield_{begin,end}.*;

1426

$members =~ s/kmemcheck_bitfield_.*?;//gos;

1474

$members =~ s/kmemcheck_bitfield_.*?;//gos;

1427

# strip attributes

1475

# strip attributes

1428

$members =~ s/__aligned\s*$\d+$//gos;

1476

$members =~ s/__aligned\s*$\d+$//gos;

1429

1477

1430

create_parameterlist($members, ';', $file);

1478

create_parameterlist($members, ';', $file);

1431

check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);

1479

check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);

1432

1480

1433

output_declaration($declaration_name,

1481

output_declaration($declaration_name,

1434

'struct',

1482

'struct',

1435

{'struct' => $declaration_name,

1483

{'struct' => $declaration_name,

1436

'module' => $modulename,

1484

'module' => $modulename,

1437

'parameterlist' => \@parameterlist,

1485

'parameterlist' => \@parameterlist,

1438

'parameterdescs' => \%parameterdescs,

1486

'parameterdescs' => \%parameterdescs,

1439

'parametertypes' => \%parametertypes,

1487

'parametertypes' => \%parametertypes,

1440

'sectionlist' => \@sectionlist,

1488

'sectionlist' => \@sectionlist,

1441

'sections' => \%sections,

1489

'sections' => \%sections,

1442

'purpose' => $declaration_purpose,

1490

'purpose' => $declaration_purpose,

1443

'type' => $decl_type

1491

'type' => $decl_type

1444

});

1492

});

1445

}

1493

}

1446

else {

1494

else {

1447

print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";

1495

print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";

1448

++$errors;

1496

++$errors;

1449

}

1497

}

1450

}

1498

}

1451

1499

1452

sub dump_enum($$) {

1500

sub dump_enum($$) {

1453

my $x = shift;

1501

my $x = shift;

1454

my $file = shift;

1502

my $file = shift;

1455

1503

1456

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1504

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1457

$x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums

1505

$x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums

1458

1506

1459

if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {

1507

if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {

1460

$declaration_name = $1;

1508

$declaration_name = $1;

1461

my $members = $2;

1509

my $members = $2;

1462

1510

1463

foreach my $arg (split ',', $members) {

1511

foreach my $arg (split ',', $members) {

1464

$arg =~ s/^\s*(\w+).*/$1/;

1512

$arg =~ s/^\s*(\w+).*/$1/;

1465

push @parameterlist, $arg;

1513

push @parameterlist, $arg;

1466

if (!$parameterdescs{$arg}) {

1514

if (!$parameterdescs{$arg}) {

1467

$parameterdescs{$arg} = $undescribed;

1515

$parameterdescs{$arg} = $undescribed;

1468

print STDERR "Warning(${file}:$.): Enum value '$arg' ".

1516

print STDERR "Warning(${file}:$.): Enum value '$arg' ".

1469

"not described in enum '$declaration_name'\n";

1517

"not described in enum '$declaration_name'\n";

1470

}

1518

}

1471

1519

1472

}

1520

}

1473

1521

1474

output_declaration($declaration_name,

1522

output_declaration($declaration_name,

1475

'enum',

1523

'enum',

1476

{'enum' => $declaration_name,

1524

{'enum' => $declaration_name,

1477

'module' => $modulename,

1525

'module' => $modulename,

1478

'parameterlist' => \@parameterlist,

1526

'parameterlist' => \@parameterlist,

1479

'parameterdescs' => \%parameterdescs,

1527

'parameterdescs' => \%parameterdescs,

1480

'sectionlist' => \@sectionlist,

1528

'sectionlist' => \@sectionlist,

1481

'sections' => \%sections,

1529

'sections' => \%sections,

1482

'purpose' => $declaration_purpose

1530

'purpose' => $declaration_purpose

1483

});

1531

});

1484

}

1532

}

1485

else {

1533

else {

1486

print STDERR "Error(${file}:$.): Cannot parse enum!\n";

1534

print STDERR "Error(${file}:$.): Cannot parse enum!\n";

1487

++$errors;

1535

++$errors;

1488

}

1536

}

1489

}

1537

}

1490

1538

1491

sub dump_typedef($$) {

1539

sub dump_typedef($$) {

1492

my $x = shift;

1540

my $x = shift;

1493

my $file = shift;

1541

my $file = shift;

1494

1542

1495

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1543

$x =~ s@/\*.*?\*/@@gos; # strip comments.

1496

while (($x =~ /$*.$\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {

1544

while (($x =~ /$*.$\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {

1497

$x =~ s/$*.$\s*;$/;/;

1545

$x =~ s/$*.$\s*;$/;/;

1498

$x =~ s/\[*.\]\s*;$/;/;

1546

$x =~ s/\[*.\]\s*;$/;/;

1499

}

1547

}

1500

1548

1501

if ($x =~ /typedef.*\s+(\w+)\s*;/) {

1549

if ($x =~ /typedef.*\s+(\w+)\s*;/) {

1502

$declaration_name = $1;

1550

$declaration_name = $1;

1503

1551

1504

output_declaration($declaration_name,

1552

output_declaration($declaration_name,

1505

'typedef',

1553

'typedef',

1506

{'typedef' => $declaration_name,

1554

{'typedef' => $declaration_name,

1507

'module' => $modulename,

1555

'module' => $modulename,

1508

'sectionlist' => \@sectionlist,

1556

'sectionlist' => \@sectionlist,

1509

'sections' => \%sections,

1557

'sections' => \%sections,

1510

'purpose' => $declaration_purpose

1558

'purpose' => $declaration_purpose

1511

});

1559

});

1512

}

1560

}

1513

else {

1561

else {

1514

print STDERR "Error(${file}:$.): Cannot parse typedef!\n";

1562

print STDERR "Error(${file}:$.): Cannot parse typedef!\n";

1515

++$errors;

1563

++$errors;

1516

}

1564

}

1517

}

1565

}

1518

1566

1519

sub save_struct_actual($) {

1567

sub save_struct_actual($) {

1520

my $actual = shift;

1568

my $actual = shift;

1521

1569

1522

# strip all spaces from the actual param so that it looks like one string item

1570

# strip all spaces from the actual param so that it looks like one string item

1523

$actual =~ s/\s*//g;

1571

$actual =~ s/\s*//g;

1524

$struct_actual = $struct_actual . $actual . " ";

1572

$struct_actual = $struct_actual . $actual . " ";

1525

}

1573

}

1526

1574

1527

sub create_parameterlist($$$) {

1575

sub create_parameterlist($$$) {

1528

my $args = shift;

1576

my $args = shift;

1529

my $splitter = shift;

1577

my $splitter = shift;

1530

my $file = shift;

1578

my $file = shift;

1531

my $type;

1579

my $type;

1532

my $param;

1580

my $param;

1533

1581

1534

# temporarily replace commas inside function pointer definition

1582

# temporarily replace commas inside function pointer definition

1535

while ($args =~ /($[^$,]+),/) {

1583

while ($args =~ /($[^$,]+),/) {

1536

$args =~ s/($[^$,]+),/$1#/g;

1584

$args =~ s/($[^$,]+),/$1#/g;

1537

}

1585

}

1538

1586

1539

foreach my $arg (split($splitter, $args)) {

1587

foreach my $arg (split($splitter, $args)) {

1540

# strip comments

1588

# strip comments

1541

$arg =~ s/\/\*.*\*\///;

1589

$arg =~ s/\/\*.*\*\///;

1542

# strip leading/trailing spaces

1590

# strip leading/trailing spaces

1543

$arg =~ s/^\s*//;

1591

$arg =~ s/^\s*//;

1544

$arg =~ s/\s*$//;

1592

$arg =~ s/\s*$//;

1545

$arg =~ s/\s+/ /;

1593

$arg =~ s/\s+/ /;

1546

1594

1547

if ($arg =~ /^#/) {

1595

if ($arg =~ /^#/) {

1548

# Treat preprocessor directive as a typeless variable just to fill

1596

# Treat preprocessor directive as a typeless variable just to fill

1549

# corresponding data structures "correctly". Catch it later in

1597

# corresponding data structures "correctly". Catch it later in

1550

# output_* subs.

1598

# output_* subs.

1551

push_parameter($arg, "", $file);

1599

push_parameter($arg, "", $file);

1552

} elsif ($arg =~ m/$.+$\s*\(/) {

1600

} elsif ($arg =~ m/$.+$\s*\(/) {

1553

# pointer-to-function

1601

# pointer-to-function

1554

$arg =~ tr/#/,/;

1602

$arg =~ tr/#/,/;

1555

$arg =~ m/[^$]+\(\*?\s*(\w*)\s*$/;

1603

$arg =~ m/[^$]+\(\*?\s*(\w*)\s*$/;

1556

$param = $1;

1604

$param = $1;

1557

$type = $arg;

1605

$type = $arg;

1558

$type =~ s/([^\(]+\(\*?)\s*$param/$1/;

1606

$type =~ s/([^\(]+\(\*?)\s*$param/$1/;

1559

save_struct_actual($param);

1607

save_struct_actual($param);

1560

push_parameter($param, $type, $file);

1608

push_parameter($param, $type, $file);

1561

} elsif ($arg) {

1609

} elsif ($arg) {

1562

$arg =~ s/\s*:\s*/:/g;

1610

$arg =~ s/\s*:\s*/:/g;

1563

$arg =~ s/\s*\[/\[/g;

1611

$arg =~ s/\s*\[/\[/g;

1564

1612

1565

my @args = split('\s*,\s*', $arg);

1613

my @args = split('\s*,\s*', $arg);

1566

if ($args[0] =~ m/\*/) {

1614

if ($args[0] =~ m/\*/) {

1567

$args[0] =~ s/(\*+)\s*/ $1/;

1615

$args[0] =~ s/(\*+)\s*/ $1/;

1568

}

1616

}

1569

1617

1570

my @first_arg;

1618

my @first_arg;

1571

if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {

1619

if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {

1572

shift @args;

1620

shift @args;

1573

push(@first_arg, split('\s+', $1));

1621

push(@first_arg, split('\s+', $1));

1574

push(@first_arg, $2);

1622

push(@first_arg, $2);

1575

} else {

1623

} else {

1576

@first_arg = split('\s+', shift @args);

1624

@first_arg = split('\s+', shift @args);

1577

}

1625

}

1578

1626

1579

unshift(@args, pop @first_arg);

1627

unshift(@args, pop @first_arg);

1580

$type = join " ", @first_arg;

1628

$type = join " ", @first_arg;

1581

1629

1582

foreach $param (@args) {

1630

foreach $param (@args) {

1583

if ($param =~ m/^(\*+)\s*(.*)/) {

1631

if ($param =~ m/^(\*+)\s*(.*)/) {

1584

save_struct_actual($2);

1632

save_struct_actual($2);

1585

push_parameter($2, "$type $1", $file);

1633

push_parameter($2, "$type $1", $file);

1586

}

1634

}

1587

elsif ($param =~ m/(.*?):(\d+)/) {

1635

elsif ($param =~ m/(.*?):(\d+)/) {

1588

if ($type ne "") { # skip unnamed bit-fields

1636

if ($type ne "") { # skip unnamed bit-fields

1589

save_struct_actual($1);

1637

save_struct_actual($1);

1590

push_parameter($1, "$type:$2", $file)

1638

push_parameter($1, "$type:$2", $file)

1591

}

1639

}

1592

}

1640

}

1593

else {

1641

else {

1594

save_struct_actual($param);

1642

save_struct_actual($param);

1595

push_parameter($param, $type, $file);

1643

push_parameter($param, $type, $file);

1596

}

1644

}

1597

}

1645

}

1598

}

1646

}

1599

}

1647

}

1600

}

1648

}

1601

1649

1602

sub push_parameter($$$) {

1650

sub push_parameter($$$) {

1603

my $param = shift;

1651

my $param = shift;

1604

my $type = shift;

1652

my $type = shift;

1605

my $file = shift;

1653

my $file = shift;

1606

1654

1607

if (($anon_struct_union == 1) && ($type eq "") &&

1655

if (($anon_struct_union == 1) && ($type eq "") &&

1608

($param eq "}")) {

1656

($param eq "}")) {

1609

return; # ignore the ending }; from anon. struct/union

1657

return; # ignore the ending }; from anon. struct/union

1610

}

1658

}

1611

1659

1612

$anon_struct_union = 0;

1660

$anon_struct_union = 0;

1613

my $param_name = $param;

1661

my $param_name = $param;

1614

$param_name =~ s/\[.*//;

1662

$param_name =~ s/\[.*//;

1615

1663

1616

if ($type eq "" && $param =~ /\.\.\.$/)

1664

if ($type eq "" && $param =~ /\.\.\.$/)

1617

{

1665

{

1618

if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {

1666

if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {

1619

$parameterdescs{$param} = "variable arguments";

1667

$parameterdescs{$param} = "variable arguments";

1620

}

1668

}

1621

}

1669

}

1622

elsif ($type eq "" && ($param eq "" or $param eq "void"))

1670

elsif ($type eq "" && ($param eq "" or $param eq "void"))

1623

{

1671

{

1624

$param="void";

1672

$param="void";

1625

$parameterdescs{void} = "no arguments";

1673

$parameterdescs{void} = "no arguments";

1626

}

1674

}

1627

elsif ($type eq "" && ($param eq "struct" or $param eq "union"))

1675

elsif ($type eq "" && ($param eq "struct" or $param eq "union"))

1628

# handle unnamed (anonymous) union or struct:

1676

# handle unnamed (anonymous) union or struct:

1629

{

1677

{

1630

$type = $param;

1678

$type = $param;

1631

$param = "{unnamed_" . $param . "}";

1679

$param = "{unnamed_" . $param . "}";

1632

$parameterdescs{$param} = "anonymous\n";

1680

$parameterdescs{$param} = "anonymous\n";

1633

$anon_struct_union = 1;

1681

$anon_struct_union = 1;

1634

}

1682

}

1635

1683

1636

# warn if parameter has no description

1684

# warn if parameter has no description

1637

# (but ignore ones starting with # as these are not parameters

1685

# (but ignore ones starting with # as these are not parameters

1638

# but inline preprocessor statements);

1686

# but inline preprocessor statements);

1639

# also ignore unnamed structs/unions;

1687

# also ignore unnamed structs/unions;

1640

if (!$anon_struct_union) {

1688

if (!$anon_struct_union) {

1641

if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {

1689

if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {

1642

1690

1643

$parameterdescs{$param_name} = $undescribed;

1691

$parameterdescs{$param_name} = $undescribed;

1644

1692

1645

if (($type eq 'function') || ($type eq 'enum')) {

1693

if (($type eq 'function') || ($type eq 'enum')) {

1646

print STDERR "Warning(${file}:$.): Function parameter ".

1694

print STDERR "Warning(${file}:$.): Function parameter ".

1647

"or member '$param' not " .

1695

"or member '$param' not " .

1648

"described in '$declaration_name'\n";

1696

"described in '$declaration_name'\n";

1649

}

1697

}

1650

print STDERR "Warning(${file}:$.):" .

1698

print STDERR "Warning(${file}:$.):" .

1651

" No description found for parameter '$param'\n";

1699

" No description found for parameter '$param'\n";

1652

++$warnings;

1700

++$warnings;

1653

}

1701

}

1654

}

1702

}

1655

1703

1656

# strip spaces from $param so that it is one continous string

1704

# strip spaces from $param so that it is one continous string

1657

# on @parameterlist;

1705

# on @parameterlist;

1658

# this fixes a problem where check_sections() cannot find

1706

# this fixes a problem where check_sections() cannot find

1659

# a parameter like "addr[6 + 2]" because it actually appears

1707

# a parameter like "addr[6 + 2]" because it actually appears

1660

# as "addr[6", "+", "2]" on the parameter list;

1708

# as "addr[6", "+", "2]" on the parameter list;

1661

# but it's better to maintain the param string unchanged for output,

1709

# but it's better to maintain the param string unchanged for output,

1662

# so just weaken the string compare in check_sections() to ignore

1710

# so just weaken the string compare in check_sections() to ignore

1663

# "[blah" in a parameter string;

1711

# "[blah" in a parameter string;

1664

###$param =~ s/\s*//g;

1712

###$param =~ s/\s*//g;

1665

push @parameterlist, $param;

1713

push @parameterlist, $param;

1666

$parametertypes{$param} = $type;

1714

$parametertypes{$param} = $type;

1667

}

1715

}

1668

1716

1669

sub check_sections($$$$$$) {

1717

sub check_sections($$$$$$) {

1670

my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;

1718

my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;

1671

my @sects = split ' ', $sectcheck;

1719

my @sects = split ' ', $sectcheck;

1672

my @prms = split ' ', $prmscheck;

1720

my @prms = split ' ', $prmscheck;

1673

my $err;

1721

my $err;

1674

my ($px, $sx);

1722

my ($px, $sx);

1675

my $prm_clean; # strip trailing "[array size]" and/or beginning "*"

1723

my $prm_clean; # strip trailing "[array size]" and/or beginning "*"

1676

1724

1677

foreach $sx (0 .. $#sects) {

1725

foreach $sx (0 .. $#sects) {

1678

$err = 1;

1726

$err = 1;

1679

foreach $px (0 .. $#prms) {

1727

foreach $px (0 .. $#prms) {

1680

$prm_clean = $prms[$px];

1728

$prm_clean = $prms[$px];

1681

$prm_clean =~ s/\[.*\]//;

1729

$prm_clean =~ s/\[.*\]//;

1682

$prm_clean =~ s/__attribute__\s*$\([a-z,_\*\s\($]*\)\)//i;

1730

$prm_clean =~ s/__attribute__\s*$\([a-z,_\*\s\($]*\)\)//i;

1683

# ignore array size in a parameter string;

1731

# ignore array size in a parameter string;

1684

# however, the original param string may contain

1732

# however, the original param string may contain

1685

# spaces, e.g.: addr[6 + 2]

1733

# spaces, e.g.: addr[6 + 2]

1686

# and this appears in @prms as "addr[6" since the

1734

# and this appears in @prms as "addr[6" since the

1687

# parameter list is split at spaces;

1735

# parameter list is split at spaces;

1688

# hence just ignore "[..." for the sections check;

1736

# hence just ignore "[..." for the sections check;

1689

$prm_clean =~ s/\[.*//;

1737

$prm_clean =~ s/\[.*//;

1690

1738

1691

##$prm_clean =~ s/^\**//;

1739

##$prm_clean =~ s/^\**//;

1692

if ($prm_clean eq $sects[$sx]) {

1740

if ($prm_clean eq $sects[$sx]) {

1693

$err = 0;

1741

$err = 0;

1694

last;

1742

last;

1695

}

1743

}

1696

}

1744

}

1697

if ($err) {

1745

if ($err) {

1698

if ($decl_type eq "function") {

1746

if ($decl_type eq "function") {

1699

print STDERR "Warning(${file}:$.): " .

1747

print STDERR "Warning(${file}:$.): " .

1700

"Excess function parameter " .

1748

"Excess function parameter " .

1701

"'$sects[$sx]' " .

1749

"'$sects[$sx]' " .

1702

"description in '$decl_name'\n";

1750

"description in '$decl_name'\n";

1703

++$warnings;

1751

++$warnings;

1704

} else {

1752

} else {

1705

if ($nested !~ m/\Q$sects[$sx]\E/) {

1753

if ($nested !~ m/\Q$sects[$sx]\E/) {

1706

print STDERR "Warning(${file}:$.): " .

1754

print STDERR "Warning(${file}:$.): " .

1707

"Excess struct/union/enum/typedef member " .

1755

"Excess struct/union/enum/typedef member " .

1708

"'$sects[$sx]' " .

1756

"'$sects[$sx]' " .

1709

"description in '$decl_name'\n";

1757

"description in '$decl_name'\n";

1710

++$warnings;

1758

++$warnings;

1711

}

1759

}

1712

}

1760

}

1713

}

1761

}

1714

}

1762

}

1715

}

1763

}

1716

1764

1717

##

1765

##

1718

# takes a function prototype and the name of the current file being

1766

# takes a function prototype and the name of the current file being

1719

# processed and spits out all the details stored in the global

1767

# processed and spits out all the details stored in the global

1720

# arrays/hashes.

1768

# arrays/hashes.

1721

sub dump_function($$) {

1769

sub dump_function($$) {

1722

my $prototype = shift;

1770

my $prototype = shift;

1723

my $file = shift;

1771

my $file = shift;

1724

1772

1725

$prototype =~ s/^static +//;

1773

$prototype =~ s/^static +//;

1726

$prototype =~ s/^extern +//;

1774

$prototype =~ s/^extern +//;

1727

$prototype =~ s/^asmlinkage +//;

1775

$prototype =~ s/^asmlinkage +//;

1728

$prototype =~ s/^inline +//;

1776

$prototype =~ s/^inline +//;

1729

$prototype =~ s/^__inline__ +//;

1777

$prototype =~ s/^__inline__ +//;

1730

$prototype =~ s/^__inline +//;

1778

$prototype =~ s/^__inline +//;

1731

$prototype =~ s/^__always_inline +//;

1779

$prototype =~ s/^__always_inline +//;

1732

$prototype =~ s/^noinline +//;

1780

$prototype =~ s/^noinline +//;

1733

$prototype =~ s/__devinit +//;

1781

$prototype =~ s/__devinit +//;

1734

$prototype =~ s/__init +//;

1782

$prototype =~ s/__init +//;

1735

$prototype =~ s/__init_or_module +//;

1783

$prototype =~ s/__init_or_module +//;

1736

$prototype =~ s/^#\s*define\s+//; #ak added

1784

$prototype =~ s/^#\s*define\s+//; #ak added

1737

$prototype =~ s/__attribute__\s*$\([a-z,]*$\)//;

1785

$prototype =~ s/__attribute__\s*$\([a-z,]*$\)//;

1738

1786

1739

# Yes, this truly is vile. We are looking for:

1787

# Yes, this truly is vile. We are looking for:

1740

# 1. Return type (may be nothing if we're looking at a macro)

1788

# 1. Return type (may be nothing if we're looking at a macro)

1741

# 2. Function name

1789

# 2. Function name

1742

# 3. Function parameters.

1790

# 3. Function parameters.

1743

#

1791

#

1744

# All the while we have to watch out for function pointer parameters

1792

# All the while we have to watch out for function pointer parameters

1745

# (which IIRC is what the two sections are for), C types (these

1793

# (which IIRC is what the two sections are for), C types (these

1746

# regexps don't even start to express all the possibilities), and

1794

# regexps don't even start to express all the possibilities), and

1747

# so on.

1795

# so on.

1748

#

1796

#

1749

# If you mess with these regexps, it's a good idea to check that

1797

# If you mess with these regexps, it's a good idea to check that

1750

# the following functions' documentation still comes out right:

1798

# the following functions' documentation still comes out right:

1751

# - parport_register_device (function pointer parameters)

1799

# - parport_register_device (function pointer parameters)

1752

# - atomic_set (macro)

1800

# - atomic_set (macro)

1753

# - pci_match_device, __copy_to_user (long return type)

1801

# - pci_match_device, __copy_to_user (long return type)

1754

1802

1755

if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1803

if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1756

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1804

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1757

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1805

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1758

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1806

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1759

$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1807

$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1760

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1808

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1761

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1809

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\(]*)$/ ||

1762

$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1810

$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1763

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1811

$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1764

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1812

$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1765

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1813

$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1766

$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1814

$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1767

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1815

$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1768

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1816

$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1769

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1817

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1770

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1818

$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/ ||

1771

$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/) {

1819

$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*$([^\{]*)$/) {

1772

$return_type = $1;

1820

$return_type = $1;

1773

$declaration_name = $2;

1821

$declaration_name = $2;

1774

my $args = $3;

1822

my $args = $3;

1775

1823

1776

create_parameterlist($args, ',', $file);

1824

create_parameterlist($args, ',', $file);

1777

} else {

1825

} else {

1778

print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";

1826

print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";

1779

++$errors;

1827

++$errors;

1780

return;

1828

return;

1781

}

1829

}

1782

1830

1783

my $prms = join " ", @parameterlist;

1831

my $prms = join " ", @parameterlist;

1784

check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");

1832

check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");

1785

1833

1786

output_declaration($declaration_name,

1834

output_declaration($declaration_name,

1787

'function',

1835

'function',

1788

{'function' => $declaration_name,

1836

{'function' => $declaration_name,

1789

'module' => $modulename,

1837

'module' => $modulename,

1790

'functiontype' => $return_type,

1838

'functiontype' => $return_type,

1791

'parameterlist' => \@parameterlist,

1839

'parameterlist' => \@parameterlist,

1792

'parameterdescs' => \%parameterdescs,

1840

'parameterdescs' => \%parameterdescs,

1793

'parametertypes' => \%parametertypes,

1841

'parametertypes' => \%parametertypes,

1794

'sectionlist' => \@sectionlist,

1842

'sectionlist' => \@sectionlist,

1795

'sections' => \%sections,

1843

'sections' => \%sections,

1796

'purpose' => $declaration_purpose

1844

'purpose' => $declaration_purpose

1797

});

1845

});

1798

}

1846

}

1799

1847

1800

sub process_file($);

1848

sub process_file($);

1801

1849

1802

# Read the file that maps relative names to absolute names for

1850

# Read the file that maps relative names to absolute names for

1803

# separate source and object directories and for shadow trees.

1851

# separate source and object directories and for shadow trees.

1804

if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {

1852

if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {

1805

my ($relname, $absname);

1853

my ($relname, $absname);

1806

while(<SOURCE_MAP>) {

1854

while(<SOURCE_MAP>) {

1807

chop();

1855

chop();

1808

($relname, $absname) = (split())[0..1];

1856

($relname, $absname) = (split())[0..1];

1809

$relname =~ s:^/+::;

1857

$relname =~ s:^/+::;

1810

$source_map{$relname} = $absname;

1858

$source_map{$relname} = $absname;

1811

}

1859

}

1812

close(SOURCE_MAP);

1860

close(SOURCE_MAP);

1813

}

1861

}

1814

1862

1815

foreach (@ARGV) {

1863

foreach (@ARGV) {

1816

chomp;

1864

chomp;

1817

process_file($_);

1865

process_file($_);

1818

}

1866

}

1819

if ($verbose && $errors) {

1867

if ($verbose && $errors) {

1820

print STDERR "$errors errors\n";

1868

print STDERR "$errors errors\n";

1821

}

1869

}

1822

if ($verbose && $warnings) {

1870

if ($verbose && $warnings) {

1823

print STDERR "$warnings warnings\n";

1871

print STDERR "$warnings warnings\n";

1824

}

1872

}

1825

1873

1826

exit($errors);

1874

exit($errors);

1827

1875

1828

sub reset_state {

1876

sub reset_state {

1829

$function = "";

1877

$function = "";

1830

%constants = ();

1878

%constants = ();

1831

%parameterdescs = ();

1879

%parameterdescs = ();

1832

%parametertypes = ();

1880

%parametertypes = ();

1833

@parameterlist = ();

1881

@parameterlist = ();

1834

%sections = ();

1882

%sections = ();

1835

@sectionlist = ();

1883

@sectionlist = ();

1836

$sectcheck = "";

1884

$sectcheck = "";

1837

$struct_actual = "";

1885

$struct_actual = "";

1838

$prototype = "";

1886

$prototype = "";

1839

1887

1840

$state = 0;

1888

$state = 0;

1841

}

1889

}

1842

1890

1843

sub tracepoint_munge($) {

1891

sub tracepoint_munge($) {

1844

my $file = shift;

1892

my $file = shift;

1845

my $tracepointname = 0;

1893

my $tracepointname = 0;

1846

my $tracepointargs = 0;

1894

my $tracepointargs = 0;

1847

1895

1848

if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

1896

if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

1849

$tracepointname = $1;

1897

$tracepointname = $1;

1850

}

1898

}

1851

if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {

1899

if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {

1852

$tracepointname = $1;

1900

$tracepointname = $1;

1853

}

1901

}

1854

if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {

1902

if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {

1855

$tracepointname = $2;

1903

$tracepointname = $2;

1856

}

1904

}

1857

$tracepointname =~ s/^\s+//; #strip leading whitespace

1905

$tracepointname =~ s/^\s+//; #strip leading whitespace

1858

if ($prototype =~ m/TP_PROTO$(.*?)$/) {

1906

if ($prototype =~ m/TP_PROTO$(.*?)$/) {

1859

$tracepointargs = $1;

1907

$tracepointargs = $1;

1860

}

1908

}

1861

if (($tracepointname eq 0) || ($tracepointargs eq 0)) {

1909

if (($tracepointname eq 0) || ($tracepointargs eq 0)) {

1862

print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".

1910

print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".

1863

"$prototype\n";

1911

"$prototype\n";

1864

} else {

1912

} else {

1865

$prototype = "static inline void trace_$tracepointname($tracepointargs)";

1913

$prototype = "static inline void trace_$tracepointname($tracepointargs)";

1866

}

1914

}

1867

}

1915

}

1868

1916

1869

sub syscall_munge() {

1917

sub syscall_munge() {

1870

my $void = 0;

1918

my $void = 0;

1871

1919

1872

$prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs

1920

$prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs

1873

## if ($prototype =~ m/SYSCALL_DEFINE0\s*$\s*(a-zA-Z0-9_)*\s*$/) {

1921

## if ($prototype =~ m/SYSCALL_DEFINE0\s*$\s*(a-zA-Z0-9_)*\s*$/) {

1874

if ($prototype =~ m/SYSCALL_DEFINE0/) {

1922

if ($prototype =~ m/SYSCALL_DEFINE0/) {

1875

$void = 1;

1923

$void = 1;

1876

## $prototype = "long sys_$1(void)";

1924

## $prototype = "long sys_$1(void)";

1877

}

1925

}

1878

1926

1879

$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name

1927

$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name

1880

if ($prototype =~ m/long (sys_.*?),/) {

1928

if ($prototype =~ m/long (sys_.*?),/) {

1881

$prototype =~ s/,/\(/;

1929

$prototype =~ s/,/\(/;

1882

} elsif ($void) {

1930

} elsif ($void) {

1883

$prototype =~ s/\)/$void$/;

1931

$prototype =~ s/\)/$void$/;

1884

}

1932

}

1885

1933

1886

# now delete all of the odd-number commas in $prototype

1934

# now delete all of the odd-number commas in $prototype

1887

# so that arg types & arg names don't have a comma between them

1935

# so that arg types & arg names don't have a comma between them

1888

my $count = 0;

1936

my $count = 0;

1889

my $len = length($prototype);

1937

my $len = length($prototype);

1890

if ($void) {

1938

if ($void) {

1891

$len = 0; # skip the for-loop

1939

$len = 0; # skip the for-loop

1892

}

1940

}

1893

for (my $ix = 0; $ix < $len; $ix++) {

1941

for (my $ix = 0; $ix < $len; $ix++) {

1894

if (substr($prototype, $ix, 1) eq ',') {

1942

if (substr($prototype, $ix, 1) eq ',') {

1895

$count++;

1943

$count++;

1896

if ($count % 2 == 1) {

1944

if ($count % 2 == 1) {

1897

substr($prototype, $ix, 1) = ' ';

1945

substr($prototype, $ix, 1) = ' ';

1898

}

1946

}

1899

}

1947

}

1900

}

1948

}

1901

}

1949

}

1902

1950

1903

sub process_state3_function($$) {

1951

sub process_state3_function($$) {

1904

my $x = shift;

1952

my $x = shift;

1905

my $file = shift;

1953

my $file = shift;

1906

1954

1907

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1955

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1908

1956

1909

if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {

1957

if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {

1910

# do nothing

1958

# do nothing

1911

}

1959

}

1912

elsif ($x =~ /([^\{]*)/) {

1960

elsif ($x =~ /([^\{]*)/) {

1913

$prototype .= $1;

1961

$prototype .= $1;

1914

}

1962

}

1915

1963

1916

if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {

1964

if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {

1917

$prototype =~ s@/\*.*?\*/@@gos; # strip comments.

1965

$prototype =~ s@/\*.*?\*/@@gos; # strip comments.

1918

$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1966

$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1919

$prototype =~ s@^\s+@@gos; # strip leading spaces

1967

$prototype =~ s@^\s+@@gos; # strip leading spaces

1920

if ($prototype =~ /SYSCALL_DEFINE/) {

1968

if ($prototype =~ /SYSCALL_DEFINE/) {

1921

syscall_munge();

1969

syscall_munge();

1922

}

1970

}

1923

if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||

1971

if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||

1924

$prototype =~ /DEFINE_SINGLE_EVENT/)

1972

$prototype =~ /DEFINE_SINGLE_EVENT/)

1925

{

1973

{

1926

tracepoint_munge($file);

1974

tracepoint_munge($file);

1927

}

1975

}

1928

dump_function($prototype, $file);

1976

dump_function($prototype, $file);

1929

reset_state();

1977

reset_state();

1930

}

1978

}

1931

}

1979

}

1932

1980

1933

sub process_state3_type($$) {

1981

sub process_state3_type($$) {

1934

my $x = shift;

1982

my $x = shift;

1935

my $file = shift;

1983

my $file = shift;

1936

1984

1937

$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1985

$x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.

1938

$x =~ s@^\s+@@gos; # strip leading spaces

1986

$x =~ s@^\s+@@gos; # strip leading spaces

1939

$x =~ s@\s+$@@gos; # strip trailing spaces

1987

$x =~ s@\s+$@@gos; # strip trailing spaces

1940

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1988

$x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1941

1989

1942

if ($x =~ /^#/) {

1990

if ($x =~ /^#/) {

1943

# To distinguish preprocessor directive from regular declaration later.

1991

# To distinguish preprocessor directive from regular declaration later.

1944

$x .= ";";

1992

$x .= ";";

1945

}

1993

}

1946

1994

1947

while (1) {

1995

while (1) {

1948

if ( $x =~ /([^{};]*)([{};])(.*)/ ) {

1996

if ( $x =~ /([^{};]*)([{};])(.*)/ ) {

1949

$prototype .= $1 . $2;

1997

$prototype .= $1 . $2;

1950

($2 eq '{') && $brcount++;

1998

($2 eq '{') && $brcount++;

1951

($2 eq '}') && $brcount--;

1999

($2 eq '}') && $brcount--;

1952

if (($2 eq ';') && ($brcount == 0)) {

2000

if (($2 eq ';') && ($brcount == 0)) {

1953

dump_declaration($prototype, $file);

2001

dump_declaration($prototype, $file);

1954

reset_state();

2002

reset_state();

1955

last;

2003

last;

1956

}

2004

}

1957

$x = $3;

2005

$x = $3;

1958

} else {

2006

} else {

1959

$prototype .= $x;

2007

$prototype .= $x;

1960

last;

2008

last;

1961

}

2009

}

1962

}

2010

}

1963

}

2011

}

1964

2012

1965

# xml_escape: replace <, >, and & in the text stream;

2013

# xml_escape: replace <, >, and & in the text stream;

1966

#

2014

#

1967

# however, formatting controls that are generated internally/locally in the

2015

# however, formatting controls that are generated internally/locally in the

1968

# kernel-doc script are not escaped here; instead, they begin life like

2016

# kernel-doc script are not escaped here; instead, they begin life like

1969

# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings

2017

# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings

1970

# are converted to their mnemonic-expected output, without the 4 * '\' & ':',

2018

# are converted to their mnemonic-expected output, without the 4 * '\' & ':',

1971

# just before actual output; (this is done by local_unescape())

2019

# just before actual output; (this is done by local_unescape())

1972

sub xml_escape($) {

2020

sub xml_escape($) {

1973

my $text = shift;

2021

my $text = shift;

1974

if (($output_mode eq "text") || ($output_mode eq "man")) {

2022

if (($output_mode eq "text") || ($output_mode eq "man")) {

1975

return $text;

2023

return $text;

1976

}

2024

}

1977

$text =~ s/\&/\\\\\\amp;/g;

2025

$text =~ s/\&/\\\\\\amp;/g;

1978

$text =~ s/\</\\\\\\lt;/g;

2026

$text =~ s/\</\\\\\\lt;/g;

1979

$text =~ s/\>/\\\\\\gt;/g;

2027

$text =~ s/\>/\\\\\\gt;/g;

1980

return $text;

2028

return $text;

1981

}

2029

}

1982

2030

1983

# convert local escape strings to html

2031

# convert local escape strings to html

1984

# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)

2032

# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)

1985

sub local_unescape($) {

2033

sub local_unescape($) {

1986

my $text = shift;

2034

my $text = shift;

1987

if (($output_mode eq "text") || ($output_mode eq "man")) {

2035

if (($output_mode eq "text") || ($output_mode eq "man")) {

1988

return $text;

2036

return $text;

1989

}

2037

}

1990

$text =~ s/\\\\\\\\lt:/</g;

2038

$text =~ s/\\\\\\\\lt:/</g;

1991

$text =~ s/\\\\\\\\gt:/>/g;

2039

$text =~ s/\\\\\\\\gt:/>/g;

1992

return $text;

2040

return $text;

1993

}

2041

}

1994

2042

1995

sub process_file($) {

2043

sub process_file($) {

1996

my $file;

2044

my $file;

1997

my $identifier;

2045

my $identifier;

1998

my $func;

2046

my $func;

1999

my $descr;

2047

my $descr;

2000

my $in_purpose = 0;

2048

my $in_purpose = 0;

2001

my $initial_section_counter = $section_counter;

2049

my $initial_section_counter = $section_counter;

2002

2050

2003

if (defined($ENV{'SRCTREE'})) {

2051

if (defined($ENV{'SRCTREE'})) {

2004

$file = "$ENV{'SRCTREE'}" . "/" . "@_";

2052

$file = "$ENV{'SRCTREE'}" . "/" . "@_";

2005

}

2053

}

2006

else {

2054

else {

2007

$file = "@_";

2055

$file = "@_";

2008

}

2056

}

2009

if (defined($source_map{$file})) {

2057

if (defined($source_map{$file})) {

2010

$file = $source_map{$file};

2058

$file = $source_map{$file};

2011

}

2059

}

2012

2060

2013

if (!open(IN,"<$file")) {

2061

if (!open(IN,"<$file")) {

2014

print STDERR "Error: Cannot open file $file\n";

2062

print STDERR "Error: Cannot open file $file\n";

2015

++$errors;

2063

++$errors;

2016

return;

2064

return;

2017

}

2065

}

2018

2066

2019

$. = 1;

2067

$. = 1;

2020

2068

2021

$section_counter = 0;

2069

$section_counter = 0;

2022

while (<IN>) {

2070

while (<IN>) {

2023

if ($state == 0) {

2071

if ($state == 0) {

2024

if (/$doc_start/o) {

2072

if (/$doc_start/o) {

2025

$state = 1; # next line is always the function name

2073

$state = 1; # next line is always the function name

2026

$in_doc_sect = 0;

2074

$in_doc_sect = 0;

2027

}

2075

}

2028

} elsif ($state == 1) { # this line is the function name (always)

2076

} elsif ($state == 1) { # this line is the function name (always)

2029

if (/$doc_block/o) {

2077

if (/$doc_block/o) {

2030

$state = 4;

2078

$state = 4;

2031

$contents = "";

2079

$contents = "";

2032

if ( $1 eq "" ) {

2080

if ( $1 eq "" ) {

2033

$section = $section_intro;

2081

$section = $section_intro;

2034

} else {

2082

} else {

2035

$section = $1;

2083

$section = $1;

2036

}

2084

}

2037

}

2085

}

2038

elsif (/$doc_decl/o) {

2086

elsif (/$doc_decl/o) {

2039

$identifier = $1;

2087

$identifier = $1;

2040

if (/\s*([\w\s]+?)\s*-/) {

2088

if (/\s*([\w\s]+?)\s*-/) {

2041

$identifier = $1;

2089

$identifier = $1;

2042

}

2090

}

2043

2091

2044

$state = 2;

2092

$state = 2;

2045

if (/-(.*)/) {

2093

if (/-(.*)/) {

2046

# strip leading/trailing/multiple spaces

2094

# strip leading/trailing/multiple spaces

2047

$descr= $1;

2095

$descr= $1;

2048

$descr =~ s/^\s*//;

2096

$descr =~ s/^\s*//;

2049

$descr =~ s/\s*$//;

2097

$descr =~ s/\s*$//;

2050

$descr =~ s/\s+/ /;

2098

$descr =~ s/\s+/ /;

2051

$declaration_purpose = xml_escape($descr);

2099

$declaration_purpose = xml_escape($descr);

2052

$in_purpose = 1;

2100

$in_purpose = 1;

2053

} else {

2101

} else {

2054

$declaration_purpose = "";

2102

$declaration_purpose = "";

2055

}

2103

}

2056

2104

2057

if (($declaration_purpose eq "") && $verbose) {

2105

if (($declaration_purpose eq "") && $verbose) {

2058

print STDERR "Warning(${file}:$.): missing initial short description on line:\n";

2106

print STDERR "Warning(${file}:$.): missing initial short description on line:\n";

2059

print STDERR $_;

2107

print STDERR $_;

2060

++$warnings;

2108

++$warnings;

2061

}

2109

}

2062

2110

2063

if ($identifier =~ m/^struct/) {

2111

if ($identifier =~ m/^struct/) {

2064

$decl_type = 'struct';

2112

$decl_type = 'struct';

2065

} elsif ($identifier =~ m/^union/) {

2113

} elsif ($identifier =~ m/^union/) {

2066

$decl_type = 'union';

2114

$decl_type = 'union';

2067

} elsif ($identifier =~ m/^enum/) {

2115

} elsif ($identifier =~ m/^enum/) {

2068

$decl_type = 'enum';

2116

$decl_type = 'enum';

2069

} elsif ($identifier =~ m/^typedef/) {

2117

} elsif ($identifier =~ m/^typedef/) {

2070

$decl_type = 'typedef';

2118

$decl_type = 'typedef';

2071

} else {

2119

} else {

2072

$decl_type = 'function';

2120

$decl_type = 'function';

2073

}

2121

}

2074

2122

2075

if ($verbose) {

2123

if ($verbose) {

2076

print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";

2124

print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";

2077

}

2125

}

2078

} else {

2126

} else {

2079

print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",

2127

print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",

2080

" - I thought it was a doc line\n";

2128

" - I thought it was a doc line\n";

2081

++$warnings;

2129

++$warnings;

2082

$state = 0;

2130

$state = 0;

2083

}

2131

}

2084

} elsif ($state == 2) { # look for head: lines, and include content

2132

} elsif ($state == 2) { # look for head: lines, and include content

2085

if (/$doc_sect/o) {

2133

if (/$doc_sect/o) {

2086

$newsection = $1;

2134

$newsection = $1;

2087

$newcontents = $2;

2135

$newcontents = $2;

2088

2136

2089

if (($contents ne "") && ($contents ne "\n")) {

2137

if (($contents ne "") && ($contents ne "\n")) {

2090

if (!$in_doc_sect && $verbose) {

2138

if (!$in_doc_sect && $verbose) {

2091

print STDERR "Warning(${file}:$.): contents before sections\n";

2139

print STDERR "Warning(${file}:$.): contents before sections\n";

2092

++$warnings;

2140

++$warnings;

2093

}

2141

}

2094

dump_section($file, $section, xml_escape($contents));

2142

dump_section($file, $section, xml_escape($contents));

2095

$section = $section_default;

2143

$section = $section_default;

2096

}

2144

}

2097

2145

2098

$in_doc_sect = 1;

2146

$in_doc_sect = 1;

2099

$in_purpose = 0;

2147

$in_purpose = 0;

2100

$contents = $newcontents;

2148

$contents = $newcontents;

2101

if ($contents ne "") {

2149

if ($contents ne "") {

2102

while ((substr($contents, 0, 1) eq " ") ||

2150

while ((substr($contents, 0, 1) eq " ") ||

2103

substr($contents, 0, 1) eq "\t") {

2151

substr($contents, 0, 1) eq "\t") {

2104

$contents = substr($contents, 1);

2152

$contents = substr($contents, 1);

2105

}

2153

}

2106

$contents .= "\n";

2154

$contents .= "\n";

2107

}

2155

}

2108

$section = $newsection;

2156

$section = $newsection;

2109

} elsif (/$doc_end/) {

2157

} elsif (/$doc_end/) {

2110

2158

2111

if (($contents ne "") && ($contents ne "\n")) {

2159

if (($contents ne "") && ($contents ne "\n")) {

2112

dump_section($file, $section, xml_escape($contents));

2160

dump_section($file, $section, xml_escape($contents));

2113

$section = $section_default;

2161

$section = $section_default;

2114

$contents = "";

2162

$contents = "";

2115

}

2163

}

2116

# look for doc_com + <text> + doc_end:

2164

# look for doc_com + <text> + doc_end:

2117

if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {

2165

if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {

2118

print STDERR "Warning(${file}:$.): suspicious ending line: $_";

2166

print STDERR "Warning(${file}:$.): suspicious ending line: $_";

2119

++$warnings;

2167

++$warnings;

2120

}

2168

}

2121

2169

2122

$prototype = "";

2170

$prototype = "";

2123

$state = 3;

2171

$state = 3;

2124

$brcount = 0;

2172

$brcount = 0;

2125

# print STDERR "end of doc comment, looking for prototype\n";

2173

# print STDERR "end of doc comment, looking for prototype\n";

2126

} elsif (/$doc_content/) {

2174

} elsif (/$doc_content/) {

2127

# miguel-style comment kludge, look for blank lines after

2175

# miguel-style comment kludge, look for blank lines after

2128

# @parameter line to signify start of description

2176

# @parameter line to signify start of description

2129

if ($1 eq "") {

2177

if ($1 eq "") {

2130

if ($section =~ m/^@/ || $section eq $section_context) {

2178

if ($section =~ m/^@/ || $section eq $section_context) {

2131

dump_section($file, $section, xml_escape($contents));

2179

dump_section($file, $section, xml_escape($contents));

2132

$section = $section_default;

2180

$section = $section_default;

2133

$contents = "";

2181

$contents = "";

2134

} else {

2182

} else {

2135

$contents .= "\n";

2183

$contents .= "\n";

2136

}

2184

}

2137

$in_purpose = 0;

2185

$in_purpose = 0;

2138

} elsif ($in_purpose == 1) {

2186

} elsif ($in_purpose == 1) {

2139

# Continued declaration purpose

2187

# Continued declaration purpose

2140

chomp($declaration_purpose);

2188

chomp($declaration_purpose);

2141

$declaration_purpose .= " " . xml_escape($1);

2189

$declaration_purpose .= " " . xml_escape($1);

2142

} else {

2190

} else {

2143

$contents .= $1 . "\n";

2191

$contents .= $1 . "\n";

2144

}

2192

}

2145

} else {

2193

} else {

2146

# i dont know - bad line? ignore.

2194

# i dont know - bad line? ignore.

2147

print STDERR "Warning(${file}:$.): bad line: $_";

2195

print STDERR "Warning(${file}:$.): bad line: $_";

2148

++$warnings;

2196

++$warnings;

2149

}

2197

}

2150

} elsif ($state == 3) { # scanning for function '{' (end of prototype)

2198

} elsif ($state == 3) { # scanning for function '{' (end of prototype)

2151

if ($decl_type eq 'function') {

2199

if ($decl_type eq 'function') {

2152

process_state3_function($_, $file);

2200

process_state3_function($_, $file);

2153

} else {

2201

} else {

2154

process_state3_type($_, $file);

2202

process_state3_type($_, $file);

2155

}

2203

}

2156

} elsif ($state == 4) {

2204

} elsif ($state == 4) {

2157

# Documentation block

2205

# Documentation block

2158

if (/$doc_block/) {

2206

if (/$doc_block/) {

2159

dump_doc_section($file, $section, xml_escape($contents));

2207

dump_doc_section($file, $section, xml_escape($contents));

2160

$contents = "";

2208

$contents = "";

2161

$function = "";

2209

$function = "";

2162

%constants = ();

2210

%constants = ();

2163

%parameterdescs = ();

2211

%parameterdescs = ();

2164

%parametertypes = ();

2212

%parametertypes = ();

2165

@parameterlist = ();

2213

@parameterlist = ();

2166

%sections = ();

2214

%sections = ();

2167

@sectionlist = ();

2215

@sectionlist = ();

2168

$prototype = "";

2216

$prototype = "";

2169

if ( $1 eq "" ) {

2217

if ( $1 eq "" ) {

2170

$section = $section_intro;

2218

$section = $section_intro;

2171

} else {

2219

} else {

2172

$section = $1;

2220

$section = $1;

2173

}

2221

}

2174

}

2222

}

2175

elsif (/$doc_end/)

2223

elsif (/$doc_end/)

2176

{

2224

{

2177

dump_doc_section($file, $section, xml_escape($contents));

2225

dump_doc_section($file, $section, xml_escape($contents));

2178

$contents = "";

2226

$contents = "";

2179

$function = "";

2227

$function = "";

2180

%constants = ();

2228

%constants = ();

2181

%parameterdescs = ();

2229

%parameterdescs = ();

2182

%parametertypes = ();

2230

%parametertypes = ();

2183

@parameterlist = ();

2231

@parameterlist = ();

2184

%sections = ();

2232

%sections = ();

2185

@sectionlist = ();

2233

@sectionlist = ();

2186

$prototype = "";

2234

$prototype = "";

2187

$state = 0;

2235

$state = 0;

2188

}

2236

}

2189

elsif (/$doc_content/)

2237

elsif (/$doc_content/)

2190

{

2238

{

2191

if ( $1 eq "" )

2239

if ( $1 eq "" )

2192

{

2240

{

2193

$contents .= $blankline;

2241

$contents .= $blankline;

2194

}

2242

}

2195

else

2243

else

2196

{

2244

{

2197

$contents .= $1 . "\n";

2245

$contents .= $1 . "\n";

2198

}

2246

}

2199

}

2247

}

2200

}

2248

}

2201

}

2249

}

2202

if ($initial_section_counter == $section_counter) {

2250

if ($initial_section_counter == $section_counter) {

2203

print STDERR "Warning(${file}): no structured comments found\n";

2251

print STDERR "Warning(${file}): no structured comments found\n";

2204

if ($output_mode eq "xml") {

2252

if ($output_mode eq "xml") {

2205

# The template wants at least one RefEntry here; make one.

2253

# The template wants at least one RefEntry here; make one.

2206

print "<refentry>\n";

2254

print "<refentry>\n";

2207

print " <refnamediv>\n";

2255

print " <refnamediv>\n";

2208

print " <refname>\n";

2256

print " <refname>\n";

2209

print " ${file}\n";

2257

print " ${file}\n";

2210

print " </refname>\n";

2258

print " </refname>\n";

2211

print " <refpurpose>\n";

2259

print " <refpurpose>\n";

2212

print " Document generation inconsistency\n";

2260

print " Document generation inconsistency\n";

2213

print " </refpurpose>\n";

2261

print " </refpurpose>\n";

2214

print " </refnamediv>\n";

2262

print " </refnamediv>\n";

2215

print " <refsect1>\n";

2263

print " <refsect1>\n";

2216

print " <title>\n";

2264

print " <title>\n";

2217

print " Oops\n";

2265

print " Oops\n";

2218

print " </title>\n";

2266

print " </title>\n";

2219

print " <warning>\n";

2267

print " <warning>\n";

2220

print " <para>\n";

2268

print " <para>\n";

2221

print " The template for this document tried to insert\n";

2269

print " The template for this document tried to insert\n";

2222

print " the structured comment from the file\n";

2270

print " the structured comment from the file\n";

2223

print " <filename>${file}</filename> at this point,\n";

2271

print " <filename>${file}</filename> at this point,\n";

2224

print " but none was found.\n";

2272

print " but none was found.\n";

2225

print " This dummy section is inserted to allow\n";

2273

print " This dummy section is inserted to allow\n";

2226

print " generation to continue.\n";

2274

print " generation to continue.\n";

2227

print " </para>\n";

2275

print " </para>\n";

2228

print " </warning>\n";

2276

print " </warning>\n";

2229

print " </refsect1>\n";

2277

print " </refsect1>\n";

2230

print "</refentry>\n";

2278

print "</refentry>\n";

2231

}

2279

}

2232

}

2280

}

2233

}

2281

}

2234

2282

GITLAB

Eric Lee / smarc-fsl-linux-kernel

docbook: warn on unused doc entries

 kernel-doc nano-HOWTO
 =====================
 How to format kernel-doc comments
 ---------------------------------
 In order to provide embedded, 'C' friendly, easy to maintain,
 but consistent and extractable documentation of the functions and
 data structures in the Linux kernel, the Linux kernel has adopted
 a consistent style for documenting functions and their parameters,
 and structures and their members.
 The format for this documentation is called the kernel-doc format.
 It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
 This style embeds the documentation within the source files, using
 a few simple conventions.  The scripts/kernel-doc perl script, some
 SGML templates in Documentation/DocBook, and other tools understand
 these conventions, and are used to extract this embedded documentation
 into various documents.
 In order to provide good documentation of kernel functions and data
 structures, please use the following conventions to format your
 kernel-doc comments in Linux kernel source.
 We definitely need kernel-doc formatted documentation for functions
 that are exported to loadable modules using EXPORT_SYMBOL.
 We also look to provide kernel-doc formatted documentation for
 functions externally visible to other kernel files (not marked
 "static").
 We also recommend providing kernel-doc formatted documentation
 for private (file "static") routines, for consistency of kernel
 source code layout.  But this is lower priority and at the
 discretion of the MAINTAINER of that kernel source file.
 Data structures visible in kernel include files should also be
 documented using kernel-doc formatted comments.
 The opening comment mark "/**" is reserved for kernel-doc comments.
 Only comments so marked will be considered by the kernel-doc scripts,
 and any comment so marked must be in kernel-doc format.  Do not use
 "/**" to be begin a comment block unless the comment block contains
 kernel-doc formatted comments.  The closing comment marker for
 kernel-doc comments can be either "*/" or "**/", but "*/" is
 preferred in the Linux kernel tree.
 Kernel-doc comments should be placed just before the function
 or data structure being described.
 Example kernel-doc function comment:
 /**
  * foobar() - short function description of foobar
  * @arg1:	Describe the first argument to foobar.
  * @arg2:	Describe the second argument to foobar.
  *		One can provide multiple line descriptions
  *		for arguments.
  *
  * A longer description, with more discussion of the function foobar()
  * that might be useful to those using or modifying it.  Begins with
  * empty comment line, and may include additional embedded empty
  * comment lines.
  *
  * The longer description can have multiple paragraphs.
  */
 The short description following the subject can span multiple lines
 and ends with an @argument description, an empty line or the end of
 the comment block.
 The @argument descriptions must begin on the very next line following
 this opening short function description line, with no intervening
 empty comment lines.
 If a function parameter is "..." (varargs), it should be listed in
 kernel-doc notation as:
  * @...: description
 Example kernel-doc data structure comment.
 /**
  * struct blah - the basic blah structure
  * @mem1:	describe the first member of struct blah
  * @mem2:	describe the second member of struct blah,
  *		perhaps with more lines and words.
  *
  * Longer description of this structure.
  */
 The kernel-doc function comments describe each parameter to the
 function, in order, with the @name lines.
 The kernel-doc data structure comments describe each structure member
 in the data structure, with the @name lines.
 The longer description formatting is "reflowed", losing your line
 breaks.  So presenting carefully formatted lists within these
 descriptions won't work so well; derived documentation will lose
 the formatting.
 See the section below "How to add extractable documentation to your
 source files" for more details and notes on how to format kernel-doc
 comments.
 Components of the kernel-doc system
 -----------------------------------
 Many places in the source tree have extractable documentation in the
 form of block comments above functions.  The components of this system
 are:
 - scripts/kernel-doc
   This is a perl script that hunts for the block comments and can mark
   them up directly into DocBook, man, text, and HTML. (No, not
   texinfo.)
 - Documentation/DocBook/*.tmpl
   These are SGML template files, which are normal SGML files with
   special place-holders for where the extracted documentation should
   go.
 - scripts/basic/docproc.c
   This is a program for converting SGML template files into SGML
   files. When a file is referenced it is searched for symbols
   exported (EXPORT_SYMBOL), to be able to distinguish between internal
   and external functions.
   It invokes kernel-doc, giving it the list of functions that
   are to be documented.
   Additionally it is used to scan the SGML template files to locate
   all the files referenced herein. This is used to generate dependency
   information as used by make.
 - Makefile
   The targets 'sgmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
   to build DocBook files, PostScript files, PDF files, and html files
   in Documentation/DocBook.
 - Documentation/DocBook/Makefile
   This is where C files are associated with SGML templates.
 How to extract the documentation
 --------------------------------
 If you just want to read the ready-made books on the various
 subsystems (see Documentation/DocBook/*.tmpl), just type 'make
 psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
 preference.  If you would rather read a different format, you can type
 'make sgmldocs' and then use DocBook tools to convert
 Documentation/DocBook/*.sgml to a format of your choice (for example,
 'db2html ...' if 'make htmldocs' was not defined).
 If you want to see man pages instead, you can do this:
 $ cd linux
 $ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
 $ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man
 Here is split-man.pl:
 -->
 #!/usr/bin/perl
 if ($#ARGV < 0) {
    die "where do I put the results?\n";
 }
 mkdir $ARGV[0],0777;
 $state = 0;
 while (<STDIN>) {
     if (/^\.TH \"[^\"]*\" 9 \"([^\"]*)\"/) {
 	if ($state == 1) { close OUT }
 	$state = 1;
 	$fn = "$ARGV[0]/$1.9";
 	print STDERR "Creating $fn\n";
 	open OUT, ">$fn" or die "can't open $fn: $!\n";
 	print OUT $_;
     } elsif ($state != 0) {
 	print OUT $_;
     }
 }
 close OUT;
 <--
 If you just want to view the documentation for one function in one
 file, you can do this:
 $ scripts/kernel-doc -man -function fn file | nroff -man | less
 or this:
 $ scripts/kernel-doc -text -function fn file
 How to add extractable documentation to your source files
 ---------------------------------------------------------
 The format of the block comment is like this:
 /**
  * function_name(:)? (- short description)?
 (* @parameterx(space)*: (description of parameter x)?)*
 (* a blank line)?
  * (Description:)? (Description of function)?
  * (section header: (section description)? )*
 (*)?*/
 All "description" text can span multiple lines, although the
 function_name & its short description are traditionally on a single line.
 Description text may also contain blank lines (i.e., lines that contain
 only a "*").
 "section header:" names must be unique per function (or struct,
 union, typedef, enum).
 Avoid putting a spurious blank line after the function name, or else the
 description will be repeated!
 All descriptive text is further processed, scanning for the following special
 patterns, which are highlighted appropriately.
 'funcname()' - function
 '$ENVVAR' - environment variable
 '&struct_name' - name of a structure (up to two words including 'struct')
 '@parameter' - name of a parameter
 '%CONST' - name of a constant.
 NOTE 1:  The multi-line descriptive text you provide does *not* recognize
 line breaks, so if you try to format some text nicely, as in:
   Return codes
     0 - cool
     1 - invalid arg
     2 - out of memory
 this will all run together and produce:
   Return codes 0 - cool 1 - invalid arg 2 - out of memory
 NOTE 2:  If the descriptive text you provide has lines that begin with
 some phrase followed by a colon, each of those phrases will be taken as
 a new section heading, which means you should similarly try to avoid text
 like:
   Return codes:
     0: cool
     1: invalid arg
     2: out of memory
 every line of which would start a new section.  Again, probably not
 what you were after.
 Take a look around the source tree for examples.
 kernel-doc for structs, unions, enums, and typedefs
 ---------------------------------------------------
 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.
 Inside a struct description, you can use the "private:" and "public:"
 comment tags.  Structure fields that are inside a "private:" area
 are not listed in the generated output documentation.  The "private:"
 and "public:" tags must begin immediately following a "/*" comment
 marker.  They may optionally include comments between the ":" and the
 ending "*/" marker.
 Example:
 /**
  * struct my_struct - short description
  * @a: first member
  * @b: second member
  *
  * Longer description
  */
 struct my_struct {
     int a;
     int b;
 /* private: internal use only */
     int c;
 };
 Including documentation blocks in source files
 ----------------------------------------------
 To facilitate having source code and comments close together, you can
 include kernel-doc documentation blocks that are free-form comments
 instead of being kernel-doc for functions, structures, unions,
 enums, or typedefs.  This could be used for something like a
 theory of operation for a driver or library code, for example.
 This is done by using a DOC: section keyword with a section title.  E.g.:
 /**
  * DOC: Theory of Operation
  *
  * The whizbang foobar is a dilly of a gizmo.  It can do whatever you
  * want it to do, at any time.  It reads your mind.  Here's how it works.
  *
  * foo bar splat
  *
  * The only drawback to this gizmo is that is can sometimes damage
  * hardware, software, or its subject(s).
  */
 DOC: sections are used in SGML templates files as indicated below.
 How to make new SGML template files
 -----------------------------------
 SGML template files (*.tmpl) are like normal SGML files, except that
 they can contain escape sequences where extracted documentation should
 be inserted.
 !E<filename> is replaced by the documentation, in <filename>, for
 functions that are exported using EXPORT_SYMBOL: the function list is
 collected from files listed in Documentation/DocBook/Makefile.
 !I<filename> is replaced by the documentation for functions that are
 _not_ exported using EXPORT_SYMBOL.
 !D<filename> is used to name additional files to search for functions
 exported using EXPORT_SYMBOL.
 !F<filename> <function [functions...]> is replaced by the
 documentation, in <filename>, for the functions listed.
 !P<filename> <section title> is replaced by the contents of the DOC:
 section titled <section title> from <filename>.
 Spaces are allowed in <section title>; do not quote the <section title>.
+!C<filename> is replaced by nothing, but makes the tools check that
+all DOC: sections and documented functions, symbols, etc. are used.
+This makes sense to use when you use !F/!P only and want to verify
+that all documentation is included.
 Tim.
 */ <twaugh@redhat.com>

 /*
  *	docproc is a simple preprocessor for the template files
  *      used as placeholders for the kernel internal documentation.
  *	docproc is used for documentation-frontend and
  *      dependency-generator.
  *	The two usages have in common that they require
  *	some knowledge of the .tmpl syntax, therefore they
  *	are kept together.
  *
  *	documentation-frontend
  *		Scans the template file and call kernel-doc for
  *		all occurrences of ![EIF]file
  *		Beforehand each referenced file is scanned for
  *		any symbols that are exported via these macros:
  *			EXPORT_SYMBOL(), EXPORT_SYMBOL_GPL(), &
  *			EXPORT_SYMBOL_GPL_FUTURE()
  *		This is used to create proper -function and
  *		-nofunction arguments in calls to kernel-doc.
  *		Usage: docproc doc file.tmpl
  *
  *	dependency-generator:
  *		Scans the template file and list all files
  *		referenced in a format recognized by make.
  *		Usage:	docproc depend file.tmpl
  *		Writes dependency information to stdout
  *		in the following format:
  *		file.tmpl src.c	src2.c
  *		The filenames are obtained from the following constructs:
  *		!Efilename
  *		!Ifilename
  *		!Dfilename
  *		!Ffilename
  *		!Pfilename
  *
  */
+#define _GNU_SOURCE
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <ctype.h>
 #include <unistd.h>
 #include <limits.h>
+#include <errno.h>
 #include <sys/types.h>
 #include <sys/wait.h>
 /* exitstatus is used to keep track of any failing calls to kernel-doc,
  * but execution continues. */
 int exitstatus = 0;
 typedef void DFL(char *);
 DFL *defaultline;
 typedef void FILEONLY(char * file);
 FILEONLY *internalfunctions;
 FILEONLY *externalfunctions;
 FILEONLY *symbolsonly;
+FILEONLY *findall;
 typedef void FILELINE(char * file, char * line);
 FILELINE * singlefunctions;
 FILELINE * entity_system;
 FILELINE * docsection;
 #define MAXLINESZ     2048
 #define MAXFILES      250
 #define KERNELDOCPATH "scripts/"
 #define KERNELDOC     "kernel-doc"
 #define DOCBOOK       "-docbook"
+#define LIST          "-list"
 #define FUNCTION      "-function"
 #define NOFUNCTION    "-nofunction"
 #define NODOCSECTIONS "-no-doc-sections"
 static char *srctree, *kernsrctree;
+static char **all_list = NULL;
+static int all_list_len = 0;
+static void consume_symbol(const char *sym)
+{
+	int i;
+	for (i = 0; i < all_list_len; i++) {
+		if (!all_list[i])
+			continue;
+		if (strcmp(sym, all_list[i]))
+			continue;
+		all_list[i] = NULL;
+		break;
+	}
+}
 static void usage (void)
 {
 	fprintf(stderr, "Usage: docproc {doc|depend} file\n");
 	fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
 	fprintf(stderr, "doc: frontend when generating kernel documentation\n");
 	fprintf(stderr, "depend: generate list of files referenced within file\n");
 	fprintf(stderr, "Environment variable SRCTREE: absolute path to sources.\n");
 	fprintf(stderr, "                     KBUILD_SRC: absolute path to kernel source tree.\n");
 }
 /*
  * Execute kernel-doc with parameters given in svec
  */
 static void exec_kernel_doc(char **svec)
 {
 	pid_t pid;
 	int ret;
 	char real_filename[PATH_MAX + 1];
 	/* Make sure output generated so far are flushed */
 	fflush(stdout);
 	switch (pid=fork()) {
 		case -1:
 			perror("fork");
 			exit(1);
 		case  0:
 			memset(real_filename, 0, sizeof(real_filename));
 			strncat(real_filename, kernsrctree, PATH_MAX);
 			strncat(real_filename, "/" KERNELDOCPATH KERNELDOC,
 					PATH_MAX - strlen(real_filename));
 			execvp(real_filename, svec);
 			fprintf(stderr, "exec ");
 			perror(real_filename);
 			exit(1);
 		default:
 			waitpid(pid, &ret ,0);
 	}
 	if (WIFEXITED(ret))
 		exitstatus |= WEXITSTATUS(ret);
 	else
 		exitstatus = 0xff;
 }
 /* Types used to create list of all exported symbols in a number of files */
 struct symbols
 {
 	char *name;
 };
 struct symfile
 {
 	char *filename;
 	struct symbols *symbollist;
 	int symbolcnt;
 };
 struct symfile symfilelist[MAXFILES];
 int symfilecnt = 0;
 static void add_new_symbol(struct symfile *sym, char * symname)
 {
 	sym->symbollist =
           realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *));
 	sym->symbollist[sym->symbolcnt++].name = strdup(symname);
 }
 /* Add a filename to the list */
 static struct symfile * add_new_file(char * filename)
 {
 	symfilelist[symfilecnt++].filename = strdup(filename);
 	return &symfilelist[symfilecnt - 1];
 }
 /* Check if file already are present in the list */
 static struct symfile * filename_exist(char * filename)
 {
 	int i;
 	for (i=0; i < symfilecnt; i++)
 		if (strcmp(symfilelist[i].filename, filename) == 0)
 			return &symfilelist[i];
 	return NULL;
 }
 /*
  * List all files referenced within the template file.
  * Files are separated by tabs.
  */
 static void adddep(char * file)		   { printf("\t%s", file); }
 static void adddep2(char * file, char * line)     { line = line; adddep(file); }
 static void noaction(char * line)		   { line = line; }
 static void noaction2(char * file, char * line)   { file = file; line = line; }
 /* Echo the line without further action */
 static void printline(char * line)               { printf("%s", line); }
 /*
  * Find all symbols in filename that are exported with EXPORT_SYMBOL &
  * EXPORT_SYMBOL_GPL (& EXPORT_SYMBOL_GPL_FUTURE implicitly).
  * All symbols located are stored in symfilelist.
  */
 static void find_export_symbols(char * filename)
 {
 	FILE * fp;
 	struct symfile *sym;
 	char line[MAXLINESZ];
 	if (filename_exist(filename) == NULL) {
 		char real_filename[PATH_MAX + 1];
 		memset(real_filename, 0, sizeof(real_filename));
 		strncat(real_filename, srctree, PATH_MAX);
 		strncat(real_filename, "/", PATH_MAX - strlen(real_filename));
 		strncat(real_filename, filename,
 				PATH_MAX - strlen(real_filename));
 		sym = add_new_file(filename);
 		fp = fopen(real_filename, "r");
 		if (fp == NULL)
 		{
 			fprintf(stderr, "docproc: ");
 			perror(real_filename);
 			exit(1);
 		}
 		while (fgets(line, MAXLINESZ, fp)) {
 			char *p;
 			char *e;
 			if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) ||
                             ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) {
 				/* Skip EXPORT_SYMBOL{_GPL} */
 				while (isalnum(*p) || *p == '_')
 					p++;
 				/* Remove parentheses & additional whitespace */
 				while (isspace(*p))
 					p++;
 				if (*p != '(')
 					continue; /* Syntax error? */
 				else
 					p++;
 				while (isspace(*p))
 					p++;
 				e = p;
 				while (isalnum(*e) || *e == '_')
 					e++;
 				*e = '\0';
 				add_new_symbol(sym, p);
 			}
 		}
 		fclose(fp);
 	}
 }
 /*
  * Document all external or internal functions in a file.
  * Call kernel-doc with following parameters:
  * kernel-doc -docbook -nofunction function_name1 filename
  * Function names are obtained from all the src files
  * by find_export_symbols.
  * intfunc uses -nofunction
  * extfunc uses -function
  */
 static void docfunctions(char * filename, char * type)
 {
 	int i,j;
 	int symcnt = 0;
 	int idx = 0;
 	char **vec;
 	for (i=0; i <= symfilecnt; i++)
 		symcnt += symfilelist[i].symbolcnt;
 	vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *));
 	if (vec == NULL) {
 		perror("docproc: ");
 		exit(1);
 	}
 	vec[idx++] = KERNELDOC;
 	vec[idx++] = DOCBOOK;
 	vec[idx++] = NODOCSECTIONS;
 	for (i=0; i < symfilecnt; i++) {
 		struct symfile * sym = &symfilelist[i];
 		for (j=0; j < sym->symbolcnt; j++) {
 			vec[idx++]     = type;
+			consume_symbol(sym->symbollist[j].name);
 			vec[idx++] = sym->symbollist[j].name;
 		}
 	}
 	vec[idx++]     = filename;
 	vec[idx] = NULL;
 	printf("<!-- %s -->\n", filename);
 	exec_kernel_doc(vec);
 	fflush(stdout);
 	free(vec);
 }
 static void intfunc(char * filename) {	docfunctions(filename, NOFUNCTION); }
 static void extfunc(char * filename) { docfunctions(filename, FUNCTION);   }
 /*
  * Document specific function(s) in a file.
  * Call kernel-doc with the following parameters:
  * kernel-doc -docbook -function function1 [-function function2]
  */
 static void singfunc(char * filename, char * line)
 {
 	char *vec[200]; /* Enough for specific functions */
         int i, idx = 0;
         int startofsym = 1;
 	vec[idx++] = KERNELDOC;
 	vec[idx++] = DOCBOOK;
         /* Split line up in individual parameters preceded by FUNCTION */
         for (i=0; line[i]; i++) {
                 if (isspace(line[i])) {
                         line[i] = '\0';
                         startofsym = 1;
                         continue;
                 }
                 if (startofsym) {
                         startofsym = 0;
                         vec[idx++] = FUNCTION;
                         vec[idx++] = &line[i];
                 }
         }
+	for (i = 0; i < idx; i++) {
+        	if (strcmp(vec[i], FUNCTION))
+        		continue;
+		consume_symbol(vec[i + 1]);
+	}
 	vec[idx++] = filename;
 	vec[idx] = NULL;
 	exec_kernel_doc(vec);
 }
 /*
  * Insert specific documentation section from a file.
  * Call kernel-doc with the following parameters:
  * kernel-doc -docbook -function "doc section" filename
  */
 static void docsect(char *filename, char *line)
 {
 	char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */
 	char *s;
 	for (s = line; *s; s++)
 		if (*s == '\n')
 			*s = '\0';
+	asprintf(&s, "DOC: %s", line);
+	consume_symbol(s);
+	free(s);
 	vec[0] = KERNELDOC;
 	vec[1] = DOCBOOK;
 	vec[2] = FUNCTION;
 	vec[3] = line;
 	vec[4] = filename;
 	vec[5] = NULL;
 	exec_kernel_doc(vec);
 }
+static void find_all_symbols(char *filename)
+{
+	char *vec[4]; /* kerneldoc -list file NULL */
+	pid_t pid;
+	int ret, i, count, start;
+	char real_filename[PATH_MAX + 1];
+	int pipefd[2];
+	char *data, *str;
+	size_t data_len = 0;
+	vec[0] = KERNELDOC;
+	vec[1] = LIST;
+	vec[2] = filename;
+	vec[3] = NULL;
+	if (pipe(pipefd)) {
+		perror("pipe");
+		exit(1);
+	}
+	switch (pid=fork()) {
+		case -1:
+			perror("fork");
+			exit(1);
+		case  0:
+			close(pipefd[0]);
+			dup2(pipefd[1], 1);
+			memset(real_filename, 0, sizeof(real_filename));
+			strncat(real_filename, kernsrctree, PATH_MAX);
+			strncat(real_filename, "/" KERNELDOCPATH KERNELDOC,
+					PATH_MAX - strlen(real_filename));
+			execvp(real_filename, vec);
+			fprintf(stderr, "exec ");
+			perror(real_filename);
+			exit(1);
+		default:
+			close(pipefd[1]);
+			data = malloc(4096);
+			do {
+				while ((ret = read(pipefd[0],
+						   data + data_len,
+						   4096)) > 0) {
+					data_len += ret;
+					data = realloc(data, data_len + 4096);
+				}
+			} while (ret == -EAGAIN);
+			if (ret != 0) {
+				perror("read");
+				exit(1);
+			}
+			waitpid(pid, &ret ,0);
+	}
+	if (WIFEXITED(ret))
+		exitstatus |= WEXITSTATUS(ret);
+	else
+		exitstatus = 0xff;
+	count = 0;
+	/* poor man's strtok, but with counting */
+	for (i = 0; i < data_len; i++) {
+		if (data[i] == '\n') {
+			count++;
+			data[i] = '\0';
+		}
+	}
+	start = all_list_len;
+	all_list_len += count;
+	all_list = realloc(all_list, sizeof(char *) * all_list_len);
+	str = data;
+	for (i = 0; i < data_len && start != all_list_len; i++) {
+		if (data[i] == '\0') {
+			all_list[start] = str;
+			str = data + i + 1;
+			start++;
+		}
+	}
+}
 /*
  * Parse file, calling action specific functions for:
  * 1) Lines containing !E
  * 2) Lines containing !I
  * 3) Lines containing !D
  * 4) Lines containing !F
  * 5) Lines containing !P
- * 6) Default lines - lines not matching the above
+ * 6) Lines containing !C
+ * 7) Default lines - lines not matching the above
  */
 static void parse_file(FILE *infile)
 {
 	char line[MAXLINESZ];
 	char * s;
 	while (fgets(line, MAXLINESZ, infile)) {
 		if (line[0] == '!') {
 			s = line + 2;
 			switch (line[1]) {
 				case 'E':
 					while (*s && !isspace(*s)) s++;
 					*s = '\0';
 					externalfunctions(line+2);
 					break;
 				case 'I':
 					while (*s && !isspace(*s)) s++;
 					*s = '\0';
 					internalfunctions(line+2);
 					break;
 				case 'D':
 					while (*s && !isspace(*s)) s++;
                                         *s = '\0';
                                         symbolsonly(line+2);
                                         break;
 				case 'F':
 					/* filename */
 					while (*s && !isspace(*s)) s++;
 					*s++ = '\0';
                                         /* function names */
 					while (isspace(*s))
 						s++;
 					singlefunctions(line +2, s);
 					break;
 				case 'P':
 					/* filename */
 					while (*s && !isspace(*s)) s++;
 					*s++ = '\0';
 					/* DOC: section name */
 					while (isspace(*s))
 						s++;
 					docsection(line + 2, s);
 					break;
+				case 'C':
+					while (*s && !isspace(*s)) s++;
+					*s = '\0';
+					if (findall)
+						findall(line+2);
+					break;
 				default:
 					defaultline(line);
 			}
 		}
 		else {
 			defaultline(line);
 		}
 	}
 	fflush(stdout);
 }
 int main(int argc, char *argv[])
 {
 	FILE * infile;
+	int i;
 	srctree = getenv("SRCTREE");
 	if (!srctree)
 		srctree = getcwd(NULL, 0);
 	kernsrctree = getenv("KBUILD_SRC");
 	if (!kernsrctree || !*kernsrctree)
 		kernsrctree = srctree;
 	if (argc != 3) {
 		usage();
 		exit(1);
 	}
 	/* Open file, exit on error */
 	infile = fopen(argv[2], "r");
         if (infile == NULL) {
                 fprintf(stderr, "docproc: ");
                 perror(argv[2]);
                 exit(2);
         }
 	if (strcmp("doc", argv[1]) == 0)
 	{
 		/* Need to do this in two passes.
 		 * First pass is used to collect all symbols exported
 		 * in the various files;
 		 * Second pass generate the documentation.
 		 * This is required because some functions are declared
 		 * and exported in different files :-((
 		 */
 		/* Collect symbols */
 		defaultline       = noaction;
 		internalfunctions = find_export_symbols;
 		externalfunctions = find_export_symbols;
 		symbolsonly       = find_export_symbols;
 		singlefunctions   = noaction2;
 		docsection        = noaction2;
+		findall           = find_all_symbols;
 		parse_file(infile);
 		/* Rewind to start from beginning of file again */
 		fseek(infile, 0, SEEK_SET);
 		defaultline       = printline;
 		internalfunctions = intfunc;
 		externalfunctions = extfunc;
 		symbolsonly       = printline;
 		singlefunctions   = singfunc;
 		docsection        = docsect;
+		findall           = NULL;
 		parse_file(infile);
+		for (i = 0; i < all_list_len; i++) {
+			if (!all_list[i])
+				continue;
+			fprintf(stderr, "Warning: didn't use docs for %s\n",
+				all_list[i]);
+		}
 	}
 	else if (strcmp("depend", argv[1]) == 0)
 	{
 		/* Create first part of dependency chain
 		 * file.tmpl */
 		printf("%s\t", argv[2]);
 		defaultline       = noaction;
 		internalfunctions = adddep;
 		externalfunctions = adddep;
 		symbolsonly       = adddep;
 		singlefunctions   = adddep2;
 		docsection        = adddep2;
+		findall           = adddep;
 		parse_file(infile);
 		printf("\n");
 	}
 	else
 	{
 		fprintf(stderr, "Unknown option: %s\n", argv[1]);
 		exit(1);
 	}
 	fclose(infile);
 	fflush(stdout);
 	return exitstatus;
 }

 #!/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                             ##
 ## Copyright (C) 2005-2009  Randy Dunlap                         ##
 ## 								 ##
 ## #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             ##
 # 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 ] [ -no-doc-sections ]
+# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ]
 #           [ -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.
+#  The -list format is for internal use by docproc.
 #
 #  -no-doc-sections
 #	Do not output DOC: sections
 #
 #  -function funcname
 #	If set, then only generate documentation for the given function(s) or
 #	DOC: section titles.  All other functions and DOC: sections are ignored.
 #
 #  -nofunction funcname
 #	If set, then only generate documentation for the other function(s)/DOC:
 #	sections. 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.
 #
 # Besides 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 $local_lt = "\\\\\\\\lt:";
 my $local_gt = "\\\\\\\\gt:";
 my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
 # XML, docbook format
 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
 			$type_constant, "<constant>\$1</constant>",
 			$type_func, "<function>\$1</function>",
 			$type_struct_xml, "<structname>\$1</structname>",
 			$type_env, "<envar>\$1</envar>",
 			$type_param, "<parameter>\$1</parameter>" );
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\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 = "";
+# list mode
+my %highlights_list = ( $type_constant, "\$1",
+			$type_func, "\$1",
+			$type_struct, "\$1",
+			$type_param, "\$1" );
+my $blankline_list = "";
 sub usage {
-    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n";
+    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n";
+    print "         [ -no-doc-sections ]\n";
     print "         [ -function funcname [ -function funcname ...] ]\n";
     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
     print "         c source file(s) > outputfile\n";
     print "         -v : verbose output, more warnings & other info listed\n";
     exit 1;
 }
 # read arguments
 if ($#ARGV == -1) {
     usage();
 }
 my $verbose = 0;
 my $output_mode = "man";
 my $no_doc_sections = 0;
 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 something.
 # 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, $brcount, %source_map);
 if (defined($ENV{'KBUILD_VERBOSE'})) {
 	$verbose = "$ENV{'KBUILD_VERBOSE'}";
 }
 # 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 $sectcheck;
 my $struct_actual;
 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 "-list") {
+	$output_mode = "list";
+	%highlights = %highlights_list;
+	$blankline = $blankline_list;
     } 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 '-no-doc-sections') {
 	    $no_doc_sections = 1;
     }
 }
 # get kernel version from env
 sub get_kernel_version() {
     my $version = 'unknown kernel 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 $file = shift;
     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;
 	$sectcheck = $sectcheck . $name . " ";
     } elsif ($name eq "@\.\.\.") {
 #	print STDERR "parameter def '...' = '$contents'\n";
 	$name = "...";
 	$parameterdescs{$name} = $contents;
 	$sectcheck = $sectcheck . $name . " ";
     } else {
 #	print STDERR "other section '$name' = '$contents'\n";
 	if (defined($sections{$name}) && ($sections{$name} ne "")) {
 		print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
 		++$errors;
 	}
 	$sections{$name} = $contents;
 	push @sectionlist, $name;
     }
 }
 ##
 # dump DOC: section after checking that it should go out
 #
 sub dump_doc_section {
     my $file = shift;
     my $name = shift;
     my $contents = join "\n", @_;
     if ($no_doc_sections) {
         return;
     }
     if (($function_only == 0) ||
 	( $function_only == 1 && defined($function_table{$name})) ||
 	( $function_only == 2 && !defined($function_table{$name})))
     {
 	dump_section($file, $name, $contents);
 	output_blockhead({'sectionlist' => \@sectionlist,
 			  'sections' => \%sections,
 			  'module' => $modulename,
 			  'content-only' => ($function_only != 0), });
     }
 }
 ##
 # 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";
 #   }
     if ($output_mode eq "html" || $output_mode eq "xml") {
 	$contents = local_unescape($contents);
 	# convert data read & converted thru xml_escape() into &xyz; format:
 	$contents =~ s/\\\\\\/&/g;
     }
 #   print STDERR "contents b4:$contents\n";
     eval $dohighlight;
     die $@ if $@;
 #   print STDERR "contents af:$contents\n";
     foreach $line (split "\n", $contents) {
 	if ($line eq ""){
 	    print $lineprefix, local_unescape($blankline);
 	} else {
 	    $line =~ s/\\\\\\/\&/g;
 	    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 DOC: block header in html
 sub output_blockhead_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";
     if ($#{$args{'parameterlist'}} >= 0) {
     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";
     } else {
 	print " <para>\n  None\n </para>\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_blockhead_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'}}) {
 	if (!$args{'content-only'}) {
 		print "<refsect1>\n <title>$section</title>\n";
 	}
 	if ($section =~ m/EXAMPLE/i) {
 	    print "<example><para>\n";
 	} else {
 	    print "<para>\n";
 	}
 	output_highlight($args{'sections'}{$section});
 	if ($section =~ m/EXAMPLE/i) {
 	    print "</para></example>\n";
 	} else {
 	    print "</para>";
 	}
 	if (!$args{'content-only'}) {
 		print "\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_blockhead_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_blockhead_text(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     foreach $section (@{$args{'sectionlist'}}) {
 	print " $section:\n";
 	print "    -> ";
 	output_highlight($args{'sections'}{$section});
+    }
+}
+## list mode output functions
+sub output_function_list(%) {
+    my %args = %{$_[0]};
+    print $args{'function'} . "\n";
+}
+# output enum in list
+sub output_enum_list(%) {
+    my %args = %{$_[0]};
+    print $args{'enum'} . "\n";
+}
+# output typedef in list
+sub output_typedef_list(%) {
+    my %args = %{$_[0]};
+    print $args{'typedef'} . "\n";
+}
+# output struct as list
+sub output_struct_list(%) {
+    my %args = %{$_[0]};
+    print $args{'struct'} . "\n";
+}
+sub output_blockhead_list(%) {
+    my %args = %{$_[0]};
+    my ($parameter, $section);
+    foreach $section (@{$args{'sectionlist'}}) {
+	print "DOC: $section\n";
     }
 }
 ##
 # 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_blockhead {
     no strict 'refs';
     my $func = "output_blockhead_" . $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;
     my $nested;
     if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
 	#my $decl_type = $1;
 	$declaration_name = $2;
 	my $members = $3;
 	# ignore embedded structs or unions
 	$members =~ s/({.*})//g;
 	$nested = $1;
 	# ignore members marked private:
 	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
 	$members =~ s/\/\*\s*private:.*//gos;
 	# strip comments:
 	$members =~ s/\/\*.*?\*\///gos;
 	$nested =~ s/\/\*.*?\*\///gos;
 	# strip kmemcheck_bitfield_{begin,end}.*;
 	$members =~ s/kmemcheck_bitfield_.*?;//gos;
 	# strip attributes
 	$members =~ s/__aligned\s*\(\d+\)//gos;
 	create_parameterlist($members, ';', $file);
 	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
 	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.
     $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums
     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 save_struct_actual($) {
     my $actual = shift;
     # strip all spaces from the actual param so that it looks like one string item
     $actual =~ s/\s*//g;
     $struct_actual = $struct_actual . $actual . " ";
 }
 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/\(.+\)\s*\(/) {
 	    # pointer-to-function
 	    $arg =~ tr/#/,/;
 	    $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
 	    $param = $1;
 	    $type = $arg;
 	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
 	    save_struct_actual($param);
 	    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*(.*)/) {
 		    save_struct_actual($2);
 		    push_parameter($2, "$type $1", $file);
 		}
 		elsif ($param =~ m/(.*?):(\d+)/) {
 		    if ($type ne "") { # skip unnamed bit-fields
 			save_struct_actual($1);
 			push_parameter($1, "$type:$2", $file)
 		    }
 		}
 		else {
 		    save_struct_actual($param);
 		    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 =~ /\.\.\.$/)
 	{
 	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
 		$parameterdescs{$param} = "variable arguments";
 	    }
 	}
 	elsif ($type eq "" && ($param eq "" or $param eq "void"))
 	{
 	    $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;
 	}
 	}
 	# strip spaces from $param so that it is one continous string
 	# on @parameterlist;
 	# this fixes a problem where check_sections() cannot find
 	# a parameter like "addr[6 + 2]" because it actually appears
 	# as "addr[6", "+", "2]" on the parameter list;
 	# but it's better to maintain the param string unchanged for output,
 	# so just weaken the string compare in check_sections() to ignore
 	# "[blah" in a parameter string;
 	###$param =~ s/\s*//g;
 	push @parameterlist, $param;
 	$parametertypes{$param} = $type;
 }
 sub check_sections($$$$$$) {
 	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
 	my @sects = split ' ', $sectcheck;
 	my @prms = split ' ', $prmscheck;
 	my $err;
 	my ($px, $sx);
 	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"
 	foreach $sx (0 .. $#sects) {
 		$err = 1;
 		foreach $px (0 .. $#prms) {
 			$prm_clean = $prms[$px];
 			$prm_clean =~ s/\[.*\]//;
 			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
 			# ignore array size in a parameter string;
 			# however, the original param string may contain
 			# spaces, e.g.:  addr[6 + 2]
 			# and this appears in @prms as "addr[6" since the
 			# parameter list is split at spaces;
 			# hence just ignore "[..." for the sections check;
 			$prm_clean =~ s/\[.*//;
 			##$prm_clean =~ s/^\**//;
 			if ($prm_clean eq $sects[$sx]) {
 				$err = 0;
 				last;
 			}
 		}
 		if ($err) {
 			if ($decl_type eq "function") {
 				print STDERR "Warning(${file}:$.): " .
 					"Excess function parameter " .
 					"'$sects[$sx]' " .
 					"description in '$decl_name'\n";
 				++$warnings;
 			} else {
 				if ($nested !~ m/\Q$sects[$sx]\E/) {
 				    print STDERR "Warning(${file}:$.): " .
 					"Excess struct/union/enum/typedef member " .
 					"'$sects[$sx]' " .
 					"description in '$decl_name'\n";
 				    ++$warnings;
 				}
 			}
 		}
 	}
 }
 ##
 # 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/^asmlinkage +//;
     $prototype =~ s/^inline +//;
     $prototype =~ s/^__inline__ +//;
     $prototype =~ s/^__inline +//;
     $prototype =~ s/^__always_inline +//;
     $prototype =~ s/^noinline +//;
     $prototype =~ s/__devinit +//;
     $prototype =~ s/__init +//;
     $prototype =~ s/__init_or_module +//;
     $prototype =~ s/^#\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;
     }
 	my $prms = join " ", @parameterlist;
 	check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
     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);
 }
 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 = ();
     $sectcheck = "";
     $struct_actual = "";
     $prototype = "";
     $state = 0;
 }
 sub tracepoint_munge($) {
 	my $file = shift;
 	my $tracepointname = 0;
 	my $tracepointargs = 0;
 	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
 		$tracepointname = $1;
 	}
 	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
 		$tracepointname = $1;
 	}
 	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
 		$tracepointname = $2;
 	}
 	$tracepointname =~ s/^\s+//; #strip leading whitespace
 	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
 		$tracepointargs = $1;
 	}
 	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
 		print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
 			     "$prototype\n";
 	} else {
 		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
 	}
 }
 sub syscall_munge() {
 	my $void = 0;
 	$prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
 ##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
 	if ($prototype =~ m/SYSCALL_DEFINE0/) {
 		$void = 1;
 ##		$prototype = "long sys_$1(void)";
 	}
 	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
 	if ($prototype =~ m/long (sys_.*?),/) {
 		$prototype =~ s/,/\(/;
 	} elsif ($void) {
 		$prototype =~ s/\)/\(void\)/;
 	}
 	# now delete all of the odd-number commas in $prototype
 	# so that arg types & arg names don't have a comma between them
 	my $count = 0;
 	my $len = length($prototype);
 	if ($void) {
 		$len = 0;	# skip the for-loop
 	}
 	for (my $ix = 0; $ix < $len; $ix++) {
 		if (substr($prototype, $ix, 1) eq ',') {
 			$count++;
 			if ($count % 2 == 1) {
 				substr($prototype, $ix, 1) = ' ';
 			}
 		}
 	}
 }
 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 !~ /^#\s*define/)) {
 	# do nothing
     }
     elsif ($x =~ /([^\{]*)/) {
 	$prototype .= $1;
     }
     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
 	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
 	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
 	$prototype =~ s@^\s+@@gos; # strip leading spaces
 	if ($prototype =~ /SYSCALL_DEFINE/) {
 		syscall_munge();
 	}
 	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
 	    $prototype =~ /DEFINE_SINGLE_EVENT/)
 	{
 		tracepoint_munge($file);
 	}
 	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;
 	}
     }
 }
 # xml_escape: replace <, >, and & in the text stream;
 #
 # however, formatting controls that are generated internally/locally in the
 # kernel-doc script are not escaped here; instead, they begin life like
 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
 # just before actual output; (this is done by local_unescape())
 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;
 }
 # convert local escape strings to html
 # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
 sub local_unescape($) {
 	my $text = shift;
 	if (($output_mode eq "text") || ($output_mode eq "man")) {
 		return $text;
 	}
 	$text =~ s/\\\\\\\\lt:/</g;
 	$text =~ s/\\\\\\\\gt:/>/g;
 	return $text;
 }
 sub process_file($) {
     my $file;
     my $identifier;
     my $func;
     my $descr;
     my $in_purpose = 0;
     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;
     }
     $. = 1;
     $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);
 		    $in_purpose = 1;
 		} else {
 		    $declaration_purpose = "";
 		}
 		if (($declaration_purpose eq "") && $verbose) {
 			print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
 			print STDERR $_;
 			++$warnings;
 		}
 		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 "") && ($contents ne "\n")) {
 		    if (!$in_doc_sect && $verbose) {
 			print STDERR "Warning(${file}:$.): contents before sections\n";
 			++$warnings;
 		    }
 		    dump_section($file, $section, xml_escape($contents));
 		    $section = $section_default;
 		}
 		$in_doc_sect = 1;
 		$in_purpose = 0;
 		$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 "") && ($contents ne "\n")) {
 		    dump_section($file, $section, xml_escape($contents));
 		    $section = $section_default;
 		    $contents = "";
 		}
 		# look for doc_com + <text> + doc_end:
 		if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
 		    print STDERR "Warning(${file}:$.): suspicious ending line: $_";
 		    ++$warnings;
 		}
 		$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 "") {
 		    if ($section =~ m/^@/ || $section eq $section_context) {
 			dump_section($file, $section, xml_escape($contents));
 			$section = $section_default;
 			$contents = "";
 		    } else {
 			$contents .= "\n";
 		    }
 		    $in_purpose = 0;
 		} elsif ($in_purpose == 1) {
 		    # Continued declaration purpose
 		    chomp($declaration_purpose);
 		    $declaration_purpose .= " " . xml_escape($1);
 		} 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_doc_section($file, $section, xml_escape($contents));
 			$contents = "";
 			$function = "";
 			%constants = ();
 			%parameterdescs = ();
 			%parametertypes = ();
 			@parameterlist = ();
 			%sections = ();
 			@sectionlist = ();
 			$prototype = "";
 			if ( $1 eq "" ) {
 				$section = $section_intro;
 			} else {
 				$section = $1;
 			}
 		}
 		elsif (/$doc_end/)
 		{
 			dump_doc_section($file, $section, xml_escape($contents));
 			$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";
 	}
     }
 }