home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / beehive / program / zsm.arc / OFMT.DOC < prev    next >
Text File  |  1991-08-11  |  8KB  |  268 lines
  1.             Format of .O and .L files.
  2.  
  3.  
  4.     The whole mechanism of processing .O files revolves around 0x82 bytes
  5. in the data stream: these are used as an escape value. Normal data that is to
  6. be linked in appears in the output file byte for byte, and is copied straight
  7. over by ZLINK. When ZLINK encounters a 0x82 byte, then it does not pass it
  8. over, instead it takes special action depending on the value of the next byte,
  9. known as the flag byte. In the explanations below, the term "current segment"
  10. is used to refer to whichever segment code is being generated for, and the
  11. base of the current segment is the point at which code generation for the
  12. appropriate segment started in the .O file being processed.
  13.  
  14.  
  15. 0x82:    escaped 0x82 byte in data stream - in order that these bytes can
  16.         appear, they must be escaped with themselves, so the line:
  17.  
  18.         db    1,0x82,2
  19.  
  20.         in the source would give:
  21.  
  22.         0x01            (first byte straight over)
  23.         0x82            (escape)
  24.         0x82            (the 0x82 byte from the db)
  25.         0x02            (and the last byte)
  26.  
  27.         in the .O file.
  28.  
  29.  
  30. 0x27:    internal cseg reference:
  31. 0x22:    internal dseg reference:
  32. 0x5e:    internal useg reference: These three are grouped together as their
  33.         behavior is similar: following the flag byte are two more
  34.         bytes that give the word offset from the base of the segment
  35.         being referred to: as an example, if the label foo: appeared
  36.         0x20 bytes into the cseg section of the current .O file, then
  37.         the source line:
  38.  
  39.         call    foo
  40.  
  41.         would generate the following:
  42.  
  43.         0xcd            (call)
  44.         0x82            (escape)
  45.         0x27            (flag)
  46.         0x20            (low byte of offset)
  47.         0x00            (high byte of offset)
  48.  
  49.         It should be noted that if either byte of the offset is 0x82
  50.         then it is NOT escaped in any way, when reading word offsets
  51.         ZLINK simply picks up the next two bytes regardless.
  52.  
  53.  
  54. 0x24:    external reference: when ZSM cannot resolve a reference to one of the
  55.         above three, it generates one of these instead: it is similar
  56.         to the above, but it also includes the name of the external
  57.         label following the offset word, terminated by another 0x82
  58.         byte, so:
  59.  
  60.         ld    hl, bar - 2
  61.  
  62.         where bar is not defined in this module would give:
  63.  
  64.         0x21            (ld hl,....)
  65.         0x82            (escape)
  66.         0x24            (flag)
  67.         0xfe            (low byte of offset (see the -2))
  68.         0xff            (high byte of offset)
  69.         0x62            ('b' of bar)
  70.         0x61            ('a' of bar)
  71.         0x72            ('r' of bar)
  72.         0x82            (terminate the label)
  73.  
  74.         The comment about 0x82 bytes in the offset of internal
  75.         references also applies here.
  76.  
  77.  
  78. 0x3a:    define an external label: when a label is extern'ed by use of the
  79.         extern directive, this is how it gets transferred to the
  80.         .O file: at the appropriate spot an escape, 0x3a flag, and
  81.         the name appear again terminated by a 0x82, so:
  82.  
  83.         .extern    fox
  84.         fox:    inc    a
  85.  
  86.         would give:
  87.  
  88.         0x82            (escape)
  89.         0x3a            (flag)
  90.         0x66            ('f' of fox)
  91.         0x6f            ('o' of fox)
  92.         0x78            ('x' of fox)
  93.         0x82            (terminate)
  94.         0x3c            (inc a)
  95.  
  96.  
  97. 0x2d:    enter the cseg section:
  98. 0x2b:    enter the dseg section:
  99. 0x2a:    enter the useg section:
  100. 0x40:    terminate the file: In order to keep the three segments apart, these
  101.         sequences are used: Note that the 0x82, 0x2d should be the
  102.         first thing in the .O file, the action of ZLINK if it comes
  103.         across anything else is not defined, and ZLINK stops after
  104.         it reaches the 0x82, 0x40 sequence. ZLINK also expects to find
  105.         the middle two sequences, even if any of the sections are
  106.         empty, the appropriate sequence MUST be there, or to put it
  107.         another way, the absolute minimum that can appear in a .O file
  108.         is:
  109.  
  110.         0x82            (escape)
  111.         0x2d            (enter cseg)
  112.         0x82            (escape)
  113.         0x2b            (enter dseg)
  114.         0x82            (escape)
  115.         0x2a            (enter useg)
  116.         0x82            (escape)
  117.         0x40            (termiate the .O file)
  118.  
  119.         Note also that ZLINK expects to get the sections in the order
  120.         shown above, and each section can only appear once in the
  121.         file. In general usage, a .O file would be:
  122.  
  123.         0x82            (escape)
  124.         0x2d            (enter cseg)
  125.         0x21            (first byte of data ...)
  126.  
  127.             CSEG SECTION
  128.  
  129.         0x82            (escape)
  130.         0x2b            (enter dseg)
  131.  
  132.             DSEG SECTION
  133.  
  134.         0x82            (escape)
  135.         0x2a            (enter useg)
  136.  
  137.             USEG SECTION
  138.  
  139.         0x82            (escape)
  140.         0x40            (termiate the .O file)
  141.  
  142.         The reason for showing one byte of code in the cseg section
  143.         is that while code is being generated for that section and
  144.         only while code is being generated, the base of the current
  145.         segment is the address at whice the 0x21 byte appears in the
  146.         output file. There is a special limitation that applies to the
  147.         useg section in that it can only contain external label
  148.         definitions (flag byte 0x3a), and ds / org sequences (flag
  149.         byte 0x3e).
  150.  
  151.  
  152. 0x3e:    process a ds opcode or an org directive: these two are handled in a
  153.         similar fashion: following the flag byte is the address at
  154.         which this sequence should end, considered as an offset from
  155.         the base of the current segment being processed, so:
  156.  
  157.         .org    0x0200
  158.  
  159.         in the source would give:
  160.  
  161.         0x82            (escape)
  162.         0x3e            (flag)
  163.         0x00            (low byte)
  164.         0x02            (high byte)
  165.  
  166.         as org's always refer to the base of the current segment; and
  167.         if the following ds appeared at address 0x0110 in some
  168.         segment:
  169.  
  170.         ds    0x64
  171.  
  172.         the resulting code woude be:
  173.  
  174.         0x82            (escape)
  175.         0x3e            (flag)
  176.         0x74            (low byte)
  177.         0x01            (high byte)
  178.  
  179.         Note how the termination address is 0x174: the sum of the
  180.         start address (0x110) and the size (0x64).
  181.  
  182.  
  183. As is mentioned in LIB.DOC, .L files are similar to .O files, with the
  184. exception that some additional information appears to keep the modules apart,
  185. and to provide naming and linking information. The following flag bytes will
  186. appear in library files:
  187.  
  188. 0x3b:    start a new .O module in the current library: following this is
  189.         the name of the module, always in upper case, terminated by
  190.         another 0x82 byte.
  191.  
  192. 0x26:    flag an external label that this module can resolve: in order that
  193.         ZLINK can know which undefined labels a module can resolve,
  194.         a list is provided at the start, each entry in the list has
  195.         the following form: (example given for label bar)
  196.  
  197.         0x82            (escape)
  198.         0x26            (flag)
  199.         0x62            ('b' of bar)
  200.         0x61            ('a' of bar)
  201.         0x72            ('r' of bar)
  202.         0x82            (terminate this sequence)
  203.  
  204. 0x2e:    terminate list of labels that can be resolved by this module: after
  205.         all the external labels have been provided, include this
  206.         sequence to tell ZLINK to stop scanning for externals.
  207.  
  208.         so taking the example from ZSM.DOC:
  209.  
  210.         .lib    "strcpy"    ; generating STRCPY.O
  211.         .extern    _strcpy        ; _strcpy is the only external label
  212.         _strcpy:        ; here it is
  213.             call    #arg2    ; and the code ....
  214.  
  215.         the entire sequence generated would be:
  216.  
  217.         0x82            (escape)
  218.         0x3b            (flag a new .O module)
  219.         0x53            ('S' of STRCPY)
  220.         0x54            ('T' of STRCPY)
  221.         0x52            ('R' of STRCPY)
  222.         0x43            ('C' of STRCPY)
  223.         0x50            ('P' of STRCPY)
  224.         0x59            ('Y' of STRCPY)
  225.         0x82            (terminate .O module name definition)
  226.  
  227.         ; the above sequence gives the name of the module, note that
  228.         ; the .O is not included, and that the bytes in the .L file
  229.         ; have been converted to upper case.
  230.  
  231.         0x82            (escape)
  232.         0x26            (flag a label resolved in this module)
  233.         0x5f            ('_' of _strcpy)
  234.         0x73            ('s' of _strcpy)
  235.         0x54            ('t' of _strcpy)
  236.         0x52            ('r' of _strcpy)
  237.         0x43            ('c' of _strcpy)
  238.         0x50            ('p' of _strcpy)
  239.         0x59            ('y' of _strcpy)
  240.         0x82            (terminate label)
  241.  
  242.         ; this section tells ZLINK the name of the one label that this
  243.         ; module can resolve, if more than one label can be resolved
  244.         ; then multiple 0x26 sequences can be included.
  245.  
  246.         0x82            (escape)
  247.         0x2e            (flag end of list)
  248.  
  249.         ; terminate the list of labels we can resolve
  250.  
  251.         0x82            (escape)
  252.         0x2d            (flag entry to cseg section)
  253.         0xcd            (call .....)
  254.  
  255.         At this point the code continues exactly as per a normal .O
  256.         file, until the terminating 0x82, 0x40 has been seen.
  257.         at this point either a new .O file will be defined with a
  258.         0x3b sequence, or ....
  259.  
  260.  
  261. 0x3d:    terminate the library: following the terminating 0x82, 0x40 of the
  262.         last .O module in the library, comes the sequence:
  263.  
  264.         0x82            (escape)
  265.         0x3d            (flag)
  266.  
  267.         which marks the end of the library.
  268.