[mirror_ubuntu-bionic-kernel.git] / Documentation / sphinx / parse-headers.pl

#!/usr/bin/perl
use strict;
use Text::Tabs;

# Uncomment if debug is needed
#use Data::Dumper;

# change to 1 to generate some debug prints
my $debug = 0;

if (scalar @ARGV < 2 || scalar @ARGV > 3) {
	die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
}

my ($file_in, $file_out, $file_exceptions) = @ARGV;

my $data;
my %ioctls;
my %defines;
my %typedefs;
my %enums;
my %enum_symbols;
my %structs;

#
# read the file and get identifiers
#

my $is_enum = 0;
open IN, $file_in or die "Can't open $file_in";
while (<IN>) {
	$data .= $_;

	if ($is_enum && m/^\s*([^\s\}\,\=]+)\s*[\,=]?/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$enum_symbols{$s} = $n;

		$is_enum = 0 if ($is_enum && m/\}/);
		next;
	}
	$is_enum = 0 if ($is_enum && m/\}/);

	if (m/^\s*#\s*define\s+([_A-Z]\S+)\s+_IO/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;

		$ioctls{$s} = $n;
		next;
	}

	if (m/^\s*#\s*define\s+([_A-Z]\S+)\s+/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$defines{$s} = $n;
		next;
	}

	if (m/^\s*typedef\s+.*\s+([_\w]\S+);/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$typedefs{$s} = $n;
		next;
	}
	if (m/^\s*enum\s+(\S+)\s+\{/ || m/^\s*enum\s+(\S+)$/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$enums{$s} = $n;

		$is_enum = $1;
		next;
	}
	if (m/^\s*struct\s+([_A-Za-z_]\S+)\s+\{/ || m/^\s*struct\s+([A-Za-z_]\S+)$/) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$structs{$s} = $n;
		next;
	}
}
close IN;

#
# Handle multi-line typedefs
#

my @matches = $data =~ m/typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*(\S+)\s*\;/g;
foreach my $m (@matches) {
		my $s = $1;
		my $n = $1;
		$n =~ tr/A-Z/a-z/;
		$n =~ tr/_/-/;

		$typedefs{$s} = $n;
	next;
}

#
# Handle exceptions, if any
#

if ($file_exceptions) {
	open IN, $file_exceptions or die "Can't read $file_exceptions";
	while (<IN>) {
		next if (m/^\s*$/ || m/^\s*#/);

		# Parsers to ignore a symbol

		if (m/^ignore\s+ioctl\s+(\S+)/) {
			delete $ioctls{$1} if (exists($ioctls{$1}));
			next;
		}
		if (m/^ignore\s+define\s+(\S+)/) {
			delete $defines{$1} if (exists($defines{$1}));
			next;
		}
		if (m/^ignore\s+typedef\s+(\S+)/) {
			delete $typedefs{$1} if (exists($typedefs{$1}));
			next;
		}
		if (m/^ignore\s+enum\s+(\S+)/) {
			delete $enums{$1} if (exists($enums{$1}));
			next;
		}
		if (m/^ignore\s+struct\s+(\S+)/) {
			delete $structs{$1} if (exists($structs{$1}));
			next;
		}

		# Parsers to replace a symbol

		if (m/^replace\s+ioctl\s+(\S+)\s+(\S+)/) {
			$ioctls{$1} = $2 if (exists($ioctls{$1}));
			next;
		}
		if (m/^replace\s+define\s+(\S+)\s+(\S+)/) {
			$defines{$1} = $2 if (exists($defines{$1}));
			next;
		}
		if (m/^replace\s+typedef\s+(\S+)\s+(\S+)/) {
			$typedefs{$1} = $2 if (exists($typedefs{$1}));
			next;
		}
		if (m/^replace\s+enum\s+(\S+)\s+(\S+)/) {
			$enums{$1} = $2 if (exists($enums{$1}));
			next;
		}
		if (m/^replace\s+symbol\s+(\S+)\s+(\S+)/) {
			$enum_symbols{$1} = $2 if (exists($enum_symbols{$1}));
			next;
		}
		if (m/^replace\s+struct\s+(\S+)\s+(\S+)/) {
			$structs{$1} = $2 if (exists($structs{$1}));
			next;
		}

		die "Can't parse $file_exceptions: $_";
	}
}

if ($debug) {
	print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
	print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
	print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
	print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
	print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
	print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
}

#
# Align block
#
$data = expand($data);
$data = "    " . $data;
$data =~ s/\n/\n    /g;
$data =~ s/\n\s+$/\n/g;
$data =~ s/\n\s+\n/\n\n/g;

#
# Add escape codes for special characters
#
$data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;

$data =~ s,DEPRECATED,**DEPRECATED**,g;

#
# Add references
#

my $start_delim = "[ \n\t\(\=\*\@]";
my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)";

foreach my $r (keys %ioctls) {
	my $n = $ioctls{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

foreach my $r (keys %defines) {
	my $n = $defines{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

foreach my $r (keys %enum_symbols) {
	my $n = $enum_symbols{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

foreach my $r (keys %enums) {
	my $n = $enums{$r};

	my $s = "\\ :ref:`enum $r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/enum\s+($r)$end_delim/$s$2/g;
}

foreach my $r (keys %structs) {
	my $n = $structs{$r};

	my $s = "\\ :ref:`struct $r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/struct\s+($r)$end_delim/$s$2/g;
}

foreach my $r (keys %typedefs) {
	my $n = $typedefs{$r};

	my $s = "\\ :ref:`$r <$n>`\\ ";

	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;

	print "$r -> $s\n" if ($debug);

	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
}

#
# Generate output file
#

my $title = $file_in;
$title =~ s,.*/,,;

open OUT, "> $file_out" or die "Can't open $file_out";
print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";
print OUT "$title\n";
print OUT "=" x length($title);
print OUT "\n\n.. parsed-literal::\n\n";
print OUT $data;
close OUT;
Commit	Line	Data
dabf8be3 MCC	1	#!/usr/bin/perl
	2	use strict;
	3	use Text::Tabs;
	4
	5	# Uncomment if debug is needed
	6	#use Data::Dumper;
	7
	8	# change to 1 to generate some debug prints
	9	my $debug = 0;
	10
	11	if (scalar @ARGV < 2 \|\| scalar @ARGV > 3) {
	12	die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n";
	13	}
	14
	15	my ($file_in, $file_out, $file_exceptions) = @ARGV;
	16
	17	my $data;
	18	my %ioctls;
	19	my %defines;
	20	my %typedefs;
	21	my %enums;
	22	my %enum_symbols;
	23	my %structs;
	24
	25	#
	26	# read the file and get identifiers
	27	#
	28
	29	my $is_enum = 0;
	30	open IN, $file_in or die "Can't open $file_in";
	31	while (<IN>) {
	32	$data .= $_;
	33
	34	if ($is_enum && m/^\s([^\s\}\,\=]+)\s[\,=]?/) {
	35	my $s = $1;
	36	my $n = $1;
	37	$n =~ tr/A-Z/a-z/;
	38	$n =~ tr/_/-/;
	39
	40	$enum_symbols{$s} = $n;
	41
	42	$is_enum = 0 if ($is_enum && m/\}/);
	43	next;
	44	}
	45	$is_enum = 0 if ($is_enum && m/\}/);
	46
	47	if (m/^\s#\sdefine\s+([_A-Z]\S+)\s+_IO/) {
	48	my $s = $1;
	49	my $n = $1;
	50	$n =~ tr/A-Z/a-z/;
	51
	52	$ioctls{$s} = $n;
	53	next;
	54	}
	55
	56	if (m/^\s#\sdefine\s+([_A-Z]\S+)\s+/) {
	57	my $s = $1;
	58	my $n = $1;
	59	$n =~ tr/A-Z/a-z/;
	60	$n =~ tr/_/-/;
	61
	62	$defines{$s} = $n;
	63	next;
	64	}
65
66	if (m/^\stypedef\s+.\s+([_\w]\S+);/) {
67	my $s = $1;
68	my $n = $1;
69	$n =~ tr/A-Z/a-z/;
70	$n =~ tr/_/-/;
71
72	$typedefs{$s} = $n;
73	next;
74	}
75	if (m/^\senum\s+(\S+)\s+\{/ \|\| m/^\senum\s+(\S+)$/) {
76	my $s = $1;
77	my $n = $1;
78	$n =~ tr/A-Z/a-z/;
79	$n =~ tr/_/-/;
80
81	$enums{$s} = $n;
82
83	$is_enum = $1;
84	next;
85	}
86	if (m/^\sstruct\s+([_A-Za-z_]\S+)\s+\{/ \|\| m/^\sstruct\s+([A-Za-z_]\S+)$/) {
87	my $s = $1;
88	my $n = $1;
89	$n =~ tr/A-Z/a-z/;
90	$n =~ tr/_/-/;
91
92	$structs{$s} = $n;
93	next;
94	}
95	}
96	close IN;
97
98	#
99	# Handle multi-line typedefs
100	#
101
102	my @matches = $data =~ m/typedef\s+struct\s+\S+\s\{[^\}]+\}\s(\S+)\s*\;/g;
103	foreach my $m (@matches) {
104	my $s = $1;
105	my $n = $1;
106	$n =~ tr/A-Z/a-z/;
107	$n =~ tr/_/-/;
108
109	$typedefs{$s} = $n;
110	next;
111	}
112
113	#
114	# Handle exceptions, if any
115	#
116
117	if ($file_exceptions) {
118	open IN, $file_exceptions or die "Can't read $file_exceptions";
119	while (<IN>) {
120	next if (m/^\s$/ \|\| m/^\s#/);
121
122	# Parsers to ignore a symbol
123
124	if (m/^ignore\s+ioctl\s+(\S+)/) {
125	delete $ioctls{$1} if (exists($ioctls{$1}));
126	next;
127	}
128	if (m/^ignore\s+define\s+(\S+)/) {
129	delete $defines{$1} if (exists($defines{$1}));
130	next;
131	}
132	if (m/^ignore\s+typedef\s+(\S+)/) {
133	delete $typedefs{$1} if (exists($typedefs{$1}));
134	next;
135	}
136	if (m/^ignore\s+enum\s+(\S+)/) {
137	delete $enums{$1} if (exists($enums{$1}));
138	next;
139	}
140	if (m/^ignore\s+struct\s+(\S+)/) {
141	delete $structs{$1} if (exists($structs{$1}));
142	next;
143	}
144
145	# Parsers to replace a symbol
146
147	if (m/^replace\s+ioctl\s+(\S+)\s+(\S+)/) {
148	$ioctls{$1} = $2 if (exists($ioctls{$1}));
149	next;
150	}
151	if (m/^replace\s+define\s+(\S+)\s+(\S+)/) {
152	$defines{$1} = $2 if (exists($defines{$1}));
153	next;
154	}
155	if (m/^replace\s+typedef\s+(\S+)\s+(\S+)/) {
156	$typedefs{$1} = $2 if (exists($typedefs{$1}));
157	next;
158	}
159	if (m/^replace\s+enum\s+(\S+)\s+(\S+)/) {
160	$enums{$1} = $2 if (exists($enums{$1}));
161	next;
162	}
163	if (m/^replace\s+symbol\s+(\S+)\s+(\S+)/) {
164	$enum_symbols{$1} = $2 if (exists($enum_symbols{$1}));
165	next;
166	}
167	if (m/^replace\s+struct\s+(\S+)\s+(\S+)/) {
168	$structs{$1} = $2 if (exists($structs{$1}));
169	next;
170	}
171
172	die "Can't parse $file_exceptions: $_";
173	}
174	}
175
176	if ($debug) {
177	print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);
178	print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);
179	print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);
180	print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);
181	print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);
182	print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);
183	}
184
185	#
186	# Align block
187	#
188	$data = expand($data);
189	$data = " " . $data;
190	$data =~ s/\n/\n /g;
191	$data =~ s/\n\s+$/\n/g;
192	$data =~ s/\n\s+\n/\n\n/g;
193
194	#
195	# Add escape codes for special characters
196	#
197	$data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g;
198
7d95fa8d MCC	199	$data =~ s,DEPRECATED,DEPRECATED,g;
7d95fa8d MCC	200
dabf8be3 MCC	201	#
	202	# Add references
	203	#
	204
6fe79d1e MCC	205	my $start_delim = "[ \n\t\(\=\*\@]";
6fe79d1e MCC	206	my $end_delim = "(\\s\|,\|\\\\=\|\\\\:\|\\;\|\\\)\|\\}\|\\{)";
dabf8be3 MCC	207
	208	foreach my $r (keys %ioctls) {
	209	my $n = $ioctls{$r};
	210
6fe79d1e	211	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	212
	213	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	214
	215	print "$r -> $s\n" if ($debug);
	216
6fe79d1e	217	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	218	}
	219
	220	foreach my $r (keys %defines) {
	221	my $n = $defines{$r};
	222
6fe79d1e	223	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	224
	225	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	226
	227	print "$r -> $s\n" if ($debug);
	228
6fe79d1e	229	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	230	}
	231
	232	foreach my $r (keys %enum_symbols) {
	233	my $n = $enum_symbols{$r};
	234
6fe79d1e	235	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	236
	237	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	238
	239	print "$r -> $s\n" if ($debug);
	240
6fe79d1e	241	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	242	}
	243
	244	foreach my $r (keys %enums) {
	245	my $n = $enums{$r};
	246
6fe79d1e	247	my $s = "\\ :ref:`enum $r <$n>`\\ ";
dabf8be3 MCC	248
	249	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	250
	251	print "$r -> $s\n" if ($debug);
	252
6fe79d1e	253	$data =~ s/enum\s+($r)$end_delim/$s$2/g;
dabf8be3 MCC	254	}
	255
	256	foreach my $r (keys %structs) {
	257	my $n = $structs{$r};
	258
6fe79d1e	259	my $s = "\\ :ref:`struct $r <$n>`\\ ";
dabf8be3 MCC	260
	261	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	262
	263	print "$r -> $s\n" if ($debug);
	264
6fe79d1e	265	$data =~ s/struct\s+($r)$end_delim/$s$2/g;
dabf8be3 MCC	266	}
	267
	268	foreach my $r (keys %typedefs) {
	269	my $n = $typedefs{$r};
	270
6fe79d1e	271	my $s = "\\ :ref:`$r <$n>`\\ ";
dabf8be3 MCC	272
	273	$r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;
	274
	275	print "$r -> $s\n" if ($debug);
	276
6fe79d1e	277	$data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;
dabf8be3 MCC	278	}
	279
	280	#
	281	# Generate output file
	282	#
	283
	284	my $title = $file_in;
	285	$title =~ s,.*/,,;
	286
	287	open OUT, "> $file_out" or die "Can't open $file_out";
	288	print OUT ".. -- coding: utf-8; mode: rst --\n\n";
	289	print OUT "$title\n";
	290	print OUT "=" x length($title);
	291	print OUT "\n\n.. parsed-literal::\n\n";
	292	print OUT $data;
	293	close OUT;