home *** CD-ROM | disk | FTP | other *** search
/ Il CD di internet / CD.iso / SOURCE / EXTRA-ST / APPLE-II / APPLE2-V.TAR / apple2 / README < prev   
Encoding:
Text File  |  1994-10-09  |  10.6 KB  |  286 lines

  1. **************************************************************************
  2. *                              (Oct. 9 1994)  *
  3. *               Apple II+ Emulator version 0.01 for Linux                *
  4. *                                     *
  5. *      Author: Alexander Jean-Claude Bottema                             *
  6. *      Email : d91a1bo@meryl.csd.uu.se                                   *
  7. **************************************************************************
  8.  
  9. Contents
  10. ========
  11.  
  12. 0. Installation issues (briefly)
  13. 1. Why did I make an Apple II+ Emulator when there are so many available?
  14. 2. System Files
  15. 3. Keyboard & keys
  16. 4. Diskette database
  17. 5. Future plans
  18. 6. Status of the current emulator
  19. 7. Can you port this to DOS?
  20. 8. Availability
  21. 9. Known problems
  22. 10. Changes since 0.00 (see CHANGES)
  23. 11. Final words
  24.  
  25. 0. Installation issues (briefly)
  26. ================================
  27.  
  28. Unpack this distribution in a temporary directory and type "make
  29. install".  Read section 2 for further information considering default
  30. parameters and system files (these must be available). Type "apple2"
  31. to run the emulator, check that the boot diskette is named disk_s6d1.
  32.  
  33. Requirements: SVGA lib version 1.05 (or later but < 1.08, see 9.)
  34.               Kernel 1.0 (or later).
  35.           libc 4.4.4 (or later).
  36.  
  37. 1. Why did I make an Apple II+ Emulator when there are so many available?
  38. =========================================================================
  39.  
  40. For three reasons. The first is that there are no Apple II emulators
  41. especially written for Linux; hence they do not take advantages that
  42. are commonly provided in Linux systems, e.g. the SVGA library
  43. distribution.  However, there is an Apple II emulator for X-Windows
  44. that easily can be compiled on most UN*X architectures, but the major
  45. disadvantage is slow emulation. You cannot obtain a fast emulator by
  46. writing it in C, despite the elegant optimizations provided by GNU-C,
  47. but of course it becomes more portable if you do that.
  48.  
  49. By contrast, this Apple II emulator is partly written in 386 (AT&T)
  50. assembler; partly in C. Only those issues that were not time critical
  51. were written in C. Especially the CPU emulation was written in
  52. optimized assembler to achieve optimum performance. The emulator
  53. approximately runs twice as fast as an ordinary Apple II+ computer if
  54. it is running on a 486 DX-50.
  55.  
  56. The second reason is that there is no Apple II emulator which is 100%
  57. usable. Either it is too slow or it is simply too fast (= there is no
  58. option to trim the speed of the emulator). Furthermore, many
  59. implementors happily avoid implementing mixed text/graphics in high
  60. resolution mode; mostly because it complicates the programming. I have
  61. never seen an Apple II+ emulator that is entirely complete. I think
  62. most emulators fail on implementing the undocumented 6502 instructions
  63. (those that are listed as ???), hence some games (or applications) may
  64. not work despite they should.
  65.  
  66. The third reason is that no emulator support an easy way to switch
  67. diskettes given a database of diskettes. With this emulator you can
  68. easily switch diskettes through an intuitive interface. You can also
  69. add additional information for each diskette (in your database), e.g.
  70. which keys to use for a particular game program. The information is
  71. kept in a plain text file that can be edited with an ordinary text
  72. editor, preferbly GNU-Emacs.
  73.  
  74. 2. System files
  75. ===============
  76.  
  77. Before you can run the emulator, three vital system files must be
  78. available. These are:
  79.  
  80. apple_II.rom (12k)    This file contains the ROM of your Apple II+.
  81.                         It is not distributed due to copyright issues.
  82.             You have to fix this file by your own. If you
  83.             have been running another emulator, you can
  84.             probably use its ROM files directly. Technically
  85.             speaking, this file is a memory dump of the
  86.             consecutive addresses from D000 to FFFF.
  87.  
  88. slot6.rom (256 bytes)    Memory dump of the consecutive addresses from
  89.             C600 to C6FF. This file is not distributed
  90.                         either due to the same reasons as above.
  91.  
  92. character.rom        This file is distributed.
  93.  
  94. Other important files
  95. ---------------------
  96.  
  97. .apple2            This file is distributed. The file contains default
  98.             parameter settings. The most important parameter is
  99.             the setting of the system path, i.e. the directory
  100.             where the three vital system files are stored. The
  101.             other parameters can be changed during run time
  102.             via the interface (activated by pressing F10).
  103.  
  104.                         Parameters (that can be set in .apple2):
  105.  
  106.             speed = <percentage>%      Speed of the emulator
  107.             path = <directory>        Diskette database directory
  108.             color = off          Monochrome mode
  109.                 on          Plain color mode
  110.                 interpolated      Interpolated color mode
  111.             sound = off          Silent mode
  112.                     pc speaker      Sound through PC speaker
  113.             joystick = off          Joystick disabled
  114.                    linear      Linear joystick mode
  115.                    digital      (Atari) digital joystick mode
  116.                                   not yet supported
  117.             origin_x = 0-255      Origin of the joystick (X)
  118.             origin_y = 0-255      Origin of the joystick (Y)
  119.             sensitivity <percentage>% Joystick sensitivity
  120.             system_path = <directory> Directory where the system
  121.                           files are stored.
  122.  
  123. a2d.info        An example is distributed. This file contains
  124.             information for various diskettes kept in the database.
  125.  
  126.             Syntax:
  127.             {<Name of diskette>}      i.e. the name is written
  128.                           within curly braces.
  129.             <Any information...>
  130.             
  131.             {<Name of another diskette>}  ... etc.
  132.  
  133. 3. Keyboard & keys
  134. ==================
  135.  
  136. F1            To switch diskettes in Drive A, Slot 6
  137. F2            To switch diskettes in Drive B, Slot 6
  138. F4            Pause
  139. F5            Keyboard layout
  140. F8            Words from the author
  141. F9            Toggle between maximum speed and configured speed.
  142. F10            General parameter settings
  143. Print Screen/SysRq    Apple II Reset key
  144. Pause/Break        Reboot Apple II emulator
  145.  
  146. The numeric keypad is used for joystick emulation.
  147.  
  148. Delete            Joystick button 0
  149. End            Joystick button 1
  150. Page Down        Joystick button 2
  151.  
  152. 4. Diskette database
  153. ====================
  154.  
  155. The diskettes are provided as plain binary files. These are actually
  156. raw dumps, containg the tracks from 0 to 34 where each track is
  157. partitioned into sectors numbered from 0 to 15. Each sector is 256
  158. bytes.  Hence, the data is organized as the following:
  159.  
  160. File offset (in bytes)          Sector        Track
  161. ----------------------          ------          -----
  162. 0                0        0
  163. 256                1        0
  164. 512                2        0
  165. .                .        .
  166. .                .        .
  167. .                .        .
  168. 3840                            15        0
  169. 4096                0        1
  170. 4352                1        1
  171. .                .        .
  172. .                .        .
  173. .                .        .
  174. 143104                15        34
  175.  
  176. To transfer Apple II diskettes into this format requires that you own
  177. an original Apple II. Since the drives provided by the IBM PC:s are
  178. not compatible with the original Apple II drives there are no
  179. conversion programs directly available. If you have used other Apple
  180. II emulators it is most likely that the files will work with this
  181. emulator too. It seems to be a common standard to structure the
  182. diskettes in the above described way, e.g. the Apl2em (emulator) for
  183. DOS uses the same structure.
  184.  
  185. Emulated diskettes MUST have the .a2d (abbreviation to "Apple 2
  186. Diskette") extension, otherwise the emulator will not recognize the
  187. file as a valid diskette. However, it is valid to compress them by
  188. using gnu-zip (then the extension becomes .a2d.gz). The emulator will
  189. automatically decompress/compress them whenever required. The only
  190. exception is the initial bootable diskette, which is always named as
  191. disk_s6d1 (i.e. without the .a2d extension).
  192.  
  193. Note that you can add information/documentation for the a2d-diskettes
  194. by using an oridnary text editor and edit the file "a2d.info". The
  195. name of the diskette is written in curly braces (without the .a2d
  196. extension) followed by any information.
  197.  
  198. 5. Future plans
  199. ===============
  200.  
  201. I intend to improve the emulator. Actually, for the next major release
  202. (i.e. version 1.00) the emulator will be entirely rewritten. For minor
  203. changes, see file CHANGES.
  204.  
  205. 6. Status of the current emulator
  206. =================================
  207.  
  208. Works in standard VGA                  Y
  209. Works in SVGA (then using SVGA facilities)    Y
  210. Disk drive emulation (slot 6)            Y
  211. Disk drive emulation (slot 5)            N (release 1.00)
  212. High resolution emulation            Y
  213. Low resolution emulation            Y
  214. Mixed mode (in all resolution modes)        Y
  215. Correct color emulation    (both Low and Hi-res)    Y
  216. Interpolated color emulation            Y
  217. Configurable speed                Y
  218. Diskette switching                Y
  219. Diskette database                Y
  220. Interface for parameter settings, etc.        Y
  221. Sound emulation (PC speaker)            Y
  222. Flashing text                    Y
  223. Joystick emulation through numeric keypad    Y
  224. Virtual console switching            Y (only when emu. is paused)
  225. Raw keyboard mode (reading scancodes)        Y
  226. Undocumented 6502 instructions            Y
  227. Language card (i.e. additonal 16k RAM)        Y
  228. Serial card                    N (maybe release 1.00)
  229. Works on DOS                    N (AND NEVER WILL)
  230.  
  231. 7. Can you port this to DOS?
  232. ============================
  233.  
  234. No, for two reasons. The first, and probably the most important, is
  235. that the current emulator use kernel specific issues that are not, and
  236. never will be, available in DOS. Future emulators will be based on the
  237. same principles, so the emulator will never run in DOS. The second
  238. reason is that DOS is a bad operating system. It is a pain in the neck
  239. to write and debug programs in DOS and there is no usable memory
  240. management provided by the kernel (if the DOS "interrupts" can be
  241. called a "kernel" at all).
  242.  
  243. With this free software I hope that more users will switch to Linux
  244. (which is a great operating system) and I have a dream that one day,
  245. DOS will become a minority.
  246.  
  247. 8. Availability
  248. ===============
  249.  
  250. This distribution is available at ftp.funet.fi and tsx-11.mit.edu and
  251. sites mirroring these.
  252.  
  253. 9. Known problems
  254. =================
  255.  
  256. Problem: SVGAlib version 1.08 adds a Ctrl-C detection in RAW keyboard
  257.          mode, but I don't know how to disable it. (I still haven't
  258.          figured out how to disable it, perhaps time to contact the
  259.          SVGAlib fellows.)
  260.  
  261. Solution: Please use SVGAlib version 1.05, 1.06 or 1.07.
  262.  
  263. Problem: The REPT (repeat) key doesn't work.
  264.  
  265. Answer: True. I was too lazy to implement it.
  266.  
  267. 10. Changes since 0.00 (see file CHANGES)
  268. =========================================
  269.  
  270. 11. Final words
  271. ===============
  272.  
  273. Note that albeit you can switch between digital and linear joystick
  274. emulation, only linear mode is presently supported. I still haven't
  275. figured out how the atari (digital) joystick emulation works, so I'll
  276. save it to the next release (as I said in the previous release :-) )
  277.  
  278. I hope you will enjoy this emulator. I do. Many games (that I have
  279. ported) works perfectly, even those that use undocumented 6502
  280. instructions. Suggestions to improvements are welcome. My email
  281. address will be valid at least one more year, i.e. as long as I am a
  282. computer science student at the University of Uppsala in Sweden.
  283.  
  284.     / Alexander Jean-Claude Bottema (Email: d91a1bo@meryl.csd.uu.se)
  285.       Oct. 9 1994  15:44:21
  286.