1 % file: .../doc/intro-1.2.tex
3 % $Header: /cvs/Darwin/Security/SecuritySNACCRuntime/doc/intro-1.2.tex,v 1.1.1.1 2001/05/18 23:14:10 mb Exp $
4 % $Log: intro-1.2.tex,v $
5 % Revision 1.1.1.1 2001/05/18 23:14:10 mb
6 % Move from private repository to open source repository
8 % Revision 1.1.1.1 1999/03/16 18:05:53 aram
9 % Originals from SMIME Free Library.
11 % Revision 1.2 1997/02/16 16:49:30 rj
12 % made return *this after calling abort()'' a compile time option.
14 % Revision 1.1 1997/01/01 22:47:30 rj
18 \chapter{\label{intro-
1.2}Introduction
}
20 Snacc compiles ASN
.1 \cite{X
.208} (Abstract Syntax Notation One) modules into C, C++, CORBA IDL
\cite{corba
} or type tables.
21 The generated C or C++ code contains equivalent data structures and
22 routines to convert values between the internal (C or C++)
23 representation and the corresponding BER
\cite{X
.209} (Basic Encoding Rules) format.
24 The name ``snacc'' is an acronym for ``Sample Neufeld ASN
.1 to C/C++ Compiler''.
26 This is release
1.2rj
\footnote{\emph{1.2} since it is the successor of
1.1 and
\emph{rj
} as i don't think that I'm the only one who worked on Snacc.
} of Snacc.
27 This chapter lists only the differences to the original author's last release, Snacc~
1.1.
28 The list in this chapter is incomplete---for a more thorough enumeration, see the file
{\ufn .../ChangeLog
}.
33 The output files generated get names derived from their input file's name, with only the suffix replaced.
34 This eases makefile writing, as now you can use simple suffix rules or other forms of filename pattern matching.
35 The old behaviour, where the output files got their name from the ASN
.1 module name, can be retained by using the
{\ufn -mm
} command line switch to
{\ufn snacc
}.
37 The C++ backend generates code with a much more complete set of constructors, destructors and assignment operators.
39 The C++ backend can supply the generated C++ classes with
\emph{meta
} information about their own structure.
40 This information can be used to build interpreted interfaces; the Snacc
1.2rj distribution contains a Tcl interface that uses this meta information as well as a Tcl script (that uses the Tcl interface) for a simple editor.
42 Snacc has successfully been ported to Linux and Alpha OSF/
1, and should be both byte order and
64 bit clean.
44 A new backend that generates CORBA IDL (work-in-progress, not even alpha)
47 The makefiles have been rewritten.
48 The old ones removed the
{\ufn .o
} files after successful compilation, and thus, for every tiny code change, a full recompilation took place!
49 With the new set of makefiles, only those files that need to be remade are.
50 Following usual conventions, the phony targets depend, check, install, clean and clobber have been added.
52 NOTE: the makefiles still are not safe for parallel making.
54 See Appendix~
\ref{makefile-sect
} for some explanations of some the makefile tricks.
56 If you've got problems with the makefiles, please refer to the appendix!
58 The
1.1 release used five config.h files, and three almost identical copies of the ASN
.1 C library.
59 They have all been merged in the file
{\ufn \dots/snacc.h
}.
60 A very small number (currently three) of compilation switches has been put into
{\ufn \dots/policy.h
}.
62 The previous release produced huge virtual inline functions.
63 Due to their size, these inlines wouldn't get inlined anyway.
64 Virtual functions don't get inlined (they get referenced via pointer in the virtual function table).
65 Due to their size they wouldn't offer any speed advantage (the function call overhead diminishes).
66 Instead, the compiler generated static functions in every
{\ufn .C
} file were the
{\ufn .h
} file is included!
67 This inflates the
{\ufn .o
} files and executables real quick (I'm speaking of MBytes per executable).
68 These functions have been turned into normal functions.
70 \section{\label{install-section
}Configuring and Installing Snacc
}
72 First of all, if you haven't already done so, un-archive Snacc to
73 produce the directory
{\ufn snacc-
1.2rj.
\textit{patchlevel
}} and its contents.
74 The directory
{\ufn snacc-
1.2rj.
\textit{patchlevel
}} will henceforth be referred to as ``
{\ufn \dots}''.
75 The following tools are required to compile Snacc:
77 \item {\ufn make
} (GNU
{\ufn make
} is recommended)
78 \item {\ufn patch
} (for a tiny patch in
{\ufn \dots/c-lib/
})
79 \item {\ufn makedepend
} or a look-alike (all of them have their advantages and disadvantages, it is hard to recommend any of them, see below)
80 \item {\ufn lex
} or GNU's
{\ufn flex
} (
{\ufn flex
} is recommended)
81 \item {\ufn yacc
} or GNU's
{\ufn bison
} (
{\ufn bison
} is recommended)
82 \item a C compiler (it doesn't have to support ANSI, K\&R will do)
85 Some versions of
{\ufn yacc
} may choke due to the large size of the
86 {\ufn parse-asn1.y
} file, however, we have had no problems with
{\ufn bison
}.
87 Our
{\ufn yacc
} grammar for ASN
.1 has
61 shift/reduce errors and
2
88 reduce/reduce errors. Most of these errors were introduced when
89 certain macros were added to the compiler. Some of the shift/reduce
90 errors will require you to follow the offending macro in the ASN
.1
91 module with a semi-colon. The reduce/reduce errors were introduced by
92 macros that have ``Type or Value Lists'' because the NULL Type and
93 NULL values use the same symbol, ``NULL''. This is not a problem
94 since no real processing is done with the macros in question at the
97 {\ufn Lex
} will work for the
{\ufn lex-asn1.l
} file but
{\ufn flex
} will typically
98 produce a smaller executable. Most versions of
{\ufn lex
} have a small
99 maximum token size that will cause problems for long tokens in the
100 ASN
.1 source files, such as quoted strings. To avoid this problem,
101 increase the
{\C YYLMAX
} value in the generated
{\ufn lex-asn1.c
} file to at least
102 2048.
{\ufn Flex
} does not seem to have this problem.
104 The configuration process has been simplified (at least for the installer of Snacc ;-) by the use of GNU autoconf.
106 The only file has may have to be edited is
{\ufn \dots/policy.h
}.
107 It contains a few compilation switches you may want to toggle.
109 The behaviour of makedepend has been changed from X11R5 to R6.
110 The new version keeps the source files' dirname and replaces the suffix only, the old version removed the dirname.
111 The makefiles expect the new behaviour.
112 If you've still got the R5 makedepend, the compiler's dependencies will be useless.
113 (If you only install the code and don't make any source code changes, this won't hurt you.)
114 If you haven't got
{\ufn makedepend
}, you can use any of the look-alikes, which often are
{\ufn sh
}-scripts calling the compiler with the
{\ufn -M
}-switch.
115 If you don't plan to make any source code changes, you can replace
{\ufn makedepend
} with
{\ufn /bin/true
}.
117 Warning: MIT X11's makedepend is broken, in both R5 and R6.
118 It silently does not produce any output for many of Snacc's C++ files (in
{\ufn \dots/c++-lib/
}).
120 The C compiler called with the
{\ufn -M
}-switch gives much better results, but is
\emph{much
} slower.
122 The Snacc compiler and library C code has been written to support ANSI or non-ANSI C\@.
123 The configuration script tries to find out whether your C compiler understands ANSI C\@.
125 The configuration script generates two files:
127 \item[{\ufn \dots/makehead
}] gets included by all makefiles.
128 It contains a lot of definitions used by make.
129 \item[{\ufn \dots/config.h
}] contains all the machine, operating system, compiler and environment dependent settings.
130 It is included by
{\ufn \dots/snacc.h
}.
133 The C++ runtime library is known to compile with both
{\ufn gcc
2.5.8} and
{\ufn gcc
2.6.3}.
134 The latter has the
{\C bool
} type built-in (which the configuration script automatically detects).
136 Finally, to compile
{\ufn snacc
} and the C and C++ runtime libraries,
137 type the following at the shell prompt:
145 If you wish to install only the C (including type tables) or only the
146 C++ versions of the library, type
{\ufn make c
} or
{\ufn make c++
},
147 respectively, instead of
{\ufn make
}. If the make succeeds, the
148 {\ufn snacc
} binary should be present as
{\ufn \dots/compiler/snacc
},
149 the C runtime libraries,
{\ufn libasn1csbuf.a
},
150 {\ufn libasn1cebuf.a
},
{\ufn libasn1cmbuf.a
} and
{\ufn libasn1ctbl.a
}, should be in
151 {\ufn \dots/c-lib/
} and the C++ runtime library,
{\ufn libasn1c++.a
}
152 (and, if you compiled with the Tcl option enabled,
153 another runtime library,
{\ufn libasn1tcl.a
}),
154 should be in
{\ufn \dots/c++-lib/
}.
155 The type table tools,
156 {\ufn ptbl
},
{\ufn pval
} and
{\ufn mkchdr
}, will be in their respective directories under
{\ufn \dots/tbl-tools/
}.
158 After compiling the libraries, you can test the library routines by calling
{\ufn make check
}
159 (or by calling
{\ufn make c-check
} or
{\ufn make c++-check
} to test the C or C++ library routines only, respectively).
161 Manual pages that contain information on running
{\ufn snacc
} and the type table tools can be found in
{\ufn \dots/doc/
}.
163 To install Snacc, you can call
{\ufn make install
} (or
{\ufn make c-install
} or
{\ufn make c++-install
}, respectively).
164 This installs the snacc compiler binary, the libraries, the
{\ufn .h
} and
{\ufn .asn1
} files, the type table tools, as well as the manual pages into the usual directories.
166 To remove the
{\ufn .o
} and other intermediate files, you can call
{\ufn make clean
}.
167 To remove the binaries, libraries and all other generated files as well, call
{\ufn make clobber
}.
169 \section{\label{run-section
}Running Snacc
}
171 Snacc is typically invoked from the shell command line and has the synopsis:
173 snacc
[-h
] [-P
] [-t
] [-e
] [-d
] [-p
] [-f
]
174 [ -c | -C | -idl | -T <table output file>
]
175 [-meta <module>.<type>
[,...
]] [-mA | -mC
]
176 [-tcl <module>.<type>
[,...
]]
177 [-u <useful types ASN
.1 file>
]
178 [-mm
] [-mf <max file name len>
]
184 Snacc generates C or C++ source code for BER encode and decode
185 routines as well as print and free routines for each type in the given
186 ASN
.1 modules. Alternatively, snacc can produce type tables that can
187 be used for table based/interpreted encoding and decoding. The type
188 table based methods tend to be slower than their C or C++ counterparts
189 but they tend use less memory (table size vs. C/C++ object code).
191 Snacc may also be used to generate CORBA IDL\@.
192 This part of Snacc is very new and I would rate it as pre-alpha.
194 The
{\ufn -meta
},
{\ufn -mA
},
{\ufn -mC
} and
{\ufn -tcl
} options are only present when the Tcl and Tk libraries where found at configuration time.
196 Most of the
1990 ASN
.1 features are parsed although some do not affect
197 the generated code. Fairly rigourous error checking is performed on
198 the ASN
.1 source; any errors detected will be reported (printed to
201 Each file in the ASN
.1 file list should contain a complete ASN
.1
202 module. ASN
.1 modules that use the IMPORTS feature must be compiled
203 together (specify all necessary modules in the ASN
.1 file list). The
204 generated source files will include each module's header file in the
205 command line order. This makes it important to order the modules from
206 least dependent to most dependent on the command line to avoid type
207 ordering problems. Currently, snacc assumes that each ASN
.1 file
208 given on the command line depends on all of the others on the command
209 line. No attempt is made to only include the header files from
210 modules referenced in the import list for that module.
212 If the target language is C, snacc will generate a
{\ufn .h
} and
{\ufn .c
} file for each specified ASN
.1 module.
213 If the target language is C++, snacc will generate a
{\ufn .h
} and
{\ufn .C
} file for each module.
214 If the target language is CORBA IDL, snacc will generate an
{\ufn .idl
} file for each module.
215 The generated file names will be derived from the module's filenames, or from the
216 module names if the
{\ufn -mm
} command line switch has been given.
218 The command line options are:
221 \item[--h
] {short for ``help'', prints a synopsis of snacc and exits.
}
223 \item[--c
] {causes snacc to generate C source code.
224 This is the default behaviour of snacc if neither of the
{\ufn -c
} or
{\ufn -C
} options are given.
225 Only one of the
{\ufn -c
},
{\ufn -C
},
{\ufn -idl
} or
{\ufn -T
} options should be specified.
}
227 \item[--C
] {causes snacc to generate C++ source code.
}
229 \item[--novolat
] {causes snacc to generate C++ ``
{\C return *this
}''
230 after calling
{\C abort()
}. (Some broken compilers don't know about
231 volatile functions, or their abort() isn't correctly typed.)
}
233 \item[--idl
] {causes snacc to generate CORBA IDL source code.
}
235 \item[--T
\emph{file
}] {causes snacc to generate type tables and write them to the given file
\emph{file
}.
}
237 \item[--meta
\emph{types
}]
238 causes snacc to generate C++ classes with type meta information.
239 Requires C++ functionality and therefore implies
{\ufn -C
} (C++ code generation).
241 The
\emph{types
} denote the PDUs and have the following syntax: a comma-separated list of pairs of: module name, a dot, and a type name from that module. (Example:
{\ufn snacc -tcl M1.T-a,M-
2.Tb mod1.asn1 m2.asn1
})
243 \item[--mA
\textnormal{and
} --mC
]
244 causes the metacode to use identifiers as defined in the ASN
.1 source files or as used in the generated C++ code, respectively.
245 (It defaults to
{\ufn -mC
}.)
247 \item[--tcl
\emph{types
}]
248 causes snacc to generate functions for a Tcl interface.
249 Needs the type meta information and thus implies
{\ufn -meta
} (see above).
250 The
{\ufn -meta
} option can and should be omitted, the
\emph{types
} are as for the
{\ufn -meta
} option (the
\emph{types
} arguments are additive, in case you specify both options).
252 \item[--P
] {causes snacc to print the parsed ASN
.1 modules to
{\C stdout
} after the types have been linked, sorted, and processed.
253 This option is useful for debugging snacc and observing the modifications snacc performs on the types to make code generation simpler.
}
256 The options,
{\ufn -t, -v, -e, -d, -p,
} and
{\ufn -f
} affect
257 what types and routines go into the generated source code.
258 These options do not affect type table generation. If none of
259 them are given on the command line, snacc assumes that all of them are
260 in effect. For example, if you do not need the Free or Print
261 routines, you should give the
{\ufn -t -v -e -d
} options to snacc.
262 This lets you trim the size of the generated code by removing
263 unnecessary routines; the code generated from large ASN
.1
264 specifications can produce very large binaries.
268 causes snacc to generate type definitions in the target language for each ASN
.1 type.
271 causes snacc to generate value definitions in the target language for each ASN
.1 value.
272 Currently value definitions are limited to INTEGERs, BOOLEANs and OBJECT IDENTIFIERs.
275 causes snacc to generate encode routines in the target language for each ASN
.1 type.
278 causes snacc to generate decode routines in the target language for each ASN
.1 type.
281 causes snacc to generate print routines in the target language for each ASN
.1 type.
284 causes snacc to generate free routines in the target language for each ASN
.1 type.
285 This option only works when the target language is C\@.
286 The free routines hierarchically free C values.
287 A more efficient approach is to use the provided nibble-memory system.
288 The nibble memory permits freeing an entire decoded value without traversing the decoded value.
289 This is the default memory allocator used by snacc generated decoders.
290 See file
{\ufn \dots/c-lib/inc/asn-config.h
} to change the default memory system.
291 For more information on the memory management see Section~
\ref{lib-mem-C-section
}.
293 \item[--u
\emph{file
}]
294 causes snacc to read the useful types definitions from the ASN
.1 module in file
\emph{file
} for linking purposes.
295 For some ASN
.1 specifications, such as SNMP, the useful types are not needed.
296 The types in the given useful types file are globally available to all modules; a useful type definition is overridden by a local or explicitly imported type with the same name.
297 The useful type module can be found in
{\ufn \dots/asn1specs/asn-useful.asn1
} and contains:
299 \setlength{\itemsep}{0pt
}
300 \setlength{\parsep}{0pt
}
302 \item ObjectDesccriptor
304 \item PrintableString
313 \item GeneralizedTime
318 This switch is supplied for backwards compatibility.
319 Snacc versions
1.0 and
1.1 produced files with names generated from the ASN
.1 module name contained in the input file.
320 Snacc
1.2rj by default retains the input file name and replaces the suffix only.
321 The new behaviour makes
{\ufn makefile
} writing easier, as with modern
{\ufn make
}s, pattern matching can be used.
323 \item[--mf
\emph{number
}]
324 causes the names of the generated source files to have a maximum length of
\emph{number
} characters, including their suffix.
325 The
\emph{number
} argument must be at least
3.
326 This option is useful for supporting operating systems that only support short file names.
327 A better solution is to shorten the module name of each ASN
.1 module.
329 \item[--l
\emph{number
}]
330 this is fairly obscure but may be useful.
331 Each error that the decoders can
report is given an id number.
332 The number
\emph{number
} is where the error ids start decreasing from as they are assigned to errors.
333 The default is -
100 if this option is not given.
334 Avoid using a number in the range -
100 to
0 since they may conflict with the library routines' error ids.
335 If you are re-compiling the useful types for the library use -
50.
336 Another use of this option is to integrate newly generated code with older code; if done correctly, the error ids will not conflict.
340 Since ASN
.1 has different scoping rules than C and C++, some name munging
341 is done for types, named-numbers etc. to eliminate conflicts.
342 Some capitalization schemes were chosen to fit common C programming
343 style. For all names, dashes in the ASN
.1 source are converted to
344 underscores. See Sections
\ref{naming-C-section
} and
\ref{naming-C++-section
}
345 for more naming information.
347 If the
{\ufn -mm
} switch has been given, the module name is used as a base name for the generated source file
348 names. It will be put into lowercase and dashes will be replaced with
349 underscores. Module names that result in file names longer than
350 specified with the
{\ufn -mf
} option will be truncated. If the
351 {\ufn -mf
} option was not given, file names will be truncated if they
352 are too long for the target file system. You may want to shorten long
353 module names to meaningful abbreviations. This will avoid file name
354 conflicts for module names that are truncated to the same substring.
355 Any module name and file name conflicts will be reported.
357 If your ASN
.1 modules have syntactic or semantic errors, each error
358 will be printed to
{\C stderr
} along with the file name and line number of
359 where it occurred. These errors are usable by GNU emacs compiling
360 tools. See the next chapter for more information on the types of
361 errors snacc can detect.
363 More errors can be detected and reported in a single compile if type
364 and value definitions are separated by semi-colons. Separating type
365 and value definitions with semi-colons is not required, and if used,
366 need not be used to separate all type and value definitions.
367 Semi-colons are necessary after some macros that introduce ambiguity.
368 In general, if you get a parse error you can't figure out, try
369 separating the surrounding type/value definitions with semicolons.
372 \subsection{Known Bugs
}
376 Snacc has problems with the following case:
381 val ANY DEFINED BY id\-\\
387 b OBJECT IDENTIFIER\-\\
391 The error checking pass will print an error to the effect that the id
392 type must be INTEGER or OBJECT IDENTIFER\@. To fix this you must modify
393 the error checking pass as well as the code generation pass. To be
394 cheap about it, disable/fix the error checking and hand modify the
398 The hashing code used for handling ANY DEFINED BY id to type mappings
399 will encounter problems if the hash table goes more than four levels
400 deep (I think this is unlikely). To fix this just add linear chaining
404 The
{\ufn \dots/configure
} script should check whether the machine's floating point format is IEEE or whether the IEEE library exists.
407 The C++ library severly lacks a convenient buffer management class that automatically expands like the C libraries' ExpBuf.
408 What use is an efficient buffer management when you have got to build a loop a round snacc's encoding routine that reallocates larger buffers until the result fits?
411 Where this
document describes personal experiences, it is usually unclear to which author `I' refers.
412 (One way to find out is to look at snacc~
1.1's documentation.)
416 \section{\label{bug-section
}Reporting Bugs and Your Own Improvements
}
418 Snacc
1.1 was Michael Sample's final release.
419 While he is watching Snacc's development, he isn't actively developing it himself.
421 Since there are quite a number of changes from release
1.1 to
1.2rj, bug reports and new features are best sent to me.
422 I can be reached as
\texttt{Robert Joop <rj@rainbow.in-berlin.de>
} or
\texttt{<rj@fokus.gmd.de>
}.
projects / apple / security.git / blob