home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / proasm / readme.txt < prev    next >
Text File  |  1996-04-25  |  20KB  |  456 lines
  1. Welcome to the shareware release of ProAsm 1.74
  2.  
  3.  
  4.  
  5.  
  6.                                   ProAsm
  7.                    Copyright © 1989-1996 by Daniel Weber
  8.                             ProAsm is Shareware
  9.  
  10.  
  11.  
  12.  
  13.  
  14. 1.74 Release Notes:
  15. ProAsm(TM) Software
  16.  
  17. These notes address the following topics:
  18.   - The ProAsm Assembler
  19.   - ASX - The ProAsm User Interface
  20.   - ProOpts - The ProAsm Configuration Program
  21.   - Support Libraries
  22.   - ProAsm Software Overview
  23.   - Documentation
  24.   - Author
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.                            The ProAsm Assembler
  33.                            --------------------
  34.  
  35. The  ProAsm  assembler  is a traditional two pass assembler that emits code
  36. for  the  entire  Motorola  MC68000  Family.  ProAsm is a high performance,
  37. full-featured   assembler   with   enough  powerful  features  to  make  it
  38. appropriate for all assembly tasks.  It produces native 68xxx code, and has
  39. special  directives to enable the selection of the target processor and the
  40. appropriate  code  optimization  for  that processor.  ProAsm supports both
  41. addressing  mode  syntaxes  as defined by Motorola.  Programmers find these
  42. capabilities  of  the  new  syntax  mode  particularly  useful for handling
  43. advanced data structures common to sophisticated application and high level
  44. languages.
  45.  
  46. The  output  produced  by  ProAsm  is  either  an  executable file that can
  47. directly  be  run  under AmigaDOS or the Workbench, object modules that are
  48. compatible with the Amiga standard linker and BLINK (the replacement linker
  49. from  'The  Software  Distillery'),  binary  output  for ROM-able code (for
  50. example),  pre-assembled  files,  or the Motorola S-record format.  Besides
  51. the  normal  output files, ProAsm can also generate four types of auxiliary
  52. output  files which reflect the results of the assembly process:  the error
  53. file  and  the  equate  file,  the  source  listing and the cross-reference
  54. listing.
  55.  
  56. ProAsm  has  a  tremendous number of switchable optimizations including the
  57. multipass  facility to gain an even more optimized code.  ProAsm also has a
  58. very  rich  set of directives including a wide range of synonyms that allow
  59. source  code  written  for  other  assemblers  (Public  Domain software for
  60. example) and the Commodore include files to be assembled.  Included as well
  61. are  directives  to  deal  with  structures,  repeat loops and similar code
  62. elements  very  easily.  Powerful macros with unlimited macro arguments and
  63. many macro directives are available to permit code to be easily and clearly
  64. arranged.
  65.  
  66. The  rich  set  of  available  facilities  allows  exact  control  over the
  67. performance  of  the  assembler.   This  control  includes features such as
  68. optimization,  case dependency for symbols, syntax control, and the default
  69. behaviour  of ProAsm to name a few.  More advanced control features such as
  70. precise  code  control  and  selectable  symbol  search  algorithm are also
  71. included.
  72.  
  73. A   valuable  feature  of  ProAsm  is  the  configuration  file,  which  is
  74. automatically  included in each assembly.  You can customize ProAsm to suit
  75. your  particular  wishes  by  including  commonly  used  macros,  code  and
  76. directives in the configuration file.
  77.  
  78. No  program  can  be  all  things  to  all  people.  So all assemblers have
  79. limitations  -  ProAsm  tries  to put them as far as possible not to narrow
  80. your  creativity.   This  results in the fact that the most limitations are
  81. just  limited  only  by  available  memory  (line length, macro body, macro
  82. nesting,  macro  arguments, nesting of macro directives, repeat and include
  83. file nesting,...).
  84.  
  85. This  makes  ProAsm  an ideal assembler for the professional developer, the
  86. high-level  language  programmer  (such  as  C,  Modula,...)  who  want  to
  87. integrate  some  assembly language code into his programs, and the beginner
  88. at assembly language programming.
  89.  
  90.  
  91.                                Some Features
  92.                                .............
  93.  
  94.   - Completely  written  in  carefully  hand-coded  assembly  language for
  95.     maximum speed.
  96.   - Supports the entire Motorola M68000 Family:
  97.     MC68000, MC68008, MC68010, MC68020, MC68030, MC68040, MC68060, MC68EC020,
  98.     MC68EC030 processors, and the MC68881, MC68882, MC68851 coprocessors.
  99.   - Both  addressing  mode syntax supported as defined by Motorola for the
  100.     M68000  Family.   (The syntax modes can individually be controlled by
  101.     using the  NEWSYNTAX,  OLDSYNTAX  and  RELAX directives.)
  102.   - Five different output file formats:
  103.     executable, linkable, binary, preasm (pre-assembled symbol tables and
  104.     macros), and the Motorola S-record format.
  105.   - Produces Amiga standard object files compatible with the Amiga standard
  106.     linker and BLINK (the replacement linker from 'The Software Distillery').
  107.   - Rich set of optimization possibilities.
  108.   - Multipass optimization to gain more compact code.
  109.   - Powerful macros (and many macro directives). (Unlimited number of macro
  110.     arguments and nesting - limited only by available memory)
  111.   - Configuration file supported to customize ProAsm.
  112.   - Convenience Pseudo-Opcodes: MEA, POP, PUSH, POPM, PUSHM, APOPM, APUSHM.
  113.   - Special directives to allow powerful string-handling.
  114.   - Support of text substitution using textual symbols.
  115.   - Include files supported (unlimited nesting of include files - limited
  116.     only by available memory).
  117.   - Conditional assembly (conditional nesting up to 231 levels possible).
  118.   - Directives to declare initialized data with restricted range
  119.   - Directives to define C-type, BCPL, and OS9-type strings.
  120.   - Supports symbol segmentation.
  121.   - Special directives to change the default behaviour of ProAsm.
  122.   - Structure offset directives allow the declaration of structures easily.
  123.   - Frame offset directives to define stack frame data structures.
  124.   - Repeat loop directives to allow text repetition (unlimited repeat
  125.     nesting - limited only by available memory).
  126.   - Up to 256 different hunks (code, data, and bss).
  127.   - Support of debug information for the executable and linkable output.
  128.     ProAsm generates either a standard or compressed debug hunk format that
  129.     is compatible with the SAS/C.
  130.   - A directive to attach an AmigaDOS comment to the output file.
  131.   - A directive to set the AmigaDOS file protection flags to the output file.
  132.   - Four auxiliary output files can be generated: the listing file, error
  133.     file, equate file, and the cross-reference listing.
  134.   - ProAsm allows the inclusion of binary images.
  135.   - The assembly task priority can be set from within the source file.
  136.   - ProAsm is entirely re-entrant, and can be made resident.
  137.   - A rich set of directives and options to control the assemblers behaviour
  138.     and to ease programming.
  139.   - The standard directives are compatible with the most popular assemblers.
  140.   - Many useful build-in symbols to make programming easier.
  141.   - Comfortable support of relative bases.
  142.   - XPK library system supported.
  143.   - Directives to control the report of information timing.
  144.   - Four selectable symbol search algorithm.
  145.   - (OSV37 & OSV39 and higher hunks supported)
  146.   - Six types of constants provided:
  147.     decimal, hexadecimal, binary, octal, floating point, and string.
  148.   - ProAsm (optionally) supports localization for the AmigaOS V38 and higher.
  149.     (German error texts included to the software package).
  150.  
  151.  
  152.  
  153.                             System Requirements
  154.                             ...................
  155.  
  156.   - Amiga with at least 512KByte of memory needed.
  157.   - Workbench and Kickstart 1.2 or higher required.
  158.   - Fully compatible with the entire Amiga family.
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.                       ASX - The ProAsm User Interface
  166.                       -------------------------------
  167. ASX  is  a user interface for the ProAsm assembler that is implemented as a
  168. commodity.   Through the use of the commodities.library it can be installed
  169. on any hotkey and fully controlled with the Commodities Exchange program.
  170.  
  171. ASX  loads  the ProAsm assembler which than can be accessed using the ARexx
  172. interface,  the  asx.library,  or the AppIcon possibility.  The asx.library
  173. and the AppIcon can optionally be enabled or disabled.
  174.  
  175. The  ARexx  commands  provide  a method of controlling ASX from an external
  176. program.   These  ARexx  commands  can  be  used  to  create  an integrated
  177. programming/development  environment  with  any  application that offers an
  178. ARexx  interface.  For example, a program can be written by a programmer on
  179. its  favourite ARexx equipped texteditor, then an ARexx command can be sent
  180. to ASX to assemble the source code.  Any error messages and warnings of the
  181. assembly  are  stored  by  ASX,  and  using  commands such as NEXTERROR and
  182. PREVERROR  the  texteditor is capable to position the cursor in the line of
  183. the  first  error.  After correcting that error a single keystroke can jump
  184. to  the  next  error,  or  another  keystroke can jump back to the previous
  185. error.
  186.  
  187. Another  method  of controlling ASX is the use of the optional asx.library.
  188. The  various  functions  that this library offers can be used to design own
  189. user interfaces with ease.
  190.  
  191. The AppIcon possibility is another visual user interface that allows one or
  192. more  source  file icons to be assembled by just dropping them over the ASX
  193. appicon.
  194.  
  195. Frequently  used include files can be loaded residently and managed by ASX.
  196. Such residently loaded include files reduce assembly time since they do not
  197. need to be loaded each time the assembler is called.
  198.  
  199. Preferred  include file paths can be added to a database that is managed by
  200. ASX.   During  assembly the assembler uses then this database to know where
  201. to look for the include files.
  202.  
  203. ASX  also  provides  a  feature  called  the source manager, which offers a
  204. possibility  to  manage the current project per hotkey.  Through the use of
  205. an  ARexx  script file the user can easily define the action that has to be
  206. fulfilled  when  an  entry  in the source manager window had been selected.
  207. Almost all shooting matches of the source manager can be set by the user to
  208. his wishes and needs to allow a wide range of flexibility.
  209.  
  210. For  an  easy  use  of  ASX,  it  comes along with an on-line help feature.
  211. Commodore's AmigaGuide is used to display the help text to the user.
  212.  
  213.  
  214.  
  215.                                Some Features
  216.                                .............
  217.  
  218.   - Hotkeys to control ASX.
  219.   - 53 ARexx commands that permits external programs to control ASX.
  220.   - 13 asx.library functions.
  221.   - Workbench 2.0's appicon feature supported.
  222.   - Source manager to manage projects and source codes by a single hotkey.
  223.   - Supports residently loaded include files to reduce assembly speed.
  224.   - Include file paths can be stored in a database to let the assembler
  225.     know where to look for the include files.
  226.   - Context-sensitive on-line help using Commodore's AmigaGuide.
  227.   - Settings can be saved and loaded.
  228.   - Full intuition/gadtools user interface to allow all changes to be done
  229.     using the mouse.
  230.   - Font-sensitive user interface.
  231.  
  232.  
  233.                             System Requirements
  234.                             ...................
  235.  
  236.   - Amiga with at least 512KByte of memory needed.
  237.   - Workbench and Kickstart 2.04 or higher required.
  238.   - Fully compatible with the entire Amiga family.
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.                 ProOpts - The ProAsm Configuration Program
  246.                 ------------------------------------------
  247. ProOpts  provides a simple method of generating or changing a configuration
  248. file  for  the ProAsm assembler.  Since ProAsm supports configuration files
  249. to  be  loaded  each  time when it is called, the user is able to customize
  250. ProAsm  to suit his particular wishes and needs.  The options for a project
  251. can  be set by clicking on the gadget that corresponds to the option.  Even
  252. options  for  which  the  ProOpts  utility  does  not  have a gadget can be
  253. specified by a special string and listview gadget.
  254.  
  255. The  generated  configuration  file  is  an  ASCII  file  that contains the
  256. specified options as assembly directives.  It is similar to an include file
  257. except  that it is loaded at the very beginning of each assembly.  There is
  258. no  restriction  on  the  use of as- sembler directives or even code in the
  259. configuration  file.   The  user  can  also  re-edit or add options using a
  260. texteditor.   Previously  generated config files can be loaded into ProOpts
  261. and then be changed to the new option settings.
  262.  
  263.  
  264.  
  265.                                Some Features
  266.                                .............
  267.  
  268.   - Configuration can be changed by using the mouse.
  269.   - Generates an assembly language source file.
  270.   - Supports options that have no specific gadget.
  271.   - Menu item to reset all options to their default.
  272.   - Full intuition/gadtools user interface to allow all changes to be done
  273.     using the mouse.
  274.   - Font-sensitive user interface.
  275.  
  276.  
  277.                             System Requirements
  278.                             ...................
  279.  
  280.   - Amiga with at least 512KByte of memory needed.
  281.   - Workbench and Kickstart 2.04 or higher required.
  282.   - Fully compatible with the entire Amiga family.
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.                              Support Libraries
  290.                              -----------------
  291. The  support  libraries  are  not  required  by  ProAsm  or  by  any of its
  292. associated  utilities.   They  can  optionally  be  installed  to  increase
  293. selectively the power and flexibility of ProAsm.
  294.  
  295.   - proasmlang.library     - ProAsm localization support library for OS V38
  296.                            and higher.
  297.   - proasmoptim.library  - Library to enlarge ProAsm's optimization dictionary
  298.                            to recognize more possible optimizations.
  299.   - proasmfp.library     - Library to boost ProAsm's floating-point support.
  300.  
  301. Please note that the last two libraries are currently not included to the
  302. archive.
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.                          ProAsm Software Overview
  310.                          ------------------------
  311. Listed and described below is the software provided in this release.
  312.  
  313.  
  314.                                  Programs
  315.                                  ........
  316.  
  317.   - Pre2Src    - Converts pre-assembled files into readable source code.
  318.   - ProHunk    - 680x0/688xx Hunk Analyser.
  319.   - Profiler    - Small run-time statistics utility.
  320.   - MMUInfo    - MMU information utility.
  321.   - StripD    - Strips debugging symbols/information from an object file.
  322.   - CLICalc    - CLI calculator.
  323.   - FCalc    - CLI IEEE double precision calculator.
  324.   - FCmp    - File compare utility.
  325.   - Bin2DC    - Converts binary data files into assembler source using the DC.x directive.
  326.   - FD2LVO    - Converts fd files to _LVO equate files.
  327.   - BDiff    - Small binary file compare program.
  328.   - UnBDiff    - Small binary un-diff.
  329.   - Blink    - Replacement linker from 'The Software Distillery'.
  330.  
  331.  
  332.                                Source Codes
  333.                                ............
  334.   - Pro68       - Shell-ASX Interface
  335.   - crypt    - Small encryption program
  336.   - perfmon    - Performance monitor
  337.   - cxchange    - Controls system commodities
  338.   - ...
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.                                  Routines
  347.                                  --------
  348. Routine  files  are  a library of useful routines that provide a simple and
  349. time  saving  method  for  assembly  programming.  Special macros have been
  350. designed  that  ensure  that  only the called routines get assembled.  This
  351. makes the routine files a good foundation for assembly programming.
  352.  
  353.   - alert.r        - Alert support routines.
  354.   - amigaguide.r    - AmigaGuide support routines.
  355.   - amigaguideasync.r    - Asynchroneous AmigaGuide support.
  356.   - AppIcon.r        - Routines for Workbench 2.0's appicon support.
  357.   - ARexx.r        - For ARexx support.
  358.   - ASLSupport.r    - For support of the ASL file requester.
  359.   - basicmac.r        - Macros for selective routines assembly.
  360.   - commodity.r        - Contains routines for commodity support.
  361.   - configfile.r    - Configuration file support routines.
  362.   - conio.r        - Routines for console window input/output.
  363.   - conoc.r        - Single console window open/close routines.
  364.   - conread.r        - Read routines for the console window.
  365.   - conreadpkt.r    - Read routines for the console window using packets.
  366.   - CRC16.r        - Routines to calculate an Ansi CRC16 checksum.
  367.   - DiskObjectSupport.r    - DiskObject support routines.
  368.   - dosfile.r        - Contains DOS file handling routines.
  369.   - doslib.r        - DOS library open and close routines.
  370.   - easylibrary.r    - Routines to open and close libraries simple.
  371.   - extmsg.r        - External message support routines.
  372.   - GadgetGroupSupport.r - GadgetGroup support routines for use with GTFace.
  373.   - graphicslib.r    - Graphics library open and close routines.
  374.   - gtface.r        - Window handling and gadtools interface routines.
  375.   - gtfdefs.r        - Definitions for GTFace.
  376.   - gtfguido.r        - GUI macros for GTFace.
  377.   - gtfmacros.r        - Macros for GTFace (gadgets and menus).
  378.   - gtfsupport.r    - Various GTFace support routines.
  379.   - gtfsupport_reb.r    - More GTFace support routines
  380.   - gtfxdefs.r        - External definitions for GTFace.
  381.   - intuitionlib.r    - Intuition open and close routines.
  382.   - IntuitionSupport.r    - Routines for the intuition BusyPointer.
  383.   - locale.r        - Support routines for locale (locale.library).
  384.   - locks.r        - Routines for locks, files, and directories.
  385.   - memory.r        - Memory handling routines.
  386.   - numbers.r        - Various routines for number conversion.
  387.   - numbers.mac        - String to number macros.
  388.   - packets.r        - DOS packet handling routines.
  389.   - paraliner.r        - UNIX like parameter line parser.
  390.   - parse.r        - Routines for text parsing.
  391.   - patch.r        - Library function patch routines.
  392.   - ports.r        - Contains ports, signal, and message handling
  393.                           routines.
  394.   - progressbars.r    - Routines to handle progress bars easily.
  395.   - qsort.r        - Quicksort sorting algorithm.
  396.   - readargs.r        - Interface routines to ReadArgs().
  397.   - readrexx.r        - Routines for a passive ARexx port.
  398.   - requester.r        - ASL and REQ file requester routine.
  399.   - reset.r        - Software reboot routine.
  400.   - script.r        - Routines to deal with batches.
  401.   - scrollbars.r    - GTFace appendum for horiz./vert. scrollbars.
  402.   - shortcut.r        - Routine to wait for a shortcut.
  403.   - startup4.r        - Enhanced CLI and Workbench startup code
  404.                           (with detach).
  405.   - string.r        - String support routines.
  406.   - stringmacros.r    - String support macros.
  407.   - structs.r        - Macros for various structures.
  408.   - support.mac        - Support macros.
  409.   - tasks.r        - Some little routines for tasks.
  410.   - tasktricks.r    - More routines for tasks.
  411.   - tooltypes.r        - Routines to get ToolTypes from a Workbench started
  412.                           program.
  413.   - ToolTypeSupport.r    - ToolType support routines.
  414.   - TypeOfProcessor.r    - Contains routine to determine installed processor and coprocessors.
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.                                Documentation
  422.                                -------------
  423. You find the complete online documentation in the Help/ and the Help/english/
  424. directory of this distribution.
  425.  
  426. A printed version of the manual with about 320 pages will be available
  427. as soon as possible.
  428.  
  429. Read the registration.doc or the registration part in the pro.guide file
  430. for further information about registration and the shareware limitation.
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.                                   Author
  438.                                   ------
  439. If   you   have   bugreports,   questions,   ideas,  flames  or  complaints
  440. (constructive  criticism is always welcome), or if you just want to contact
  441. me, write or send a letter to:
  442.  
  443.  
  444.                         Daniel Weber
  445.  
  446.         Internet:       dweber@amiga.icu.net.ch   (preferred)
  447.                         dweber@iiic.ethz.ch
  448.  
  449.         Mail:           Daniel Weber
  450.                         Hoeflistrasse 32
  451.                         CH-8135 Langnau
  452.                         Switzerland.
  453.  
  454.  
  455.  
  456.