Return to overview.ms CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / pepsy / doc

Annotation of 43BSDReno/contrib/isode-beta/pepsy/doc/overview.ms, revision 1.1

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.