![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to overview.ms 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 overview.ms CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / pepsy / doc |
1.1 root 1: .NH 1
2: Overview of pepsy system
3: .XS
4: Overview of pepsy system
5: .XE
6: .PP
7: This section describes how the various parts fit together to make
8: the system work.
9: The principle behind pepsy is fairly simple.
10: The \fBASN.1\fR is summarised as tables of integers.
11: These tables are read by driver routines which encode or decode
12: data to or from the internal format that \fBISODE\fR \fBOSI\fR implementation uses.
13: In \fBISODE\fR specific functions are generated for each \fBASN.1\fR type
14: defined in contrast the pepsy merely generates a new table of data which
15: is far far smaller.
16: .PP
17: As there is a great deal of effort invested in the \fBISODE\fR interface to the
18: encoding/decoding routines pepsy automatically provides macros which map
19: the original functions into the appropriate function call of a driver.
20: This allows existing posy using code to switch to the
21: pepsy system with \fBno changes\fR
22: to the code \fBprovided\fR no function pointers are used to the original
23: \fBISODE\fR functions.
24: Even when there are function pointers used the changes are very simple and
25: take only a few hours to implement.
26: .NH 2
27: Brief description of the use of the pepsy system.
28: .XS
29: A Brief description of the use of the pepsy system.
30: .XE
31: .NH 3
32: Outline of the files produced under the pepsy system.
33: .XS
34: Outline of the files produced under the pepsy system.
35: .XE
36: .PP
37: The pepsy system consists of a program called \fIposy\fR
38: which translates \fBASN.1\fR modules into a set of tables, called \fIposy\fR at the moment,
39: and library of driver routines, called \fIlibpepsy.a\fR.
40: Running this \fIposy\fR program on the \fBASN.1\fR file will produce several
41: files.
42: If the name of the \fBASN.1\fR module is \fBMODULE\fR the following files
43: are generated:
44: .I
45: .IP MODULE-types.h
46: .R
47: which contains \fBC\fR structure definitions.
48: The user of the library provides data as a linked list of
49: these \fBC\fR data structures and expects to receive data back as a similar
50: linked list.
51: These data structures are exactly the same as those produced by the original
52: \fBISODE\fR \fIposy\fR so that existing software written for the old \fIposy\fR
53: program needs no change.
54: For details on the \fBC\fR data structures types generated
55: see the documentation of the original \fIposy\fR program in
56: volume 4 Chapter 5 of the \fBISODE\fR manuals.
57: .I
58: .IP MODULE_tables.c
59: .R
60: This file contains the tables generated by the new \fIposy\fR program.
61: These tables consist of three parts, the first which contains the summary of
62: \fBASN.1\fR types.
63: Each type is summarised as an array of a primitive type, \fBstruct pte\fR,
64: for encoding and decoding, and \fBstruct ptpe\fR for printing.
65: As implied there is one array for each type for each of encoding, decoding and
66: printing as specified when \fIposy\fR is run.
67: The next part contains up to three tables of pointers to these arrays.
68: Each of the three different types of arrays, encoding, decoding and printing,
69: has its own table of pointers.
70: Finally there is the module type definition which contains contains pointers
71: to these tables and some other useful information about the module such as its
72: name.
73: This module type structure, which is \fBtypedef\fRed to \fBmodtyp\fR,
74: is the only piece of data which is global, all the
75: rest of the data is static and is only addressable via the \fBmodtyp\fR
76: data structure.
77: This provides a kind of object oriented approach to handling the tables.
78: Once you are passed a pointer to an \fBASN.1\fR's \fBmodtyp\fR structure
79: you can encode, decode and print any of its types by calling the appropriate
80: \fBlibpepsy.a\fR routine with its type number.
81: .I
82: .IP MODULE_pre_defs.h
83: .R
84: This file contains \fB#define\fRs symbol of each of the \fBASN.1\fR types
85: to its type number, which is used when calling a \fBlibpepsy.a\fR routine.
86: Each symbol is \fB_Ztype-nameMODULE\fR where \fItype-name\fR is the name of
87: the type with dashes (\fB-\fR) turned into underscores (\fB_\fR) and
88: \fIMODULE\fR is the name of the module.
89: For example of the \fBASN.1\fR universal type \fIGraphicString\fR would
90: have the \fB#define\fR symbol \fB_ZGraphicStringUNIV\fR.
91: The \fI_Z\fR is prepended to try to make the symbols unique.
92: This file also contains and extern declaration for the \fBmodtyp\fR data
93: for its module.
94: .I
95: .IP MODULE_defs.h
96: .R
97: This file contains macros for all the encoding, decoding and printing
98: functions that the \fIpepy\fR program would have for these \fBASN.1\fR
99: types.
100: This allows much of the code that uses the routines generated by running
101: the old \fIposy\fR program and taking its output and running \fIpepy\fR on
102: augmented \fBASN.1\fR output can be recompiled unchanged.
103: If the code used pointers to these functions it is necessary to change it
104: to pass around the type numbers instead and to call appropriately call
105: a \fBlibpepsy.a\fR library routine with the type number.
106: As pointers to the printing routines in ISODE are passed as arguments
107: a \fB#define\fR is provided to turn the argument into the pair of arguments,
108: type number and pointer to \fBmodtyp\fR structure, which are needed to allow
109: the diagnostic printing code to work with no change for
110: the current \fBISODE\fR stack.
111: This file also contains a \fB#include\fR of the \fIMODULE_pre_defs.h\fR file.
112: .PP
113: As the \fIMODULE-types.h\fR file \fB#include\fR's the \fIMODULE_defs.h\fR
114: file no further \fB#include\fRs need to be added to the files using the
115: encoding/decoding/printing functions.
116: This means that code written to use posy/pepy system may need no change at all
117: and the only effort required is to change the Makefile to use the pepsy
118: system.
119: If there is code changes required it would most likely be because function
120: pointers are used to reference the functions generated by posy.
121: If only the \fIpepy\fR system was used,
122: not posy then pepy,
123: with code placed inside action statements then quite a large amount of work
124: may be needed to change over to the new system, depending on how large and
125: complex the \fIpepy\fR module is.
126: .NH 3
127: Outline of the pepsy library.
128: .XS
129: Outline of the pepsy library.
130: .XE
131: .IP enc.c
132: This contains the routines that encode data from the \fBC\fR data structures
133: into \fBISODE\fR's \fBPElement\fR linked list data structure which it
134: uses for all presentation data.
135: The most important function to pepsy users is \fBenc_f\fR which called to
136: encode a particular type.
137: It is passed the type number and a pointer to \fBmodtyp\fR structure for that
138: module and then the rest of the arguments which are passed to an encode
139: function generated by \fIposy\fR/\fIpepy\fR system.
140: See the documentation in Volume 4, "The Applications Cookbook",
141: Section 6.4 called "Pepy Environment".
142: Most of these latter arguments are ignored, only \fBparm\fR and \fBpe\fR,
143: are used.
144: .PP
145: Contrary to what the \fBISODE\fR documentation says these ignored parameters
146: are hardly ever used by existing code.
147: We have not found a single case where used for encoding a named type,
148: which is all that the user can reference anyway,
149: so we don't see any problems with ignoring these other parameters.
150: Hopefully one day they can be thrown away entirely, until then they are
151: actually passed the the encoding function.
152: .PP
153: The rest of the functions are mostly recursive routines which encode a
154: particular type of table entry.
155: For example \fBSEQUENCE\fR is encoded by \fBen_seq\fR which may call itself
156: or others to encode the types from which it is built up.
157: The function \fBen_type\fR builds up a simple type and \fBen_obj\fR encodes
158: a new type (object) and so on with other functions.
159: There are a few utility routines in the file such as \fBsame\fR which
160: determines whether the value is the same as the default value also.
161: .IP dec.c
162: This file contains the decoding routines that translate
163: presentation data into \fBC\fR data structures defined in
164: the \fBMODULE-types.h\fR
165: is like \fIenc.c\fR.
166: It is very much like the file \fIenc.c\fR except the routines do the
167: reverse tasks
168: The routines are structured in a very similar way.
169: We have \fBdec_f\fR which is called by the user to decode a type
170: and like \fBenc_f\fR takes the same arguments as the decoding functions
171: generated by \fIposy\fR with two additions, the type number and a pointer
172: to the \fBmodtyp\fR structure for that module.
173: Likewise the other functions are very much like those of enc.c
174: .IP prnt.c
175: This file contains the routines that print the presentation data in a format
176: similar to that generated by \fIpepy\fR's printing functions.
177: It's main function \fBprnt_f\fR is takes the same arguments as the printing
178: function generated by \fIpepy\fR as well as the now familiar type number
179: and \fBmodtyp\fR pointer.
180: The functions are modeled on the decoding routines as it has similar job to.
181: The only difference is that instead of storing the decoded data
182: into a \fBC\fR data structure it is nicely printed out.
183: .IP fr.c
184: This file contains code to free the data structures
185: defined in \fBMODULE-types.h\fR.
186: Likewise if the \fB-f\fR flag is given when generating the types file it also
187: includes macros in the types file which replace the freeing functions generated
188: by ISODE's \fIposy\fR.
189: The function that the user calls us \fBfre_obj\fR which takes a pointer to
190: the data structure, its decoding table entry and a pointer
191: to the \fBmodtyp\fR structure for the module.
192: The freeing is based on the decoding routines except instead of decoding all
193: it does is free each part of the data structure, which might involve recursive
194: calls, then it frees the data structure at the end.
195: .IP util.c
196: This contains the utility routines used by more than one of the above files.
197: This is mostly diagnostic routines at the moment, more general routines could
198: be included in here.
199: If there is an error at the moment which it can't recover from it just prints
200: out a message on standard error and calls \fBexit\fR.
201: Not perfect and this is something that will need work.
202: .IP main.c
203: This contains code to perform a series of tests on the \fIpepsy\fR library
204: which is a useful check to see whether any of the routines has been broken
205: by any changes made.
206: It basically loops through a whole series of test cases.
207: Each test case is encoded from some built in test data and then decoded
208: and checked to see if the data has changed in the transfer.
209: If it is compiled with \fI-DPRNT=1\fR the encoded data is also printed
210: out to check the printing routines which generates a vast amount of output.
211: Finally the free routines are used to free the allocated data, although it
212: can not directly check the free routines to see if they work, it can be used
213: with a malloc tracing package to check that the routines work.
214: .IP test_table.h
215: This contains the test cases that \fImain.c\fR program runs.
216: Each entry in the table corresponds to a type.
217: One of the fields is count of how many times that type is to be tested
218: to try out the different possibly data values it might have.
219: .IP "pep.h and pepdefs.h"
220: These files contain the definition of types used for the tables that drive the
221: encoding/decoding/printing routines.
222: All the constants used in that table are defined here via \fB#define\fRs.
223: The \fBmodtyp\fR structure is defined in \fIpepdefs.h\fR.
224: .IP "t1.py and t2.py"
225: These are test \fBASN.1\fR modules that are used by \fImain.c\fR routines
226: to check the \fIpepsy\fR library.
227: The file \fIt1.py\fR contains the majority of different types with
228: a few of a different module provided in \fIt2.py\fR.
229: This allows the testing of the code for handling \fBASN.1\fR
230: external references, i.e. references to types defined in other, external,
231: modules.
232: .NH 3
233: New files in the pepy directory
234: .XS
235: New files in the pepy directory
236: .XE
237: .IP "etabs.c, dtabs.c and ptabs.c"
238: These files contain the code to generate the encoding/decoding/printing tables.
239: The main routine in \fIetabs.c\fR is \fBtenc_typ\fR which is called
240: on each \fBASN.1\fR type
241: to generate an array of entries which describe how to encode that type.
242: See the details section for more information about how the
243: table entries function.
244: Similarly \fIdtabs.c\fR contains the routine \fBtdec_typ\fR which is
245: called on each type to generate its decoding table entries.
246: Likewise \fBtprnt_typ\fR routine generates the arrays of table entries for
247: the printing tables.
248: This function is in \fIptabs.c\fR.
249: .IP "dfns.c"
250: This file contains miscellaneous string handling routines and hash table
251: routines that don't really belong anywhere else.
252: Some of the routines could be cleaned up in that they tend not to free memory
253: they use.
254: .IP mine.h
255: This file contains the definitions for the hash table(s) that are used to keep
256: track of the \fBASN.1\fR types.
257: This could probably be done with out a hash table, should anyone want to
258: clean this up, feel welcome.
259: The lookup function is in \fIdfns.c\fR.
260: .IP pass2.h
261: This file has most of the \fB#define\fRs for the table generating program.
262: Most of the prefixes and suffixes of function names and files names are defined
263: here so, hopefully, the names can be changed by merely changing the definition.
264: This contains most of the important definitions needed by the changes
265: to the \fIposy\fR program needed to generate tables.
266: .IP posy.h
267: This contains the definition of a symbol which is now needed outside of the
268: the main routine and the yacc file.
269: By putting it here we can include it any file that needs to know it with out
270: putting in any that doesn't need it and with out including all the other
271: definitions that occur in \fIpepy.h\fR.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.