C/C++ Interactive Reference Guide/C-C++ Interactive Reference Guide.iso/c_ref/csource3/130_01/yaccrl.doc

Text File | 1985-03-11 | 8.1 KB | 192 lines

YACCRL.DOC
==========

**********************************************************
*        Yet Another C CRL generator         *
* This file contains information on using the "CCRL"     *
* program to convert COM files (generated by ASM or MAC) *
* into CRL format for use with the BDS C package.     *
* The original program was called "CRLADD", and it was     *
* written by:    Earl T. Cohen                 *
*        Cyclotomics, Inc.             *
*        2140 Shattuck Ave.             *
*        Berkeley, Ca. 94704             *
* Modifications and original documentation by:         *
*        Jack M. Wierda                 *
*        33 W. Naperville Rd. apt 9         *
*        Westmont, Illinois 60559         *
* This version (2) has been modified again to read a     *
* listing file for the additional information required     *
* by the CRL format (why not let the computer do the     *
* work!), by:                         *
*        Robert T. Pasky                 *
*        36 Wiswall Road                 *
*        Newton Centre, MA 02159             *
**********************************************************

This program is another version of the CCRL program written by
Earl T. Cohen, and modified by Jack M. Wierda.

The purpose of the program is to create a CRL-compatible file from
an existing <filename>.COM and <filename>.PRN (or .LST) files. The
<filename>.CRL  file  produced can then be manipulated using CLIB,
putting it into the desired library (presently, only one  function
is created at a time).

The audience for which this program is intended includes those who
wish to create or modify C functions written in assembly  language
but  do not have the MAC assembler for which "cmac.lib" performs a
similar function. In fact, in my somewhat biased opinion, the CCRL
method seems simpler and less artificial, if you can live with the
fact that only one function is allowed per source file (something,
by the way, which should not be difficult to surmount).

The command line is simply,

    CCRL <filename> [-p]

Where <filename> is the name of the .COM and .PRN file from  which
the  CRL file will be created. The optional "-p" switch causes the
program to display additional information, such as any lines  from
the listing file containing relocatable code.

Using ASM or MAC (or any other compatible assembler) and  LOAD,  a
.COM file should be created. At the same time, a listing file (for
ASM and MAC this is a .PRN type file) will be created.

The .COM file is simply read to obtain a copy of the object  code.
The  .PRN  file is a convenient way of finding the addresses which
will require reloction. The external function names and  the  size
of the object code is also obtained by reading the .PRN file.

In order for the program to "find" this information, a few special
characters are introduced into the .PRN file.  Since these symbols
are  placed  in the comment field, they can simply be added to the
source (.ASM) file when it is created. This may seem like a lot of
work, but it needs to be done only once. When any later changes or
bug fixes are made to the function,  the relocation information is
automatically updated, too.

The symbols are as follows:
    ;#<function name> - function to be created
    ;$<external required function name>
            - as many other functions as necessary
              and ended by:
    ;$        - denotes end of required function list
    ;'        - denotes internal relocation
    ;"        - denotes external (function) call
    ;#        - denotes end of function being created:
              a line whose address field is one more
              than the highest address of the function

The  above  symbols  are  listed in the order they should appear in
the source file.  That is, the function name first, followed by the
required function names  (one per line, as many as necessary).  The
end of this list is indicated by a null function name (i.e., a ";$"
followed by a new-line).  All this must appear  before  the  actual
function code. The code, flagged with internal and external symbols
where necessary, follows. Finally, the end of function (;#)  symbol
must  appear at the end of the assembly code to be included in this
function.

            -- Externals --

External function calls require special handling for the program to
handle them properly.  The CRL format requires a JMP instruction at
the beginning of the object code for each external function  called
by this function.  (Their addresses are  filled  in by  CLINK  once
their  actual locations are resolved.)  The calls made in your code
must actually refer to whichever one of these JMPs  corresponds  to
the  external function  (they will be assigned in the same order in
which they appear in the external required  function  list. )  even
even  though  the JMPs don't appear in the source code at all!  The
best way to do this is to equate the function name.

The example below should make things a bit clearer.

TPA    EQU    100H    ;Start of transient program area
    ORG    TPA
            ;#foobar -- function name
ABS    EQU    TPA+3    ;$abs
PRINTF    EQU    TPA+6    ;$printf
            ;$
    ...
    CALL    ABS    ;" This is an external function call
    ...
    LXI    H, MSG1    ;' This is an internal relocation
    PUSH    H
    CALL    PRINTF    ;" Another external function call
    ...
MSG1    DB    'Hello, there.'
    END        ;#

Note that the constant added to the TPA is 3 * <location  of  name
in e.r.f.n. list>, starting with 3 * 1 = 3.  I suggest you put the
e.r.f.n. definitions on the same line -- don't forget  the  final,
null definition!

The final symbol  (;#)  tells the program to stop reading the .PRN
file and additionally indicates the end address for the function.


            -- Relocation Symbols --

The internal and exteral relocation  symbols should appear on  any
line  containing  an address which would be changed as the code is
relocated by CLINK.  This means JMPs, CALLs, LHLDs and SHLDs. Also
LXIs and DWs only if their operands are addresses to be relocated.

You should be aware that the actual relocation is done to the  2nd
and  3rd bytes of the instruction on the line.  If you need to use
DWs or are using a Z-80 four-byte instruction  (e.g., LD IX,@addr)
this would cause the wrong bytes to be changed.  Therefore,  a "+"
or  "-"  sign may follow the relocation symbols to add or subtract
one from the address which is normally assumed. Use the minus sign
(;'-) for DWs, and plus sign (;'+) for four-byte instructions.

Once these additions are made to the source file,  simply assemble
it as you normally would;  the listing being sent to a disk  file.
Use LOAD to create a .COM file.  Run this program,  and bingo! ...
instant .CRL file!

--------------------------------------------------------------------

For those who wish to modify or simply understand this program, here
is some additional inside information.

The .PRN file is read a line at a time, scanned for a semi-colon (;),
and then the immediate next character is tested for whichever special
symbols are expected. In the case of function names, any white space
following the special symbol is skipped and the next 8 or fewer
characters are converted to upper case and the last character has its
high-order bit set to one as required by the CRL format. The name ends
with the first white space following the first real character so that
comments may be included on the same line.

When relocation symbols are found, the next character is checked for
"+" or "-", which sets up a fudge factor of +1 or -1, otherwise it's 0.
The line is scanned again for 4 hex digits starting at the LIST_COL
column. This column is the address field for the instruction on that line.
If your assembler listing has a different format, simply change the
LIST_COL definition in the program and recompile. If your assembler uses
split octal or some other format, some simple changes to the "readhx"
function will be required.

When the end symbol (;#) is found, the address field is used to
determine the size of the object file, which is used for several
purposes (the number of bytes to read from the .COM file, for one
thing).

Another change which may be necessary for other assemblers is the
definition of LIST_BEGIN. This is simply the column of the listing
file which begins the source text; it speeds up the scanning process
by skipping past the line number, address and object code columns.

If you would like to try adding multiple functions per file, most of the
routines which handle the output to CRL format should have little problem;
they were designed (by my predecessors) for the general case.


arting at the LIST_COL
column