![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to DESCRIPTION CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / pepsy / doc|
Return to DESCRIPTION CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / pepsy / doc |
1.1 root 1:
2:
3:
4:
5:
6:
7: _1. _O_v_e_r_v_i_e_w _o_f _p_e_p_s_y _s_y_s_t_e_m
8:
9: This section describes how the various parts fit
10: together to make the system work. The principle behind
11: pepsy is fairly simple. The ASN.1 is summarised as tables
12: of integers. These tables are read by driver routines which
13: encode or decode data to or from the internal format that
14: ISODE OSI implementation uses. In ISODE specific functions
15: are generated for each ASN.1 type defined in contrast the
16: pepsy merely generates a new table of data which is far far
17: smaller.
18:
19: As there is a great deal of effort invested in the
20: ISODE interface to the encoding/decoding routines pepsy
21: automatically provides macros which map the original func-
22: tions into the appropriate function call of a driver. This
23: allows existing posy using code to switch to the pepsy sys-
24: tem with no changes to the code provided no function
25: pointers are used to the original ISODE functions. Even
26: when there are function pointers used the changes are very
27: simple and take only a few hours to implement.
28:
29: _1._1. _B_r_i_e_f _d_e_s_c_r_i_p_t_i_o_n _o_f _t_h_e _u_s_e _o_f _t_h_e _p_e_p_s_y _s_y_s_t_e_m.
30:
31: _1._1._1. _O_u_t_l_i_n_e _o_f _t_h_e _f_i_l_e_s _p_r_o_d_u_c_e_d _u_n_d_e_r _t_h_e _p_e_p_s_y _s_y_s_-
32: _t_e_m.
33:
34: The pepsy system consists of a program called _p_o_s_y
35: which translates ASN.1 modules into a set of tables, called
36: _p_o_s_y at the moment, and library of driver routines, called
37: _l_i_b_p_e_p_s_y._a. Running this _p_o_s_y program on the ASN.1 file
38: will produce several files. If the name of the ASN.1 module
39: is MODULE the following files are generated:
40:
41: MODULE-types.h
42: which contains C structure definitions. The user of
43: the library provides data as a linked list of these C
44: data structures and expects to receive data back as a
45: similar linked list. These data structures are exactly
46: the same as those produced by the original ISODE _p_o_s_y
47: so that existing software written for the old _p_o_s_y pro-
48: gram needs no change. For details on the C data struc-
49: tures types generated see the documentation of the ori-
50: ginal _p_o_s_y program in volume 4 Chapter 5 of the ISODE
51: manuals.
52:
53: MODULE_tables.c
54: This file contains the tables generated by the new _p_o_s_y
55: program. These tables consist of three parts, the
56: first which contains the summary of ASN.1 types. Each
57: type is summarised as an array of a primitive type,
58: struct pte, for encoding and decoding, and struct ptpe
59: for printing. As implied there is one array for each
60: type for each of encoding, decoding and printing as
61:
62:
63:
64: January 23, 1990
65:
66:
67:
68:
69:
70: - 2 -
71:
72:
73: specified when _p_o_s_y is run. The next part contains up
74: to three tables of pointers to these arrays. Each of
75: the three different types of arrays, encoding, decoding
76: and printing, has its own table of pointers. Finally
77: there is the module type definition which contains con-
78: tains pointers to these tables and some other useful
79: information about the module such as its name. This
80: module type structure, which is typedefed to modtyp, is
81: the only piece of data which is global, all the rest of
82: the data is static and is only addressable via the mod-
83: typ data structure. This provides a kind of object
84: oriented approach to handling the tables. Once you are
85: passed a pointer to an ASN.1's modtyp structure you can
86: encode, decode and print any of its types by calling
87: the appropriate libpepsy.a routine with its type
88: number.
89:
90: MODULE_pre_defs.h
91: This file contains #defines symbol of each of the ASN.1
92: types to its type number, which is used when calling a
93: libpepsy.a routine. Each symbol is _Ztype-nameMODULE
94: where _t_y_p_e-_n_a_m_e is the name of the type with dashes (-)
95: turned into underscores (_) and _M_O_D_U_L_E is the name of
96: the module. For example of the ASN.1 universal type
97: _G_r_a_p_h_i_c_S_t_r_i_n_g would have the #define symbol _ZGra-
98: phicStringUNIV. The __Z is prepended to try to make the
99: symbols unique. This file also contains and extern
100: declaration for the modtyp data for its module.
101:
102: MODULE_defs.h
103: This file contains macros for all the encoding, decod-
104: ing and printing functions that the _p_e_p_y program would
105: have for these ASN.1 types. This allows much of the
106: code that uses the routines generated by running the
107: old _p_o_s_y program and taking its output and running _p_e_p_y
108: on augmented ASN.1 output can be recompiled unchanged.
109: If the code used pointers to these functions it is
110: necessary to change it to pass around the type numbers
111: instead and to call appropriately call a libpepsy.a
112: library routine with the type number. As pointers to
113: the printing routines in ISODE are passed as arguments
114: a #define is provided to turn the argument into the
115: pair of arguments, type number and pointer to modtyp
116: structure, which are needed to allow the diagnostic
117: printing code to work with no change for the current
118: ISODE stack. This file also contains a #include of the
119: _M_O_D_U_L_E__p_r_e__d_e_f_s._h file.
120:
121: As the _M_O_D_U_L_E-_t_y_p_e_s._h file #include's the _M_O_D_U_L_E__d_e_f_s._h
122: file no further #includes need to be added to the files
123: using the encoding/decoding/printing functions. This means
124: that code written to use posy/pepy system may need no change
125: at all and the only effort required is to change the
126: Makefile to use the pepsy system. If there is code changes
127:
128:
129:
130: January 23, 1990
131:
132:
133:
134:
135:
136: - 3 -
137:
138:
139: required it would most likely be because function pointers
140: are used to reference the functions generated by posy. If
141: only the _p_e_p_y system was used, not posy then pepy, with code
142: placed inside action statements then quite a large amount of
143: work may be needed to change over to the new system, depend-
144: ing on how large and complex the _p_e_p_y module is.
145:
146: _1._1._2. _O_u_t_l_i_n_e _o_f _t_h_e _p_e_p_s_y _l_i_b_r_a_r_y.
147:
148: enc.cThis contains the routines that encode data from the C
149: data structures into ISODE's PElement linked list data
150: structure which it uses for all presentation data. The
151: most important function to pepsy users is enc_f which
152: called to encode a particular type. It is passed the
153: type number and a pointer to modtyp structure for that
154: module and then the rest of the arguments which are
155: passed to an encode function generated by _p_o_s_y/_p_e_p_y
156: system. See the documentation in Volume 4, "The Appli-
157: cations Cookbook", Section 6.4 called "Pepy Environ-
158: ment". Most of these latter arguments are ignored,
159: only parm and pe, are used.
160:
161: Contrary to what the ISODE documentation says these
162: ignored parameters are hardly ever used by existing code.
163: We have not found a single case where used for encoding a
164: named type, which is all that the user can reference anyway,
165: so we don't see any problems with ignoring these other
166: parameters. Hopefully one day they can be thrown away
167: entirely, until then they are actually passed the the encod-
168: ing function.
169:
170: The rest of the functions are mostly recursive routines
171: which encode a particular type of table entry. For example
172: SEQUENCE is encoded by en_seq which may call itself or oth-
173: ers to encode the types from which it is built up. The
174: function en_type builds up a simple type and en_obj encodes
175: a new type (object) and so on with other functions. There
176: are a few utility routines in the file such as same which
177: determines whether the value is the same as the default
178: value also.
179:
180: dec.cThis file contains the decoding routines that translate
181: presentation data into C data structures defined in the
182: MODULE-types.h is like _e_n_c._c. It is very much like the
183: file _e_n_c._c except the routines do the reverse tasks The
184: routines are structured in a very similar way. We have
185: dec_f which is called by the user to decode a type and
186: like enc_f takes the same arguments as the decoding
187: functions generated by _p_o_s_y with two additions, the
188: type number and a pointer to the modtyp structure for
189: that module. Likewise the other functions are very
190: much like those of enc.c
191:
192: prnt.cThis file contains the routines that print the
193:
194:
195:
196: January 23, 1990
197:
198:
199:
200:
201:
202: - 4 -
203:
204:
205: presentation data in a format similar to that generated
206: by _p_e_p_y's printing functions. It's main function
207: prnt_f is takes the same arguments as the printing
208: function generated by _p_e_p_y as well as the now familiar
209: type number and modtyp pointer. The functions are
210: modeled on the decoding routines as it has similar job
211: to. The only difference is that instead of storing the
212: decoded data into a C data structure it is nicely
213: printed out.
214:
215: fr.c This file contains code to free the data structures
216: defined in MODULE-types.h. Likewise if the -f flag is
217: given when generating the types file it also includes
218: macros in the types file which replace the freeing
219: functions generated by ISODE's _p_o_s_y. The function that
220: the user calls us fre_obj which takes a pointer to the
221: data structure, its decoding table entry and a pointer
222: to the modtyp structure for the module. The freeing is
223: based on the decoding routines except instead of decod-
224: ing all it does is free each part of the data struc-
225: ture, which might involve recursive calls, then it
226: frees the data structure at the end.
227:
228: util.cThis contains the utility routines used by more than
229: one of the above files. This is mostly diagnostic rou-
230: tines at the moment, more general routines could be
231: included in here. If there is an error at the moment
232: which it can't recover from it just prints out a mes-
233: sage on standard error and calls exit. Not perfect and
234: this is something that will need work.
235:
236: main.cThis contains code to perform a series of tests on the
237: _p_e_p_s_y library which is a useful check to see whether
238: any of the routines has been broken by any changes
239: made. It basically loops through a whole series of
240: test cases. Each test case is encoded from some built
241: in test data and then decoded and checked to see if the
242: data has changed in the transfer. If it is compiled
243: with -_D_P_R_N_T=_1 the encoded data is also printed out to
244: check the printing routines which generates a vast
245: amount of output. Finally the free routines are used
246: to free the allocated data, although it can not
247: directly check the free routines to see if they work,
248: it can be used with a malloc tracing package to check
249: that the routines work.
250:
251: test_table.h
252: This contains the test cases that _m_a_i_n._c program runs.
253: Each entry in the table corresponds to a type. One of
254: the fields is count of how many times that type is to
255: be tested to try out the different possibly data values
256: it might have.
257:
258: pep.h and pepdefs.h
259:
260:
261:
262: January 23, 1990
263:
264:
265:
266:
267:
268: - 5 -
269:
270:
271: These files contain the definition of types used for
272: the tables that drive the encoding/decoding/printing
273: routines. All the constants used in that table are
274: defined here via #defines. The modtyp structure is
275: defined in _p_e_p_d_e_f_s._h.
276:
277: t1.py and t2.py
278: These are test ASN.1 modules that are used by _m_a_i_n._c
279: routines to check the _p_e_p_s_y library. The file _t_1._p_y
280: contains the majority of different types with a few of
281: a different module provided in _t_2._p_y. This allows the
282: testing of the code for handling ASN.1 external refer-
283: ences, i.e. references to types defined in other,
284: external, modules.
285:
286: _1._1._3. _N_e_w _f_i_l_e_s _i_n _t_h_e _p_e_p_y _d_i_r_e_c_t_o_r_y
287:
288: etabs.c, dtabs.c and ptabs.c
289: These files contain the code to generate the
290: encoding/decoding/printing tables. The main routine in
291: _e_t_a_b_s._c is tenc_typ which is called on each ASN.1 type
292: to generate an array of entries which describe how to
293: encode that type. See the details section for more
294: information about how the table entries function.
295: Similarly _d_t_a_b_s._c contains the routine tdec_typ which
296: is called on each type to generate its decoding table
297: entries. Likewise tprnt_typ routine generates the
298: arrays of table entries for the printing tables. This
299: function is in _p_t_a_b_s._c.
300:
301: dfns.cThis file contains miscellaneous string handling rou-
302: tines and hash table routines that don't really belong
303: anywhere else. Some of the routines could be cleaned
304: up in that they tend not to free memory they use.
305:
306: mine.hThis file contains the definitions for the hash
307: table(s) that are used to keep track of the ASN.1
308: types. This could probably be done with out a hash
309: table, should anyone want to clean this up, feel wel-
310: come. The lookup function is in _d_f_n_s._c.
311:
312: pass2.h
313: This file has most of the #defines for the table gen-
314: erating program. Most of the prefixes and suffixes of
315: function names and files names are defined here so,
316: hopefully, the names can be changed by merely changing
317: the definition. This contains most of the important
318: definitions needed by the changes to the _p_o_s_y program
319: needed to generate tables.
320:
321: posy.hThis contains the definition of a symbol which is now
322: needed outside of the the main routine and the yacc
323: file. By putting it here we can include it any file
324: that needs to know it with out putting in any that
325:
326:
327:
328: January 23, 1990
329:
330:
331:
332:
333:
334: - 6 -
335:
336:
337: doesn't need it and with out including all the other
338: definitions that occur in _p_e_p_y._h. The structure and
339: meaning of the tables generated from the ASN.1 grammar
340:
341: Each collection of ASN.1 grammar is called a module.
342: (See ASN.1 ) Each ASN.1 module is completely specified in
343: the program by a single C structure of type modtyp and the
344: data which it references. See the _p_e_p_d_e_f_s._h file in the
345: _p_e_p_s_y directory. For each ASN.1 module there are three
346: tables that are generated fromASN.1 grammar. These initial-
347: ised arrays which we call tables are called the encoding,
348: decoding and printing tables. Each of these tables is
349: referenced through a different pointer of the modtyp struc-
350: ture.
351:
352: Each of these pointers references an array of pointers,
353: one pointer for each ASN.1 type defined in the module. The
354: position of one of these pointers is the unique type number
355: we give to its corresponding type. The pointer references
356: an array of type tpe or ptpe, depending whether it is an
357: entry in the decoding/encoding tables or printing tables
358: respectively. See _p_e_p._h in the _p_e_p_s_y directory. This array
359: actually contains the necessary information to
360: encode/decode/print that ASN.1 type. So given the modtyp
361: structure of an ASN.1 module and its type number you can
362: call a routine to encode, decode or print that type.
363:
364: The rest of this document assumes a good knowledge of
365: ASN.1 notation so go read a copy if you haven't already.
366: From here on I shall mention only tpe and this means tpe in
367: the case of encoding or decoding and ptpe in the case of
368: printing, unless otherwise stated. Each type is represented
369: by an array of tpe (or ptpe for printing). The basic ele-
370: ment consists of four integer fields, the printing table is
371: the same with an addition char pointer field which contains
372: the name corresponding to that entry in the ASN.1 grammar.
373: The first specifies the type of the entry and determines how
374: the rest are interpreted. The possible types are listed in
375: _p_e_p_s_y/_p_e_p._h. Each type is an array which starts with an
376: entry of type PE_START and ends with one of type PE_END.
377: Each primitive type requires one entry to specify it, apart
378: from possible PE_START and PE_END used to specify the start
379: and end of the type. Constructed types are represented by a
380: list of entries terminated by an entry of type PE_END. As
381: ASN.1 types can be nested inside so will the representation
382: in tpe entries be nested. For example the ASN.1 type defin-
383: ition:
384: Example1 ::=
385: SEQUENCE {
386: seq1 SEQUENCE {
387: an-i INTEGER,
388: an-ostring OCTET STRING
389: },
390: a-bool IMPLICIT [0] BOOLEAN
391:
392:
393:
394: January 23, 1990
395:
396:
397:
398:
399:
400: - 7 -
401:
402:
403: }
404: Will generate an encoding array:
405: static tpe et_Example1Test[] = {
406: { PE_START, 0, 0, 0 },
407: { SEQ_START, 0, 16, FL_UNIVERSAL },
408: { SEQ_START, OFFSET(struct type_Test_Example1, seq1), 16, FL_UNIVERSAL },
409: { INTEGER, OFFSET(struct element_Test_0, an__i), 2, FL_UNIVERSAL },
410: { OCTETSTRING, OFFSET(struct element_Test_0, an__ostring), 4, FL_UNIVERSAL },
411: { PE_END, 0, 0, 0 },
412: { BOOLEAN, OFFSET(struct type_Test_Example1, a__bool), 0, FL_CONTEXT },
413: { PE_END, 0, 0, 0 },
414: { PE_END, 0, 0, 0 }
415: };
416:
417:
418: Here the second last PE_END matches and closes off the
419: first SEQ_START. The entries which correspond to the other
420: primative types are pretty obvious, with the INTEGER entry
421: corresponding to the primative INTEGER. For fields that
422: generate data the general interpretation of the other three
423: fields is offset, tag and flags/class fields respectively.
424:
425: offsetThe second field gives the offset in a C data struc-
426: ture needed to reference the data that corresponds to
427: this table entry. Each ASN.1 type has C structure
428: types generated as described in the ISODE manuals,
429: volume 4 "The applications Cookbook" Section 5.2, "POSY
430: Environment". As this offset may have to be determined
431: in a compiler dependent manner a C preprocessor macro
432: is used hide the actual details.
433:
434: tag This is the tag associated with the ASN.1 type for that
435: entry. Notice that in the example the [0] IMPLICIT
436: which changes the tag associated with the BOOLEAN entry
437: actually has the correct tag of 0 in the table. Like-
438: wise SEQUENCE has the correct tag of 16 in its
439: SEQ_START entry and so on for the others.
440:
441: flags/class
442: This contains the ASN.1 class associated with the
443: entry's type. That is UNIVERSAL for all except the
444: BOOLEAN type which is CONTEXT class. This fourth can
445: also contain flags that specify if the type is OPTIONAL
446: or DEFAULT. There is plenty of room here as there is
447: only four possibly classes.
448:
449: Now that you have some idea of how these arrays are
450: arranged for a type definition I will proceed to go through
451: the possible type of entries and describe what they do and
452: how they work. These values are defined in _p_e_p_s_y/_p_e_p._h.
453: Those entries with a value below TYPE_DATA are entries that
454: don't correspond to data to be encoded/decoded and are for
455: other book keeping type purposes.
456:
457:
458:
459:
460: January 23, 1990
461:
462:
463:
464:
465:
466: - 8 -
467:
468:
469: PE_START and PE_END
470: As explained above PE_START starts the beginning of a
471: ASN.1 type's array. It probably isn't necessary but
472: the size of the tables is so small it isn't much of an
473: over head to keep around for cosmetic reasons. The
474: entry type PE_END is necessary to mark the end of some
475: compound type as well as the end of ASN.1 data type.
476:
477: XOBJECT and UCODE
478: These are obsolete types and probably should be
479: removed. They were to allow C code written directly by
480: the user to be incorporated into the encoding/decoding
481: but it was found unnecessary. Prehaps some brave soul
482: would like to use them in an attempt to implement a
483: similar system based on _p_e_p_y which is what we first
484: attempted to do until we found this to be much easier.
485:
486: MALLOCThis field only occurs in the decoding tables. It
487: specifies how much space to malloc out for the current
488: C structure it is just inside of. For instance in the
489: example above the decoding table has the following
490: entry:
491:
492: { MALLOC, 0, sizeof (struct type_Test_Example1), 0 },
493:
494: just after the first SEQ_START entry. It tells it to
495: malloc out a struct type_Test_Example1 structure to
496: hold the data from the sequence when it is decoded.
497:
498: SCTRLThis entry is used in handling the ASN.1 CHOICE type.
499: The C type generated for ASN.1 CHOICE type is a struc-
500: ture with an offset field in it and a union of all the
501: C types present in the CHOICE. Each ASN.1 type in the
502: CHOICE of types has a C type definition generated for
503: it. The union is of all these types, which is quite a
504: logical way to implement a CHOICE type. The offset
505: field specifies which possibility of interpreting the
506: union should be used (which _m_e_m_b_e_r should selected).
507: As such it needs to be read by the encoding routines
508: when encoding the data from the C data structures and
509: to be set by the decoding routines when it is decoding
510: the data into the C data structures. There is one such
511: entry for each CHOICE type to specify where the offset
512: field is.
513:
514: CH_ACTAnother redundant entry type. I think this was also
515: used in code to handle C statements or actions speci-
516: fied by the user. It probably should be removed.
517:
518: OPTL This is used to handle the optionals field that is gen-
519: erated by posy when optional types that are _n_o_t imple-
520: mented by pointers are present in the ASN.1 type. For
521: example if an ASN.1 type has an optional integer field
522: how does the encoding routine determine if the integer
523:
524:
525:
526: January 23, 1990
527:
528:
529:
530:
531:
532: - 9 -
533:
534:
535: is to be present or not? If it was implemented as a
536: pointer it could use a NULL (zero) pointer to mean that
537: the type was not present because NULL is guaranteed to
538: never occur as a legal pointer to a real object. But
539: all the possible values for integer could be legally
540: passed so instead for these types which are not
541: pointers and are optional a bit map is allocated in the
542: structure. Each non pointer optional type a bit from
543: the bit map is allocated.
544:
545: If that bit is set the corresponding type is present
546: and it is not present if the bit is not set. Each bit has a
547: #define generated for it. The bit map is merely an integer
548: field called "optionals" limiting maximum number of such
549: optionals to 32 on Sun machines, 16 on some others. (An
550: array of char as BSD fd_sets would have avoid all such lim-
551: its, not that this limit is expected to be exceeded very
552: often !) Like the SCTRL entry this entry merely serves to
553: specify where this field is so it can be test and set by the
554: encoding and decoding routines respectively.
555:
556: ANY and CONS_ANY
557: The C type corresponding to the entry is a PE pointer.
558: To conform with _p_e_p_y the tag and class of this entry
559: are ignored, which may or may not be the most sensible
560: thing. The CONS_ANY is a redundant symbol which means
561: the same thing but is not used. This should be clean
562: up and removed.
563:
564: INTEGER, BOOLEAN, BITSTRING, OCTETSTRING and OBJID
565: These are just as described in the first article. See
566: the ISODE manual to find out what they are allocated as
567: a C data type to implement them. The offset fields
568: says where to find this data type with in the current
569: structure.
570:
571: SET_START, SETOF_START, SEQ_START and SEQOF_START
572: These compound entries differ from the above in that
573: they group all the following entries together up to the
574: matching PE_END. The entries with OF in them
575: correspond to the ASN.1 types which have OF in them
576: e.g. SET OF. Allowing the OF items to have an arbi-
577: trary number of entries is excessive flexibility, they
578: can only have one type by the ASN.1 grammar rules. The
579: C data type corresponding to them is either a structure
580: if it is the first such type in the array or a pointer
581: to a structure is isn't. This complicates the process-
582: ing of these structures a little but not greatly. The
583: OF types differ one other important way, they may occur
584: zero, one or more times, with no upper bound. To cope
585: with this the C data type is a linked list structure.
586: The pointer to the data structure determines whether or
587: not there is another occurrence of the type, if it is
588: NULL there isn't. Thus each data structure has this
589:
590:
591:
592: January 23, 1990
593:
594:
595:
596:
597:
598: - 10 -
599:
600:
601: pointer to the next occurrence, the offset of this
602: pointer is placed in the PE_END field where it can con-
603: veniently be used to determine whether or not to make
604: another pass through the table entry.
605:
606: OBJECTWhen one type references another it generates an
607: OBJECT entry. This specifies the type number of the
608: type which is present in the 3rd field of the tpe
609: structure, pe_tag. The 2nd field still gives the
610: offset in the C data structure which specifies where
611: the user's data for that type is to be found. Usually
612: this a pointer to the C data structure for that type.
613:
614: T_NULLThis entry means the ASN.1 primative type NULL. It
615: doesn't have any body and consequently has no offset as
616: it cannot carry data directly. Only its absence or
617: presence can mean anything so if it is optional it sets
618: or clears a bit in the bit map as described earlier for
619: OPTL entry.
620:
621: T_OIDThis use to be used for Object Identifiers and now is
622: unused, it should be got rid.
623:
624: OBJIDThis corresponds to the Object Identifier ASN.1 type
625: primitive. It is implemented the same as other prima-
626: tive types like INTEGER and OCTET STRING.
627:
628: ETAG This entry gives the explicit tag of the following
629: entry. The usual fields which define class and tag are
630: the only ones which have meaning in this entry. By
631: concatenating successive ETAG entries it is possibly to
632: build up an limited number explicit tags, although this
633: hasn't been tested yet.
634:
635: IMP_OBJ
636: If a type has an implicit tag usually all we have to do
637: is set its tag and class appropriately in its entry.
638: This works for all but one important case, the refer-
639: ence of another type. This is messy because we can't
640: alter the definition of the type with out wrecking it
641: for the other uses. So what we do for encoding is
642: build the type normally and then afterward it is built
643: change its tag and class to be the values we want.
644: Similarly for decoding we match the tag and class up
645: and then decode the body of the type. We can't use a
646: OBJECT entry for this because among other reasons there
647: 3rd field is already to store the type number. (The
648: forth needs to be free to contain flags such as DEFAULT
649: and OPTIONAL) So a new entry type is used, IMP_OBJ, to
650: hold the tag and class. It must be followed by an
651: OBJECT entry which is used to handle the type as nor-
652: mal, the IMP_OBJ entry gives the tag and class to be
653: used. Like the ETAG entry the IMP_OBJ affects the
654: entry that follows it.
655:
656:
657:
658: January 23, 1990
659:
660:
661:
662:
663:
664: - 11 -
665:
666:
667: EXTOBJ and EXTMOD
668: These handle external type references. This is just
669: like a normal (internal?) type reference except we must
670: now specify which module as well as the type. Simi-
671: larly because there are no more free fields in the
672: OBJECT type we need two entries to hold all the infor-
673: mation we need. The EXTMOD occurs first and holds the
674: type number and the offset into the C data structure
675: and the flags, exactly as for an OBJECT entry. The
676: next entry, which must be an EXTMOD, contains a pointer
677: to the modtyp structure for its module. Like a normal
678: OBJECT entry to handle the case of an implicit tag an
679: IMP_OBJ entry would occur before these two entries
680: which gives the class and tag. Likewise it could have
681: an explicit tag in which the two entries would be pro-
682: ceeded by an ETAG entry.
683:
684: DFLT_F and DFLT_B
685: When a type has a default value, to handle decoding and
686: encoding properly you need to know its value. As there
687: is no space to store the value in most entries we allo-
688: cate a whole entry to specify the value. When encoding
689: it is convenient to have the default occur before the
690: entry it refers to. This allows a single check to han-
691: dle all the default encoding. All it has to do is
692: check whether it is the same as the default value and
693: if so not bother encoding the next type. On the other
694: hand when decoding it is more convenient to have the
695: entry after the one it refers to. In this case we need
696: to determine that it is missing before we use the
697: default value to determine the value to pass to the
698: user. To handle this we have entries of both types.
699: _D_F_L_T__F contains the default value for the following
700: entry (F = Front) and DFLT_B contains that for the
701: entry before it (B = Back). Consequently DFLT_F are
702: only used in the decoding tables and DFLT_B entries are
703: only used in the decoding (and printing tables).
704:
705: S-Types
706: These types are entries for the same ASN.1 type as the
707: entry type formed by removing the starting `S'. The
708: above forms would do to handle ASN.1 but we also have
709: to be compatible with the C data structures generated
710: by _p_o_s_y. The implementors decided to optimise the C
711: data structures generated a little means we have to
712: have all these S type entries. If a type was a single
713: field in most cases they produced a #define which elim-
714: inates the need to have a whole structure just for that
715: type. In all the places where this type is used the
716: field of the C structure is changed from a pointer to
717: field which holds the value directly in the structure.
718: See the ISODE reference given above for more details.
719:
720: We handle this by generating the same tables that would
721:
722:
723:
724: January 23, 1990
725:
726:
727:
728:
729:
730: - 12 -
731:
732:
733: be generated with out the optimisation, except the optimised
734: types the S-type of entries instead of the normal ones. For
735: example an optimised OCTET STRING would have the type field
736: of its entry as SOCTETSTRING instead of OCTETSTRING. The
737: only difference in how S type and its corresponding normal
738: are handle is how they find the C data structure for that
739: entry. That difference is that there is no indirection
740: through pointers.
741:
742: Flags field
743: Besides the encoding the class the pe_flags field also
744: contains a few possible flags. Mainly FL_OPTIONAL
745: which means the ASN.1 type corresponding to this flag
746: is OPTIONAL. Consequently when encoding it has to
747: determine if the type is present in the user data pos-
748: sibly using the bit map as described under the OPTL
749: entry. Likewise when decoding it may have to set a bit
750: in the bit map appropriately. The other flag at the
751: moment is FL_DEFAULT which means the entry corresponds
752: to an ASN.1 DEFAULT type. This bit is still needed as
753: not all types have DFLT_* entries implmented for them
754: at the moment. In particular compound value things
755: like SEQUENCE and SET can't have thier default value
756: specified. This is consistent with ISODE, if fact
757: implementing that may even break existing ISODE code.
758: This last flag FL_IMPLICIT is obsolete and not not used
759: any where.
760:
761:
762: _1._2. _W_a_l_k _t_h_r_o_u_g_h _o_f _p_e_p_s_y _l_i_b_r_a_r_y _r_o_u_t_i_n_e_s.
763:
764: Here we walk through all the pepsy library routines at
765: least briefly. If any new routines are added or a routine
766: changed this documentation is the most likely part that will
767: need changing. First we give some theory as to how the task
768: have have been brocken into routines then describe each
769: function in detail. We assume you are familiar with ISODE's
770: PE data structure manipulation routines. if not they are
771: documented in the ISODE manuals, Volume one, chapter 5,
772: "Encoding of Data-Structures" (It actually covers decoding
773: as well).
774:
775: _1._2._1. _O_v_e_r_v_i_e_w _o_f _p_e_p_s_y _l_i_b_r_a_r_y
776:
777: Each seperate task is put into a different file. So
778: all the encoding stuff is in _e_n_c._c, all the decoding stuff
779: is in _d_e_c._c, printing stuff in _p_r_n_t._c and freeing stuff in
780: _f_r_e._c. Actually it breaks down a little in practice, some
781: of the routines for moving around the tables are used in
782: both _e_n_c._c and _d_e_c._c for example. Probably they should
783: defined in _u_t_i_l._c so that linking one of the files from the
784: library doesn't force linking any other except _u_t_i_l._o.
785:
786: There is a common structure to each of the major files
787:
788:
789:
790: January 23, 1990
791:
792:
793:
794:
795:
796: - 13 -
797:
798:
799: as well. There is a main routine which the user calls to
800: obtain the services provided by that file's routines. As
801: all the files revolve about processing the table entries
802: their structure is based on running through the table
803: entries.
804:
805: We shall call each array of entries a table or an
806: object. There is a routine, usually with a name ending in
807: _obj, which is designed to process an object. For example
808: en_obj is the routine called to generated an encoded object.
809: Then there are routines to call on each compound type such
810: as en_seq for encode a SEQUENCE. Finally all the primitives
811: are handled by a one function that ends in _type. This lets
812: each routine concentrate on handling the features particular
813: to its type and call the appropriate routine to handle each
814: type it finds with in its compound type.
815:
816: Most of these table processing routines have just three
817: arguements: which are called parm, p, mod. The parm is char
818: * or char ** in the encoding and decoding routines respec-
819: tively. This points to the user's C structure that data to
820: be encoded is taken from when encoding. When decoding it is
821: the address of a pointer which is made to point the C struc-
822: ture filled with the decode data. The freeing, which is
823: based on the decoding routines, has a char ** while the
824: printing routines don't look at the user's data and so don't
825: have such a pointer. The p points to the current table
826: entry we are up to processing and the mod arguement points
827: to the modtyp structure for the current module we are pro-
828: cessing.
829:
830: All these processing routines return a PE type, which
831: is defined in ISODE's file _h/_p_s_a_p._h, and to return zero if
832: they have an error, but not always. In fact the error han-
833: dling is needs some work and has not been tested very well.
834: Generally it tries to print out the table entry where some-
835: thing went wrong and the name of the function it was in. It
836: then sometimes does an exit which may not be very pleasent
837: for the user.
838:
839: _1._2._2. _T_h_e _e_n_c_o_d_i_n_g _r_o_u_t_i_n_e_s - _e_n_c._c
840:
841: enc_fThis is the the routine made available to the user for
842: the encoding routines. It is fairly simple as it
843: leaves all the hard things up to other routines. All
844: it does is use the type number and modtyp pointer to
845: get a pointer to the table for encoding that type.
846: Then it calls the table or object encoding routine,
847: en_obj, on that object. It first does a consistency
848: check of making sure the first entry in the table is a
849: PE_start. Note that it returns an integer (OK or
850: NOTOK) instead of a PE pointer. This is to be consi-
851: tent with ISODE functions.
852:
853:
854:
855:
856: January 23, 1990
857:
858:
859:
860:
861:
862: - 14 -
863:
864:
865: en_objWe loop through the entries until we come to the end
866: of the table and then we return the PE we have built up
867: from the user's data which is pointed to by parm. In
868: looping through each entry we call the appropriate rou-
869: tine to encode its data. The default case is handled
870: by calling en_type which takes care of all the primi-
871: tive types.
872:
873: The macro NEXT_TPE sets its arguement to point to the
874: next type in the table, counting compound types as one type.
875: Thus if NEXT_TPE is called on a SET_START it will skip all
876: the entries up to and including the matching PE_END. As
877: many objects consist of one compound type and its components
878: the main loop will only be run through once. Even when the
879: object is not based on a compound type it will then consist
880: of one simple type which is processed by en_type, again
881: probably going through the loop only once. In fact the only
882: way it can go through the loop more than once is to process
883: entries that subsidary to the main type, e.g. ETAG entries
884: and things like that. To double check this is the case
885: there is some code that looks for the processing of more
886: than one data generating entry.
887:
888: Much of that testing could probably be eliminated with
889: no loss. Similarly prehaps the IMP_OBJ and ETAG could be
890: handled by the default action of calling en_type. As these
891: routines have evolved after many changes there are things
892: like that which really need to be looked at closely before
893: trying. The comment /*SUPRESS 288*/ means suppress warning
894: 288 to saber C debugging tool that we use.
895:
896: en_type
897: This is one of the longest functions as it has so many
898: cases to handle. It again is structure as a loop over
899: the types until PE_END but it actually returns as soon
900: as it has encoded the next type. We can now look at
901: the encoding of the primative ASN.1 types in detail.
902:
903: DFLT_FBecause we have arranged that for encoding tables,
904: that we precede the entry with a DFLT_F entry we can
905: neatly handle all the default cases. All we do is
906: check if the parameter passed in the user data, in
907: parm, is the same as the default value specified in the
908: DFLT_F entry. The function same performs this check.
909: If it is the same don't encode anything just return,
910: otherwise continue on and encode it.
911:
912: ETAG To handle explicit tags we merely allocate a PE with
913: the right tag and call en_etype to encode its contents,
914: which are in the following entries. The switch on the
915: pe_ucode field use to make a difference but now it is
916: meaningless and should be cleaned up.
917:
918: SEQ_START, SEQOF_START, SET_START, SETOF_START
919:
920:
921:
922: January 23, 1990
923:
924:
925:
926:
927:
928: - 15 -
929:
930:
931: We merely call the appropriate function handle them.
932: Note one _i_m_p_o_r_t_a_n_t difference in the way they are
933: called here from that in enc_obj, the parm arguement is
934: used as a base to index off and fetch a new pointer to
935: pass the next function. This seemly bizarre action is
936: quite straight forward when seen written as it is nor-
937: mally in C, "parm->offset". Where the field offset is
938: a pointer which has an offset from the start of the
939: structure of p->pe_ucode bytes.
940:
941: This is the magic of how we access all the different
942: fields of the C data structures with the one piece of code.
943: It is also prehaps the most critical dependency of the whole
944: system on the implementation of the C language. As the BGNU
945: C compiler supports this feature then it is compilerable on
946: most machines. But any porters should pay attention to this
947: to ensure that thier compiler is happy generating these
948: offsets and compiling these casts properly.
949:
950: The reason why this is different from the calls in
951: en_obj is that this is not the first compound type in the
952: table. The first and only the first does not have an offset
953: and does not need to be indirected through any pointers.
954: All the compound types inside this type will have as their
955: field a pointer which points to a structure. From here on
956: we shall say _i_n_d_i_r_e_c_t_i_o_n to mean this adding the pe_ucode
957: field to the pointer to the structure and using it to refer-
958: ence a pointer. Whether to use _i_n_d_i_r_e_c_t_i_o_n or not is very
959: important matter that really needs to be understood to
960: understand how the routines are structured.
961:
962: IMP_OBJ
963: Here we have to handle the case where we can encode the
964: object then have to change its tag and class after
965: encoding. At the end of this entry this is done very
966: simply by assigning the right values to the appropriate
967: fields after the object has been built. This means
968: that if the intermeadiate form is altered this piece of
969: code may have to be altered as well. There seems to be
970: no better way of handling this.
971:
972: The complication in handling this field is the handling
973: of all the possible types of object. If it is an external
974: object we have to perform a call to enc_f with all the right
975: arguements where a normal OBJECT, the last else branch,
976: requires a normal call to en_obj. Note the case of SOBJECT
977: is the same as OBJECT _e_x_c_e_p_t _t_h_e_r_e _i_s _n_o _i_n_d_i_r_e_c_t_i_o_n.
978:
979: SOBJECT and OBJECT
980: Here is the code that handles the two cases sperately.
981: It is exactly as in the IMP_OBJ case except seperated
982: out. Note the only difference between the two cases is
983: lack of indirection in the SOBJECT case.
984:
985:
986:
987:
988: January 23, 1990
989:
990:
991:
992:
993:
994: - 16 -
995:
996:
997: CHOICE_START
998: This is exactly as all other compound types, like
999: SEQ_START and OBJECT, we call the appropriate routine
1000: with indirection. From reading the ISODE manuals that
1001: the ASN.1 CHOICE type is handled by a structure of its
1002: own like the other compund types.
1003:
1004: EXTOBJ and SEXTOBJ
1005:
1006:
1007:
1008:
1009:
1010:
1011:
1012:
1013:
1014:
1015:
1016:
1017:
1018:
1019:
1020:
1021:
1022:
1023:
1024:
1025:
1026:
1027:
1028:
1029:
1030:
1031:
1032:
1033:
1034:
1035:
1036:
1037:
1038:
1039:
1040:
1041:
1042:
1043:
1044:
1045:
1046:
1047:
1048:
1049:
1050:
1051:
1052:
1053:
1054: January 23, 1990
1055:
1056:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.