home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d183 / fixfd.lha / FixFd / FixFd.docs < prev    next >
Text File  |  1989-02-26  |  7KB  |  234 lines
  1.  
  2.  FixFD v1.0
  3.  User Manual
  4.  
  5. Copyright (C) 1988 by Peter Wyspianski
  6.  
  7. [31 Dec 88]
  8.  
  9.  
  10. ----------------------
  11. Please Read The Manual
  12. ----------------------
  13.  
  14. The FixFD utility is not complicated, but please take a couple minutes to
  15. read through this manual before you try it.  Thanks!
  16.  
  17.  
  18. --------
  19. Abstract
  20. --------
  21.  
  22. FixFD is a utility for the Amiga series of computers that reads an '.FD'
  23. file to produce an assembler 'include' file.
  24.  
  25.  
  26. -----------
  27. Legal Stuff
  28. -----------
  29.  
  30. Amiga is a trademark of Commodore-Amiga, Inc.
  31. The author is in no way connected with Commodore-Amiga, Inc.
  32.  
  33. The FixFD utility package, consisting of the program and documentation file,
  34. is copyrighted.  Permission is granted for NON-COMMERCIAL distribution of
  35. UNMODIFIED copies of the entire package.  All other rights are reserved. 
  36. Distribution of separate parts of the package, or of modified copies is
  37. specifically prohibited.  Failure to abide by these rules may result in a
  38. fine, and/or jail term.  Additionally you may get a guilty conscience and
  39. I certainly won't visit you.  Pass the word, pass this program!
  40.  
  41.  
  42. -----------------------
  43. Who Needs This Utility?
  44. -----------------------
  45.  
  46. If you are an Amiga assembly language programmer (or want to be), then read 
  47. on.  Otherwise, this utility is NOT for you (sorry)!
  48.  
  49.  
  50. -----------
  51. The Problem
  52. -----------
  53.  
  54. When you're programming in assembly language, the most common way to define 
  55. a 'Library Vector Offset' (LVO) is to use the XLIB macro like so:
  56.  
  57.     XLIB    Open    ; DOS.Library
  58.     XLIB    Close    ; DOS.Library
  59.     
  60. where the 'XLIB' macro looks something like this:
  61.  
  62. XLIB    macro        ; <routine name>
  63.     xref    _LVO\1
  64.     endm
  65.  
  66. so by the time the assembler has sorted out those first couple of
  67. definitions 
  68. here is what you got:
  69.  
  70.     xref    _LVOOpen
  71.     xref    _LVOClose
  72.     
  73. Later on in the program you may want to call the 'Open' routine:
  74.  
  75.     move.l    DOSBase,a6
  76.     jsr    _LVOOpen(a6)
  77.  
  78. Of course most of us use a macro for those lines.  But here is a question -
  79. just where IS the actual value of the symbol '_LVOOpen' defined?  It is
  80. defined in the scanned library 'Amiga.Lib'!
  81.  
  82. The problem is that Amiga.Lib is about 80K bytes long, and contains a LOT of
  83. things besides the _LVO definitions.  Having the _LVOs defined in Amiga.Lib
  84. requires that you ALWAYS link your code with Amiga.Lib.  This effectively
  85. neutralizes assemblers that produce loadable object files.  It also makes 
  86. for some very long link times.
  87.  
  88.  
  89. ------------
  90. The Solution
  91. ------------
  92.  
  93. The ideal solution to the problem of having the LVOs defined in Amiga.Lib 
  94. is to just equate them to their proper values:
  95.  
  96. _LVOOpen    EQU    -30
  97. _LVOClose    EQU    -36
  98.  
  99. Now you don't have to link with Amiga.Lib and the assembler will probably 
  100. get done a bit sooner as it doesn't have to do as much work.  To get these
  101. equates you simply use FixFD!
  102.  
  103.  
  104. ------------
  105. What It Does
  106. ------------
  107.  
  108. The Extras disk includes a drawer called 'FDx.x' (where x.x is the operating
  109. system revision, currently '1.3'.  Within this drawer are a number of files
  110. whose names end with '.FD'.  These '.FD' files all have a standard format. 
  111. They completely define all the LVOs within a particular library.  The '.FD'
  112. files are updated with every new revision of the operating system.
  113.  
  114. FixFD simply reads an '.FD' format file and cranks out a file that your
  115. assembler can read (using 'INCLUDE').  And thats all there is to it!
  116.  
  117. You have a lot of choices when it comes to putting the resultant 'include'
  118. files to use.  Adding a bunch of 'INCLUDE' statements is one possibility. 
  119. Or you could merge them into one big include file.  If your assembler
  120. supports 'preassembled symbols' then you can preassemble the LVO file(s)
  121. for lightning assembly speed!
  122.  
  123. I like to have all the LVOs in one big file.  That way I can use the cut-
  124. and-paste features of my text editor to put just the LVOs I need right into
  125. the assembly file I'm working on.
  126.  
  127. There is probably a utility somewhere out there that does exactly the same
  128. thing as FixFD.  Too bad I haven't seen it (yet)!  So here is my contribution. 
  129. Incidentally, it would have been far quicker to write this in something like
  130. BASIC, but I simply wanted some practice at working with DOS files from
  131. assembly.
  132.  
  133.  
  134. -----------
  135. Using FixFD
  136. -----------
  137.  
  138. From the CLI (Command Line Interpreter) or Shell type:
  139.  
  140. >fixfc source_file dest_file
  141.  
  142. where 'source_file' is the name of the '.FD' file you want to read
  143.  and   'dest_file'  is the name of the new file you want to make
  144.  
  145. You can use an asterix ('*') for the dest file, to send output to the CLI
  146. window.  In that case the fancy line number display is suppressed so it 
  147. doesn't tangle up the output.
  148.  
  149. FixFD can be aborted in the usual way (ctrl-c).  And if you forget one of 
  150. the file names (or use '?'), you get a little blurb reminding you what to do.
  151.  
  152. It DOESN'T work from WorkBench so don't try it (crashes the system).  I could
  153. make it WorkBench compatible but why bother?
  154.  
  155. Thats about it.  I sure hope you like it!
  156.  
  157.  
  158. --------------------
  159. So How Does It Work?
  160. --------------------
  161.  
  162. [This section is for the curious; it may be safely skipped by others.]
  163.  
  164.  
  165. FixFD scans each line of the input file looking for one of the following:
  166.  
  167. ##bias xx
  168.  
  169. Where xx is a decimal number 0-65535.  Sets the base from which subsequent 
  170. LVOs are calculated.  Defaults to zero.  The usual value is 30.
  171.  
  172. <LVO name> <whatever>
  173.  
  174. An LVO name is any line that starts with one of these characters:
  175.  
  176.     a-z, A-Z, period ('.'), underline ('_')
  177.     
  178. When an LVO name is found, the line is scaned for an open paren ('(') or 
  179. space.  If one is found, the line is chopped from that point on.  In any 
  180. case, the LVO name is written to the dest file with the prefix '_LVO'.  
  181. Following the name is a tab, the word 'equ', another tab, and the decimal
  182. offset of the LVO.
  183.  
  184. All other lines (including blank lines, and lines beginning with ';' or '*')
  185. are ignored.
  186.  
  187.  
  188. -------------------------
  189. Send Postcards Not Money!
  190. -------------------------
  191.  
  192. The Author enjoys getting mail.  Especially picture post cards.  If you like
  193. this program, hate it, or want to see some improvements, please send me a
  194. post card:
  195.  
  196. Peter Wyspianski
  197. 5-10A Brock Cres
  198. Kingston, Ont
  199. CANADA  K7K 5K6
  200.  
  201. Don't bother sending money.  However, all offers of employment will be
  202. seriously considered.
  203.  
  204.  
  205. -----------------
  206. End of the Manual
  207. -----------------
  208.  
  209. Congradulations on having read this far.  Current research indicates that
  210. you are one of only 9.23% of users who bother to read the manual.
  211.  
  212.  
  213. -------------------------
  214. Technical Details/Credits
  215. -------------------------
  216.  
  217. FixFD is written in M68000 Assembly Language.  Total development time was 
  218. about eight hours, including writing this doc file.  I had to write most of
  219. the DOS file code from scratch.  I already had the decimal conversion and
  220. formatting routines.
  221.  
  222. Some of the better products used in the development of this utility include:
  223.  
  224. CAPE 68010 Assembler (Inovatronics)
  225. BLink (Software Distillery)
  226. Uedit (Rick Stiles)
  227.  
  228. (The preceeding was an unsolicited endorsement).
  229.  
  230. Special Thanks: Sharon W.
  231.  
  232.  
  233.  
  234.