The C Users' Group Library 1994 August/wc-cdrom-cusersgrouplibrary-1994-08.iso/vol_100/162_01/readme.doc

Text File | 1985-08-21 | 17KB | 463 lines

                P R E F A C E


    Release of software like Mchip80 to the public domain is at least a
   small boost to supportive commercial products that are discussed in the
   documentation. Here is a list to acknowledge the vendors and the
   products, plus some of the shortened names that might appear in the text.

    Vendor: The Software Toolworks    ['Toolworks']
    Products:    C/80 compiler, C/80 Mathpak  ['Mathpak']

    Vendor: Microsoft
    Products:    Macro80, m80.abs[.com], l80.abs[.com]

    Vendor: Heath/Zenith Computers    ['Heathkit']
    Products:    H89 computer, HDOS system software

    Vendor: Advanced Micro Devices
    Product:    AM9511 math processor chip  ['device']

    Vendor: Digital Research
    Product:    CP/M system software

    Vendor: Zilog
    Product:    Z80 microprocessor

    The C/80 user/programmer who chooses to use the Mchip80 software
   package will in some cases need to make no changes to his pre-existing
   programs that run with Toolworks C/80 Mathpak. There is no way to tell
   the C/80 compiler that it is working with a substitute for its' Mathpak
   cousin, and the C/80 compiler doesn't need to be told that dlibrary.rel
   is substituting for about 90 percent of flibrary.rel. This degree of
   compatibility is achieved at the assembly language level by having
   Mchip80 use the same global labels as C/80 Mathpak, while performing
   similarly defined tasks using very different methods.

    Considering the limited scope for naming labels in software packages
   doing floating point and long arithmetic, assembly language labels such
   as 'F.add' and 'L.div' must be accepted as generic, and not subject to
   copyright, like single notes in a piece of music, or single words in a
   novel. Beyond common usage of generic labels, no part of Mathpak is
   reproduced. In some situations where Toolworks code is first and best,
   where the AM9511 is not involved, Z80 or no Z80, there is no attempt at
   replacement. The L80 linking loader is always commanded to search
   flibrary, immediately after it's search of dlibrary, and the needed gem
   of code in a Toolworks module will be included in the executable program.

    Observations such as "the C/80 compiler doesn't need to be told that
   ...     ", occurring in this document, are not reviews of any product nor
   updates to their documentation. These are opinions based on experiments
   by one individual, who endorses all named products, the configurations in
   which they are marketed, and the documentation that is part of those
   products.
















                P A R T   O N E

        Creating and Running an Executable Version of 'Demo1.c'

                 Your Inventory

    For hardware you need an AM9511 math processor chip installed in a
   Heathkit H89 computer or equivalent. The Z80 microprocessor is essential.

    You need this software, named Mchip80, which requires that you also
   have the following set of software development tools, in versions that
   run with either the CP/M or HDOS operating systems.

    C/80 compiler and C/80 Mathpak, which are two separate
    packages from the Software Toolworks.
    Macro80 assembler package from Microsoft.

                 Preparations.

    If you need more detailed instructions for any of the following
   operations, consult the documentation that comes with the related
   product. Configure the C/80 compiler to accept floats and longs, and also
   to generate Macro80 output. You must use the augmented utility, cconfigf,
   from the Mathpak distribution disk for the float/long fix.

    Get the file 'fprintf.c' from the C/80 Mathpak disk, compile and
   assemble to create 'fprintf.rel'. Including the float version of printf
   in this exercise will prove the compatibility of the function ftoa() as
   supplied with Mchip80.

    Read your hardware documentation and make a note of the two I/O
   ports used for your AM9511 chip. Convert the port numbers to decimal, or
   consult your C/80 documentation on hex or octal constants.

    Load your editor program and view the file 'demo1.c' from your back
   up copy of the Mchip80 disk. Locate the line that reads

    "portd = 188; portc = 189; /* must be YOUR hardware ports */ ".

    If your hardware uses port 188 (decimal) for AM9511 data access, and
   189 for commands and status, delete this line from your program.
   Otherwise change the line to reflect your data and command ports, and the
   host program will write your numbers over preset values in a library
   module, before the AM9511 is used. Remember to use this convenient port
   setting procedure in all your future C/80 programs using Mchip80 and the
   AM9511, or at least until you simplify the source code and remake
   dlibrary.

                Compile/Assemble

    Use C/80 to compile your modified version of 'demo1.c', then use m80
   from the Microsoft package to assemble 'demo1.mac' and create
   'demo1.rel'.










                   The Link Operation

    Copy the following files to drive A: [or SY0:]

        L80.abs[.com]    (Microsoft)
        Demo1.rel    (as created above)
        Fprintf.rel    (as created above)
        Dlibrary.rel    (Mchip80 software)
        Flibrary.rel    (Toolworks Mathpak disk)
        Clibrary.rel    (Toolworks C/80 disk)

    Enter the following command line to run the linker program:

    L80 demo1,fprintf,dlibrary/s,flibrary/s,clibrary/s,demo1/n/e

   to create the executable version of demo1. A comment at this point is
   that if you omit dlibrary/s from the above command line, you have
   standard usage of the Toolworks flibrary. The resultant program will run,
   but the AM9511 will not get involved.

                   Execution

    Run the newly created program by entering 'demo1'. There will be no
   prompt, so enter a floating point number such as '34.56'. The number you
   entered will be echoed 15 times, in five lines and three columns, in a
   variety of formats and precisions. Next enter a number in exponential
   format, such as '23.45e-2'. The same pattern will appear on the console.
   You have just checked out your AM9511 chip, it's hardware interface, the
   Mchip80 versions of ftoa() and atof(), and most of the modules from
   dlibrary.


                P A R T   T W O

                 Usage and Background.


    If you feel that you are now ready to run a C/80 program that you
   have used successfully with Mathpak, hold the action and read some more
   before you proceed. Look at your C/80 source file where the global float
   variables are declared. Are any of them initialized? For example:

    float    fnum = 5.32e-6;

    Then your program has to be changed before it will run properly with
   Mchip80. The good news is that this is the only C/80 feature that is
   cancelled by use of Mchip80, as far as is known. Do not initialize floats
   when using Mchip80. Find the best way to change your program. Why is
   initialization of floats de-implemented? Read on.

                  Which Float Format?

    Unfortunately there are two good float formats to discuss, while the
   simple approach of Mchip80 requires that one be used, and the other not
   only discarded, but also quarantined to prevent any errors or confusion.











   The float formats of Toolworks Mathpak and the AM9511 math chip play in
   ballparks of equal dimensions,

    Both formats occupy 32 bits of memory, and
    Both yield six significant decimal digits.

    Internally, the formats have a one bit alignment discrepancy, which
   produces the following differences in numeric range:

                 Decimal Float values
          MAX. (pos. or neg.)       MIN. (pos. or neg.)
   AM9511 format          9.2e18             2.7e-20
   Toolworks format           10e38              10e-38

    The C/80 compiler knows only the Mathpak float format, which
   apparently it never uses, except to initialize float variables. In
   runtime situations involving floats or longs, a C/80 program will copy
   the four bytes per variable to CPU registers or the stack, and then call
   a Mathpak routine. When a Mchip80 routine replaces a Mathpak routine, it
   starts by finding the four byte variables in either CPU registers or the
   stack. When it returns a variable, it copies four bytes from the device
   to CPU registers and exits, just like a Mathpak exit routine. The host
   program then usually moves the four bytes to RAM, not caring which float
   format was used on them.

    The 'atof()' function that is supplied with the Mchip80 software
   converts alpha-numeric strings, such as '4.5678e3', to 32 bit binary
   float variables in the AM9511 device format. When four byte float
   variables are passed to Mchip80 routines, they must either be a product
   of this 'atof()' function, or of type conversion from int or long, since
   those type conversions are done by the AM9511. When you write a program,
   you control the creation of each float variable, and it must not be from
   initialization by the C/80 compiler.

    There is no such quarantine requirement with long variables. You can
   allow the C/80 compiler to initialize them.

         Individual Styles and Applications Start Here.

    Mchip80 provides 'dlibrary.rel', which is ready to use in many
   applications, but Mchip80 does not exploit all the AM9511 potential.
   Mchip80 is an unfinished package, with development stopped at several
   points where individual preferences can start budding. Here are two
   situations where the AM9511 is not exploited in Mchip80:

    16 bit int arithmetic, including the modulo operation.
    C/80 does a fine job.

    Comprehensive error processing. Your options are
    wide open, and there is something in 'dlibrary.rel'
    that could be useful and convenient.

    The program 'demo2.c' shows a simple way for a program written in
   C/80 to detect the AM9511's warning when an out of range input was
   attempted before its last operation. This should lead you to reading of
   the source code file 'COMP32.MAC', where for the convenience of C/80
   programmers, the status byte returned by the AM9511 can be expanded into
   a group of 14 global integers, which can be treated as flags since they
   will always have values of either zero or one.









                  P A R T    T H R E E

          The List: Functions, Modules, Source Files.


    The source code of all modules in dlibrary is on the distribution
   disk of Mchip80. The remainder of this documentation is a list of those
   source files, with sub-lists of the features in each source file.

    The features fall into two groups, and for each file documented
   there are two sub-list headings. The first heading is "Compiler-call
   subroutines", and any features listed here may only be called from C/80
   compiler assembly coded output. These subroutines could be described as
   invisible to the C/80 programmer.

    The second sub-list heading is "Visible functions for C/80". The
   programmer uses these as regular C functions, and many of them conform to
   the C/80 Mathpak documentation, while some exist to provide access to
   features of the AM9511 math processor.

   FILE: DEQ.MAC (name means "Device Equates")
       Compiler-call subroutines:
       None
       Visible functions for C/80
       None
       Remarks:
       INCLUDED in all *.MAC files, and in some of the *.C files.

   FILE: ftoa.c (name means "Float to ASCII")
       Compiler-call subroutines:
       None
       Visible functions for C/80
       Ftoa() performs as described in the Toolworks Mathpak
       documentation, except that the number of digits after the decimal
       place is 20 or less, because the AM9511 float format is used.

   FILE: atof.c (name means "ASCII to Float")
       Compiler-call subroutines:
       None
       Visible functions for C/80
       Atof() performs as described in the Toolworks Mathpak
       documentation, except that an exponent greater than 18 (less than
       -20) will cause an unspecified error because the AM9511 float
       format is used.

   FILE: fmdx.c (name means "Float, multiply/divide by 'X'")
       Compiler-call subroutines:
       None
       Visible functions for C/80
       Fdten(fexp) and fmten(fexp) return the value of fexp ("float
       expression") divided by ten, or multiplied by ten. Both are used
       by previous functions in this library.













   FILE: logpow.c (name means "Logs, Powers and Misc.")
       Compiler-call subroutines:
       None
       Visible functions for C/80
       Sqrt(),exp(),pow(),pow10(),ln(),log() and fabs() perform as
       described in the Toolworks Mathpak documentation. The extra
       function invrt(fexp) returns the float value of one(1) divided by
       the float argument 'fexp'.

   FILE: ftrig.c (name means "Float, trigonometric")
       Compiler-call subroutines:
       None
       Visible functions for C/80
       Sin(), cos() and atan() perform as described in the Toolworks
       Mathpak documentation. Three more functions, tan(), asin() and
       acos() implement other commands in the AM9511 set, and return
       tangent, arc sine and arc cosine. The AM9511 can be commanded to
       place the float value of pi in its top of stack location, and the
       functions fdpi(f) and fmpi(f) divide or multiply their float
       arguments by pi.

   FILE: XLONG.MAC (name means "A single LONG operation(!!)")
       Compiler-call subroutines:
       Label "L.mod" is the entry point to the subroutine that returns
       the long modulo result to the C/80 generated assembly program.
       Visible functions for C/80
       None
       Remarks:
       The AM9511 does not have a single command for long modulo, and
       this routine gives it a string of commands to execute. Avoid this
       slow operation and preferably arrange for modulo operations to
       involve int types only.

   FILE: CONV32.MAC (name means "Conversions of longs and floats.")
       Compiler-call subroutines:
       Convert float variables to long type, and vice versa. C/80 will
       sometimes need the variables in the stack, other times in
       registers. The four operative labels are F..L, L..F, Bf.Bl and
       Bl.Bf .
       Visible functions for C/80
       None
       Remarks:
       Each of these need only a single command to the AM9511.

   FILE: COMP32.MAC (name means "Comparisons for float and long types")
       Compiler-call subroutines:
       Float compare ("cf.??" labels) and long compare ("cl.??" labels),
       as tabulated:
        greater than/equals to        cf.ge        cl.ge
        less than            cf.lt        cl.lt
        equals                cf.eq        cl.eq
        not equal to            cf.ne        cl.ne
        greater than            cf.gt        cl.gt
        less than/equals to        cf.le        cl.le











       Visible functions for C/80
       Xpand1(), - with no arguments, updates the fourteen global
       integers declared at the beginning of the source file, providing
       all diagnostic clues as to the wholesomeness of the last result
       given by the AM9511. All of these clues are from one byte of
       status returned by the AM9511. See the program demo2.c for a
       simple application.
       Remarks:
       Expect slow comparisons of floats and longs, and arrange for int
       comparisons when possible.

   FILE: EDCODE.MAC (name means "Essential Device CODE.")
       Compiler-call subroutines:
       The AM9511 performs primary float and long arithmetic quickly
       from single commands, after the variable data has been loaded.
       Assembly and macro code at the following labels couple the AM9511
       chip to C/80 calls as simply and conveniently as possible.
            F.neg        L.neg
            F.add        L.add
            F.sub        L.sub
            F.mul        L.mul
            F.div        L.div
       The AM9511 makes it simple and convenient to convert int type to
       float, and vice versa, and the following C/80 labels are
       honoured:
            I..F        Hi.Bf
            F..I        Bf.Hi
       The AM9511 does not convert char, int or unsigned types to long
       type (nor equivalent reverse functions), so the global labels
       "C..L", "U..L" and "I..L" are in EDCODE, but only to intercept
       the action and quickly pass it to a Toolworks flibrary module:
       Visible functions for C/80
       None
       Remarks:
       Conversions of longs back to int, char or unsigned are performed
       entirely in a Toolworks library module.
       Some code segments in EDCODE are used by earlier modules in
       dlibrary, therefore library module EDCODE must be linked into the
       last position in dlibrary.

    It is recommended that locations of modules in dlibrary be kept
   within their original groups, below, and that the groups be kept in the
   following order.

   Group One: atof.c, ftoa.c, and always last within this group, fmdx.c
   Group Two: logpow.c, ftrig.c
   Group Three: XLONG.MAC, CONV32.MAC, COMP32.MAC
   Last Location in dlibrary: EDCODE.MAC