From 058eba7c2f6661bac25eeacfb97e53fda162d141 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 15 Nov 2012 09:34:06 +0100 Subject: Update documentation for the asn1 application --- lib/asn1/doc/src/asn1_ug.xml | 389 ++++--------------------------------------- lib/asn1/doc/src/asn1ct.xml | 69 +++----- lib/asn1/doc/src/asn1rt.xml | 39 +---- lib/asn1/doc/src/notes.xml | 2 +- 4 files changed, 64 insertions(+), 435 deletions(-) (limited to 'lib/asn1/doc') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 09b9e7315a..6cb251c3e2 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -186,13 +186,21 @@ END The following shows how the compiler can be called from the Erlang shell:

-1>asn1ct:compile("People",[ber_bin]).
+1>asn1ct:compile("People", [ber]).
+ok
+2>      
+ +

The verbose option can be given to have information + about the generated files printed:

+
+2>asn1ct:compile("People", [ber,verbose]).
 Erlang ASN.1 compiling "People.asn" 
 --{generated,"People.asn1db"}--
 --{generated,"People.hrl"}--
 --{generated,"People.erl"}--
 ok
-2>      
+3> +

The ASN.1 module People is now accepted and the abstract syntax tree is saved in the People.asn1db file, the generated Erlang code is compiled using the Erlang compiler and @@ -229,7 +237,7 @@ receive constructed and encoded using 'People':encode('Person',Answer) 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.

The encoder and the decoder can also be run from @@ -239,24 +247,12 @@ The encoder and the decoder can also be run from

 2> Rockstar = {'Person',"Some Name",roving,50}.
 {'Person',"Some Name",roving,50}
-3> {ok,Bytes} = asn1rt:encode('People','Person',Rockstar).
-{ok,[<<243>>,
-     [17],
-     [19,9,"Some Name"],
-     [2,1,[2]],
-     [2,1,"2"]]}
-4> Bin = list_to_binary(Bytes).
-<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,2,1,50>>
-5> {ok,Person} = asn1rt:decode('People','Person',Bin).
+3> {ok,Bin} = asn1rt:encode('People','Person',Rockstar).
+{ok,<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
+      2,1,50>>}
+4> {ok,Person} = asn1rt:decode('People','Person',Bin).
 {ok,{'Person',"Some Name",roving,50}}
-6>      
-

Notice that the result from encode is a nested list which - must be turned into a binary before the call to decode. A - binary is necessary as input to decode since the module was compiled - with the ber_bin option - The reason for returning a nested list is that it is faster to produce - and the list_to_binary operation is - performed automatically when the list is sent via the Erlang port mechanism.

+5>
@@ -305,17 +301,15 @@ The encoder and the decoder can also be run from ASN.1 compiler:

 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      

The useful options for the ASN.1 compiler are:

- -b[ber | per | ber_bin | per_bin | uper_bin] + -b[ber | per | uper]

Choice of encoding rules, if omitted ber is the - default. The ber_bin and per_bin options - allows for optimizations and are therefore recommended - instead of the ber and per options.

+ default.

-o OutDirectory @@ -339,42 +333,12 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn +der -

DER encoding rule. Only when using -ber or - -ber_bin option.

-
- +optimize - -

This flag has effect only when used together with one of - per_bin or ber_bin flags. It gives time optimized - code in the generated modules and it uses another runtime module. - In the per_bin case a nif is used. The - result from an encode is a binary.

-

When this flag is used you cannot use the old format{TypeName,Value} 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 {ComponentName,Value} 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 - {ComponentName,Value}. See also about - {Typename,Value} below - and in the sections for each type.

-
- +driver - -

As of R15B this means the same as the nif option. Kept for - backwards compatability reasons.

-
- +nif - -

Together with the flags ber_bin - and optimize you choose to use a nif for considerable - faster encode and decode.

+

DER encoding rule. Only when using -ber option.

+asn1config

This functionality works together with the flags - ber_bin and optimize. You enables the + ber. It enables the specialized decodes, see the Specialized Decode chapter.

@@ -413,7 +377,6 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn

For a complete description of erlc see Erts Reference Manual.

-

For preferred option use see Preferred Option Use section.

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 +392,9 @@ asn1ct:compile("H323-MESSAGES.asn1").

which equals:

 asn1ct:compile("H323-MESSAGES.asn1",[ber]).      
-

If one wants PER encoding with optimizations:

+

If one wants PER encoding:

-asn1ct:compile("H323-MESSAGES.asn1",[per_bin,optimize]).      
+asn1ct:compile("H323-MESSAGES.asn1",[per]).

The generic encode and decode functions can be invoked like this:

 asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
@@ -442,269 +405,6 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes).      
'H323-MESSAGES':decode('SomeChoiceType',Bytes).
-
- - Preferred Option Use -

- 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. -

-

- The default option is ber. It is the same backend as - ber_bin 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 - allowed combinations of coding and optimization - options: (EAVF stands for how ASN1 values are represented in - Erlang which is described in the ASN1 Types chapter) -

- - - Encoding Rule - Compile options, allowed combinations - encode input - encode output - decode input - decode output - - - BER - [ber] (default) - EAVF - flat list - flat list / binary - EAVF - - - BER - [ber_bin] - EAVF - iolist - binary - EAVF - - - BER - [ber_bin, optimize] - EAVF - iolist - binary - EAVF - - - BER - [ber_bin, optimize, nif] - EAVF - iolist - iolist / binary - EAVF - - - PER aligned variant - [per] - EAVF - flat list - flat list - EAVF - - - PER aligned variant - [per_bin] - EAVF - iolist / binary - binary - EAVF - - - PER aligned variant - [per_bin, optimize] - EAVF - binary - binary - EAVF - - - PER unaligned variant - [uper_bin] - EAVF - binary - binary - EAVF - - - - DER - [(ber), der] - EAVF - flat list - flat list / binary - EAVF - - - DER - [ber_bin, der] - EAVF - iolist - binary - EAVF - - - DER - [ber_bin, optimize, der] - EAVF - iolist - binary - EAVF - - - DER - [ber_bin, optimize, nif, der] - EAVF - iolist - binary - EAVF - - - - The output / input formats for different combinations of compile options. -
-

- Encode / decode speed comparison in one user case for the above - alternatives (except DER) is showed in the table below. The - DER alternatives are slower than their corresponding - BER alternative. -

- - - - compile options - encode time - decode time - - - [ber] - 120 - 162 - - - [ber_bin] - 124 - 154 - - - [ber_bin, optimize] - 50 - 78 - - - [ber_bin, optimize, driver] - 50 - 62 - - - [per] - 141 - 133 - - - [per_bin] - 125 - 123 - - - [per_bin, optimize] - 77 - 72 - - - [uper_bin] - 97 - 104 - - - One example of difference in speed for the compile option alternatives. - -
- -

- The compile options ber, per and - driver 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. -

-

- You are strongly recommended to use the appropriate alternative - of the bold typed options. The optimize and - nif options does not affect the encode or decode - result, just the time spent in run-time. When ber_bin and - nif or per_bin and optimize is - combined the C-code nif is used in chosen parts of encode / - decode procedure. -

- - - Compile options, allowed combinations - use of nif - - - [ber] - no - - - [ber_bin] - no - - - [ber_bin, optimize] - no - - - [ber_bin, optimize, nif] - yes - - - [per] - no - - - [per_bin] - no - - - [per_bin, optimize] - yes - - - [uper_bin] - no - - - - [(ber), der] - no - - - [ber_bin, der] - no - - - [ber_bin, optimize, der] - no - - - [ber_bin, optimize, nif, der] - yes - - - - When the ASN1 nif is used. -
- -
Run-time Functions

A brief description of the major functions is given here. For a @@ -719,9 +419,9 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). 'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}). 'H323-MESSAGES':decode('SomeChoiceType',Bytes).

The asn1 nif is enabled in two occasions: encoding of - asn1 values when the asn1 spec is compiled with per_bin and - optimize or decode of encoded asn1 values when the asn1 spec is - compiled with ber_bin, optimize and nif. In + asn1 values when the asn1 spec is compiled with per and + or decode of encoded asn1 values when the asn1 spec is + compiled with ber. In those cases the nif will be loaded automatically at the first call to encode/decode. If one doesn't want the performance overhead of the nif being loaded at the first call it is possible @@ -868,26 +568,6 @@ Operational ::= BOOLEAN --ASN.1 definition

 Val = true,
 {ok,Bytes}=asn1rt:encode(MyModule,'Operational',Val),    
-

For historical reasons it is also possible to assign ASN.1 values - in Erlang using a tuple notation - with type and value as this

-
-Val = {'Operational',true}    
- - -

The tuple notation, {Typename, Value} is only kept - because of backward compatibility and may be withdrawn in a - future release. If the notation is used the Typename - element must be spelled correctly, otherwise a run-time error - will occur. -

-

If the ASN.1 module is compiled with the flags - per_bin or ber_bin and optimize 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 {ComponentName,Value} notation in case of a - SEQUENCE or SET type.

-

Below follows a description of how values of each type can be represented in Erlang.

@@ -1149,7 +829,7 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] The following example shows how it works:

In a file PrimStrings.asn1 the type BMP is defined as

-BMP ::= BMPString then using BER encoding (ber_bin +BMP ::= BMPString then using BER encoding (ber option)the input/output format will be:

 1> {ok,Bytes1} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,45,56}]).
@@ -1174,9 +854,9 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....]
         utf8_list_to_binary, are in the asn1rt module. In
         the example below we assume an asn1 definition UTF ::= UTF8String in a module UTF.asn:

-1> asn1ct:compile('UTF',[ber_bin]).
+1> asn1ct:compile('UTF',[ber]).
 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
@@ -1731,12 +1411,9 @@ SS ::= SET {
 1> Val = 'Values':tt().
 {'TT',77,["kalle","kula"]}
 2> {ok,Bytes} = 'Values':encode('TT',Val).
-{ok,["0",
-     [18],
-     [[[128],[1],"M"],["\\241","\\r",[[[4],[5],"kalle"],[[4],[4],"kula"]]]]]}
-3> FlatBytes = lists:flatten(Bytes).
-[48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,107,117,108,97]
-4> 'Values':decode('TT',FlatBytes).
+{ok,<<48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,
+      107,117,108,97>>}
+4> 'Values':decode('TT',Bytes).
 {ok,{'TT',77,["kalle","kula"]}}
 5>
     
diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index 3be58cbc8e..9a9bb7ec1b 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -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).

+ +

In R16, the options have been simplified. The back-end is chosen + using one of the options ber, per, or uper. + The options optimize, nif, and driver options + are no longer necessary (and the ASN.1 compiler will print a + warning if they are used). The options ber_bin, per_bin, + and uper_bin options will still work, but will print a warning. +

+

Another change in R16 is that the generated encode/2 + function (and asn1rt:encode/3) always returns a binary. + The encode/2 function for the BER back-end used to return + an iolist.

+
@@ -50,9 +63,9 @@ Asn1module = atom() | string() Options = [Option| OldOption] - 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 | + Option = ber | per | uper | der | compact_bit_string | + noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} | + asn1config | undec_rest | {inline, OutputName} | inline | {macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose | warnings_as_errors OldOption = ber | per Reason = term() @@ -112,7 +125,7 @@ File3.asn
section in users guide. Available options are:

- ber | ber_bin | per | per_bin | uper_bin + ber | per | uper

The encoding rule to be used. The supported encoding rules @@ -120,23 +133,12 @@ File3.asn PER aligned (Packed Encoding Rules) and PER unaligned. If the encoding rule option is omitted ber is the default. - The per_bin option means the aligned - variant. To use the unaligned variant the uper_bin - option has to be used.

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.

-

- The ber_bin and per_bin options are - equivalent with the OldOptions ber and per - 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. -

der @@ -144,7 +146,7 @@ File3.asn By this option the Distinguished Encoding Rules (DER) is chosen. DER is regarded as a specialized variant of the BER encoding rule, therefore the der option only makes sense together - with the ber or ber_bin option. + with the ber option. This option sometimes adds sorting and value checks when encoding, which implies a slower encoding. The decoding routines are the same @@ -206,28 +208,6 @@ Binary = binary() shall be placed. If omitted the files are placed in the current directory.

- optimize - -

This option is only valid together with one of the - per_bin - or ber_bin option. It gives time optimized code - generated and it uses another runtime module and - in the per_bin case a nif. The result - in the per_bin case from an encode when compiled - with this option will be a binary.

-
- driver - -

As of R15B this means the same as the nif option. Kept for - backwards compatability reasons.

-
- nif - -

Option valid together with ber_bin and optimize - 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 nif

-
asn1config

When one of the specialized decodes, exclusive or @@ -270,10 +250,6 @@ Binary = binary() {export, [atom()]} or {export_all, true} option are provided. The list of atoms are names of chosen asn1 specs from the .set.asn file.

-

When used together with nif for ber_bin, the - asn1 nifs will be used if the asn1rt_nif module is - available. If it is not available, a slower erlang fallback - will be used.

inline @@ -327,13 +303,12 @@ Binary = binary() Module = Type = atom() Value = term() - Bytes = [Int] when integer(Int), Int >= 0, Int =< 255 + Bytes = binary() Reason = term()

Encodes Value of Type defined in the ASN.1 module - Module. Returns a list of bytes if successful. To get as fast execution as - possible the + Module. To get as fast execution as possible the encode function only performs rudimentary tests that the input Value is a correct instance of Type. The length of strings is for example @@ -348,10 +323,10 @@ Binary = binary() Module = Type = atom() Value = Reason = term() - Bytes = [Int] when integer(Int), Int >= 0, Int =< 255 + Bytes = binary() -

Decodes Type from Module from the list of bytes +

Decodes Type from Module from the binary Bytes. Returns {ok, Value} if successful.

diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml index 0c3c257189..f2cac0c9e7 100644 --- a/lib/asn1/doc/src/asn1rt.xml +++ b/lib/asn1/doc/src/asn1rt.xml @@ -47,35 +47,34 @@ Module = Type = atom() Value = Reason = term() - Bytes = binary | [Int] when integer(Int), Int >= 0, Int =< 255 | binary + Bytes = binary -

Decodes Type from Module from the list of bytes or - binary Bytes. If the module is compiled with ber_bin - or per_bin option Bytes must be a binary. +

Decodes Type from Module from the binary Bytes. Returns {ok,Value} if successful.

- encode(Module,Type,Value)-> {ok,BinOrList} | {error,Reason} + encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason} Encode an ASN.1 value. Module = Type = atom() Value = term() - BinOrList = Bytes | binary() - Bytes = [Int|binary|Bytes] when integer(Int), Int >= 0, Int =< 255 + Bytes = binary Reason = term()

Encodes Value of Type defined in the ASN.1 module Module. Returns a possibly nested list of bytes and or binaries - if successful. If Module was compiled with the options per_bin and optimize 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 Value is a correct instance of Type. The length of strings is for example not always checked.

+ +

Starting in R16, Bytes is always a binary.

+
@@ -94,28 +93,6 @@ - - load_driver() -> ok | {error,Reason} - Loads the linked-in driver. (deprecated) - - Reason = term() - - -

This function is obsolete and will be removed in R16A

-
-
- - - unload_driver() -> ok | {error,Reason} - Unloads the linked-in driver. (deprecated) - - Reason = term() - - -

This function is obsolete and will be removed in R16A

-
-
- utf8_binary_to_list(UTF8Binary) -> {ok,UnicodeList} | {error,Reason} Transforms an utf8 encoded binary to a unicode list. diff --git a/lib/asn1/doc/src/notes.xml b/lib/asn1/doc/src/notes.xml index 5ca86130a1..72b496caf7 100644 --- a/lib/asn1/doc/src/notes.xml +++ b/lib/asn1/doc/src/notes.xml @@ -483,7 +483,7 @@ ENUMERATION type, the compilation will be terminated with an error code.
Below follows an example on how to use the option from the command line with erlc:
- erlc -bper_bin +optimize +driver +"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn + erlc -bper+"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn

Own Id: OTP-8136 Aux Id: seq11347

-- cgit v1.2.3