version 0.9
diff --git a/doc/asn1c-usage.html b/doc/asn1c-usage.html
index 8aeafae..d7b22b0 100644
--- a/doc/asn1c-usage.html
+++ b/doc/asn1c-usage.html
@@ -1,4 +1,3 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
original version by: Nikos Drakos, CBLU, University of Leeds
@@ -11,8 +10,6 @@
<META NAME="description" CONTENT="Using the Free ASN.1 Compiler">
<META NAME="asn1c, ASN.1, free, compiler, BER, DER, PER, XER\">
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
</HEAD>
@@ -28,6 +25,8 @@
<P ALIGN="CENTER"><STRONG>Lev Walkin <vlm@lionet.info></STRONG></P>
</DIV>
+
+<P>
<BR>
<H2><A NAME="SECTION01000000000000000000">
@@ -36,83 +35,97 @@
<!--Table of Contents-->
<UL>
-<LI><A NAME="tex2html38"
+<LI><A NAME="tex2html45"
HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A>
<UL>
-<LI><A NAME="tex2html39"
+<LI><A NAME="tex2html46"
HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A>
<UL>
-<LI><A NAME="tex2html40"
+<LI><A NAME="tex2html47"
HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A>
<UL>
-<LI><A NAME="tex2html41"
+<LI><A NAME="tex2html48"
HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A>
-<LI><A NAME="tex2html42"
+<LI><A NAME="tex2html49"
HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A>
-<LI><A NAME="tex2html43"
+<LI><A NAME="tex2html50"
HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A>
-<LI><A NAME="tex2html44"
+<LI><A NAME="tex2html51"
HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A>
-<LI><A NAME="tex2html45"
+<LI><A NAME="tex2html52"
HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A>
-<LI><A NAME="tex2html46"
+<LI><A NAME="tex2html53"
HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A>
</UL>
-<LI><A NAME="tex2html47"
+<LI><A NAME="tex2html54"
HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A>
<UL>
-<LI><A NAME="tex2html48"
+<LI><A NAME="tex2html55"
HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A>
-<LI><A NAME="tex2html49"
+<LI><A NAME="tex2html56"
HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A>
-<LI><A NAME="tex2html50"
+<LI><A NAME="tex2html57"
HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A>
-<LI><A NAME="tex2html51"
+<LI><A NAME="tex2html58"
HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A>
-<LI><A NAME="tex2html52"
+<LI><A NAME="tex2html59"
HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A>
</UL>
-<LI><A NAME="tex2html53"
+<LI><A NAME="tex2html60"
HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A>
<UL>
-<LI><A NAME="tex2html54"
+<LI><A NAME="tex2html61"
HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A>
-<LI><A NAME="tex2html55"
+<LI><A NAME="tex2html62"
HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A>
-<LI><A NAME="tex2html56"
+<LI><A NAME="tex2html63"
HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A>
-<LI><A NAME="tex2html57"
+<LI><A NAME="tex2html64"
HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A>
-<LI><A NAME="tex2html58"
+<LI><A NAME="tex2html65"
HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A>
</UL>
</UL>
</UL><BR>
-<LI><A NAME="tex2html59"
+<LI><A NAME="tex2html66"
HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A>
<UL>
-<LI><A NAME="tex2html60"
+<LI><A NAME="tex2html67"
HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A>
+<LI><A NAME="tex2html68"
+ HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A>
+<LI><A NAME="tex2html69"
+ HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A>
<UL>
-<LI><A NAME="tex2html61"
- HREF="asn1c-usage.html#SECTION03110000000000000000">Quick start</A>
-<LI><A NAME="tex2html62"
- HREF="asn1c-usage.html#SECTION03120000000000000000">Slow start</A>
+<LI><A NAME="tex2html70"
+ HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A>
+<LI><A NAME="tex2html71"
+ HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A>
+<LI><A NAME="tex2html72"
+ HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from the application</A>
<UL>
-<LI><A NAME="tex2html63"
- HREF="asn1c-usage.html#SECTION03121000000000000000">Recognizing compiler output</A>
-<LI><A NAME="tex2html64"
- HREF="asn1c-usage.html#SECTION03122000000000000000">Invoking the ASN.1 helper code from the application</A>
+<LI><A NAME="tex2html73"
+ HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A>
+<LI><A NAME="tex2html74"
+ HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A>
+<LI><A NAME="tex2html75"
+ HREF="asn1c-usage.html#SECTION03333000000000000000">Validating the target structure</A>
+<LI><A NAME="tex2html76"
+ HREF="asn1c-usage.html#SECTION03334000000000000000">Printing the target structure</A>
+<LI><A NAME="tex2html77"
+ HREF="asn1c-usage.html#SECTION03335000000000000000">Freeing the target structure</A>
</UL>
</UL>
</UL><BR>
-<LI><A NAME="tex2html65"
+<LI><A NAME="tex2html78"
HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
</UL>
<!--End of Table of Contents-->
<P>
+<P>
+
<H1><A NAME="SECTION02000000000000000000">
ASN.1 Basics</A>
</H1>
@@ -157,15 +170,13 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
Rectangle ::= SEQUENCE {
height INTEGER,
width INTEGER
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
containing two integer fields. This specification may tell the reader
that there is this kind of data structure and that some entity may
@@ -183,28 +194,27 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
UsageExampleModule1
{ iso org(3) dod(6) internet(1) private(4)
enterprise(1) spelio(9363) software(1)
asn1c(5) docs(2) usage(1) 1 }
- AUTOMATIC TAGS DEFINITIONS ::=
+ DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
-- This is a comment which describes nothing.
Rectangle ::= SEQUENCE {
height INTEGER, -- Height of the rectangle
- width INTEGER, -- Width of the rectangle
+ width INTEGER -- Width of the rectangle
}
END
-
</PRE>
-</DD>
+</BLOCKQUOTE>
The module header consists of module name (UsageExampleModule1), the
-module object identifier ({...}), some flags (AUTOMATIC TAGS) and
-''DEFINITIONS ::= BEGIN''. The module ends with an ''END'' statement.
+module object identifier ({...}), a keyword ''DEFINITIONS'', a
+set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module
+ends with an ''END'' statement.
<P>
@@ -235,16 +245,16 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
SimpleInteger ::= INTEGER
+
-- An integer with a very limited range
SmallInt ::= INTEGER (0..127)
+
-- Integer, negative
NegativeInt ::= INTEGER (MIN..0)
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -258,11 +268,11 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
FruitId ::= ENUMERATED { apple(1), orange(2) }
+
-- The numbers in braces are optional,
--- the enumeration may be performed
+-- the enumeration can be performed
-- automatically by the compiler
ComputerOSType ::= ENUMERATED {
FreeBSD, -- will be 0
@@ -271,9 +281,8 @@
Linux, -- will be 6
MacOS -- will be 7
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -305,18 +314,18 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
ExampleOID ::= OBJECT IDENTIFIER
+
usageExampleModule1-oid ExampleOID
::= { 1 3 6 1 4 1 9363 1 5 2 1 1 }
+
-- An identifier of the Internet.
internet-id OBJECT IDENTIFIER
::= { iso(1) identified-organization(3)
dod(6) internet(1) }
-
</PRE>
-</DD>
+</BLOCKQUOTE>
As you see, names are optional.
<P>
@@ -333,14 +342,13 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
this-document RELATIVE-OID ::= { docs(2) usage(1) }
+
this-example RELATIVE-OID ::= {
this-document assorted-examples(0) this-example(1) }
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -356,7 +364,7 @@
<P>
This is essentially the ASCII, with 128 character codes available
-(7 lower bits of 8-bit byte).
+(7 lower bits of an 8-bit byte).
<P>
@@ -400,15 +408,15 @@
<P>
The character string with the alphabet which is more or less a subset
-of ASCII between space and ''~'' (tilde). Alternatively,
-the alphabet may be represented as the PrintableString alphabet described
-earlier, plus the following characters: ''<B>!</B>'', ''<B>''</B>'',
-''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'', ''<B>&</B>'',
-''<B>*</B>'', ''<B>;</B>'', ''<B><</B>'', ''<B>></B>'',
-''<B>[</B>'', ''<B>\</B>'', ''<B>]</B>'',
-''<B>^</B>'', ''<B>_</B>'', ''<B>`</B>''
-(single left quote), ''<B>{</B>'', ''<B>|</B>'', ''<B>}</B>'',
-''~''.
+of ASCII between space and ''<B>~</B>'' (tilde).
+Alternatively, the alphabet may be described as the PrintableString
+alphabet presented earlier, plus the following characters: ''<B>!</B>'',
+''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
+''<B>&</B>'', ''<B>*</B>'', ''<B>;</B>'', ''<B><</B>'',
+''<B>></B>'', ''<B>[</B>'', ''<B>\</B>'',
+''<B>]</B>'', ''<B>^</B>'', ''<B>_</B>'',
+''<B>`</B>'' (single left quote), ''<B>{</B>'', ''<B>|</B>'',
+''<B>}</B>'', ''<B>~</B>''.
<P>
@@ -428,8 +436,7 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
Address ::= SEQUENCE {
-- The apartment number may be omitted
apartmentNumber NumericString OPTIONAL,
@@ -439,9 +446,8 @@
-- This one may be omitted too
zipNo NumericString OPTIONAL
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -473,15 +479,13 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
ResponseCode ::= CHOICE {
intCode INTEGER,
boolCode BOOLEAN
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -494,20 +498,20 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
-- Example 1
ManyIntegers ::= SEQUENCE OF INTEGER
+
-- Example 2
ManyRectangles ::= SEQUENCE OF Rectangle
+
-- More complex example:
-- an array of structures defined in place.
ManyCircles ::= SEQUENCE OF SEQUENCE {
radius INTEGER
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -523,15 +527,14 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
-- A set of structures defined elsewhere
SetOfApples :: SET OF Apple
+
-- Set of integers encoding the kind of a fruit
FruitBag ::= SET OF ENUMERATED { apple, orange }
-
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
@@ -549,92 +552,198 @@
The purpose of the ASN.1 compiler, of which this document is part,
is to convert the ASN.1 specifications to some other target language
(currently, only C is supported<A NAME="tex2html1"
- HREF="#foot136"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
+ HREF="#foot144"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
language structures and surrounding maintenance code. For example,
the C structure which may be created by compiler to represent the
simple <I>Rectangle</I> specification defined earlier in this document,
may look like this<A NAME="tex2html2"
- HREF="#foot315"><SUP>2.2</SUP></A>:
+ HREF="#foot379"><SUP>2.2</SUP></A>:
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
typedef struct Rectangle_s {
int height;
int width;
} Rectangle_t;
-
</PRE>
-</DD>
+</BLOCKQUOTE>
This would not be of much value for such a simple specification, so
the compiler goes further and actually produces the code which fills
-in this structure by parsing the binary<A NAME="tex2html3"
- HREF="#foot142"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
+in this structure by parsing the opaque binary<A NAME="tex2html3"
+ HREF="#foot151"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
this structure as an argument and performs structure serialization
by emitting a series of bytes.
<P>
-<H1><A NAME="SECTION03110000000000000000">
+<H1><A NAME="SECTION03200000000000000000">
Quick start</A>
</H1>
<P>
-After building and installing the compiler, the asn1c command may
-be used to compile the ASN.1 specification<A NAME="tex2html4"
- HREF="#foot316"><SUP>2.4</SUP></A>:
+After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4"
+ HREF="#foot380"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
+ HREF="#foot381"><SUP>3.2</SUP></A>:
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
asn1c <I><spec.asn1></I>
-
</PRE>
-</DD>
-If several specifications contain interdependencies, all of them must
-be specified:
+</BLOCKQUOTE>
+If several specifications contain interdependencies, all of the files
+must be specified altogether:
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
asn1c <I><spec1.asn1> <spec2.asn1> ...</I>
-
</PRE>
-</DD>
-The compiler -E and -EF options are used for testing the parser and
-the semantic fixer, respectively. These options will instruct the
-compiler to dump out the parsed (and fixed) ASN.1 specification as
-it was "understood" by the compiler. It might might
-be useful to check whether a particular syntactic construction is
-properly supported by the compiler.
+</BLOCKQUOTE>
+The compiler <B>-E</B> and <B>-EF</B> options are used for testing
+the parser and the semantic fixer, respectively. These options will
+instruct the compiler to dump out the parsed (and fixed, if <B>-F</B>
+is involved) ASN.1 specification as it was "understood"
+by the compiler. It might be useful to check whether a particular
+syntactic construction is properly supported by the compiler.
<P>
-<DD><PRE>
-
-asn1c -EF <I><spec-to-test.asn1></I>
-
+<BLOCKQUOTE><PRE>
+asn1c <B>-EF</B> <I><spec-to-test.asn1></I>
</PRE>
-</DD>
-The -P option is used to dump the compiled output on the screen instead
-of creating a bunch of .c and .h files on disk in the current directory.
-You would probably want to start with -P option instead of creating
-a mess in your current directory.
+</BLOCKQUOTE>
+The <B>-P</B> option is used to dump the compiled output on the
+screen instead of creating a bunch of .c and .h files on disk in the
+current directory. You would probably want to start with <B>-P</B>
+option instead of creating a mess in your current directory. Another
+option, <B>-R</B>, asks compiler to only generate the files which
+need to be generated, and supress linking in the numerous support
+files.
+
+<P>
+Print the compiled output instead of creating multiple source files:
<P>
-<H1><A NAME="SECTION03120000000000000000">
-Slow start</A>
+<BLOCKQUOTE><PRE>
+asn1c <B>-P</B> <I><spec-to-compile-and-print.asn1></I>
+</PRE>
+</BLOCKQUOTE>
+
+<P>
+
+<H1><A NAME="SECTION03300000000000000000">
+Using the ASN.1 Compiler</A>
</H1>
<P>
-<H2><A NAME="SECTION03121000000000000000">
+<H1><A NAME="SECTION03310000000000000000">
+Command-line options</A>
+</H1>
+
+<P>
+The <A HREF=#Table1>Table 1</A> summarizes various options affecting
+the compiler's behavior.
+
+<P>
+<BR><P></P>
+<DIV ALIGN="CENTER"><A NAME="384"></A>
+<TABLE>
+<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
+The list of asn1c command line options</CAPTION>
+<TR><TD><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
+<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=JUSTIFY WIDTH="3in">
+<TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
+<B>Overall Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<B>Description</B></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-E</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Stop after the parsing stage and print the reconstructed ASN.1
+specification code to the standard output.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-F</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Used together with -E, instructs the compiler to stop after
+the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
+specification to the standard output.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-P</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Dump the compiled output to the standard output instead of
+cre- ating the target language files on disk.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-R</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Restrict the compiler to generate only the ASN.1 tables, omit-
+ting the usual support code.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-S <I><directory></I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Use the specified directory with ASN.1 skeleton files.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-t <I><data-string></I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Interpret the data-string as a sequence of hexadecimal values
+representing the start of BER TLV encoding. Print the human readable
+explanation.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Warning Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<B>Description</B></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Werror</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Treat warnings as errors; abort if any warning is produced.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-lexer</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Enable lexer debugging during the ASN.1 parsing stage.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-fixer</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+ <FONT SIZE="-1">Enable ASN.1 syntax tree fixer debugging during the
+ fixing stage.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-Wdebug-compiler</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Enable debugging during the actual compile time.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Language Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<B>Description</B></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fbless-SIZE</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Allow SIZE() constraint for INTEGER, ENUMERATED, and other
+types for which this constraint is normally prohibited by the standard.
+This is a violation of an ASN.1 standard and compiler may fail to
+produce the meaningful code.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fnative-integers</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Use native machine's integer types whenever possible, instead
+of the complex ASN.1 INTEGER and ENUMERATED types. </FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-funnamed-unions</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Enable unnamed unions in the definitions of target language's
+structures.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-ftypes88</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Use only ASN.1:1988 embedded types.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Output Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<B>Description</B></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-print-constraints</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">When -EF are also specified, this option forces the compiler
+to explain its internal understanding of subtype constraints.</FONT></TD></TR>
+</TBODY><TBODY>
+<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-print-lines</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
+<FONT SIZE="-1">Generate "- #line" comments in -E output.</FONT></TD></TR>
+</TBODY>
+</TABLE>
+
+<P>
+</TD></TR>
+</TABLE>
+</DIV><P></P><BR>
+
+<P>
+
+<H1><A NAME="SECTION03320000000000000000">
Recognizing compiler output</A>
-</H2>
+</H1>
<P>
After compiling, the following entities will be created in your current
@@ -649,10 +758,9 @@
specification defined in the beginning of this document).
</LI>
<LI>A set of helper .c and .h files which contain generic encoders, decoders
-and other useful routines. There will be many of them, some of them
-even not necessary<A NAME="tex2html5"
- HREF="#foot161"><SUP>2.5</SUP></A>, but the overall amount of code after compiling will be rather small
-anyway.
+and other useful routines. There will be quite a few of them, some
+of them even are not always necessary, but the overall amount of code
+after compiling will be rather small anyway.
</LI>
</UL>
It is your responsibility to create .c file with the <I>int main()</I>
@@ -670,33 +778,29 @@
<P>
-<DD><PRE>
-
-cc -o rectangle *.c # It could be <I>that</I> simple<A NAME="tex2html6"
- HREF="#foot319"><SUP>2.6</SUP></A>
-
+<BLOCKQUOTE><PRE>
+cc -o rectangle *.c # It could be <I>that</I> simple<A NAME="tex2html7"
+ HREF="#foot387"><SUP>4.1</SUP></A>
</PRE>
-</DD>
+</BLOCKQUOTE>
<P>
-<H2><A NAME="SECTION03122000000000000000">
+<H1><A NAME="SECTION03330000000000000000">
Invoking the ASN.1 helper code from the application</A>
-</H2>
+</H1>
<P>
-First of all, you would want to include one or more header files into
-your application. For the Rectangle module, including the Rectangle.h
+First of all, you should to include one or more header files into
+your application. For our Rectangle module, including the Rectangle.h
file is enough:
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
#include <Rectangle.h>
-
</PRE>
-</DD>
+</BLOCKQUOTE>
The header files defines the C structure corresponding to the ASN.1
definition of a rectangle and the declaration of the ASN.1 type descriptor,
which is used as an argument to most of the functions provided by
@@ -705,14 +809,13 @@
<P>
-<DD><PRE>
-
-Rectangle_t *rect = ;
+<BLOCKQUOTE><PRE>
+Rectangle_t *rect = ...;
+
asn1_DEF_Rectangle->free_struct(&asn1_DEF_Rectangle,
rect, 0);
-
</PRE>
-</DD>
+</BLOCKQUOTE>
This code defines a <I>rect</I> pointer which points to the Rectangle_t
structure which needs to be freed. The second line invokes the generic
free_struct routine created specifically for this Rectangle_t structure.
@@ -730,8 +833,8 @@
explicit subtype constraints. Please refer to Section sub:Validating-the-target.
</DD>
<DT><STRONG>ber_decoder</STRONG></DT>
-<DD>This is the generic <I>restartable</I><A NAME="tex2html7"
- HREF="#foot183"><SUP>2.7</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
+<DD>This is the generic <I>restartable</I><A NAME="tex2html8"
+ HREF="#foot241"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
and/or fill the target structure for you. Please refer to Section
[<A HREF="#sub:Decoding-BER">Decoding-BER</A>].
</DD>
@@ -761,10 +864,9 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
Rectangle_t *
-simple_deserializer(void *buffer, size_t buf_size) {
+simple_deserializer(const void *buffer, size_t buf_size) {
Rectangle_t *rect = 0; /* Note this 0! */
ber_dec_rval_t rval;
@@ -777,14 +879,14 @@
if(rval<B>.code</B> == RC_OK) {
return rect; /* Decoding succeeded */
} else {
+ /* Free partially decoded rect */
asn1_DEF_Rectangle->free_struct(
&asn1_DEF_Rectangle, rect, 0);
return 0;
}
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
The code above defines a function, <I>simple_deserializer</I>, which
takes a buffer and its length and expected to return a pointer to
the Rectangle_t structure. Inside, it tries to convert the bytes
@@ -807,9 +909,9 @@
<P>
-<H3><A NAME="SECTION03122100000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
+<H2><A NAME="SECTION03331000000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
Decoding BER
-</H3>
+</H2>
<P>
The Basic Encoding Rules describe the basic way how the structure
@@ -859,13 +961,11 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
rval = ber_decode(&asn1_DEF_Rectangle, (void **)&rect,
buffer, buf_size);
-
</PRE>
-</DD>
+</BLOCKQUOTE>
Note that the initial (asn1_DEF_Rectangle->ber_decoder) reference
is gone, and also the last argument (0) is no longer necessary.
@@ -901,9 +1001,9 @@
<P>
-<H3><A NAME="SECTION03122200000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
+<H2><A NAME="SECTION03332000000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
Encoding DER
-</H3>
+</H2>
<P>
The Distinguished Encoding Rules is the variant of BER encoding rules
@@ -920,13 +1020,13 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
/*
* This is a custom function which writes the
* encoded output into some FILE stream.
*/
-int _write_stream(void *buffer, size_t size, void *app_key) {
+static int
+write_stream(const void *buffer, size_t size, void *app_key) {
FILE *ostream = app_key;
size_t wrote;
@@ -945,7 +1045,7 @@
der_enc_rval_t rval; /* Return value */
rval = der_encode(&asn1_DEF_Rect, rect,
- _write_stream, ostream);
+ write_stream, ostream);
if(rval<B>.encoded</B> == -1) {
/*
* Failure to encode the rectangle data.
@@ -959,9 +1059,8 @@
return rval.encoded;
}
}
-
</PRE>
-</DD>
+</BLOCKQUOTE>
As you see, the DER encoder does not write into some sort of buffer
or something. It just invokes the custom function (possible, multiple
times) which would save the data into appropriate storage. The optional
@@ -974,8 +1073,8 @@
DER encoder will essentially do the same thing (i.e., encode the data)
but no callbacks will be invoked (so the data goes nowhere). It may
prove useful to determine the size of the structure's encoding before
-actually doing the encoding<A NAME="tex2html8"
- HREF="#foot253"><SUP>2.8</SUP></A>.
+actually doing the encoding<A NAME="tex2html9"
+ HREF="#foot313"><SUP>4.3</SUP></A>.
<P>
Please look into der_encoder.h for the precise definition of der_encode()
@@ -983,9 +1082,9 @@
<P>
-<H3><A NAME="SECTION03122300000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
+<H2><A NAME="SECTION03333000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
Validating the target structure
-</H3>
+</H2>
<P>
Sometimes the target structure needs to be validated. For example,
@@ -1011,9 +1110,9 @@
<P>
-<H3><A NAME="SECTION03122400000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
+<H2><A NAME="SECTION03334000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
Printing the target structure
-</H3>
+</H2>
<P>
There are two ways to print the target structure: either invoke the
@@ -1022,20 +1121,18 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
asn_fprint(stdout, &asn1_DEF_Rectangle, rect);
-
</PRE>
-</DD>
+</BLOCKQUOTE>
Please look into constr_TYPE.h for the precise definition of asn_fprint()
and related types.
<P>
-<H3><A NAME="SECTION03122500000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
+<H2><A NAME="SECTION03335000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
Freeing the target structure
-</H3>
+</H2>
<P>
Freeing the structure is slightly more complex than it may seem to.
@@ -1046,17 +1143,15 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
struct my_figure { /* The custom structure */
int flags; /* <some custom member> */
/* The type is generated by the ASN.1 compiler */
<I>Rectangle_t rect;</I>
/* other members of the structure */
};
-
</PRE>
-</DD>
+</BLOCKQUOTE>
In this example, the application programmer defined a custom structure
with one ASN.1-derived member (rect). This member is not a reference
to the Rectangle_t, but an in-place inclusion of the Rectangle_t
@@ -1075,8 +1170,7 @@
<P>
-<DD><PRE>
-
+<BLOCKQUOTE><PRE>
/* Rectangle_t is defined within my_figure */
struct my_figure *mf = <B>...</B>;
/*
@@ -1094,9 +1188,8 @@
*/
asn1_DEF_Rectangle->free_struct(
&asn1_DEF_Rectangle, rect, <I>0</I> /* free the pointer too */);
-
</PRE>
-</DD>
+</BLOCKQUOTE>
It is safe to invoke the <I>free_struct</I> function with the target
structure pointer set to 0 (NULL), the function will do nothing.
@@ -1104,7 +1197,9 @@
<H2><A NAME="SECTION04000000000000000000">
Bibliography</A>
-</H2><DL COMPACT><DD><P></P><DT><A NAME="Dub00">Dub00</A>
+</H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A>
+<DD>Free ASN.1 Compiler. http://lionet.info/asn1/
+<P></P><DT><A NAME="Dub00">Dub00</A>
<DD>Olivier Dubuisson - <I>ASN.1 Communication between heterogeneous
systems</I> - Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
ISBN:0-12-6333361-0.
@@ -1114,51 +1209,52 @@
<P>
<BR><HR><H4>Footnotes</H4>
<DL>
-<DT><A NAME="foot136">... supported</A><A
+<DT><A NAME="foot144">... supported</A><A
HREF="asn1c-usage.html#tex2html1"><SUP>2.1</SUP></A></DT>
-<DD>C++ is ''supported'' too, as long as an object-oriented approach
-is not a definitive factor.
+<DD>C++ is ''supported'' too, as long as an class-based approach is
+not a definitive factor.
</DD>
-<DT><A NAME="foot315">... this</A><A
+<DT><A NAME="foot379">... this</A><A
HREF="asn1c-usage.html#tex2html2"><SUP>2.2</SUP></A></DT>
<DD><I>-fnative-integers</I> compiler option is used to produce basic
-C <I>int</I> types instead of generic INTEGER_t.
+C <I>int</I> types instead of infinite width INTEGER_t structures.
+See <A HREF=#Table1>Table 1</A>.
</DD>
-<DT><A NAME="foot142">... binary</A><A
+<DT><A NAME="foot151">... binary</A><A
HREF="asn1c-usage.html#tex2html3"><SUP>2.3</SUP></A></DT>
<DD>BER, CER and DER encodings are binary. However, the XER encoding is
text (XML) based.
</DD>
-<DT><A NAME="foot316">... specification</A><A
- HREF="asn1c-usage.html#tex2html4"><SUP>2.4</SUP></A></DT>
+<DT><A NAME="foot380">...asn1c</A><A
+ HREF="asn1c-usage.html#tex2html4"><SUP>3.1</SUP></A></DT>
+<DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter.
+
+</DD>
+<DT><A NAME="foot381">... specification</A><A
+ HREF="asn1c-usage.html#tex2html5"><SUP>3.2</SUP></A></DT>
<DD>This is probably <B>not</B> what you want to try out right now -
-read through the rest of this chapter to find out about -P option.
+read through the rest of this chapter to find out about <B>-P</B>
+and <B>-R</B> options.
</DD>
-<DT><A NAME="foot161">... necessary</A><A
- HREF="asn1c-usage.html#tex2html5"><SUP>2.5</SUP></A></DT>
-<DD>Soon the compiler will be modified to emit the smallest subset of
-necessary files.
-
-</DD>
-<DT><A NAME="foot319">...that simple</A><A
- HREF="asn1c-usage.html#tex2html6"><SUP>2.6</SUP></A></DT>
+<DT><A NAME="foot387">...that simple</A><A
+ HREF="asn1c-usage.html#tex2html7"><SUP>4.1</SUP></A></DT>
<DD>Provided that you've also created a .c file with the <I>int main()</I>
routine.
</DD>
-<DT><A NAME="foot183">...restartable</A><A
- HREF="asn1c-usage.html#tex2html7"><SUP>2.7</SUP></A></DT>
+<DT><A NAME="foot241">...restartable</A><A
+ HREF="asn1c-usage.html#tex2html8"><SUP>4.2</SUP></A></DT>
<DD>Restartable means that if the decoder encounters the end of the buffer,
it will fail, but may later be invoked again with the rest of the
buffer to continue decoding.
</DD>
-<DT><A NAME="foot253">... encoding</A><A
- HREF="asn1c-usage.html#tex2html8"><SUP>2.8</SUP></A></DT>
+<DT><A NAME="foot313">... encoding</A><A
+ HREF="asn1c-usage.html#tex2html9"><SUP>4.3</SUP></A></DT>
<DD>It is actually faster too: the encoder might skip over some computations
which aren't important for the size determination.
@@ -1166,7 +1262,7 @@
</DL><BR><HR>
<ADDRESS>
Lev Walkin
-2004-08-06
+2004-08-23
</ADDRESS>
</BODY>
</HTML>
diff --git a/doc/asn1c-usage.lyx b/doc/asn1c-usage.lyx
index 03b1fc9..6fc0078 100644
--- a/doc/asn1c-usage.lyx
+++ b/doc/asn1c-usage.lyx
@@ -1,9 +1,20 @@
#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
+\begin_preamble
+%\fancyhf{}
+%\renewcommand{\chaptermark}[1]{\markboth{\thechapter.\ #1\ sdf}{}}
+%\renewcommand{\sectionmark}[1]{\markright{\MakeUppercase{\thesection.\ #1}}}
+%\fancyhead[LE,RO]{\thepage}
+%\fancyhead[LO]{\rightmark}
+%\fancyhead[RE]]{\leftmark}
+\usepackage{extramarks}
+\lhead{\firstxmark}
+\rfoot{\lastxmark}
+\end_preamble
\language english
\inputencoding latin1
-\fontscheme ae
+\fontscheme times
\graphics default
\paperfontsize default
\spacing single
@@ -21,8 +32,8 @@
\quotes_language swedish
\quotes_times 2
\papercolumns 1
-\papersides 1
-\paperpagestyle default
+\papersides 2
+\paperpagestyle fancy
\layout Title
@@ -38,11 +49,37 @@
\layout Standard
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash
+extramarks{Document version 0.9}{}
+\end_inset
+
+
+\layout Standard
+
+
\begin_inset LatexCommand \tableofcontents{}
\end_inset
+\layout Standard
+
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+pagestyle{headings}
+\end_inset
+
+
\layout Part
ASN.1 Basics
@@ -159,7 +196,7 @@
asn1c(5) docs(2) usage(1) 1 }
\layout LyX-Code
- AUTOMATIC TAGS DEFINITIONS ::=
+ DEFINITIONS AUTOMATIC TAGS ::=
\layout LyX-Code
BEGIN
@@ -177,7 +214,7 @@
height INTEGER, -- Height of the rectangle
\layout LyX-Code
- width INTEGER, -- Width of the rectangle
+ width INTEGER -- Width of the rectangle
\layout LyX-Code
}
@@ -190,11 +227,19 @@
\layout Standard
The module header consists of module name (UsageExampleModule1), the module
- object identifier ({...}), some flags (AUTOMATIC TAGS) and
+ object identifier ({...}), a keyword
\begin_inset Quotes sld
\end_inset
-DEFINITIONS ::= BEGIN
+DEFINITIONS
+\begin_inset Quotes srd
+\end_inset
+
+, a set of module flags (AUTOMATIC TAGS) and
+\begin_inset Quotes sld
+\end_inset
+
+::= BEGIN
\begin_inset Quotes srd
\end_inset
@@ -232,12 +277,18 @@
SimpleInteger ::= INTEGER
\layout LyX-Code
+
+\layout LyX-Code
+
-- An integer with a very limited range
\layout LyX-Code
SmallInt ::= INTEGER (0..127)
\layout LyX-Code
+
+\layout LyX-Code
+
-- Integer, negative
\layout LyX-Code
@@ -254,10 +305,13 @@
FruitId ::= ENUMERATED { apple(1), orange(2) }
\layout LyX-Code
+
+\layout LyX-Code
+
-- The numbers in braces are optional,
\layout LyX-Code
--- the enumeration may be performed
+-- the enumeration can be performed
\layout LyX-Code
-- automatically by the compiler
@@ -315,12 +369,18 @@
ExampleOID ::= OBJECT IDENTIFIER
\layout LyX-Code
+
+\layout LyX-Code
+
usageExampleModule1-oid ExampleOID
\layout LyX-Code
::= { 1 3 6 1 4 1 9363 1 5 2 1 1 }
\layout LyX-Code
+
+\layout LyX-Code
+
-- An identifier of the Internet.
\layout LyX-Code
@@ -348,6 +408,9 @@
this-document RELATIVE-OID ::= { docs(2) usage(1) }
\layout LyX-Code
+
+\layout LyX-Code
+
this-example RELATIVE-OID ::= {
\layout LyX-Code
@@ -361,7 +424,7 @@
\layout Standard
This is essentially the ASCII, with 128 character codes available (7 lower
- bits of 8-bit byte).
+ bits of an 8-bit byte).
\layout Subsection
The UTF8String type
@@ -584,13 +647,17 @@
\begin_inset Quotes sld
\end_inset
+
+\series bold
~
+\series default
+
\begin_inset Quotes srd
\end_inset
(tilde).
- Alternatively, the alphabet may be represented as the PrintableString alphabet
- described earlier, plus the following characters:
+ Alternatively, the alphabet may be described as the PrintableString alphabet
+ presented earlier, plus the following characters:
\begin_inset Quotes sld
\end_inset
@@ -828,7 +895,11 @@
\begin_inset Quotes sld
\end_inset
+
+\series bold
~
+\series default
+
\begin_inset Quotes srd
\end_inset
@@ -954,12 +1025,18 @@
ManyIntegers ::= SEQUENCE OF INTEGER
\layout LyX-Code
+
+\layout LyX-Code
+
-- Example 2
\layout LyX-Code
ManyRectangles ::= SEQUENCE OF Rectangle
\layout LyX-Code
+
+\layout LyX-Code
+
-- More complex example:
\layout LyX-Code
@@ -990,6 +1067,9 @@
SetOfApples :: SET OF Apple
\layout LyX-Code
+
+\layout LyX-Code
+
-- Set of integers encoding the kind of a fruit
\layout LyX-Code
@@ -1018,7 +1098,7 @@
\begin_inset Quotes srd
\end_inset
- too, as long as an object-oriented approach is not a definitive factor.
+ too, as long as an class-based approach is not a definitive factor.
\end_inset
).
@@ -1043,7 +1123,13 @@
\emph on
int
\emph default
- types instead of generic INTEGER_t.
+ types instead of infinite width INTEGER_t structures.
+ See Table
+\begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
+
+\end_inset
+
+.
\end_inset
:
@@ -1063,9 +1149,9 @@
This would not be of much value for such a simple specification, so the
compiler goes further and actually produces the code which fills in this
- structure by parsing the binary
+ structure by parsing the opaque binary
\begin_inset Foot
-collapsed false
+collapsed true
\layout Standard
@@ -1076,13 +1162,37 @@
data provided in some buffer.
It also produces the code that takes this structure as an argument and
performs structure serialization by emitting a series of bytes.
-\layout Section
+\layout Chapter
Quick start
\layout Standard
-After building and installing the compiler, the asn1c command may be used
- to compile the ASN.1 specification
+After building and installing the compiler, the
+\emph on
+asn1c
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+The 1 symbol in asn
+\series bold
+1
+\series default
+c is a digit, not an
+\begin_inset Quotes sld
+\end_inset
+
+ell
+\begin_inset Quotes srd
+\end_inset
+
+ letter.
+\end_inset
+
+
+\emph default
+ command may be used to compile the ASN.1 specification
\begin_inset Foot
collapsed false
@@ -1093,7 +1203,15 @@
not
\series default
what you want to try out right now -- read through the rest of this chapter
- to find out about -P option.
+ to find out about
+\series bold
+-P
+\series default
+ and
+\series bold
+-R
+\series default
+ options.
\end_inset
:
@@ -1104,8 +1222,8 @@
<spec.asn1>
\layout Standard
-If several specifications contain interdependencies, all of them must be
- specified:
+If several specifications contain interdependencies, all of the files must
+ be specified altogether:
\layout LyX-Code
asn1c
@@ -1113,27 +1231,536 @@
<spec1.asn1> <spec2.asn1> ...
\layout Standard
-The compiler -E and -EF options are used for testing the parser and the
- semantic fixer, respectively.
- These options will instruct the compiler to dump out the parsed (and fixed)
- ASN.1 specification as it was "understood" by the compiler.
- It might might be useful to check whether a particular syntactic construction
+The compiler
+\series bold
+-E
+\series default
+ and
+\series bold
+-EF
+\series default
+ options are used for testing the parser and the semantic fixer, respectively.
+ These options will instruct the compiler to dump out the parsed (and fixed,
+ if
+\series bold
+-F
+\series default
+ is involved) ASN.1 specification as it was "understood" by the compiler.
+ It might be useful to check whether a particular syntactic construction
is properly supported by the compiler.
\layout LyX-Code
-asn1c -EF
+asn1c
+\series bold
+-EF
+\series default
+
\emph on
<spec-to-test.asn1>
\layout Standard
-The -P option is used to dump the compiled output on the screen instead
- of creating a bunch of .c and .h files on disk in the current directory.
- You would probably want to start with -P option instead of creating a mess
- in your current directory.
+The
+\series bold
+-P
+\series default
+ option is used to dump the compiled output on the screen instead of creating
+ a bunch of .c and .h files on disk in the current directory.
+ You would probably want to start with
+\series bold
+-P
+\series default
+ option instead of creating a mess in your current directory.
+ Another option,
+\series bold
+-R
+\series default
+, asks compiler to only generate the files which need to be generated, and
+ supress linking in the numerous support files.
+\layout Standard
+
+Print the compiled output instead of creating multiple source files:
+\layout LyX-Code
+
+asn1c
+\series bold
+-P
+\series default
+
+\emph on
+<spec-to-compile-and-print.asn1>
+\layout LyX-Code
+
+\layout Chapter
+
+Using the ASN.1 Compiler
\layout Section
-Slow start
-\layout Subsection
+Command-line options
+\layout Standard
+
+The Table
+\begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
+
+\end_inset
+
+ summarizes various options affecting the compiler's behavior.
+\layout Standard
+
+
+\begin_inset Float table
+wide false
+collapsed true
+
+\layout Standard
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="20" columns="2">
+<features>
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="block" valignment="top" leftline="true" rightline="true" width="3in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Overall Options
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-E
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Stop after the parsing stage and print the reconstructed ASN.1 specification
+ code to the standard output.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-F
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Used together with -E, instructs the compiler to stop after the ASN.1 syntax
+ tree fixing stage and dump the reconstructed ASN.1 specification to the
+ standard output.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-P
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Dump the compiled output to the standard output instead of cre- ating the
+ target language files on disk.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-R
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Restrict the compiler to generate only the ASN.1 tables, omit- ting the usual
+ support code.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-S
+\emph on
+<directory>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Use the specified directory with ASN.1 skeleton files.
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-t
+\emph on
+<data-string>
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Interpret the data-string as a sequence of hexadecimal values representing
+ the start of BER TLV encoding.
+ Print the human readable explanation.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Warning Options
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-Werror
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Treat warnings as errors; abort if any warning is produced.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-Wdebug-lexer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Enable lexer debugging during the ASN.1 parsing stage.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-Wdebug-fixer
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+ Enable ASN.1 syntax tree fixer debugging during the fixing stage.
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-Wdebug-compiler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Enable debugging during the actual compile time.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Language Options
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-fbless-SIZE
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Allow SIZE() constraint for INTEGER, ENUMERATED, and other types for which
+ this constraint is normally prohibited by the standard.
+ This is a violation of an ASN.1 standard and compiler may fail to produce
+ the meaningful code.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-fnative-integers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Use native machine's integer types whenever possible, instead of the complex
+ ASN.1 INTEGER and ENUMERATED types.
+
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-funnamed-unions
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Enable unnamed unions in the definitions of target language's structures.
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-ftypes88
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Use only ASN.1:1988 embedded types.
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Output Options
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\series bold
+Description
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-print-constraints
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+When -EF are also specified, this option forces the compiler to explain
+ its internal understanding of subtype constraints.
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-print-lines
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+
+\size small
+Generate "-- #line" comments in -E output.
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Caption
+
+
+\begin_inset LatexCommand \label{cap:asn1c-cmdopts}
+
+\end_inset
+
+The list of asn1c command line options
+\end_inset
+
+
+\layout Section
Recognizing compiler output
\layout Standard
@@ -1157,17 +1784,8 @@
A set of helper .c and .h files which contain generic encoders, decoders and
other useful routines.
- There will be many of them, some of them even not necessary
-\begin_inset Foot
-collapsed false
-
-\layout Standard
-
-Soon the compiler will be modified to emit the smallest subset of necessary
- files.
-\end_inset
-
-, but the overall amount of code after compiling will be rather small anyway.
+ There will be quite a few of them, some of them even are not always necessary,
+ but the overall amount of code after compiling will be rather small anyway.
\layout Standard
It is your responsibility to create .c file with the
@@ -1233,14 +1851,14 @@
\end_inset
-\layout Subsection
+\layout Section
Invoking the ASN.1 helper code from the application
\layout Standard
-First of all, you would want to include one or more header files into your
- application.
- For the Rectangle module, including the Rectangle.h file is enough:
+First of all, you should to include one or more header files into your applicati
+on.
+ For our Rectangle module, including the Rectangle.h file is enough:
\layout LyX-Code
#include <Rectangle.h>
@@ -1252,7 +1870,10 @@
For example, here is the code which frees the Rectangle_t structure:
\layout LyX-Code
-Rectangle_t *rect = ;
+Rectangle_t *rect = ...;
+\layout LyX-Code
+
+
\layout LyX-Code
asn1_DEF_Rectangle->free_struct(&asn1_DEF_Rectangle,
@@ -1366,7 +1987,7 @@
Rectangle_t *
\layout LyX-Code
-simple_deserializer(void *buffer, size_t buf_size) {
+simple_deserializer(const void *buffer, size_t buf_size) {
\layout LyX-Code
Rectangle_t *rect = 0; /* Note this 0! */
@@ -1409,6 +2030,9 @@
} else {
\layout LyX-Code
+ /* Free partially decoded rect */
+\layout LyX-Code
+
asn1_DEF_Rectangle->free_struct(
\layout LyX-Code
@@ -1461,7 +2085,7 @@
\end_inset
-\layout Subsubsection
+\layout Subsection
\begin_inset LatexCommand \label{sub:Decoding-BER}
@@ -1575,7 +2199,7 @@
Please look into ber_decoder.h for the precise definition of ber_decode()
and related types.
-\layout Subsubsection
+\layout Subsection
\begin_inset LatexCommand \label{sub:Encoding-DER}
@@ -1610,7 +2234,10 @@
*/
\layout LyX-Code
-int _write_stream(void *buffer, size_t size, void *app_key) {
+static int
+\layout LyX-Code
+
+write_stream(const void *buffer, size_t size, void *app_key) {
\layout LyX-Code
FILE *ostream = app_key;
@@ -1667,7 +2294,7 @@
rval = der_encode(&asn1_DEF_Rect, rect,
\layout LyX-Code
- _write_stream, ostream);
+ write_stream, ostream);
\layout LyX-Code
if(rval
@@ -1760,7 +2387,7 @@
Please look into der_encoder.h for the precise definition of der_encode()
and related types.
-\layout Subsubsection
+\layout Subsection
\begin_inset LatexCommand \label{sub:Validating-the-target}
@@ -1791,7 +2418,7 @@
Please look into constraints.h for the precise definition of asn_check_constraint
s() and related types.
-\layout Subsubsection
+\layout Subsection
\begin_inset LatexCommand \label{sub:Printing-the-target}
@@ -1811,7 +2438,7 @@
Please look into constr_TYPE.h for the precise definition of asn_fprint()
and related types.
-\layout Subsubsection
+\layout Subsection
\begin_inset LatexCommand \label{sub:Freeing-the-target}
@@ -1938,6 +2565,16 @@
function with the target structure pointer set to 0 (NULL), the function
will do nothing.
\layout Bibliography
+\bibitem [ASN1C]{ASN1C}
+
+Free ASN.1 Compiler.
+
+\begin_inset LatexCommand \htmlurl{http://lionet.info/asn1/}
+
+\end_inset
+
+
+\layout Bibliography
\bibitem [Dub00]{Dub00}
Olivier Dubuisson --
diff --git a/doc/asn1c-usage.pdf b/doc/asn1c-usage.pdf
index 5601cd2..a33e9aa 100644
--- a/doc/asn1c-usage.pdf
+++ b/doc/asn1c-usage.pdf
Binary files differ