home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource3 / 162_01 / readme.doc < prev    next >
Text File  |  1985-08-21  |  17KB  |  463 lines
  1.  
  2.  
  3.                 P R E F A C E  
  4.  
  5.  
  6.     Release of software like Mchip80 to the public domain is at least a
  7.    small boost to supportive commercial products that are discussed in the
  8.    documentation. Here is a list to acknowledge the vendors and the
  9.    products, plus some of the shortened names that might appear in the text.
  10.  
  11.     Vendor: The Software Toolworks    ['Toolworks']
  12.     Products:    C/80 compiler, C/80 Mathpak  ['Mathpak']
  13.    
  14.     Vendor: Microsoft
  15.     Products:    Macro80, m80.abs[.com], l80.abs[.com]
  16.    
  17.     Vendor: Heath/Zenith Computers    ['Heathkit']
  18.     Products:    H89 computer, HDOS system software
  19.    
  20.     Vendor: Advanced Micro Devices
  21.     Product:    AM9511 math processor chip  ['device']
  22.    
  23.     Vendor: Digital Research
  24.     Product:    CP/M system software
  25.    
  26.     Vendor: Zilog
  27.     Product:    Z80 microprocessor
  28.  
  29.     The C/80 user/programmer who chooses to use the Mchip80 software
  30.    package will in some cases need to make no changes to his pre-existing
  31.    programs that run with Toolworks C/80 Mathpak. There is no way to tell
  32.    the C/80 compiler that it is working with a substitute for its' Mathpak
  33.    cousin, and the C/80 compiler doesn't need to be told that dlibrary.rel
  34.    is substituting for about 90 percent of flibrary.rel. This degree of
  35.    compatibility is achieved at the assembly language level by having
  36.    Mchip80 use the same global labels as C/80 Mathpak, while performing
  37.    similarly defined tasks using very different methods.
  38.  
  39.     Considering the limited scope for naming labels in software packages
  40.    doing floating point and long arithmetic, assembly language labels such
  41.    as 'F.add' and 'L.div' must be accepted as generic, and not subject to
  42.    copyright, like single notes in a piece of music, or single words in a
  43.    novel. Beyond common usage of generic labels, no part of Mathpak is
  44.    reproduced. In some situations where Toolworks code is first and best,
  45.    where the AM9511 is not involved, Z80 or no Z80, there is no attempt at
  46.    replacement. The L80 linking loader is always commanded to search
  47.    flibrary, immediately after it's search of dlibrary, and the needed gem
  48.    of code in a Toolworks module will be included in the executable program.
  49.  
  50.     Observations such as "the C/80 compiler doesn't need to be told that
  51.    ...     ", occurring in this document, are not reviews of any product nor
  52.    updates to their documentation. These are opinions based on experiments
  53.    by one individual, who endorses all named products, the configurations in
  54.    which they are marketed, and the documentation that is part of those
  55.    products.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.                 P A R T   O N E
  73.  
  74.         Creating and Running an Executable Version of 'Demo1.c'
  75.  
  76.                  Your Inventory
  77.  
  78.     For hardware you need an AM9511 math processor chip installed in a
  79.    Heathkit H89 computer or equivalent. The Z80 microprocessor is essential.
  80.  
  81.     You need this software, named Mchip80, which requires that you also
  82.    have the following set of software development tools, in versions that
  83.    run with either the CP/M or HDOS operating systems.
  84.  
  85.     C/80 compiler and C/80 Mathpak, which are two separate
  86.     packages from the Software Toolworks.
  87.     Macro80 assembler package from Microsoft.
  88.    
  89.                  Preparations.
  90.  
  91.     If you need more detailed instructions for any of the following
  92.    operations, consult the documentation that comes with the related
  93.    product. Configure the C/80 compiler to accept floats and longs, and also
  94.    to generate Macro80 output. You must use the augmented utility, cconfigf,
  95.    from the Mathpak distribution disk for the float/long fix.
  96.  
  97.     Get the file 'fprintf.c' from the C/80 Mathpak disk, compile and
  98.    assemble to create 'fprintf.rel'. Including the float version of printf
  99.    in this exercise will prove the compatibility of the function ftoa() as
  100.    supplied with Mchip80.
  101.  
  102.     Read your hardware documentation and make a note of the two I/O
  103.    ports used for your AM9511 chip. Convert the port numbers to decimal, or
  104.    consult your C/80 documentation on hex or octal constants.
  105.  
  106.     Load your editor program and view the file 'demo1.c' from your back
  107.    up copy of the Mchip80 disk. Locate the line that reads
  108.  
  109.     "portd = 188; portc = 189; /* must be YOUR hardware ports */ ".
  110.  
  111.     If your hardware uses port 188 (decimal) for AM9511 data access, and
  112.    189 for commands and status, delete this line from your program.
  113.    Otherwise change the line to reflect your data and command ports, and the
  114.    host program will write your numbers over preset values in a library
  115.    module, before the AM9511 is used. Remember to use this convenient port
  116.    setting procedure in all your future C/80 programs using Mchip80 and the
  117.    AM9511, or at least until you simplify the source code and remake
  118.    dlibrary.
  119.  
  120.                 Compile/Assemble
  121.  
  122.     Use C/80 to compile your modified version of 'demo1.c', then use m80
  123.    from the Microsoft package to assemble 'demo1.mac' and create
  124.    'demo1.rel'.
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.                    The Link Operation
  136.  
  137.     Copy the following files to drive A: [or SY0:]
  138.  
  139.         L80.abs[.com]    (Microsoft)
  140.         Demo1.rel    (as created above)
  141.         Fprintf.rel    (as created above)
  142.         Dlibrary.rel    (Mchip80 software)
  143.         Flibrary.rel    (Toolworks Mathpak disk)
  144.         Clibrary.rel    (Toolworks C/80 disk)
  145.  
  146.     Enter the following command line to run the linker program:
  147.  
  148.     L80 demo1,fprintf,dlibrary/s,flibrary/s,clibrary/s,demo1/n/e
  149.    
  150.    to create the executable version of demo1. A comment at this point is
  151.    that if you omit dlibrary/s from the above command line, you have
  152.    standard usage of the Toolworks flibrary. The resultant program will run,
  153.    but the AM9511 will not get involved.
  154.  
  155.                    Execution
  156.  
  157.     Run the newly created program by entering 'demo1'. There will be no
  158.    prompt, so enter a floating point number such as '34.56'. The number you
  159.    entered will be echoed 15 times, in five lines and three columns, in a
  160.    variety of formats and precisions. Next enter a number in exponential
  161.    format, such as '23.45e-2'. The same pattern will appear on the console.
  162.    You have just checked out your AM9511 chip, it's hardware interface, the
  163.    Mchip80 versions of ftoa() and atof(), and most of the modules from
  164.    dlibrary.
  165.  
  166.  
  167.                 P A R T   T W O
  168.  
  169.                  Usage and Background.
  170.  
  171.  
  172.     If you feel that you are now ready to run a C/80 program that you
  173.    have used successfully with Mathpak, hold the action and read some more
  174.    before you proceed. Look at your C/80 source file where the global float
  175.    variables are declared. Are any of them initialized? For example:
  176.  
  177.     float    fnum = 5.32e-6;
  178.  
  179.     Then your program has to be changed before it will run properly with
  180.    Mchip80. The good news is that this is the only C/80 feature that is
  181.    cancelled by use of Mchip80, as far as is known. Do not initialize floats
  182.    when using Mchip80. Find the best way to change your program. Why is
  183.    initialization of floats de-implemented? Read on.
  184.  
  185.                   Which Float Format?
  186.  
  187.     Unfortunately there are two good float formats to discuss, while the
  188.    simple approach of Mchip80 requires that one be used, and the other not
  189.    only discarded, but also quarantined to prevent any errors or confusion.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.    The float formats of Toolworks Mathpak and the AM9511 math chip play in
  202.    ballparks of equal dimensions,
  203.  
  204.     Both formats occupy 32 bits of memory, and
  205.     Both yield six significant decimal digits.
  206.  
  207.     Internally, the formats have a one bit alignment discrepancy, which
  208.    produces the following differences in numeric range:
  209.  
  210.                  Decimal Float values
  211.           MAX. (pos. or neg.)       MIN. (pos. or neg.)
  212.    AM9511 format          9.2e18             2.7e-20
  213.    Toolworks format           10e38              10e-38
  214.  
  215.     The C/80 compiler knows only the Mathpak float format, which
  216.    apparently it never uses, except to initialize float variables. In
  217.    runtime situations involving floats or longs, a C/80 program will copy
  218.    the four bytes per variable to CPU registers or the stack, and then call
  219.    a Mathpak routine. When a Mchip80 routine replaces a Mathpak routine, it
  220.    starts by finding the four byte variables in either CPU registers or the
  221.