1atari++(6) Games Manual atari++(6)
2
6 atari++ - a versatile extended emulator of Atari 8 bit machines
7
9 atari++ [-option value [-option value]...]
10
12 atari++ is an emulator for (now rather aged) Atari 8 bit computers. It
13 emulates the Atari800, Atari400, the 800XL and 600XL, the 65XE and
14 130XE and the Atari 5200 Game Console. The emulation is cycle-precise,
15 that is “on the fly” modifications of chip registers will be visible on
16 the screen immediately, emulating even programs using horizontal kernel
17 tricks correctly.
18 atari++ includes also emulation of an extended 1050 disk-drive, capable
20 of single, enhanced and double density and adds some frequent exten‐
21 sions found in third-party hardware. The disk drive emulation supports
22 disk images in the xfd and atr file format, and is also capable of
23 loading binary load files (so called exe files) by emulating a mini
24 Game-DOS whose disk layout is similar to Dos 2.0S. Most exe files
25 wouldn't require to be loaded from a regular DOS therefore. As a bonus,
26 the emulation also includes Matthias Reichl's “atarisio” interface,
27 allowing you to connect a real 1050 or 810 drive to the emulating PC by
28 means of a 1050-to-PC or ProSystem cable.
29 In case no Atari ROM image is available, atari++ emulates a standard
31 800XL/130XE ROM image that is sufficient to run almost all programs.
32 Note, however, that an emulation of the Basic ROM is not included.
33 Emulation of printers is included as well. Print-out text is forwarded
35 to the standard printer tool, which defaults to the lpr printer front-
36 end. The print-out command can be adjusted by means of the command line
37 options and the configuration files (see below).
38 Additional features include emulation of the 850 serial/parallel inter‐
40 face box, a screen-snapshot, a complete machine state save and load
41 feature that allows you to stop and replay a game in a later session
42 and sound support by the Open Sound System (Oss) or Alsa sound drivers.
43 Furthermore, to aid the developer, a simple system monitor using a
45 curses terminal front-end has been integrated into the emulator. It
46 offers several features not available on the real hardware, as single
47 stepping thru programs and setting breakpoints, even in ROM code.
48 Graphics output is either emulated within an X11 window, or - if avail‐
50 able - with the SDL library. As last resort, and for special applica‐
51 tions, some ports provide a curses front-end that renders its output in
52 textual form on a console. Alternatively, the emulator can also be
53 instructed to read and write input to the operating system editor
54 device directly to and from the console, i.e. the standard input and
55 output streams of the program. This is not implemented as a new type of
56 front-end, but rather as an operating system patch.
57
60 Quite untypical for unixoid systems, the atari++ options are not case
61 sensitive, upper and lower case won't matter. Furthermore, the order of
62 the command line arguments doesn't matter as well. The following
63 options are supported:
64 --help prints all available options to the console. NOTE: Due to the
66 dynamic build-up of the atari++ components, the options these
67 components become only available if the corresponding component
68 is activated as well. E.g, you won't see the X11 options with
69 the SDL front-end activated.
70 -h similar to the above.
72 All following options are of four kinds: Numerical options taking
74 exactly one number as argument. They typically accept only numbers
75 within a limited range. Boolean options, taking the strings on yes or
76 true as positive and off , no or false as negative choices and string
77 options that take either a file or a string as value. Last but not
78 least, selective options that pick one out of several possible, mutu‐
79 ally exclusive choices.
80 On the Fly Configuration
83 Atari++ provides a quick and a complete menu to setup or modify its
84 configuration on the fly. For the quick menu, press and hold the left
85 mouse button within the emulator window, and pick an apropriate option
86 from the menu on the screen. This menu provides the most-used options,
87 namely to load and boot a disk, to pick a cartridge or to reset the
88 emulated Atari.
89 The full menu is either available as an option within the quick menu,
91 or by pressing the F1 key on the keyboard. The options presented there
92 are identical to the options listed below.
93 NOTE: The quick menu is not available in case the mouse has been arbi‐
95 trated to emulate a joystick or any other kind of input device. You'd
96 need to enter the full menu by the F1 key to adjust the configuration
97 in this case.
98 Global Options
101 This set of options does not belong to a specific part of the emulation
102 core, but rather influence the emulator as a whole.
103 -h or --help
105 prints out the list of currently available options. This list
106 does, however, depend on the current configuration of the file
107 as options for modules that are currently not in use will not be
108 shown on this list. For example, if your .atari++.conf file
109 selects the X11 frontend for graphics output, the options for
110 the SDL graphics support will not be shown. Unlike all other
111 options, this option does not take an argument.
112 -config filename
114 Load an alternative configuration file into the emulator. This
115 will override the options from all other configuration files,
116 but will be overridden by the command line arguments itself.
117 -state filename
119 Load a machine state snapshot file. This restores the machine
120 state of a previous atari++ session by re-installing the memory
121 conents and all hardware register settings of the previous ses‐
122 sion. For more details about the snapshot feature, see the SNAP‐
123 SHOT FILES section below.
124 Machine Type Options
126 The following options modify the overall emulation process, picks the
127 hardware to be emulated and the frontend how to perform graphics and
128 sound output.
129 -machine 800|1200|XL|XE|5200
131 Sets the type of machine to emulate. This is a meta-option that
132 sets suitable defaults for several other options, still allowing
133 to override these defaults with further commands. Hence, you'd
134 be still able to run an Atari XL machine with the Os of the
135 Atari 800. The following models are available: 800 emulates the
136 Atari 800 and its derivative, the Atari 400. 1200 emulates the
137 Atari 1200XL. This is almost identical to the 800XL, except that
138 the default ROM image is different. XL emulates the Atari
139 800XL, the 600XL and the 65XE. XE emulates the Atari 130XE with
140 a total of 128KByte memory. Last but not least, the 5200 argu‐
141 ment selects the emulation of the 5200 game console.
142 -frontend X11|SDL|CURSES|NONE
144 Defines which graphical front-end should be used. Currently, the
145 X11 the CURSES and the SDL front-ends are supported. NONE is a
146 dummy front-end without any graphical or textual output that can
147 be used for playing music or related tasks. The installedevice
148 option is suggested to get minimal support from the console
149 using only stream-I/O. Note this type of redirection is not a
150 front-end option, but rather an optional operating system patch,
151 see OS Options below.
152 The X11 interface is only available for Unix based operating
154 systems, most notably Linux, while the SDL interface is cur‐
155 rently available on most ports. The latter is also able to run
156 in a full-screen mode that is more suitable for gameplay. Typi‐
157 cally, the SDL front-end provides better performance unless you
158 need to scale up the output with the -pixelwidth or -pixelheight
159 options. Then, X11 performs noticeably better. The CURSES front-
160 end requires only a terminal for rendering, but its graphics
161 capabilities are rather limited. Specifically, it is only able
162 to emulate text-based graphics modes and expects the built-in
163 font to render the output. The keyboard mapping for the CURSES
164 output is also slightly different, see the CURSES section for
165 details.
166 -sound HQOSS|OSS|WAV|SDL|ALSA|DIRECTX
169 Sets the audio front-end used to generate audio output. For the
170 OSS and HQOSS front-ends, an Open Sound System compatible driver
171 is required, or no sound whatsoever will be available. Sound
172 synthesis will be very close to the real sound output and will
173 be at good quality, though some CPU power is required to guaran‐
174 tee continuous output without dropouts. In general, the HQOSS
175 driver is preferably since it requires less precise implementa‐
176 tions of the Oss standard and provides excellent quality for
177 synthesized speech.
178 The main intention of the WAV front-end is to record the sound
180 output as sampled sound in a .wav encoded file in optimum qual‐
181 ity. To allow you to listen to in-game sounds, this front-end
182 also offers a “play-back” option that also generates sound out‐
183 put thru an OSS compatible sound output, though this output is
184 of less quality than that of the dedicated HQOSS module. Even
185 though the play-back sound may contain some “blips” or drop-
186 outs, the quality of the recorded audio within the .wav file
187 will be perfect and very close to the original.
188 The SDL audio generation comes close in quality to that of the
190 HQOSS driver, though it is more likely to generate drop-outs for
191 highly loaded systems. SDL is the best in portability as SDL
192 exists on a variety of systems. The SDL driver also emulates
193 software speech correctly.
194 The DIRECTX driver is obviously available only for win32 compi‐
196 lations and uses the DirectSound interface of the DirectX sys‐
197 tem. This is the prefered sound system under Windows as it
198 offers lowest latency at best quality.
199 Finally, the ALSA front-end uses the state of the art ALSA sound
201 drivers for linux and provides optimal sound quality at minimal
202 CPU load. It provides similar or better quality than the HQOSS
203 front-end at less complexity, but it requires ALSA support,
204 nowadays almost universally available.
205 -monitoroncrash bool
208 If this boolean option is enabled, then the emulator enters
209 automatically the built-in monitor in case the 6502 CPU crashes
210 due to a corrupt program. Note that these crashes are not due to
211 bugs in the emulator, but rather due to flaws in the emulated
212 program, i.e. a “real” Atari would have crashed in the same sit‐
213 uation. If this option is disabled, then a warning gets printed
214 and the user menu is entered. It is then up to you to either
215 reset the emulation or to launch the monitor manually. This
216 option defaults to false ,i.e. the monitor is not entered by
217 itself.
218 For details about the system monitor, see the MONITOR section
220 below.
221 -acceptlicence bool
224 If enabled, then it is understood that you read and agreed to
225 the licence conditions under which Atari++ is delivered, and the
226 licence conditions are no longer presented on startup.
227 -stereopokey bool
230 Toggles the “dual Pokey” hardware hack emulation. This hardware
231 hack installs a second Pokey at base address $d210 into the sys‐
232 tem, allowing stereo sound emulation. Atari++ provides then a
233 second Pokey chip named “ExtraPokey” that otherwise takes the
234 same configuration arguments than the first Pokey does, though
235 this second chip is not connected to the serial output and the
236 keyboard.
237 NOTE: The second Pokey chip is fully functional and also pro‐
239 vides interrupts. Since the Atari Os is not aware of this chip,
240 it cannot handle these interrupts. Thus, programs might crash if
241 interrupts of this extra chip are erraneously enabled. This is
242 not the fault of the emulator, a real system would crash under
243 the same circumstances.
244 CPU Options
247 The following options control the emulation of the 6502 CPU:
248 -wsyncpos 80..114
250 A technical option that defines the horizontal position where
251 ANTIC releases the CPU if it has been formerly blocked by a STA
252 WSYNC. This is counted in CPU cycles clocks from the falling
253 edge of the horizontal sync. It defaults to 105 cycles and is
254 adjustable within a range of 80 to 114 color clocks.
255 -traceonreset bool
257 This boolean option is useful for debugging. If enabled with the
258 on argument, the CPU enters trace mode on a reset, entering the
259 build-in monitor immediately.
260 -traceinterrupts bool
262 Another debugging related option. If this is enabled, instruc‐
263 tion stepping will also step into interrupt routines as soon as
264 an interrupt gets detected. This might cause some confusion
265 because surprisingly the 6502 CPU will continue execution from a
266 completely different place, though it is helpful to find bugs in
267 display list interrupts.
268 -cputype 6502|WD65C02
270 Selects the CPU type that is emulated. The WD65C02 offers a cou‐
271 ple of addtional addressing modes and instructions that are sup‐
272 ported by a couple of products, e.g. the Mac/65 assembler car‐
273 tridge.
274 GTIA Options
277 The following options modify the emulation process of the video signal
278 generator, the Graphics Television Interface Adaptor chip:
279 -videomode PAL|NTSC
281 Defines whether the emulated GTIA should either identify itself
282 as PAL or as NTSC chip. Some games read this value and modify
283 their timing accordingly. This option also changes the color map
284 GTIA sends to the front-end as colors differ slightly between
285 the PAL and the NTSC version of GTIA.
286 -ChipGeneration CTIA|GTIA|XLGTIA
288 Selects the chip generation to emulate. CTIA selects the old
289 first generation used in some very early 800 and 400 models.
290 This chip did not provide the special 16 hue/16 luminance and 8
291 color modes, BASIC modes 9 to 11. GTIA selects the second gen‐
292 eration, used in most 800 and 400 models, and XLGTIA the third
293 generation in the XL series. The last two chips do actually not
294 differ, only the surrounding analog circuits change the color
295 artifacts slightly, which is the only noticable difference
296 between them.
297 -artifacts bool
299 This boolean option controls whether GTIA should emulate color
300 artifacts that are caused by video system. If set to on , the
301 video rendering will detect hi-lo and lo-hi transitions for
302 high-resolution graphics and text mode and will generate pseudo-
303 colors similar to a real TV. These artifacts are limited to NTSC
304 systems for the real hardware and are not as effective nor very
305 visible for the PAL hardware; the emulator, however, displays
306 them regardless of the emulated video mode. Some games require
307 this setting to look properly. If set to off , artifact genera‐
308 tion is disabled as for a higher quality monitor or for the PAL
309 video system. This also makes text more readable and less
310 blurry, it also speeds up the emulation process somewhat and is
311 better suited for text-oriented software.
312 -palcolorblur bool
314 enables emulation of a feature of the PAL video system standard
315 that can be used to create additional colors by mixing. If two
316 adjacent horizontal lines on top of each other share the same
317 intensity but have a different hue, then the mixture of the col‐
318 ors appears instead of two separate colors. This option is com‐
319 putationally a bit complex and requires a true color display,
320 i.e. a color depth of 24 bit to be effective.
321 -antiflicker bool
323 enables the Atari++ flicker fixer. Some programs create addi‐
324 tional colors by quickly altering the colors forth and back,
325 causing the mixture of the colors due to the slowness of the TV
326 screen. PC monitors are typically much faster, causing an anoy‐
327 ing flicker for these programs. This switch enables a flicker-
328 fixer that mixes the colors already in the GTIA display genera‐
329 tion at the price of a higher complexity. This option also
330 requires a true-color display, i.e. a bit depth of 24 bit.
331 -playerallocate 0..32
333 this setting controls the number of half-color clocks required
334 by the GTIA player/missile logic to get aware of a player/mis‐
335 sile horizontal position change. This is the minimal horizontal
336 displacement between writing to a player/missile register and
337 the first visible pixel of a player on the screen. If the modi‐
338 fication of the register happens closer to the horizontal posi‐
339 tion than the indicated amount, GTIA will not get aware of the
340 change and will delay the change to the next scanline. The
341 default value for this setting is 12, i.e. it takes 12/4 = 3 CPU
342 clocks before a player/missile horizontal position change takes
343 effect.
344 -playerrelease 0..32
346 the number of half-color clocks before a player/missile channel
347 can be re-used on the same scanline. That is, the distance from
348 the first visible pixel of a player to the first possible hori‐
349 zontal position where the CPU can write again into the same reg‐
350 ister to take an effect on the screen. The default for this set‐
351 ting is 8, thus it takes two CPU cycles before a player or mis‐
352 sile can be re-used.
353 -colormapname filename
355 requires a filename to a color map to be used instead of the
356 default PAL or NTSC color map. The color map file must be
357 exactly 768 bytes long and contains for each Atari color a red,
358 green and blue color triple, eight bits per channel.
359 -playertrigger.0 all|players|missiles|none
361 The first out of four otherwise identical options sets the abil‐
362 ity of player zero to generate collisions with other objects on
363 the screen. Note that this does not change the ability of player
364 zero to detect collisions itself, though. It just removes the
365 ability of other players or missiles to collide with it.
366 If this option is set to all, then player zero can create colli‐
368 sions with all other objects, for the players setting, only col‐
369 lisions with other players are generated and missiles never see
370 any collisions with player zero. For the missiles setting, the
371 situation is reversed and only missiles can detect collisions to
372 player zero. Finally, for the none argument, player zero gener‐
373 ates no collisions at all.
374 -playertrigger.1 all|players|missiles|none
376 works similar to the above except that it changes the ability of
377 player one to generate collisions.
378 -playertrigger.2 all|players|missiles|none
380 changes the abilities of player two and, finally,
381 -playertrigger.3 all|players|missiles|none
383 modifies the collision abilities of player three.
384 Note that there are no options to modify the collision abilities
386 of a missile since it has none in the real hardware. A missile
387 can never create a collision with a player itself, or any other
388 object. Rather, the situation is somewhat reversed from the
389 expected logic: A player creates a collision to a missile, and
390 hence, its ability to collide with missiles must be turned off
391 to avoid detection of player-missile collisions.
392 -playfieldtrigger.0 all|players|missiles|none
394 Modifies the abilities of playfield zero, i.e. the first fore‐
395 ground color, to generate collisions to other objects. Similar
396 to the above set of four options, playfields can be allowed to
397 generate collisions to all objects, players only, missiles only
398 or no objects at all.
399 -playfieldtrigger.1
401 Triggers the ability of playfield one to generate collisions;
402 otherwise, similar to the above.
403 -playfieldtrigger.2
405 The same again for playfield two.
406 -playfieldtrigger.3
408 the same once again for playfield three.
409 ANTIC Options
412 The following options control the DMA controller and the playfield
413 graphics generator chip:
414 -videomode PAL|NTSC
416 This option is intentionally identical to the GTIA option of the
417 same name and controls the video system ANTIC should emulate. As
418 for ANTIC, this switch controls the height of the video output.
419 For PAL , a total of 312 lines is generated, and for NTSC , only
420 262 lines of output are displayed. Note that not all lines are
421 available for graphics as the vertical retrace takes up some of
422 them.
423 -beforedlicycles 0..16
425 This option controls the number of CPU cycles from the end of
426 the horizontal blank to the falling edge of the NMI interrupt
427 signal when a display list interrupt is generated, and thus the
428 number of cycles ANTIC requires to decode the display list and
429 to generate the DLI signal. This is a very technical setting and
430 usually should not be required to be adjusted. It defaults to 12
431 CPU cycles.
432 -beforedisplayclocks 0..32
434 Controls the number of CPU cycles, in total, from the end of the
435 horizontal blank to the first visible display cycle. This set‐
436 ting controls the placement of horizontal kernel modifications
437 on the screen since it defines the relative placement of the CPU
438 to the GTIA display generation. The default for this value is 16
439 CPU cycles.
440 -yposinccycle 104..114
442 This setting defines the horizontal cycle position at which the
443 vertical line counter gets incremented, and thus defines the
444 start of the horizontal blanking signal. By default, this hap‐
445 pens at cycle 108.
446 POKEY Options
449 The next set of options influences the sound generation. For sound out‐
450 put, the Open Sound System driver for your sound card, more specifi‐
451 cally, /dev/dsp must be available. Alternatively, sound output can be
452 written into a .wav file and replayed later by a suitable tool, e.g.
453 XMMS. Alternative sound outputs are SDL or Alsa , depending on their
454 availibility. See the Machine Settings section for more details.
455 The following set of switches will not change the output of the sound,
457 but rather the emulation of the POKEY chip generating the audio signal
458 that is further processed by the OSS module described below.
459 NOTE: If the “stereopokey” emulation is enabled, a second set of Pokey
461 control options appears under the topic “extrapokey”. This set is iden‐
462 tical to the set described here.
463 -volume 0..300
466 Controls the overall volume of the POKEY output in percent com‐
467 pared to normal output. 300% is loudest and 0 disables the out‐
468 put. The default is 100%.
469 -gamma 50..150
471 Controls the output linearity of the POKEY D/A converter in per‐
472 cent. 100% is a perfectly linear output (provided the sound card
473 output is linear). Values smaller than 100% cause sublinear
474 behaivour (high amplitudes appear smaller than they should),
475 values higher than 100% cause superlinear characteristics (high
476 amplitudes are louder than they should). Real pokey chips typi‐
477 cally show sublinear characteristics with a gamma value around
478 70% to 80%.
479 -videomode PAL|NTSC
481 Even though Pokey is not a video interface circuit, its timing
482 is controlled by the system base frequency which is related to
483 the video mode. This option controls whether Pokey should find
484 itself in a PAL or NTSC system; it changes the audio base fre‐
485 quencies slightly.
486 -siosound bool
488 Enables or disables the serial transfer sound, provided the
489 siopatch is not enabled and bypasses hardware driven serial i/o.
490 This option enables a more complete Pokey emulation by also tak‐
491 ing care of the serial transfer modes for generating sound.
492 Thus, you get the very unique “Atari sound effects” for all
493 kinds of disk access.
494 -cycleprecise bool
496 Controls wether the Pokey emulation works cycle-precise, that
497 is, whether pokey interrupts and potentiometer registers are are
498 updated and queried on a cycle by cycle basis. This allows a
499 more precise emulation, though it also requires more computing
500 power.
501 -filterconstant 0..1024
503 controls the time constant for an optional high-pass filter that
504 is applied to the audio output signal generated by the Pokey
505 emulation. This high-pass filter cancels any DC offset in the
506 sound generation that might cause trouble for audio cards or
507 amplifiers, especially when the audio output level is close to
508 the maximum. The lower the filter constant, the more frequencies
509 are cut-off by the filter. Setting the filter constant to zero
510 disables the filter. The default setting is 512.
511 PIA Options
514 The following set of options modify the emulation of the Peripheral
515 Interface Adapter chip.
516 -mathpackcontrol bool
518 enables control of the MATHPACKDISABLE signal thru bit 6 of PIA
519 port B. This function is only required for some dedicated hard‐
520 ware of the author of this program and should be otherwise left
521 alone.
522 MMU Options
525 The following options control the features of the Memory Management
526 Unit. For the 800 and 400, no real MMU chip has been used. Rather, the
527 MMU is a set of standard logic gates that control the memory map of the
528 system. From the 800XL and up, all these gates have been integrated
529 into a dedicated hardware chip called the MMU. Regardless of these
530 technicalities, the memory management logic is controlled by the fol‐
531 lowing options:
532 -4kextended bool
534 Enables additional 4K of memory in the range of 0xc000..0xd000
535 for the Atari 400 and 800 models. For the XL and XE, this memory
536 region contains parts of the ROM and is never available. For the
537 400 and 800, this region is otherwise blank.
538 -axlonram bool
540 Enables emulation of Axlon type RAM expansions that are con‐
541 trolled by address 0xcfff. These RAM disks have pages of 16K
542 each that are mapped into the memory from 0x4000 to 0x8000.
543 -axlonbankbits 0..8
545 Defines the number of bits within the page control port 0xcfff
546 of the Axlon RAM disk emulation used for the page selection. The
547 more bits are enabled, the more banks are available. Each addi‐
548 tional bit doubles the number of 16K banks.
549 -xebankbits 0..8
551 This option is only available if the emulator is setup to the
552 130XE machine type. Then, it defines the number of PIA port B
553 RAM bits used to define the selected/active bank. The 130XE uses
554 two bits for selecting the bank, and hence has four pages of
555 16K, making a total of 64K extended RAM. Note that the more bank
556 bits you enable here, the less compatible the resulting emula‐
557 tion will be to a “straight” 130XE. Specifically, you loose the
558 proprietry PIA Port B “MathPackDisable” at three bits, the self‐
559 test at four bits, the Basic ROM at five bits, separate Antic
560 access at six bits, OS Rom mapping at seven bits and CPU access
561 control at eight bits.
562 OS Options
565 The following options control the emulation of the Operating System ROM
566 and related features, most notably various Os patches that are
567 installed into it. NOTE: Original Atari ROM images are not included in
568 the distribution of Atari++ due to copyright restrictions, but Atari++
569 provides an Os emulation that works as well in most cases. This does
570 not, however, implement a Basic ROM.
571 -osapath filename
573 Gives the location of the OS A ROM image. This file contains a
574 simple dump of the memory area 0xd800..0xffff of the original
575 first revision Os of the Atari 800 and 400, or a dump from
576 0xf800..0xffff for the 5200 console.
577 -osbpath filename
579 Specifies the location of the second revision for the Atari800
580 and 400 ROM image file.
581 -os1200path filename
583 Specifies the location of the Atari 1200XL ROM image. This is an
584 early version of the Atari 800XL image with some ROM bugs the
585 emulator has to keep care of.
586 -osxlpath filename
588 Specifies the location of the Atari 800XL and later model ROM
589 image. This ROM image contains the memory areas 0xc000..0xd000,
590 the self-test that can be mirrored to 0x5000..0x5800, and the
591 math-pack and the upper ROM area from 0xd800 to 0xffff, in that
592 order. This is also the natural order within the real ROM chip,
593 which is twice as large as for the former Atari models.
594 -os5200path filename
596 specifies the location of the 5200 ROM image.
597 NOTE: If no ROM image is available, the built-in ROM will be used. This
599 ROM is an XL/XE operating system only and thus requires a the 800XL
600 machine type for proper emulation.
601 If none of the above options have been given on the command line, then
603 Atari++ will try to locate them itself, or fall back to the built-in
604 ROM if it is unable to find any ROM. It therefore looks into the direc‐
605 tory “roms” in the current directory. For the XL operating system, it
606 tries to find a file named “atarixl.rom” in this directory. For the Os
607 A resp. Os B image, files named “atariosa.rom” resp. “atariosb.rom” are
608 searched, and loaded if found.
609 -ostype Auto|OsA|OsB|Os1200|OsXL|5200|BuiltIn
611 Defines which kind of ROM shall be loaded into the system. Note
612 that this need not to be identical to the type of machine you
613 are emulating, even though this is the default and probably the
614 most useful selection. The 5200 console is an exception: Its ROM
615 will not be accepted by anything but the 5200 machine, and any
616 other machine type will not accept the 5200 ROM. This is because
617 the mapping of the hardware differs between the “regular” Atari
618 8 bit systems and the 5200 console, making the ROMs non-porta‐
619 ble.
620 The “builtin” option selects the built-in ROM emulation that
622 implements a fully-features 800XL/130XE ROM. This ROM emulation
623 is used if no other ROM image is found. More on this ROM image
624 in the “Os Emulation” section below.
625 The “Auto” option, which is the default, does not select a spe‐
627 cific ROM, but rather picks a suitable rom image for the
628 selected machine.
629 -installpdevice bool
632 Selects whether a patched P: device handler should be installed
633 that redirects printer output directly to the printer component.
634 If this patch is not installed, printer emulation will be re-
635 routed thru the SIO emulation described below. This will work as
636 much as this direct patch, but might be somewhat slower.
637 -installrdevice bool
639 Installs optionally an RS232 interface box handler for serial
640 transfer. On a real Atari, this handler would be loaded from the
641 interface box by a tiny bootstrap code that is usually part of
642 an “AUTORUN.SYS” or “HANDLERS.SYS” file; even though this boot‐
643 strapping is also emulated, the resident handler patched in by
644 this option has the advantage that it doesn't take up any RAM
645 space, unlike the handler provided by the interface box emula‐
646 tion itself. However, in case a program tries to trick around
647 with the interface box, the bootstrapped 6502 based handler pro‐
648 vides closer emulation than the native emulation implemented by
649 this option. Otherwise, the native emulation and the 6502 imple‐
650 mentation provided by the emulated 850 interface box are func‐
651 tionally identical.
652 Note further that this option only installs the CIO emulation
654 layer of the 850 interface box. You still need to enable the
655 interface box itself with the “-Enable850 on” option.
656 -installhdevice bool
658 If enabled, the C: cassette handler is replaced by an emulator
659 specific H: (Host) handler that mirrors parts of the host filing
660 system into the emulator. The H: device understands all major
661 CIO commands and most XIO commands, following the conventions of
662 DOS 2.0S, e.g. RENAME and LOCK XIOs are available by its DOS
663 2.0S command IDs. More about the H: device can be found below in
664 a specific section.
665 -installedevice bool
667 This option installs a specific patch which replaces the operat‐
668 ing system editor device, E: and to some degree, the keyboard
669 device, K: by emulator specific routines that redirect input and
670 output from and to the operating system handler to the standard
671 input and output streams. That is, instead of typing into the
672 emulator window, keyboard data is read from the standard input,
673 and output to the editor device is echoed on the console. In
674 addition, the editor device stream also goes to the front-end of
675 the emulator. Note that this mode relies on the line-buffering
676 of the console and does not provide a full-screen editor unlike
677 the Atari. You cannot move the cursor back to a previous line
678 and re-enter it. Furthermore, input will not be seen by the emu‐
679 latur until you press RETURN at the end of the line, and only a
680 very limited set of control characters, namely those standard‐
681 ized in ANSI-C, will be transposed from ASCII to ATASCII. For
682 example, cursor movement sequences, which are console-specific,
683 are not available with this patch. The major purpose of this
684 patch is to script the emulator, less to redirect I/O to a ter‐
685 minal. For that, consider the curses front-end.
686 -installhasdisk bool
689 Changes the device letter under which the host handler will be
690 installed. By default, the handler will be called H:, but if
691 this flag is set, then the handler will be inserted as D: giving
692 you emulated disk access. Programs that entirely access the disk
693 thru this handler, for example BASIC programs, will then run off
694 the host filing system.
695 -h1dir filename
697 Defines the directory where the first unit of the H: device
698 should be anchored. Files in this directory are accessible thru
699 H1: or H:, provided the host handler is patched in by the option
700 above.
701 -h2dir filename
703 Specifies the anchor path for the second unit of the H: handler,
704 accessible by H2:.
705 -h3dir filename
707 The host directory for the third unit of the H: handler.
708 -h4dir filename
710 Finally, the directory for the fourth unit of the host handler.
711 -siopatch bool
713 If enabled, then serial input/output handling is routed thru an
714 Os patch to the emulated devices directly instead of using the
715 detour thru the POKEY emulation and the emulation of the serial
716 port. This speeds up serial access, especially disk drive
717 access, noticeably, but might cause compatibility problems with
718 some critical software that expects precise timing and exact
719 behavior of the serial hardware.
720 -installmathpatch bool
722 Installs optionally a series of patches into the MathPack module
723 of the operating system; this part of the Os is responsible for
724 floating point support and is used heavely by AtariBasic and
725 other programming languages. This patch replaces the ROM based
726 math routines by custom patches that make use of the host system
727 FPU instead, hence speeding up any kind of floating point opera‐
728 tion dramatically. Due to the limited precision of both the
729 Atari floating point model and the host system floating point
730 system, computations performed by the orginal MathPack might
731 differ slightly from the results obtained from the patch, though
732 the difference is typically neglectible and below the precision
733 of the MathPack itself.
734 KEYBOARD Options
737 The following set of three options relates to the way how Atari++ uses
738 the host system keyboard to emulate the Atari keyboard. They currently
739 only influence the emulation of the console keys which are strictly
740 speaking not part of the keyboard hardware of the Atari.
741 -holdoption bool
743 Defines whether the emulator shall emulate pressing the Option
744 key during the coldstart. The Atari XL/XE roms query the state
745 of this key during bootstrap and disable the built-in BASIC rom
746 in case the Option key is held down. Hence, this option should
747 be set to be able to play (non-BASIC) games on an emulated XL/XE
748 system.
749 -holdselect bool
751 Defines whether the Select console key shall be pressed during
752 the cold start process. No known Os currently evaluates the
753 state of this key on bootstrap, though.
754 -holdstart bool
756 Similar to the above, enables or disables the activation of the
757 Start console key on coldstart. This signals a boot process from
758 the tape recorder, though tape emulation is currently not sup‐
759 ported by the emulator.
760 -bufferkeys bool
762 Atari++ comes with a smart keyboard type-ahead buffer that
763 allows you to type faster than the original Atari hardware is
764 able to react. Unrecognized keys are buffered until the emulator
765 is able to fetch them. While this feature helps a lot when pro‐
766 gramming on the emulator, fast gameplay using the keyboard as
767 input device might become more problematic if keys are delayed
768 rather than swallowed.
769 -keybutton.0.enable bool
771 This option is only available for the Atari 5200 emulation; it
772 allows the generation of 5200 “keyboard” events thru joystick
773 buttons. If this specific option is enabled, the '0' key on the
774 Atari 5200 keypad can be connected to a joystick button, similar
775 options exist for all other numeric keys as well as for the
776 haskmark and the asterisk, named “keybutton.hashmark.enable” and
777 “keybutton.asterisk.enable”, respectively.
778 -keybutton.0.button 1..4
780 If the above option is enabled, this option controls which of
781 the virtual buttons of a joystick type device is used to trigger
782 the keyboard event for the '0' key on the 5200 keypad. The but‐
783 ton numbers required here do not directly relate to the hardware
784 numbering of the Os specific joystick device, but they rather
785 refer to the button event numbers used by the analog joystick
786 interfaces of Atari++. The “First_Button” option of this device
787 then defines which hardware button is responsible for generating
788 the virtual button 1 events, and so on.
789 Similar options exist for the keypad buttons 0 to 9, and for the
791 asterisk and the hashmark, namely as “keybutton.hashmark.button”
792 and “keybutton.asterisk.button”.
793 -keybutton.0.sensitivity 0..32767
796 controls the sensitivity of the reaction, i.e. the minimum
797 amplitude of the button input required to trigger the keyboard
798 event. Since buttons are usually digitial, this option can be be
799 left alone in most cases. Similar options exist for the remain‐
800 ing keypad buttons.
801 -keybutton.0.port devicename
804 defines the input device for the Atari 5200 keypad '0' button.
805 This device is setup in the very same way as for the JOYSTICK
806 emulation and we refer to this chapter instead. Similar options
807 exist for all other keypad keys.
808 CARTRIDGE Options
811 The next set of options allows to insert a cartridge into the emulated
812 cartridge slot of the system. Currently, only the left cart slot of the
813 Atari 400 and 800 , resp. the one and only cart slot of all later mod‐
814 els is emulated.
815 -cartpath filename
817 specifies the filename of the cartridge image to load.
818 -carttype none|8k|16k|32k|oss|ossb|sdx|xegs|bounty‐
820 bob|flash|megarom|atrax
821 specifies the type of cartridge to load. Unfortunately, the emu‐
822 lator cannot figure out the cart type itself in all cases just
823 by looking at the image file. Therefore, this option has to be
824 given along with the option above.
825 None is a dummy option that just disables the cart, and hence
827 ignores the above option altogether.
828 8K emulates an 8K sized plain cartridge that is mapped into the
830 memory from 0xa000 to 0xbfff.
831 Right8K this cartridge type is only available for the Atari800
833 hardware type and emulates a cartridge for the right cart slot
834 of this system that gets mapped to the area 0x8000 to 0x9fff.
835 16K emulates a plain 16K cart occupying the memory region from
837 0x8000 to 0xbfff.
838 32K emulates 32K cartridges of the 5200 game system. This option
840 and the 32K rom images will not be accepted for all other
841 machine types and hence remains unavailable then.
842 32KEE16 emulates a 5200 game system cartridge with a 16K sized
844 image file with incomplete addressing that occupies 32K ROM
845 space.
846 Debug32 emulates a 32K debug cartridge for the 5200 game system
848 with two 16K banks mapped into the area from 0x8000 to 0xbfff.
849 Oss emulates an Oss super cartridge that is mirrored into the
851 memory map from 0xa000 to 0xbfff, but is 16K sized internally.
852 The cartridge therefore provides a bank-switching mechanism thru
853 the CARTCTRL system component, as it consists internally of two
854 ROM chips, called RomA and RomB in the following. The lower
855 region 0xa000 to 0xafff is variable and can be bank-switched,
856 the upper region 0xb000 to 0xbfff is hard-wired to the upper
857 part of RomA. The following table shows the mapping for the
858 lower region:
859 CartCtrl Port Rom mapped at 0xa000 to 0xafff
862 ─────────────────────────────────────────────────────────
863 0xd500 RomB Lo
864 0xd502 or 0xd506 Blank
865 0xd501,0xd503 or 0xd507 RomA Lo
866 0xd504 or 0xd509 RomB Hi
867 0xd508 and up disable cart
868 OssB is also an Oss super-cart except that the cartridge ROM has
870 been dumped to disk in a different order and hence the address‐
871 ing of the cartridge ROM contents is different. If the Oss
872 option does not work, try this option instead.
873 SDX emulates a 64K large ROM image with eight banks mapped into
875 the region of 0xa000 to 0xbfff.
876 EXP a variant of the SDX cartridge with a slightly different
878 bank switching logic.
879 Diamond another variant of the SDX cartridge type with just
881 another bank switching logic.
882 XEGS emulates a variable size XEGS cartridge. This cart type
884 occupies 16K of memory within the address space of the 6502 CPU
885 but consists of several banks that can be mapped into the
886 0x8000...0x9fff region.
887 ExtXEGS a mildy extended version of the XEGS cartridge type that
889 additionally allows disabling the cartridge.
890 BountyBob emulates the 40K sized BountyBob cartridge for the
892 5200 games system. This cartridge uses a very unique bank
893 switching mechanism that requires its own emulation provided by
894 this option.
895 Flash Emulates Steven J. Trucker's “AtariMax” flash ROM cart.
897 This is a 128K or 1MB cart with bank-switching logic that is
898 mapped into the 0xa000...0xbfff region. This cart type allows
899 flashing, and thus the cart ROM can be modified by the emulation
900 process. The emulator will ask you to save back the cart image
901 as soon as the cart shall be removed again.
902 MegaROM Emulates the various types of the Mega ROM cartridges.
904 These carts come in varous sizes and map in as 16K banks in the
905 area of 0x8000...0xbfff.
906 Atrax Emulates the 128K bank switching Atrax cartridges that map
908 in as 8K banks in the area of 0xa000...0xbfff.
909 Will Another super cartridge type of 32K or 64K size that maps
911 its 8K sized banks into the area of 0xa000 to 0xbfff.
912 Phoenix This type emulates the Phoenix and Blizzard super car‐
914 tridges. The first is a regular 8K cart that can be disabled,
915 the latter is a 16K switching cart. Both are emulated by the
916 same cart type.
917 ATMax A super cart that comes as 128K or 1MB cartridge.
919 -rtime8 bool
922 enables or disables the emulation of the RTime-8 pass-thru car‐
923 tridge. This this a cartridge rom that contains a battery
924 buffered real-time clock and passes the cartridge slot connec‐
925 tions thru to be able to use the real-time clock together with
926 other cartridges. The default is not to enable the real-time
927 clock cartridge.
928 CARTFLASH Options
931 The flash cartridge type is the only cart type that can be configured
932 by the command line and the GUI. Currently, there is only a single
933 option available, namely:
934 -enablecartflash
937 If this option is disabled, the flash cartridge mapping will be
938 disabled on the next reset. However, the cart still receives the
939 bank mapping signals and thus can be re-enabled by software.
940 This is useful if you want to re-flash the cartridges by Steve
941 Trucker's flashing software: Just disable this switch, insert
942 the flash software disk, and reboot. The cart will be disabled,
943 the Atari will boot from the inserted disk, and the flash soft‐
944 ware will re-enable the cartridge, allowing you to overwrite its
945 contents. To write the cart image back to disk, change the car‐
946 tridge type to “none” or insert any other cart.
947 BASIC Options
950 The following options control the function of the BASIC Rom of the
951 Atari 800XL and later models. Since the Atari 800 and 400 models do not
952 come with a built-in BASIC, these options are ignored for the earlier
953 models; you'd need to insert the BASIC as a regular 8K cartridge for
954 them. Furthermore, whether the basic is mapped for the XL and later
955 series depends on whether the Option console key is held down during
956 bootstrap. This option is part of the keyboard options below, even
957 though it influences the working of the basic ROM for the XL and XE
958 series.
959 -basicpath filename
961 Specifies the file name where the BASIC rom image shall be read
962 from. This is a simple 8K memory dump of the ROM appearing at
963 0xa000 to 0xbfff. NOTE: Due to copyright restrictions, no BASIC
964 ROM image is included in the distribution of Atari++.
965 -usebasic bool
967 Specifies whether the BASIC ROM shall be made available to the
968 emulator. If set to on, then the BASIC will be enabled. On the
969 XL or XE series, the Option console key must NOT be held down
970 during bootstrap as well to make the BASIC appear.
971 SIO Options
974 The Serial Input/Output module is a specific part of the operating sys‐
975 tem taking care of serial communication. The Atari++ emulation compo‐
976 nent of the same name hence controls the low-level emulation features
977 of all devices emulated on the serial port, hence the disk-drives and
978 the printer. The emulation of the serial port can be bypassed by the
979 -siopatch option described in the OS Option section above, giving a
980 noticeable speedup for disk-drive and printer, but possibly also caus‐
981 ing compatibility problems for software that depends on precise timing
982 or side-effects of the Os implementation. You usually need not to care
983 about the settings below as they closely match those of typical serial
984 hardware anyhow.
985 -serincmddelay 0..240
987 The amount of time taken by a serial device to accept a command
988 frame. This time is given in horizontal blanks. It defaults to
989 50 lines.
990 -readdonedelay 0..240
992 The time taken for a serial read command to complete. For the
993 disk-drive emulation, this would emulate the time required to
994 read a sector from disk up to the time where the first byte of
995 the sector arrives at the port. This setting also defaults to 50
996 lines.
997 -writedonedelay 0..240
999 Required time to complete a write command. For the disk-drive,
1000 this is the time taken from the last byte of a sector arriving
1001 at the drive up to the time where the disk-drive sends the
1002 acknowledgement frame. This setting defaults again to 50 lines.
1003 -formatdonedelay 0..1024
1005 Required time to format a disk in a disk-drive, measured as the
1006 time from issuing the command up to the time where the first
1007 byte of the sector status map arrives at the serial input. This
1008 is again given in horizontal lines. Since the Os assumes that
1009 the timing of formatting is a bit more relaxed than the regular
1010 reading time - yes, formatting is a read command for the Atari -
1011 this is a separate option, defaulting to 400 horizontal lines.
1012 PRINTER Options
1015 The next set of options controls the printer emulation. Commands and
1016 data enter this emulation either by the SIO, or directly by the P: han‐
1017 dler should it be patched into the Os. See the OS Options for more
1018 details about this.
1019 -printtarget tospoolcommand|tofile
1021 selects where printer output is sent to. For the tospoolcommand
1022 selection, printer output is piped into the printcommand
1023 selected by the option below. This is typically the “lpr” or
1024 “lp” command. For tofile , printer output is sent to a regular
1025 file. On some systems, this might be the only available option
1026 to print at all.
1027 -printcommand file
1029 Specifies the command used to print out text on the host system.
1030 The text arriving at the emulated printer will wait in a queue
1031 and will be flushed regularly, appearing at the STDIN of this
1032 command. Typically, this should be either lpr or lp , depending
1033 on the printing system you use at your machine.
1034 -printfile filename
1036 Specifies the file printer output is sent to should this type of
1037 output be selected. This is by default empty, disabling printer
1038 output completely, though the printer appears to be turned on.
1039 -appendtoprintfile bool
1041 defines whether the printer output file specified by the previ‐
1042 ous option is overwritten on each printer-output or the new out‐
1043 put is just appended at the end of it. By default, new printer
1044 output overwrites older printer dumps.
1045 -enableprinter bool
1047 Enables or disables the emulated printer. If set to off, the
1048 printer will not react on any SIO commands as if it has been
1049 turned off. Otherwise, printing will be allowed.
1050 -transposeeol bool
1052 The Atari doesn't use the regular LF character to separate lines
1053 on the printer output. Rather, it uses the character 0x9B (CSI
1054 in the ANSI set, named EOL on Ataris) to separate lines. Hence,
1055 for printing text, EOL has to be transposed into line feeds by
1056 this option, which is also the default. However, for graphics
1057 output, this character transposition will change the meaning of
1058 the graphics data send to the printer, and will hence distort
1059 the graphics. NOTE: Currently, Atari++ does not include the
1060 emulation of a graphics printer. All control and graphics
1061 sequences sent out to the emulated printer will be spooled
1062 directly into the print command without interpreting them fur‐
1063 ther.
1064 -flushdelay 0..60
1066 This specifies the delay in seconds from the last data arriving
1067 at the emulated printer until the collected text/graphics are
1068 printed out. Hence, if data is printed at a rate lower given by
1069 this delay, they will appear in separate spool jobs. This delay
1070 defaults to five seconds.
1071 SPEED Options
1074 The following set of options controls the timing of the emulator. Sev‐
1075 eral other factors influence the maximum speed, though. First of all,
1076 the graphical front-end of the emulator might be more or less perform‐
1077 ing. For full-screen emulation, the SDL front-end is performing pro‐
1078 vided no pixel upscaling is used. In all other cases, the X11 frontend
1079 offers higher speed. This is not the fault of the emulator, but rather
1080 a matter of the poor performance of SDL. Furthermore, the sound emula‐
1081 tion has some impact as well. For software speech emulation, high sam‐
1082 pling rates and slim buffers are a must, causing some software overhead
1083 and higher CPU loads. For maximizing the speed, either run the X11
1084 frontend on 1x1 or 1x2 pixel sizes and reduce the quality of the audio
1085 output.
1086 -unlockrate bool
1088 If this option is set to true, then a custom, non-standard frame
1089 rate can be selected that is not locked to the video mode (see
1090 below) of the emulated machine. The default is to disable this
1091 option and thus to lock the frame rate to the natural frame rate
1092 of the emulated machine.
1093 -framerate 1..100
1095 This option specifies the screen refresh rate, to be given in
1096 milliseconds per frame. A standard PAL screen with 50 frames per
1097 second requires 20 milliseconds per frame, a NTSC screen
1098 requires 17 milliseconds. This option defaults to 20, i.e. the
1099 PAL rate, but is ignored unless the frame rate is unlocked with
1100 the unlockrate switch above.
1101 -maxmiss 1..16
1103 Unlike the above, this option controls how much frames the emu‐
1104 lator may miss to keep the emulation speed. If this is set to
1105 one, the emulator never misses a frame, but looses much speed on
1106 slow systems. If set to a value higher than one, at most the
1107 specified number of frames might be dropped to keep up the
1108 refresh rate set by the option above. Hence, it does not hurt to
1109 select a higher maxmiss rate on a fast machine, but it will keep
1110 up the speed for more complex graphics on slower machines as
1111 well at the cost of loosing some frames.
1112 -videodmode PAL|NTSC
1114 Intentionally identical to the same option of the ANTIC and GTIA
1115 emulation, this selects the frame rate based on the video output
1116 mode. For a PAL machine, this selects a freshmode of 50
1117 frames/second, for a NTSC machine, the emulator will try to gen‐
1118 erate 60 frames/second. This option is overridden if the unlock‐
1119 rate switch above is enabled.
1120 DISKDRIVE Options
1123 The following set of options controls the emulation of up to four disk
1124 drives. The diskdrive options consist of a base name, a dot and the
1125 unit number specifying the unit of the disk drive they control. Hence,
1126 all the following options exist four times, and just differ by the
1127 digit behind the dot.
1128 -enable.1 bool
1130 Enables or disables the first diskdrive. If set to off, the
1131 first drive will not react as if it has been turned off, other‐
1132 wise it will be turned on. The default is to enable the first
1133 drive and to disable all others.
1134 -image.1 filename
1136 Specifies the path to an image file to be loaded into the drive.
1137 The Atari++ emulator supports several kinds of image files:
1138 First, raw disk images that keep the contents of the disk sector
1139 by sector. These files are typically identifies by their exten‐
1140 der .xfd. The second available format is the so called .atr
1141 format implemented by several other Atari emulators. It consists
1142 of a tiny header describing the format and the size of the disk
1143 plus the sector image. The third format supported by Atari++ is
1144 that of Atari binary load files or short, so called .exe files.
1145 These files consist of a two 0xff byte header plus address
1146 information where to place the data to load. These files are
1147 booted by writing them as DOS 2.0S files onto disk, toghether
1148 with a minimal game DOS header that bootstraps the .exe format.
1149 Note that no full DOS will be available for these files, though
1150 this emulation is sufficient for most .exe based games right
1151 away. Last but not least, Atari++ also supports .dcm images,
1152 which have been prepared by the “Disk Communicator” program and
1153 are (slightly) compressed. Similar to the .exe files, Atari++
1154 cannot re-compress these. Therefore, disk images of this type
1155 are marked write-protected, making writes to these disks fail.
1156 All of the above disk image types can be compressed by means of
1157 the gzip program; Atari++ will then uncompress them on demand as
1158 soon as the image gets loaded. Since it does not re-compress
1159 images, these disks also always end up write-protected.
1160 -protect.1 bool
1163 Enables or disables the write-protection of the inserted disk.
1164 If set to on, the disk image will be write-protected as if the
1165 write-protection notch has been covered on a physical disk. The
1166 emulator also write-protects disk images automatically if the
1167 corresponding image is marked non-writeable by the protection
1168 bits of the host operating system, or if the disk is build up
1169 for the .exe binary load file emulation, or comes in the already
1170 compressed .dcm Disk Communicator format. Similarly, all .gz
1171 compressed images are write-protected, no matter what the origi‐
1172 nal file format has been.
1173 -eject.1 bool
1176 If enabled, ejects the current disk in the drive. This option is
1177 useless as a command line parameter, but also appears as an menu
1178 item in the “quick menu” and allows easy removal of disks. The
1179 default is not to eject a disk if one is currently inserted.
1180 -emul815.1 bool
1183 Enables or disables the emulation of the extended command set of
1184 the double-density 815/Percom drives. Ususally, this emulation
1185 does only good since it enhances the compatibility with various
1186 third-party products, but for some programs, the specific reac‐
1187 tion of a plain unextended drive is required.
1188 -happy.1 bool
1191 This enables or disables another popular set of the command set
1192 extension of the Atari disk drives, namely that of the “Happy”
1193 hardware extension. The extended command set allows not only
1194 faster reading and track buffering, it also includes commands to
1195 manipulate the floppy CPU directly. Commands that require emula‐
1196 tion of the floppy CPU are, however, not emulated here. By
1197 default this extension is enabled, but it can be disabled if the
1198 commands are in the way for special programs.
1199 Similar disk drive options exist for drives two to four by replacing
1202 the digit 1 in the above list by the appropriate drive number.
1203 SIOCABLE Options
1206 The following set of options control the overall setup of Matthias
1207 Reichl's “AtariSIO” emulation. It requires that the kernel interface
1208 and development files for /dev/atarsio are available, or the DirectSe‐
1209 rial interface to be used. Otherwise, the following options remain
1210 unrecognized. To make use of the AtariSIO emulation, connect your Atari
1211 drive by means of the following two interface cable types to the PC,
1212 and disable the built-in disk drive emulation for the corresponding
1213 drive unit. I.e. if your external drive has been set to drive unit 1,
1214 the internal emulation for drive 1 has to be disabled by -enable.1
1215 false or the corresponding gadget in the DiskDrive menu.
1216 -cabletype 1050-2-PC|ProSystem
1219 selects the type of the cable that has been used to interface a
1220 1050 or 810 drive to the PC. Currently, AtariSIO supports two
1221 cable types, the “1050-2-PC” and the “ProSystem“ layout.
1222 -enableatarisio bool
1225 This is the overall enabling/disabling option for the AtariSIO
1226 interface. This switch defaults to on whenever AtariSIO has been
1227 compiled into the emulator.
1228 -directserial bool
1230 if enabled, Atari++ does not use the AtariSIO kernel interface
1231 but rather a user space interface, not requiring the installa‐
1232 tion of the AtariSIO kernel module. Even though this sounds
1233 attractive, timing cannot be as precise as for the kernel inter‐
1234 face and this interface is likely to fail under heavy load con‐
1235 ditions.
1236 -cmdtodatadelay 0..2000
1238 only used if the directserial option is enabled, this defines
1239 timing details for the Atari SIO emulation; specifically, this
1240 is the delay from the start of the falling edge of the COMMAND
1241 line to the start of the first byte of the command frame, given
1242 in micro seconds. According to the Atari SIO specifications,
1243 this delay shall be between 750 and 1600 usecs long. The default
1244 is 900usecs.
1245 -cmdframelength 800..10000
1247 This option defines another timing constraint of the Atari SIO
1248 directserial communications protocol, namely the total length of
1249 a command frame, from the falling to the raising edge of the
1250 COMMAND line, again given in micro seconds. According to the
1251 Atari SIO specifications, this delay shall be between 4060 and
1252 5210usecs long, the default is here 5150usecs. Note that due to
1253 the load of the host system some fine tuning of this parameter
1254 might be required to get a stable SIO communication.
1255 ATARISIO Options
1258 Similar to the above set of options, the following fine-tune the
1259 behaivour of the AtariSIO interface whenever it is available. However,
1260 this option set exists once per external drive and defines parameters
1261 that are specific for the drive and not to the cable interfacing to the
1262 drive. Therefore, the following options exist four times, by replacing
1263 the suffix “.1” in the following list by the appropriate unit number.
1264 -sioenable.1 bool
1267 enables the first - or subsequent for higher suffixes - external
1268 drive. It is disabled by default. Note that for redirecting
1269 drive accesses to AtariSIO, the emulator-internal drive emula‐
1270 tion must be disabled as well. Hence, to use a real 1050 as
1271 first floppy drive, the following two options would be required:
1272 -sioenable.1 true -enable.1 false
1274 -sioprotect.1 bool
1277 enables or disables an additional write-protection that blocks
1278 any write access to the external drive as if the floppy write-
1279 protection notch has been covered. This option defaults to off.
1280 -siotimeout 1..30
1283 specifies the timeout in seconds that applies to regular com‐
1284 mands. Since the Atari++ emulation of the diskdrive applies at
1285 the level of raw Pokey communcations, the emulator cannot know
1286 the desired timeout that has been selected by the driving Atari
1287 software. This timeout defaults to seven seconds.
1288 -sioformattimeout 10..120
1291 specifies the timeout in seconds for formatting commands that
1292 typically require longer than regular commands. This timeout
1293 defaults to sixty seconds, i.e. one minute, but is overridden by
1294 the specifications that are returned by the disk drive itself as
1295 soon as a status command is send to the drive.
1296 JOYSTICK Options
1299 Joystick emulation for Atari++ consists of two layers: First of all,
1300 the emulation of the corresponding port at the emulated hardware, and
1301 second the generation of sigals to feed data into this emulated port.
1302 For that, Atari++ uses the concept of a generic input device consisting
1303 of two axes and four buttons, abstracting from the real physical device
1304 on your machine to generate the input. For a physical (analog) PC joy‐
1305 stick, the meaning of the two axis and four buttons should be obvious,
1306 but other sources for the abstract input device exist as well, e.g. the
1307 mouse or the keyboard.
1308 Later stages of the Atari++ input layer then only refer to the buttons
1310 of these virtual devices, e.g. the keypad options of the 5200 device.
1311 The following set of options do not control the physical input devices,
1313 but rather select how the emulator should make use of this abstraction
1314 layer, whereever it comes from, to form digital joystick input. Hence,
1315 the following set of options controls the emulation of the emulated
1316 joystick port on input from an abstract input device.
1317 Similar to the diskdrive options, all joystick options exist four
1319 times, now numbered from zero to three. The digit behind the dot in the
1320 option name defines the joystick port this option controls. For the
1321 Atari 800 and 400, all four ports are used by the emulator, for the XL
1322 and later models, only the ports 0 and 1 are mapped to the emulated
1323 hardware, similar to their physical counterparts.
1324 -joystick.0.sensitivity 0..32767
1327 This option sets a threshold that must be crossed by the
1328 abstract analogue joystick input to detect a joystick movement
1329 on the emulated joystick port. The lower the number, the higher
1330 the sensitivity. The abstract input devices generate axis move‐
1331 ments from -32767 to 32767, the default of this option is that a
1332 movement of 8192 units on this scale is required to generate an
1333 input signal.
1334 -joystick.0.port devicename
1336 Defines the name of the abstract device that should be connected
1337 to the port. Currently, the following devices exist:
1338 MouseStick.0
1340 Uses the mouse on your host system as abstract input device,
1341 with the horizontal and vertical position of the mouse
1342 pointer forming the horizontal and vertical axis of the
1343 abstract input device connected to the port. There is only
1344 unit 0 of this device.
1345 RelMouseStick.0
1347 This works similar to the MouseStick input device above
1348 except that reacts on mouse movements rather than the abso‐
1349 lute mouse coordinate. This is often the better alternative,
1350 unless the pointer device emulating the mouse of the host
1351 machine uses also an absolute position, i.e. a trackpad or a
1352 touchscreen.
1353 KeypadStick.0
1355 Uses the keypad on the keyboard of the host system forming
1356 the abstract input device. Digits 8,4,6 and 2 generate maxi‐
1357 mal axis movements in top, left, right and down movement,
1358 respectively; keys 7,9,1 and 3 move in the corresponding
1359 diagonal directions. The 0 and Enter map to button 0 of the
1360 joystick. There is - quite obviously - only unit 0 of the
1361 keypad-stick. These keys can be reconfigured dynamically,
1362 and its configuration is found under the section KeypadStick
1363 below.
1364 AnalogJoystick.0
1367 Uses the (real) analog joystick connected to the port con‐
1368 trolled by the /dev/js0 device to form the abstract input of
1369 the device. Which physical axis forms which abstract axis is
1370 controlled by the analog joystick options described below,
1371 but the default mapping is the obvious: Each physical axis
1372 maps to the same abstract axis, and buttons 0 and 1 map to
1373 their abstract counterparts. Atari++ accepts up to eight
1374 physical joysticks by replacing the digit 0 in the above
1375 option by 1 to 7 for further joysticks that are then con‐
1376 nected to the corresponding joystick devices.
1377 DigitalJoystick.0
1379 Uses a (real, antique) Atari Joystick connected to an analog
1380 PC joystick port by means of the “El Cheapo” joystick
1381 adapter of the author. This adaptor maps the digital input
1382 lines of a digital joystick to the buttons 1 to 4 of an ana‐
1383 log joystick, and maps the one and only button by a resistor
1384 array to axis 0. As above, some parameters of this interface
1385 can be setup by the digital joystick options described
1386 below. Similar to above, the signals generated by this hard‐
1387 ware are then read thru the standard /dev/js0 Linux inter‐
1388 face, and up to eight digital joysticks can be emulated this
1389 way, accessing the devices /dev/js1 to /dev/js7. NOTE: You
1390 need to build some additional hardware to make use of this
1391 abstract device, but you get perfect Atari feeling as a
1392 bonus.
1393 The schematics for this interface are included in the dis‐
1395 tribution as “joystick.ps”.
1396 SDLAnalog.0
1399 Similar to “AnalogJoystick.0” except that the joystick posi‐
1400 tion isn't read from the kernel interface directly, but
1401 rather indirectly thru the SDL library. This makes abso‐
1402 lutely no difference except that on some systems only the
1403 kernel interface is available, whereas on others only the
1404 SDL interface can be used.
1405 SDLDigital.0
1407 Works exactly the same as “DigitalJoystick.0” except that
1408 the joystick movements are reported thru the SDL library
1409 rather than thru the kernel interface. Causes no difference
1410 in usage and options otherwise.
1411 None Do not connect any device to this joystick input and read it
1413 as “centered, no button pressed” all the time.
1414 Similar to the diskdrive options, the joystick options exist four times
1416 with the unit numbers 0 to 3. The default for the abstract input
1417 device is to use the keypad stick for joystick zero and leave all other
1418 joysticks and paddles unconnected.
1419 NOTE: The 5200 console system does not use standard Atari digital joy‐
1421 stick input. Instead, analog joysticks connected to the paddle inputs
1422 are used. It is therefore mandatory to define the input devices of the
1423 first two paddles, paddle 0 and 1, to have an input device for the 5200
1424 console. The digital joystick inputs defined by the options above WILL
1425 NOT WORK.
1426 PADDLE Options
1429 The following set of options control the emulation of up to eight pad‐
1430 dles that can be connected to the emulator. Similar to the above, the
1431 emulation requires an abstract input device to read the input of the
1432 emulated paddle from; paddle emulation uses only axis zero of this
1433 abstract device to form the paddle input, but requires buttons zero and
1434 one for the emulation of the two paddle buttons.
1435 NOTE: The paddles on the Atari machines use the joystick input lines
1437 for the paddle buttons. For that reason, paddles and joysticks should
1438 not make use of the same input device.
1439 NOTE: For the 5200 system, the controller is connected as a paddle and
1441 hence these - and not the joystick options - must be defined.
1442 As above, the following options exist several times, with the digit 0
1444 replaced by 1..7 for all other paddle units. Whereas the Atari 800 and
1445 400 allow this maximal number of eight paddles, inputs 4..7 are not
1446 available on a real Atari XL or XE. However, the Atari++ allows connec‐
1447 tion to these paddle inputs regardless of the emulated host input as
1448 the corresponding input lines are otherwise unused on the real hardware
1449 either.
1450 -paddle.0.sensitivity 0..32767
1453 Adjusts the sensitivity of the paddle and hence the movement
1454 necessary for a full paddle rotation. Note that the abstract
1455 input device generate movements on a scale of -32767 to 32767.
1456 -paddle.0.invert bool
1458 Since paddle input has no natural orientation, this option
1459 allows you to invert the meaning of the input device position.
1460 Since some games interpret paddle positions just opposide to
1461 others, this flag helps you out as it changes left movement to
1462 right, or upwards movement to downwards movement.
1463 -paddle.0.port devicename
1465 Defines which abstract input device to use to feed the paddle
1466 emulation. The very same devices as for the joystick emulation
1467 are available here, though pure digital devices as the keyboard
1468 or the digital joystick device are not very usable for paddle
1469 emulation. Since an abstract input device provides two axis and
1470 two buttons each, it makes sense to map one input device to two
1471 paddle inputs: For that reason, each even paddle number maps to
1472 the first axis and the first button, and each odd paddle number
1473 maps to the second axis and button of each abstract input
1474 device.
1475 LIGHTPEN Options
1477 Atari++ also allows emulation of the lightpen as a kind of analog input
1478 device. Though rarely used, the corresponding input lines at ANTIC are
1479 available and can be feed by this emulation component. There is only
1480 one lightpen device available, though its other options are very simi‐
1481 lar to the paddle emulation.
1482 -lightpen.sensitivity 0..32767
1484 Defines the sensitivity of the lightpen and hence the fac‐
1485 tor/adjustment between the real physical device and the emulated
1486 position of the lightpen on the screen.
1487 -lightpen.port devicename
1489 Specifies which abstract input device to connect the emulated
1490 lightpen to. The list of available devices is identical to the
1491 list of devices for all other gameport like input, please see
1492 the JOYSTICK Options section above.
1493 KEYPADSTICK Options
1495 Options in this group define the keys used by the Keyboard Joystick
1496 emulation. By default, the numeric keypad to the right of a standard PC
1497 keyboard is used for this purpose, but the keys can be reconfigured.
1498 -leftup keyname
1500 defines the key that moves the stick in the diagonal left
1501 upwards position. Pressing the left and the up key simultane‐
1502 ously is equivalent to this. Key names are either the numbers 0
1503 to 9 or the letters A to Z, indicating the corresponding keys on
1504 the main keyboard, or are taken from the list below. An empty
1505 string indicated by an empty pair of opening and closing quotes
1506 disables the corresponding function.
1507 -up keyname
1509 -rightup keyname
1511 -left keyname
1513 -right keyname
1515 -leftdown keyname
1517 -down keyname
1519 -rightdown keyname
1521 move all the joystick in the corresponding direction. Diagonal
1522 directions can be either assigned to separate keys, or are
1523 reached by pressing the two direction keys simultaneously.
1524 -center keyname
1526 centers the joystick.
1527 The option
1529 -leftbutton keyname
1531 configures the key that emulates the left button if the keypad
1532 is used as a paddle, or the one and only button if the keypad
1533 emulates a digital joystick.
1534 -rightbutton keyname
1536 selects the key to emulate the right button on paddles. The key
1537 has no function if the keypad emulates a standard Atari joy‐
1538 stick.
1539 Key Names are either alpha-numeric characters from 0 to 9 or A
1541 to Z indicating the corresponding keys on the main keyboard, or
1542 the following special names. Note that names containing spaces
1543 need to be quoted on the command line:
1544 -
1546 Name Key
1547 Cursor Left Left pointing arrow of the four cursor keys
1548 Cursor Right Move cursor right key
1549 Cursor Up Move cursor up
1550 Cursor Down Move cursor down, all the above on the cursor keypad
1551 Return Return key on the main keyboard
1552 Tab TAB key on the main keyboard
1553 Backspace Backspace key on the main keyboard
1554 Keypad 0 Digit 0 on the numeric keypad, similar for 1 to 9
1555 Keypad Divide Division key on the numeric keypad
1556 Keypad Multiply Multiplication key on the numeric keypad
1557 Keypad Plus Addition on the numeric keypad
1558 Keypad Minus Subtraction on the numeric keypad
1559 Keypad Dot Decimal separator, dot or comma, on the keypad
1560 Insert The insert key between main keyboard and numeric pad
1561 Delete The delete key in the same group
1562 Home The home key
1563 End The end key
1564 Scroll Up The page up key
1565 Scroll Down The page down key
1566 ANALOGJOYSTICK Options
1569 Unlike the JOYSTICK Options, the following set of options describes the
1570 mapping of a true analog joystick connected to one of the joystick
1571 device drivers to the abstract input device that forms the basis for
1572 either joystick, paddle or lightpen input. Hence, it defines the layout
1573 of the AnalogJoystick devices that can be connected to the above emula‐
1574 tion components.
1575 Similar to most above options, the following options exist several
1577 times with the digit 0 replaced by the unit of the corresponding
1578 device. Hence, the analog PC joystick controlled by /dev/js1 is setup
1579 by options similar to those above with a 1 replacing the 0.
1580 -first_button 1..16
1582 Defines which button of the physical joystick shall map to the
1583 button zero of the abstract input device. The default is to con‐
1584 nect the first button of the physical joystick to the first but‐
1585 ton, i.e. button zero, of the abstract device. This defaults to
1586 button #1 of the real device. If used in conjunction with the
1587 5200 keypad device, i.e. the “KeyButton.0.Button” and related
1588 options, the button index #1 used in the keyboard configuration
1589 refers to the button addressed by this option, and not directly
1590 to a hardware button. Thus, keypad buttons are routed twices: In
1591 a first stage, but the hardware abstraction layer defined by
1592 this option, and a second time by the keyboard device picking
1593 one of the four abstract buttons the hardware abstraction layer
1594 offers.
1595 -second_button 1..16
1597 Similar to the above, this defines the real button that shall be
1598 connected to the emulated second button of the emulated device.
1599 -third_button 1..16
1601 Again, this routes one of the hardware buttons to a virtual but‐
1602 ton of the hardware interface layer. Since the Atari hardware is
1603 only capable of supporting at most two buttons, namely for the
1604 paddles, the third and fourth button are only usable for the
1605 5200 keypad emulation, see the keyboard configuration chapter
1606 for details.
1607 -fourth_button 1..16
1609 The input line of the fourth button an abstract joystick device
1610 might support. Only usable from the keypad emulation.
1611 -haxis.0 xaxis.1|yaxis.1|xaxis.2|yaxis.2
1613 Specifies the axis of the physical joystick that should emulate
1614 the horizontal axis of the abstract analog joystick device. The
1615 default is the first horizontal axis of the physical joystick.
1616 -vaxis.0 xaxis.1|yaxis.1|xaxis.2|yaxis.2
1618 Similar to the above for the vertical axis of the abstract
1619 device. The default is, of course, the first vertical axis.
1620 SDLANALOG Options
1623 This is a modified AnalogJoystick interface that reads joystick posi‐
1624 tions thru the SDL library instead using the kernel interface directly.
1625 Its configuration options are identical to that of the AnalogJoystick
1626 interface and are hence not described here again.
1627 DIGITALJOYSTICK Options
1630 The next set of options is used to setup the digital joystick input and
1631 the “El Cheapo” Joystick input adapter that can be used to connect a
1632 true Atari digital joystick to the analog gameport input of the PC.
1633 This option set also exists several times, once for each available
1634 gameport detected in the host system. Once again, replace the digit 0
1635 by the unit number of the corresponding device the joystick is con‐
1636 nected to.
1637 -upbutton.0 Button.1|Button.2|Button.3|Button.3
1639 Defines which of the four joystick buttons on the analog game‐
1640 port acts as the input for the upwards movement line. The
1641 default is button three.
1642 -downbutton.0 Button.1|Button.2|Button.3|Button.3
1644 Similar to the above for the downwards movement. The default is
1645 button one.
1646 -leftbutton.0 Button.1|Button.2|Button.3|Button.3
1648 Selects the button that acts as the left movement input. This
1649 defaults to button four.
1650 -rightbutton.0 Button.1|Button.2|Button.3|Button.3
1652 Selects the button for right movement input. The default is but‐
1653 ton two.
1654 -triggeraxis.0 XAxis.1|YAxis.1|XAxis.2|YAxis.2
1656 Selects the analog gameport axis that reads the digital joystick
1657 button input. The default is that the digital fire button is
1658 connected to the first horizontal axis.
1659 -triggerthres.0 -32768..32768
1661 Since the digital button is read by the game port as an analog
1662 input, the digital signal arrives as a numerical value between
1663 -32768 and 32767 at the digital joystick device of the emulator.
1664 The above option sets the threshold by which the button is read
1665 as pressed resp. released. The precise values depend of course
1666 on the resistance network that is connected to the analog game‐
1667 port line, but the default for 16384 works fine for the author's
1668 hand-soldered adaptor.
1669 -inverttrigger.0 bool
1671 With this switch, the fire button input line reading can be
1672 inverted, i.e. active inputs are read as released fire buttons
1673 and vice versa. This shouldn't be necessary with the author's
1674 interface. The default is hence off.
1675 SDLDIGITAL Options
1677 This is just a slightly modified DigitalJoystick interface that con‐
1678 nects to SDL instead to the kernel interface. All its options are iden‐
1679 tical, please refer to the above list for details.
1680 OSSHQSOUND Options
1683 In the following, we give a set of options to control the generation of
1684 audio thru the OSSHQ driver, making use of the Open Sound System kernel
1685 interface or an equivalent emulation, e.g. by ALSA. Rather than the
1686 POKEY Options, these options concern the quality of the samples gener‐
1687 ated by the POKEY emulation and its built-up for OSS. For audio output
1688 to work properly, you need to have an Open Sound System compatible
1689 audio driver available, and you need to have permission to access the
1690 /dev/dsp device.
1691 Note that generating audio samples with high quality has a non-
1693 neglectable impact on the CPU load. If your machine has problems keep‐
1694 ing up with the natural framerate, or if the CPU load is too high, try
1695 to lower these settings, use a different audio front-end, or disable
1696 sound output alltogether.
1697 -enablesound bool
1699 Enables or disables the generation of audio output. The default
1700 is the enable the audio generation, unless no audio output
1701 device is available which then disables audio output.
1702 -enableconsolespeaker bool
1704 Enables or disables the emulation of the Atari console speaker.
1705 The Atari Os generates keyboard click sounds and the buzzer by
1706 means of this speaker. Some games also use the console speaker
1707 for speech output.
1708 -consolespeakervolume 0..64
1710 Sets the output volume of the console speaker. Setting this to
1711 zero effectively disables the output, and setting this to a
1712 value higher than 32 may cause distortion with regular POKEY
1713 audio output. This option ranges from zero to no up to 64 for
1714 maximal volume with the default being 32.
1715 -audiodevice filename
1717 Specifies the name of the audio device to send the samples to.
1718 This device must accept all Oss specific ioct() settings. It
1719 defaults, naturally, to /dev/dsp.
1720 -samplefreq 4000..48000
1722 The sampling frequency in Hz by which samples should be gener‐
1723 ated, and hence the limiting frequency for the audio signals.
1724 The higher this value is, the higher are the possible frequen‐
1725 cies that can be emulated, and the more natural the sound plays.
1726 Frequencies higher than 16000 are required for software speech
1727 output, but otherwise a frequency limit of 8000 Hz is enough for
1728 all other sound effects. The default is 44.1kHz, the CD replay
1729 frequency.
1730 -fragsize 2..16
1732 This is a technical setting that allows to specify the size of
1733 an audio buffer fragment. These fragments get filled sample by
1734 sample and are transmitted to the replay hardware as soon as
1735 they are full and the hardware is capable of playing another
1736 sample. If they are too small, the buffer has to be refilled too
1737 often and you might hear drop-outs since the computation cannot
1738 keep up with the audio replay. If they are too long, the audio
1739 latency becomes too high and the sound is no longer synchronized
1740 with the video out. This option does, however, not specify the
1741 fragment size itself, but rather the exponent to the base of
1742 two, i.e the true fragment size will be two to the power of this
1743 exponent. The default for this option is 8, i.e. a fragment size
1744 of 256 bytes. You'd rarely need to play with this setting.
1745 -numfrags 6..256
1747 The number of buffers, each of the size given by the above argu‐
1748 ment, to be used for audio sample generation. More buffers
1749 reduce the likelyhood of drop-outs, but increase the latency.
1750 The default are 16 buffers, more is rarely useful.
1751 -forcestereo bool
1753 Enforces to generate stereo samples even though mono output is
1754 available for the sound chip. Some broken sound implementations,
1755 notably ALSA on the Emu10K1 chipset require this to work cor‐
1756 rectly under all configuations.
1757 OSSSOUND Options
1760 The Oss driver is a less complex frontend for the Open Sound System
1761 audio interface, though it requires a very precise implementation of
1762 it. Some emulations, e.g. ALSA might not be suitable for this fron‐
1763 tend, and it rarely provides better quality than HQOss. Since it pro‐
1764 vides quite similar options as well, we only describe most of them
1765 roughly and refer to the HQOss frontend for further details.
1766 -enablesound bool
1769 Enables or disables the generation of audio output.
1770 -enableconsolespeaker bool
1772 Enables or disables the emulation of the Atari console speaker.
1773 -consolespeakervolume 0..64
1775 Sets the output volume of the console speaker.
1776 -audiodevice filename
1778 Specifies the name of the audio device to send the samples to;
1779 this is typically /dev/dsp.
1780 -samplefreq 4000..48000
1782 The sampling frequency in Hz for the audio output.
1783 -refillfreq 20..48000
1785 The frequency in Hz by which the audio samples are recomputed by
1786 the emulator. If this is set to a relatively low value, but the
1787 sampling frequency is high, then quite a lot of samples are com‐
1788 puted in one go, but the updating period by which these samples
1789 are matched to the true POKEY output is rather low. This refill
1790 frequency must be lower than the sampling frequency above. For
1791 software speech generation, a refill frequency of 15700 proved
1792 most effective. For regular sound output, this frequency can be
1793 much lower. Note that for software speech output, the audio ker‐
1794 nel interface must meet the specifications of the Open Sound
1795 System architecture precisely. Some emulations, e.g. ALSA fail
1796 here. Try to use the HQOss frontend in this case; in most cases,
1797 it is capable of providing better quality anyhow.
1798 -fragsize 2..16
1800 The exponent for the base of two giving the size of an audio
1801 buffer fragment in bytes. This is similar to the fragment size
1802 of the HQOss frontend and is discussed in more detail above.
1803 -numfrags 1..256
1805 The number of buffers to be used for audio sample generation.
1806 For two buffers, this means that audio output is double-
1807 buffered. More than four buffers are rarely useful for this
1808 driver, making this the default.
1809 -forcestereo bool
1811 Enforces to generate stereo samples even though mono output is
1812 available for the sound chip. Some broken sound implementations,
1813 notably ALSA on the Emu10K1 chipset require this to work cor‐
1814 rectly under all configuations.
1815 WAV Options
1819 The WAV frontend is the alterantive audio output module that rather
1820 records the generated sound than to play it; or at least, this is its
1821 main intention: WAV also offers playback of the recorded sound, though
1822 due to timing restrictions the quality of this sound is - sometimes
1823 noticably - worse than that of the Oss or HQOss module and the sound
1824 that got recorded in the final .wav file. As said, the quality of the
1825 output file will be perfect.
1826 -enablerecording bool
1829 Enables or disables the recording to the wav output file. If
1830 enabled, the emulator starts recording as soon as the emulated
1831 machine starts running, though the recorded file is disposed and
1832 re-written from scratch on a cold-reset, e.g. generated by the
1833 F7 key. To record game music, you'd best first enable the
1834 recording, then start the game, let the music play and interrupt
1835 the music by entering the configuration menu with the F1 short‐
1836 cut. Then turn off recording. This will leave the recorded file
1837 intact.
1838 -enableplayback bool
1840 Enables or disables the playback of the recorded data. If this
1841 option is enabled, the WAV frontend will also play the music
1842 over an OSS compatible sound driver. It is typically a good idea
1843 to enable this option as well whenever it is available, i.e.
1844 whenever an OSS sound driver is in the system. Note, though,
1845 that the quality of the sound output might be of noticably worse
1846 quality than that of the recorded sound within the output file.
1847 -enableconsolespeaker bool
1849 Similar to the option of the same name for the OSS sound front-
1850 end, this option enables or disables the generation of sound
1851 thru the console speaker. It is typically used for the keyboard-
1852 clicks and the buzzer-sound.
1853 -consolespeakervolume 0..64
1855 Sets the volume of the console speaker if enabled. This option
1856 defaults to 32.
1857 -outputfile filespec
1859 Defines the full path of the .wav output file to record the
1860 sound in. If this option is not given, then this file name
1861 defaults to “out.wav”.
1862 -audiodevice device
1864 Sets the name of the OSS sound device. This is typically
1865 “/dev/dsp”, which is also the default setting for this option.
1866 -samplefreq 4000..48000
1868 Sets the sampling frequency in Hz for the recorded .wav file,
1869 and by that also the sampling frequency of the played-back audio
1870 output. The smaller, the less CPU power is required and the
1871 shorter the output file becomes for recording the same timespan
1872 of music, but the worse the quality gets. This option defaults
1873 to 15700 Hz which is the best compromise between quality and
1874 data size. Much higher frequencies make little sense and do not
1875 improve quality noticably.
1876 -fragsize 2..16
1878 sets similar to the OSS front-end option of the same name the
1879 exponent for the size of the fragment for audio playback. It has
1880 no influence whatsoever on the output file whatsoever, but
1881 rather modifies the behaivour of audio playback only.
1882 -numfrags 1..256
1884 sets the number of audio fragments (buffers) for audio playback,
1885 similar to the option of the same name of the OSS front-end. It
1886 has no influence on the recorded samples.
1887 SDLSound Options
1890 The next audio front-end is generation thru the Standard Direct Media
1891 Library, or short SDL, all provided you have an SDL library and the
1892 required development files installed on your host. The quality of the
1893 SDL output is close to that of the HQOss frontend, though due to the
1894 different driver architecture, it is unfortunately more likely for the
1895 SDL driver to generate drop-outs. It furthermore requires longer frag‐
1896 ments and has therefore a higher latency, but it is very portable as
1897 SDL exists on a variety of platforms.
1898 -enablesound bool
1901 enables or disables the sound generation thru SDL, similar to
1902 the same option for the OSS and WAV audio front-ends.
1903 -enableconsolespeaker bool
1905 will toggle the console speaker emulation on or off. The emula‐
1906 tion is enabled by default.
1907 -consolespeakervolume 0..64
1909 adjusts the volume of the console speaker. This setting defaults
1910 to a medium volume of 32.
1911 -samplefreq 4000..48000
1913 adjusts the sampling frequency for the audio generation in Hz =
1914 samples per second. Higher sampling frequencies provide closer
1915 sound output emulation, but also enlarge the CPU load on the
1916 system. The sampling frequency defaults to 44100Hz, i.e. CD
1917 quality. You might have to lower this setting on weaker systems.
1918 -fragsize 2..16
1920 selects the size of an audio output buffer as the exponent for
1921 the base of two. The smaller the fragment size, the more often
1922 the audio output will get updated to reflect the audio register
1923 setting of the POKEY chip, and the more natural audio output
1924 will become. If the fragment size is too small, then audio out‐
1925 put will degrate quickly, though, as the emulation will then no
1926 longer be able to refill the output buffers in time. The optimal
1927 setting for this value is around nine, which is also the
1928 default.
1929 -forcestereo bool
1931 Enforces to generate stereo samples even though mono output is
1932 available for the sound chip. Some broken sound implementations,
1933 notably ALSA on the Emu10K1 chipset require this to work cor‐
1934 rectly under all configuations.
1935 DirectX Sound Options
1939 This audio front-end is only available for win32 compatible platforms
1940 and requires at least DirectX 8.0 installed on the host machine. It
1941 offers the highest audio quality available under the win32 operating
1942 system at minimal latency.
1943 The following options are available for DIRECTX sound:
1945 -enablesound bool
1948 enables or disables audio output. It is enabled by default.
1949 -enableconsolespeaker bool
1952 turns emulation of the console speaker on or off. This speaker
1953 generates the keyboard click and buzzer sounds, but is otherwise
1954 not very frequently used; it is enabled by default.
1955 -consolespeakervolume 0..64
1958 controls the volume of the console speaker. The default setting
1959 is 32, though higher volumes are not recommended as they will
1960 cause distortion when mixing them with the regular POKEY output.
1961 -samplefreq 4000..48000
1964 selects the sampling frequency in samples per second. The
1965 default is 22050 Hz, i.e. half the frequency of an audio CD.
1966 Higher frequencies are not recommended for DirectX as the CPU
1967 load gets very high otherwise.
1968 -fragsize 2..12
1971 sets the size of one audio buffer, also called a “fragment” by
1972 defining its exponent to the base of two. Thus, increasing this
1973 setting by one doubles the size of one audio buffer, a setting
1974 of eight causes buffers that are 2^8 = 256 samples long. This is
1975 also the default buffer setting and a good compromize between
1976 latency and quality for fast, up-to-date hardware. Slower sys‐
1977 tems might require higher values; in case you hear audio drop-
1978 outs, increase this value.
1979 -numfrags 6..16
1982 defines the number of audio buffers of the above size to be
1983 allocated. A higher number will allocate more buffers, causing
1984 higher latency, but also lowering the probability of drop-outs.
1985 The default are six buffers, but this number should be increased
1986 in case the audio output isn't smooth.
1987 ALSASound Options
1990 The last available audio front-end uses the ALSA sound drivers avail‐
1991 able on Linux and the asoundlib API. Both, and their development files
1992 must be available at compile time to provide this interface. Further‐
1993 more, Atari++ requires a relatively recent version of ALSA, namely
1994 0.9.0rc7 or later since the hardware API changed at this release.
1995 If available, ALSA provides a high quality sound similar to the HQOSS
1997 frontend, though its demands concerning the CPU power are very moderate
1998 and lower than that of other frontends.
1999 The following options are available for ALSA:
2001 -enablesound bool
2004 enables or disables the sound output. This defaults to on.
2005 -enableconsolespeaker bool
2008 controls emulation of the console speaker; this option is turned
2009 on by default.
2010 -consolespeakervolumne 0..64
2013 selects the volume of the console speaker. It is set to 32 by
2014 default; higher volumes might cause distortion in the sound out‐
2015 put.
2016 -audiocard name
2019 selects the audio hardware ALSA shall sent the samples to. This
2020 is not a device specification in the sense of a path name. It
2021 defaults to “hw:0,0” which addresses the first available audio
2022 hardware that is handled by ALSA. Further audio cards are named
2023 “hw:1,0” and so on. Even though Atari++ supports a wide range of
2024 sampling formats natively, some exotic cards might require the
2025 help by ALSA. To enable this additional software support, sub‐
2026 stitute “hw” by “plughw”, e.g. specify “plughw:1,0” as device
2027 name. This enables an additional software conversion inside
2028 ALSA.
2029 -samplefreq 4000..48000
2032 selects the sampling frequency in samples per second. The
2033 default is 44100 Hz, i.e. CD quality.
2034 -fragsize 2..16
2037 defines the size of an audio buffer fragment as the exponent to
2038 the base of two. This works very similar to all other audio
2039 frontends and is not explained here again. ALSA allows a rela‐
2040 tively small default of 8 here, meaning fragments of 2^8 = 256
2041 bytes.
2042 -numfrags 6..256
2045 defines the size of the audio buffer in fragments. The more
2046 fragments, the lower the probability of drop-outs but the higher
2047 the latency. The number of fragments defaults to 12.
2048 -forcestereo bool
2051 Enforces to generate stereo samples even though mono output is
2052 available for the sound chip. Some broken sound implementations,
2053 notably ALSA on the Emu10K1 chipset require this to work cor‐
2054 rectly under all configuations.
2055 X11 Options
2059 The next set of options controls the X11 graphical frontend of the
2060 Atari++ emulator, all provided it has been selected with the -frontend
2061 X11 option. Otherwise, the control options of the selected frontend
2062 apply instead.
2063 -privatecmap bool
2065 If set to on, then Atari++ will emulate its own color map for
2066 the emulation window output. This is only required if you run it
2067 on a 8 bit display and the emulator further complains that it
2068 couldn't allocate enough free pens. The downside of this option
2069 is that the colors will get wrong as soon as the mouse pointer
2070 leaves the emulator window on an 8 bpp display, but at least you
2071 get a display with proper colors otherwise.
2072 This option is not at all useful for 16 bpp or any other true-
2074 color displays as the color mapping will be correct all the time
2075 otherwise. Therefore, the default for this option is off.
2076 -syncx bool
2078 A boolean flag that describes whether the X11 frontend shall try
2079 to keep the display output in sync with the emulator. If set to
2080 off, all rendering operations will be asynchronous, possibly
2081 causing some lag between the gameplay and the display. The down‐
2082 side of enforcing synchronous graphic renderning by setting this
2083 to on is that the display refresh must wait for the X server to
2084 perform the refresh and to notify the client about it, adding
2085 the turn-around times and the net transfer overhead to the dis‐
2086 play refresh time. It is therefore rarely a good idea to enable
2087 this option.
2088 -renderindirect bool
2090 If set to on, then all rendering happens indirectly to an off-
2091 screen pixmap in a first step, then blitting the pixmap in a
2092 second step back to the screen. This has the downside of being
2093 slower by requiring an additional transfer step, but it makes
2094 the display refresh smoother as well as the rendering operation
2095 itself remains invisible. Since it makes emulation slower, this
2096 option remains off by default.
2097 -screenbase filename
2099 Selects a filename base for the screen dumps. If a screendump is
2100 requested, a counter and a file type extender is appended to
2101 this name and the screen contents are saved to this file. Cur‐
2102 rently, screen dumps are saved in the Portable Pixmap (ppm) For‐
2103 mat that is readable by most Linux/Unix tools, e.g. by xv and
2104 gimp. The default filename is “ScreenDump”.
2105 -dumpformat PNM|BMP|PNG
2107 Specifies the file format to be used for screen dumps. PNM is
2108 the simplistic *nix specific PNM/PPM true color dump file format
2109 that is understood by most *nix programs. BMP is the Windows
2110 Bitmap format, a very popular but rather aged image file format
2111 of the Win32 world. PNG is the “Portable Network Graphics” file
2112 format, an image format driven forward by the Open Source commu‐
2113 nity. This file format requires the availibility of the LibPNG.
2114 -pixelwidth 1..8
2117 This option spezifies the magnification degree in horizontal
2118 direction by which the pixels of the emulated scren are rendered
2119 to the X11 display. The default of the pixelsize option is 2,
2120 i.e. a single pixel of the Atari display is rendered twice as
2121 large on the X window showing the emulation. Depending on the
2122 hardware driver of your graphics board, enlarging the pixelsize
2123 might be almost for free with the X11 frontend.
2124 -pixelheight 1..8
2126 This option controls the magnification of the pixel size in ver‐
2127 tical direction, similar to the above option the default value
2128 is 2.
2129 -leftedge 0..64
2132 Sets the horizontal position of the first Atari pixel that gets
2133 displayed within the X11 window. The pixels left to this pixel
2134 are not made visible. This option is useful either to align the
2135 size of the X window to the natural size of the screen the win‐
2136 dow is contained in, to hide the leftmost pixel junk caused by
2137 the horizontal ANTIC scrolling, or to remove the hardware border
2138 of the window, similar to the operation performed by some TVs.
2139 This option defaults to 16, just enough to make the HSCROLL
2140 artefacts invisible.
2141 -topedge 0..64
2143 Sets the first row of the ANTIC display to render to the X11
2144 window. This is otherwise identical to the -leftedge option
2145 except that it works in vertical direction. The default of this
2146 option is zero.
2147 -width 320..480
2149 Sets the total amount of pixels to render into the screen and
2150 hence the inner dimension of the X window. Reducing this width
2151 can be either useful to fit this window into the screen, or to
2152 avoid some pixel junk at the right edge of the ANTIC display.
2153 The default width is 352 pixels.
2154 -height 192..248
2156 Sets the height of the window in emulated pixels. Since the low‐
2157 est lines are always left blank anyhow, they need not to be ren‐
2158 dered. Therefore, this option defaults to 240.
2159 SDL Options
2162 The next option set controls the layout of the alternate emulator fron‐
2163 tend driven by the Simple Direct Media Library, or short, SDL. This
2164 library allows fullscreen output, though its overall performance is
2165 lower as soon as it requires to upscale the pixels. The SDL frontend is
2166 activated by the -frontend SDL switch, and only then the following
2167 options apply:
2168 -leftedge 0..64
2170 Similar to the X11 Option of the same name, this selects the
2171 first visible emulator pixel on the SDL screen. This option
2172 defaults to 16.
2173 -topedge 0..64
2175 Specifies the first visible row on the screen. The default is to
2176 start the display at row 0.
2177 -width 320..480
2179 The width in emulator pixels of the screen to render. The
2180 default is 352.
2181 -height 192..248
2183 The height of the emulated display. The default is to drop some
2184 lines at the bottom end since they are always blank anyhow: 240
2185 lines are rendered by default.
2186 -pixelwidth 1..8
2188 Set the width of one emulator pixel in SDL pixels. The default
2189 is that one emulator pixel is represented by one pixel on the
2190 SDL screen. Setting this to values larger than two easely
2191 degrades the emulator performance.
2192 -pixelheight 1..8
2194 Set the height of one emulator pixel in SDL pixels. As already
2195 said above, the default is one. Pixel heights larger than two
2196 typically slow down the emulator too much to be useful.
2197 -screenbase filename
2199 Defines a base file name similar to the X11 screenbase option
2200 for screen dumps. The filename of the screen dump is, as above,
2201 formed by a counting number and the extender of the file format.
2202 Currently, screen snapshots are saved as PPM images.
2203 -doublebuffer bool
2205 enables double buffering, provided the implementation of SDL on
2206 the host system implements it. Double buffering allows smoother
2207 scrolling at the price of a slightly higher CPU load. At the
2208 time of writing, only the win32 version of SDL provides double
2209 buffering, the Linux version does not. Thus, enabling this
2210 option under Linux does nothing. However, the renderindirect
2211 option of the X11 front-end does something very similar.
2212 -fullscreen bool
2214 Enables or disables full screen display. The default is to use
2215 the full screen display, and it is recommended to use the X11
2216 frontend otherwise as it provides higher performance in this
2217 case.
2218 -dumpformat PNM|BMP|PNG
2220 Specifies the file format to be used for screen dumps. PNM is
2221 the simplistic *nix specific PNM/PPM true color dump file format
2222 that is understood by most *nix programs. BMP is the Windows
2223 Bitmap format, a very popular but rather aged image file format
2224 of the Win32 world. PNG is the “Portable Network Graphics” file
2225 format, an image format driven forward by the Open Source commu‐
2226 nity. This file format requires the availibility of the LibPNG.
2227 -shieldcursor bool
2229 Enables a workaround against an SDL bug that allows a program to
2230 overdraw the active mouse pointer, trashing its backing store
2231 and leaving invalid graphics behind the pointer if it is moved
2232 away. This workaround will remove th cursor prior the drawing
2233 operation to avoid the problem, at the cost of a possibly more
2234 flickering pointer.
2235 -deblocker bool
2237 Enables a deblocking filter that creates rounder and smoother
2238 graphics for pixel sizes between two and three. This avoids to
2239 some degree the blocky-ness of the emulated display that is
2240 caused by the higher and finer resolution of the PC monitor com‐
2241 pared to the TV output the Atari hardware was designed for.
2242 850INTERFACE Options
2245 The Atari++ contains a complete emulation of the 850 serial interface
2246 box, including a boot-able R: handler that would be part of this inter‐
2247 face. This interface box allows you to use the serial port of the host
2248 system as a serial output port of the 850 interface, allowing you to
2249 connect a modem to the emulated Atari. The emulation has only two limi‐
2250 tations: For first, it cannot provide some of the exotic baud rates the
2251 850 box is able to generate, and it provides only a single serial port,
2252 not four of them. On the other hand, it offers a true hardware hand‐
2253 shake, unlike the 850. For more information about the emulator provided
2254 R: handler, see below.
2255 The following options configure the 850 emulation:
2257 -enable850 bool
2259 Enables or disables the 850 interface. If disabled, the inter‐
2260 face box will not react on any SIO commands and will hence pre‐
2261 tend to be turned off.
2262 -serialname path
2264 Specifies the device name for the serial port the emulated 850
2265 interface shall use as its output port. The default device name
2266 is “/dev/ttyS0”, i.e. the first serial output port of the sys‐
2267 tem.
2268
2271 Atari++ is not only controlled by its huge amount of command line
2272 parameters. It is also adjustable by configuration files. These config‐
2273 uration files contain the very same options than the command line
2274 parameters, except that there is only one option per line, an equals =
2275 sign separates option from value, and the minus-sign in front of the
2276 option is missing. Additionally, empty lines and comments starting with
2277 the hash-mark # are allowed. The following example shows a typical con‐
2278 figuration file:
2279 #
2281 # This is the config file for the atari++ emulator
2282 #
2283 HoldOption = true
2284 Artefacts = off
2285 Enable.1 = on
2286 Protect.1 = on
2287 SIOPatch = on
2288 InstallPDevice = on
2289 SampleFreq = 44100
2290 RefillFreq = 15700
2291 NumFrags = 4
2292 Joystick.0.Port = DigitalJoystick.0
2293 The Atari++ emulator knows three configuration files: The system spe‐
2295 cific configuration file, residing at /etc/atari++/atari++.conf, the
2296 per-user specific configuration file at ~/.atari++.conf and the per-
2297 directory configuration file at ./.atari++.conf. Each later configura‐
2298 tion file overloads the defaults of the former, and the command line
2299 arguments finally overload all of them. This way, the least frequently
2300 adjusted options should go into the configuration file in the home
2301 directory, with system specific settings in /etc.
2302
2304 The Atari++ emulator uses the following keymap:
2305 F1 This key enters the graphical configuration menu. The usage of
2307 this menu should be quite obvious as all the options are named
2308 as in this manual and sorted under the same topics. The menu is
2309 left by the topmost Prefs topic which also allows loading and
2310 saving the settings and entering the monitor. The F1 key changes
2311 its meaning for the CURSES front-end, where no full menu is
2312 available. Here, it replaces the Atari resp. inverse-video key.
2313 F2 is mapped to the Option console key.
2315 F3 is mapped to the Select console key.
2317 F4 is mapped to the Start console key.
2319 F5 is the Help key that is otherwise only available on the XL and
2321 XE hardware.
2322 F6 is the Reset console key. Its function differs a bit amongst
2324 various models. For the Atari 800 and 400, this key just signals
2325 a special NMI interrupt at ANTIC, and the Os resets the system
2326 manually. For the XL and XE, this signal is really connected to
2327 the CPU reset line. Atari++ emulates this behaivour.
2328 F7 coldstarts the system as if it has been turned off and on again.
2330 Hence, unlike F6, this is a true coldstart and not a warmstart.
2331 F8 emulates the Break key, used to stop listings and BASIC pro‐
2333 grams.
2334 F9 requests a screen dump. Where this screendump goes is a matter
2336 of the -screenbase command line option.
2337 F10 aborts the emulator immediately, similar to closing the window.
2339 F11 and Pause
2341 pauses the emulator. Pressing F11 again continues the emulation.
2342 F12 enters the on-line monitor that is described below.
2344 Home/Clear
2346 emulate the Shift+< sequence, enforcing a clear screen.
2347 Insert inserts a blank character under the cursor by emulating Ctrl+>.
2349 If pressed together with shift, a blank line is inserted at the
2350 current line position.
2351 Del removes a single character under the cursor by emulating a
2353 Ctrl+BS keyboard sequence.
2354 Cursor Keys
2356 move the cursor in the indicating direction by holding either
2357 +,*,-,= and the Ctrl key down. This works fine most the time
2358 except for the DDT debugger which requires these keys pressed
2359 without Ctrl for window movement. Do not use the separate cursor
2360 keys but the above keys directly for DDT.
2361 Esc emulates, as expected, the ESC key on the Atari keypad.
2363 Keypad keys 7,8,9,4,5,6,1,2,3
2365 are part of the “keypadstick.0” device and a possible emulation
2366 source for joystick input; they are also configurable, see the
2367 KeypadStick section.
2368 Keypad keys 0 and Enter
2371 emulate the joystick button of the device as well.
2372 ALT emulates the Atari or InverseVideo key. For some implementa‐
2374 tions, this key is also emulated by the Windows key.
2375 All other keys have their natural key binding except for the
2377 5200 game console which is explained below. This binding is
2378 given by the current keyboard layout; this means especially that
2379 the keyboard layout is language specific and does not neces‐
2380 sarely match the layout of the Atari keyboard. E.g. for a german
2381 keyboard, the keys for “y” and “z” work as printed on the PC
2382 keyboard, and not as for the (american) Atari keyboard layout. I
2383 currently consider this as an advantage.
2384 KEYBOARD INPUT FOR THE 5200
2387 Keyboard input on the 5200 game system is considerably different as
2388 this console does not have a keyboard, but a small numberic pad on each
2389 of its controllers. This pad consists of the numbers zero to nine, the
2390 asterisk “*”, the hash-mark “#” and the buttons labelled “Start”,
2391 “Pause” and “Reset”. Furthermore, the joysticks have two buttons
2392 instead of one, and are actually analog joysticks using the paddle
2393 input lines, see above. The current emulator uses the PC keyboard for
2394 all additional keys and does currently not distinguish between the var‐
2395 ious keypads. A button pressed on the PC keyboard will be read as com‐
2396 ing from all game controllers at once. A future version of atari++ may
2397 possibly use a different scheme.
2398 The following keyboard keys act differently on the 5200 system:
2400 F2 is the “Reset” key on the keypad of the controller. This key is
2403 in no way any kind of hardware reset and is dissimilar to the
2404 “real” hardware reset which is still triggered by F6. Instead,
2405 this key is just an ordinary key that must be read by the loaded
2406 game, typically bringing you back to the setup screen.
2407 F3 is the “Pause” key on the keypad. This is also a purely software
2409 driven feature the game may or may not support.
2410 F4 is the “Start” key; it typically launches the game.
2412 keys 0..9
2414 activate the corresponding keypad keys.
2415 H or # emulates the hash-mark on the keypad controller key. Since the
2417 hashmark is not available on all native PC keyboards, the H is
2418 available as an replacement.
2419 S or * emulates the asterisk on the controller keypad. Similarly, the S
2421 is a suitable emulation for native keyboards with a hard-to-
2422 reach asterisk key.
2423 Shift acts as the second trigger button on all external controller
2425 keypads.
2426 F2 thru F12
2428 act as usual, see the list above.
2429 all other keys
2431 are blind and perform no operation in the 5200 emulation mode.
2432
2435 The keyboard input of the CURSES (terminal) front-end is rather limited
2436 because the emulator has considerably less control over the keyboard
2437 than under the graphical front-ends. Note that this emulation replaces
2438 the complete front-end of the emulator, it is not fit to script it,
2439 e.g. feed input to it from a file. For that, better replace operating
2440 system editor functions and use the InstallEDevice function.
2441 In the curses front-end, most keys work as expected, with some limita‐
2443 tions:
2444 F1 does not provide a full menu, which is not available due to lack
2446 of graphics output. Instead, the machine must be configured man‐
2447 ually from the command line or the configuration files. The F1
2448 key rather maps to the Atari or InverseVideo key as the state of
2449 the ALT key is not directly accessible from the CURSES inter‐
2450 face.
2451 CAPS is not directly available because the CapsLock key is read by
2454 the host operating system and is not forwarded to the emulation.
2455 Instead, the emulator sends a CAPS key event after each reset,
2456 triggering the system to low-caps, which is the default under
2457 most host operating systems, and then setting the Shift key of
2458 the emulated machine according to the case of the inserted char‐
2459 acter. This makes CAPS “appear” to work right for most situa‐
2460 tions, unless a program fiddles with the operating system and
2461 alters the CAPS state manually, or performs a software-driven
2462 reset. In this case, the ASCII TILDE that is “ ~ ” will emulate
2463 a press on the CAPS key of the host.
2464 Requesters and Menus
2467 Requesters and error messages will be emulated on the console by
2468 text-driven menus, allowing you to select a choice by typing the
2469 indicated character.
2470 Graphics Output
2473 The graphics emulation is limited to text based ANTIC modes,
2474 limited to the standard character set. Some of the text graphics
2475 can be emulated, ASCII-Art might work to a limited degree, but
2476 bitmap graphics output will not appear on the console. Some lim‐
2477 ited support for horizontal scrolling is available, though.
2478
2481 The atari++ allows you to make a snapshot of the complete machine state
2482 anytime within a game, to save this state to a file and to restart the
2483 game later on from this position. This is not only useful to interrupt
2484 a game temporarely - maybe because you've better things to do in the
2485 mean time - it also helps to try hard game puzzles several times.
2486 To create a snapshot file, enter the menu by pressing the F1 key on
2488 your keyboard, pick the Prefs item on the left hand side list and enter
2489 the name of the state file into the bottommost gadget labelled “Save
2490 State To”.
2491 To restore a machine state, i.e. to load the snapshot file, use the
2493 gadget “Load State From” right on top of it, or the command line option
2494 -state filename expecting the name of your snapshot file.
2495 It is important to understand that the snapshot file contains only the
2497 part of the inner machine state that is not covered by the configura‐
2498 tion file. For example, the snapshot file will NOT contain the cur‐
2499 rently active ROM image as this image is already sufficiently specified
2500 by the configuration. Hence, if your configuration at the time you made
2501 the snapshot differs from your default configuration, you should also
2502 save that configuration, and load it along with the snapshot. Snapshot
2503 files extend configuration files, they are not independent from the
2504 emulator configuration.
2505
2508 The emulator provides an optional interface from the emulated Atari to
2509 the host environment by the H: handler that makes parts of the filing
2510 system of the host visible within the emulation. To make use of this
2511 handler, it has to be enabled by the -InstallHDevice on command line
2512 option or a similar option within the configuration files. This option
2513 will replace the C: cassette interface - which is rarely, if ever, use‐
2514 ful - by the host interface filehandler. This handler provides four
2515 units, named H1: to H4: opening four directories of the host system
2516 within the emulator. These directories are configured by the -H1Dir to
2517 -H4Dir command line options, expecting path name(s) to host system
2518 directories.
2519 FILE NAMES AND PATTERN MATCHING
2522 Similar to the standard file management systems DOS 2.0S and upper, the
2523 H: handler automatically resolves patterns within filenames. The fol‐
2524 lowing wildcards are supported:
2525 * matches a sequence of any, possibly zero, length of any charac‐
2527 ters, quite similar to the bash or the csh.
2528 ? matches one single character.
2530 - Matches any character and ignores the rest of the pattern.
2532 Unlike the standard file management systems, the dot “.” has no
2534 special meaning for the H: device except that file names are
2535 truncated to eigth characters in front and three characters
2536 beyond it. This is a backwards compatibility feature to be able
2537 to run most Atari Os compliant programs on the H: device without
2538 additions.
2539 The handler will furthermore ignore cases when comparing the
2541 requested file name with a file name on the host system. Files
2542 generated by the emulator will use lower case for convenience.
2543 COMMAND SET
2546 The H: handler supports the following IO commands:
2547 CMD 3: OPEN
2549 used by the BASIC OPEN #channel,aux1,aux2,“H:filespec” command.
2550 The aux2 specifier will be ignored, valid aux1 values are:
2551 aux1 function
2554 ─────────────────────────────────────────
2555 4 open for read-only
2556 6 open the directory
2557 7 open the directory
2558 8 create for write-only
2559 9 open for append write-only
2560 12 open for read, write and append
2561 13 create for read, write and append
2562 This follows closely the DOS 2.0S conventions with the addition
2564 that mode 12 is able to write past EOF and mode 13 also creates
2565 files. Mode 7 is an addition that was made for compatibility of
2566 DOS 2.XL by the author.
2567 The filespec follows the file name convention explained in the
2569 previous subsection; the directory listing generated by codes 6
2570 and 7 will be formatted similar to the DOS 2.0S output for the
2571 same request, but the amount of free sectors will always show up
2572 as “999”. This is because there is basically no visual storage
2573 limit for a tiny Atari file system inside a Unix/Linux worksta‐
2574 tion. Files that are not user-writeable appear as “locked” and
2575 are marked with an asterisk in the first column. Similarly, file
2576 locking and unlocking changes the user-writeable protection bit
2577 of the host system.
2578 CMD 5: GET RECORD
2580 Reads characters up to an EOL character, or up to the buffer
2581 end, into a buffer. This is a standard command supplied by all
2582 handlers. This implements the BASIC INPUT #channel,var and
2583 related commands.
2584 CMD 7: GET CHARACTERS
2586 Reads a block of characters into a buffer. This is a standard
2587 command, consult the Atari technical manual for details. Not
2588 reachable from BASIC.
2589 CMD 9: PUT RECORD
2591 Writes characters up to an EOL or up to the end of the buffer
2592 into the opened stream. Also part of the standard command set.
2593 Not reachable from BASIC, but related to the BASIC command PRINT
2594 #channel,data.
2595 CMD 11: PUT CHARACTERS
2597 Writes a block of characters into a stream. A standard command.
2598 Not reachable within BASIC, but related to the BASIC commands
2599 PUT #channel,value and PRINT #channel,data.
2600 CMD 12: CLOSE
2602 Releases the given stream, closes the file on the host system
2603 and frees all buffers. This command is considered harmless on
2604 streams already closed. This implements the BASIC CLOSE #channel
2605 command.
2606 CMD 13: STATUS
2608 Requests the status of the given stream. It returns status code
2609 133 if the channel is not open, status code 1 if the channel
2610 generated no error, status code 3 if you are about to read from
2611 the EOF on the next go, or the last error should the stream be
2612 in an error condition otherwise. This follows standard conven‐
2613 tions.
2614 CMD 32: RENAME
2616 Implements the BASIC XIO 32,#channel,aux1,aux2,“H:oldname,new‐
2617 name” command. Note that the file specification of this command
2618 consists of an existing filename, a comma “,”, and a new file
2619 name. This command attempts to rename the existing file to a new
2620 name.
2621 CMD 33: DELETE
2623 Implements the BASIC XIO 33,#channel,aux1,aux2,“H:filespec” com‐
2624 mand and attempts to remove (delete) the given files or pat‐
2625 terns. It will fail if the files are not user-readable, i.e.
2626 appear “locked” in the emulator.
2627 CMD 34: VALIDATE
2629 An extension following DOS 3 conventions also reachable within
2630 BASIC with XIO 34, this command will check whether the given
2631 filespec is well-formed and will return an error code if not. It
2632 does not attempt to open any file.
2633 CMD 35: UNPROTECT
2635 Implements the XIO 35 command which “unlocks” the given file(s)
2636 and allows write-access into it. The host system reflects this
2637 operation by enabling the user-writeable permission bit.
2638 CMD 36: PROTECT
2640 Implements the BASIC XIO 36 command and “locks“ the filespec by
2641 removing the user write-permission bit.
2642 CMD 37: POINT
2644 Unlike command 32 to 36 above, this expects that the given chan‐
2645 nel is already linked to an open stream. It implements the basic
2646 POINT #ch,sector,byte command for placing the file pointer
2647 within the file. The Os. CIO places the sector offset in AUX4
2648 and AUX5 and the byte offset into AUX3. However, conventions for
2649 file addressing are different from DOS 2.0S and are more orthog‐
2650 onal. The H: handler appears to have sectors of 256 bytes each,
2651 numbered linearly from 0 up within each file. Sectors are not
2652 global within the filing sytem but local to the file linked to
2653 the channel. This is somewhat similar to the DOS 3 implementa‐
2654 tion of POINT.
2655 CMD 38: NOTE
2657 Similar to command 37, this command expects an open stream on
2658 the same channel, implementing the BASIC NOTE #ch,sector,byte
2659 command. It reads the file pointer within the opened file and
2660 returns byte and sector offsets using the same conventions as
2661 POINT. Bytes are numbered consequently from 0 to 255, and sec‐
2662 tors are numbered from the start of the file from zero up, each
2663 of them but possibly the last carrying 256 bytes of data. As
2664 long as programs use the values returned by NOTE as opaque val‐
2665 ues and avoid to perform algebra on them, this remains compati‐
2666 ble to the DOS 2.0S. However, programs expecting 125 byte sec‐
2667 tors and absolute sectoring are likely to fail.
2668 CMD 40: RESOLVE
2670 This command resolves a wild card sequence by a real filename.
2671 It reads the wildcard from IOCBAdr, and places the resolved
2672 filename back into the buffer pointed to by IOCBAdr as well. To
2673 be able to resolve non-unique wildcards, IOCBAux2 defines which
2674 of the non-unqiue matches shall be returned. It counts from one
2675 up, and returns the n-th found match to the specified wildcard.
2676 CMD 41: BINARY LOAD
2678 Load an executable file, and possibly initialize and run it if
2679 the file AUX2 specifies whether the loaded file shall be ini‐
2680 tialized or run. If set to 192, the file is initialized and run,
2681 128 means “init only”, 64 just runs, but does not initialize the
2682 file, and 0 neither runs nor initializes the file.
2683 Unimplemented commands
2686 The H: device does not implement the various format commands for
2687 obvious reason. It also doesn't implement some DOS 2.XL resp.
2688 DOS 3 extensions to initialize a DOS. Especially, opening the
2689 DOS.SYS file for writing will not perform anything special.
2690
2693 The operating system editor handler is responsible to collect user
2694 input from the screen, and output data back on it. It is usually left
2695 alone as all necessary components are emulated to let it function as
2696 is. However, to script the editor, it is sometimes feasible to redirect
2697 the output that would normally go to the editor of the machine to a
2698 Unix or Windows file, and to read input that would normally come from
2699 the keyboard from a file as well. For that, use the operating system
2700 patch -installedevice on which will replace the Atari handler by a
2701 patch running on the host system. Input data will be read from the
2702 standard input of the emulator command, and output will go both to the
2703 emulator front-end and the standard-output of the emulator command.
2704 Only a limited number control character transpositions will be avail‐
2705 able, though --- namely, the following standard ANSI control characters
2706 will be recognized and translated accordingly:
2707 \t Horizontal TAB
2710 \n New Line, transposed to EOL
2711 \b Backspace
2712 \a Bell
2713 \f Form Feed, transposed to Clear Screen
2714 Cursor movement and other advanced sequences are left alone, they are
2716 output device dependent and require a more careful analysis that
2717 depends on the console type used. If you need to run the emulator in a
2718 console, consider the curses front-end instead.
2719 Another limitation of the E: device patch is that it obviously cannot
2721 emulate the full-screen editor buffer of the Atari ROM as it has no
2722 access to the screen of the emulator. Instead, only the line-buffering
2723 of the console is available, i.e. the emulator will not be able to see
2724 your input unless you press RETURN. This also holds for the keyboard
2725 device, for which a patch is provided along with this patch. Specifi‐
2726 cally, if software running in the emulator requires you to press a key,
2727 you need to terminate this input by RETURN to make it accessible to the
2728 emulator.
2729
2732 The R: handler is part of the emulated 850 interface box and not spe‐
2733 cific to the emulator. A real 850 would also provide this handler.
2734 Unlike the H: handler, the R: handler is not installed by the emulator
2735 directly, and is not available unless it is booted by a dedicated file.
2736 An Atari DOS distribution should either contain a file named HAN‐
2737 DLERS.SYS or an apropriate AUTORUN.SYS file to bootstrap this handler.
2738 Dos 2.5, for example, provides a setup program to generate the apropri‐
2739 ate file. This bootstrap code is not specific to the emulator and works
2740 generically for the real, as for the emulated 850 interface box. For
2741 the real 850, the bootstrap code loads code from the interface into the
2742 Atari; for Atari++, this code is part of the 850 emulation, but uses
2743 otherwise the same command set as the real 850, providing maximal com‐
2744 patibility.
2745 The emulator even emulates some of the limitations of the 850 system:
2747 Once opened, the R: handler is in block mode , only allowing you to
2748 write blocks of data asynchroniously, but not allowing you to receive
2749 data. In block mode, 850 I/O can be mixed freely with any other disk
2750 I/O.
2751 With a special XIO command, the handler must be put into concurrent
2753 mode to be able to read and write data synchroniously. In this mode,
2754 data gets sent out immediately as it is written, and input data can be
2755 received back as soon as it arrives, but any other device on the serial
2756 chain is unreachable and cannot be used savely. Thus, the disk is
2757 unavailable in concurrent mode.
2758 COMMAND SET
2761 The following set of CIO commands are made available by the R: handler:
2762 CMD 3: OPEN
2764 Open a channel to the R: handler. Aux1 is either 8 for output
2765 only in block mode, 5 for input with concurrent mode support, 9
2766 for output in block and concurrent mode, and 13 for input/out‐
2767 put, including concurrent mode support. Aux2 is ignored.
2768 CMD 5: GET RECORD
2770 Reads characters up to an EOL character, or up to the buffer
2771 end, into a buffer. Reading is only available in concurrent
2772 mode. Read characters can be optionally translated from ASCII
2773 into ATASCII, see CMD 38 below.
2774 CMD 7: GET CHARACTERS
2776 Reads a block of characters into a buffer. Again, only available
2777 in concurrent mode.
2778 CMD 9: PUT RECORD
2780 Writes characters up to an EOL or up to the end of the buffer
2781 into the opened stream. Available in block mode or in concurrent
2782 mode. In block mode, data is buffered and transmitted as soon as
2783 either the buffer becomes full, or an EOL is sent. In concurrent
2784 mode, data is sent out immediately. In both modes, characters
2785 can be optionally translated from ATASCII into ASCII.
2786 CMD 11: PUT CHARACTERS
2788 Writes a block of characters into a stream, not necessarely ter‐
2789 minated by an EOL. Otherwise identically to the above.
2790 CMD 12: CLOSE
2792 Releases the given stream, possibly empties the buffer in block
2793 mode, or waits until the write buffer is empty in concurrent
2794 mode.
2795 CMD 13: STATUS
2797 Requests the status of the given stream. Additionally, memory
2798 locations $2ea to $2ed are filled with useful information. Loca‐
2799 tion $2ea contains the error flags of the serial transfer as
2800 follows:
2801 Bit Meaning
2804 7 received a framing error
2805 6 input register overrun error
2806 5 parity error detected
2807 4 input buffer overrun error
2808 The difference between bit 6 and bit 4 is that bit 6 gets set if
2810 the emulated Atari could not react fast enough on interrupts,
2811 and bit 4 gets set if the user-provided input buffer overruns in
2812 receive mode, though the data could have been catched success‐
2813 fully.
2814 Location $2eb contains the state of the handshake lines in block
2816 mode:
2817 Bit Meaning
2820 7 current status of the DSR line
2821 6 previous status of the DSR
2822 5 current status of the CTS line
2823 4 previous status of the CTS line
2824 3 current status of the CD line
2825 2 previous status of the CD line
2826 1,0 unused, reserved
2827 The history bits mirror the state of the lines that has been
2829 returned by the previous “STATUS” command.
2830 Locations $2ec to $2ed are unassigned in block mode.
2832 In concurrent mode, $2eb and $2ec contain the low- and high-byte
2834 representing the number of characters in the input buffers,
2835 respectively. Location $2ed contains the number of characters in
2836 the output buffer.
2837 CMD 32: FORCE
2839 Flushes the output buffer in block mode, or waits until the out‐
2840 put buffer has been transmitted in concurrent mode.
2841 CMD 34: SETLINES
2843 Only available in block mode, not in concurrent mode. This com‐
2844 mand selects the states of the output lines RTS and DTR. On the
2845 real 850, the state of the data line TxD can be selected, too.
2846 The bits in Aux1 are interpreted as follows:
2847 Bit Meaning
2850 7 change the state of the DTR line
2851 6 new state of DTR if bit 7 is on
2852 5 change the state of the RTS line
2853 4 new state of RTS if bit 5 is on
2854 3 ignored, reserved
2855 2 ignored, reserved
2856 1 change the state of the TxD line
2857 0 new state of TxD if bit 1 is on (unsupported)
2858 Currently, the emulator does not support direct state changes on
2860 TxD, though. The value of Aux2 is ignored.
2861 CMD 36: SETBAUD
2863 Specifies the baud rate and other serial transfer parameters,
2864 and handshaking. Only available in block mode, not available in
2865 concurrent mode. The bits in Aux1 are interpreted as follows:
2866 If bit 7 is set, at least two, maybe more stop bits are gener‐
2868 ated. If the bit is clear, one stop bit, maybe more can be gen‐
2869 erated. Bit 6 is unsed, Bits 5 and 4 specify the number of data
2870 bits: If set to zero, eight data bits are transmitted, for 16
2871 (bits = 0,1 resp.) seven bits are used, for 32 (bits = 1,0) six
2872 data bits are generated, and for 48 (bits = 1,1) five data bits
2873 are sent. Bits 3 to 0 define the baud rate according to this ta‐
2874 ble:
2875 Value Baud rate
2878 0 remain unchanged
2879 1 45.5 (not emulated)
2880 2 50
2881 3 56.875 (not emulated)
2882 4 75
2883 5 110
2884 6 134.5 (emulated as 134 baud)
2885 7 150
2886 8 300
2887 9 600
2888 10 1200
2889 11 1800
2890 12 2400
2891 13 4800
2892 14 9600
2893 15 9600
2894 Note that values 14 and 15 generate the same rate.
2896 The bits of Aux2 indicate which serial lines have to be moni‐
2898 tored if concurrent mode is entered. If the selected serial
2899 lines are not set, an error is generated. For the emulator, mon‐
2900 itoring of CTS also enables hardware handshake.
2901 Bit Line
2904 7..3 reserved, unused
2905 2 monitor DSR
2906 1 monitor CTS, enable hardware handshake
2907 0 monitor CD
2908 CMD 38: SETPARITY
2911 This command is available in block as well as in concurrent
2912 mode. It selects character translations from ASCII into ATASCII
2913 and vice versa, and selects input and output parity. The bits in
2914 Aux1 have the following meaning:
2915 Bit Meaning
2918 7 reserved, unused
2919 6 if enabled, a LineFeed is inserted after each generated CR
2920 5,4 ASCII<->ATASCII translation, see below.
2921 3,2 input parity
2922 1,0 output parity
2923 If the character translation is set to 0, EOL is translated to
2925 CR (not LF!) and vice versa, and bit 7 is stripped off. If set
2926 to 16 (bits = 0,1), additionally non-ASCII characters are not
2927 written, resp. replaced by Aux2 on input.
2928 If the parity bits are set to zero, data is read or written “as
2930 is”. This especially implies that parity bits and stop bits of
2931 the input data are not stripped off. Furthermore, on output only
2932 eight data bits can be generated, unless the upper bits are set
2933 to one manually to emulate stop bits.
2934 If the parity bits are set to one (bits = 0,1), odd parity is
2936 generated or checked for. This works only for seven or less data
2937 bits.
2938 For the parity bits set to two (bits = 1,0), even parity is gen‐
2940 erated or checked for seven or less data bits.
2941 For parity bits set to three (both bits set, bits = 1,1), the
2943 parity bit is stripped off on input, and always set on output
2944 (parity = SPACE).
2945 Aux2 of this command specifies a “garbadge character” that gets
2947 inserted for full character translation whenever a non-ATASCII
2948 character is received.
2949 CMD 40: STARTCONCURRENT
2952 Enters the concurrent mode from block mode. The only way to
2953 leave the concurrent mode again is to close and re-open the
2954 channel. Aux1 and Aux2 are irrelevant for this command, but
2955 IOCBAdr and IOCBLen might provide the location and size of an
2956 optional input buffer where incoming data is kept until it is
2957 read off. This buffer should better be large for “higher” baud
2958 rates. If no input buffer is supplied, i.e. IOCBAdr is set to
2959 NULL, the handler will provide a short 32 byte input buffer.
2960 On entering concurrent mode, the input lines specified by the
2962 “SETBAUD” command are monitored once. If the selected lines are
2963 not set, an error is generated. The real 850 interface does not
2964 provide full hardware handshaking, the emulated 850 does by mon‐
2965 itoring CTS.
2966
2969 The Atari++ emulator provides its own operating system in case no Atari
2970 ROM image is available. This makes the emulator self-contained as you
2971 don't require to hold any usage rights on the original ROMs to run it.
2972 The built-in ROM implements a full Atari XL operating system and tries
2973 to be compatible to the XL ROM in most aspects; however, since it is a
2974 re-implementation, absolute ROM addresses and implementation details
2975 may, and will, differ. The paragraphs below give a brief overview on
2976 the ROM features, the subsections discuss the features in more detail.
2977 Built-in FMS (DOS)
2980 The built-in operating system comes with its own file management
2981 system, unlike the original Atari ROMs. This is classically, but
2982 imprecisely, called the DOS (Disk Operating System). This FMS is
2983 used in case no bootable disk is available on bootstrap. This
2984 allows easy loading and saving of binary images without requir‐
2985 ing an Atari copyrighted FMS. For details, see the FMS subsec‐
2986 tion below.
2987 Parallel Port Support
2990 has been dropped. This is because Atari++ neither emulates any
2991 parallel port devices, nor does the author has any usable docu‐
2992 mentation about it.
2993 The MathPack
2996 is classically not considered part of the operating system, but
2997 is emulated fully with all documented and some undocumented
2998 entry points the author is aware of. The emulation is complete
2999 enough to allow BASIC and many other programs operate properly,
3000 except that the re-implementation is usually a bit and sometimes
3001 considerably faster. You might also consider the MathPack patch
3002 option that evaluates the mathematical operations on the host
3003 CPU.
3004 The C: Tape handler
3007 is replaced by a dummy. This is because Atari++ does not emulate
3008 the tape device, and the ROM space was required.
3009 CHARACTER GENERATOR
3012 The international character set at position 0xcc00 and up has been
3013 slightly modified. Character position 8 (Ctrl-H) is now the Euro-sign,
3014 character position 96 (Ctrl-.) is the german sharp-s. The pound sign
3015 and the inverted exclamation mark are no longer available.
3016 INTERRUPT HANDLING
3019 VBI Handler
3020 The built-in Os vertical retrace handler (VBI) does not check
3021 whether TRIG3 and its shadow-register coincide. This avoids a
3022 couple of deadlock situations in various games that overwrite
3023 the shadow register. VBI handling of 1200XL keyboard features is
3024 not present since atari++ does not emulate these keys and the
3025 author has no precise documentation about them.
3026 IRQ Handler
3028 The IRQ handler is more streamlined than the original IRQ han‐
3029 dler; it also no longer handles any parallel port related inter‐
3030 rupts since they are never generated by the emulator.
3031 KERNEL
3034 Parallel port call-ins
3035 have been replaced by dummies.
3036 0xe48f: BOOT850
3038 This is a new kernel-call in that bootstraps the 850 interface
3039 handler thru SIO. It should be typically used by a minimal HAN‐
3040 DLERS.SYS file that contains nothing but a RUN-vector to this
3041 call-in.
3042 0xe45c: SETIRQVECTOR
3044 The SetIRQVector call-in can now also savely install IRQs as
3045 well without requiring the caller to set the interrupt bit of
3046 the CPU.
3047 RESET/Bootstrap
3050 Tape bootstrap
3051 Since the built-in Os does not implement a usable tape device,
3052 tape bootstrap is no longer supported. The CASINIT vector
3053 (0x02/0x03) is, however, emulated properly.
3054 Disk bootstrap
3056 The built-in Os tries to bootstrap the disk as usual, but does
3057 not loop forever in case it detects that no disk is inserted in
3058 the drive. In case an usable boot block is found, the resident
3059 FMS is not installed and a disk-based DOS can replace it, as
3060 usual. The resident FMS is launched if either no usable boot
3061 block is found, no usable disk is found, or the user holds down
3062 the START key on bootstrap. An unusable boot block is indicated
3063 by a bootstrap address of zero, thus by a blank boot block. Note
3064 that START is no longer an indication for tape bootstrap since
3065 there is no tape support. In case the built-in FMS gains control
3066 in the boot process, see below in the FMS subsection for further
3067 bootstrap activity.
3068 850 interface bootstrap
3070 In case the disk bootstrap failed because no disk is inserted,
3071 the ROM also tries to bootstrap the 850 interface box since no
3072 HANDLERS.SYS file can be loaded then.
3073 SELFTEST
3076 The ROM space occupied by the self-test was required for the DOS com‐
3077 mand line (the DUP ) and is therefore no longer part of the Os.
3078 Instead, the following color codes appear on the screen if the power-on
3079 tests fail:
3080 Color code RED
3082 The RAM test failed, a faulty RAM chip has been detected.
3083 Color code PINK
3085 The ROM checksum is faulty.
3086 Color code BLUE
3088 The bootstrap code could not open the initial editor handler.
3089 SERIAL I/O (SIO)
3092 SIO interrupts
3093 The serial communication is initiated thru the Pokey XMTDONE
3094 interrupt. This makes it easier for future extensions to relo‐
3095 cate disk buffers under the Os ROM.
3096 Parallel port handling
3098 of SIO communications has been dropped due to lack of ROM space
3099 and documentation.
3100 Tape device handling
3102 is no longer provided by SIO since Atari++ does not emulate the
3103 tape anyhow. Trying to use the tape thru SIO will now initiate a
3104 standard serial communication and will no longer use two-tone
3105 modulation. Thus, tapes won't work as expected.
3106 Resident Disk handler (DISKINTERF)
3109 Format command
3110 The DISKINTERF vector handles now the enhanced density format
3111 command of the 1050 floppy drive correctly. Thus, it supports
3112 the 1050 command set fully.
3113 Parallel port I/O
3115 thru DISKINTERF via SIO is no longer possible since SIO does not
3116 try to interact with the parallel port any more.
3117 CENTRAL I/O (CIO)
3120 CIO CMD_OPEN
3121 The CIO OPEN command installs now the PUT ONE BYTE vector before
3122 calling the OPEN vector of the corresponding handler. This
3123 allows the handler to overload this vector in order to implement
3124 “bursting” more easily. Currently, the FMS makes use of this
3125 feature to avoid the check whether it was called from the BASIC
3126 ROM that incorrectly uses this vector.
3127 CIO HATABS extension
3129 thru the parallel port linked list is not implemented since the
3130 author has no sufficient documentation about its implementation
3131 and usage.
3132 CIO handler bootstrap
3134 is no longer supported due to lack of documentation.
3135 THE C: TAPE HANDLER
3138 is only a dummy that returns error conditions on all I/O operations. It
3139 only remained in the ROM to allow the H: handler to patch it over.
3140 THE K: KEYBOARD HANDLER
3143 should work mostly like its equivalent in the Atari 800XL ROM except
3144 that it does not check for Atari 1200XL function keys. Extended editor
3145 keyboard functions are provided to the best knowledge of the author,
3146 though. The K: handler respects now the BREAK key correctly.
3147 THE E: EDITOR
3150 The editor device is much more decoupled from the screen handler than
3151 in the original ROM, see also the S: handler section below.
3152 Editor Buzzer
3154 The buzzer is run on a cursor position that depends on the edi‐
3155 tor margins now. It is also rung on character insertion if char‐
3156 acters are likely to be moved out of the screen.
3157 Editor Window
3159 Unlike the original Atari Editor device, the emulated E: handler
3160 allows arbitrary high editor windows, not just four or 24 lines
3161 - if programmed properly.
3162 Editor Scrolling
3164 on line insertion or delection does no longer erraneously try to
3165 overwrite the ROM area.
3166 THE S: SCREEN HANDLER
3169 As mentioned above, the S: handler is decoupled from the E: handler and
3170 therefore reacts in certain aspects differently than its original coun‐
3171 terpart.
3172 Screen GET/PUT
3174 The S: handler no longer tries to scroll, neither does it
3175 respect editor margins. If the put or get commands reach the end
3176 of the screen, an out-of-bounds error (error 141) is generated.
3177 Open Command
3179 The S: open provides more graphic modes than the original. If 64
3180 is added to the graphics mode, then a text window is generated
3181 even for the graphic modes 9, 10 and 11. Smooth scrolling works
3182 flawlessy even in these text windows.
3183 DMA/Player-Missile
3185 The S: handler no longer interacts with player/missile graphics
3186 and respects the corresponding bits in the DMACTRL shadow regis‐
3187 ter.
3188 Out of memory situations
3190 will be handled more graceful than in the original ROM.
3191 THE P: PRINTER HANDLER
3194 The built-in ROM supports the printer to full extend, and no functional
3195 changes should hopefully appear.
3196 MATH PACK
3199 The MathPack is not part of the operating system, but historically part
3200 of the BASIC. As a consequence, the math pack is does not provide a
3201 jump-in table as the operating system, and fixed ROM-addresses must be
3202 used.
3203 Atari++ also provides an emulation, or rather a replacement implement‐
3205 ing the same routines as the original math ROM. The precision and speed
3206 of the re-implementation should be superior to the original ROM imple‐
3207 mentation. However, it is, in general though, advisable to use the
3208 MathPackPatch which is again a lot faster and still more precise than
3209 the re-implementation because it uses the floating-point math of the
3210 host machine.
3211 NOTE: While the author tried its best to make the replacement math-pack
3213 as compatible as possible to the original ROM, some problems should be
3214 expected. BASIC and MAC/65 software should be mostly unaffected, but
3215 since Atari never provided a jump-in table for the math-pack, third-
3216 party software might use routines of the math-pack that have never been
3217 officially documented, and are not provided by the emulation. Despite
3218 that, this math-pack replacement does already contain a number of in-
3219 official call-ins that are used by BASIC and other software. Neverthe‐
3220 less, numerical results obtained by this implementation might differ
3221 from the original due to round-off issues where the re-implementation
3222 offers often better more precise results.
3223 The replacement math-pack provides the following routines and data:
3225 AFP $d800
3228 Convert the ATASCII number in the buffer pointed to by "inbuff"
3229 ($f3,$f4) at offset given by "cix" ($f2) into a floating point
3230 number in "fr0" ($d4 to $d9). On output, "cix" points to the
3231 first character that could not be converted. The carry register
3232 is set in case no conversion could be conformed at all. Unlike
3233 the original, this routine operates at ten instead of nine-dig‐
3234 its precision and rounds properly if more than ten digits are
3235 provided.
3236 FASC $d8e6
3239 Convert the floating point number in "fr0" ($d4 to $d9) into
3240 ATASCII in the output buffer at $580 and following. "fr0" is
3241 destroyed on completion. The end of the string is indicated by
3242 having the last character have its MSB set, the final string is
3243 pointed to by "inbuff" ($F3,$F4) on exit. Unlike the ROM imple‐
3244 mentation, this routine is more streamlined and does not over‐
3245 write bytes in front of the output buffer, the output will
3246 always start at, and not sometimes in front of $580. If called
3247 at FASC+3, the user can define its output buffer where he likes
3248 by placing the address into "inbuff". This is not available in
3249 the original ROM.
3250 IFP $d9aa
3253 Convert the unsigned integer in "fr0"(lo) and "fr0+1"(hi) into a
3254 floating point representation to "fr0" ($d4 to $d9). Unlike in
3255 the original ROM ,"IFP+4" converts the integer in the registers
3256 X(lo) and Y(hi) into floating point.
3257 FPI $d9d2
3260 Convert the floating point number in "fr0" ($d4 to $d9) into a
3261 two-byte integer representation, also in "fr0" and "fr0+1",
3262 rounded correctly to the nearest integer. If the conversion is
3263 not possible, the carry bit will be set. The original implemen‐
3264 tation had a couple of issues on overflow and rounding that are
3265 not reproduced here.
3266 ZFR0 $da44
3269 Initialize the "fr0" register ($d4 to $d9) with zero.
3270 AF1 $da46
3273 Initialize the six-byte floating point register pointed to by
3274 the X register with zero.
3275 ZERORGS $da48
3278 Clear N bytes starting at the zero-page register given by X,
3279 where N is given in the Y register. This inofficial call-in is
3280 used by Mac/65 and BASIC.
3281 LOADOUTBUFF $da51
3284 Initialize the "inbuff" zero page registers ($f3 and $f4) to
3285 point to the floating point output buffer at $580. Used by BASIC
3286 and MAC/65.
3287 FADD $da66
3290 Add the contents of the floating point register "fr1" ($e0 to
3291 $e5) to the floating point register "fr0" ($d4 to $d9). "fr1"
3292 will be destroyed. Sets the carry in case the representation
3293 overflows, and destroyes "fr1". Unlike the orignal, this routine
3294 employes a correct "round to nearest" policy if the output can‐
3295 not be represented exactly, and it also uses denormalized num‐
3296 bers if the output is very close to zero.
3297 FSUB $da60
3300 Subtracts the contents of the floating point register "fr1" ($e0
3301 to $e5) from the floating point register "fr0" ($d4 to $d9).
3302 "fr1" will be destroyed. Otherwise, works like the floating
3303 point addition and its new round-to-nearest mode.
3304 FMUL $dadb
3307 Multiplies the contents of "fr1" ($e0 to $e5) with "fr0" ($d4 to
3308 $d9) and places the result in "fr0". "fr1" will be destroyed. On
3309 overflow, the carry flag of the processor will be set. Like
3310 addition, this routine uses a smarter round-to-nearest policy,
3311 and unlike the original, has all issues on detecting overflows
3312 fixed, specifically, multiplying two very small numbers will
3313 give zero, not an overflow. It will also handle denormalized
3314 numbers correctly, and is noticably faster than the original.
3315 FDIV $db28
3318 Divides the contents of "fr0" ($d4 to $d9) by the contents of
3319 "fr1" ($e0 to $e5) and places the result in "fr0", destroying
3320 "fr1". On overflow or divide by zero, the carry flag will be
3321 set. This routine also uses a precise round-to-nearest policy.
3322 Unlike the original routine, dividing a small number by a very
3323 large number will not create an overflow, but - as appropriate -
3324 zero.
3325 SKIPBLANKS $dba1
3328 This routine is not officially documented but nevertheless used
3329 by Mac/65. It skips all blank-characters in the input buffer
3330 ($f3,$f4) at offset in "cix" ($f2) and adjusts "cix" such that
3331 it points at the first non-blank character.
3332 TESTDIGIT $dbaf
3335 Another inofficial function used by Mac/65 and BASIC. This func‐
3336 tion tests the character at "inbuff" ($f3,f4) at offset "cix"
3337 ($f2) for a valid decimal digit and returns the numerical value
3338 of this digit and the carry flag cleared if possible. Otherwise,
3339 on an invalid digit, the carry flag gets set.
3340 NORMALIZE $dc00
3343 This method is neither officially documented, but used neverthe‐
3344 less by BASIC and Mac/65. It normalizes the floating-point num‐
3345 ber in "fr0" ($d4 to $d9), eliminating leading zero-digit pairs
3346 in the mantissa and adjusting the exponent accordingly. It
3347 returns with the carry flag cleared on success and with the
3348 carry set on overflow. Unlike the original implemenation, this
3349 version leaves near-zero numbers denormalized, and overflows at
3350 a decimal exponent of 100, not at 99 as the original.
3351 PLYEVL $dd40
3354 Evaluates the polynomial whose floating point coefficients are
3355 pointed to by X(lo) and Y(hi) at the location given by "fr0"
3356 ($d4 to $d9). The number of coefficients, and hence the degree
3357 of the polynomial plus one is passed in the accumulator on
3358 entry. Returns the result in "fr0", and destroys "fr1" ($e0 to
3359 $e5), sets the carry flag on overflow.
3360 FLD0R $dd89
3363 Load "fr0" ($d4 to $d9) with the floating point value pointed to
3364 by X(lo) and Y(hi).
3365 FLD0P $dd8d
3368 Load "fr0" ($d4 to $d9) with the floating point value pointed to
3369 by "flptr" ($fc,$fd).
3370 FLD1R $dd98
3373 Load "fr1" ($e0 to $e5) with the floating point value pointed to
3374 by X(lo) and Y(hi).
3375 FLD1P $dd9c
3378 Load "fr1" ($e0 to $e5) with the floating point value pointed to
3379 by "flptr" ($fc,$fd).
3380 FSTOR $dda7
3383 Store "fr0" ($d4 to $d9) to the six-byte memory buffer pointed
3384 to by X(lo) and Y(hi).
3385 FSTOP $ddab
3388 Store "fr0" ($d4 to $d9) to the six-byte memory buffer pointed
3389 to by "flptr" ($fc,$fd).
3390 FMOVE $ddb6
3393 Copy the contents of "fr0" ($d4 t0 $d9) to "fr1" ($e0 to $e5).
3394 EXP $ddc0
3397 Compute a the exponential function at the location given by
3398 "fr0" ($d4 to $d9), destroys the contents of "fr1". Returns with
3399 the result in "fr0" and the carry cleared on success, with carry
3400 set on overflow.
3401 EXP10 $ddcc
3404 Computes 10 to the power of the number given in "fr0" ($d4 to
3405 $d9), destroys the contents of "fr1", returns with the carry set
3406 on overflow or the proper result in "fr0". This implementation
3407 is not only faster than the original ROM implementation, it is
3408 also more precise - in general, nine to ten correct digits can
3409 be expected. It also has a couple of issues of the original
3410 implementation fixed, namely the exponential of a very negative
3411 number yields zero, not an overflow, and the exponential of ten
3412 to an integer power is always integer. BASIC uses this function
3413 to compute the exponential, via the call-in above, but also to
3414 compute the power function (a^b). Unfortunately, due to a bug in
3415 BASIC revisions B and C (but not in revision A), BASIC always
3416 rounds the result up to the next integer if a and b are integer,
3417 with the side effect that if the result of this method is a tiny
3418 little bit too large, the output will be off by one. For exam‐
3419 ple, computing 4^4 results in 256.000002, which is correct to
3420 nine places, but which is rounded by BASIC to 257. This is a bug
3421 in BASIC and not in this implementation; the coefficients have
3422 been carefully choosen to avoid such situations for lower expo‐
3423 nents, i.e. for b=1 to 3, the result will be always correct.
3424 Enforcing correct results for higher exponents would have
3425 resulted in a major precision loss just to work around old bugs,
3426 which was considered inappropriate.
3427 FFRAC $de95
3430 This is another call-in that is used by BASIC which is not offi‐
3431 cially documented. It computes the rational function (x-C)/(x+C)
3432 where the value of x is given by the contents of the "fr0" reg‐
3433 ister ($d4 to $d9) and C is stored as a six-byte floating point
3434 number pointed to by X(lo) and Y(hi). On exit, the carry flag is
3435 set on overflow, and clear on success. Then, the result is given
3436 in the "fr0" register.
3437 LOG $decd
3440 Compute the natural logarithm of the number given in "fr0" ($d4
3441 to $d9). Returns with the carry set on overflow, or zero or neg‐
3442 ative input, otherwise with the result in "fr0".
3443 LOG10 $ded1
3446 Compute the decadic logarithm (logarithm to the base of ten) of
3447 the number given in "fr0" ($d4 to $d9). Returns with the carry
3448 set on overflow, negative or zero input, and carry cleared and
3449 the proper result in "fr0" otherwise. This method can be
3450 expected to be faster and more precise than the original ver‐
3451 sion.
3452 ONEHALF $df6c
3455 Not a call-in, but rather a floating-point constant that is used
3456 by BASIC for various purposes, most notably for the SQR func‐
3457 tion. Its value is 0.5.
3458 ATNCOEFF $dfae
3461 This is not a call-in, but rather a table of eleven floating
3462 point constants representing the coefficients of the minimax-
3463 approximation of the arcus tangens in the interval from 0 to 1.
3464 It is used by the BASIC implementation of the ATN function.
3465 NEARONE $dfea
3468 Part of the above table, but also used by BASIC separately, this
3469 is the constant term of the above polynomial, and also used to
3470 adjust coefficients outside the interval 0..1 by means of the
3471 functional equation of ATN. The value of this constant should be
3472 exactly one in an ideal infinite-precision implementation, but
3473 due to various round-off errors, it is 0.9999999999.
3474 PIOVER4 $dff0
3477 Another floating point constant used by BASIC, here the value of
3478 Pi divided by four correct to ten decimal places. It is used by
3479 the ATN function in the BASIC rom.
3480 THE D: HANDLER
3483 This handler is provided by the now built-in FMS that is used if disk-
3484 bootstrap was unsuccessful or aborted by the user, see also above. The
3485 FMS in ROM space is basically a reworked and bugfixed version of Dos
3486 2.XL/XA of the same author that was streamlined to fit into the low
3487 memory Os area 0xc002 to 0xcbff. It therefore provides 963 free sectors
3488 on a standard enhanced density disk while retaining Dos 2.0S compati‐
3489 bility. It can read Dos 2.5 disks, but it is not write-compatible to
3490 Dos 2.5. This route was choosen basically because the author had the
3491 Dos 2.XL sources available for obvious reasons, unlike the Dos 2.5
3492 sources. The following documents the FMS command set:
3493 CMD 3:OPEN
3495 Opens a file. Details depend on AUX1 and AUX2. For AUX1 = 0, the
3496 following modes are used:
3497 aux1 function
3499 ───────────────────────────────────────────────────────────
3500 4 open for read-only
3501 6 open for directory reading, including the disk name
3502 7 open the directory, excluding the disk name
3503 8 create/overwrite for write-only
3504 9 open for append write-only
3505 12 open for read and write (update).
3506 13 create for read, write and append
3507 Note that mode 9 does not waste a sector, unlike the Dos 2.0S
3509 implementation. Mode 12 is the update mode, it generates an EOF
3510 condition in case it is attempted to extend the file over its
3511 initial size. Mode 13 is new and automatically extends the file
3512 over its boundary should a write past the EOF be sent. Unlike
3513 mode 9, the file pointer is positioned at the start of the file
3514 initially. Mode 6 also includes a disk title should it be pro‐
3515 vided.
3516 For AUX2 = 128, things change dramatically. This mode provides
3518 full random access to the raw disk without any file management
3519 functions; thus, this mode allows “raw” access to disks. File
3520 names do not matter here, and sectors are always 128 bytes long.
3521 The disk is understood as one big sequential file starting at
3522 sector one and extending to its last sector. Access to sectors
3523 is provided by means of the POINT/NOTE commands. The following
3524 open modes are available for AUX1 = 128:
3525 aux1 function
3527 ──────────────────────────────────────────────────────────
3528 4 open for read-only. Reads raw sectors sequentially
3529 8 create for write-only. Writes raw sectors.
3530 12 open for simulateous raw read and write
3531 CMD 5: GET RECORD
3534 The standard CIO record reading command. Reads bytes until the
3535 record is full or an EOL is detected.
3536 CMD 7: GET CHARACTERS
3538 Reads characters into the buffer until either the buffer is full
3539 or an EOF condition is reached. The FMS tries to bypass CIO,
3540 i.e. it tries to “burst” to speed up processing.
3541 CMD 9: PUT RECORD
3543 Writes bytes to the file/disk until either the buffer becomes
3544 empty, and EOL is found in the buffer or an EOF condition is
3545 generated.
3546 CMD 11: PUT CHARACTERS
3548 Writes characters to the file until the buffer becomes empty or
3549 an EOF condition is generated. This command also implies burst‐
3550 ing, if possible.
3551 CMD 12: CLOSE
3553 Closes the file, writes the last buffer out and updates the
3554 directory unless the stream is ”raw“.
3555 CMD 13: STATUS
3557 Checks the given filespec for validity, tests wether the given
3558 disk is available and readable, and whether the file can be
3559 written to. Otherwise, apropriate error conditions are gener‐
3560 ated.
3561 CMD 32: RENAME
3563 Renames files. Requires the old filespec, then a comma, and the
3564 new target file name. This command may cause several identically
3565 named files, see below for file name specifications how to
3566 resolve this problem.
3567 CMD 33: DELETE
3569 Delete one or several files on the disk.
3570 CMD 34: FIND
3572 Resolves a wild card filespec and returns a full file name in
3573 the input buffer. If several files match the wildcard, the value
3574 of the AUX2 selects the number of the file that is to be
3575 resolved. This command is used by the command line interpreter
3576 (“DUP”) to resolve wild-cards. This command is here to maintain
3577 Dos 3 compatibility, the author suggests to use CMD 40 instead.
3578 CMD 35: LOCK
3580 Prevents a file or several files from getting overwritten by
3581 setting their write-protecting bits.
3582 CMD 36: UNLOCK
3584 Removes the write-protection lock on a file or several files.
3585 CMD 37: POINT
3587 Places the file pointer at a given file/sector position. Unfor‐
3588 tunately, the FMS doesn't provide simple sequential accessing of
3589 files, but rather expects an absolute sector/byte offset in
3590 AUX3,AUX4 (sector) and AUX5 (byte), similar to Dos 2.0S. If an
3591 invalid write position is specified here, then the disk might
3592 get corrupted. Only file pointers obtained by a previous NOTE
3593 onto the same file should be passed in as arguments here. This
3594 command is also used for absolute positioning within the disk if
3595 the corresponding stream is opened for raw mode, i.e. with AUX2
3596 = 128.
3597 CMD 38: NOTE
3599 Returns the current file pointer as sector/byte offset to be
3600 used for a future POINT command. AUX3/4 contain the low/high-
3601 byte of the sector, AUX5 the sector offset.
3602 CMD 39: INIT
3604 Clears and initializes the disk, erasing all files, but not for‐
3605 matting the disk. This is a quick format for disks that have
3606 been formatted already. Optionally, a disk title can be given
3607 behind the device specification. This title will then appear in
3608 reverse video on each directory listing.
3609 CMD 40: FIND
3611 Similar to CMD 34 to maintain Dos 2.XL compatibility. This is
3612 the suggested FIND command.
3613 CMD 41: BINARY LOAD
3615 Loads a binary file from disk, possibly initializing and running
3616 the binary. AUX2 specifies whether the loaded file shall be
3617 initialized or run. If set to 192, the file is initialized and
3618 run, 128 means “init only”, 64 just runs, but does not initial‐
3619 ize the file, and 0 neither runs nor initializes the file.
3620 CMD 42: FORMAT
3622 Formats a disk in various sizes. If AUX1 is set to 33, then the
3623 disk is formatted in single density to 707 sectors. For AUX1 set
3624 to 34, then an enhanced density format is initiated, resulting
3625 in a 963 sector disk. All other values are reserved. This com‐
3626 mand also accepts a disk title.
3627 CMD 43: FORMAT ENHANCED
3629 Initiates a standard enhanced density format, independent of
3630 AUX1 and AUX2. This also accepts a disk name, similar to the
3631 above.
3632 CMD 254: FORMAT ENHANCED
3634 Identical to CMD 43.
3635 FMS FILE SPECS
3638 The built-in FMS defines the following rules for filenames; these rules
3639 are very close to those formulated by Dos 2.0S.
3640 The first character must be an uppercase letter, all remaining charac‐
3642 ters must be uppercase letters or digits. A file name consists of at
3643 most eight characters, and an optional three character extender behind
3644 a dot (“.”). Three wild card-characters are understood: The question
3645 mark “?” that matches one single arbitrary character, the asterisk “*”
3646 that matches a sequence of arbitrary characters except the dot, and the
3647 dash “-” that is equivalent to the wild-card sequence “*.*” and thus
3648 matches any file.
3649 Additionally, the FMS supports access mode modifiers that can be
3651 appended to a file name to change the behaivour of the command. These
3652 modifiers are appended behind a slash, “/”, e.g. “D:FILE/A”. The fol‐
3653 lowing modifiers are understood:
3654 /A Open a file for append mode instead of write mode, i.e. change
3657 mode 8 to mode 9. Also changes the plain directory mode to the
3658 restricted directory mode that suppresses the disk name, and
3659 modifies mode 12 to mode 13. All other combinations are invalid.
3660 This modifier is useful in the FMS command line in combination
3661 with the COPY command to append one file to another.
3662 /D Changes the open mode from reading to directory reading, i.e.
3665 changes mode 4 to mode 6. This is, for example, useful in the
3666 FMS command line to print the directory by means of COPY
3667 D:-/D,P:
3668 /O Does not modify the open mode, but rather disables verify writes
3671 and uses the faster write without verify disk command. This
3672 makes writes faster at the price of possibly hiding write errors
3673 on bad disks.
3674 /V Similar to the above, though it enables verify writes.
3677 /N Only used together with the BINARY LOAD command to disable
3680 launching the program after having loaded it.
3681 /1../9 If several identically named files exist, access the n-th file
3684 of them. This access modifier allows to specify one of several
3685 identically named files as they could have been created by the
3686 Rename command.
3687 Note that the file spec “DOS.SYS” is not at all special for the FMS,
3689 unlike DOS 2.0S; it will refer to a standard regular file. The FMS will
3690 never ever try to write itself to disk. Thus, even the FMS can write
3691 the disk structure of Dos 2.XL fine on disk initialization, these disks
3692 will not be bootable without the ROM FMS.
3693 FMS ERROR CODES
3696 The FMS generates the following error codes; Not listed here are
3697 generic SIO errors that are generated by the Os kernel, not by the FMS:
3698 Error 160, IllegalUnit
3701 The requested disk unit is not available.
3702 Error 161, TooManyFiles
3705 Too many files are open at once, the FMS run out of buffers.
3706 Error 162, DiskFull
3709 No more free store on the disk.
3710 Error 164, FileLinkBroken
3713 Fms structure found damaged, possibly because of an invalid
3714 POINT.
3715 Error 165, FileNameInvalid
3718 The file name is invalid.
3719 Error 166, InvalidPoint
3722 An argument to POINT was out of range.
3723 Error 167, FileProtected
3726 A write operation to a locked file was attempted.
3727 Error 169, DirectoryFull
3730 Could not create a file since the directory was filled.
3731 Error 170, FileNotFound
3734 The specified filespec does not exist.
3735 Error 175, NoBinaryFile
3738 The specified file is not a binary load file.
3739 Error 176, BadLinkage
3742 Found a bad sector link to sector #0, the disk structure is dam‐
3743 aged.
3744 Error 177, InvalidMode
3747 The specified open mode is invalid.
3748 THE COMMAND LINE PROCESSOR (DUP)
3751 The built-in FMS also provides a disk utility package (a “DUP”). It is
3752 activated from BASIC via the DOS command, or is run automatically if no
3753 cart is found inserted.
3754 The command line accepts commands similar to a Linux shell, except that
3756 its commands are much more restrictive. If the command entered is just
3757 a device specification, i.e. a one- or two-letter string terminated by
3758 a colon, then the active device is changed. Otherwise, the command line
3759 tries to locate the command as file on disk, as a binary, and then runs
3760 it. It does NOT append a file extender, as for example “.COM”. The file
3761 name is loaded and executed as entered.
3762 The full command line including the command and its arguments is placed
3764 in a 128 byte buffer at 0x580 where the executed binary may find it,
3765 and may parse it itself if required. The command line does not provide
3766 functions to parse this buffer.
3767 NOTE This is not the way how Dos OS/A+ executes external commands.
3769 There was unfortunately not enough ROM space available to implement
3770 this interface.
3771 If the command starts with a double quote, or is not found on disk,
3773 then the command line processor tries to locate this as an internal
3774 command. The following internal commands are available: Optional argu‐
3775 ments are here denoted in square brackets, these are not part of the
3776 command syntax. filespec is a file specification, optionally contain‐
3777 ing wildcards, and optionally containing a device specification sepa‐
3778 rated from the file name by a colon. If no device name is given, the
3779 curently active device in front of the command is used.
3780 DIR [filespec]
3783 Lists the disk directory. If a filespec is given, only the files
3784 matching the filespec will be listed. DIR is not able to list
3785 the directory to some other device. For that, use the COPY com‐
3786 mand and a source filespec with the “/D” access modifier.
3787 DELETE filespec
3790 Deletes the file or files that match the filespec. Note that
3791 this command performs its work immediately and without asking
3792 further question.
3793 RENAME filespec,newname
3796 Renames a file or several files to a target filename on the same
3797 device. If more than one file matches the wildcard, all of them
3798 are renamed to the same target name. You can pick between vari‐
3799 ous identically named files by means of the /1 to /9 modifiers,
3800 allowing you to rename some of them back.
3801 LOCK filespec
3804 Marks the file or files as write-protected. Any kind of write
3805 operation, or deletion of the file is then prohibited.
3806 UNLOCK filespec
3809 Removes the write protection again, the opposite of the above.
3810 CAR Runs the cartridge should there be one inserted. If no cart is
3813 available, the command processor will be entered again.
3814 FORMAT [title]
3817 Formats the specified disk to enhanced density, erasing all its
3818 contents. An optional disk name can be specified here that will
3819 be printed in inverse video when listing the directory contents.
3820 CLEAR [title]
3823 Similar to the above, this command clears the entire disk con‐
3824 tents and installs an optional disk name. However, the CLEAR
3825 command only re-initializes an already formatted disk. By that,
3826 CLEAR is much faster than FORMAT and intended to be a quick-for‐
3827 mat.
3828 RUN [hexaddress]
3831 Runs a machine code program at the specified address. If no
3832 address has been given, the previously loaded command will be
3833 run again.
3834 SAVE filespec,from,to,[[,init],run]
3837 Saves a binary file to disk, starting at the given hex address,
3838 up to the given address. An optional init and run address can be
3839 given here as well. Note that you can always append to a file,
3840 and thus extend a binary load file, by using the “/A” access
3841 modifier behind the file name.
3842 LOAD filespec
3845 Loads a file from disk, but does not start it. You can run this
3846 file later by means of the RUN command without additional argu‐
3847 ments.
3848 COPY filespec,target
3851 Copies one or several files from one disk to the same or another
3852 disk. COPY will first read the file from the source, and will
3853 then wait for you to swap disks. If the source and the target
3854 disk are identically, just press RETURN, otherwise swap disks
3855 first. COPY will then write the target file, and might ask you
3856 again to insert the source disk if the file is too large to be
3857 read in one go, or if more than one file is to be copied.
3858 COPY will invalidate the user RAM contents; therefore, a BASIC
3860 program that has been loaded into RAM will be lost after a COPY
3861 command if BASIC is re-entered. Similar restrictions arise for
3862 other cartridges (e.g. Mac/65 will loose the current assembly
3863 source code). COPY does not try to notify you about this fact.
3864 Due to ROM size limitations, there is neither a MEM.SAV file to
3865 protect you against this memory loss.
3866 FMS HINTS AND TWEAKS
3869 Sometimes an external command has the same name as an internal one. In
3870 that case, the external command is prefered to the internal one and is
3871 loaded, bypassing the internal one. If this is undesired, place a dou‐
3872 ble quote in front of the command. This will avoid the external command
3873 lookup.
3874 You might have noted that the DIR command is not able to list the
3876 directory to anything but to the screen. However, the COPY command can
3877 perform a similar operation by using the /D access specifier:
3878 COPY -/D,P:
3880 will print out the contents of the directory by copying the contents of
3882 the directory to the printer device.
3883 The LOAD command can be emulated by using the no-run specifier when you
3885 just want to load, but not to run an external command. Thus, LOAD foo‐
3886 bar and foobar/N are equivalent.
3887 FMS BOOTSTRAP PROCESS
3890 If the FMS is initiated by the built-in Os, and a disk is found active
3891 and usable, the following additional bootstrap steps take place:
3892 FMS Configuration
3895 The FMS tries to load and execute the binary load file D:CON‐
3896 FIG.SYS. This file should modify the FMS settings by writing
3897 into its configuration area. The FMS will then re-allocate buf‐
3898 fers according to its new settings. Note that this is the only
3899 way how to modify the FMS parameters since it is ROM based.
3900 Handler bootstrap
3903 Next, the FMS tries to load and execute the binary file D:HAN‐
3904 DLERS.SYS. This file should contain the bootstrap code for any
3905 additional boot-time handlers that must be linked into the sys‐
3906 tem. For example, this file could load and run the 850 interface
3907 box firmware (easiest by simply calling the Os vector BOOT850,
3908 0xe48f).
3909 Command execution
3912 Last, the FMS runs the traditional D:AUTORUN.SYS file. This is a
3913 user defined binary load file that could contain about anything
3914 the user may consider.
3915 OS EQUATES
3918 In most cases, the built-in Os uses the same memory locations as the
3919 Atari 800XL ROM, though some extensions have been made. Note that mem‐
3920 ory cells reserved within the XL operating system for parallel port and
3921 tape usage are likely to be no longer in use. However, these should
3922 remain reserved for future versions of the Atari++ operating system.
3923 0x15 FMSTMP
3926 Used by the FMS for various issues.
3927 0x16 DIRENTRYOFFSET
3930 Used by the FMS to point into the directory buffer for the cur‐
3931 rently processed file.
3932 0x43 FMSPTR
3935 Temporary pointer variables for miscellaneous uses in the FMS.
3936 0x45 DISKBUFFER
3939 Points within the FMS to the VTOC buffer for the currently pro‐
3940 cessed disk drive.
3941 0x47 FILEBUFFER
3944 Points within the FMS to the file input/output buffer for the
3945 currently processed file.
3946 0x2b8 OVERRUNFLAG
3949 This flag is set by the E: handler in case the line is nearly
3950 full and the buzzer should be run.
3951 0x318 SCREENSTACK
3954 This byte is traditionally used by SIO, and so it is by the
3955 built-in Os. It is, however, also used by the S: and E: handler
3956 to keep the stack pointer to make error handling easier.
3957 0x3f5 FMSBOOTFLAG
3960 Specifies the FMS bootstrap modes and various other related
3961 issues as listed in the following table:
3962 Bit function
3964 ─────────────────────────────────────────────────
3965 Bit 0 If set, the next reset shall signal the
3966 cart a coldstart. This bit gets set by
3967 the command line processor in case the
3968 memory contents gets invalidated by the
3969 COPY command.
3970 Bit 6 Is set if the command processor shall
3972 be launched on the next warmstart.
3973 Bit 7 Is set if the FMS should be initialized
3975 on Reset. Note that the FMS no longer
3976 requires the DosInit vector.
3977 0x3f6,0x3f7 DUPVECTOR
3980 DupVector (hi) This address is jumped at instead of the cart run
3981 vector during a warmstart if bit 6 of the FmsBootFlag is set. A
3982 program that jumps thru DOSVECTOR (0x0a,0x0b) will set bit 6 of
3983 the FMSBOOTFLAG, then cause a reset which in turn will run the
3984 command processor thru this vector.
3985 The next addresses are only used if the FMS is initialized. They can be
3987 modified from the CONFIG.SYS file to change the FMS parameters when
3988 booting.
3989 0x70a FMSDRIVEMASK
3992 Contains a bitmask that defines which drives should be address‐
3993 able. A one-bit enables the corresponding disk unit, a zero dis‐
3994 ables it. Bit #0 enables/disables drive 1, bit #1 controls drive
3995 2 and so on. The default value is 3, meaning a two-disk system
3996 is supported. Each supported drive requires 128 bytes additional
3997 storage.
3998 0x709 FMSBUFFERS
4001 Number of file buffers the FMS shall allocate. This controls
4002 how many files can be opened at once. The default value is five,
4003 allowing to open at most five files at once. Each file buffer
4004 requires 128 bytes of storage.
4005 0x779 WRITECMD
4008 The SIO command the FMS shall use for writing sectors. This can
4009 be either P for writing without or W for writing with verify. It
4010 is however suggested to use the file name extenders /V and /O to
4011 switch verify on and off instead.
4012 Fms state flags
4015 Addresses $700-$7ff except the above contain FMS state variables
4016 that remain undocumented.
4017 Fms buffers
4020 FMS buffers for drives and file buffers are allocated from $800
4021 up. In the default configuration, they extend up to $a7f, leav‐
4022 ing RAM from $a80 and up to the user. Thus, the memory footprint
4023 of the built-in FMS is much better than for DOS 2.0S.
4024
4027 Atari++ comes with a build-in mini-monitor that can be helpful for
4028 debugging programs, or for finding bugs in the emulator. The following
4029 section describes briefly the front-end and the commands of this moni‐
4030 tor, assuming that the emulator has been compiled with curses support.
4031 Otherwise, the front-end is less user-friendly (or even more user un-
4032 friendly than it used to be before, but that's another topic).
4033 ENTERING THE MONITOR
4035 The monitor is entered either by pressing F12 while the emulation is
4036 active, by pressing ^C in the shell that launched Atari++, or if the
4037 CPU core emulator crashes. The crash could be either due to an instruc‐
4038 tion that is not implemented, an instruction that would otherwise stop
4039 the CPU completely or an unstable instruction whose function depends on
4040 some floating bus signals that are hard or not at all emulatable. Other
4041 than that, Atari++ emulates all known stable “extra opcodesrq some
4042 lesser quality programs tend to use.
4043 Another way of entering the monitor is due to hitting a break point, or
4045 by finishing a single-stepped instruction.
4046 MONITOR COMMANDS
4049 The monitor is entirely command line driven. Commands are four charac‐
4050 ters long, non-case sensitive, with a possible abbreviation of one
4051 character. Commands furthermore have an optional extension given by a
4052 dot (.) and a single additional character. This extender typically
4053 modifies the command somewhat, or sets some parameter for the command,
4054 as for example the output format. The extender for each command is
4055 remembered by the command itself up to the next time the very same com‐
4056 mand is used. Hence, you won't need to type the same extender every
4057 time. Using the question mark “?” as extender lists the available
4058 extenders for the command.
4059 Most commands also remember the last address they operated on. If typed
4061 without arguments, they silently re-use the last address used. This is
4062 handy for disassembling long routines since you just have to re-type
4063 the disassembly command to continue the listing.
4064 ALGEBRAIC EXPRESSIONS
4067 The monitor is capable of evaluating simple algebraic expressions in C
4068 syntax containing the basic operators +,-,*,/, the binary operators
4069 &,|,^,~ the logical operators ||,&&,! , the comparisons <,<=,>=,==,!=
4070 and the shifts <<,>>. The precedence of the operators follows mainly
4071 the C syntax except that priority of the shifts has been “fixed” to
4072 follow more closely the (or at least my) intuition, brackets are sup‐
4073 ported with their obvious meaning. Furthermore, the contents of the
4074 registers are available as the algebraic expressions A,X,Y,P,S,PC. Oth‐
4075 erwise, numerical constants are understood in hex (sedecimal) notation.
4076 A nice gymmick are the indirection operators [],[].b,[].w with the
4078 first two being equivalent. They evaluate their contents as an address,
4079 and then return the contents of this (emulator) address as their value.
4080 The first two are byte versions reading a single byte, the latter is a
4081 word version that reads two bytes in little-endian notation to form a
4082 sixteen bit integer.
4083 COMMAND DESCRIPTION
4085 The following commands are available in the monitor:
4086 HELP=? This command prints a command summary.
4088 DUMP=D [expr]; extenders: A,S,V
4090 Dumps the memory contents at the address given by the argument
4091 or continuing the last dump. The A extender switches to mixed
4092 hex-ATASCII output, emulating inverse video as much as possible
4093 thru curses, the S extender uses hex-ANTIC screen code dumps.
4094 The V extender doesn't dump anything at all but rather sets the
4095 number of lines to dump in one go.
4096 EDIT=E [expr]; extenders: X,D,A,S,I
4098 Edit memory starting at the given address either in hex, deci‐
4099 mal, ATASCII or Antic Screen codes, respectively. For hex and
4100 decimal input, memory contents are lines separated by blanks,
4101 and the input is aborted by an empty line, i.e. by just pressing
4102 RETURN. For ATASCII and screen code editing, the text given as
4103 input is placed directly in the memory of the Atari, possibly
4104 first converting to the target format. The I extender doesn't
4105 edit any memory but toggles the seventh bit of the ATASCII resp.
4106 screen code entries on or off.
4107 FILL=L addr size; extenders: X,D,A,S,I
4109 Fill the given memory range, given by base address and size with
4110 a byte pattern. You will be prompted for the fill pattern sepa‐
4111 rately in a second stange: With the X extender, the byte pattern
4112 is given as a space-separated list of hexadecimal (sedecimal)
4113 byte values, with the D extender, this pattern is given in deci‐
4114 mal notation instead. Using the A extender allows to enter the
4115 bytes as ATASCII codes, and the S extender, last but not least,
4116 encodes the pattern in the ANTIC screen codes.
4117 The I extender toggles the seventh bit of the entered ATASCII or
4119 screen code pattern on or off. Its setting is ignored for hex or
4120 decimal input.
4121 MOVE=M from to size; extenders: S,C,A
4123 Move a memory block of the given size from the start location to
4124 the target location. Source and target may overlap, the move
4125 command will be smart enough to copy memory blocks correctly in
4126 all circumstances. The S extender will perform a simple memory
4127 copy operation within the current address space, no matter which
4128 one has been selected by the ENVI command (see below). The C
4129 extender, however, will move bytes from the selected address
4130 space into the address space as seen from the 6502. This allows
4131 you to copy data from the ANTIC space to the CPU space. The A
4132 extender works in the reverse direction by always writing into
4133 the ANTIC space.
4134 FIND=F [expr]; extenders: X,D,A,S,I,V
4136 Scans the memory starting at the given location for a byte pat‐
4137 tern, possibly filtering the pattern thru a mask. You are first
4138 prompted to enter the byte string to look for, and then for a
4139 possible mask, that must be either left blank or as long as the
4140 pattern entered first. If left blank, the byte string in memory
4141 must match the entered string precisely for a match. Otherwise,
4142 only the one-bits in the mask are significant and all zero bits
4143 in the mask are not compared against the search pattern. This
4144 allows, for example, scanning for a text in non-case-sensitive
4145 mode: Just set all pattern bytes to “5F” for ignoring case and
4146 inverse video bits.
4147 The extenders work similar to the extenders of the EDIT or FILL
4149 commands: X expects hexadecimal input, D requests decimal input,
4150 A allows ATASCII and S screen code patterns. The pattern mask,
4151 however, is always given in hexadecimal notation. As always, the
4152 I extender toggles the seventh bit on or off for the A and S
4153 extenders. Last but not least, the V extender defines the maxi‐
4154 mal number of matches that will be printed before the search is
4155 aborted.
4156 EVAL== expr; takes no extenders
4158 Evaluates its argument and prints the result on the screen.
4159 SKTB=K [expr];
4161 Prints a stack traceback, optionally starting at the given stack
4162 address. For this option, the monitor will find the locations
4163 from which the current routine has been called. The locations of
4164 the JSR instructions are printed on the screen.
4165 BRKP=B [expr]; extenders: S,C,D,E,A,L
4167 Controls breakpoints. Once a breakpoint is hit, and the break‐
4168 point is enabled, the monitor is re-entered. Breakpoints can be
4169 set in either RAM or ROM. They do not alter the memory at all
4170 but are rather emulated directly in the CPU core. Hence, they
4171 cannot interact with software reading or interpreting the code.
4172 BRKP.S installs and activates a breakpoint at the address given
4174 by its argument. BRKP.C removes it again. The D and E extenders
4175 disable, resp. enable breakpoints that have been set before. A
4176 disabled breakpoint is temporarely turned off, but remembered,
4177 and can be turned on later on.
4178 The A extender removes all breakpoints at once and the L exten‐
4180 der lists all breakpoints and their status, i.e. wether they are
4181 disabled or enabled.
4182 DLST=A [expr]; extenders: L,S,V
4184 displays the antic Display List and the ANTIC status. The L
4185 extender prints a disassembly of the ANTIC program, or short the
4186 Display List. This is useful for getting an idea how the screen
4187 is generated. The S extender prints the contents of the ANTIC
4188 register set, for example to find the start address of the dis‐
4189 play list. Finally, the V extender sets the number of lines the
4190 ANTIC disassembler prints in one go.
4191 UNAS=U [expr]; extenders: L,V
4193 This is the 6502 disassembler. The L extender does exactly this;
4194 it disassembles at the address given by its argument. The disas‐
4195 sembler knows all “extra instructions” of the 6502 and prints
4196 them as four character rather than three character opcodes.
4197 The V extender sets the number of lines the disassembler prints
4199 at a time.
4200 RSET=P; extenders: W,C,I
4202 Various reset commands. The W extender warm-starts the emulator,
4203 the C extender runs into a coldstart. Both instructions also
4204 leave the monitor as its full working environment is reset as
4205 well. If you need to debug instructions directly following the
4206 cold-start sequence, consider using the -traceonreset on command
4207 line switch.
4208 Note that the warm-reset really holds the reset signal of the
4210 CPU. This is unlike the Reset Console Key on the Atari 800 and
4211 400 models work; they just raise a special Antic NMI signal and
4212 leave it to the Os to detect this signal and jump to the reset
4213 vector. This kind of reset is reached with the I extender,
4214 though note that the detection of this NMI interrupt has been
4215 removed in Os ROM of the XL and XE models.
4216 EXIT=X; no extenders
4218 Takes no arguments and no extenders and leaves the emulator
4219 immediately.
4220 GOPG=G; extenders: P,U,M
4222 Takes no arguments and re-starts the emulation at the current
4223 program counter value for the P extender. Hence, this leaves the
4224 monitor and continues emulation. For the M extender, the emula‐
4225 tion also continues, but the configuration menu is entered as
4226 soon as possible after leaving the monitor, as if F1 has been
4227 pressed. This may take as long as a vertical retrace of the emu‐
4228 lated screen, and some code might have been run when the menu is
4229 entered. The U extender, finally, runs the program until the
4230 stack pointer gets larger than its current value. This is useful
4231 to terminate a current subroutine call and to return to the
4232 calling function immediately.
4233 STEP=Z; extenders: S,I
4235 Single step thru a program. If used with the S extender, the
4236 simple interface is used and similar to the GOPG command, the
4237 program is run, but the monitor is re-entered immediately after
4238 execution of the command under the PC, printing the command that
4239 was executed last. This is most useful for debugging purposes
4240 and single-stepping thru critical sections of a program.
4241 If the I extender is selected, a full-screen graphical debugger
4243 is entered provided the curses library was available at compile
4244 time. If so, a full screen of disassembled code is printed and
4245 the monitor waits for further commands. The Z key single steps
4246 then, the N key works similar to the NEXT command (see below)
4247 and steps over subroutines and loops, the G key re-starts the
4248 program and leaves the monitor, the B key sets a break point at
4249 the current program location and, finally, the U command runs
4250 the emulated CPU until the stack pointer is increased, thus usu‐
4251 ally up to the end of the current sub-program.
4252 NEXT=N; no extenders
4255 Similar to STEP though this command does not step into subrou‐
4256 tines. For any operation that places data onto the hardware
4257 stack, this command will run the program up to the location
4258 where the data is again popped from the stack; if the current
4259 instruction is not a JSR instruction, then the emulator is run
4260 until the program counter of the emulated CPU gets larger than
4261 its current value. This is for example useful to complete a
4262 larger loop with a backwards branch at its end by just one moni‐
4263 tor command.
4264 STAT=T [comp]; extenders: L,S
4266 Prints status information about various system components,
4267 including internal hardware register sets, port settings and
4268 configuration. The L extender lists all system components for
4269 which a status information is available, and STAT.S followed by
4270 the name of this component prints the status of the mentioned
4271 component.
4272 SETR=S register=expr; no extenders
4274 Sets a CPU register to a specified value given by an expression.
4275 The syntax of this command is non-standard for convenience rea‐
4276 sons. Register and desired register contents are separated by an
4277 equals sign, and not by a blank. For example, SETR A=ff would
4278 set the contents of the accumulator to 255=0xff.
4279 REGS=R; no extenders
4281 displays the contents of the CPU in a brief listing. This com‐
4282 mand is ideal for the SPLT command explained next.
4283 SPLT=/ [cmds]; extenders: C,S
4285 This command is special as it modifies the behaviour of the mon‐
4286 itor and does not perform a direct action on the emulation com‐
4287 ponents. The S extender splits off the top part of the monitor
4288 output window and prints there the contents of the commands fol‐
4289 lowing the SPLT command. For example, SPLT.S R would continously
4290 display the register dump of the 6502 CPU on top of the screen.
4291 Several commands can be run at once by separating them with a
4293 colon. The split-off output is updated on each command, making
4294 the screen splitting an ideal feature for the single stepping
4295 and debugging. The C extender cleans and removes this split-off
4296 part of the screen again.
4297 ENVI=V [value]; extenders: A,L
4299 Controls various (currently one) monitor environment settings.
4300 The A extender controls the view on the memory. As the 130XE
4301 offers 128K of memory that can be selectively banked for the CPU
4302 and for ANTIC, it matters whether the memory is seen by the CPU
4303 or by ANTIC as both may have selected different banks for it.
4304 This environment switch toggles the view of the monitor onto the
4305 memory as either comming from ANTIC or from the CPU. L This
4306 extender expects a file name as argument. The status of the emu‐
4307 lated CPU is then logged into the file, including the register
4308 set and the timing information, i.e. horizontal and vertical
4309 beam position. Note that this file may grow very fast and
4310 becomes huge shortly. To disable logging, supply an empty file
4311 name.
4312
4314 /etc/atari++/atari++.conf
4315 The system global configuration files
4316 ~/.atari++.conf
4318 The user specific configuration file
4319 ./.atari++.conf
4321 The directory specific configuration file.
4322
4324 No emulator specific variables. Atari++ is controlled completely by its
4325 configuration files and command line arguments.
4326
4328 David Firth for his Atari800 emulator. Atari++ is not based on this
4329 earlier work, though influenced. Atari++ was entirely and completely
4330 rewritten from scratch, in C++, avoiding some of the constructional
4331 difficulties of David's work. Especially, the way how graphics output
4332 is constructed and how player/missile graphic priorities are generated
4333 is quite different from his implementation.
4334 Ron Fries for the Pokey emulation routine that got used in early
4336 releases of the Atari800 emulator. The strategy that has been utilized
4337 for sound build-up has been used in the pokey emulation of this emula‐
4338 tor as well, though the implementation details are a bit different and
4339 the overall quality of the sound emulation has been improved heavily.
4340 Specifically, high-pass filters, sound muting and anti-aliasing are new
4341 to the emulation model.
4342 Jean-loup Gailly and Mark Adler for the Z compression library that gets
4344 used if available for .gz compressed disk images.
4345 Sam Lantinga and the SDL group for the Simple DirectMedia Layer
4347 library, or short, SDL, that offers one of the possible front-ends of
4348 the Atari++ emulator if it is available.
4349 Jindroush and the Atari Cartridge Dumping project for providing insight
4351 into the details of the cart emulation. Specifically, SDX and XEGS cart
4352 emulation would have been impossible without him.
4353 Petr Stehlik and the remaining atari800 team for cooperation and for
4355 working out the licencing conditions of this emulator. Specifically, I
4356 thank Petr for keeping cool in the hot days of working out all the
4357 details of making this project available.
4358 Andreas Magenheimer and the ABBUC team for providing some hardware
4360 insight that was otherwise not available. Specifically, emulation of
4361 various bank switching logics is due to ABBUC.
4362 Jason Duerstock's for its analyzation of the RT8 cartridge. Unfortu‐
4364 nately, something seems to be still not quite right with it. The cur‐
4365 rent implementation in Atari++ uses a somewhat different route how the
4366 register assignment might work. This is all an educated guess, though.
4367 B. Watson for keeping pushing me to re-implement the math-pack; it's
4369 been done, now, providing a full free implementation of the Atari oper‐
4370 ating system.
4371 Konrad Kokoszkiewicz for finding and fixing many bugs in the emulation
4373 of floppy disks. Part of the "speedy" comments were broken or poten‐
4374 tially mis-interpreted, and floppy sizes weren't detected and supported
4375 correctly under all circumstances. Thanks, folks!
4376
4379 DE RE ATARI
4380 by John Eckstrom, Michael A. Eckberg, Gus Makreas, Lane Winner
4381 and Elizabeth Hernaton.
4382 Das Atari Profibuch
4384 by Julian Reschke and Andreas Wiethoff, Sybex, 1985.
4385 6502 Assembly Language Programming
4387 by Lance A. Leventhal, McGraw-Hill, 1979.
4388 Atari Technical Documentation
4390 from The Atari Historical Society at www.atari-history.com
4391 Your Atari Computer
4393 by Lon Pool, Martin McNiff & Steven Cook, McGraw-Hill, 1982.
4394 German translation “Mein Atari Computer” by te-wi, 1983.
4395
4397 Thomas Richter (thor@math.tu-berlin.de)
4398
4400 An Atari800.
4401 atari++ Emulator atari++(6)