aboutsummaryrefslogtreecommitdiffstats
path: root/lib/asn1/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/asn1/doc')
-rw-r--r--lib/asn1/doc/src/asn1_ug.xml519
-rw-r--r--lib/asn1/doc/src/asn1ct.xml128
-rw-r--r--lib/asn1/doc/src/asn1rt.xml41
-rw-r--r--lib/asn1/doc/src/notes.xml69
4 files changed, 195 insertions, 562 deletions
diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
index 1b399fb641..362ca9330f 100644
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ b/lib/asn1/doc/src/asn1_ug.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>1997</year><year>2011</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -186,13 +186,21 @@ END </pre>
The following shows how the compiler
can be called from the Erlang shell:</p>
<pre>
-1><input>asn1ct:compile("People",[ber_bin]).</input>
+1><input>asn1ct:compile("People", [ber]).</input>
+ok
+2> </pre>
+
+ <p>The <c>verbose</c> option can be given to have information
+ about the generated files printed:</p>
+ <pre>
+2><input>asn1ct:compile("People", [ber,verbose]).</input>
Erlang ASN.1 compiling "People.asn"
--{generated,"People.asn1db"}--
--{generated,"People.hrl"}--
--{generated,"People.erl"}--
ok
-2> </pre>
+3> </pre>
+
<p>The ASN.1 module People is now accepted and the abstract syntax tree
is saved in the <c>People.asn1db</c> file, the
generated Erlang code is compiled using the Erlang compiler and
@@ -229,7 +237,7 @@ receive
constructed and encoded using
<c>'People':encode('Person',Answer)</c> which takes an
instance of a defined ASN.1 type and transforms it to a
- (possibly) nested list of bytes according to the BER or PER
+ binary according to the BER or PER
encoding-rules.
<br></br>
The encoder and the decoder can also be run from
@@ -239,24 +247,12 @@ The encoder and the decoder can also be run from
<pre>
2> <input>Rockstar = {'Person',"Some Name",roving,50}.</input>
{'Person',"Some Name",roving,50}
-3> <input>{ok,Bytes} = asn1rt:encode('People','Person',Rockstar).</input>
-{ok,[&lt;&lt;243&gt;&gt;,
- [17],
- [19,9,"Some Name"],
- [2,1,[2]],
- [2,1,"2"]]}
-4> <input>Bin = list_to_binary(Bytes).</input>
-&lt;&lt;243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,2,1,50&gt;&gt;
-5> <input>{ok,Person} = asn1rt:decode('People','Person',Bin).</input>
+3> <input>{ok,Bin} = asn1rt:encode('People','Person',Rockstar).</input>
+{ok,&lt;&lt;243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
+ 2,1,50&gt;&gt;}
+4> <input>{ok,Person} = asn1rt:decode('People','Person',Bin).</input>
{ok,{'Person',"Some Name",roving,50}}
-6> </pre>
- <p>Notice that the result from <c>encode</c> is a nested list which
- must be turned into a binary before the call to <c>decode</c>. A
- binary is necessary as input to decode since the module was compiled
- with the <c>ber_bin</c> option
- The reason for returning a nested list is that it is faster to produce
- and the <c>list_to_binary</c> operation is
- performed automatically when the list is sent via the Erlang port mechanism.</p>
+5> </pre>
</section>
<section>
@@ -305,17 +301,15 @@ The encoder and the decoder can also be run from
ASN.1 compiler:</p>
<pre>
erlc Person.asn
-erlc -bper_bin Person.asn
-erlc -bber_bin +optimize ../Example.asn
+erlc -bper Person.asn
+erlc -bber ../Example.asn
erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn </pre>
<p>The useful options for the ASN.1 compiler are:</p>
<taglist>
- <tag><c>-b[ber | per | ber_bin | per_bin | uper_bin]</c></tag>
+ <tag><c>-b[ber | per | uper]</c></tag>
<item>
<p>Choice of encoding rules, if omitted <c>ber</c> is the
- default. The <c>ber_bin</c> and <c>per_bin</c> options
- allows for optimizations and are therefore recommended
- instead of the <c>ber</c> and <c>per</c> options.</p>
+ default.</p>
</item>
<tag><c>-o OutDirectory</c></tag>
<item>
@@ -330,51 +324,14 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
are several places to search in. The compiler will always
search the current directory first.</p>
</item>
- <tag><c>+compact_bit_string</c></tag>
- <item>
- <p>Gives the user the option to use a compact format of the BIT
- STRING type to save memory space, typing space and
- increase encode/decode performance, for details see
- <seealso marker="#BIT STRING">BIT STRING </seealso>type section.</p>
- </item>
<tag><c>+der</c></tag>
<item>
- <p>DER encoding rule. Only when using <c>-ber</c> or
- <c>-ber_bin</c> option.</p>
- </item>
- <tag><c>+optimize</c></tag>
- <item>
- <p>This flag has effect only when used together with one of
- <c>per_bin</c> or <c>ber_bin</c> flags. It gives time optimized
- code in the generated modules and it uses another runtime module.
- In the <c>per_bin</c> case a nif is used. The
- result from an encode is a binary.</p>
- <p><em>When this flag is used you cannot use the old format</em><c>{TypeName,Value}</c> when you encode values. Since it is
- an unnecessary construct it has been removed in favor of
- performance. It
- is neither admitted to construct SEQUENCE or SET component values
- with the format <c>{ComponentName,Value}</c> since it also is
- unnecessary. The only case were it is necessary is in a CHOICE,
- were you have to pass values to the right component by specifying
- <c>{ComponentName,Value}</c>. See also about
- <seealso marker="#TypeNameValue">{Typename,Value}</seealso> below
- and in the sections for each type.</p>
- </item>
- <tag><c>+driver</c></tag>
- <item>
- <p>As of R15B this means the same as the <c>nif</c> option. Kept for
- backwards compatability reasons.</p>
- </item>
- <tag><c>+nif</c></tag>
- <item>
- <p>Together with the flags <c>ber_bin</c>
- and <c>optimize</c> you choose to use a nif for considerable
- faster encode and decode. </p>
+ <p>DER encoding rule. Only when using <c>-ber</c> option.</p>
</item>
<tag><c>+asn1config</c></tag>
<item>
<p>This functionality works together with the flags
- <c>ber_bin</c> and <c>optimize</c>. You enables the
+ <c>ber</c>. It enables the
specialized decodes, see the <seealso marker="asn1_spec">Specialized Decode</seealso> chapter.
</p>
</item>
@@ -388,22 +345,6 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
list or a binary. Earlier versions of the compiler ignored
those following bytes.</p>
</item>
- <tag><c>{inline,OutputName}</c></tag>
- <item>
- <p>Compiling with this option gives one output module
- containing all asn1 run-time functionality. The asn1 specs
- are provided in a target module <c>Module.set.asn</c> as
- described in the <seealso marker="asn1ct#asn1set">reference manual</seealso>. The name of the resulting module
- containing generated encode/decode functions and inlined
- run-time functions will be <c>OutputName.erl</c>. The
- merging/inlining of code is done by the <c>igor</c> module
- of <c>syntax_tools</c>. By default the functions generated
- from the first asn1 spec in the <c>.set.asn</c> are
- exported, unless a <c>{export,[atom()]}</c> or
- <c>{export_all,true}</c> option are provided. The list of
- atoms are names of choosen asn1 specs from the
- <c>.set.asn</c> file. See further examples of usage <seealso marker="#inlineExamples">below</seealso></p>
- </item>
<tag><c>+'Any Erlc Option'</c></tag>
<item>
<p>You may add any option to the Erlang compiler when
@@ -413,7 +354,6 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
</item>
</taglist>
<p>For a complete description of <c>erlc</c> see Erts Reference Manual.</p>
- <p>For preferred option use see <seealso marker="#preferred option use">Preferred Option Use</seealso> section.</p>
<p>The compiler and other compile-time functions can also be invoked from
the Erlang shell. Below follows a brief
description of the primary functions, for a
@@ -429,9 +369,9 @@ asn1ct:compile("H323-MESSAGES.asn1"). </pre>
<p>which equals:</p>
<pre>
asn1ct:compile("H323-MESSAGES.asn1",[ber]). </pre>
- <p>If one wants PER encoding with optimizations:</p>
+ <p>If one wants PER encoding:</p>
<pre>
-asn1ct:compile("H323-MESSAGES.asn1",[per_bin,optimize]). </pre>
+asn1ct:compile("H323-MESSAGES.asn1",[per]). </pre>
<p>The generic encode and decode functions can be invoked like this:</p>
<pre>
asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
@@ -443,269 +383,6 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
</section>
<section>
- <marker id="preferred option use"></marker>
- <title>Preferred Option Use</title>
- <p>
- It may not be obvious which compile options best fit a
- situation. This section describes the format of the result of
- encode and decode. It also gives some performance statistics
- when using certain options. Finally there is a recommendation
- which option combinations should be used.
- </p>
- <p>
- The default option is <c>ber</c>. It is the same backend as
- <c>ber_bin</c> except that the result of encode is transformed
- to a flat list. Below is a table that gives the different
- formats of input and output of encode and decode using the
- <em>allowed combinations</em> of coding and optimization
- options: (EAVF stands for how ASN1 values are represented in
- Erlang which is described in the <seealso
- marker="#ASN1Types">ASN1 Types chapter</seealso>)
- </p>
- <table>
- <row>
- <cell align="left" valign="middle"><em>Encoding Rule</em></cell>
- <cell align="left" valign="middle"><em>Compile options, allowed combinations</em></cell>
- <cell align="left" valign="middle"><em>encode input</em></cell>
- <cell align="left" valign="middle"><em>encode output</em></cell>
- <cell align="left" valign="middle"><em>decode input</em></cell>
- <cell align="left" valign="middle"><em>decode output</em></cell>
- </row>
- <row>
- <cell align="left" valign="middle">BER</cell>
- <cell align="left" valign="middle">[ber] (default)</cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">flat list</cell>
- <cell align="left" valign="middle">flat list / binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">BER</cell>
- <cell align="left" valign="middle">[ber_bin]</cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">BER</cell>
- <cell align="left" valign="middle"><em>[ber_bin, optimize]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">BER</cell>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, nif]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist</cell>
- <cell align="left" valign="middle">iolist / binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">PER aligned variant</cell>
- <cell align="left" valign="middle">[per]</cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">flat list</cell>
- <cell align="left" valign="middle">flat list</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">PER aligned variant</cell>
- <cell align="left" valign="middle"><em>[per_bin]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist / binary</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">PER aligned variant</cell>
- <cell align="left" valign="middle"><em>[per_bin, optimize]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">PER unaligned variant</cell>
- <cell align="left" valign="middle"><em>[uper_bin]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
-
- <row>
- <cell align="left" valign="middle">DER</cell>
- <cell align="left" valign="middle">[(ber), der]</cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">flat list</cell>
- <cell align="left" valign="middle">flat list / binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">DER</cell>
- <cell align="left" valign="middle">[ber_bin, der]</cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">DER</cell>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, der]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
- <row>
- <cell align="left" valign="middle">DER</cell>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, nif, der]</em></cell>
- <cell align="left" valign="middle">EAVF</cell>
- <cell align="left" valign="middle">iolist</cell>
- <cell align="left" valign="middle">binary</cell>
- <cell align="left" valign="middle">EAVF</cell>
- </row>
-
-
- <tcaption>The output / input formats for different combinations of compile options.</tcaption>
- </table>
- <p>
- Encode / decode speed comparison in one user case for the above
- alternatives (except <c>DER</c>) is showed in the table below. The
- <c>DER</c> alternatives are slower than their corresponding
- <c>BER</c> alternative.
- </p>
-
- <table>
- <row>
- <cell align="left" valign="middle"><em>compile options</em></cell>
- <cell align="left" valign="middle"><em>encode time</em></cell>
- <cell align="left" valign="middle"><em>decode time</em></cell>
- </row>
- <row>
- <cell align="left" valign="middle">[ber]</cell>
- <cell align="left" valign="middle">120</cell>
- <cell align="left" valign="middle">162</cell>
- </row>
- <row>
- <cell align="left" valign="middle">[ber_bin]</cell>
- <cell align="left" valign="middle">124</cell>
- <cell align="left" valign="middle">154</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[ber_bin, optimize]</em></cell>
- <cell align="left" valign="middle">50</cell>
- <cell align="left" valign="middle">78</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, driver]</em></cell>
- <cell align="left" valign="middle">50</cell>
- <cell align="left" valign="middle">62</cell>
- </row>
- <row>
- <cell align="left" valign="middle">[per]</cell>
- <cell align="left" valign="middle">141</cell>
- <cell align="left" valign="middle">133</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[per_bin]</em></cell>
- <cell align="left" valign="middle">125</cell>
- <cell align="left" valign="middle">123</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[per_bin, optimize]</em></cell>
- <cell align="left" valign="middle">77</cell>
- <cell align="left" valign="middle">72</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[uper_bin]</em></cell>
- <cell align="left" valign="middle">97</cell>
- <cell align="left" valign="middle">104</cell>
- </row>
- <tcaption>
- One example of difference in speed for the compile option alternatives.
- </tcaption>
- </table>
-
- <p>
- The compile options <c>ber</c>, <c>per</c> and
- <c>driver</c> are kept for backwards compatibility and should not be
- used in new code. The nif implementation which replaces the linked-in
- driver has been shown to be about 5-15% faster.
- </p>
- <p>
- You are strongly recommended to use the appropriate alternative
- of the bold typed options. The <c>optimize</c> and
- <c>nif</c> options does not affect the encode or decode
- result, just the time spent in run-time. When <c>ber_bin</c> and
- <c>nif</c> or <c>per_bin</c> and <c>optimize</c> is
- combined the C-code nif is used in chosen parts of encode /
- decode procedure.
- </p>
- <table>
- <row>
- <cell align="left" valign="middle"><em>Compile options, allowed combinations</em></cell>
- <cell align="left" valign="middle"><em>use of nif</em></cell>
- </row>
- <row>
- <cell align="left" valign="middle">[ber]</cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle">[ber_bin]</cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[ber_bin, optimize]</em></cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, nif]</em></cell>
- <cell align="left" valign="middle">yes</cell>
- </row>
- <row>
- <cell align="left" valign="middle">[per]</cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[per_bin]</em></cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[per_bin, optimize]</em></cell>
- <cell align="left" valign="middle">yes</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[uper_bin]</em></cell>
- <cell align="left" valign="middle">no</cell>
- </row>
-
- <row>
- <cell align="left" valign="middle">[(ber), der]</cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle">[ber_bin, der]</cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, der]</em></cell>
- <cell align="left" valign="middle">no</cell>
- </row>
- <row>
- <cell align="left" valign="middle"><em>[ber_bin, optimize, nif, der]</em></cell>
- <cell align="left" valign="middle">yes</cell>
- </row>
-
-
- <tcaption>When the ASN1 nif is used.</tcaption>
- </table>
-
- </section>
- <section>
<title>Run-time Functions</title>
<p>A brief description of the major functions is given here. For a
complete description of each function see
@@ -719,9 +396,9 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre>
<p>The asn1 nif is enabled in two occasions: encoding of
- asn1 values when the asn1 spec is compiled with <c>per_bin</c> and
- <c>optimize</c> or decode of encoded asn1 values when the asn1 spec is
- compiled with <c>ber_bin</c>, <c>optimize</c> and <c>nif</c>. In
+ asn1 values when the asn1 spec is compiled with <c>per</c> and
+ or decode of encoded asn1 values when the asn1 spec is
+ compiled with <c>ber</c>. In
those cases the nif will be loaded automatically at the first call
to <c>encode</c>/<c>decode</c>. If one doesn't want the performance
overhead of the nif being loaded at the first call it is possible
@@ -754,21 +431,8 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
any reason. Maybe you need to compile the same specs for
different encoding/decoding standards.</item>
<item>You want only one resulting module.</item>
- <item>If it is crucial to have a minimal system. Using
- <c>{inline,OutputModule}</c> includes all necessary run-time
- functions of the asn1 application, but skips those modules not
- used.</item>
- <item>Upgrading issues: Even if you upgrade your Erlang system
- you may want to continue running the old asn1 run-time
- functionality.</item>
- <item>Performance issues: If you have an asn1 system with a lot
- of cross references you may gain in performance. Measurements
- must be done for each case.</item>
</list>
- <p>You may choose either the plain multi file compilation that just
- merges the chosen asn1 specs or the <c>{inline,OutputModule}</c>
- that also includes the used asn1 run-time functionality.</p>
- <p>For both cases you need to specify which asn1 specs you will
+ <p>You need to specify which asn1 specs you will
compile in a module that must have the extension
<c>.set.asn</c>. You chose name of the module and provide the
names of the asn1 specs. For instance, if you have the specs
@@ -782,17 +446,7 @@ File3.asn </pre>
<code type="none">
~> erlc MyModule.set.asn </code>
<p>the result will be one merged module <c>MyModule.erl</c> with
- the generated code from the three asn1 specs. But if you compile
- with:</p>
- <code type="none">
-~> erlc +"{inline,'OutputModule'}" MyModule.set.asn </code>
- <p>the result will be a module <c>OutputModule.erl</c> that
- contains all encode/decode functions for the three asn1 specs and
- all used functions from the asn1 run-time modules, in this case
- <c>asn1rt_ber_bin</c>. In the former case all encode/decode
- functions are exported but in the latter only the encode/decode
- functions of the first spec in the <c>.set.asn</c>, i.e. those
- from <c>File1.asn</c>.
+ the generated code from the three asn1 specs.
</p>
</section>
@@ -868,26 +522,6 @@ Operational ::= BOOLEAN --ASN.1 definition </pre>
<pre>
Val = true,
{ok,Bytes}=asn1rt:encode(MyModule,'Operational',Val), </pre>
- <p>For historical reasons it is also possible to assign ASN.1 values
- in Erlang using a tuple notation
- with type and value as this</p>
- <pre>
-Val = {'Operational',true} </pre>
- <warning>
- <marker id="warning"></marker>
- <p>The tuple notation, <c>{Typename, Value}</c> is only kept
- because of backward compatibility and may be withdrawn in a
- future release. If the notation is used the <c>Typename</c>
- element must be spelled correctly, otherwise a run-time error
- will occur.
- </p>
- <p>If the ASN.1 module is compiled with the flags
- <c>per_bin</c> or <c>ber_bin</c> and <c>optimize</c> it is not
- allowed to use the tuple notation. That possibility has been
- removed due to performance reasons. Neither is it allowed to
- use the <c>{ComponentName,Value}</c> notation in case of a
- SEQUENCE or SET type.</p>
- </warning>
<p>Below follows a description of how
values of each type can be represented in Erlang.
</p>
@@ -1008,7 +642,7 @@ Day1 = saturday,
<section>
<marker id="BIT STRING"></marker>
- <title>BIT STRING </title>
+ <title>BIT STRING</title>
<p>The BIT STRING type can be used to model information which
is made up of arbitrary length series of bits. It is intended
to be used for a selection of flags, not for binary files. <br></br>
@@ -1019,56 +653,66 @@ Day1 = saturday,
Bits1 ::= BIT STRING
Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
</pre>
- <p>There are four different notations available for representation of
+ <p>There are five different notations available for representation of
BIT STRING values in Erlang and as input to the encode functions.</p>
<list type="ordered">
- <item>A list of binary digits (0 or 1).</item>
- <item>A hexadecimal number (or an integer). This format should be
- avoided, since it is easy to misinterpret a <c>BIT STRING</c>
- value in this format. This format may be withdrawn in a future
- release.</item>
+ <item>A bitstring. By default, a BIT STRING with no
+ symbolic names will be decoded to an Erlang bitstring.</item>
<item>A list of atoms corresponding to atoms in the <c>NamedBitList</c>
- in the BIT STRING definition.</item>
+ in the BIT STRING definition. A BIT STRING with symbolic
+ names will always be decoded to this format.</item>
+ <item>A list of binary digits (0 or 1). This format is always
+ accepted as input to the encode functions. A BIT STRING will
+ be decoded to this format if <em>legacy_bit_string</em> option
+ has been given. <em>This format may be withdrawn in a future
+ release.</em>
+ </item>
<item>As <c>{Unused,Binary}</c> where <c>Unused</c> denotes how
- many trailing zero-bits 0 to 7 that are unused in the least
- significant byte in <c>Binary</c>. This notation is only
- available when the ASN.1 files have been compiled with the
- <em>+compact_bit_string</em> flag in the option list. In
- this case it is possible to use all kinds of notation when
- encoding. But the result when decoding is always in the
- compact form. The benefit from this notation is a more
- compact notation when one has large BIT STRINGs. The
- encode/decode performance is also much better in the case of
- large BIT STRINGs. </item>
+ many trailing zero-bits 0 to 7 that are unused in the least
+ significant byte in <c>Binary</c>. This format is always
+ accepted as input to the encode functions. A BIT STRING will
+ be decoded to this format if <em>compact_bit_string</em> has
+ been given. <em>This format may be withdrawn in a future
+ release.</em>
+ </item>
+ <item>A hexadecimal number (or an integer). This format should be
+ avoided, since it is easy to misinterpret a <c>BIT STRING</c>
+ value in this format. <em>This format may be withdrawn in a future
+ release.</em>
+ </item>
</list>
<note>
- <p>Note that it is advised not to use the integer format of a
- BIT STRING, see the second point above.</p>
+ <p>It is recommended to either use the bitstring format (for
+ BIT STRINGs with no symbolic names) or a list of symbolic
+ names (for BIT STRINGs with symbolic names). The other formats
+ should be avoided since they may be withdrawn in a future
+ release.
+ </p>
</note>
<pre>
-Bits1Val1 = [0,1,0,1,1],
+Bits1Val1 = &lt;&lt;0:1,1:1,0:1,1:1,1:1&gt;&gt;,
Bits1Val2 = 16#1A,
-Bits1Val3 = {3,&lt;&lt;0:1,1:1,0:1,1:1,1:1,0:3&gt;&gt;}
+Bits1Val3 = {3,&lt;&lt;0:1,1:1,0:1,1:1,1:1,0:3&gt;&gt;},
+Bits1Val4 = [0,1,0,1,1]
</pre>
- <p>Note that <c>Bits1Val1</c>, <c>Bits1Val2</c> and <c>Bits1Val3</c>
- denote the same value.</p>
+ <p>Note that <c>Bits1Val1</c>, <c>Bits1Val2</c>, <c>Bits1Val3</c>,
+ and <c>Bits1Val1</c> denote the same value.</p>
<pre>
Bits2Val1 = [gnu,punk],
-Bits2Val2 = 2#1110,
+Bits2Val2 = &lt;&lt;2#1110:4&gt;&gt;,
Bits2Val3 = [bar,gnu,gnome],
-Bits2Val4 = [0,1,1,1]
</pre>
- <p>The above <c>Bits2Val2</c>, <c>Bits2Val3</c> and <c>Bits2Val4</c>
- also all denote the same value.</p>
+ <p><c>Bits2Val2</c> and <c>Bits2Val3</c> above denote the same value.</p>
<p><c>Bits2Val1</c> is assigned symbolic values. The assignment means
that the bits corresponding to <c>gnu</c> and <c>punk</c> i.e. bits
2 and 14 are set to 1 and the rest set to 0. The symbolic values
appear as a list of values. If a named value appears, which is not
specified in the type definition, a run-time error will occur.</p>
<p>The compact notation equivalent to the empty BIT STRING is
- <c><![CDATA[{0,<<>>}]]></c>, which in the other notations is <c>[]</c> or
+ <c><![CDATA[{0,<<>>}]]></c>, which in the other notations is
+ <c><![CDATA[<<>>]]></c>, <c>[]</c>, or
<c>0</c>.</p>
- <p>BIT STRINGS may also be sub-typed with for example a SIZE
+ <p>BIT STRINGS may also be sub-typed with, for example, a SIZE
specification:</p>
<pre>
Bits3 ::= BIT STRING (SIZE(0..31)) </pre>
@@ -1149,7 +793,7 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....]
The following example shows how it works:</p>
<p>In a file <c>PrimStrings.asn1</c> the type <c>BMP</c> is defined as
<br></br>
-<c>BMP ::= BMPString</c> then using BER encoding (<c>ber_bin</c>
+<c>BMP ::= BMPString</c> then using BER encoding (<c>ber</c>
option)the input/output format will be:</p>
<pre>
1> <input>{ok,Bytes1} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,45,56}]).</input>
@@ -1174,9 +818,9 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....]
<c>utf8_list_to_binary</c>, are in the <c>asn1rt</c> module. In
the example below we assume an asn1 definition <c>UTF ::= UTF8String</c> in a module <c>UTF.asn</c>:</p>
<pre>
-1> <input>asn1ct:compile('UTF',[ber_bin]).</input>
+1> <input>asn1ct:compile('UTF',[ber]).</input>
Erlang ASN.1 version "1.4.3.3" compiling "UTF.asn"
-Compiler Options: [ber_bin]
+Compiler Options: [ber]
--{generated,"UTF.asn1db"}--
--{generated,"UTF.erl"}--
ok
@@ -1287,14 +931,6 @@ Pdu ::= SEQUENCE {
<p>Values can be assigned in Erlang as shown below:</p>
<pre>
MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}. </pre>
-<note>
- <p>
- In very early versions of the asn1 compiler it was also possible to
- specify the values of the components in
- a SEQUENCE or a SET as a list of tuples <c>{ComponentName,Value}</c>.
- This is no longer supported.
- </p>
-</note>
<p>The decode functions will return a record as result when decoding
a <c>SEQUENCE</c> or a <c>SET</c>.
<marker id="DEFAULT"></marker>
@@ -1739,12 +1375,9 @@ SS ::= SET {
1> <input>Val = 'Values':tt().</input>
{'TT',77,["kalle","kula"]}
2> <input>{ok,Bytes} = 'Values':encode('TT',Val).</input>
-{ok,["0",
- [18],
- [[[128],[1],"M"],["\\241","\\r",[[[4],[5],"kalle"],[[4],[4],"kula"]]]]]}
-3> <input>FlatBytes = lists:flatten(Bytes).</input>
-[48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,107,117,108,97]
-4> <input>'Values':decode('TT',FlatBytes).</input>
+{ok,&lt;&lt;48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,
+ 107,117,108,97&gt;&gt;}
+4> <input>'Values':decode('TT',Bytes).</input>
{ok,{'TT',77,["kalle","kula"]}}
5>
</pre>
diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml
index 3be58cbc8e..f04bac9fec 100644
--- a/lib/asn1/doc/src/asn1ct.xml
+++ b/lib/asn1/doc/src/asn1ct.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1997</year><year>2012</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -41,6 +41,19 @@
encode/decode functions. There are also some generic functions which
can be used in during development of applications which handles ASN.1
data (encoded as BER or PER).</p>
+ <note>
+ <p>In R16, the options have been simplified. The back-end is chosen
+ using one of the options <c>ber</c>, <c>per</c>, or <c>uper</c>.
+ The options <c>optimize</c>, <c>nif</c>, and <c>driver</c> options
+ are no longer necessary (and the ASN.1 compiler will print a
+ warning if they are used). The options <c>ber_bin</c>, <c>per_bin</c>,
+ and <c>uper_bin</c> options will still work, but will print a warning.
+ </p>
+ <p>Another change in R16 is that the generated <c>encode/2</c>
+ function (and <c>asn1rt:encode/3</c>) always returns a binary.
+ The <c>encode/2</c> function for the BER back-end used to return
+ an iolist.</p>
+ </note>
</description>
<funcs>
<func>
@@ -50,9 +63,10 @@
<type>
<v>Asn1module = atom() | string()</v>
<v>Options = [Option| OldOption]</v>
- <v>Option = ber_bin | per_bin | uper_bin | der | compact_bit_string |
- noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} | optimize |
- nif | asn1config | undec_rest | {inline, OutputName} | inline |
+ <v>Option = ber | per | uper | der | compact_bit_string |
+ legacy_bit_string |
+ noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} |
+ asn1config | undec_rest |
{macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose | warnings_as_errors</v>
<v>OldOption = ber | per</v>
<v>Reason = term()</v>
@@ -107,12 +121,10 @@ File3.asn </pre>
<c>Options</c> is a list with options specific for the asn1
compiler and options that are applied to the Erlang compiler.
The latter are those that not is recognized as asn1 specific.
- For <em>preferred option use</em> see <seealso
- marker="asn1_ug#preferred option use">Preferred Option Use
- section in users guide</seealso>. Available options are:
+ Available options are:
</p>
<taglist>
- <tag><c>ber | ber_bin | per | per_bin | uper_bin</c></tag>
+ <tag><c>ber | per | uper</c></tag>
<item>
<p>
The encoding rule to be used. The supported encoding rules
@@ -120,23 +132,12 @@ File3.asn </pre>
PER aligned (Packed Encoding Rules) and PER unaligned.
If the encoding rule option is omitted <c>ber</c>
is the default.
- The <c>per_bin</c> option means the aligned
- variant. To use the unaligned variant the <c>uper_bin</c>
- option has to be used.
</p>
<p>
The generated Erlang module always gets the same name
as the ASN.1 module and as a consequence of this only one
encoding rule per ASN.1 module can be used at runtime.
</p>
- <p>
- The <c>ber_bin</c> and <c>per_bin</c> options are
- equivalent with the <c>OldOptions</c> <c>ber</c> and <c>per</c>
- with the difference that the generated encoding/decoding
- functions take advantage of the bit syntax, which in most
- cases increases the performance considerably. The result
- from encoding is a binary or an iolist.
- </p>
</item>
<tag><c>der</c></tag>
<item>
@@ -144,7 +145,7 @@ File3.asn </pre>
By this option the Distinguished Encoding Rules (DER) is chosen.
DER is regarded as a specialized variant of the BER encoding
rule, therefore the <c>der</c> option only makes sense together
- with the <c>ber</c> or <c>ber_bin</c> option.
+ with the <c>ber</c> option.
This option
sometimes adds sorting and value checks when encoding, which
implies a slower encoding. The decoding routines are the same
@@ -154,22 +155,26 @@ File3.asn </pre>
<tag><c>compact_bit_string</c></tag>
<item>
<p>
- Makes it possible to use a compact notation for values
- of the BIT STRING type in Erlang. The notation:
+ The BIT STRING type will be decoded to the "compact notation".
+ <em>This option is not recommended for new code.</em>
+ </p>
+ <p>For details see
+ <seealso marker="asn1_ug#BIT STRING">
+ BIT STRING type section in the Users Guide
+ </seealso>.
</p>
- <pre>
-BitString = {Unused, Binary},
-Unused = integer(),
-Binary = binary()
- </pre>
+ </item>
+ <tag><c>legacy_bit_string</c></tag>
+ <item>
<p>
- <c>Unused</c> must be a number in the range 0 to 7. It
- tells how many bits in the least significant byte in
- <c>Binary</c> that is unused.
- For details see
+ The BIT STRING type will be decoded to the legacy
+ format, i.e. a list of zeroes and ones.
+ <em>This option is not recommended for new code.</em>
+ </p>
+ <p>For details see
<seealso marker="asn1_ug#BIT STRING">
- BIT STRING type section in users guide
- </seealso>.
+ BIT STRING type section in the Users Guide
+ </seealso>.
</p>
</item>
<tag><c>{n2n, EnumTypeName}</c></tag>
@@ -206,28 +211,6 @@ Binary = binary()
shall be placed. If omitted the files are placed in the
current directory.</p>
</item>
- <tag><c>optimize</c></tag>
- <item>
- <p>This option is only valid together with one of the
- <c>per_bin</c>
- or <c>ber_bin</c> option. It gives time optimized code
- generated and it uses another runtime module and
- in the <c>per_bin</c> case a nif. The result
- in the <c>per_bin</c> case from an encode when compiled
- with this option will be a binary.</p>
- </item>
- <tag><c>driver</c></tag>
- <item>
- <p>As of R15B this means the same as the <c>nif</c> option. Kept for
- backwards compatability reasons.</p>
- </item>
- <tag><c>nif</c></tag>
- <item>
- <p>Option valid together with <c>ber_bin</c> and <c>optimize</c>
- options. It enables the use of several nifs that gives faster
- encode and decode. Nifs are only enabled by the explicit use of
- the option <c>nif</c></p>
- </item>
<tag><c>asn1config</c></tag>
<item>
<p>When one of the specialized decodes, exclusive or
@@ -255,32 +238,6 @@ Binary = binary()
list or a binary. Earlier versions of the compiler ignored
those following bytes.</p>
</item>
- <tag><c>{inline, OutputName}</c></tag>
- <item>
- <p>Compiling with this option gives one output module
- containing all asn1 run-time functionality. The asn1 specs
- are provided in a target module Module.set.asn as described
- <seealso marker="#asn1set">above</seealso>. The name of the
- resulting module containing generated encode/decode functions
- and in-lined run-time functions will be
- <c>OutputName.erl</c>. The merging/in-lining of code is done
- by the <c>igor</c> module of <c>syntax_tools</c>. By default
- the functions generated from the first asn1 spec in the
- <c>.set.asn</c> are exported, unless a
- <c>{export, [atom()]}</c> or <c>{export_all, true}</c> option
- are provided. The list of atoms are names of chosen asn1
- specs from the <c>.set.asn</c> file. </p>
- <p>When used together with <c>nif</c> for <c>ber_bin</c>, the
- asn1 nifs will be used if the <c>asn1rt_nif</c> module is
- available. If it is not available, a slower erlang fallback
- will be used.</p>
- </item>
- <tag><c>inline</c></tag>
- <item>
- <p>It is also possible to use the sole argument <c>inline</c>.
- It is as <c>{inline, OutputName}</c>, but the output file gets the
- default name of the source <c>.set.asn</c> file.</p>
- </item>
<tag><c>{macro_name_prefix, Prefix}</c></tag>
<item>
<p>All macro names generated by the compiler are prefixed with
@@ -327,13 +284,12 @@ Binary = binary()
<type>
<v>Module = Type = atom()</v>
<v>Value = term()</v>
- <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
+ <v>Bytes = binary()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module
- <c>Module</c>. Returns a list of bytes if successful. To get as fast execution as
- possible the
+ <c>Module</c>. To get as fast execution as possible the
encode function only performs rudimentary tests that the input
<c>Value</c>
is a correct instance of <c>Type</c>. The length of strings is for example
@@ -348,10 +304,10 @@ Binary = binary()
<type>
<v>Module = Type = atom()</v>
<v>Value = Reason = term()</v>
- <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
+ <v>Bytes = binary()</v>
</type>
<desc>
- <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes
+ <p>Decodes <c>Type</c> from <c>Module</c> from the binary
<c>Bytes</c>. Returns <c>{ok, Value}</c> if successful.</p>
</desc>
</func>
diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml
index 0c3c257189..2b1b108ab1 100644
--- a/lib/asn1/doc/src/asn1rt.xml
+++ b/lib/asn1/doc/src/asn1rt.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1997</year><year>2011</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -47,35 +47,34 @@
<type>
<v>Module = Type = atom()</v>
<v>Value = Reason = term()</v>
- <v>Bytes = binary | [Int] when integer(Int), Int >= 0, Int =&lt; 255 | binary</v>
+ <v>Bytes = binary</v>
</type>
<desc>
- <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes or
- binary <c>Bytes</c>. If the module is compiled with <c>ber_bin</c>
- or <c>per_bin</c> option <c>Bytes</c> must be a binary.
+ <p>Decodes <c>Type</c> from <c>Module</c> from the binary <c>Bytes</c>.
Returns <c>{ok,Value}</c> if successful.</p>
</desc>
</func>
<func>
- <name>encode(Module,Type,Value)-> {ok,BinOrList} | {error,Reason}</name>
+ <name>encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}</name>
<fsummary>Encode an ASN.1 value.</fsummary>
<type>
<v>Module = Type = atom()</v>
<v>Value = term()</v>
- <v>BinOrList = Bytes | binary()</v>
- <v>Bytes = [Int|binary|Bytes] when integer(Int), Int >= 0, Int =&lt; 255</v>
+ <v>Bytes = binary</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module
<c>Module</c>. Returns a possibly nested list of bytes and or binaries
- if successful. If <c>Module</c> was compiled with the options <c>per_bin</c> and <c>optimize</c> the result is a binary. To get as
- fast execution as possible the
+ if successful. To get as fast execution as possible the
encode function only performs rudimentary tests that the input
<c>Value</c>
is a correct instance of <c>Type</c>. The length of strings is for example
not always checked. </p>
+ <note>
+ <p>Starting in R16, <c>Bytes</c> is always a binary.</p>
+ </note>
</desc>
</func>
@@ -95,28 +94,6 @@
</func>
<func>
- <name>load_driver() -> ok | {error,Reason}</name>
- <fsummary>Loads the linked-in driver. (deprecated)</fsummary>
- <type>
- <v>Reason = term()</v>
- </type>
- <desc>
- <p>This function is obsolete and will be removed in R16A</p>
- </desc>
- </func>
-
- <func>
- <name>unload_driver() -> ok | {error,Reason}</name>
- <fsummary>Unloads the linked-in driver. (deprecated)</fsummary>
- <type>
- <v>Reason = term()</v>
- </type>
- <desc>
- <p>This function is obsolete and will be removed in R16A</p>
- </desc>
- </func>
-
- <func>
<name>utf8_binary_to_list(UTF8Binary) -> {ok,UnicodeList} | {error,Reason}</name>
<fsummary>Transforms an utf8 encoded binary to a unicode list.</fsummary>
<type>
diff --git a/lib/asn1/doc/src/notes.xml b/lib/asn1/doc/src/notes.xml
index de58aef0e2..5e21b926a8 100644
--- a/lib/asn1/doc/src/notes.xml
+++ b/lib/asn1/doc/src/notes.xml
@@ -31,6 +31,73 @@
<p>This document describes the changes made to the asn1 application.</p>
+<section><title>Asn1 2.0</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Encoding SEQUENCEs with multiple extension addition
+ groups with optional values could fail (depending both on
+ the specification and whether all values were provided).</p>
+ <p>
+ Own Id: OTP-10664</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>The options for the ASN.1 compiler has been
+ drastically simplified. The backend is chosen by using
+ <c>ber</c>, <c>per</c>, or <c>uper</c>. The options
+ <c>optimize</c>, <c>nif</c>, and <c>driver</c> are no
+ longer needed. The old options will still work, but will
+ issue a warning.</p>
+ <p>Another change is that generated <c>encode/2</c>
+ function will always return a binary (some backends used
+ to return an iolist).</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-10410 Aux Id: kunagi-254 [165] </p>
+ </item>
+ <item>
+ <p>
+ The ASN.1 compiler generates faster decode functions for
+ PER and UPER. Some minor improvements have also been made
+ for PER/UPER encoding, and to the BER backend.</p>
+ <p>
+ Own Id: OTP-10519 Aux Id: kunagi-322 [233] </p>
+ </item>
+ <item>
+ <p>The ASN.1 compiler will now always include necessary
+ run-time functions in the generated Erlang modules
+ (except for <c>asn1rt_nif</c> which is still neeeded). If
+ the option '<c>inline</c>' is used the ASN.1 compiler
+ will generate a warning. But if
+ '<c>{inline,OutputFile}</c>' is use, the ASN.1 compiler
+ will refuse to compile the file. (Use a <c>.set.asn</c>
+ file if you need to remove the output file.)</p>
+ <p>The '<c>BIT STRING</c>' type will now be decoded as
+ Erlang bitstrings by default. Use the new
+ <c>legacy_bit_string</c> option to encode as lists of
+ ones and zeroes. (The <c>compact_bit_string</c> option
+ still works as before.)</p>
+ <p>Open types are now always returned as binaries (when
+ there is no information allowing them to be decoded).</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-10588 Aux Id: kunagi-341 [252] </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Asn1 1.8.1</title>
<section><title>Fixed Bugs and Malfunctions</title>
@@ -512,7 +579,7 @@
ENUMERATION type, the compilation will be terminated with an
error code.<br/>
Below follows an example on how to use the option from the command line with <c>erlc</c>:<br/>
- <c>erlc -bper_bin +optimize +driver +"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn</c>
+ <c>erlc -bper+"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn</c>
</p>
<p>
Own Id: OTP-8136 Aux Id: seq11347 </p>