PKTGEN$ 1R8 -- Procedure for Generating Packets

PKTGEN$ is a procedure which facilitates the generation of packets in MASM programs. It provides for cells of whole or partial word length, cell initialization, and overlapping cells. At the user's option, the packet may be drawn and the EQUF table listed.

          $INCLUDE  'MAXR$'         .
          $INCLUDE  'PKTGEN$'       .
[Label]   P$KTGEN,'options'   'pkt-name'[,xreg,breg,'length-tag'] ;
          'Name',length,'descr',value,alt-xreg,'more-descr',... ;
          'Name', ... ;
          ...

The only required subfields are 'options', 'pkt-name', 'name', and length. All subfields except xreg, breg, length, and value are strings within single quotes. As will be seen, 'name', length, and 'description' may be flagged by preceding them with an asterisk ('*') to denote certain special cases.

Label: optional label for generated table. If coded, will be included on all EQUFs and drawings. This label, followed by the letter 'L', will also be equated to the length of the packet, provided it is shorter than 12 characters.

D - Draw the packet. If the table is being generated (T option on P$KTGEN call), initialized data cells will be displayed to the left of the packet. If an item is longer than two words, only its first and last word will be shown.

F - If any fractional designators were used, display them above the packet drawing to show where they divide words.

M - Show multiply defined (overlayed) cells when drawing the packet.

(See also separate section on C option.)

G - Generate EQUFs for packet items.

L - List EQUF offsets & descriptions for packet items.

R - Generate and display EQUFs as numeric offsets relative to the start of the current location counter. Implies O option. Converted to "$" option if the highest offset would be > 077777. Overrides the use of the packet label, if any, when generating or displaying items.

$ - Same as R, but generate and display items as offsets to the current location ("$+nnn" format). Does not assume O option.

X - The label supplied on the P$KTGEN call is externally defined; use it in drawings and EQUFs, but don't generate either the label or any packet words.

T - Generate table (i.e., allocate words for packet items). PKTGEN$ will generate and show items as offsets to 0, to the label ("LABEL+nnn"), to the start of the current location counter (R option), or to the current location ($ option).

V - Show table value generation ($LIST when generating table words). Note that initial packet values are also displayed by the D option.

Z - Zero-fill the uninitialized portion of numeric items longer than two words (i.e., items without a string in the "value" field). This is done by explicitly generating a +0 for each word, which could increase the size of the resulting relocatable and absolute elements. The default mode, without the Z option, is to use the RES directive for those uninitialized words.

To space-fill an uninitialized item, code a blank string in its "value" field (' ').

N - An $UNLIST preceded this call; do a $LIST. This option provides for not listing the actual call to P$KTGEN, which can be lengthy and unwieldy; but just displaying the packet, tables, and EQUFs.

U - Do an $UNLIST at the end of this PKTGEN$ call. May be used with N if there are several consecutive calls to PKTGEN$; only a single $UNLIST will be needed before the first. The sequence to use is: $UNLIST; one or more P$KTGEN calls with the NU options; and a final P$KTGEN call with only the N option.

E - Eliminate extra spaces between columns of EQUF list (L option).

O - Show packet offsets & EQUFs as octal rather than decimal.

/ - If used before D, L, or V, eject page before corresponding display. If used at end of option string, eject page at end of call.

< - If M option used, don't insert additional divider line between multiple definitions of a packet word. This will result in a more compact drawing.

> - Same as <, but put an underscore ('_') in every other blank space of such multiple definition lines. This will separate the lines more clearly but, depending on the lengths of item names, may make the packet drawing more cluttered.

- - Use '-' for horizontal line character (default).

= - Use '=' for horizontal line character.

* - Use '*' for horizontal line character.

. - Use '.' for horizontal line character.

_ - Use '_' (underscore) for horizontal line character.

\ or | - Use '|' (vertical bar) for vertical line character (default).

: - Use ':' for vertical line character.

I - Use 'I' for vertical line character.

! - Use '!' for vertical line character.

# - Use '*' for vertical line character.

" - Use '.' for vertical line character.

'pkt-name'[,xreg,breg,'length-tag'] ;

'pkt-name': name, purpose, or description of packet, up to 40 characters.

xreg: optional index register to attach to EQUFs. Will appear in offset list. May be preceded with "*" to denote incrementation.

breg: optional Base Register to attach to EQUFs if packet is generated with $EXTEND directive in effect. If you expect to use the packet with different B-regs, omit breg or set it to 0 (B0); then you can include any desired B-regs on individual instructions without truncation errors.

'length-tag': a name to be equated to the length of the packet. May be needed if a label is not used and such a tag is desired.

'Name',length,'descr',value,alt-xreg,'more-descr',... ;

'Name': name of this table item. Will be used as a label when setting up EQUFs. Names longer than 11 characters may be truncated in the packet drawing, depending on the size of the cell.

If name is '$WORD', the next item, length, denotes a decrement to apply to the current packet word counter, usually -1. This in effect allows a redefinition of the previous packet word, thus accommodating overlayed items more flexibly than other methods.

'*' before name: Draw this item in the packet, but don't generate an EQUF for it. This can be used for "unused" or "reserved" cells. In such a case, the name may contain any characters, or none ('').

Length: 6,9,12,18/17,24,27,30 (bit length for partial words)

OR: -1,-2,-3,... (whole words). 36 (bits) allowed for single word.

Unless an "*" precedes the name field to designate an unused cell, partial word items will be allocated in the next legally addressable cell of that size in the current word or, if none remain, the first such cell in the next word. Will use H1/H2 for 18, XH1/XH2 for 17; for 24/27/30, will equate to whole word.

OR: 0 -- This is an EQU item which will be equated to the value subfield. Several of these could follow a cell of flag bits to define the possible values for this field and their descriptions.

'*' before length: Start new word for this item. Otherwise, items will be allocated in order as long as they fit in the current word.

Length may also be coded as a number in quotes. This signifies that you are supplying an absolute length that the packet is to be filled out to. Typically this will be an unused or variable part of the packet.

If an asterisk precedes a length of -1 (whole word), indirect addressing will be assumed for that item's EQUF and generation listing.

'descr': description of item. Up to about 60 characters, depending on how much else is included in the EQUF listing (maximum name length, label, xreg, offset digits, partial word designator).

'*' before description: Generate the EQUF for this item, but don't include it in the packet drawing unless the M option is used. This feature has the effect of delaying incrementation of the bit position within the current word, thus allowing the definition of overlayed items. To overlay a half-word with three sixths, for example, the field for the half word (the larger item) would go first and its description would be preceded by '*'. The fields for the sixth-words would follow without the '*', and bit incrementation would resume normally.

When overlaying, PKTGEN$ will check that smaller partial words fit exactly inside larger ones, but it will permit the special case of three sixths of a word overlaying two quarters if coded as follows:

                       'QWD1', 9, *'First overlayed Quarter-word' ;
                       'SWD1', 6,  'First Sixth-Word' ;
                       'QWD2', 9, *'Second overlayed Quarter-word' ;
                       'SWD2', 6,  'Second Sixth-Word' ;
                       'SWD3', 6,  'Third Sixth-Word' ;

...

value: actual value to place in the cell when generating the packet, whether a numeric value or a string in quotes. For an EQU item (length 0), value is always put in quotes; if a string, precede value with '*': '001', *'abc'.

alt-xreg: alternate index register for this item only. This subfield may be omitted if it is not used. If there is a default xreg and this item is to have none, code *0 for alt-xreg. As with xreg, this subfield may be preceded by an asterisk to denote incrementation.

'more-descr': additional description lines, if needed. These may begin in the preceding subfield if alt-xreg is not used.

An element called PKTGEN$/DEMO is included with the source for this utility; assemble and list it for a demonstration of PKTGEN$ usage.

Portions of a packet may be conditionally generated based on assembly time variables. The MASM directives $IF, $ELSE, $ELSF and $ENDF are used as name fields in the P$KTGEN call to set off these sections; and the conditions they test for are placed in the length field. Example:

TESTVAL1 EQU       0                 .
TESTVAL2 EQU       COND1++COND2      .
.
         P$KTGEN,'DGTVL'   'TEST TABLE' ;
         ;
         'ITEM1', -1, 'ITEM #1' ;
         'ITEM2', 18, 'ITEM #2' ;
         'ITEM3', 18, 'ITEM #3' ;
         '$IF', TESTVAL1 ;
         'ITEM4A', -1, 'ITEM #4A' ;
         '$ELSF', TESTVAL2 ;
         'ITEM4B', -1, 'ITEM #4B' ;
         '$ELSE' ;
         'ITEM4C', -1, 'ITEM #4C' ;
         '$ENDF' ;
         'ITEM5', -1, 'ITEM #5' ;
         ...

An option is provided for generating a different type of PKTGEN$ output.

C - Generate source output consisting of definitions for the packet items that can be input to the CPMD utility for individual dumping. For instance, for a packet item defined as

GOTEOF EQUF FLAGWD+5,,S4

PKTGEN$ will generate the image

LET GOTEOF:=S4$(@(FLAGWD+5))

If the P$KTGEN call does not have a label, PKTGEN$ will use default label 'PKG$ADR' for the LET statements. If this occurs, then after calling @CPMD you must first enter a statement to define the base address of the packet. Example: "LET PKG$ADR:=050103".

After the program using the packet is executed and @CPMD is invoked, @ADD the source output created by the PKTGEN$ C option call to establish the definitions. All partial word packet items will now be declared as variables and may be dumped by commands such as "VI GOTEOF" (decimal), "VO GOTEOF" (octal), VA (Fieldata), and VAS (ASCII).

Packet items that occupy one or more words will be declared as multi-word areas, as in:

LET SYMB$PKT:=MAINPKT+12,10

Such items are dumped with normal (non-"V") commands, as in "O SYMB$PKT" and will be dumped for their entire word length.

A variable for the entire packet will be declared by preceding the name with "$", truncating as needed to avoid exceeding 12 characters.

LET $MAINPKT:=MAINPKT,36

Then, entering "O $MAINPKT" will be the same as entering "O MAINPKT,36".

To create this C-option PKTGEN$ output, it is best to isolate the P$KTGEN call in a separate element; the presence of other code may cause errors, although this will not necessarily prevent the output from being written. If the P$KTGEN call is in an MSD (MASM Definition Element), for example, you must remove the $DEF directive. Add an $INCLUDE of PKTGEN$ if necessary, add the C option to the P$KTGEN call -- all other options besides O will be ignored -- and process the element using the following call format:

@MASM[,S] file.PKTELT,file.DEFELT . (S option lists output.)

The output element DEFELT contains the definitions to be @ADDed.