home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource4 / 233_01 / msftsdr.doc < prev    next >
Encoding:
Text File  |  1987-07-01  |  6.6 KB  |  149 lines
  1. DOCUMENTATION FOR MSFTSDR.ASM
  2.  
  3. AUTHOR:  James W. Haefner
  4. DATE:    18 May 1987
  5. VERSION: 1.0
  6.  
  7. ----------------------------------------------------------------
  8. This document describes the purpose and use of two files 
  9. "MSFTSDR.ASM" and "MSCALLS.ASM", both of which are hereby 
  10. released to the public domain.
  11. ----------------------------------------------------------------
  12.  
  13. PURPOSE
  14.  
  15. The purpose of these 8086 assembly language subroutines and 
  16. macros is to call the transcendental functions contained in the 
  17. Microsoft (tm) (hereafter: MS) FORTRAN mathematics libraries 
  18. from a DataLight C (DLC) program.  The routines are specific to 
  19. the DLC compiler and will probably require alteration to
  20. interface with other compilers.  In theory, most C compilers 
  21. that produce an MS compatible link file (*.OBJ) can be 
  22. interfaced.  The primary reason for wanting to replace the DLC 
  23. math routines with those from MS is due to the fact that all of 
  24. the transcendentals in the DLC library are coded in C and are 
  25. extremely slow (see benchmarks below).  These calls are verified 
  26. to work for DLC version 3.01.
  27.  
  28. METHOD
  29.  
  30. During calls to floating point functions, DLC pushes doubles on 
  31. the stack from AX to DX, with AX having the MSB (most 
  32. significant byte) of the IEEE format and DX the LSB (least 
  33. significant byte).  DLC does not push the address of a double.  
  34. DLC expects doubles to be returned in the same manner.  
  35. Consistent with custom, DLC pushes the arguments in reverse 
  36. order.  MS FORTRAN calls subroutines with all arguments 
  37. referenced by name (address), not value.  These addresses are 
  38. pushed in the order in which they appear in the source code 
  39. call.  Values returned from FORTRAN functions are placed in 
  40. temporary arrays created by the calling program.  The MS 
  41. FORTRAN manual documents the method for interfacing with 
  42. assembly language routines.
  43.  
  44. MSFTSDR.ASM works by defining assembly language subroutines with 
  45. the same name as the DLC library names (e.g., sin, acos, etc).  
  46. These routines do nothing but create temporary storage for 
  47. FORTRAN return values, push the addresses (segment and offset) 
  48. of the C arguments, push the address of the temporary storage, 
  49. and copy the returned value from temporary storage to the 
  50. appropriate registers for return to DLC.
  51.  
  52. MSCALLS.ASM contains two macros to simplify the above process.  
  53. This file requires a DLC file of macros called MACROS.ASM.
  54.  
  55. USE
  56.  
  57. Compile MSFTSDR.ASM using MASM in the normal way: 
  58.  
  59. A>MASM MSFTSDR;  
  60.  
  61. If you wish to use the MS FORTRAN versions of the 
  62. transcendentals, then link them with the program according to 
  63. the DLC convention: 
  64.  
  65. A>LINK c+savag+msftsdr,savag,savag,nl+8087+fortran/m
  66.  
  67. where "8087" and "fortran" are the two required MS FORTRAN 
  68. libraries for the transcendentals.  "nl" and "c" are DLC 
  69. specific files.  You will receive a link warning message: 
  70. "Unresolved externals:  ENTGQQ in 8087.LIB(entx61)", or 
  71. something similar.  ENTGQQ is the first MS symbol name in the 
  72. OBJ file containing the FORTRAN main.  I can find it defined in 
  73. no MS library; apparently the symbol is defined in compiler or 
  74. runtime libraries (??).  In any case, the error has caused no 
  75. problems in my testing of the routines.
  76.  
  77. The use of the routines in a C program are identical to the use 
  78. of the supplied DLC functions and give identical, or more 
  79. accurate, results.  For example, the following is the C form of 
  80. the arctangent of a ratio of two arguments.
  81.  
  82. double z;
  83. z=atan2(1.0,0.5);
  84.  
  85. The result is 1.107149.  Note, there is an error in the DLC 
  86. manual, which claims that atan2(d1,d2) returns the arctangent of 
  87. d2/d1.  Instead, it returns arctan(d1/d2), which is consistent 
  88. with the FORTRAN definition.
  89.  
  90. In addition to all of the transcendental and power functions 
  91. available in DLC, I have added an integer power function since 
  92. it is available in the MS library.  This function is called
  93. "ipow", and must be declared to return a double.  I recommend 
  94. you add this definition to the DLC file "MATH.H".  Ipow raises a 
  95. double base to a long integer power.  For example, 
  96. "z=ipow(2.0,3L);" returns 8.0 as a double. 
  97.  
  98. BENCHMARKS
  99.  
  100. Below are sizes, timings, and accuracy for the Savage floating point 
  101. benchmark published in Dr. Dobbs' Journal August 1984 using the 
  102. DLC and MS libraries, respectively.  For comparison, I give the 
  103. results for a similar test written entirely in MS FORTRAN.  
  104. Timings are means of three stopwatch times; the hardware used 
  105. was an 80286/80287 S-100 system with the math coprocessor 
  106. running at approximately 5MHz.  The correct answer is 
  107. 2501.0000000000000. 
  108.  
  109. LIBRARY      EXE SIZE   TIME(SEC)   RESULT
  110.  
  111. DLC          20288      29.80       2501.0000008425761
  112. MS           22456       5.22       2501.0000000015812
  113. MSFORTRAN    31K         4.97       2501.0000000015812
  114.  
  115. The MS libraries are approximately 6 times faster and over 2 
  116. orders of magnitude more accurate.  The additional 2K bytes of
  117. EXE file seem a small price to pay.  The 5% speed overhead of the
  118. additional calls to the transcendentals is also tolerable, given 
  119. the niceties of coding in C versus FORTRAN.
  120.  
  121. DLC claims it supports the generation of "inline 8087 or 80287 
  122. instructions" using the "-f" option to DLC1 (version 3.01 manual 
  123. page 17).  On my version and hardware, this generated a fatal 
  124. error in the compiler.  Not an error message complaining of C 
  125. syntax errors, an actual "DLC bug 8284" message from the DLC2 
  126. pass and return to DOS.  Thus, I was unable to perform the 
  127. benchmarks with this compiler option.  I have also not repeated 
  128. the exercise using the DLC Optimizer.
  129.  
  130. BUGS, LIMITATIONS, AND CAVEATS
  131.  
  132. 1.    As written, the functions assume the DLC compiler, version 3.01.
  133. 2.  Tested only with the MS 8087.LIB library, should work with the 
  134.     8087 emulating libraries as well.  That may require linking 
  135.     other MS FORTRAN files or libraries.
  136. 3.  Verified for MS FORTRAN version 3.2 only.
  137. 4.  As written, the functions assume the user is dealing with 
  138.     doubles, as DLC converts all floats to double.  The single 
  139.     precision versions of the MS FORTRAN functions are also in the 
  140.     libraries and in principle could be accessed from DLC.  This 
  141.     would be valuable if speed were more important than accuracy 
  142.     and if an 8087 was not available.  If an 8087 is available, 
  143.     there is insufficient speed increase in single precision to 
  144.     justify the reduction in accuracy.
  145. 5.  There is an apparently inconsequential "unresolved external" warning 
  146.     from the linker.
  147. 6.  Verified for DLC small model only; code in place to potentially
  148.     handle large models.
  149.