home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 3 / AUCD3.iso / funland / emulators / c64 / breadpatch / !BreadPtch / !Help next >
Text File  |  1997-08-03  |  13KB  |  255 lines
  1. BREADPATCH (version 1.3)
  2. ========================
  3.  
  4.  
  5.  
  6. PLEASE READ THIS HELP-FILE CAREFULLY BEFORE ATTEMPTING THE PATCH!
  7.  
  8.  
  9.  
  10. Slight changes since the first version:
  11.  
  12. - vectored system calls are now trapped correctly. This allows the native SID player
  13.   (RealSIDPlayer, see ftp://utopia.hacktic.nl/pub/c64) to work, for instance.
  14. - corrected CIA keyboard / joystick reading: $DC00 = $7F, not $FF when nothing's
  15.   pressed. That makes some programs work that used to have problems reading the
  16.   joystick in port 2 (e.g. Commando).
  17. - I got hold of release #2 and did the patch myself, so now I can be really sure
  18.   it works OK. I did find a wrong branch in the patched patch used in version 1.2.
  19.  
  20.  
  21.  
  22. This is a patch for the C64-Emulator "!Breadbox" V0.44 (Rel #1/2). It gives you simple
  23. IO, simulating Floppy Disc Drives (Device# >= 8) and Printers (Device# = 4). This
  24. is done by trapping certain OS calls, like those for loading/saving files and
  25. anything to do with open channels on the IEC bus. Anything that goes beyond
  26. this (like Floppyspeeders that download a program into the Floppy Disc Drive)
  27. will not work with that Patch either but a large number of stuff will.
  28.  
  29. In addition it cures the bug in displaying hires mono mode. For some reason Denys
  30. brought the background colour into it which could result in a bad address offset
  31. which in turn totaled the machine. Hires mono is completely independent of the
  32. background colour register - this is now fixed, everything works fine and I
  33. haven't had a single crash since :-)
  34.  
  35. This is NOT an official patch - I am in no way related with Daydream Software or
  36. Denys Bogatz. Thus if anything goes wrong don't blame them. Don't blame me either
  37. because as usual with free stuff the author refuses any kind of responsibility
  38. blahblahblah (see below).
  39.  
  40.  
  41.  
  42. Patching your copy of !Breadbox:
  43. --------------------------------
  44.  
  45. First up: the !BreadPtch application folder contains two versions of the patch
  46. binary: !RunImage (for release#1) and !RunImage2 (for release#2). By default !RunImage
  47. is used (i.e. release#1). If you have release#2 you must either change the !Run-File
  48. to start !RunImage2 or rename !RunImage2 into !RunImage. That done you're ready to
  49. start patching the Breadbox.
  50.  
  51. Open the !Breadbox application-folder: this contains the file CODE. Start !BreadPtch
  52. by double-clicking on its filer icon. This will open a small window with a greyed-out
  53. sprite icon and two writable icons. Dragging the CODE file (_not_ the application itself)
  54. onto the patch-window will result in said icon being un-greyed. The filename you want to
  55. save the new CODE file under has to be entered in the writable icon under the sprite
  56. icon. This is set to CODE+ by default to avoid casual overwriting of your original file.
  57.  
  58. In the writable icon headed "EmuMode" you can specify what screen mode the emulator
  59. should use when active. The default one used by !Breadbox rel#1 is mode106 - although the
  60. mode module is called mode126. However mode 106 plays merry hell with the Colour Card
  61. Gold, so I changed it to mode 126 on my system. You have to enter the correct mode
  62. number here, there's no default value used by the patcher. Remember to change the
  63. module defining the screen mode too if you make !Breadbox use a different mode (using
  64. !CustomVDU, for instance)! Rel#2 uses mode126 by default, for all I know.
  65.  
  66. If all is set up alright drag the sprite icon into the destination directory window
  67. as with any SaveAs box (only filer windows are allowed!). DO NOT OVERWRITE YOUR ORIGINAL
  68. CODE-FILE!!! This is very important. Don't write onto the original floppy disc either
  69. since that might lead to trouble with Daydream Software should you want an upgrade.
  70. Make a copy of !Breadbox on your harddisc instead - most people will have put it
  71. there first thing anyway - and write the new CODE file in there. If you save the patched
  72. file under a different name than "CODE" (which I recommend) make sure the !Run-file
  73. starts the correct one. Patching might take some time unless a hard- or RAM-disc is
  74. involved (a RAM disc is a "bit" over the top, though). You should have about 600kB of
  75. free RAM available for patching!
  76.  
  77. After successful patching !BreadPtch will automatically terminate itself and you'll
  78. have the new CODE file ready for use (it's a bit over 540k). Since it's longer than
  79. the original file you'll have to alter the !Run-file to give the program a 544k wimpslot
  80. (the original had 540k). The size of the patched file is due to uncrunching. You may cut
  81. down its size again using e.g. !Crunch (which seems to have been used on the original as
  82. well).
  83.  
  84. If your version of !Breadbox is incompatible with the one this patch was written for
  85. the patching will be aborted. !BreadPtch checks quite a lot of things on the way so
  86. if it runs without complaining there shouldn't be any complications later on.
  87.  
  88. You should now have a working version of the patched Breadbox.
  89.  
  90. I know the patch program could be better but then why bother for a one-way application?
  91.  
  92.  
  93.  
  94. IO from/to where?
  95. -----------------
  96.  
  97. The virtual Floppy disc drive reads from VC1541$Path so you have to set up that variable
  98. to point to the directories or VC1541 disc images that hold the files you wish to
  99. access. You may specify more than one directory - in that case all of the files contained
  100. in these can be accessed; the directory will be read from the first, new files (ones that
  101. aren't found in any of the directories on VC1541$Path) are created in the last directory
  102. (this is RISC OS specific, don't blame me). Please note that _all_ file accesses will affect
  103. files in all the specified directories, which includes deleting files (files with matching
  104. names are deleted from all of these directories!). You can check if you've set up the
  105. path correctly by typing "*cat VC1541:" on the CLI which should catalogue the first
  106. directory on the path.
  107.  
  108. If you're loading/saving files there will be no messages along the lines of "searching
  109. for <filename>... loading", only a "ready." after it's finished. Unless you get an error
  110. the load will have been performed OK.
  111.  
  112. Error messages may be completely wrong. I didn't bother to set the correct error for
  113. everything that can go wrong; hardly any program cares anyway. E.g. if a file can't
  114. be found you get a "break error". So don't take these errors literally, the messages
  115. might not have anything to do with the real cause.
  116.  
  117. Accessing files within a VC1541 disc image (extension .D64) is not supported directly by
  118. this program, all file accesses are handled through RISC OS. Hence you'll have to run
  119. D64ImageFS for that (which I uploaded on the same FTP servers as this patch). Even without
  120. D64ImageFS you can read an image's directory and access it with block-read/write commands.
  121.  
  122. A speciality of the load/save routines is that they only access the emulated C64's RAM,
  123. not the ROM. I.e. saving &a000-&c000 will save the RAM under the BASIC ROM, no matter
  124. what the contents of $01. Since saving the ROM doesn't make much sense this is usually
  125. no problem. A special case is the IO-area from $D000-$DFFF (both for load and save). If
  126. the start-address is less than $D000 the operation will be applied on the RAM, even
  127. if the end-address is beyond $D000. I don't know any program which would do that,
  128. actually, since loading to $D000 will completely screw up your machine, but there are
  129. some programs which go beyond $D000 and hence need a special loader on a real C64,
  130. but because of this distinction not with the emulator. If the start-address lies between
  131. $D000 and $DFFF, however, the operation will be applied on the IO-area. I can only
  132. think of one occasion where this would be handy and that's loading/saving the colour-RAM
  133. from $D800-$DBFF, that's why I did the distinction.
  134. Another special thing about load/save: these are always called for Floppy Discs, no
  135. matter what device you specify. Thus you can load a file with ``load "<file>"'' instead
  136. of ``load "<file>",8''. You only have to bother with the usual device-numbers if you
  137. need a secondary-address other than zero.
  138. I might change this in future versions but for now I couldn't care less.
  139.  
  140. Directory routines differ for RO-directories and VC1541 disc images since the latter
  141. contain some additional info (like the disc image's name and the number of free
  142. blocks). RO directories will be given a generic header and footer, VC1541 disc
  143. images will look more or less exactly like they used to on a real C64.
  144. The only supported directory format is the one where the secondary address is 0! That
  145. means a BASIC-file rather than the raw data. This is by far the most widespread format
  146. used, I don't think this should pose any problems. The directory may be loaded into
  147. memory (load "$",8) or opened as file and read in byte-for-byte. Opening another
  148. directory-file while the previous one isn't closed will reset the previous one - this
  149. patch only supports 1 open directory file at a time. This also should not be a
  150. limitation - but I don't know what the original VC1541 did in that case which
  151. essentially doesn't make any sense.
  152.  
  153. Data sent to the printer (Device# = 4) is spooled into the file "VC1541:_C64_Prnt_".
  154. If you opened the printer channel via open 1,4,x,"<stuff>" the <stuff> will be lost -
  155. sorry but once again this hardly ever matters at all since practically all programs
  156. open the channel without any <stuff> and if they do all that's lost are usually some
  157. escape-sequences to the printer.
  158.  
  159. DON'T MAKE SNAPSHOTS WHILE FILE OPERATIONS ARE IN PROGRESS. The snapshot will save
  160. the C64-RAM but not the file state of the emulator and thus it'll be useless later on.
  161. But that's no different from a real C64 where you can't just make a snapshot in the
  162. middle of an IO-operation either. Making snapshots shouldn't crash anything, though.
  163.  
  164.  
  165.  
  166. Supported Floppy-Commands:
  167. --------------------------
  168.  
  169. You can send Floppy-commands to a channel with secondary address 15 as on a real C64:
  170.  
  171. open1,8,15,"s:file1,file2": close1
  172.  
  173. will delete file1 and file2 just like in the good ole days. In the same way you can
  174. read the Floppy's status by reading from such a channel. Currently there are only two
  175. different states of the virtual Floppy, OK and error - live with it.
  176.  
  177. 1) File-commands:
  178. ~~~~~~~~~~~~~~~~~
  179.  
  180.     copy:new=old1,old2,...    (c:...)
  181.     initialise        (i)    -- Doesn't do anything.
  182.     new:            (n:)    -- Doesn't do anything. Use D64ImageFS instead.
  183.     rename:new=old        (r:...)
  184.     scratch:file1,file2,...    (s:...)
  185.     validate        (v)    -- Doesn't do anything. Use D64ImageFS instead.
  186.  
  187. 2) Direct access-commands:
  188. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  189.  
  190. These commands access a disc image directly. These will always access the _first_ object
  191. on VC1541$Path so if you want to use these commands make sure this object is a disc
  192. image! If it isn't... well, there shouldn't be any data loss or real hazards but avoid
  193. it anyway.
  194. In the following "c" stands for the channel (secondary address), t/s for track/sector,
  195. n for the Floppy number (usually 0 - this is _not_ the Floppy _device_ number (8)) and
  196. p for a pointer position (0<=p<=255)
  197.  
  198.     block-allocate:n,t,s    (b-a:...)    Allocate a block
  199.     block-free:n,t,s    (b-f:...)    Free a block
  200.     block-read:c,n,t,s    (b-r:...)    Read a block into the buffer for channel c
  201.     block-write:c,n,t,s    (b-w:...)    Write a block from the buffer for channel c
  202.     buffer-pointer:c,p    (b-p:...)    Set the buffer pointer for channel c to p
  203.     user1:...        (u1:...)    Same as b-r
  204.     usera:...        (ua:...)    Same as user1
  205.     user2:...        (u2:...)    Same as b-w
  206.     userb:...        (ub:...)    Same as user2
  207.  
  208. b-r/w and the user-commands are not 100% identical on a real C64. This is another small
  209. incompatibility. But then I never had any _decent_ documentation on the Floppy's innards
  210. and it seems to work anyway.
  211. Like on a real C64 you can open a channel to a Floppy buffer by opening a file with the
  212. name "#". Unlike on a real C64 a buffer number (e.g. "#7") will be ignored, instead the
  213. next free buffer will be allocated. The number of buffers is currently limited to 4
  214. which should be more than enough within the limitations of the emulator.
  215. Important note: DO NOT CHANGE VC1541$Path WHILE A "#"-FILE IS OPEN! The reason is that
  216. upon opening such a channel the emulator checks whether the first object on VC1541: is
  217. a disc image and opens it if so. If you change the path you'll still read from the
  218. image you opened and I don't know what kind of stuff might turn up apart from that.
  219. Remember that changing the path is like changing a disc on a real C64 and don't do
  220. anything with the path where you wouldn't do anything with a disc!
  221.  
  222.  
  223.  
  224. LEGAL:
  225. ======
  226.  
  227. This unofficial patch is Freeware. You may copy and use it freely as long as no part
  228. of it is changed and it isn't sold for profit. The author will not be held responsible
  229. for any kind of damage resulting from using this patch. Use it entirely at your own risk!
  230. (It runs dead stable for me, BTW).
  231.  
  232.  
  233.  
  234. CONTACT:
  235. ========
  236.  
  237.  
  238. Andreas Dehmel
  239. Am Schorn 18
  240. 82327 Tutzing
  241. Germany
  242.  
  243. dehmel@informatik.tu-muenchen.de
  244.  
  245.  
  246.  
  247.  
  248. "Exalt!
  249.  The queen of death-white winter enthroned
  250.  Evil-resplendent, in dusk red seething skies
  251.  Foam-flecked nightmares drag a moon
  252.  of Draconian design."
  253.  
  254.     (Cradle of Filth - Queen of Winter, throned)
  255.