home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / afixv100.zip / AFIX.DOC < prev    next >
Text File  |  1990-02-18  |  7KB  |  150 lines
  1. AFIX conversion tool, V1.0                 February 18, 1990
  2. Copyright 1990 Eric Isaacson.  All rights reserved.
  3.  
  4. Eric Isaacson
  5. 416 E. University Ave.
  6. Bloomington, IN 47401-4739
  7. (812)339-1811
  8.  
  9. The AFIX package consists of this AFIX.DOC file, the program 
  10. AFIX.COM, and the set of files with the .FIX extension, that
  11. are fed to the AFIX program.
  12.  
  13. I consider the legal status of the AFIX package to be the same 
  14. as that of the free-distribution parts of my A86 package: I 
  15. grant permission for anyone to copy the complete, unmodified 
  16. package and use it to try out A86.  There is no separate 
  17. registration fee for AFIX: if you register for A86, that covers 
  18. the usage of AFIX.  See the A86 package (V3.22 or later) for 
  19. details of my copying permissions/restrictions, including my 
  20. reservation of the right to inform specific parties that they 
  21. may not distribute some or all of my software.
  22.  
  23.  
  24. Overview of AFIX
  25.  
  26. In an effort to expand the test base for my A86 assembler, I 
  27. recently converted 61 assembly-language source files, published 
  28. by PC Magazine during the past 3 years.  These files were 
  29. written for various versions of the inferior but more widely-
  30. distributed MASM assembler by Microsoft.  I made the minimum 
  31. modifications necessary so that A86 would assemble the source 
  32. files directly to COM files that are functionally equivalent to 
  33. the files produced by MASM, LINK, and EXE2BIN. I would like to 
  34. make the modified files as widely available as the original MASM 
  35. files; but simply distributing them would violate their 
  36. copyright. 
  37.  
  38. AFIX was written to solve this legal problem.  For each modified 
  39. source file, I am publishing a special file with the extension 
  40. .FIX, that contains the specifications for modifying the 
  41. original PC Magazine source file.  The FIX files contain 
  42. absolutely nothing from the original .ASM files; so they are 
  43. entirely mine and I can copyright and distribute them as I 
  44. please. 
  45.  
  46. To run AFIX, you must place AFIX.COM, the original .ASM file, 
  47. and the corresponding .FIX file into your current directory, and 
  48. type AFIX followed by the file name to the DOS prompt.  AFIX 
  49. will verify that the .ASM file has the same size and 16-bit 
  50. checksum as the file I have.  If it does, AFIX will produce an 
  51. A86-compatible file, with the extension .8.  A comment line is 
  52. inserted at the top of the file, giving the A86 invocation line 
  53. that will assemble the program.  If the original file was more 
  54. than 64K in size, the output will be split into multiple files, 
  55. with names ending in _1, _2, etc. 
  56.  
  57. You do not need to run AFIX for each individual source file: 
  58. AFIX will accept wildcards in the program name.  In fact, if you 
  59. simply type AFIX to the DOS prompt, with no arguments, then 
  60. *.FIX is assumed, and AFIX will convert all programs for which a 
  61. .FIX file and the correct .ASM file both exist.  If you do this, 
  62. you might want to redirect standard output to a disk file, so 
  63. that you can review the status messages at the end: 
  64.  
  65.     AFIX >AFIX.LOG
  66.  
  67. If you get AFIX from a disk you have purchased from me or from a 
  68. shareware distribution house, the disk will not contain the .ASM 
  69. files you need-- they are copyrighted and cannot be sold.  
  70. You'll need to download them from a BBS, or from the utilities 
  71. forum of PCMagnet. 
  72.  
  73.  
  74. What AFIX Doesn't Do
  75.  
  76. AFIX is not a general-purpose MASM-to-A86 translation tool-- you 
  77. **cannot** apply it to files you have created.  AFIX is merely a 
  78. tool that allows me to communicate, in a machine-readable 
  79. format, the changes that I manually made to the copyrighted 
  80. source files.  It works only with the .FIX files that I have 
  81. supplied.  I do hope to write a MASM-to-A86 tool that will 
  82. assist you in converting any program; but there are other 
  83. improvements I would like to make to A86 first.  Meanwhile, this 
  84. present effort makes over 2 megabytes of A86 source code 
  85. publicly available.  That should be enough to keep you busy for 
  86. awhile! 
  87.  
  88.  
  89. Some Comments About the Converted Programs
  90.  
  91. This conversion effort has substantially improved both the 
  92. reliability and compatibility of A86.  I made several dozen 
  93. changes for the V3.22 release, to minimize the changes needed 
  94. for the successful conversion.  I added a new switch, +L8, that 
  95. changes assumptions made about untyped forward references, 
  96. reducing the number of B and W type-specifiers needed. The +D 
  97. switch already made the syntax of numeric constants MASM-
  98. compatible.  Thus, for maximum compatibility, the converted 
  99. files are assembled with the +DL8 switch setting. 
  100.  
  101. Chapter 12 of the A86 manual goes into detail about what needs
  102. to be done to convert files from MASM to A86.  All 61 source
  103. files assemble to complete .COM programs.  The changes made to
  104. these files fell into five categories: 
  105.  
  106. 1. Most of the changes comprised the addition of explicit 
  107.    segment-override operators to memory references.  MASM 
  108.    inserts such overrides behind the programmer's back, as 
  109.    controlled by the confusing and misunderstood ASSUME 
  110.    directive.  These overrides appear primarily in the
  111.    handlers for interrupts taken over by memory-resident
  112.    (TSR) programs.  For simple, non-resident COM programs,
  113.    all segment registers point to the program segment,
  114.    so that overrides aren't needed.
  115.  
  116. 2. Two of the 61 source files contained macros.  A86's
  117.    macro definition syntax is different, so the definitions
  118.    had to be converted.  These were the only two files
  119.    that did not retain MASM-compatibility after conversion.
  120.  
  121. 3. There were some forward-reference symbols whose type
  122.    needed to be specified, usually with the OFFSET operator.
  123.  
  124. 4. There were a few expressions involving forward references
  125.    that A86 couldn't handle.  The expressions were moved into
  126.    EQU directives placed below the symbols referenced.
  127.  
  128. 5. There were a couple of built-in mnemonics, such as WAIT, that 
  129.    doubled as user symbols.  MASM allows this; A86 doesn't.  The 
  130.    symbols were modified by appending an underscore character. 
  131.  
  132. I verified the correctness of the converted files by generating a 
  133. proprietary version of A86 that mimicked as closely as possible 
  134. the (mostly inferior) code generation of MASM.  This reduced the
  135. number of discrepancies in the resulting .COM files to a small
  136. enough number that I could manually verify their functional
  137. equivalency.  I did not attempt to test the execution of the
  138. programs themselves.
  139.  
  140. The total size of changes was minuscule in proportion to the 
  141. total size of the source files.  In fact, the one-line comments 
  142. appended to the top of each program totalled more bytes than the 
  143. code changes made!  Without those comments, the total changes 
  144. (moved bytes plus inserted bytes plus deleted bytes) for the 59 
  145. non-macro files were 3363 out of 2231783 bytes.  I can thus 
  146. claim that for COM programs not containing macros, A86 is 99.83% 
  147. MASM-compatible.  Twenty of the files required no changes
  148. whatever. 
  149.  
  150.