home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / bdsc-2 / l2-225.ark / LI.DOC < prev    next >
Text File  |  1988-05-21  |  9KB  |  257 lines
  1.  
  2. L225.DOC
  3. Using .REL files with version 2.2.5 of the L2 linker.
  4. July 1984
  5.  
  6.     When portions of a C program compiled with the BDS C compiler are
  7. to be implemented in assembly language, the present version of L2 provides
  8. an alternative to the use of CASM.  Formerly, one had to prepare a .CRL
  9. file by running CASM, then assembling the resulting preprocessed file.  Now
  10. the assembly language source file can be assembled with Microsoft's M80,
  11. and the .REL file produced by the assembler then linked directly with the
  12. other parts of the program.
  13.  
  14.     As an example, consider the following assembler source for a function
  15. which puts out a character, but substitutes a 'D' for any digit:
  16.  
  17.     ndput::
  18.         pop    d
  19.         pop    h
  20.         push    h
  21.         push    d
  22.         mov    a,l
  23.         cpi    '0'
  24.         jc    .1
  25.         cpi    '9'+1
  26.         jnc    .1
  27.         mvi    l,'D'
  28.     .1:    push    h
  29.         call    putchar##
  30.         pop    d
  31.         ret
  32.         end
  33.  
  34. Supposing the above text to be in a file NDPUT.MAC, then the procedure
  35. to assemble it and link it into a C program CND that calls this function is:
  36.  
  37.     A>m80 =ndput
  38.     A>l2 cnd ndput.rel
  39.  
  40. L2 determines that it is to load a .REL file instead of a .CRL file from
  41. the presence of the extension ".rel". L2 will also scan .REL file libraries
  42. that are put together using the library manager LIB.
  43.  
  44.     Here are some advantages of using M80 and the new version of L2 over
  45. the old way of incorporating assembly modules:
  46.  
  47.     (1) it's more convenient and straightforward
  48.     (2) assembler syntax is more flexible (labels can
  49.         be indented, '$' can be used)
  50.     (3) conditional assembly instructions and macros are
  51.         available
  52.     (4) Z80 source code can be used
  53.     (5) modules can have multiple entry points
  54.     (6) assembly modules can make external reference to
  55.         data in other assembly modules (not just callable
  56.         functions)
  57.     (7) an assembly module can request that a .REL file be
  58.         scanned to satisfy its external references, through
  59.         the use of the pseudo-operation '.request'
  60.     (8) it is easier for C modules and assembly modules to
  61.         make joint use of data in the external area of ram by
  62.         the use of dseg's (cf. below)
  63.     (9) external variables can be provided with initial values
  64.         (also by using dseg's)
  65.  
  66. On the other hand, the loading or scanning of .REL files by L2 is
  67. slightly slower than with .CRL files, and this version of L2 is larger by
  68. about 1 1/2k, making less ram available to hold the program being linked.
  69.  
  70.     M80 partions code into segments, viz. aseg's, cseg's, dseg's,
  71. and common.  Version 2.2.5 of L2 can deal with only two of these --
  72. cseg's and dseg's. The ordinary case is where code and data are in
  73. a cseg.  The little example given above was like this, although the
  74. 'cseg' directive was not given explicitly. A dseg is useful when a
  75. function written in assembler and a C program both need to refer
  76. to the same external variable.  Here is an example where a C program
  77. calls an assembly function to initialize a string to blanks:
  78.  
  79.     /* file tstblank.c */
  80.     #include <bdscio.h>
  81.     char blanks[41];
  82.     main()
  83.     {    fillblank();
  84.     }
  85.  
  86.    -----------------------------
  87.  
  88.         .comment    *
  89.     file fillblan.mac    *
  90.  
  91.     fillblank::
  92.         lxi    h,blanks
  93.         mvi    e,40
  94.         mvi    a,' '
  95.     .1:    mov    m,a
  96.         inx    h
  97.         dcr    e
  98.         jnz    .1
  99.         mvi    m,0
  100.         ret
  101.  
  102.         dseg
  103.         ds    6    ;6 bytes used in bdscio.h
  104.     blanks: ds 41
  105.  
  106.         end
  107.  
  108.    ----------------------------
  109.  
  110.     A>cc tstblank -e1000
  111.     A>m80 =fillblan
  112.     A>l2 tstblank fillblan.rel
  113.  
  114. In such a case, L2 equates the beginning of the dseg with the beginning
  115. of the external data area, which in this example was given as 1000H when
  116. the program was compiled. When dseg's are used, some address is ordinarily
  117. given using the compiler '-e' option, so that L2 can tell what offset
  118. to use for the data segment. When the C program was not compiled with the
  119. '-e' option, or when the main module is a .REL file, this address can be
  120. supplied to the linker using its '-e' option (new to this version):
  121.     A>cc tstblank
  122.     A>m80 =fillblan
  123.     A>l2 tstblank -e 1000 fillblan.rel
  124.  
  125.    So long as dseg's contain only labels and 'ds' or 'org' directives,
  126. their use will have no impact on the length of the code file produced
  127. by L2; however, if any real data is put in a dseg with 'db' or 'dw'
  128. directives, the code file will have to be longer to accommodate it.
  129. In the following example, the blank initialized string will be incorporated
  130. into the .COM file:
  131.  
  132.     /* file noth.c */
  133.     #include <bdscio.h>
  134.     char blanks[41];
  135.     main()
  136.     {    /* does nothing */
  137.     }
  138.  
  139.    -----------------------------
  140.  
  141.         .comment    *
  142.     file exdata.mac        *
  143.  
  144.         dseg
  145.         ds    6    ;6 bytes used in bdscio.h
  146.         rept    40
  147.         db    ' '
  148.         endm
  149.         db    0
  150.  
  151.         end
  152.  
  153.    ----------------------------
  154.  
  155.     A>cc noth -e1000
  156.     A>m80 =exdata
  157.     A>l2 noth exdata.rel
  158.  
  159. Like CLINK, this version of L2 has a '-z' option which prevents the
  160. zeroing of the external data area which ordinarily is done at the
  161. start of execution of a C program. It might seem that this option
  162. should have been used above -- i.e.:
  163.     A>l2 noth -z exdata.rel
  164. It is ok to do this, but not necessary, since L2 would assume that
  165. the '-z' option was intended in any case. (Why zero out the initialization
  166. data before it can be used?)
  167.  
  168.    In the above example, an external symbol 'blanks::' could have
  169. been put in the assembly file, but this could not make any difference
  170. to the way the program works, unless there were another assembly
  171. module referring to this symbol. This is because names associated
  172. with external data are lost in the process of compilation.
  173.  
  174.    According to M80, external symbols have at most seven significant
  175. characters, whereas in .CRL files produced by the BDS C compiler the
  176. name of a function can have up to eight significant characters. This
  177. difference might occasionally cause a problem. In the first example
  178. given in this document, the statement "call putchar##" gives rise to
  179. a reference to the external symbol 'PUTCHAR?', where the '?' is wild --
  180. it matches the end of another external symbol or any eighth character
  181. in another external symbol. So, if there happened to be a C function
  182. called 'putchart', e.g., this might be called instead of the intended
  183. function 'putchar'. L2 will not warn you about this. Nasty situation.
  184.  
  185.    In case there is an external data area defined through dseg's but
  186. not in a compiled main program in C, the linker will have to decide where
  187. the external data area ends according to what it finds in the dseg's.
  188. To make sure that it decides correctly, define a symbolic address at the
  189. end of the last data. E.g.
  190.  
  191.         dseg
  192.     mpointer:    ds    2
  193.     mbuffer:    ds    80h
  194.     dummy:
  195.         end
  196.  
  197. Without the symbol 'dummy', L2 would think the data area ended at the
  198. beginning of mbuffer, instead of at the end.
  199.  
  200.    Large programs that require a 2nd disk phase pass through the .CRL
  201. and .REL files and which also have initialization data defined in
  202. dseg's will sometimes require all code to be linked in before any
  203. dseg's are encountered, and it may also be necessary to arrange the data
  204. so that it will be loaded in order of increasing memory addresses.
  205.  
  206.  
  207.    Finally, here are some notes about the source files for version
  208. 2.2.5 of L2:
  209.  
  210.     L2.C    [perhaps called L225.C]
  211.     The main program, adapted from David Kirkland's version (which
  212.     came from Scott Layson's version).
  213.  
  214.     RDRL.MAC
  215.     A function to read an item from a .REL file bit stream.
  216.  
  217.     SPR.MAC
  218.     Assembly language version of the standard library function _spr,
  219.     which is called by printf. Needs about 2 pages less code than
  220.     the C version. (This and RDRL could fairly easily be converted
  221.     to .CSM files -- some symbol names with '.' or '_' might have
  222.     to be changed.)
  223.  
  224.     CHARIO.MAC
  225.     Assembly language version of Scott Layson's CHARIO.C. Needs about
  226.     2 pages less code than the C version.
  227.  
  228.     BDS.LIB
  229.     Include file for the .MAC functions. (This is the same as the
  230.     standard version of this file, but has a few extra symbols defined.)
  231.  
  232. There is a note on compilation and linking in L2.C. If you don't need to
  233. make a new L2.COM file, you can easily do so. Well, what I mean to say is
  234. that a version 2.2.5 of L2 can be most readily built up if a version 2.2.5
  235. of L2 is already available, in which case the procedure is:
  236.     A>m80 =rdrl
  237.     A>m80 =spr
  238.     A>m80 =chario
  239.     A>cc l2 -e5100
  240.     A>l2 l2 rdrl.rel spr.rel chario.rel
  241.  
  242. If the L2.COM [possibly called L225.OBJ] which accompanies this document is
  243. for some reason unusable, a version 2.2.5 could (I suppose) be brought up
  244. from the first two of these files and the original CHARIO.C by editing RDRL
  245. into .CSM format, and using CASM, ASM, and an older L2 or CLINK. The '-e'
  246. address would have to be adjusted upwards.
  247.  
  248. I do not know how, or whether, this version of L2 works with CDB. I have
  249. no specific reason to think that it wouldn't work, but I haven't tried it.
  250.  
  251. It is possible that .REL files produced by D.R.'s RMAC can be loaded by
  252. L2, but that's something else I haven't tried.
  253.  
  254.             Greg Lee
  255.             631B 10th Ave
  256.             Honolulu, HI 96816
  257.