From 848dff8f0d9242c0c7a417a1482c14ac289deb6f Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sat, 8 Oct 2005 00:33:19 +0000 Subject: r10829: Documentation updates Update TODO Some small fixes to the modules (This used to be commit 0c53e7c3cf7fd91fd34c48a5e68c1bcf70569854) --- source4/pidl/TODO | 13 ++-- source4/pidl/lib/Parse/Pidl/Dump.pm | 14 ++++ .../pidl/lib/Parse/Pidl/Ethereal/Conformance.pm | 75 +++++++++++++++++++ source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm | 8 +++ source4/pidl/lib/Parse/Pidl/NDR.pm | 32 ++++++--- source4/pidl/lib/Parse/Pidl/Samba3/Header.pm | 15 ++-- source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm | 40 ++++++++--- source4/pidl/pidl | 83 ++++------------------ 8 files changed, 180 insertions(+), 100 deletions(-) (limited to 'source4/pidl') diff --git a/source4/pidl/TODO b/source4/pidl/TODO index 9fc3a7d904..ca5047c0d7 100644 --- a/source4/pidl/TODO +++ b/source4/pidl/TODO @@ -1,16 +1,17 @@ -- True multiple dimension array / strings in arrays support +- true multiple dimension array / strings in arrays support - compatibility mode for generating MIDL-readable data: - strip out pidl-specific properties - - convert subcontext() to an array of uint8. - - perhaps replace subcontext() with something more generic? The argument - to subcontext() isn't really intuitive at the moment - don't be so strict on array boundaries.. arrays can and will be empty when a (regular) remote error occurs - support nested elements -- Don't output [ref] pointers for Samba 4? +- auto-alloc [ref] pointers for Samba4 during pull if they were NULL -- alternative to subcontext() +- better replacement for subcontext() + +- --explain-ndr option that dumps out parse tree + +- fix test suite diff --git a/source4/pidl/lib/Parse/Pidl/Dump.pm b/source4/pidl/lib/Parse/Pidl/Dump.pm index 80219a8f1a..3a1cec1b59 100644 --- a/source4/pidl/lib/Parse/Pidl/Dump.pm +++ b/source4/pidl/lib/Parse/Pidl/Dump.pm @@ -1,8 +1,22 @@ ################################################### # dump function for IDL structures # Copyright tridge@samba.org 2000 +# Copyright jelmer@samba.org 2005 # released under the GNU GPL +=pod + +=head1 NAME + +Parse::Pidl::Dump - Dump support + +=head1 DESCRIPTION + +This module provides functions that can generate IDL code from +internal pidl data structures. + +=cut + package Parse::Pidl::Dump; use Exporter; diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm index 706a259306..1b550ae1e7 100644 --- a/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm +++ b/source4/pidl/lib/Parse/Pidl/Ethereal/Conformance.pm @@ -3,6 +3,81 @@ # Copyright jelmer@samba.org 2005 # released under the GNU GPL +=pod + +=head1 NAME + +Parse::Pidl::Ethereal::Conformance - Conformance file parser for Ethereal + +=head1 DESCRIPTION + +This module supports parsing Ethereal conformance files (*.cnf). + +=head1 FILE FORMAT + +Pidl needs additional data for ethereal output. This data is read from +so-called conformance files. This section describes the format of these +files. + +Conformance files are simple text files with a single command on each line. +Empty lines and lines starting with a '#' character are ignored. +Arguments to commands are seperated by spaces. + +The following commands are currently supported: + +=over 4 + +=item I name dissector ft_type base_type mask valsstring alignment + +Register new data type with specified name, what dissector function to call +and what properties to give header fields for elements of this type. + +=item I type + +Suppress emitting a dissect_type function for the specified type + +=item I type param + +Set parameter to specify to dissector function for given type. + +=item I hf title filter ft_type base_type valsstring mask description + +Generate a custom header field with specified properties. + +=item I old_hf_name new_hf_name + +Force the use of new_hf_name when the parser generator was going to +use old_hf_name. + +This can be used in conjunction with HF_FIELD in order to make more then +one element use the same filter name. + +=item I prefix + +Remove the specified prefix from all function names (if present). + +=item I longname shortname filtername + +Change the short-, long- and filter-name for the current interface in +Ethereal. + +=item I field desc + +Change description for the specified header field. `field' is the hf name of the field. + +=item I dissector code... + +Code to insert when generating the specified dissector. @HF@ and +@PARAM@ will be substituted. + +=back + +=head1 EXAMPLE + + INFO_KEY OpenKey.Ke + +=cut + package Parse::Pidl::Ethereal::Conformance; require Exporter; diff --git a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm index be542638ef..8a4c0ed60c 100644 --- a/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm +++ b/source4/pidl/lib/Parse/Pidl/Ethereal/NDR.pm @@ -6,6 +6,14 @@ # Portions based on idl2eth.c by Ronnie Sahlberg # released under the GNU GPL +=pod + +=head1 NAME + +Parse::Pidl::Ethereal::NDR - Parser generator for Ethereal + +=cut + package Parse::Pidl::Ethereal::NDR; use strict; diff --git a/source4/pidl/lib/Parse/Pidl/NDR.pm b/source4/pidl/lib/Parse/Pidl/NDR.pm index 64190e87b8..f975e07b15 100644 --- a/source4/pidl/lib/Parse/Pidl/NDR.pm +++ b/source4/pidl/lib/Parse/Pidl/NDR.pm @@ -5,6 +5,26 @@ # Copyright jelmer@samba.org 2004-2005 # released under the GNU GPL +=pod + +=head1 NAME + +Parse::Pidl::NDR - NDR parsing information generator + +=head1 DESCRIPTION + +##################################################################### +# return a table describing the order in which the parts of an element +# should be parsed +# Possible level types: +# - POINTER +# - ARRAY +# - SUBCONTEXT +# - SWITCH +# - DATA + +=cut + package Parse::Pidl::NDR; require Exporter; @@ -62,15 +82,6 @@ sub fatal($$) die("$pos->{FILE}:$pos->{LINE}:$s\n"); } -##################################################################### -# return a table describing the order in which the parts of an element -# should be parsed -# Possible level types: -# - POINTER -# - ARRAY -# - SUBCONTEXT -# - SWITCH -# - DATA sub GetElementLevelTable($) { my $e = shift; @@ -394,6 +405,7 @@ sub ParseUnion($) if (has_property($e, "nodiscriminant")) { $switch_type = undef; } + my $hasdefault = 0; foreach my $x (@{$e->{ELEMENTS}}) { my $t; @@ -404,6 +416,7 @@ sub ParseUnion($) } if (has_property($x, "default")) { $t->{CASE} = "default"; + $hasdefault = 1; } elsif (defined($x->{PROPERTIES}->{case})) { $t->{CASE} = "case $x->{PROPERTIES}->{case}"; } else { @@ -417,6 +430,7 @@ sub ParseUnion($) SWITCH_TYPE => $switch_type, ELEMENTS => \@elements, PROPERTIES => $e->{PROPERTIES}, + HAS_DEFAULT => $hasdefault, ORIGINAL => $e }; } diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm index 78bd8fe339..25102e511a 100644 --- a/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm +++ b/source4/pidl/lib/Parse/Pidl/Samba3/Header.pm @@ -31,7 +31,6 @@ sub ParseElement($) return if ($l->{POINTER_TYPE} eq "ref" and $l->{LEVEL} eq "top"); pidl "\tuint32 ptr$l->{POINTER_INDEX}_$e->{NAME};"; } elsif ($l->{TYPE} eq "SWITCH") { - pidl "\tuint32 level_$e->{NAME};"; } elsif ($l->{TYPE} eq "DATA") { pidl "\t" . DeclShort($e) . ";"; } elsif ($l->{TYPE} eq "ARRAY") { @@ -106,30 +105,28 @@ sub ParseUnion($$$) my $extra = {}; - unless (has_property($u, "nodiscriminant")) { - $extra->{switch_value} = 1; - } + $extra->{switch_value} = $u->{SWITCH_TYPE}; foreach my $e (@{$u->{ELEMENTS}}) { foreach my $l (@{$e->{LEVELS}}) { if ($l->{TYPE} eq "ARRAY") { if ($l->{IS_CONFORMANT}) { - $extra->{"size"} = 1; + $extra->{"size"} = "uint32"; } if ($l->{IS_VARYING}) { - $extra->{"length"} = $extra->{"offset"} = 1; + $extra->{"length"} = $extra->{"offset"} = "uint32"; } } elsif ($l->{TYPE} eq "POINTER") { - $extra->{"ptr$l->{POINTER_INDEX}"} = 1; + $extra->{"ptr$l->{POINTER_INDEX}"} = "uint32"; } elsif ($l->{TYPE} eq "SWITCH") { - $extra->{"level"} = 1; + $extra->{"level"} = "uint32"; } } } pidl "typedef struct $if->{NAME}_$n\_ctr {"; indent; - pidl "uint32 $_;" foreach (keys %$extra); + pidl "$extra->{$_} $_;" foreach (keys %$extra); pidl "union $if->{NAME}_$n {"; indent; foreach (@{$u->{ELEMENTS}}) { diff --git a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm index eaab50b553..c6cc188391 100644 --- a/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm +++ b/source4/pidl/lib/Parse/Pidl/Samba3/Parser.pm @@ -75,8 +75,18 @@ sub ParseElementLevelData($$$$$$$) # See if we need to add a level argument because we're parsing a union foreach (@{$e->{LEVELS}}) { - push (@args, ParseExpr("level_$e->{NAME}", $env)) - if ($_->{TYPE} eq "SWITCH"); + next unless ($_->{TYPE} eq "SWITCH"); + my $t = getType($l->{DATA_TYPE}); + + # Set 0 here because one of the variables referenced in SWITCH_IS + # might be an in variable while this one is [out] + if (grep(/in/, @{$e->{DIRECTION}}) or + not defined($t) or + has_property($t->{DATA}, "nodiscriminant")) { + push (@args, ParseExpr($_->{SWITCH_IS}, $env)); + } else { + push (@args, -1); + } } my $c = DissectType(@args); @@ -263,7 +273,6 @@ sub GenerateEnvElement($$) } elsif ($l->{TYPE} eq "POINTER") { $env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}_$e->{NAME}"; } elsif ($l->{TYPE} eq "SWITCH") { - $env->{"level_$e->{NAME}"} = "v->level_$e->{NAME}"; } elsif ($l->{TYPE} eq "ARRAY") { $env->{"length_$e->{NAME}"} = "v->length_$e->{NAME}"; $env->{"size_$e->{NAME}"} = "v->size_$e->{NAME}"; @@ -368,7 +377,6 @@ sub UnionGenerateEnvElement($) } elsif ($l->{TYPE} eq "POINTER") { $env->{"ptr$l->{POINTER_INDEX}_$e->{NAME}"} = "v->ptr$l->{POINTER_INDEX}"; } elsif ($l->{TYPE} eq "SWITCH") { - $env->{"level_$e->{NAME}"} = "v->level"; } elsif ($l->{TYPE} eq "ARRAY") { $env->{"length_$e->{NAME}"} = "v->length"; $env->{"size_$e->{NAME}"} = "v->size"; @@ -394,15 +402,20 @@ sub ParseUnion($$$) indent; DeclareArrayVariables($u->{ELEMENTS}); - unless (has_property($u, "nodiscriminant")) { - pidl "if (!prs_uint32(\"switch_value\", ps, depth, &v->switch_value))"; + if (defined ($u->{SWITCH_TYPE})) { + pidl "if (MARSHALLING(ps)) "; + pidl "\tv->switch_value = level;"; + pidl ""; + pidl "if (!prs_$u->{SWITCH_TYPE}(\"switch_value\", ps, depth, &v->switch_value))"; pidl "\treturn False;"; pidl ""; + } else { + pidl "v->switch_value = level;"; } # Maybe check here that level and v->switch_value are equal? - pidl "switch (level) {"; + pidl "switch (v->switch_value) {"; indent; foreach (@{$u->{ELEMENTS}}) { @@ -420,19 +433,30 @@ sub ParseUnion($$$) pidl ""; } + unless ($u->{HAS_DEFAULT}) { + pidl "default:"; + pidl "\treturn False;"; + pidl ""; + } + deindent; pidl "}"; pidl ""; pidl "return True;"; deindent; pidl "}"; + pidl ""; pidl "BOOL $dfn(const char *desc, $sn* v, uint32 level, prs_struct *ps, int depth)"; pidl "{"; indent; DeclareArrayVariables($u->{ELEMENTS}); - pidl "switch (level) {"; + if (defined($u->{SWITCH_TYPE})) { + pidl "switch (v->switch_value) {"; + } else { + pidl "switch (level) {"; + } indent; foreach (@{$u->{ELEMENTS}}) { diff --git a/source4/pidl/pidl b/source4/pidl/pidl index 07bfefa956..1e77b59be9 100755 --- a/source4/pidl/pidl +++ b/source4/pidl/pidl @@ -8,13 +8,15 @@ # released under the GNU GPL =pod + =head1 NAME -pidl - IDL Compiler written in Perl +pidl - An IDL compiler written in Perl =head1 SYNOPSIS pidl --help + pidl [--outputdir[=OUTNAME]] [--parse-idl-tree] [--dump-idl-tree] [--dump-ndr-tree] [--ndr-header[=OUTPUT]] [--header[=OUTPUT]] [--ejs[=OUTPUT]] [--swig[=OUTPUT]] [--uint-enums] [--ndr-parser[=OUTPUT]] [--client] [--server] [--dcom-proxy] [--com-header] [--warn-compat] [--quiet] [--verbose] [--template] [--eth-parser[=OUTPUT]] [--diff] [--dump-idl] [--tdr-header=[OUTPUT]] [--tdr-parser[=OUTPUT]] [--samba3-header[=OUTPUT]] [--samba3-parser=[OUTPUT]] [--samba3-server=[OUTPUT]] [--samba3-template[=OUTPUT]] [--samba3-client[=OUTPUT]] [.idl]... =head1 DESCRIPTION @@ -95,8 +97,8 @@ packet-dcerpc-OUTNAME.h. Pidl will read additional data from an ethereal conformance file if present. Such a file should have the same location as the IDL file but with the -extension I rather then I. See below for details on the format of -this file. +extension I rather then I. See L +for details on the format of this file. =item I<--diff> @@ -354,82 +356,26 @@ oleautomation, optional, pragma, propget, propputref, propput, readonly, requestedit, restricted, retval, source, transmit_as, uidefault, usesgetlasterror, vararg, vi_progid, wire_marshal. -=head1 ETHEREAL CONFORMANCE FILES - -Pidl needs additional data for ethereal output. This data is read from -so-called conformance files. This section describes the format of these -files. - -Conformance files are simple text files with a single command on each line. -Empty lines and lines starting with a '#' character are ignored. -Arguments to commands are seperated by spaces. - -The following commands are currently supported: - -=over 4 - -=item I name dissector ft_type base_type mask valsstring alignment - -Register new data type with specified name, what dissector function to call -and what properties to give header fields for elements of this type. - -=item I type - -Suppress emitting a dissect_type function for the specified type - -=item I type param - -Set parameter to specify to dissector function for given type. - -=item I hf title filter ft_type base_type valsstring mask description - -Generate a custom header field with specified properties. - -=item I old_hf_name new_hf_name - -Force the use of new_hf_name when the parser generator was going to -use old_hf_name. - -This can be used in conjunction with HF_FIELD in order to make more then -one element use the same filter name. - -=item I prefix - -Remove the specified prefix from all function names (if present). - -=item I longname shortname filtername - -Change the short-, long- and filter-name for the current interface in -Ethereal. - -=item I field desc - -Change description for the specified header field. `field' is the hf name of the field. - -=item I dissector code... - -Code to insert when generating the specified dissector. @HF@ and -@PARAM@ will be substituted. - -=back - =head1 EXAMPLES # Generating an ethereal parser $ ./pidl --eth-parser -- atsvc.idl - # Generating a TDR parser + # Generating a TDR parser and header $ ./pidl --tdr-parser --tdr-header --header -- regf.idl -=head1 VERSION + # Generating a Samba3 parser, client and server + $ ./pidl --samba3-parser --samba3-server --samba3-client -- dfs.idl -This man page is correct for version 4.0 of the Samba suite. L. + # Generating a Samba4 NDR parser, client and server + $ ./pidl --ndr-parser --ndr-client --ndr-server -- samr.idl =head1 SEE ALSO L, L, -yapp(1) +L, +L =head1 LICENSE @@ -438,7 +384,7 @@ pidl is licensed under the GNU General Public License L +Copyright (C) Jelmer Vernooij Usage: pidl [options] [--] [...] -- cgit