home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / emulation / woz / Manual < prev   
Encoding:
Text File  |  1991-11-05  |  12.2 KB  |  267 lines
  1. Apple //e emulator user guide (v 0.6)
  2.  
  3. (c) 1990-91 Benoit GILON.
  4.  
  5. 0. Warning
  6. 0.0 READ THIS PARAGRAPH FIRST....
  7.  
  8. DUE TO COPYRIGHT CONTINGENCIES, AT THIS DATE (22/11/91) !Woz IS NOT
  9. A STAND ALONE EMULATOR PROGRAM!!!!
  10.  
  11. IF YOU DON'T OWN AN APPLE //E|//C|//GS SYSTEM AND DON'T USE ONE AT WORK
  12. THEN:
  13. > YOU CAN FORMAT THIS DISK ... FOR MORE USEFUL WORK,
  14. > WRITE TO APPLE U.K. TO ENCOURAGE THEM GIVING ME THE PERMISSION TO
  15.   INCLUDE THE FIRMWARE ON DISK FOR DISTRIBUTION
  16. > STAY TUNED   
  17.  
  18. 0.1 How to get the necessary ROM and disk (DOS 3.3/ProDOS) system files:
  19.  
  20. Including those files as part of the !Woz emulator without the written
  21. permission of Apple Inc. would infringe the copyright law.
  22.  
  23. In order to get the needed pieces of Software, two solutions are at your
  24. disposal:
  25.  
  26. - Send a SASE with the following content:
  27. > An empty and properly "E" formatted (800 Ko) 3'1/2 disk.
  28. > A copy of your Apple //e|//c|//gs warranty card with the serial number.
  29. to the following address:
  30.                  Benoit GILON
  31.                  15, rue RIBERA
  32.                  75016 PARIS
  33.                  FRANCE
  34.  
  35. - Get those files on your own:
  36. Here is a guideline to show you how I did:
  37.  
  38.            RS232C 19200 bauds                  3'1/2 MSDOS disk
  39. Apple //c \__________________/MSDOS Compatible\_________________/Archimedes
  40. Apple //e /  CrossWorks 2.0  \(Amiga SideCar) /  !PCDir         \ (ADFS)
  41.  
  42. > Using 3.5" disks as DOS 3.3 backups Call A.P.P.L.E. August 86 - Sean Nolan
  43.   (note I have included the source file for converting 5'1/4 as well as
  44.   3'1/2 disks to ProDOS files).
  45. > CrossWorks 2.0    Softspoken, Inc. (this is a commercial software)
  46. > !PCDir            (C) Keith Sloan. (this is a careware distributed by
  47.                                       Archive)
  48. Here I would like to thank all those manufacturers and sofware designers
  49. for the high quality of their products.
  50.  
  51. 1. Introduction
  52.  
  53. Nowadays hardware and software emulators are strengthening their
  54. stand in the Computer World as they give a satisfactory solution to
  55. every human desire: Run programs designed for a computer model X
  56. on another model (Y)... This means the right to buy the wrong machine.
  57.  
  58. X can take its value in the following list:
  59. { MacIntosh, IBM PC, Atari ST, C64, BBC Model B, ... }
  60. and Y in:
  61. { IBM PC, Amiga, Atari ST, Archimedes ... }
  62.  
  63. * The Apple // line of computers being widely used in the North American
  64. education world, it would be useful to run Apple // programs on Archimedes
  65. along with BBC's.
  66.  
  67. * Most of the emulators listed above are based on a hardware design as
  68. software only earlier emulators running on slow CPUs have a performance
  69. level near zero. The Archimedes computer is the only computer I know for
  70. which an Apple // software emulator is worth doing.
  71.  
  72. * Technical details about the 6502 emulator from Acorn being scarce (to say
  73.   a few), I wrote my own with the Acorn ANSI C (Release 3) package. This
  74.   version emulates a 65C02 CPU with a clock speed of about 150KHz (less than
  75.   20% of an Apple // CPU at 1MHz).
  76.  
  77. Despite its slow speed, I think it's a workable product. Future versions
  78. will be released with an improved speed. Please consult the paragraph
  79. entitled 'Features to come' for greater details. !Woz will greatly benefit
  80. from an ARM3 CPU with cache on.
  81.  
  82. 2. Current version's features:
  83.  
  84. 2.1 How to launch !Woz
  85.  
  86. - Insert the !Woz disk in drive :0,
  87. - Check that there's at least 288 Ko free under the Wimp. In case you are in
  88.   need of RAM memory, you can quit from WIMP based applications or simply
  89.   exit the Desktop environment by pressing the <Ctrl><Shift><F12>.
  90. - Under the Desktop, simply click on the !Woz icon to launch the emulator.
  91. - Under the RISCOS command level ('*' prompt), issue the following commands.
  92.   *SET Obey$Dir $.!Woz
  93.   *$.!Woz.!Run
  94.  
  95. The screen which will appear should be familiar to some.
  96.  
  97. 2.2 So what (you can do now) ...
  98.  
  99. The emulated Apple //e has the followings:
  100. - A CPU 65C02 (manufactured by NCR/GTE),
  101. - Langage card protocol (16 Ko bank switched with
  102.   ROM),
  103. - ROM enhanced //e version,
  104. - Extended 80 col. text card (with 64 Ko RAM auxiliary memory),
  105. - Mousetext characters, Lores, mixed and page2 graphics are supported,
  106. - Keyboard softswitches are supported,
  107. - The Open Apple key is the left Alt key on the Archimedes' keyboard,
  108. - The Solid Apple key is the right Alt key.
  109. - The Apple keyboard' Reset key is the break key on the Archimedes:
  110.   > To cause a warmstart reset, press the <Ctrl><Break> key sequence,
  111.   > To cause a coldstart reset, press the <Left_ALt><Ctrl><Break> key
  112.     sequence,
  113.   > To exit from the emulator, press the <Shift><Ctrl><Break> key
  114.     sequence.
  115. - A Drive ][ controler card in the Apple's sixth slot.  A Floppy disk's
  116.   content is seen as a 140Ko ADFS file for the emulator (just like the
  117.   MSDOS hard drive partition with the Acorn PC emulator). When you launch
  118.   !Woz, the emulated Apple //e will boot with a ProDOS 8 system disk.
  119.   If you wish to change the disk in your "Apple drive", just press the <F1>
  120.   key when a program waits for a keyboard entry, enter the name of the file
  121.   which contents the disk you wish to insert; The next coldstart will boot
  122.   on this "disk" (note that the ADFS disk file should be in the !Woz
  123.   directory). Please read next chapter for further details about
  124.   configuration management.
  125. - ProDOS recognizes the Archimedes internal clock and will use it for its
  126.   own file datestamping.
  127. - A program resides on the ProDOS 8 boot disk which copies files to and
  128.   from ADFS and ProDOS. Consult chapter 5 for further details.
  129. - Once !Woz is launched you can insert a specially formatted ADFS disk in
  130.   order to emulate as many Unidisk 3'5 as the number of floppy drives in
  131.   your Archimedes system.
  132. - Warning! This emulator's version doesn't provide neither Hires nor
  133.   Double hires graphics..
  134.  
  135. 3. Configuration management under !Woz:
  136.  
  137. All the configuration options can be selected by using the <F1> key whenever
  138. the Apple system scan the keyboard address (0xc000); with those commands you
  139. can emulate the disk swap in a sixth slot's drive, or simply change the way
  140. the characters are rendered on the screen.
  141.  
  142. When you press the <F1> key, a message prompt should be printed at the 25th
  143. screen row: "Filename/Command: ". The option selected is given by the first
  144. character you type in:
  145. > "0": You certainly have noticed the switch under your Apple //e keyboard.
  146.        It serves to toggle between the two character sets available in the
  147.        video ROM inside your Apple //e. Well the "0" option serves the same
  148.        purpose. It's based upon the "Local" textfile inside !Woz' directory.
  149. > "[1]<filename>": Emulates the disk swapping in the sixth slot' first disk
  150.        drive. You can omit the "1" when the filename itself doesn't begin
  151.        with a digit.
  152. > "2<filename>": Same purpose as before for the second disk drive. However
  153.        the "2" character is mandatory this time.
  154. > "3": When !Woz is launched, the current BBC 8x8 caracter set is used (with
  155.        some redesign due to mousetext support). This ensure greatest speed
  156.        for displaying characters on screen but will cause some "video
  157.        distorsion" on future Hires mixed modes (with text and graphics
  158.        displayed at the same time). So I designed 7x8 characters which fit
  159.        exactly the Apple native charset, these character set is based upon
  160.        a spritefile inside !Woz' directory. You can toggle between the two
  161.        methods by choosing this option, the screen is immediately refreshed.
  162.        I hope you'll enjoy the new appearance of the Archimedes screen.
  163.  
  164. Note: double quotes, angle brackets and the "[", "]" symbols are not part of
  165. legal commands. Items between angle brackets are mandatory, items between
  166. "[" and "]" are optional.
  167.  
  168. 4. Archimedes - Apple file copy and conversion:
  169.  
  170. 4.1 Copy:
  171. !Woz provides a small utility to copy files between the Archimedes and the
  172. Apple. The copy is of the raw kind on a byte for byte basis (i.e. it
  173. doesn't care about the source file's type to introduce format conversion).
  174.  
  175. To copy files between Archimedes' FileSwitch and ProDOS, proceed as below:
  176. - Launch the !Woz emulator as usual,
  177. - Ensure that the ProDOS disk named "Floppy1" (ie ADFS file) is on line
  178.   (refer to the previous chapter if in need).
  179. - At the BASIC prompt (BASIC.SYSTEM is the system file to run), run the
  180.   program named TRANS (which resides in the root directory):
  181.   ]-TRANS
  182. - At the prompt enter a digit "0" or "1" which tells the program whether you
  183.   wish to copy a file from or to ProDOS.
  184. - You will then be asked to enter the Archimedes filename:
  185.   you can then enter any valid pathname (for FileSwitch), in order to
  186.   easier the keyboard entry you can use the two macros provided by the
  187.   TRANS program: These macros are activated by pressing the "O" or "W"
  188.   keys while holding the LeftAlt/OpenApple key when the cursor is at the
  189.   beginning of the line.
  190.   . "O" is the macro key for "<Obey$Dir>." string pattern.
  191.   . "W" is the macro key for "<Woz$Dir>.".
  192. - Then enter the ProDOS pathname (full or partial)
  193. - The copy takes place.
  194. - If all went well, the program should print "Well done" and prompt for
  195.   another copy. In case an error (on the ProDOS or FileSwitch side) occured,
  196.   the messsage "Ooops" is displayed along with an error code. An error code
  197.   between 0 and 3 means something went wrong on the FileSwitch side:
  198.   . 0 : Protocol error, the TRANS program tried to open a file for transfer
  199.         as the previous file opened for a copy is not closed or something
  200.         like that.
  201.   . 1 : Open error, the FileSwitch source file you selected for reading
  202.         doesn't exist or the FileSwitch destination file you selected for
  203.         writing can't be opened due to the lack of space on the media.
  204.   . 2 : End of file when reading a FileSwitch source file, you should never
  205.         see this code on your screen as it is filtered by the TRANS program
  206.         which ends the copy process.
  207.   . 3 : Write error probably due to a lack of disk space on the FileSwitch
  208.         side.
  209.   Other error codes which may appear are standard ProDOS MLI error codes.
  210.  
  211. To the fellow Apple programmers, I have included the TRANS source file in
  212. the !Woz disk as well as in the ProDOS disk (Merlin 8/16 assembly).  
  213.  
  214. 4.2 Text conversion utility:
  215.  
  216. WTCU is a very simple RISC_OS application to convert textfiles between the
  217. Archimedes and the Apple. Here are the differences:
  218. - Contrary to the Archimedes', Apple textfile format only knows about 7 bit
  219.   ASCII codes (hi bit is always set)
  220. - Apple EOL character is [8d], Archimedes EOL character is [0a].
  221.  
  222. In addition & provided that a "local" textfile has been seen before the
  223. conversion takes place (usualy in the <Woz$Dir> folder), you can tell WTCU to
  224. convert international characters (i.e. which have a code value > 127 in the
  225. ISO Latin 1).
  226.  
  227. 5. Features to come...
  228.  
  229. 5.1 What to do next (i.e. next month?)
  230.  
  231. - Provide disk caching for Unidisk 3'5 I/O, standard Apple ProDOS I/O units
  232.   are 512 bytes wide blocks, ADFS sectors are 1024 bytes wide...
  233. - Program to exchange files between DOS 3.3 and FileSwitch.
  234. - A RISCOS application to convert Applesoft BASIC programs to Archimedes
  235.   BBC BASIC format.
  236. - Apple Protocol RAM disk support in the RAMFS free space.
  237.  
  238. 5.2 At a later stage (i.e. next year?)
  239.  
  240. - Hires & double hires graphics.
  241. - A RISCOS application to easier file transfer thru a serial link
  242.   between the Archimedes and an Apple //.
  243.  
  244. 6. Software running under !Woz:
  245.  
  246. > Merlin 8 v2.58 ProDOS version & v2.48 DOS 3.3 version,
  247. > AppleWorks 1.4 (localized french version),
  248. > ProSel 8 (by Glen Bredon), program launcher and useful utilities,
  249. > ZBASIC compiler ProDOS 64Ko and 128 Ko versions (don't be afraid by
  250.   what should be the ZBASIC Welcome Hires screen),
  251. > Copy ][+ v9.0, ProDOS disk utilities, all file relative options work.
  252.   Of course, bit copy routines as well as cataloging a DOS 3.3 disk
  253.   hang up (I guess it uses its own routines instead of calling the ProDOS
  254.   READ_BLOCK/WRITE_BLOCK MLI sub.).
  255.  
  256.     As a bonus, if you wish to mutate your legally purchased
  257. Apple unlocked software under !Woz, just send me a warranty card (+ a copy
  258. disk of your software if it does'nt belong to the previous list),
  259. an ADFS E formatted 3'1/2 disk and return postage; I'll send it back to
  260. you ready to run under !Woz (plan for a delay of two weeks for Europe).
  261.  
  262. 7. Final notes:
  263.  
  264. - The Watford ARM3support module's hot keys to toggle the CPU speed
  265.   (LeftAlt/LeftShift/LeftControl) have a special meaning under !Woz too.
  266.   So don't forget to correct the speed after a !Woz "cold start" for example.
  267.