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 various disk drive models, 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 800XL/130XE
31 ROM image compatible to the Atari ROM that is sufficient to run almost
32 all programs. Basic programs are supported by the built-in Basic emula‐
33 tion that is also compatible to the native Basic ROM.
34 Emulation of printers is included as well. Print-out text is forwarded
36 to the standard printer tool, which defaults to the lpr printer front-
37 end. The print-out command can be adjusted by means of the command line
38 options and the configuration files (see below).
39 Additional features include emulation of the 850 serial/parallel inter‐
41 face box, emulation of the tape drive, a screen-snapshot, a complete
42 machine state save and load feature that allows you to stop and replay
43 a game in a later session and sound support by the Open Sound System
44 (Oss) or Alsa sound drivers.
45 Furthermore, to aid the developer, a simple system monitor using a
47 curses terminal front-end has been integrated into the emulator. It
48 offers several features not available on the real hardware, as single
49 stepping thru programs and setting breakpoints, even in ROM code.
50 Graphics output is either emulated within an X11 window, or - if avail‐
52 able - with the SDL library. As last resort, and for special applica‐
53 tions, some ports provide a curses front-end that renders its output in
54 textual form on a console. Alternatively, the emulator can also be
55 instructed to read and write input to the operating system editor
56 device directly to and from the console, i.e. the standard input and
57 output streams of the program. This is not implemented as a new type of
58 front-end, but rather as an operating system patch.
59
62 Quite untypical for unixoid systems, the atari++ options are not case
63 sensitive, upper and lower case won't matter. Furthermore, the order of
64 the command line arguments doesn't matter as well. The following
65 options are supported:
66 --help prints all available options to the console. NOTE: Due to the
68 dynamic build-up of the atari++ components, the options these
69 components become only available if the corresponding component
70 is activated as well. E.g, you won't see the X11 options with
71 the SDL front-end activated.
72 -h similar to the above.
74 All following options are of four kinds: Numerical options taking
76 exactly one number as argument. They typically accept only numbers
77 within a limited range. Boolean options, taking the strings on yes or
78 true as positive and off , no or false as negative choices and string
79 options that take either a file or a string as value. Last but not
80 least, selective options that pick one out of several possible, mutu‐
81 ally exclusive choices.
82 On the Fly Configuration
85 Atari++ provides a quick and a complete menu to setup or modify its
86 configuration on the fly. For the quick menu, press and hold the left
87 mouse button within the emulator window, and pick an apropriate option
88 from the menu on the screen. This menu provides the most-used options,
89 namely to load and boot a disk, to pick a cartridge or to reset the
90 emulated Atari.
91 The full menu is either available as an option within the quick menu,
93 or by pressing the F1 key on the keyboard. The options presented there
94 are identical to the options listed below.
95 NOTE: The quick menu is not available in case the mouse has been arbi‐
97 trated to emulate a joystick or any other kind of input device. You'd
98 need to enter the full menu by the F1 key to adjust the configuration
99 in this case.
100 Global Options
103 This set of options does not belong to a specific part of the emulation
104 core, but rather influence the emulator as a whole.
105 -h or --help
107 prints out the list of currently available options. This list
108 does, however, depend on the current configuration of the file
109 as options for modules that are currently not in use will not be
110 shown on this list. For example, if your .atari++.conf file
111 selects the X11 frontend for graphics output, the options for
112 the SDL graphics support will not be shown. Unlike all other
113 options, this option does not take an argument.
114 -config filename
116 Load an alternative configuration file into the emulator. This
117 will override the options from all other configuration files,
118 but will be overridden by the command line arguments itself.
119 -state filename
121 Load a machine state snapshot file. This restores the machine
122 state of a previous atari++ session by re-installing the memory
123 conents and all hardware register settings of the previous ses‐
124 sion. For more details about the snapshot feature, see the SNAP‐
125 SHOT FILES section below.
126 Machine Type Options
128 The following options modify the overall emulation process, picks the
129 hardware to be emulated and the frontend how to perform graphics and
130 sound output.
131 -machine 800|1200|XL|XE|5200
133 Sets the type of machine to emulate. This is a meta-option that
134 sets suitable defaults for several other options, still allowing
135 to override these defaults with further commands. Hence, you'd
136 be still able to run an Atari XL machine with the Os of the
137 Atari 800. The following models are available: 800 emulates the
138 Atari 800 and its derivative, the Atari 400. 1200 emulates the
139 Atari 1200XL. This is almost identical to the 800XL, except that
140 the default ROM image is different. XL emulates the Atari
141 800XL, the 600XL and the 65XE. XE emulates the Atari 130XE with
142 a total of 128KByte memory. Last but not least, the 5200 argu‐
143 ment selects the emulation of the 5200 game console.
144 -frontend X11|SDL|CURSES|NONE
146 Defines which graphical front-end should be used. Currently, the
147 X11 the CURSES and the SDL front-ends are supported. NONE is a
148 dummy front-end without any graphical or textual output that can
149 be used for playing music or related tasks. The installedevice
150 option is suggested to get minimal support from the console
151 using only stream-I/O. Note this type of redirection is not a
152 front-end option, but rather an optional operating system patch,
153 see OS Options below.
154 The X11 interface is only available for Unix based operating
156 systems, most notably Linux, while the SDL interface is cur‐
157 rently available on most ports. The latter is also able to run
158 in a full-screen mode that is more suitable for gameplay. Typi‐
159 cally, the SDL front-end provides better performance unless you
160 need to scale up the output with the -pixelwidth or -pixelheight
161 options. Then, X11 performs noticeably better. The CURSES front-
162 end requires only a terminal for rendering, but its graphics
163 capabilities are rather limited. Specifically, it is only able
164 to emulate text-based graphics modes and expects the built-in
165 font to render the output. The keyboard mapping for the CURSES
166 output is also slightly different, see the CURSES section for
167 details.
168 -sound HQOSS|OSS|WAV|SDL|ALSA|DIRECTX
171 Sets the audio front-end used to generate audio output. For the
172 OSS and HQOSS front-ends, an Open Sound System compatible driver
173 is required, or no sound whatsoever will be available. Sound
174 synthesis will be very close to the real sound output and will
175 be at good quality, though some CPU power is required to guaran‐
176 tee continuous output without dropouts. In general, the HQOSS
177 driver is preferably since it requires less precise implementa‐
178 tions of the Oss standard and provides excellent quality for
179 synthesized speech.
180 The main intention of the WAV front-end is to record the sound
182 output as sampled sound in a .wav encoded file in optimum qual‐
183 ity. To allow you to listen to in-game sounds, this front-end
184 also offers a “play-back” option that also generates sound out‐
185 put thru an OSS compatible sound output, though this output is
186 of less quality than that of the dedicated HQOSS module. Even
187 though the play-back sound may contain some “blips” or drop-
188 outs, the quality of the recorded audio within the .wav file
189 will be perfect and very close to the original.
190 The SDL audio generation comes close in quality to that of the
192 HQOSS driver, though it is more likely to generate drop-outs for
193 highly loaded systems. SDL is the best in portability as SDL
194 exists on a variety of systems. The SDL driver also emulates
195 software speech correctly.
196 The DIRECTX driver is obviously available only for win32 compi‐
198 lations and uses the DirectSound interface of the DirectX sys‐
199 tem. This is the prefered sound system under Windows as it
200 offers lowest latency at best quality.
201 Finally, the ALSA front-end uses the state of the art ALSA sound
203 drivers for linux and provides optimal sound quality at minimal
204 CPU load. It provides similar or better quality than the HQOSS
205 front-end at less complexity, but it requires ALSA support,
206 nowadays almost universally available.
207 -monitoroncrash bool
210 If this boolean option is enabled, then the emulator enters
211 automatically the built-in monitor in case the 6502 CPU crashes
212 due to a corrupt program. Note that these crashes are not due to
213 bugs in the emulator, but rather due to flaws in the emulated
214 program, i.e. a “real” Atari would have crashed in the same sit‐
215 uation. If this option is disabled, then a warning gets printed
216 and the user menu is entered. It is then up to you to either
217 reset the emulation or to launch the monitor manually. This
218 option defaults to false ,i.e. the monitor is not entered by
219 itself.
220 For details about the system monitor, see the MONITOR section
222 below.
223 -acceptlicence bool
226 If enabled, then it is understood that you read and agreed to
227 the licence conditions under which Atari++ is delivered, and the
228 licence conditions are no longer presented on startup.
229 -stereopokey bool
232 Toggles the “dual Pokey” hardware hack emulation. This hardware
233 hack installs a second Pokey at base address $d210 into the sys‐
234 tem, allowing stereo sound emulation. Atari++ provides then a
235 second Pokey chip named “ExtraPokey” that otherwise takes the
236 same configuration arguments than the first Pokey does, though
237 this second chip is not connected to the serial output and the
238 keyboard.
239 NOTE: The second Pokey chip is fully functional and also pro‐
241 vides interrupts. Since the Atari Os is not aware of this chip,
242 it cannot handle these interrupts. Thus, programs might crash if
243 interrupts of this extra chip are erraneously enabled. This is
244 not the fault of the emulator, a real system would crash under
245 the same circumstances.
246 -ignoreerrors bool
249 instructs the emulator to ignore all error messages and to con‐
250 tinue operations as if the error requester has been closed by
251 pressing “Cancel”.
252 -ignorewarnings bool
255 similar to the above option, will suppress all warning
256 requesters as if the user accepted the warning.
257 CPU Options
260 The following options control the emulation of the 6502 CPU:
261 -traceonreset bool
263 This boolean option is useful for debugging. If enabled with the
264 on argument, the CPU enters trace mode on a reset, entering the
265 build-in monitor immediately.
266 -traceinterrupts bool
268 Another debugging related option. If this is enabled, instruc‐
269 tion stepping will also step into interrupt routines as soon as
270 an interrupt gets detected. This might cause some confusion
271 because surprisingly the 6502 CPU will continue execution from a
272 completely different place, though it is helpful to find bugs in
273 display list interrupts.
274 -cputype 6502|WD65C02
276 Selects the CPU type that is emulated. The WD65C02 offers a cou‐
277 ple of addtional addressing modes and instructions that are sup‐
278 ported by a couple of products, e.g. the Mac/65 assembler car‐
279 tridge.
280 GTIA Options
283 The following options modify the emulation process of the video signal
284 generator, the Graphics Television Interface Adaptor chip:
285 -videomode PAL|NTSC
287 Defines whether the emulated GTIA should either identify itself
288 as PAL or as NTSC chip. Some games read this value and modify
289 their timing accordingly. This option also changes the color map
290 GTIA sends to the front-end as colors differ slightly between
291 the PAL and the NTSC version of GTIA.
292 -ChipGeneration CTIA|GTIA|XLGTIA
294 Selects the chip generation to emulate. CTIA selects the old
295 first generation used in some very early 800 and 400 models.
296 This chip did not provide the special 16 hue/16 luminance and 8
297 color modes, BASIC modes 9 to 11. GTIA selects the second gen‐
298 eration, used in most 800 and 400 models, and XLGTIA the third
299 generation in the XL series. The last two chips do actually not
300 differ, only the surrounding analog circuits change the color
301 artifacts slightly, which is the only noticable difference
302 between them.
303 -artifacts bool
305 This boolean option controls whether GTIA should emulate color
306 artifacts that are caused by video system. If set to on , the
307 video rendering will detect hi-lo and lo-hi transitions for
308 high-resolution graphics and text mode and will generate pseudo-
309 colors similar to a real TV. These artifacts are limited to NTSC
310 systems for the real hardware and are not as effective nor very
311 visible for the PAL hardware; the emulator, however, displays
312 them regardless of the emulated video mode. Some games require
313 this setting to look properly. If set to off , artifact genera‐
314 tion is disabled as for a higher quality monitor or for the PAL
315 video system. This also makes text more readable and less
316 blurry, it also speeds up the emulation process somewhat and is
317 better suited for text-oriented software.
318 -palcolorblur bool
320 enables emulation of a feature of the PAL video system standard
321 that can be used to create additional colors by mixing. If two
322 adjacent horizontal lines on top of each other share the same
323 intensity but have a different hue, then the mixture of the col‐
324 ors appears instead of two separate colors. This option is com‐
325 putationally a bit complex and requires a true color display,
326 i.e. a color depth of 24 bit to be effective.
327 -antiflicker bool
329 enables the Atari++ flicker fixer. Some programs create addi‐
330 tional colors by quickly altering the colors forth and back,
331 causing the mixture of the colors due to the slowness of the TV
332 screen. PC monitors are typically much faster, causing an anoy‐
333 ing flicker for these programs. This switch enables a flicker-
334 fixer that mixes the colors already in the GTIA display genera‐
335 tion at the price of a higher complexity. This option also
336 requires a true-color display, i.e. a bit depth of 24 bit.
337 -playerpositiondelay 0..32
339 this setting controls the number of half color-clocks required
340 by GTIA to detect any change of the player/missile horizontal
341 position register. It is the minimal screen distance in half
342 color-clocks after writing to the horizontal position register
343 until the change becomes effective. The default for this value
344 is 12, i.e. it takes 12/4 = 3 CPU clocks before a horizontal
345 adjustment is recognized.
346 -playerresizedelay 0..32
348 this controls, similar to the above, the internal GTIA propaga‐
349 tion delay until a change of a player/missile size register
350 becomes effective, and thus the distance in screen hires pixels
351 from the modification to the position where the change becomes
352 visible. The default is six half color-clocks.
353 -playerreshapedelay 0..32
355 quite similar again, this setting controls the propagation delay
356 for player shape changes, i.e. how long it takes for a write to
357 the P/M graphics register to propagate to the output logic of
358 GTIA. If the write comes too late, the shape change will become
359 visible only on the next scanline - unless GTIA fetches the data
360 through the ANTIC DMA, of course.
361 -colormapname filename
363 requires a filename to a color map to be used instead of the
364 default PAL or NTSC color map. The color map file must be
365 exactly 768 bytes long and contains for each Atari color a red,
366 green and blue color triple, eight bits per channel.
367 -playertrigger.0 all|players|missiles|none
369 The first out of four otherwise identical options sets the abil‐
370 ity of player zero to generate collisions with other objects on
371 the screen. Note that this does not change the ability of player
372 zero to detect collisions itself, though. It just removes the
373 ability of other players or missiles to collide with it.
374 If this option is set to all, then player zero can create colli‐
376 sions with all other objects, for the players setting, only col‐
377 lisions with other players are generated and missiles never see
378 any collisions with player zero. For the missiles setting, the
379 situation is reversed and only missiles can detect collisions to
380 player zero. Finally, for the none argument, player zero gener‐
381 ates no collisions at all.
382 -playertrigger.1 all|players|missiles|none
384 works similar to the above except that it changes the ability of
385 player one to generate collisions.
386 -playertrigger.2 all|players|missiles|none
388 changes the abilities of player two and, finally,
389 -playertrigger.3 all|players|missiles|none
391 modifies the collision abilities of player three.
392 Note that there are no options to modify the collision abilities
394 of a missile since it has none in the real hardware. A missile
395 can never create a collision with a player itself, or any other
396 object. Rather, the situation is somewhat reversed from the
397 expected logic: A player creates a collision to a missile, and
398 hence, its ability to collide with missiles must be turned off
399 to avoid detection of player-missile collisions.
400 -playfieldtrigger.0 all|players|missiles|none
402 Modifies the abilities of playfield zero, i.e. the first fore‐
403 ground color, to generate collisions to other objects. Similar
404 to the above set of four options, playfields can be allowed to
405 generate collisions to all objects, players only, missiles only
406 or no objects at all.
407 -playfieldtrigger.1
409 Triggers the ability of playfield one to generate collisions;
410 otherwise, similar to the above.
411 -playfieldtrigger.2
413 The same again for playfield two.
414 -playfieldtrigger.3
416 the same once again for playfield three.
417 ANTIC Options
420 The following options control the DMA controller and the playfield
421 graphics generator chip:
422 -videomode PAL|NTSC
424 This option is intentionally identical to the GTIA option of the
425 same name and controls the video system ANTIC should emulate. As
426 for ANTIC, this switch controls the height of the video output.
427 For PAL , a total of 312 lines is generated, and for NTSC , only
428 262 lines of output are displayed. Note that not all lines are
429 available for graphics as the vertical retrace takes up some of
430 them.
431 POKEY Options
434 The next set of options influences the sound generation. For sound out‐
435 put, the Open Sound System driver for your sound card, more specifi‐
436 cally, /dev/dsp must be available. Alternatively, sound output can be
437 written into a .wav file and replayed later by a suitable tool, e.g.
438 XMMS. Alternative sound outputs are SDL or Alsa , depending on their
439 availibility. See the Machine Settings section for more details.
440 The following set of switches will not change the output of the sound,
442 but rather the emulation of the POKEY chip generating the audio signal
443 that is further processed by the OSS module described below.
444 NOTE: If the “stereopokey” emulation is enabled, a second set of Pokey
446 control options appears under the topic “extrapokey”. This set is iden‐
447 tical to the set described here.
448 -volume 0..300
451 Controls the overall volume of the POKEY output in percent com‐
452 pared to normal output. 300% is loudest and 0 disables the out‐
453 put. The default is 100%.
454 -gamma 50..150
456 Controls the output linearity of the POKEY D/A converter in per‐
457 cent. 100% is a perfectly linear output (provided the sound card
458 output is linear). Values smaller than 100% cause sublinear
459 behaivour (high amplitudes appear smaller than they should),
460 values higher than 100% cause superlinear characteristics (high
461 amplitudes are louder than they should). Real pokey chips typi‐
462 cally show sublinear characteristics with a gamma value around
463 70% to 80%.
464 -videomode PAL|NTSC
466 Even though Pokey is not a video interface circuit, its timing
467 is controlled by the system base frequency which is related to
468 the video mode. This option controls whether Pokey should find
469 itself in a PAL or NTSC system; it changes the audio base fre‐
470 quencies slightly.
471 -siosound bool
473 Enables or disables the serial transfer sound, provided the
474 siopatch is not enabled and bypasses hardware driven serial i/o.
475 This option enables a more complete Pokey emulation by also tak‐
476 ing care of the serial transfer modes for generating sound.
477 Thus, you get the very unique “Atari sound effects” for all
478 kinds of disk or tape access.
479 -cycleprecise bool
481 Controls wether the Pokey emulation works cycle-precise, that
482 is, whether pokey interrupts and potentiometer registers are are
483 updated and queried on a cycle by cycle basis. This allows a
484 more precise emulation, though it also requires more computing
485 power.
486 -filterconstant 0..1024
488 controls the time constant for an optional high-pass filter that
489 is applied to the audio output signal generated by the Pokey
490 emulation. This high-pass filter cancels any DC offset in the
491 sound generation that might cause trouble for audio cards or
492 amplifiers, especially when the audio output level is close to
493 the maximum. The lower the filter constant, the more frequencies
494 are cut-off by the filter. Setting the filter constant to zero
495 disables the filter. The default setting is 512.
496 -recordasSAP bool
498 If this option is enabled, the Pokey output is recorded on every
499 vertical blank in a SAP type R file. In principle, such files
500 could be played back as music files by third party software.
501 Unfortunately, type R does not seem to be well supported at this
502 time.
503 -sapname name
505 This option defines the name of the song that is currently
506 recorded, and also the file name the song will be saved under.
507 The file will be created in the directory the emulator was
508 started in, and the file name will be generated by appending
509 “.sap” to the song name.
510 -sapauthor name
512 Defines the name of the author to be recorded in the SAP output
513 file. This option may remain unset in which case an unknown
514 author will be indicated.
515 PIA Options
518 The following set of options modify the emulation of the Peripheral
519 Interface Adapter chip.
520 -mathpackcontrol bool
522 enables control of the MATHPACKDISABLE signal thru bit 6 of PIA
523 port B. This function is only required for some dedicated hard‐
524 ware of the author of this program and should be otherwise left
525 alone.
526 MMU Options
529 The following options control the features of the Memory Management
530 Unit. For the 800 and 400, no real MMU chip has been used. Rather, the
531 MMU is a set of standard logic gates that control the memory map of the
532 system. From the 800XL and up, all these gates have been integrated
533 into a dedicated hardware chip called the MMU. Regardless of these
534 technicalities, the memory management logic is controlled by the fol‐
535 lowing options:
536 -4kextended bool
538 Enables additional 4K of memory in the range of 0xc000..0xd000
539 for the Atari 400 and 800 models. For the XL and XE, this memory
540 region contains parts of the ROM and is never available. For the
541 400 and 800, this region is otherwise blank.
542 -axlonram bool
544 Enables emulation of Axlon type RAM expansions that are con‐
545 trolled by address 0xcfff. These RAM disks have pages of 16K
546 each that are mapped into the memory from 0x4000 to 0x8000.
547 -axlonbankbits 0..8
549 Defines the number of bits within the page control port 0xcfff
550 of the Axlon RAM disk emulation used for the page selection. The
551 more bits are enabled, the more banks are available. Each addi‐
552 tional bit doubles the number of 16K banks.
553 -xebankbits 0..8
555 This option is only available if the emulator is setup to the
556 130XE machine type. Then, it defines the number of PIA port B
557 RAM bits used to define the selected/active bank. The 130XE uses
558 two bits for selecting the bank, and hence has four pages of
559 16K, making a total of 64K extended RAM. Note that the more bank
560 bits you enable here, the less compatible the resulting emula‐
561 tion will be to a “straight” 130XE. Specifically, you loose the
562 proprietry PIA Port B “MathPackDisable” at three bits, the self‐
563 test at four bits, the Basic ROM at five bits, separate Antic
564 access at six bits, OS Rom mapping at seven bits and CPU access
565 control at eight bits.
566 OsROM Options
569 The following options control the emulation of the Operating System ROM
570 and related features, most notably various Os patches that are
571 installed into it. NOTE: Original Atari ROM images are not included in
572 the distribution of Atari++ due to copyright restrictions, but Atari++
573 provides an Os emulation that works as well in most cases. Note that
574 the Basic ROM and the Os ROM are contained in two separate chips and
575 hence also emulated separately.
576 -osapath filename
578 Gives the location of the OS A ROM image. This file contains a
579 simple dump of the memory area 0xd800..0xffff of the original
580 first revision Os of the Atari 800 and 400, or a dump from
581 0xf800..0xffff for the 5200 console.
582 -osbpath filename
584 Specifies the location of the second revision for the Atari800
585 and 400 ROM image file.
586 -os1200path filename
588 Specifies the location of the Atari 1200XL ROM image. This is an
589 early version of the Atari 800XL image with some ROM bugs the
590 emulator has to keep care of.
591 -osxlpath filename
593 Specifies the location of the Atari 800XL and later model ROM
594 image. This ROM image contains the memory areas 0xc000..0xd000,
595 the self-test that can be mirrored to 0x5000..0x5800, and the
596 math-pack and the upper ROM area from 0xd800 to 0xffff, in that
597 order. This is also the natural order within the real ROM chip,
598 which is twice as large as for the former Atari models.
599 -os5200path filename
601 specifies the location of the 5200 ROM image.
602 NOTE: If no ROM image is available, the built-in ROM will be used. This
604 ROM is an XL/XE type of operating system only and thus requires a the
605 800XL or 130XE machine type for proper emulation.
606 If none of the above options have been given on the command line, then
608 Atari++ will try to locate them itself, or fall back to the built-in
609 ROM if it is unable to find any ROM. It therefore looks into the direc‐
610 tory “roms” in the current directory. For the XL operating system, it
611 tries to find a file named “atarixl.rom” in this directory. For the Os
612 A resp. Os B image, files named “atariosa.rom” resp. “atariosb.rom” are
613 searched, and loaded if found.
614 -ostype Auto|OsA|OsB|Os1200|OsXL|5200|BuiltIn
616 Defines which kind of ROM shall be loaded into the system. Note
617 that this need not to be identical to the type of machine you
618 are emulating, even though this is the default and probably the
619 most useful selection. The 5200 console is an exception: Its ROM
620 will not be accepted by anything but the 5200 machine, and any
621 other machine type will not accept the 5200 ROM. This is because
622 the mapping of the hardware differs between the “regular” Atari
623 8 bit systems and the 5200 console, making the ROMs non-porta‐
624 ble.
625 The “builtin” option selects the built-in ROM emulation that
627 implements a fully-features 800XL/130XE ROM. This ROM emulation
628 is used if no other ROM image is found. More on this ROM image
629 in the “Os Emulation” section below.
630 The “Auto” option, which is the default, does not select a spe‐
632 cific ROM, but rather picks a suitable rom image for the
633 selected machine.
634 -installpdevice bool
637 Selects whether a patched P: device handler should be installed
638 that redirects printer output directly to the printer component.
639 If this patch is not installed, printer emulation will be re-
640 routed thru the SIO emulation described below. This will work as
641 much as this direct patch, but might be somewhat slower.
642 -installrdevice bool
644 Installs optionally an RS232 interface box handler for serial
645 transfer. On a real Atari, this handler would be loaded from the
646 interface box by a tiny bootstrap code that is usually part of
647 an “AUTORUN.SYS” or “HANDLERS.SYS” file; even though this boot‐
648 strapping is also emulated, the resident handler patched in by
649 this option has the advantage that it doesn't take up any RAM
650 space, unlike the handler provided by the interface box emula‐
651 tion itself. However, in case a program tries to trick around
652 with the interface box, the bootstrapped 6502 based handler pro‐
653 vides closer emulation than the native emulation implemented by
654 this option. Otherwise, the native emulation and the 6502 imple‐
655 mentation provided by the emulated 850 interface box are func‐
656 tionally identical.
657 Note further that this option only installs the CIO emulation
659 layer of the 850 interface box. You still need to enable the
660 interface box itself with the “-Enable850 on” option.
661 -installhdevice bool
663 If enabled, the C: cassette handler is replaced by an emulator
664 specific H: (Host) handler that mirrors parts of the host filing
665 system into the emulator. In specific, booting from tape, or
666 tape access in Basic with the CLOAD and CSAVE statements is then
667 not available. The H: device understands all major CIO commands
668 and most XIO commands, following the conventions of DOS 2.0S,
669 e.g. RENAME and LOCK XIOs are available by its DOS 2.0S command
670 IDs. More about the H: device can be found below in a specific
671 section.
672 -installedevice bool
674 This option installs a specific patch which replaces the operat‐
675 ing system editor device, E: and to some degree, the keyboard
676 device, K: by emulator specific routines that redirect input and
677 output from and to the operating system handler to the standard
678 input and output streams. That is, instead of typing into the
679 emulator window, keyboard data is read from the standard input,
680 and output to the editor device is echoed on the console. In
681 addition, the editor device stream also goes to the front-end of
682 the emulator. Note that this mode relies on the line-buffering
683 of the console and does not provide a full-screen editor, unlike
684 the Atari. You cannot move the cursor back to a previous line
685 and re-enter it. Furthermore, input will not be seen by the emu‐
686 latur until you press RETURN at the end of the line, and only a
687 very limited set of control characters, namely those standard‐
688 ized in ANSI-C, will be transposed from ASCII to ATASCII. For
689 example, cursor movement sequences, which are console-specific,
690 are not available with this patch. The major purpose of this
691 patch is to script the emulator, less to redirect I/O to a ter‐
692 minal. For that, consider the curses front-end instead.
693 -installhasdisk bool
696 Changes the device letter under which the host handler will be
697 installed. By default, the handler will be called H:, but if
698 this flag is set, then the handler will be inserted as D: giving
699 you emulated disk access. Programs that entirely access the disk
700 thru this handler, for example BASIC programs, will then run off
701 the host filing system.
702 -h1dir filename
704 Defines the directory where the first unit of the H: device
705 should be anchored. Files in this directory are accessible thru
706 H1: or H:, provided the host handler is patched in by the option
707 above.
708 -h2dir filename
710 Specifies the anchor path for the second unit of the H: handler,
711 accessible by H2:.
712 -h3dir filename
714 The host directory for the third unit of the H: handler.
715 -h4dir filename
717 Finally, the directory for the fourth unit of the host handler.
718 -siopatch bool
720 If enabled, then serial input/output handling is routed thru an
721 Os patch to the emulated devices directly instead of using the
722 detour thru the POKEY emulation and the emulation of the serial
723 port. This speeds up serial access, especially disk drive
724 access, noticeably, but might cause compatibility problems with
725 some critical software that expects precise timing and exact
726 behavior of the serial hardware.
727 -installmathpatch bool
729 Installs optionally a series of patches into the MathPack module
730 of the operating system; this part of the Os is responsible for
731 floating point support and is used heavely by AtariBasic and
732 other programming languages. This patch replaces the ROM based
733 math routines by custom patches that make use of the host system
734 FPU instead, hence speeding up any kind of floating point opera‐
735 tion dramatically. Due to the limited precision of both the
736 Atari floating point model and the host system floating point
737 system, computations performed by the orginal MathPack might
738 differ slightly from the results obtained from the patch, though
739 the difference is typically neglectible and below the precision
740 of the MathPack itself.
741 KEYBOARD Options
744 The following set of three options relates to the way how Atari++ uses
745 the host system keyboard to emulate the Atari keyboard. They currently
746 only influence the emulation of the console keys which are strictly
747 speaking not part of the keyboard hardware of the Atari.
748 -holdoption bool
750 Defines whether the emulator shall emulate pressing the Option
751 key during the coldstart. The Atari XL/XE roms query the state
752 of this key during bootstrap and disable the built-in BASIC rom
753 in case the Option key is held down. Hence, this option should
754 be set to be able to play (non-BASIC) games on an emulated XL/XE
755 system.
756 -holdselect bool
758 Defines whether the Select console key shall be pressed during
759 the cold start process. No known Os currently evaluates the
760 state of this key on bootstrap, though.
761 -holdstart bool
763 Similar to the above, enables or disables the activation of the
764 Start console key on coldstart. This signals a boot process from
765 the tape recorder.
766 -bufferkeys bool
768 Atari++ comes with a smart keyboard type-ahead buffer that
769 allows you to type faster than the original Atari hardware is
770 able to react. Unrecognized keys are buffered until the emulator
771 is able to fetch them. While this feature helps a lot when pro‐
772 gramming on the emulator, fast gameplay using the keyboard as
773 input device might become more problematic if keys are delayed
774 rather than swallowed.
775 -keybutton.0.enable bool
777 This option is only available for the Atari 5200 emulation; it
778 allows the generation of 5200 “keyboard” events thru joystick
779 buttons. If this specific option is enabled, the '0' key on the
780 Atari 5200 keypad can be connected to a joystick button, similar
781 options exist for all other numeric keys as well as for the
782 haskmark and the asterisk, named “keybutton.hashmark.enable” and
783 “keybutton.asterisk.enable”, respectively.
784 -keybutton.0.button 1..4
786 If the above option is enabled, this option controls which of
787 the virtual buttons of a joystick type device is used to trigger
788 the keyboard event for the '0' key on the 5200 keypad. The but‐
789 ton numbers required here do not directly relate to the hardware
790 numbering of the Os specific joystick device, but they rather
791 refer to the button event numbers used by the analog joystick
792 interfaces of Atari++. The “First_Button” option of this device
793 then defines which hardware button is responsible for generating
794 the virtual button 1 events, and so on.
795 Similar options exist for the keypad buttons 0 to 9, and for the
797 asterisk and the hashmark, namely as “keybutton.hashmark.button”
798 and “keybutton.asterisk.button”.
799 -keybutton.0.sensitivity 0..32767
802 controls the sensitivity of the reaction, i.e. the minimum
803 amplitude of the button input required to trigger the keyboard
804 event. Since buttons are usually digitial, this option can be be
805 left alone in most cases. Similar options exist for the remain‐
806 ing keypad buttons.
807 -keybutton.0.port devicename
810 defines the input device for the Atari 5200 keypad '0' button.
811 This device is setup in the very same way as for the JOYSTICK
812 emulation and we refer to this chapter instead. Similar options
813 exist for all other keypad keys.
814 CARTRIDGE Options
817 The next set of options allows to insert a cartridge into the emulated
818 cartridge slot of the system. Currently, only the left cart slot of the
819 Atari 400 and 800 , resp. the one and only cart slot of all later mod‐
820 els is emulated.
821 -cartpath filename
823 specifies the filename of the cartridge image to load.
824 -carttype none|8k|16k|32k|oss|ossb|sdx|xegs|bounty‐
826 bob|flash|megarom|atrax
827 specifies the type of cartridge to load. Unfortunately, the emu‐
828 lator cannot figure out the cart type itself in all cases just
829 by looking at the image file. Therefore, this option has to be
830 given along with the option above.
831 None is a dummy option that just disables the cart, and hence
833 ignores the above option altogether.
834 8K emulates an 8K sized plain cartridge that is mapped into the
836 memory from 0xa000 to 0xbfff.
837 Right8K this cartridge type is only available for the Atari800
839 hardware type and emulates a cartridge for the right cart slot
840 of this system that gets mapped to the area 0x8000 to 0x9fff.
841 16K emulates a plain 16K cart occupying the memory region from
843 0x8000 to 0xbfff.
844 32K emulates 32K cartridges of the 5200 game system. This option
846 and the 32K rom images will not be accepted for all other
847 machine types and hence remains unavailable then.
848 32KEE16 emulates a 5200 game system cartridge with a 16K sized
850 image file with incomplete addressing that occupies 32K ROM
851 space.
852 Debug32 emulates a 32K debug cartridge for the 5200 game system
854 with two 16K banks mapped into the area from 0x8000 to 0xbfff.
855 Oss emulates an Oss super cartridge that is mirrored into the
857 memory map from 0xa000 to 0xbfff, but is 16K sized internally.
858 The cartridge therefore provides a bank-switching mechanism thru
859 the CARTCTRL system component, as it consists internally of two
860 ROM chips, called RomA and RomB in the following. The lower
861 region 0xa000 to 0xafff is variable and can be bank-switched,
862 the upper region 0xb000 to 0xbfff is hard-wired to the upper
863 part of RomA. The following table shows the mapping for the
864 lower region:
865 CartCtrl Port Rom mapped at 0xa000 to 0xafff
868 ─────────────────────────────────────────────────────────
869 0xd500 RomB Lo
870 0xd502 or 0xd506 Blank
871 0xd501,0xd503 or 0xd507 RomA Lo
872 0xd504 or 0xd509 RomB Hi
873 0xd508 and up disable cart
874 OssB is also an Oss super-cart except that the cartridge ROM has
876 been dumped to disk in a different order and hence the address‐
877 ing of the cartridge ROM contents is different. If the Oss
878 option does not work, try this option instead.
879 SDX emulates a 64K large ROM image with eight banks mapped into
881 the region of 0xa000 to 0xbfff.
882 EXP a variant of the SDX cartridge with a slightly different
884 bank switching logic.
885 Diamond another variant of the SDX cartridge type with just
887 another bank switching logic.
888 XEGS emulates a variable size XEGS cartridge. This cart type
890 occupies 16K of memory within the address space of the 6502 CPU
891 but consists of several banks that can be mapped into the
892 0x8000...0x9fff region.
893 ExtXEGS a mildy extended version of the XEGS cartridge type that
895 additionally allows disabling the cartridge.
896 BountyBob emulates the 40K sized BountyBob cartridge for the
898 5200 games system. This cartridge uses a very unique bank
899 switching mechanism that requires its own emulation provided by
900 this option.
901 Flash Emulates Steven J. Trucker's “AtariMax” flash ROM cart.
903 This is a 128K or 1MB cart with bank-switching logic that is
904 mapped into the 0xa000...0xbfff region. This cart type allows
905 flashing, and thus the cart ROM can be modified by the emulation
906 process. The emulator will ask you to save back the cart image
907 as soon as the cart shall be removed again.
908 MegaROM Emulates the various types of the Mega ROM cartridges.
910 These carts come in varous sizes and map in as 16K banks in the
911 area of 0x8000...0xbfff.
912 Atrax Emulates the 128K bank switching Atrax cartridges that map
914 in as 8K banks in the area of 0xa000...0xbfff.
915 Will Another super cartridge type of 32K or 64K size that maps
917 its 8K sized banks into the area of 0xa000 to 0xbfff.
918 Phoenix This type emulates the Phoenix and Blizzard super car‐
920 tridges. The first is a regular 8K cart that can be disabled,
921 the latter is a 16K switching cart. Both are emulated by the
922 same cart type.
923 ATMax A super cart that comes as 128K or 1MB cartridge.
925 -rtime8 bool
928 enables or disables the emulation of the RTime-8 pass-thru car‐
929 tridge. This this a cartridge rom that contains a battery
930 buffered real-time clock and passes the cartridge slot connec‐
931 tions thru to be able to use the real-time clock together with
932 other cartridges. The default is not to enable the real-time
933 clock cartridge.
934 CARTFLASH Options
937 The flash cartridge type is the only cart type that can be configured
938 by the command line and the GUI. Currently, there is only a single
939 option available, namely:
940 -enablecartflash
943 If this option is disabled, the flash cartridge mapping will be
944 disabled on the next reset. However, the cart still receives the
945 bank mapping signals and thus can be re-enabled by software.
946 This is useful if you want to re-flash the cartridges by Steve
947 Trucker's flashing software: Just disable this switch, insert
948 the flash software disk, and reboot. The cart will be disabled,
949 the Atari will boot from the inserted disk, and the flash soft‐
950 ware will re-enable the cartridge, allowing you to overwrite its
951 contents. To write the cart image back to disk, change the car‐
952 tridge type to “none” or insert any other cart.
953 BASIC Options
956 The following options control the function of the BASIC Rom of the
957 Atari 800XL and later models. Since the Atari 800 and 400 models do not
958 come with a built-in BASIC, these options are ignored for the earlier
959 models; you'd need to insert the BASIC as a regular 8K cartridge for
960 them. Furthermore, whether the basic is mapped for the XL and later
961 series depends on whether the Option console key is held down during
962 bootstrap. This option is part of the keyboard options below, even
963 though it influences the working of the basic ROM for the XL and XE
964 series.
965 Atari published three versions of their basic, Revisions A, B and C.
967 Each has its own bugs, with revision B having the most critical bugs
968 (really) and revision C is the most bug-free. In addition, the emulator
969 also includes a built-in Basic emulation, Basic++ , which fixes most
970 bugs of all three revisions.
971 -basicapath filename
974 This option specifies the file name of the Revision A Basic rom
975 image if you have one. The ROM image is a simple 8K memory dump
976 of the ROM appearing between 0xa000 and 0xbfff. Revision A was
977 only available as cartridge on the 800 and 400 models; if you
978 want to emulate these two models, insert Revision A as car‐
979 tridge, see the CARTRIDGE section of this manual for details.
980 Revision A contains several bugs and is only of historical
981 interest.
982 -basicbpath filename
985 This option specifies the file name of a Revision B Basic rom
986 image. This revision was shipped with most early 800XL and 600XL
987 machines. It contains one critical bug that crashes the Basic
988 interpreter potentially when entering source code. It should
989 best be avoided.
990 -basiccpath filename
993 This option selects the location of a Revision C Basic rom
994 image. This revision was delivered with many later 800XL and
995 600XL models and the last and final XE series. It is the most
996 bug free of the three Basic revisions Atari produced and the
997 recommended selection if you want an original Basic.
998 -basictype auto|reva|revb|revc|builtin|disabled
1001 Selects the Basic version Atari++ should emulate. The default is
1002 “auto”, which selects Revision C on XL and XE machines if is
1003 available, otherwise the built-in Basic++.
1004 “reva” selects the revision A Basic, “revb” the revision B basic
1006 and “revc” the revision C basic. “builtin” uses Basic++, which
1007 is compiled into the emulator and always available. “disabled”
1008 removes the Basic completely, making it unavailable indepedently
1009 of the state of the Option key on all machine types.
1010 SIO Options
1013 The Serial Input/Output module is a specific part of the operating sys‐
1014 tem taking care of serial communication. The Atari++ emulation compo‐
1015 nent of the same name controls the low-level emulation features of all
1016 devices emulated on the serial port, hence the disk-drives, the
1017 printer, the 850 serial interface box and the tape. The emulation of
1018 the serial port can be bypassed by the -siopatch option described in
1019 the OS Option section above, giving a noticeable speedup for disk-drive
1020 and printer, but possibly also causing compatibility problems for soft‐
1021 ware that depends on precise timing or side-effects of the Os implemen‐
1022 tation. You usually need not to care about the settings below as they
1023 closely match those of typical serial hardware anyhow.
1024 -serincmddelay 0..240
1026 The amount of time taken by a serial device to accept a command
1027 frame. This time is given in horizontal blanks. It defaults to
1028 50 lines.
1029 -readdonedelay 0..240
1031 The time taken for a serial read command to complete. For the
1032 disk-drive emulation, this would emulate the time required to
1033 read a sector from disk up to the time where the first byte of
1034 the sector arrives at the port. This setting also defaults to 50
1035 lines.
1036 -writedonedelay 0..240
1038 Required time to complete a write command. For the disk-drive,
1039 this is the time taken from the last byte of a sector arriving
1040 at the drive up to the time where the disk-drive sends the
1041 acknowledgement frame. This setting defaults again to 50 lines.
1042 -formatdonedelay 0..1024
1044 Required time to format a disk in a disk-drive, measured as the
1045 time from issuing the command up to the time where the first
1046 byte of the sector status map arrives at the serial input. This
1047 is again given in horizontal lines. Since the Os assumes that
1048 the timing of formatting is a bit more relaxed than the regular
1049 reading time - yes, formatting is a read command for the Atari -
1050 this is a separate option, defaulting to 400 horizontal lines.
1051 PRINTER Options
1054 This option set controls the printer emulation. Commands and data enter
1055 this emulation either by the SIO, or directly by the P: handler should
1056 it be patched into the Os. See the OS Options for more details on this.
1057 This option set is used in either case, no matter how the emulated
1058 printer is accessed.
1059 -printtarget tospoolcommand|tofile
1061 selects where printer output is sent to. For the tospoolcommand
1062 selection, printer output is piped into the printcommand
1063 selected by the option below. This is typically the “lpr” or
1064 “lp” command on Unixoid systems. For tofile , printer output is
1065 sent to a regular file. On some systems, this might be the only
1066 available option to print at all.
1067 -printcommand file
1069 Specifies the command used to print out text on the host system.
1070 The text arriving at the emulated printer will wait in a queue
1071 and will be flushed regularly, appearing at the STDIN of this
1072 command. Typically, this should be either lpr or lp , depending
1073 on the printing system you use at your machine.
1074 -printfile filename
1076 Specifies the file printer output is sent to should this type of
1077 output be selected. This is by default empty, disabling printer
1078 output completely, though the printer appears to be turned on.
1079 -appendtoprintfile bool
1081 defines whether the printer output file specified by the previ‐
1082 ous option is overwritten on each printer-output or the new out‐
1083 put is just appended at the end of it. By default, new printer
1084 output overwrites older printer dumps.
1085 -enableprinter bool
1087 Enables or disables the emulated printer. If set to off, the
1088 printer will not react on any SIO commands as if it has been
1089 turned off. Otherwise, printing will be allowed.
1090 -transposeeol bool
1092 The Atari doesn't use the regular LF character to separate lines
1093 on the printer output. Rather, it uses the character 0x9B (CSI
1094 in the ANSI set, named EOL on Ataris) to separate lines. Hence,
1095 for printing text, EOL has to be transposed into line feeds by
1096 this option, which is also the default. However, for graphics
1097 output, this character transposition will change the meaning of
1098 the graphics data send to the printer, and will hence distort
1099 the graphics. NOTE: Currently, Atari++ does not include the
1100 emulation of a graphics printer. All control and graphics
1101 sequences sent out to the emulated printer will be spooled
1102 directly into the print command without interpreting them fur‐
1103 ther.
1104 -flushdelay 0..60
1106 This specifies the delay in seconds from the last data arriving
1107 at the emulated printer until the collected text/graphics are
1108 printed out. Hence, if data is printed at a rate lower given by
1109 this delay, they will appear in separate spool jobs. This delay
1110 defaults to five seconds.
1111 SPEED Options
1114 The following set of options controls the timing of the emulator. Sev‐
1115 eral other factors influence the maximum speed, though. First of all,
1116 the graphical front-end of the emulator might be more or less perform‐
1117 ing. For full-screen emulation, the SDL front-end is performing well
1118 provided no pixel upscaling is used. In all other cases, the X11 fron‐
1119 tend offers higher speed. This is not the fault of the emulator, but
1120 rather a matter of the poor performance of SDL. Furthermore, the sound
1121 emulation has some impact as well. For software speech emulation, high
1122 sampling rates and slim buffers are a must, causing additional software
1123 overhead and higher CPU loads. To maximizing the speed, either run the
1124 X11 frontend on 1x1 or 1x2 pixel sizes and reduce the quality of the
1125 audio output.
1126 -unlockrate bool
1128 If this option is set to true, then a custom, non-standard frame
1129 rate can be selected that is not locked to the video mode (see
1130 below) of the emulated machine. The default is to disable this
1131 option and thus to lock the frame rate to the natural frame rate
1132 of the emulated machine.
1133 -framerate 1..100
1135 This option specifies the screen refresh rate, to be given in
1136 milliseconds per frame. A standard PAL screen with 50 frames per
1137 second requires 20 milliseconds per frame, a NTSC screen
1138 requires 17 milliseconds. This option defaults to 20, i.e. the
1139 PAL rate, but is ignored unless the frame rate is unlocked with
1140 the unlockrate switch above.
1141 -maxmiss 1..16
1143 Unlike the above, this option controls how much frames the emu‐
1144 lator may miss to keep the emulation speed. If this is set to
1145 one, the emulator never misses a frame, may become slow on less
1146 performing systems. If set to a value higher than one, at most
1147 the specified number of frames might be dropped to keep up the
1148 refresh rate set by the option above. Hence, it does not hurt to
1149 select a higher maxmiss rate on a fast machine, but it will keep
1150 up the speed for more complex graphics on slower machines as
1151 well at the cost of not emulating the video output frequently.
1152 -videodmode PAL|NTSC
1154 Intentionally identical to the same option of the ANTIC and GTIA
1155 emulation, this selects the frame rate based on the video output
1156 mode. For a PAL machine, this selects a freshmode of 50
1157 frames/second, for a NTSC machine, the emulator will try to gen‐
1158 erate 60 frames/second. This option is overridden if the unlock‐
1159 rate switch above is enabled.
1160 DISKDRIVE Options
1163 The following set of options controls the emulation of up to four disk
1164 drives. The diskdrive options consist of a base name, a dot and the
1165 unit number specifying the unit of the disk drive they control. Hence,
1166 all the following options exist four times, and just differ by the
1167 digit behind the dot.
1168 -enable.1 bool
1170 Enables or disables the first diskdrive. If set to off, the
1171 first drive will not react as if it has been turned off, other‐
1172 wise it will be turned on. The default is to enable the first
1173 drive and to disable all others.
1174 -image.1 filename
1176 Specifies the path to an image file to be loaded into the drive.
1177 The Atari++ emulator supports several kinds of image files:
1178 First, raw disk images that keep the contents of the disk sector
1179 by sector. These files are typically identifies by their exten‐
1180 der .xfd. The second available format is the so called .atr
1181 format implemented by several other Atari emulators. It consists
1182 of a tiny header describing the format and the size of the disk
1183 plus the sector image. The third format supported by Atari++ is
1184 that of Atari binary load files or short, so called .exe files.
1185 These files consist of a two 0xff byte header plus address
1186 information where to place the data to load. These files are
1187 booted by writing them as DOS 2.0S files onto disk, toghether
1188 with a minimal game DOS header that bootstraps the .exe format.
1189 Note that no full DOS will be available for these files, though
1190 this emulation is sufficient for most .exe based games right
1191 away. While the above formats capture all high-level details of
1192 disks, they do not include enough information to reproduce the
1193 low-level behavior of the disk drive. Specifically, copy pro‐
1194 tected disks cannot be represented by them. Atari++ supports for
1195 that the .atx format, which includes pecularities such as disk
1196 timing, duplicate sectors or sector defects. Again, the emulator
1197 cannot create such disk images, but is able to read from them.
1198 Atari++ also supports .dcm images, which have been prepared by
1199 the “Disk Communicator” program and are (slightly) compressed.
1200 Similar to the .exe files, Atari++ cannot re-compress these.
1201 Therefore, disk images of this type are marked write-protected,
1202 making writes to these disks fail. All of the above disk image
1203 types can be compressed by means of the gzip program; Atari++
1204 will then uncompress them on demand as soon as the image gets
1205 loaded. Since it does not re-compress images, these disks also
1206 always end up write-protected. Last but not least, the emulator
1207 also supports .bas files, which are tokenized Basic files. To
1208 load such files, make sure that either a Basic cartridge is
1209 inserted, or the Basic emulation is enabled. The Basic program
1210 will not boot automatically if the emulated machine is reset,
1211 unless Basic++ , i.e. the built-in Basic dialect, is selected
1212 and the Basic file is inserted into the first drive. All other
1213 Basic dialects will see the basic image as a file named
1214 “AUTORUN.BAS” on a write-protected disk. To start the file,
1215 enter the command
1216 RUN "D:AUTORUN.BAS"
1218 manually on the editor window of the emulated Basic and press
1220 RETURN.
1221 -protect.1 bool
1224 Enables or disables the write-protection of the inserted disk.
1225 If set to on, the disk image will be write-protected as if the
1226 write-protection notch has been covered on a physical disk. The
1227 emulator also write-protects disk images automatically if the
1228 corresponding image is marked non-writeable by the protection
1229 bits of the host operating system, or if the disk is build up
1230 for the .exe binary load file emulation, or comes in the already
1231 compressed .dcm Disk Communicator format. Similarly, all .gz
1232 compressed images and .bas files are write-protected, no matter
1233 what the original file format has been.
1234 -drivemodel.1 1050|810|815|happy1050|warp‐
1237 speed810|speedy|xf551|usturbo|indusgt
1238 selects the drive model to emulate. The “1050” is the disk drive
1239 that shipped with the XL series of computers, and the default
1240 selection. It handles single or extended density disks of 720 or
1241 1040 sectors, each of which is 128 bytes long. Note that this
1242 drive type does not support ATR or XFD images with sector counts
1243 or sector sizes that go beyond the capabilities of this drive.
1244 The “810” is the first disk drive that was available for the 800
1245 and 400 models. It handles only single density disks, i.e. disks
1246 of 720 sectors of 128 bytes each. All other disk types will not
1247 be accepted. The “815” drive is a dual-disk drive supporting
1248 single or double density disks of 720 sectors, either 128 or 256
1249 bytes per sector. The “xf551” is the last floppy drive sold by
1250 Atari, it allows single, extended, double and quadrupel density
1251 disks. It has two heads and can read the disk from both sides
1252 simultaneously. All other drive types are third party extensions
1253 that allow higher transfer speeds and extended sector formats.
1254 Note that the file management system that is part of the built-
1255 in Os emulation does not make use of the higher serial transfer
1256 speeds of these extensions, but third-party file systems will be
1257 able to detect these drive types and will then switch to a
1258 higher transfer speed.
1259 Similar disk drive options exist for drives two to four by replacing
1262 the digit 1 in the above list by the appropriate drive number.
1263 SIOCABLE Options
1266 The following set of options control the overall setup of Matthias
1267 Reichl's “AtariSIO” emulation. It requires that the kernel interface
1268 and development files for /dev/atarsio are available. Alternatively,
1269 the DirectSerial can be used, which might be less reliable since it
1270 cannot ensure correct timing. To make use of the AtariSIO emulation,
1271 connect your Atari drive by means of one of two possible interface
1272 cable types to the PC, and disable the built-in disk drive emulation
1273 for the corresponding drive unit. I.e. if your external drive has been
1274 set to drive unit 1, the internal emulation for drive 1 has to be dis‐
1275 abled by -enable.1 false , or de-selecting the corresponding gadget in
1276 the DiskDrive menu.
1277 -cabletype 1050-2-PC|ProSystem
1280 selects the type of the cable that has been used to interface a
1281 1050 or 810 drive to the PC. Currently, AtariSIO supports two
1282 cable types, the “1050-2-PC” and the “ProSystem” layout.
1283 -enableatarisio bool
1286 This is the overall enabling/disabling option for the AtariSIO
1287 interface, no matter which protocol is used.
1288 -directserial bool
1291 if enabled, Atari++ does not use the AtariSIO kernel interface
1292 but rather a user space interface, not requiring the installa‐
1293 tion of the AtariSIO kernel module. Even though this sounds
1294 attractive, timing cannot be as precise as for the kernel inter‐
1295 face, and this interface may fail if the system is under heavy
1296 load. If AtariSIO is not compiled into the system, this is the
1297 only possible interface method anyhow and this command line
1298 option does not appear. Direct serial communication is then
1299 always enabled.
1300 -cmdtodatadelay 0..2000
1303 only used if the directserial option is enabled, this defines
1304 timing details for the Atari SIO emulation; specifically, this
1305 is the delay from the start of the falling edge of the COMMAND
1306 line to the start of the first byte of the command frame, given
1307 in micro seconds. According to the Atari SIO specifications,
1308 this delay shall be between 750 and 1600 usecs long. The default
1309 is 900usecs.
1310 -cmdframelength 800..10000
1312 This option defines another timing constraint of the Atari SIO
1313 directserial communications protocol, namely the total length of
1314 a command frame, from the falling to the raising edge of the
1315 COMMAND line, again given in micro seconds. According to the
1316 Atari SIO specifications, this delay shall be between 4060 and
1317 5210usecs long, the default is here 5150usecs. Note that due to
1318 the load of the host system some fine tuning of this parameter
1319 might be required to get a stable SIO communication.
1320 TAPE Options
1323 In addition to disk drives, Atari++ also supports an archaic medium for
1324 data storage, namely the 410 and 1010 tape drives. They store binary
1325 data in frequency-modulated form, a high tone for a one called “mark” ,
1326 and a somewhat lower tone for a zero also called “space”. The emulator
1327 supports two types of tape images: First, .cas files, which are tape
1328 archives that have already been converted into a binary representation,
1329 and .wav files which contain the digitized audio from the tapes
1330 directly. For the latter, Atari++ emulates analog filters required to
1331 decode the audio, though due to the nature of the process, .wav files
1332 are less reliable, similar to real-world tape recordings. If possible,
1333 use .cas files whenever possible.
1334 The option
1336 -image filename
1338 defines the .cas or .wav file to be read from or to be written
1339 to. Atari++ accepts both the “cas” or “wav” format as input, and
1340 can create both file types when writing to a simulated tape. The
1341 emulator cannot append to tape archives, i.e. each recording has
1342 to go into a separate file.
1343 -play bool
1346 This option presses the “play” button of the simulated tape
1347 drive and hence allows the motor to spin if enabled by the main
1348 system. This option does not make much sense as a command line
1349 option but is best used within the emulator. Once the Atari
1350 operating system beeps once, requesting you to start the tape,
1351 enter the menu and start the tape by the button of the same name
1352 in the Tape menu, then return to the emulation and press the
1353 RETURN button there. This will start the playback.
1354 -record bool
1357 For recording data on tape, the Atari operating system beeps
1358 twice, requesting you to press the “play” and “record” buttons.
1359 The same must be done in the emulator: Go to the menu, into the
1360 Tape menu, enable the “play” option there, but also select the
1361 “record” button below. The corresponding command line option is
1362 as given above, but also makes little sense as stand-alone
1363 option. Afterwards, return to the emulator window and press
1364 RETURN. This starts the recording process. If the “siosound”
1365 option is enabled, you should hear a distinct high pitch tone
1366 that is typical for data recordings on tape.
1367 -eject bool
1370 presses the simulated eject” button of the tape drive, removing
1371 the recording from the drive. This unloads the image and com‐
1372 pletes it on disk. It is most useful as a button of the same
1373 name in the Tape menu as well.
1374 -recordaswav bool
1377 controls the output format when recording data on tape. By
1378 default, Atari++ records in the more robust .cas format which
1379 does not require additional decoding. If this option is set, the
1380 emulator creates .wav files that correspond to the audio infor‐
1381 mation that would be recorded on a real tape. This format is not
1382 recommended for archiving purposes as it creates longer files
1383 that are also harder to decode.
1384 The following additional options are also recognized by the tape
1386 subsystem:
1387 -videomode PAL|NTSC
1389 defines the video mode the system operates in, and by that the
1390 timing of the tape. This should be, and on the command line only
1391 can be, set identical to the video mode of the host system.
1392 -motoroffeofgap 20..10000
1395 controls when the emulator considers a stopping tape as the end
1396 of the recording. Unlike the real machine, where the tape is
1397 entirely controlled by the user, the emulator has to make some
1398 guessing as to when a recording should be considered as com‐
1399 pleted, and no additional data is following. It currently does
1400 this whenever the motor stops longer than the indicated time, in
1401 milliseconds. The value defaults to 3000, i.e. three seconds.
1402 Once the motor halts longer than this, the simulated tape is
1403 removed from the tape recorder and no further data is expected.
1404 Enlarge this value if a tape file is created by a relatively
1405 slow BASIC program.
1406 ATARISIO Options
1409 This option group fine tunes the AtariSIO interface whenever it is
1410 available. Unlike the SIOCABLE option group, ths set exists once per
1411 external drive and defines parameters that are specific for the drive
1412 and not to the cable interfacing to the drive. Therefore, the following
1413 options exist four times, where the suffix “.1” needs to be replaced by
1414 the appropriate drive number.
1415 -sioenable.1 bool
1418 enables the first - or subsequent for higher suffixes - external
1419 drive. It is disabled by default. Note that for redirecting
1420 drive accesses to AtariSIO, the emulator-internal drive emula‐
1421 tion must be disabled as well. Hence, to use a real 1050 as
1422 first floppy drive, the following two options would be required:
1423 -sioenable.1 true -enable.1 false
1425 -sioprotect.1 bool
1428 enables or disables an additional write-protection that blocks
1429 any write access to the external drive as if the floppy write-
1430 protection notch has been covered. This option defaults to off.
1431 -siotimeout 1..30
1434 specifies the timeout in seconds that applies to regular com‐
1435 mands. Since the Atari++ emulation of the diskdrive applies at
1436 the level of raw POKEY communcations, the emulator cannot know
1437 the desired timeout that has been selected by the driving Atari
1438 software. This timeout defaults to seven seconds.
1439 -sioformattimeout 10..120
1442 specifies the timeout in seconds for formatting commands that
1443 typically require longer than regular commands. This timeout
1444 defaults to sixty seconds, i.e. one minute, but is overridden by
1445 the specifications that are returned by the disk drive itself as
1446 soon as a status command is send to the drive.
1447 JOYSTICK Options
1450 Joystick emulation for Atari++ consists of two layers: First of all,
1451 the emulation of the corresponding port at the emulated hardware, and
1452 second the generation of sigals to feed data into this emulated port.
1453 For that, Atari++ uses the concept of a generic input device consisting
1454 of two axes and four buttons, abstracting from the real physical device
1455 on your machine to generate the input. For a physical (analog) PC joy‐
1456 stick, the meaning of the two axis and four buttons should be obvious,
1457 but other sources for the abstract input device exist as well, e.g. the
1458 mouse or the keyboard.
1459 Later stages of the Atari++ input layer then only refer to the buttons
1461 of these virtual devices, e.g. the keypad options of the 5200 device.
1462 The following set of options do not control the physical input devices,
1464 but rather select how the emulator should make use of this abstraction
1465 layer, whereever it comes from, to form digital joystick input. I.e. ,
1466 these options control the emulation of the emulated joystick port on
1467 input from an abstract input device.
1468 Similar to the diskdrive options, all joystick options exist four
1470 times, now numbered from zero to three. The digit behind the dot in the
1471 option name defines the joystick port this option controls. For the
1472 Atari 800 and 400, all four ports are used by the emulator, for the XL
1473 and later models, only the ports 0 and 1 are mapped to the emulated
1474 hardware, similar to their physical counterparts.
1475 -joystick.0.sensitivity 0..32767
1478 This option sets a threshold that must be crossed by the
1479 abstract analogue joystick input to detect a joystick movement
1480 on the emulated joystick port. The lower the number, the higher
1481 the sensitivity. The abstract input devices generate axis move‐
1482 ments from -32767 to 32767, the default of this option is that a
1483 movement of 8192 units on this scale is required to generate an
1484 input signal.
1485 -joystick.0.port devicename
1487 Defines the name of the abstract device that should be connected
1488 to the port. Currently, the following devices exist:
1489 MouseStick.0
1491 Uses the mouse on your host system as abstract input device,
1492 with the horizontal and vertical position of the mouse
1493 pointer forming the horizontal and vertical axis of the
1494 abstract input device connected to the port. There is only
1495 unit 0 of this device.
1496 RelMouseStick.0
1498 This works similar to the MouseStick input device above
1499 except that reacts on mouse movements rather than the abso‐
1500 lute mouse coordinate. This is often the better alternative,
1501 unless the pointer device emulating the mouse of the host
1502 machine uses also an absolute position, i.e. a trackpad or a
1503 touchscreen.
1504 KeypadStick.0
1506 Uses the keypad on the keyboard of the host system forming
1507 the abstract input device. Digits 8,4,6 and 2 generate maxi‐
1508 mal axis movements in top, left, right and down movement,
1509 respectively; keys 7,9,1 and 3 move in the corresponding
1510 diagonal directions. The 0 and Enter map to button 0 of the
1511 joystick. There is - quite obviously - only unit 0 of the
1512 keypad-stick. These keys can be reconfigured dynamically,
1513 and its configuration is found under the section KeypadStick
1514 below.
1515 AnalogJoystick.0
1518 Uses the (real) analog joystick connected to the port con‐
1519 trolled by the /dev/js0 device to form the abstract input of
1520 the device. Which physical axis forms which abstract axis is
1521 controlled by the analog joystick options described below,
1522 but the default mapping is the obvious: Each physical axis
1523 maps to the same abstract axis, and buttons 0 and 1 map to
1524 their abstract counterparts. Atari++ accepts up to eight
1525 physical joysticks by replacing the digit 0 in the above
1526 option by 1 to 7 for further joysticks that are then con‐
1527 nected to the corresponding joystick devices.
1528 DigitalJoystick.0
1530 Uses a (real, antique) Atari Joystick connected to an analog
1531 PC joystick port by means of the “El Cheapo” joystick
1532 adapter of the author. This adaptor maps the digital input
1533 lines of a digital joystick to the buttons 1 to 4 of an ana‐
1534 log joystick, and maps the one and only button by a resistor
1535 array to axis 0. As above, some parameters of this interface
1536 can be setup by the digital joystick options described
1537 below. Similar to above, the signals generated by this hard‐
1538 ware are then read thru the standard /dev/js0 Linux inter‐
1539 face, and up to eight digital joysticks can be emulated this
1540 way, accessing the devices /dev/js1 to /dev/js7. NOTE: You
1541 need to build some additional hardware to make use of this
1542 abstract device, but you get perfect Atari feeling as a
1543 bonus.
1544 The schematics for this interface are included in the dis‐
1546 tribution as “joystick.ps”.
1547 SDLAnalog.0
1550 Similar to “AnalogJoystick.0” except that the joystick posi‐
1551 tion isn't read from the kernel interface directly, but
1552 rather indirectly thru the SDL library. This makes abso‐
1553 lutely no difference except that on some systems only the
1554 kernel interface is available, whereas on others only the
1555 SDL interface can be used.
1556 SDLDigital.0
1558 Works exactly the same as “DigitalJoystick.0” except that
1559 the joystick movements are reported thru the SDL library
1560 rather than thru the kernel interface. Causes no difference
1561 in usage and options otherwise.
1562 None Do not connect any device to this joystick input and read it
1564 as “centered, no button pressed” all the time.
1565 Similar to the diskdrive options, the joystick options exist four times
1567 with the unit numbers 0 to 3. The default for the abstract input
1568 device is to use the keypad stick for joystick zero and leave all other
1569 joysticks and paddles unconnected.
1570 NOTE: The 5200 console system does not use standard Atari digital joy‐
1572 stick input. Instead, analog joysticks connected to the paddle inputs
1573 are used. It is therefore mandatory to define the input devices of the
1574 first two paddles, paddle 0 and 1, to have an input device for the 5200
1575 console. The digital joystick inputs defined by the options above WILL
1576 NOT WORK.
1577 PADDLE Options
1580 The following set of options control the emulation of up to eight pad‐
1581 dles that can be connected to the emulator. Similar to the above, the
1582 emulation requires an abstract input device to read the input of the
1583 emulated paddle from; paddle emulation uses only axis zero of this
1584 abstract device to form the paddle input, but requires buttons zero and
1585 one for the emulation of the two paddle buttons.
1586 NOTE: The paddles on the Atari machines use the joystick input lines
1588 for the paddle buttons. For that reason, paddles and joysticks should
1589 not make use of the same input device.
1590 NOTE: For the 5200 system, the controller is connected as a paddle and
1592 hence these - and not the joystick options - must be defined.
1593 As above, the following options exist several times, with the digit 0
1595 replaced by 1..7 for all other paddle units. Whereas the Atari 800 and
1596 400 allow this maximal number of eight paddles, inputs 4 to 7 are not
1597 available on a real Atari XL or XE. However, the Atari++ allows connec‐
1598 tion to these paddle inputs regardless of the emulated host input as
1599 the corresponding input lines are otherwise unused on the real hardware
1600 either.
1601 -paddle.0.sensitivity 0..32767
1604 Adjusts the sensitivity of the paddle and hence the movement
1605 necessary for a full paddle rotation. Note that the abstract
1606 input device generate movements on a scale of -32767 to 32767.
1607 -paddle.0.invert bool
1609 Since paddle input has no natural orientation, this option
1610 allows you to invert the meaning of the input device position.
1611 Since some games interpret paddle positions just opposide to
1612 others, this flag helps you out as it changes left movement to
1613 right, or upwards movement to downwards movement.
1614 -paddle.0.port devicename
1616 Defines which abstract input device to use to feed the paddle
1617 emulation. The very same devices as for the joystick emulation
1618 are available here, though pure digital devices as the keyboard
1619 or the digital joystick device are not very usable for paddle
1620 emulation. Since an abstract input device provides two axis and
1621 two buttons each, it makes sense to map one input device to two
1622 paddle inputs: For that reason, each even paddle number maps to
1623 the first axis and the first button, and each odd paddle number
1624 maps to the second axis and button of each abstract input
1625 device.
1626 LIGHTPEN Options
1629 Atari++ also allows emulation of the lightpen as a kind of analog input
1630 device. Though rarely used, the corresponding input lines at ANTIC are
1631 available and can be feed by this emulation component. There is only
1632 one lightpen device available, though its other options are very simi‐
1633 lar to the paddle emulation.
1634 -lightpen.sensitivity 0..32767
1636 Defines the sensitivity of the lightpen and hence the fac‐
1637 tor/adjustment between the real physical device and the emulated
1638 position of the lightpen on the screen.
1639 -lightpen.port devicename
1641 Specifies which abstract input device to connect the emulated
1642 lightpen to. The list of available devices is identical to the
1643 list of devices for all other gameport like input, please see
1644 the JOYSTICK Options section above.
1645 KEYPADSTICK Options
1647 Options in this group define the keys used by the Keyboard Joystick
1648 emulation. By default, the numeric keypad to the right of a standard PC
1649 keyboard is used for this purpose, but the keys can be reconfigured.
1650 -leftup keyname
1652 defines the key that moves the stick in the diagonal left
1653 upwards position. Pressing the left and the up key simultane‐
1654 ously is equivalent to this. Key names are either the numbers 0
1655 to 9 or the letters A to Z, indicating the corresponding keys on
1656 the main keyboard, or are taken from the list below. An empty
1657 string indicated by an empty pair of opening and closing quotes
1658 disables the corresponding function.
1659 -up keyname
1661 -rightup keyname
1663 -left keyname
1665 -right keyname
1667 -leftdown keyname
1669 -down keyname
1671 -rightdown keyname
1673 move all the joystick in the corresponding direction. Diagonal
1674 directions can be either assigned to separate keys, or are
1675 reached by pressing the two direction keys simultaneously.
1676 -center keyname
1678 centers the joystick.
1679 The option
1681 -leftbutton keyname
1683 configures the key that emulates the left button if the keypad
1684 is used as a paddle, or the one and only button if the keypad
1685 emulates a digital joystick.
1686 -rightbutton keyname
1688 selects the key to emulate the right button on paddles. The key
1689 has no function if the keypad emulates a standard Atari joy‐
1690 stick.
1691 Key Names are either alpha-numeric characters from 0 to 9 or A
1693 to Z indicating the corresponding keys on the main keyboard, or
1694 the following special names. Note that names containing spaces
1695 need to be quoted on the command line:
1696 -
1698 Name Key
1699 Cursor Left Left pointing arrow of the four cursor keys
1700 Cursor Right Move cursor right key
1701 Cursor Up Move cursor up
1702 Cursor Down Move cursor down, all the above on the cursor keypad
1703 Return Return key on the main keyboard
1704 Tab TAB key on the main keyboard
1705 Backspace Backspace key on the main keyboard
1706 Keypad 0 Digit 0 on the numeric keypad, similar for 1 to 9
1707 Keypad Divide Division key on the numeric keypad
1708 Keypad Multiply Multiplication key on the numeric keypad
1709 Keypad Plus Addition on the numeric keypad
1710 Keypad Minus Subtraction on the numeric keypad
1711 Keypad Dot Decimal separator, dot or comma, on the keypad
1712 Insert The insert key between main keyboard and numeric pad
1714 Delete The delete key in the same group
1715 Home The home key
1716 End The end key
1717 Scroll Up The page up key
1718 Scroll Down The page down key
1719 ANALOGJOYSTICK Options
1722 Unlike the JOYSTICK Options, the following set of options describes the
1723 mapping of a true analog joystick connected to one of the joystick
1724 device drivers to the abstract input device that forms the basis for
1725 either joystick, paddle or lightpen input. Hence, it defines the layout
1726 of the AnalogJoystick devices that can be connected to the above emula‐
1727 tion components.
1728 Similar to most above options, the following options exist several
1730 times with the digit 0 replaced by the unit of the corresponding
1731 device. Hence, the analog PC joystick controlled by /dev/js1 is setup
1732 by options similar to those above with a 1 replacing the 0.
1733 -first_button 1..16
1735 Defines which button of the physical joystick shall map to the
1736 button zero of the abstract input device. The default is to con‐
1737 nect the first button of the physical joystick to the first but‐
1738 ton, i.e. button zero, of the abstract device. This defaults to
1739 button #1 of the real device. If used in conjunction with the
1740 5200 keypad device, i.e. the “KeyButton.0.Button” and related
1741 options, the button index #1 used in the keyboard configuration
1742 refers to the button addressed by this option, and not directly
1743 to a hardware button. Thus, keypad buttons are routed twices: In
1744 a first stage, but the hardware abstraction layer defined by
1745 this option, and a second time by the keyboard device picking
1746 one of the four abstract buttons the hardware abstraction layer
1747 offers.
1748 -second_button 1..16
1750 Similar to the above, this defines the real button that shall be
1751 connected to the emulated second button of the emulated device.
1752 -third_button 1..16
1754 Again, this routes one of the hardware buttons to a virtual but‐
1755 ton of the hardware interface layer. Since the Atari hardware is
1756 only capable of supporting at most two buttons, namely for the
1757 paddles, the third and fourth button are only usable for the
1758 5200 keypad emulation, see the keyboard configuration chapter
1759 for details.
1760 -fourth_button 1..16
1762 The input line of the fourth button an abstract joystick device
1763 might support. Only usable from the keypad emulation.
1764 -haxis.0 xaxis.1|yaxis.1|xaxis.2|yaxis.2
1766 Specifies the axis of the physical joystick that should emulate
1767 the horizontal axis of the abstract analog joystick device. The
1768 default is the first horizontal axis of the physical joystick.
1769 -vaxis.0 xaxis.1|yaxis.1|xaxis.2|yaxis.2
1771 Similar to the above for the vertical axis of the abstract
1772 device. The default is, of course, the first vertical axis.
1773 SDLANALOG Options
1776 This is a modified AnalogJoystick interface that reads joystick posi‐
1777 tions thru the SDL library instead using the kernel interface directly.
1778 Its configuration options are identical to that of the AnalogJoystick
1779 interface and are hence not described here again.
1780 DIGITALJOYSTICK Options
1783 The next set of options is used to setup the digital joystick input and
1784 the “El Cheapo” Joystick input adapter that can be used to connect a
1785 true Atari digital joystick to the analog gameport input of the PC.
1786 This option set also exists several times, once for each available
1787 gameport detected in the host system. Once again, replace the digit 0
1788 by the unit number of the corresponding device the joystick is con‐
1789 nected to.
1790 -upbutton.0 Button.1|Button.2|Button.3|Button.3
1792 Defines which of the four joystick buttons on the analog game‐
1793 port acts as the input for the upwards movement line. The
1794 default is button three.
1795 -downbutton.0 Button.1|Button.2|Button.3|Button.3
1797 Similar to the above for the downwards movement. The default is
1798 button one.
1799 -leftbutton.0 Button.1|Button.2|Button.3|Button.3
1801 Selects the button that acts as the left movement input. This
1802 defaults to button four.
1803 -rightbutton.0 Button.1|Button.2|Button.3|Button.3
1805 Selects the button for right movement input. The default is but‐
1806 ton two.
1807 -triggeraxis.0 XAxis.1|YAxis.1|XAxis.2|YAxis.2
1809 Selects the analog gameport axis that reads the digital joystick
1810 button input. The default is that the digital fire button is
1811 connected to the first horizontal axis.
1812 -triggerthres.0 -32768..32768
1814 Since the digital button is read by the game port as an analog
1815 input, the digital signal arrives as a numerical value between
1816 -32768 and 32767 at the digital joystick device of the emulator.
1817 The above option sets the threshold by which the button is read
1818 as pressed resp. released. The precise values depend of course
1819 on the resistance network that is connected to the analog game‐
1820 port line, but the default for 16384 works fine for the author's
1821 hand-soldered adaptor.
1822 -inverttrigger.0 bool
1824 With this switch, the fire button input line reading can be
1825 inverted, i.e. active inputs are read as released fire buttons
1826 and vice versa. This shouldn't be necessary with the author's
1827 interface. The default is hence off.
1828 SDLDIGITAL Options
1830 This is just a slightly modified DigitalJoystick interface that con‐
1831 nects to SDL instead to the kernel interface. All its options are iden‐
1832 tical, please refer to the above list for details.
1833 OSSHQSOUND Options
1836 In the following, we give a set of options to control the generation of
1837 audio thru the OSSHQ driver, making use of the Open Sound System kernel
1838 interface or an equivalent emulation, e.g. by ALSA. Rather than the
1839 POKEY Options, these options concern the quality of the samples gener‐
1840 ated by the POKEY emulation and its built-up for OSS. For audio output
1841 to work properly, you need to have an Open Sound System compatible
1842 audio driver available, and you need to have permission to access the
1843 /dev/dsp device.
1844 Note that generating audio samples with high quality has a non-
1846 neglectable impact on the CPU load. If your machine has problems keep‐
1847 ing up with the natural framerate, or if the CPU load is too high, try
1848 to lower these settings, use a different audio front-end, or disable
1849 sound output alltogether.
1850 -enablesound bool
1852 Enables or disables the generation of audio output. The default
1853 is the enable the audio generation, unless no audio output
1854 device is available which then disables audio output.
1855 -enableconsolespeaker bool
1857 Enables or disables the emulation of the Atari console speaker.
1858 The Atari Os generates keyboard click sounds and the buzzer by
1859 means of this speaker. Some games also use the console speaker
1860 for speech output.
1861 -consolespeakervolume 0..64
1863 Sets the output volume of the console speaker. Setting this to
1864 zero effectively disables the output, and setting this to a
1865 value higher than 32 may cause distortion with regular POKEY
1866 audio output. This option ranges from zero to no up to 64 for
1867 maximal volume with the default being 32.
1868 -audiodevice filename
1870 Specifies the name of the audio device to send the samples to.
1871 This device must accept all Oss specific ioct() settings. It
1872 defaults, naturally, to /dev/dsp.
1873 -samplefreq 4000..48000
1875 The sampling frequency in Hz by which samples should be gener‐
1876 ated, and hence the limiting frequency for the audio signals.
1877 The higher this value is, the higher are the possible frequen‐
1878 cies that can be emulated, and the more natural the sound plays.
1879 Frequencies higher than 16000 are required for software speech
1880 output, but otherwise a frequency limit of 8000 Hz is enough for
1881 all other sound effects. The default is 44.1kHz, the CD replay
1882 frequency.
1883 -fragsize 2..16
1885 This is a technical setting that allows to specify the size of
1886 an audio buffer fragment. These fragments get filled sample by
1887 sample and are transmitted to the replay hardware as soon as
1888 they are full and the hardware is capable of playing another
1889 sample. If they are too small, the buffer has to be refilled too
1890 often and you might hear drop-outs since the computation cannot
1891 keep up with the audio replay. If they are too long, the audio
1892 latency becomes too high and the sound is no longer synchronized
1893 with the video out. This option does, however, not specify the
1894 fragment size itself, but rather the exponent to the base of
1895 two, i.e the true fragment size will be two to the power of this
1896 exponent. The default for this option is 8, i.e. a fragment size
1897 of 256 bytes. You'd rarely need to play with this setting.
1898 -numfrags 6..256
1900 The number of buffers, each of the size given by the above argu‐
1901 ment, to be used for audio sample generation. More buffers
1902 reduce the likelyhood of drop-outs, but increase the latency.
1903 The default are 16 buffers, more is rarely useful.
1904 -forcestereo bool
1906 Enforces to generate stereo samples even though mono output is
1907 available for the sound chip. Some broken sound implementations,
1908 notably ALSA on the Emu10K1 chipset require this to work cor‐
1909 rectly under all configuations.
1910 OSSSOUND Options
1913 The Oss driver is a less complex frontend for the Open Sound System
1914 audio interface, though it requires a very precise implementation of
1915 it. Some emulations, e.g. ALSA might not be suitable for this fron‐
1916 tend, and it rarely provides better quality than HQOss. Since it pro‐
1917 vides quite similar options as well, we only describe most of them
1918 roughly and refer to the HQOss frontend for further details.
1919 -enablesound bool
1922 Enables or disables the generation of audio output.
1923 -enableconsolespeaker bool
1925 Enables or disables the emulation of the Atari console speaker.
1926 -consolespeakervolume 0..64
1928 Sets the output volume of the console speaker.
1929 -audiodevice filename
1931 Specifies the name of the audio device to send the samples to;
1932 this is typically /dev/dsp.
1933 -samplefreq 4000..48000
1935 The sampling frequency in Hz for the audio output.
1936 -refillfreq 20..48000
1938 The frequency in Hz by which the audio samples are recomputed by
1939 the emulator. If this is set to a relatively low value, but the
1940 sampling frequency is high, then quite a lot of samples are com‐
1941 puted in one go, but the updating period by which these samples
1942 are matched to the true POKEY output is rather low. This refill
1943 frequency must be lower than the sampling frequency above. For
1944 software speech generation, a refill frequency of 15700 proved
1945 most effective. For regular sound output, this frequency can be
1946 much lower. Note that for software speech output, the audio ker‐
1947 nel interface must meet the specifications of the Open Sound
1948 System architecture precisely. Some emulations, e.g. ALSA fail
1949 here. Try to use the HQOss frontend in this case; in most cases,
1950 it is capable of providing better quality anyhow.
1951 -fragsize 2..16
1953 The exponent for the base of two giving the size of an audio
1954 buffer fragment in bytes. This is similar to the fragment size
1955 of the HQOss frontend and is discussed in more detail above.
1956 -numfrags 1..256
1958 The number of buffers to be used for audio sample generation.
1959 For two buffers, this means that audio output is double-
1960 buffered. More than four buffers are rarely useful for this
1961 driver, making this the default.
1962 -forcestereo bool
1964 Enforces to generate stereo samples even though mono output is
1965 available for the sound chip. Some broken sound implementations,
1966 notably ALSA on the Emu10K1 chipset require this to work cor‐
1967 rectly under all configuations.
1968 WAV Options
1972 The WAV frontend is the alterantive audio output module that rather
1973 records the generated sound than to play it; or at least, this is its
1974 main intention: WAV also offers playback of the recorded sound, though
1975 due to timing restrictions the quality of this sound is - sometimes
1976 noticably - worse than that of the Oss or HQOss module and the sound
1977 that got recorded in the final .wav file. As said, the quality of the
1978 output file will be perfect.
1979 -enablerecording bool
1982 Enables or disables the recording to the wav output file. If
1983 enabled, the emulator starts recording as soon as the emulated
1984 machine starts running, though the recorded file is disposed and
1985 re-written from scratch on a cold-reset, e.g. generated by the
1986 F7 key. To record game music, you'd best first enable the
1987 recording, then start the game, let the music play and interrupt
1988 the music by entering the configuration menu with the F1 short‐
1989 cut. Then turn off recording. This will leave the recorded file
1990 intact.
1991 -enableplayback bool
1993 Enables or disables the playback of the recorded data. If this
1994 option is enabled, the WAV frontend will also play the music
1995 over an OSS compatible sound driver. It is typically a good idea
1996 to enable this option as well whenever it is available, i.e.
1997 whenever an OSS sound driver is in the system. Note, though,
1998 that the quality of the sound output might be of noticably worse
1999 quality than that of the recorded sound within the output file.
2000 -enableconsolespeaker bool
2002 Similar to the option of the same name for the OSS sound front-
2003 end, this option enables or disables the generation of sound
2004 thru the console speaker. It is typically used for the keyboard-
2005 clicks and the buzzer-sound.
2006 -consolespeakervolume 0..64
2008 Sets the volume of the console speaker if enabled. This option
2009 defaults to 32.
2010 -outputfile filespec
2012 Defines the full path of the .wav output file to record the
2013 sound in. If this option is not given, then this file name
2014 defaults to “out.wav”.
2015 -audiodevice device
2017 Sets the name of the OSS sound device. This is typically
2018 “/dev/dsp”, which is also the default setting for this option.
2019 -samplefreq 4000..48000
2021 Sets the sampling frequency in Hz for the recorded .wav file,
2022 and by that also the sampling frequency of the played-back audio
2023 output. The smaller, the less CPU power is required and the
2024 shorter the output file becomes for recording the same timespan
2025 of music, but the worse the quality gets. This option defaults
2026 to 15700 Hz which is the best compromise between quality and
2027 data size. Much higher frequencies make little sense and do not
2028 improve quality noticably.
2029 -fragsize 2..16
2031 sets similar to the OSS front-end option of the same name the
2032 exponent for the size of the fragment for audio playback. It has
2033 no influence whatsoever on the output file whatsoever, but
2034 rather modifies the behaivour of audio playback only.
2035 -numfrags 1..256
2037 sets the number of audio fragments (buffers) for audio playback,
2038 similar to the option of the same name of the OSS front-end. It
2039 has no influence on the recorded samples.
2040 SDLSound Options
2043 The next audio front-end is generation thru the Standard Direct Media
2044 Library, or short SDL, all provided you have an SDL library and the
2045 required development files installed on your host. The quality of the
2046 SDL output is close to that of the HQOss frontend, though due to the
2047 different driver architecture, it is unfortunately more likely for the
2048 SDL driver to generate drop-outs. It furthermore requires longer frag‐
2049 ments and has therefore a higher latency, but it is very portable as
2050 SDL exists on a variety of platforms.
2051 -enablesound bool
2054 enables or disables the sound generation thru SDL, similar to
2055 the same option for the OSS and WAV audio front-ends.
2056 -enableconsolespeaker bool
2058 will toggle the console speaker emulation on or off. The emula‐
2059 tion is enabled by default.
2060 -consolespeakervolume 0..64
2062 adjusts the volume of the console speaker. This setting defaults
2063 to a medium volume of 32.
2064 -samplefreq 4000..48000
2066 adjusts the sampling frequency for the audio generation in Hz =
2067 samples per second. Higher sampling frequencies provide closer
2068 sound output emulation, but also enlarge the CPU load on the
2069 system. The sampling frequency defaults to 44100Hz, i.e. CD
2070 quality. You might have to lower this setting on weaker systems.
2071 -fragsize 2..16
2073 selects the size of an audio output buffer as the exponent for
2074 the base of two. The smaller the fragment size, the more often
2075 the audio output will get updated to reflect the audio register
2076 setting of the POKEY chip, and the more natural audio output
2077 will become. If the fragment size is too small, then audio out‐
2078 put will degrate quickly, though, as the emulation will then no
2079 longer be able to refill the output buffers in time. The optimal
2080 setting for this value is around nine, which is also the
2081 default.
2082 -forcestereo bool
2084 Enforces to generate stereo samples even though mono output is
2085 available for the sound chip. Some broken sound implementations,
2086 notably ALSA on the Emu10K1 chipset require this to work cor‐
2087 rectly under all configuations.
2088 DirectX Sound Options
2092 This audio front-end is only available for win32 compatible platforms
2093 and requires at least DirectX 8.0 installed on the host machine. It
2094 offers the highest audio quality available under the win32 operating
2095 system at minimal latency.
2096 The following options are available for DIRECTX sound:
2098 -enablesound bool
2101 enables or disables audio output. It is enabled by default.
2102 -enableconsolespeaker bool
2105 turns emulation of the console speaker on or off. This speaker
2106 generates the keyboard click and buzzer sounds, but is otherwise
2107 not very frequently used; it is enabled by default.
2108 -consolespeakervolume 0..64
2111 controls the volume of the console speaker. The default setting
2112 is 32, though higher volumes are not recommended as they will
2113 cause distortion when mixing them with the regular POKEY output.
2114 -samplefreq 4000..48000
2117 selects the sampling frequency in samples per second. The
2118 default is 22050 Hz, i.e. half the frequency of an audio CD.
2119 Higher frequencies are not recommended for DirectX as the CPU
2120 load gets very high otherwise.
2121 -fragsize 2..12
2124 sets the size of one audio buffer, also called a “fragment” by
2125 defining its exponent to the base of two. Thus, increasing this
2126 setting by one doubles the size of one audio buffer, a setting
2127 of eight causes buffers that are 2^8 = 256 samples long. This is
2128 also the default buffer setting and a good compromize between
2129 latency and quality for fast, up-to-date hardware. Slower sys‐
2130 tems might require higher values; in case you hear audio drop-
2131 outs, increase this value.
2132 -numfrags 6..16
2135 defines the number of audio buffers of the above size to be
2136 allocated. A higher number will allocate more buffers, causing
2137 higher latency, but also lowering the probability of drop-outs.
2138 The default are six buffers, but this number should be increased
2139 in case the audio output isn't smooth.
2140 ALSASound Options
2143 The last available audio front-end uses the ALSA sound drivers avail‐
2144 able on Linux and the asoundlib API. Both, and their development files
2145 must be available at compile time to provide this interface.
2146 If available, ALSA provides a high quality sound similar to the HQOSS
2148 frontend, though its demands concerning the CPU power are very moderate
2149 and lower than that of other frontends.
2150 The following options are available for ALSA:
2152 -enablesound bool
2155 enables or disables the sound output. This defaults to on.
2156 -enableconsolespeaker bool
2159 controls emulation of the console speaker; this option is turned
2160 on by default.
2161 -consolespeakervolumne 0..64
2164 selects the volume of the console speaker. It is set to 32 by
2165 default; higher volumes might cause distortion in the sound out‐
2166 put.
2167 -audiocard name
2170 selects the audio hardware ALSA shall sent the samples to. This
2171 is not a device specification in the sense of a path name. It
2172 defaults to “hw:0,0” which addresses the first available audio
2173 hardware that is handled by ALSA. Further audio cards are named
2174 “hw:1,0” and so on. Even though Atari++ supports a wide range of
2175 sampling formats natively, some exotic cards might require the
2176 help by ALSA. To enable this additional software support, sub‐
2177 stitute “hw” by “plughw”, e.g. specify “plughw:1,0” as device
2178 name. This enables an additional software conversion inside
2179 ALSA.
2180 -samplefreq 4000..48000
2183 selects the sampling frequency in samples per second. The
2184 default is 44100 Hz, i.e. CD quality.
2185 -fragsize 2..16
2188 defines the size of an audio buffer fragment as the exponent to
2189 the base of two. This works very similar to all other audio
2190 frontends and is not explained here again. ALSA allows a rela‐
2191 tively small default of 8 here, meaning fragments of 2^8 = 256
2192 bytes.
2193 -numfrags 6..256
2196 defines the size of the audio buffer in fragments. The more
2197 fragments, the lower the probability of drop-outs but the higher
2198 the latency. The number of fragments defaults to 12.
2199 -forcestereo bool
2202 Enforces to generate stereo samples even though mono output is
2203 available for the sound chip. Some broken sound implementations,
2204 notably ALSA on the Emu10K1 chipset, may require this to work
2205 correctly under all configuations.
2206 X11 Options
2210 The next set of options controls the X11 graphical frontend of the
2211 Atari++ emulator, all provided it has been selected with the -frontend
2212 X11 option. Otherwise, the control options of the selected frontend
2213 apply instead.
2214 -privatecmap bool
2216 If set to on, then Atari++ will emulate its own color map for
2217 the emulation window output. This is only required if you run it
2218 on a 8 bit display and the emulator further complains that it
2219 couldn't allocate enough free pens. The downside of this option
2220 is that the colors will get wrong as soon as the mouse pointer
2221 leaves the emulator window on an 8 bpp display, but at least you
2222 get a display with proper colors otherwise.
2223 This option is not at all useful for 16 bpp or any other true-
2225 color displays as the color mapping will be correct all the time
2226 otherwise. Therefore, the default for this option is off.
2227 -syncx bool
2229 A boolean flag that describes whether the X11 frontend shall try
2230 to keep the display output in sync with the emulator. If set to
2231 off, all rendering operations will be asynchronous, possibly
2232 causing some lag between the gameplay and the display. The down‐
2233 side of enforcing synchronous graphic renderning by setting this
2234 to on is that the display refresh must wait for the X server to
2235 perform the refresh and to notify the client about it, adding
2236 the turn-around times and the net transfer overhead to the dis‐
2237 play refresh time. It is therefore rarely a good idea to enable
2238 this option.
2239 -disableDPMS
2241 disables the display management power signal extension and thus
2242 prevents the monitor blanker or screen safer of the operating
2243 system to jump in while playing with the emulator. It is usually
2244 a good idea to enable this option.
2245 -xvideorendering bool
2247 will use the “XVideo” extension of the X11 system to render
2248 graphics on the screen. Unlike the default rendering mode which
2249 builts the image from many colored rectangles, this render mode
2250 writes the raw display data into a shared memory region which is
2251 then scaled and pushed to the screen directly by the video over‐
2252 lay mechanism of the graphics card when available. Depending on
2253 the graphics hardware, this option may provide better perfor‐
2254 mance on lower end hardware.
2255 -renderindirect bool
2257 If set to on, then all rendering happens indirectly to an off-
2258 screen pixmap in a first step, then blitting the pixmap in a
2259 second step back to the screen. This has the downside of being
2260 slower by requiring an additional transfer step, but it makes
2261 the display refresh smoother as well as the rendering operation
2262 itself remains invisible. Since it makes emulation slower, this
2263 option remains off by default.
2264 -screenbase filename
2266 Selects a filename base for the screen dumps. If a screendump is
2267 requested, a counter and a file type extender is appended to
2268 this name and the screen contents are saved to this file. Cur‐
2269 rently, screen dumps are saved in the Portable Pixmap (ppm) For‐
2270 mat that is readable by most Linux/Unix tools, e.g. by xv and
2271 gimp. The default filename is “ScreenDump”.
2272 -dumpformat PNM|BMP|PNG
2274 Specifies the file format to be used for screen dumps. PNM is
2275 the simplistic *nix specific PNM/PPM true color dump file format
2276 that is understood by most *nix programs. BMP is the Windows
2277 Bitmap format, a very popular but rather aged image file format
2278 of the Win world. PNG is the “Portable Network Graphics” file
2279 format, an image format driven forward by the Open Source commu‐
2280 nity. This file format requires the availibility of the LibPNG.
2281 -pixelwidth 1..8
2284 This option spezifies the magnification degree in horizontal
2285 direction by which the pixels of the emulated scren are rendered
2286 to the X11 display. The default of the pixelsize option is 2,
2287 i.e. a single pixel of the Atari display is rendered twice as
2288 large on the X window showing the emulation. Depending on the
2289 hardware driver of your graphics board, enlarging the pixelsize
2290 might be almost for free with the X11 frontend.
2291 -pixelheight 1..8
2293 This option controls the magnification of the pixel size in ver‐
2294 tical direction, similar to the above option the default value
2295 is 2.
2296 -leftedge 0..64
2299 Sets the horizontal position of the first Atari pixel that gets
2300 displayed within the X11 window. The pixels left to this pixel
2301 are not made visible. This option is useful either to align the
2302 size of the X window to the natural size of the screen the win‐
2303 dow is contained in, to hide the leftmost pixel junk caused by
2304 the horizontal ANTIC scrolling, or to remove the hardware border
2305 of the window, similar to the operation performed by some TVs.
2306 This option defaults to 16, just enough to make the HSCROLL
2307 artefacts invisible.
2308 -topedge 0..64
2310 Sets the first row of the ANTIC display to render to the X11
2311 window. This is otherwise identical to the -leftedge option
2312 except that it works in vertical direction. The default of this
2313 option is zero.
2314 -width 320..480
2316 Sets the total amount of pixels to render into the screen and
2317 hence the inner dimension of the X window. Reducing this width
2318 can be either useful to fit this window into the screen, or to
2319 avoid some pixel junk at the right edge of the ANTIC display.
2320 The default width is 352 pixels.
2321 -height 192..248
2323 Sets the height of the window in emulated pixels. Since the low‐
2324 est lines are always left blank anyhow, they need not to be ren‐
2325 dered. Therefore, this option defaults to 240.
2326 SDL Options
2329 The next option set controls the layout of the alternate emulator fron‐
2330 tend driven by the Simple Direct Media Library, or short, SDL. This
2331 library allows fullscreen output, though its overall performance is
2332 lower as soon as it requires to upscale the pixels. The SDL frontend is
2333 activated by the -frontend SDL switch, and only then the following
2334 options apply:
2335 -leftedge 0..64
2337 Similar to the X11 Option of the same name, this selects the
2338 first visible emulator pixel on the SDL screen. This option
2339 defaults to 16.
2340 -topedge 0..64
2342 Specifies the first visible row on the screen. The default is to
2343 start the display at row 0.
2344 -width 320..480
2346 The width in emulator pixels of the screen to render. The
2347 default is 352.
2348 -height 192..248
2350 The height of the emulated display. The default is to drop some
2351 lines at the bottom end since they are always blank anyhow: 240
2352 lines are rendered by default.
2353 -pixelwidth 1..8
2355 Set the width of one emulator pixel in SDL pixels. The default
2356 is that one emulator pixel is represented by one pixel on the
2357 SDL screen. Setting this to values larger than two easely
2358 degrades the emulator performance.
2359 -pixelheight 1..8
2361 Set the height of one emulator pixel in SDL pixels. As already
2362 said above, the default is one. Pixel heights larger than two
2363 typically slow down the emulator too much to be useful.
2364 -screenbase filename
2366 Defines a base file name similar to the X11 screenbase option
2367 for screen dumps. The filename of the screen dump is, as above,
2368 formed by a counting number and the extender of the file format.
2369 Currently, screen snapshots are saved as PPM images.
2370 -doublebuffer bool
2372 enables double buffering, provided the implementation of SDL on
2373 the host system implements it. Double buffering allows smoother
2374 scrolling at the price of a slightly higher CPU load. At the
2375 time of writing, only the win32 version of SDL provides double
2376 buffering, the Linux version does not. Thus, enabling this
2377 option under Linux does nothing. However, the renderindirect
2378 option of the X11 front-end does something very similar.
2379 -fullscreen bool
2381 Enables or disables full screen display. The default is to use
2382 the full screen display, and it is recommended to use the X11
2383 frontend otherwise as it provides higher performance in this
2384 case.
2385 -dumpformat PNM|BMP|PNG
2387 Specifies the file format to be used for screen dumps. PNM is
2388 the simplistic *nix specific PNM/PPM true color dump file format
2389 that is understood by most *nix programs. BMP is the Windows
2390 Bitmap format, a very popular but rather aged image file format
2391 of the Win32 world. PNG is the “Portable Network Graphics” file
2392 format, an image format driven forward by the Open Source commu‐
2393 nity. This file format requires the availibility of the LibPNG.
2394 -shieldcursor bool
2396 Enables a workaround against an SDL bug that allows a program to
2397 overdraw the active mouse pointer, trashing its backing store
2398 and leaving invalid graphics behind the pointer if it is moved
2399 away. This workaround will remove the cursor prior the drawing
2400 operation to avoid the problem, at the cost of a possibly flick‐
2401 ering pointer.
2402 -deblocker bool
2404 Enables a deblocking filter that creates rounder and smoother
2405 graphics for pixel sizes between two and three. This avoids to
2406 some degree the blocky-ness of the emulated display that is
2407 caused by the higher and finer resolution of the PC monitor com‐
2408 pared to the TV output the Atari hardware was designed for.
2409 850INTERFACE Options
2412 The Atari++ contains a complete emulation of the 850 serial interface
2413 box, including a boot-able R: handler that would be usually included in
2414 the ROM of the interface box. The emulation allows you to use the
2415 serial port of the host system as a serial output port of the 850
2416 interface, allowing you to connect a modem to the emulated Atari. The
2417 emulation has only two limitations: For first, it cannot provide some
2418 of the exotic baud rates the 850 box is able to generate, and it pro‐
2419 vides only a single serial port, not four of them. On the other hand,
2420 it offers a true hardware handshake, unlike the Atari 850. For more
2421 information about the emulator provided R: handler, see below.
2422 The following options configure the 850 emulation:
2424 -enable850 bool
2426 Enables or disables the 850 interface. If disabled, the inter‐
2427 face box will not react on any SIO commands and will hence pre‐
2428 tend to be turned off.
2429 -serialname path
2431 Specifies the device name for the serial port the emulated 850
2432 interface shall use as its output port. The default device name
2433 is “/dev/ttyS0”, i.e. the first serial output port of the sys‐
2434 tem.
2435
2438 Atari++ is not only controlled by its huge amount of command line
2439 parameters. It is also adjustable by configuration files. These config‐
2440 uration files contain the very same options than the command line
2441 parameters, except that there is only one option per line, an equals =
2442 sign separates option from value, and the minus-sign in front of the
2443 option is missing. Additionally, empty lines and comments starting with
2444 the hash-mark # are allowed. The following example shows a typical con‐
2445 figuration file:
2446 #
2448 # This is the config file for the atari++ emulator
2449 #
2450 HoldOption = true
2451 Artefacts = off
2452 Enable.1 = on
2453 Protect.1 = on
2454 SIOPatch = on
2455 InstallPDevice = on
2456 SampleFreq = 44100
2457 RefillFreq = 15700
2458 NumFrags = 4
2459 Joystick.0.Port = DigitalJoystick.0
2460 The Atari++ emulator knows three configuration files: The system spe‐
2462 cific configuration file, residing at /etc/atari++/atari++.conf, the
2463 per-user specific configuration file at ~/.atari++.conf and the per-
2464 directory configuration file at ./.atari++.conf. Each later configura‐
2465 tion file overloads the defaults of the former, and the command line
2466 arguments finally overload all of them. This way, the least frequently
2467 adjusted options should go into the configuration file in the home
2468 directory, with system specific settings in /etc.
2469
2471 The Atari++ emulator uses the following keymap:
2472 F1 This key enters the graphical configuration menu. The usage of
2474 this menu should be quite obvious as all the options are named
2475 as in this manual and sorted under the same topics. The menu is
2476 left by the topmost Prefs topic which also allows loading and
2477 saving the settings and entering the monitor. The F1 key changes
2478 its meaning for the CURSES front-end, where no full menu is
2479 available. Here, it replaces the Atari resp. inverse-video key.
2480 F2 is mapped to the Option console key.
2482 F3 is mapped to the Select console key.
2484 F4 is mapped to the Start console key.
2486 F5 is the Help key that is otherwise only available on the XL and
2488 XE hardware.
2489 F6 is the Reset console key. Its function differs a bit amongst
2491 various models. For the Atari 800 and 400, this key just signals
2492 a special NMI interrupt at ANTIC, and the Os resets the system
2493 manually. For the XL and XE, this signal is really connected to
2494 the CPU reset line. Atari++ emulates this behaivour.
2495 F7 coldstarts the system as if it has been turned off and on again.
2497 Hence, unlike F6, this is a true coldstart and not a warmstart.
2498 F8 emulates the Break key, used to stop listings and BASIC pro‐
2500 grams.
2501 F9 requests a screen dump. Where this screendump goes is a matter
2503 of the -screenbase command line option.
2504 F10 aborts the emulator immediately, similar to closing the window.
2506 F11 and Pause
2508 pauses the emulator. Pressing F11 again continues the emulation.
2509 F12 enters the on-line monitor that is described below.
2511 Home/Clear
2513 emulate the Shift+< sequence, enforcing a clear screen.
2514 Insert inserts a blank character under the cursor by emulating Ctrl+>.
2516 If pressed together with shift, a blank line is inserted at the
2517 current line position.
2518 Del removes a single character under the cursor by emulating a
2520 Ctrl+BS keyboard sequence.
2521 Cursor Keys
2523 move the cursor in the indicating direction by holding either
2524 +,*,-,= and the Ctrl key down. This works fine most the time
2525 except for the DDT debugger which requires these keys pressed
2526 without Ctrl for window movement. Do not use the separate cursor
2527 keys but the above keys directly for DDT.
2528 Esc emulates, as expected, the ESC key on the Atari keypad.
2530 Keypad keys 7,8,9,4,5,6,1,2,3
2532 are part of the “keypadstick.0” device and a possible emulation
2533 source for joystick input; they are also configurable, see the
2534 KeypadStick section.
2535 Keypad keys 0 and Enter
2538 emulate the joystick button of the device as well.
2539 ALT emulates the Atari or InverseVideo key. For some implementa‐
2541 tions, this key is also emulated by the Windows key.
2542 All other keys have their natural key binding except for the
2544 5200 game console which is explained below. This binding is
2545 given by the current keyboard layout; this means especially that
2546 the keyboard layout is language specific and does not neces‐
2547 sarely match the layout of the Atari keyboard. E.g. for a german
2548 keyboard, the keys for “y” and “z” work as printed on the PC
2549 keyboard, and not as for the (american) Atari keyboard layout. I
2550 currently consider this as an advantage.
2551 KEYBOARD INPUT FOR THE 5200
2554 Keyboard input on the 5200 game system is considerably different as
2555 this console does not have a keyboard, but a small numberic pad on each
2556 of its controllers. This pad consists of the numbers zero to nine, the
2557 asterisk “*”, the hash-mark “#” and the buttons labelled “Start”,
2558 “Pause” and “Reset”. Furthermore, the joysticks have two buttons
2559 instead of one, and are actually analog joysticks using the paddle
2560 input lines, see above. The current emulator uses the PC keyboard for
2561 all additional keys and does currently not distinguish between the var‐
2562 ious keypads. A button pressed on the PC keyboard will be read as com‐
2563 ing from all game controllers at once. A future version of atari++ may
2564 possibly use a different scheme.
2565 The following keyboard keys act differently on the 5200 system:
2567 F2 is the “Reset” key on the keypad of the controller. This key is
2570 in no way any kind of hardware reset and is dissimilar to the
2571 “real” hardware reset which is still triggered by F6. Instead,
2572 this key is just an ordinary key that must be read by the loaded
2573 game, typically bringing you back to the setup screen.
2574 F3 is the “Pause” key on the keypad. This is also a purely software
2576 driven feature the game may or may not support.
2577 F4 is the “Start” key; it typically launches the game.
2579 keys 0..9
2581 activate the corresponding keypad keys.
2582 H or # emulates the hash-mark on the keypad controller key. Since the
2584 hashmark is not available on all native PC keyboards, the H is
2585 available as an replacement.
2586 S or * emulates the asterisk on the controller keypad. Similarly, the S
2588 is a suitable emulation for native keyboards with a hard-to-
2589 reach asterisk key.
2590 Shift acts as the second trigger button on all external controller
2592 keypads.
2593 F2 thru F12
2595 act as usual, see the list above.
2596 all other keys
2598 are blind and perform no operation in the 5200 emulation mode.
2599
2602 The keyboard input of the CURSES (terminal) front-end is rather limited
2603 because the emulator has considerably less control over the keyboard
2604 than under the graphical front-ends. Note that this emulation replaces
2605 the complete front-end of the emulator, it is not fit to script it,
2606 e.g. feed input to it from a file. For that, better replace operating
2607 system editor functions and use the InstallEDevice function.
2608 In the curses front-end, most keys work as expected, with some limita‐
2610 tions:
2611 F1 does not provide a full menu, which is not available due to lack
2613 of graphics output. Instead, the machine must be configured man‐
2614 ually from the command line or the configuration files. The F1
2615 key rather maps to the Atari or InverseVideo key as the state of
2616 the ALT key is not directly accessible from the CURSES inter‐
2617 face.
2618 CAPS is not directly available because the CapsLock key is read by
2621 the host operating system and is not forwarded to the emulation.
2622 Instead, the emulator sends a CAPS key event after each reset,
2623 triggering the system to low-caps, which is the default under
2624 most host operating systems, and then setting the Shift key of
2625 the emulated machine according to the case of the inserted char‐
2626 acter. This makes CAPS “appear” to work right for most situa‐
2627 tions, unless a program fiddles with the operating system and
2628 alters the CAPS state manually, or performs a software-driven
2629 reset. In this case, the ASCII TILDE that is “ ~ ” will emulate
2630 a press on the CAPS key of the host.
2631 Requesters and Menus
2634 Requesters and error messages will be emulated on the console by
2635 text-driven menus, allowing you to select a choice by typing the
2636 indicated character.
2637 Graphics Output
2640 The graphics emulation is limited to text based ANTIC modes,
2641 limited to the standard character set. Some of the text graphics
2642 can be emulated, ASCII-Art might work to a limited degree, but
2643 bitmap graphics output will not appear on the console. Some lim‐
2644 ited support for horizontal scrolling is available, though.
2645
2648 The atari++ allows you to make a snapshot of the complete machine state
2649 anytime within a game, to save this state to a file and to restart the
2650 game later on from this position. This is not only useful to interrupt
2651 a game temporarely - maybe because you've better things to do in the
2652 mean time - it also helps to try hard game puzzles several times.
2653 To create a snapshot file, enter the menu by pressing the F1 key on
2655 your keyboard, pick the Prefs item on the left hand side list and enter
2656 the name of the state file into the bottommost gadget labelled “Save
2657 State To”.
2658 To restore a machine state, i.e. to load the snapshot file, use the
2660 gadget “Load State From” right on top of it, or the command line option
2661 -state filename expecting the name of your snapshot file.
2662 It is important to understand that the snapshot file contains only the
2664 part of the inner machine state that is not covered by the configura‐
2665 tion file. For example, the snapshot file will NOT contain the cur‐
2666 rently active ROM image as this image is already sufficiently specified
2667 by the configuration. Hence, if your configuration at the time you made
2668 the snapshot differs from your default configuration, you should also
2669 save that configuration, and load it along with the snapshot. Snapshot
2670 files extend configuration files, they are not independent from the
2671 emulator configuration.
2672
2675 The emulator provides an optional interface from the emulated Atari to
2676 the host environment by the H: handler that makes parts of the filing
2677 system of the host visible within the emulation. To make use of this
2678 handler, it has to be enabled by the -InstallHDevice on command line
2679 option or a similar option within the configuration files. This option
2680 will replace the C: cassette interface - which is rarely, if ever, use‐
2681 ful - by the host interface filehandler. This handler provides four
2682 units, named H1: to H4: opening four directories of the host system
2683 within the emulator. These directories are configured by the -H1Dir to
2684 -H4Dir command line options, expecting path name(s) to host system
2685 directories.
2686 FILE NAMES AND PATTERN MATCHING
2689 Similar to the standard file management systems DOS 2.0S and upper, the
2690 H: handler automatically resolves patterns within filenames. The fol‐
2691 lowing wildcards are supported:
2692 * matches a sequence of any, possibly zero, length of any charac‐
2694 ters, quite similar to the bash or the csh.
2695 ? matches one single character.
2697 - Matches any character and ignores the rest of the pattern.
2699 Unlike the standard file management systems, the dot “.” has no
2701 special meaning for the H: device except that file names are
2702 truncated to eigth characters in front and three characters
2703 beyond it. This is a backwards compatibility feature to be able
2704 to run most Atari Os compliant programs on the H: device without
2705 additions.
2706 The handler will furthermore ignore cases when comparing the
2708 requested file name with a file name on the host system. Files
2709 generated by the emulator will use lower case for convenience.
2710 COMMAND SET
2713 The H: handler supports the following IO commands:
2714 CMD 3: OPEN
2716 used by the BASIC OPEN #channel,aux1,aux2,“H:filespec” command.
2717 The aux2 specifier will be ignored, valid aux1 values are:
2718 aux1 function
2721 ─────────────────────────────────────────
2722 4 open for read-only
2723 6 open the directory
2724 7 open the directory
2725 8 create for write-only
2726 9 open for append write-only
2727 12 open for read, write and append
2728 13 create for read, write and append
2729 This follows closely the DOS 2.0S conventions with the addition
2731 that mode 12 is able to write past EOF and mode 13 also creates
2732 files. Mode 7 is an addition that was made for compatibility of
2733 DOS 2.XL by the author.
2734 The filespec follows the file name convention explained in the
2736 previous subsection; the directory listing generated by codes 6
2737 and 7 will be formatted similar to the DOS 2.0S output for the
2738 same request, but the amount of free sectors will always show up
2739 as “999”. This is because there is basically no visual storage
2740 limit for a tiny Atari file system inside a Unix/Linux worksta‐
2741 tion. Files that are not user-writeable appear as “locked” and
2742 are marked with an asterisk in the first column. Similarly, file
2743 locking and unlocking changes the user-writeable protection bit
2744 of the host system.
2745 CMD 5: GET RECORD
2747 Reads characters up to an EOL character, or up to the buffer
2748 end, into a buffer. This is a standard command supplied by all
2749 handlers. This implements the BASIC INPUT #channel,var and
2750 related commands.
2751 CMD 7: GET CHARACTERS
2753 Reads a block of characters into a buffer. This is a standard
2754 command, consult the Atari technical manual for details. Not
2755 reachable from BASIC.
2756 CMD 9: PUT RECORD
2758 Writes characters up to an EOL or up to the end of the buffer
2759 into the opened stream. Also part of the standard command set.
2760 Not reachable from BASIC, but related to the BASIC command PRINT
2761 #channel,data.
2762 CMD 11: PUT CHARACTERS
2764 Writes a block of characters into a stream. A standard command.
2765 Not reachable within BASIC, but related to the BASIC commands
2766 PUT #channel,value and PRINT #channel,data.
2767 CMD 12: CLOSE
2769 Releases the given stream, closes the file on the host system
2770 and frees all buffers. This command is considered harmless on
2771 streams already closed. This implements the BASIC CLOSE #channel
2772 command.
2773 CMD 13: STATUS
2775 Requests the status of the given stream. It returns status code
2776 133 if the channel is not open, status code 1 if the channel
2777 generated no error, status code 3 if you are about to read from
2778 the EOF on the next go, or the last error should the stream be
2779 in an error condition otherwise. This follows standard conven‐
2780 tions.
2781 CMD 32: RENAME
2783 Implements the BASIC XIO 32,#channel,aux1,aux2,“H:oldname,new‐
2784 name” command. Note that the file specification of this command
2785 consists of an existing filename, a comma “,”, and a new file
2786 name. This command attempts to rename the existing file to a new
2787 name.
2788 CMD 33: DELETE
2790 Implements the BASIC XIO 33,#channel,aux1,aux2,“H:filespec” com‐
2791 mand and attempts to remove (delete) the given files or pat‐
2792 terns. It will fail if the files are not user-readable, i.e.
2793 appear “locked” in the emulator.
2794 CMD 34: VALIDATE
2796 An extension following DOS 3 conventions also reachable within
2797 BASIC with XIO 34, this command will check whether the given
2798 filespec is well-formed and will return an error code if not. It
2799 does not attempt to open any file.
2800 CMD 35: UNPROTECT
2802 Implements the XIO 35 command which “unlocks” the given file(s)
2803 and allows write-access into it. The host system reflects this
2804 operation by enabling the user-writeable permission bit.
2805 CMD 36: PROTECT
2807 Implements the BASIC XIO 36 command and “locks“ the filespec by
2808 removing the user write-permission bit.
2809 CMD 37: POINT
2811 Unlike command 32 to 36 above, this expects that the given chan‐
2812 nel is already linked to an open stream. It implements the basic
2813 POINT #ch,sector,byte command for placing the file pointer
2814 within the file. The Os. CIO places the sector offset in AUX4
2815 and AUX5 and the byte offset into AUX3. However, conventions for
2816 file addressing are different from DOS 2.0S and are more orthog‐
2817 onal. The H: handler appears to have sectors of 256 bytes each,
2818 numbered linearly from 0 up within each file. Sectors are not
2819 global within the filing sytem but local to the file linked to
2820 the channel. This is somewhat similar to the DOS 3 implementa‐
2821 tion of POINT.
2822 CMD 38: NOTE
2824 Similar to command 37, this command expects an open stream on
2825 the same channel, implementing the BASIC NOTE #ch,sector,byte
2826 command. It reads the file pointer within the opened file and
2827 returns byte and sector offsets using the same conventions as
2828 POINT. Bytes are numbered consequently from 0 to 255, and sec‐
2829 tors are numbered from the start of the file from zero up, each
2830 of them but possibly the last carrying 256 bytes of data. As
2831 long as programs use the values returned by NOTE as opaque val‐
2832 ues and avoid to perform algebra on them, this remains compati‐
2833 ble to the DOS 2.0S. However, programs expecting 125 byte sec‐
2834 tors and absolute sectoring are likely to fail.
2835 CMD 40: RESOLVE
2837 This command resolves a wild card sequence by a real filename.
2838 It reads the wildcard from IOCBAdr, and places the resolved
2839 filename back into the buffer pointed to by IOCBAdr as well. To
2840 be able to resolve non-unique wildcards, IOCBAux2 defines which
2841 of the non-unqiue matches shall be returned. It counts from one
2842 up, and returns the n-th found match to the specified wildcard.
2843 CMD 41: BINARY LOAD
2845 Load an executable file, and possibly initialize and run it if
2846 the file AUX2 specifies whether the loaded file shall be ini‐
2847 tialized or run. If set to 192, the file is initialized and run,
2848 128 means “init only”, 64 just runs, but does not initialize the
2849 file, and 0 neither runs nor initializes the file.
2850 Unimplemented commands
2853 The H: device does not implement the various format commands for
2854 obvious reason. It also doesn't implement some DOS 2.XL resp.
2855 DOS 3 extensions to initialize a DOS. Especially, opening the
2856 DOS.SYS file for writing will not perform anything special.
2857
2860 The operating system editor handler is responsible to collect user
2861 input from the screen, and output data back on it. It is usually left
2862 alone as all necessary components are emulated to let it function as
2863 is. However, to script the editor, it is sometimes feasible to redirect
2864 the output that would normally go to the editor of the machine to a
2865 Unix or Windows file, and to read input that would normally come from
2866 the keyboard from a file as well. For that, use the operating system
2867 patch -installedevice on which will replace the Atari handler by a
2868 patch running on the host system. Input data will be read from the
2869 standard input of the emulator command, and output will go both to the
2870 emulator front-end and the standard-output of the emulator command.
2871 Only a limited number control character transpositions will be avail‐
2872 able, though --- namely, the following standard ANSI control characters
2873 will be recognized and translated accordingly:
2874 \t Horizontal TAB
2877 \n New Line, transposed to EOL
2878 \b Backspace
2879 \a Bell
2880 \f Form Feed, transposed to Clear Screen
2881 Cursor movement and other advanced sequences are left alone, they are
2883 output device dependent and require a more careful analysis that
2884 depends on the console type used. If you need to run the emulator in a
2885 console, consider the curses front-end instead.
2886 Another limitation of the E: device patch is that it obviously cannot
2888 emulate the full-screen editor buffer of the Atari ROM as it has no
2889 access to the screen of the emulator. Instead, only the line-buffering
2890 of the console is available, i.e. the emulator will not be able to see
2891 your input unless you press RETURN. This also holds for the keyboard
2892 device, for which a patch is provided along with this option. Specifi‐
2893 cally, if software running in the emulator requires you to press a key,
2894 you need to terminate this input by RETURN to make it accessible to the
2895 emulator.
2896
2899 The R: handler is part of the emulated 850 interface box and not spe‐
2900 cific to the emulator. A real 850 would also provide this handler.
2901 Unlike the H: handler, the R: handler is not installed by the emulator
2902 directly, and is not available unless it is booted by a dedicated file.
2903 An Atari DOS distribution should either contain a file named HAN‐
2904 DLERS.SYS or an apropriate AUTORUN.SYS file to bootstrap this handler.
2905 Dos 2.5, for example, provides a setup program to generate the apropri‐
2906 ate file. This bootstrap code is not specific to the emulator and works
2907 generically for the real, as for the emulated 850 interface box. For
2908 the real 850, the bootstrap code loads code from the interface into the
2909 Atari; for Atari++, this code is part of the 850 emulation, but uses
2910 otherwise the same command set as the real 850, providing maximal com‐
2911 patibility.
2912 The emulator even emulates some of the limitations of the 850 system:
2914 Once opened, the R: handler is in block mode , only allowing you to
2915 write blocks of data asynchroniously, but not allowing you to receive
2916 data. In block mode, 850 I/O can be mixed freely with any other disk
2917 I/O.
2918 With a special XIO command, the handler must be put into concurrent
2920 mode to be able to read and write data synchroniously. In this mode,
2921 data gets sent out immediately as it is written, and input data can be
2922 received back as soon as it arrives, but any other device on the serial
2923 chain is unreachable and cannot be used savely. Thus, the disk is
2924 unavailable in concurrent mode.
2925 COMMAND SET
2928 The following set of CIO commands are made available by the R: handler:
2929 CMD 3: OPEN
2931 Open a channel to the R: handler. Aux1 is either 8 for output
2932 only in block mode, 5 for input with concurrent mode support, 9
2933 for output in block and concurrent mode, and 13 for input/out‐
2934 put, including concurrent mode support. Aux2 is ignored.
2935 CMD 5: GET RECORD
2937 Reads characters up to an EOL character, or up to the buffer
2938 end, into a buffer. Reading is only available in concurrent
2939 mode. Read characters can be optionally translated from ASCII
2940 into ATASCII, see CMD 38 below.
2941 CMD 7: GET CHARACTERS
2943 Reads a block of characters into a buffer. Again, only available
2944 in concurrent mode.
2945 CMD 9: PUT RECORD
2947 Writes characters up to an EOL or up to the end of the buffer
2948 into the opened stream. Available in block mode or in concurrent
2949 mode. In block mode, data is buffered and transmitted as soon as
2950 either the buffer becomes full, or an EOL is sent. In concurrent
2951 mode, data is sent out immediately. In both modes, characters
2952 can be optionally translated from ATASCII into ASCII.
2953 CMD 11: PUT CHARACTERS
2955 Writes a block of characters into a stream, not necessarely ter‐
2956 minated by an EOL. Otherwise identically to the above.
2957 CMD 12: CLOSE
2959 Releases the given stream, possibly empties the buffer in block
2960 mode, or waits until the write buffer is empty in concurrent
2961 mode.
2962 CMD 13: STATUS
2964 Requests the status of the given stream. Additionally, memory
2965 locations $2ea to $2ed are filled with useful information. Loca‐
2966 tion $2ea contains the error flags of the serial transfer as
2967 follows:
2968 Bit Meaning
2971 7 received a framing error
2972 6 input register overrun error
2973 5 parity error detected
2974 4 input buffer overrun error
2975 The difference between bit 6 and bit 4 is that bit 6 gets set if
2977 the emulated Atari could not react fast enough on interrupts,
2978 and bit 4 gets set if the user-provided input buffer overruns in
2979 receive mode, though the data could have been catched success‐
2980 fully.
2981 Location $2eb contains the state of the handshake lines in block
2983 mode:
2984 Bit Meaning
2987 7 current status of the DSR line
2988 6 previous status of the DSR
2989 5 current status of the CTS line
2990 4 previous status of the CTS line
2991 3 current status of the CD line
2992 2 previous status of the CD line
2993 1,0 unused, reserved
2994 The history bits mirror the state of the lines that has been
2996 returned by the previous “STATUS” command.
2997 Locations $2ec to $2ed are unassigned in block mode.
2999 In concurrent mode, $2eb and $2ec contain the low- and high-byte
3001 representing the number of characters in the input buffers,
3002 respectively. Location $2ed contains the number of characters in
3003 the output buffer.
3004 CMD 32: FORCE
3006 Flushes the output buffer in block mode, or waits until the out‐
3007 put buffer has been transmitted in concurrent mode.
3008 CMD 34: SETLINES
3010 Only available in block mode, not in concurrent mode. This com‐
3011 mand selects the states of the output lines RTS and DTR. On the
3012 real 850, the state of the data line TxD can be selected, too.
3013 The bits in Aux1 are interpreted as follows:
3014 Bit Meaning
3017 7 change the state of the DTR line
3018 6 new state of DTR if bit 7 is on
3019 5 change the state of the RTS line
3020 4 new state of RTS if bit 5 is on
3021 3 ignored, reserved
3022 2 ignored, reserved
3023 1 change the state of the TxD line
3024 0 new state of TxD if bit 1 is on (unsupported)
3025 Currently, the emulator does not support direct state changes on
3027 TxD, though. The value of Aux2 is ignored.
3028 CMD 36: SETBAUD
3030 Specifies the baud rate and other serial transfer parameters,
3031 and handshaking. Only available in block mode, not available in
3032 concurrent mode. The bits in Aux1 are interpreted as follows:
3033 If bit 7 is set, at least two, maybe more stop bits are gener‐
3035 ated. If the bit is clear, one stop bit, maybe more can be gen‐
3036 erated. Bit 6 is unsed, Bits 5 and 4 specify the number of data
3037 bits: If set to zero, eight data bits are transmitted, for 16
3038 (bits = 0,1 resp.) seven bits are used, for 32 (bits = 1,0) six
3039 data bits are generated, and for 48 (bits = 1,1) five data bits
3040 are sent. Bits 3 to 0 define the baud rate according to this ta‐
3041 ble:
3042 Value Baud rate
3045 0 remain unchanged
3046 1 45.5 (not emulated)
3047 2 50
3048 3 56.875 (not emulated)
3049 4 75
3050 5 110
3051 6 134.5 (emulated as 134 baud)
3052 7 150
3053 8 300
3054 9 600
3055 10 1200
3056 11 1800
3057 12 2400
3058 13 4800
3059 14 9600
3060 15 9600
3061 Note that values 14 and 15 generate the same rate.
3063 The bits of Aux2 indicate which serial lines have to be moni‐
3065 tored if concurrent mode is entered. If the selected serial
3066 lines are not set, an error is generated. For the emulator, mon‐
3067 itoring of CTS also enables hardware handshake.
3068 Bit Line
3071 7..3 reserved, unused
3072 2 monitor DSR
3073 1 monitor CTS, enable hardware handshake
3074 0 monitor CD
3075 CMD 38: SETPARITY
3078 This command is available in block as well as in concurrent
3079 mode. It selects character translations from ASCII into ATASCII
3080 and vice versa, and selects input and output parity. The bits in
3081 Aux1 have the following meaning:
3082 Bit Meaning
3085 7 reserved, unused
3086 6 if enabled, a LineFeed is inserted after each generated CR
3087 5,4 ASCII<->ATASCII translation, see below.
3088 3,2 input parity
3089 1,0 output parity
3090 If the character translation is set to 0, EOL is translated to
3092 CR (not LF!) and vice versa, and bit 7 is stripped off. If set
3093 to 16 (bits = 0,1), additionally non-ASCII characters are not
3094 written, resp. replaced by Aux2 on input.
3095 If the parity bits are set to zero, data is read or written “as
3097 is”. This especially implies that parity bits and stop bits of
3098 the input data are not stripped off. Furthermore, on output only
3099 eight data bits can be generated, unless the upper bits are set
3100 to one manually to emulate stop bits.
3101 If the parity bits are set to one (bits = 0,1), odd parity is
3103 generated or checked for. This works only for seven or less data
3104 bits.
3105 For the parity bits set to two (bits = 1,0), even parity is gen‐
3107 erated or checked for seven or less data bits.
3108 For parity bits set to three (both bits set, bits = 1,1), the
3110 parity bit is stripped off on input, and always set on output
3111 (parity = SPACE).
3112 Aux2 of this command specifies a “garbadge character” that gets
3114 inserted for full character translation whenever a non-ATASCII
3115 character is received.
3116 CMD 40: STARTCONCURRENT
3119 Enters the concurrent mode from block mode. The only way to
3120 leave the concurrent mode again is to close and re-open the
3121 channel. Aux1 and Aux2 are irrelevant for this command, but
3122 IOCBAdr and IOCBLen might provide the location and size of an
3123 optional input buffer where incoming data is kept until it is
3124 read off. This buffer should better be large for “higher” baud
3125 rates. If no input buffer is supplied, i.e. IOCBAdr is set to
3126 NULL, the handler will provide a short 32 byte input buffer.
3127 On entering concurrent mode, the input lines specified by the
3129 “SETBAUD” command are monitored once. If the selected lines are
3130 not set, an error is generated. The real 850 interface does not
3131 provide full hardware handshaking, the emulated 850 does by mon‐
3132 itoring CTS.
3133
3136 The Atari++ emulator provides its own operating system in case no Atari
3137 ROM image is available. This makes the emulator self-contained as you
3138 don't require to hold any usage rights on the original ROMs to run it.
3139 The built-in ROM implements a full Atari XL operating system and tries
3140 to be compatible to the XL ROM in most aspects; however, since it is a
3141 re-implementation, absolute ROM addresses and implementation details
3142 may, and will, differ. The paragraphs below give a brief overview on
3143 the ROM features, the subsections discuss the features in more detail.
3144 Built-in FMS (DOS)
3147 The built-in operating system comes with its own file management
3148 system, unlike the original Atari ROMs. This is classically, but
3149 imprecisely, called the DOS (Disk Operating System). This FMS is
3150 used in case no bootable disk is available on bootstrap. This
3151 allows easy loading and saving of binary images without requir‐
3152 ing an Atari copyrighted FMS. For details, see the FMS subsec‐
3153 tion below.
3154 Parallel Port Support
3157 has been dropped. This is because Atari++ neither emulates any
3158 parallel port devices, nor does the author has any usable docu‐
3159 mentation about it.
3160 The MathPack
3163 is classically not considered part of the operating system, but
3164 is emulated fully with all documented and some undocumented
3165 entry points the author is aware of. The emulation is complete
3166 enough to allow BASIC and many other programs operate properly,
3167 except that the re-implementation is usually a bit and sometimes
3168 considerably faster. You might also consider the MathPack patch
3169 option that evaluates the mathematical operations on the host
3170 CPU and improves the speed beyond what is achievable with the
3171 6502 implementation.
3172 The C: Tape handler
3175 is replaced by a dummy. This is because Atari++ does not emulate
3176 the tape device, and the ROM space was required.
3177 CHARACTER GENERATOR
3180 The international character set at position 0xcc00 and up has been
3181 slightly modified. Character position 8 (Ctrl-H) is now the Euro-sign,
3182 character position 96 (Ctrl-.) is the german sharp-s. The pound sign
3183 and the inverted exclamation mark are no longer available.
3184 INTERRUPT HANDLING
3187 The Os NMI handler also checks the ANTIC Reset NMI signal and, if
3188 detected, jumps indirectly through the vector in location $24e. This
3189 vector points to the warmstart Os vector. Unknown NMI sources are
3190 ignored, unlike the original Os which handles them as VBIs.
3191 VBI Handler
3194 The built-in Os vertical retrace handler (VBI) does not check
3195 whether TRIG3 and its shadow-register coincide. This avoids a
3196 couple of deadlock situations in various games that overwrite
3197 the shadow register. VBI handling of 1200XL keyboard features is
3198 not present since atari++ does not emulate these keys and the
3199 author has no precise documentation about them.
3200 IRQ Handler
3203 The IRQ handler is more streamlined than the original IRQ han‐
3204 dler; it also no longer handles any parallel port related inter‐
3205 rupts since they are never generated by the emulator.
3206 KERNEL
3209 Parallel port call-ins
3210 have been replaced by dummies.
3211 $e48f: BOOT850
3214 This is a new kernel-call in that bootstraps the 850 interface
3215 handler thru SIO. It should be typically used by a minimal HAN‐
3216 DLERS.SYS file that contains nothing but a RUN-vector to this
3217 call-in.
3218 $e45c: SETIRQVECTOR
3220 The SetIRQVector call-in can now also savely install IRQs as
3221 well without requiring the caller to set the interrupt bit of
3222 the CPU.
3223 $e492: RUNDUP
3225 This vector launches the DUP keyboard command processor. The DUP
3226 vector at $a,$b points to this address by default. The built-in
3227 DUP can be replaced by a custom DUP by changing the reset-resi‐
3228 dent vector at $3f6.
3229 $e498: FMSINIT
3231 This vector initializes the built-in FMS. The Os reset initial‐
3232 izes the ROM-based FMS thru this vector if no bootable disk is
3233 found.
3234 RESET/Bootstrap
3237 Tape bootstrap
3238 Since the built-in Os does not implement a usable tape device,
3239 tape bootstrap is no longer supported. The CASINIT vector
3240 (0x02/0x03) is, however, emulated properly.
3241 Disk bootstrap
3243 The built-in Os tries to bootstrap the disk as usual, but does
3244 not loop forever in case it detects that no disk is inserted in
3245 the drive. In case an usable boot block is found, the resident
3246 FMS is not installed and a disk-based DOS can replace it, as
3247 usual. The resident FMS is launched if either no usable boot
3248 block is found, no usable disk is found, or the user holds down
3249 the START key on bootstrap. An unusable boot block is indicated
3250 by a bootstrap address of zero, thus by a blank boot block. Note
3251 that START is no longer an indication for tape bootstrap since
3252 there is no tape support. In case the built-in FMS gains control
3253 in the boot process, see below in the FMS subsection for further
3254 bootstrap activity.
3255 850 interface bootstrap
3257 In case the disk bootstrap failed because no disk is inserted,
3258 the ROM also tries to bootstrap the 850 interface box since no
3259 HANDLERS.SYS file can be loaded then.
3260 SELFTEST
3263 The ROM space occupied by the self-test was required for the DOS com‐
3264 mand line (the DUP ) and is therefore no longer part of the Os.
3265 Instead, the following color codes appear on the screen if the power-on
3266 tests fail:
3267 Color code RED
3269 The RAM test failed, a faulty RAM chip has been detected.
3270 Color code PINK
3272 The ROM checksum is faulty.
3273 Color code BLUE
3275 The bootstrap code could not open the initial editor handler.
3276 SERIAL I/O (SIO)
3279 SIO interrupts
3280 The serial communication is initiated thru the Pokey XMTDONE
3281 interrupt. This makes it easier for future extensions to relo‐
3282 cate disk buffers under the Os ROM.
3283 Parallel port handling
3285 of SIO communications has been dropped due to lack of ROM space
3286 and documentation.
3287 Tape device handling
3289 is no longer provided by SIO since Atari++ does not emulate the
3290 tape anyhow. Trying to use the tape thru SIO will now initiate a
3291 standard serial communication and will no longer use two-tone
3292 modulation. Thus, tapes won't work as expected.
3293 Resident Disk handler (DISKINTERF)
3296 Format command
3297 The DISKINTERF vector handles now the enhanced density format
3298 command of the 1050 floppy drive correctly. Thus, it supports
3299 the 1050 command set fully.
3300 Parallel port I/O
3302 thru DISKINTERF via SIO is no longer possible since SIO does not
3303 try to interact with the parallel port any more.
3304 CENTRAL I/O (CIO)
3307 CIO CMD_OPEN
3308 The CIO OPEN command installs now the PUT ONE BYTE vector before
3309 calling the OPEN vector of the corresponding handler. This
3310 allows the handler to overload this vector in order to implement
3311 “bursting” more easily. Currently, the FMS makes use of this
3312 feature to avoid the check whether it was called from the BASIC
3313 ROM that incorrectly uses this vector.
3314 CIO HATABS extension
3316 thru the parallel port linked list is not implemented since the
3317 author has no sufficient documentation about its implementation
3318 and usage.
3319 CIO handler bootstrap
3321 is no longer supported due to lack of documentation.
3322 THE C: TAPE HANDLER
3325 is only a dummy that returns error conditions on all I/O operations. It
3326 only remained in the ROM to allow the H: handler to patch it over.
3327 THE K: KEYBOARD HANDLER
3330 works like its equivalent in the Atari 800XL ROM except that it does
3331 not check for Atari 1200XL function keys. Extended editor keyboard
3332 functions are provided to the best knowledge of the author, though. The
3333 K: handler respects now the BREAK key correctly.
3334 THE E: EDITOR
3337 The editor device is much more decoupled from the screen handler than
3338 in the original ROM, see also the S: handler section below.
3339 Editor Buzzer
3341 The buzzer is run on a cursor position that depends on the edi‐
3342 tor margins now. It is also rung on character insertion if char‐
3343 acters are likely to be moved out of the screen.
3344 Editor Window
3346 Unlike the original Atari Editor device, the emulated E: handler
3347 allows arbitrary high editor windows, not just four or 24 lines
3348 - if programmed properly.
3349 Editor Scrolling
3351 on line insertion or delection does no longer overwrite memory
3352 above MEMTOP.
3353 THE S: SCREEN HANDLER
3356 As mentioned above, the S: handler is decoupled from the E: handler and
3357 therefore reacts in certain aspects differently than its original coun‐
3358 terpart.
3359 Screen GET/PUT
3361 The S: handler no longer tries to scroll, neither does it
3362 respect editor margins. If the put or get commands reach the end
3363 of the screen, an out-of-bounds error (error 141) is generated.
3364 The only control codes the screen handler handles separately are
3365 $7d, which clears the screen, and $9b, which implements a line
3366 feed, though dos not scroll.
3367 Open Command
3369 The S: open provides more graphic modes than the original. If 64
3370 is added to the graphics mode, then a text window is generated
3371 even for the graphic modes 9, 10 and 11. Unlike in the original
3372 Os, smooth scrolling works correctly in text windows, even in
3373 text windows of the GTIA modes 9 to 11.
3374 DMA/Player-Missile
3376 The S: handler no longer interacts with player/missile graphics
3377 and respects the corresponding bits in the DMACTRL shadow regis‐
3378 ter.
3379 Out of memory situations
3381 will be handled more graceful than in the original ROM.
3382 THE P: PRINTER HANDLER
3385 The built-in ROM supports the printer to full extend, and no functional
3386 changes should hopefully appear.
3387 MATH PACK
3390 The MathPack is not part of the operating system, but historically part
3391 of the BASIC. As a consequence, the math pack is does not provide a
3392 jump-in table as the operating system, and fixed ROM-addresses must be
3393 used.
3394 Atari++ also provides an emulation, or rather a replacement implement‐
3396 ing the same routines as the original math ROM. The precision and speed
3397 of the re-implementation should be superior to the original ROM imple‐
3398 mentation. However, it is, in general though, advisable to use the
3399 MathPackPatch which is again a lot faster and still more precise than
3400 the re-implementation because it uses the floating-point math of the
3401 host machine.
3402 NOTE: While the author tried its best to make the replacement math-pack
3404 as compatible as possible to the original ROM, some problems should be
3405 expected. BASIC and MAC/65 software should be mostly unaffected, but
3406 since Atari never provided a jump-in table for the math-pack, third-
3407 party software might use routines of the math-pack that have never been
3408 officially documented, and are not provided by the emulation. Despite
3409 that, this math-pack replacement does already contain a number of in-
3410 official call-ins that are used by BASIC and other software. Neverthe‐
3411 less, numerical results obtained by this implementation might differ
3412 from the original due to round-off issues where the re-implementation
3413 offers often better more precise results.
3414 The replacement math-pack provides the following routines and data:
3416 AFP $d800
3419 Convert the ATASCII number in the buffer pointed to by "inbuff"
3420 ($f3,$f4) at offset given by "cix" ($f2) into a floating point
3421 number in "fr0" ($d4 to $d9). On output, "cix" points to the
3422 first character that could not be converted. The carry register
3423 is set in case no conversion could be conformed at all. Unlike
3424 the original, this routine operates at ten instead of nine-dig‐
3425 its precision and rounds properly if more than ten digits are
3426 provided.
3427 FASC $d8e6
3430 Convert the floating point number in "fr0" ($d4 to $d9) into
3431 ATASCII in the output buffer at $580 and following. "fr0" is
3432 destroyed on completion. The end of the string is indicated by
3433 setting the MSB of the last character, the final string is
3434 pointed to by "inbuff" ($F3,$F4) on exit. Unlike the ROM imple‐
3435 mentation, this routine is more streamlined and does not over‐
3436 write bytes in front of the output buffer, the output will
3437 always start at, and not sometimes in front of $580. If called
3438 at FASC+3, the user can define its output buffer where he likes
3439 by placing the address into "inbuff". This is not available in
3440 the original ROM.
3441 IFP $d9aa
3444 Convert the unsigned integer in "fr0"(lo) and "fr0+1"(hi) into a
3445 floating point representation to "fr0" ($d4 to $d9). Unlike in
3446 the original ROM ,"IFP+4" converts the integer in the registers
3447 X(lo) and Y(hi) into floating point.
3448 FPI $d9d2
3451 Convert the floating point number in "fr0" ($d4 to $d9) into a
3452 two-byte integer representation, also in "fr0" and "fr0+1",
3453 rounded correctly to the nearest integer. If the conversion is
3454 not possible, the carry bit will be set. The original implemen‐
3455 tation had a couple of issues on overflow and rounding that are
3456 not reproduced here.
3457 ZFR0 $da44
3460 Initialize the "fr0" register ($d4 to $d9) with zero.
3461 AF1 $da46
3464 Initialize the six-byte floating point register pointed to by
3465 the X register with zero.
3466 ZERORGS $da48
3469 Clear N bytes starting at the zero-page register given by X,
3470 where N is given in the Y register. This inofficial call-in is
3471 used by Mac/65 and BASIC.
3472 LOADOUTBUFF $da51
3475 Initialize the "inbuff" zero page registers ($f3 and $f4) to
3476 point to the floating point output buffer at $580. Used by BASIC
3477 and MAC/65.
3478 FADD $da66
3481 Add the contents of the floating point register "fr1" ($e0 to
3482 $e5) to the floating point register "fr0" ($d4 to $d9). "fr1"
3483 will be destroyed. Sets the carry in case the representation
3484 overflows, and destroyes "fr1". Unlike the orignal, this routine
3485 employes a correct "round to nearest" policy if the output can‐
3486 not be represented exactly, and it also uses denormalized num‐
3487 bers if the output is very close to zero.
3488 FSUB $da60
3491 Subtracts the contents of the floating point register "fr1" ($e0
3492 to $e5) from the floating point register "fr0" ($d4 to $d9).
3493 "fr1" will be destroyed. Otherwise, works like the floating
3494 point addition and its new round-to-nearest mode.
3495 FMUL $dadb
3498 Multiplies the contents of "fr1" ($e0 to $e5) with "fr0" ($d4 to
3499 $d9) and places the result in "fr0". "fr1" will be destroyed. On
3500 overflow, the carry flag of the processor will be set. Like
3501 addition, this routine uses a smarter round-to-nearest policy,
3502 and unlike the original, has all issues on detecting overflows
3503 fixed, specifically, multiplying two very small numbers will
3504 give zero, not an overflow. It will also handle denormalized
3505 numbers correctly, and is noticably faster than the original.
3506 FDIV $db28
3509 Divides the contents of "fr0" ($d4 to $d9) by the contents of
3510 "fr1" ($e0 to $e5) and places the result in "fr0", destroying
3511 "fr1". On overflow or divide by zero, the carry flag will be
3512 set. This routine also uses a precise round-to-nearest policy.
3513 Unlike the original routine, dividing a small number by a very
3514 large number will not create an overflow, but - as appropriate -
3515 zero.
3516 SKIPBLANKS $dba1
3519 This routine is not officially documented but nevertheless used
3520 by Mac/65. It skips all blank-characters in the input buffer
3521 ($f3,$f4) at offset in "cix" ($f2) and adjusts "cix" such that
3522 it points at the first non-blank character.
3523 TESTDIGIT $dbaf
3526 Another inofficial function used by Mac/65 and BASIC. This func‐
3527 tion tests the character at "inbuff" ($f3,f4) at offset "cix"
3528 ($f2) for a valid decimal digit and returns the numerical value
3529 of this digit and the carry flag cleared if possible. Otherwise,
3530 on an invalid digit, the carry flag gets set.
3531 FR0TIMESTEN $dbeb
3534 This is also an inofficial vector that multiplies the mantissa
3535 of the fr0 floating point register at address $d4 by ten, i.e.
3536 it shifts all digits to the left. It is used by the multiplica‐
3537 tion and division function, and the Basic++ square root func‐
3538 tion.
3539 NORMALIZE $dc00
3542 This method is neither officially documented, but used neverthe‐
3543 less by BASIC and Mac/65. It normalizes the floating-point num‐
3544 ber in "fr0" ($d4 to $d9), eliminating leading zero-digit pairs
3545 in the mantissa and adjusting the exponent accordingly. It
3546 returns with the carry flag cleared on success and with the
3547 carry set on overflow. Unlike the original implemenation, this
3548 version leaves near-zero numbers denormalized, and overflows at
3549 a decimal exponent of 100, not at 99 as the original.
3550 PLYEVL $dd40
3553 Evaluates the polynomial whose floating point coefficients are
3554 pointed to by X(lo) and Y(hi) at the location given by "fr0"
3555 ($d4 to $d9). The number of coefficients, and hence the degree
3556 of the polynomial plus one is passed in the accumulator on
3557 entry. Returns the result in "fr0", and destroys "fr1" ($e0 to
3558 $e5), sets the carry flag on overflow.
3559 FLD0R $dd89
3562 Load "fr0" ($d4 to $d9) with the floating point value pointed to
3563 by X(lo) and Y(hi).
3564 FLD0P $dd8d
3567 Load "fr0" ($d4 to $d9) with the floating point value pointed to
3568 by "flptr" ($fc,$fd).
3569 FLD1R $dd98
3572 Load "fr1" ($e0 to $e5) with the floating point value pointed to
3573 by X(lo) and Y(hi).
3574 FLD1P $dd9c
3577 Load "fr1" ($e0 to $e5) with the floating point value pointed to
3578 by "flptr" ($fc,$fd).
3579 FSTOR $dda7
3582 Store "fr0" ($d4 to $d9) to the six-byte memory buffer pointed
3583 to by X(lo) and Y(hi).
3584 FSTOP $ddab
3587 Store "fr0" ($d4 to $d9) to the six-byte memory buffer pointed
3588 to by "flptr" ($fc,$fd).
3589 FMOVE $ddb6
3592 Copy the contents of "fr0" ($d4 t0 $d9) to "fr1" ($e0 to $e5).
3593 EXP $ddc0
3596 Compute a the exponential function at the location given by
3597 "fr0" ($d4 to $d9), destroys the contents of "fr1". Returns with
3598 the result in "fr0" and the carry cleared on success, with carry
3599 set on overflow.
3600 EXP10 $ddcc
3603 Computes 10 to the power of the number given in "fr0" ($d4 to
3604 $d9), destroys the contents of "fr1", returns with the carry set
3605 on overflow or the proper result in "fr0". This implementation
3606 is not only faster than the original ROM implementation, it is
3607 also more precise - in general, nine to ten correct digits can
3608 be expected. It also has a couple of issues of the original
3609 implementation fixed, namely the exponential of a very negative
3610 number yields zero, not an overflow, and the exponential of ten
3611 to an integer power is always integer. BASIC uses this function
3612 to compute the exponential, via the call-in above, but also to
3613 compute the power function (a^b). Unfortunately, due to a bug in
3614 BASIC revisions B and C (but not in revision A), BASIC always
3615 rounds the result up to the next integer if a and b are integer,
3616 with the side effect that if the result of this method is a tiny
3617 little bit too large, the output will be off by one. For exam‐
3618 ple, computing 4^4 results in 256.000002, which is correct to
3619 nine places, but which is rounded by BASIC to 257. This is a bug
3620 in BASIC and not in this implementation; the coefficients have
3621 been carefully choosen to avoid such situations for lower expo‐
3622 nents, i.e. for b=1 to 3, the result will be always correct.
3623 Enforcing correct results for higher exponents would have
3624 resulted in a major precision loss just to work around old bugs,
3625 which was considered inappropriate.
3626 FFRAC $de95
3629 This is another call-in that is used by BASIC which is not offi‐
3630 cially documented. It computes the rational function (x-C)/(x+C)
3631 where the value of x is given by the contents of the "fr0" reg‐
3632 ister ($d4 to $d9) and C is stored as a six-byte floating point
3633 number pointed to by X(lo) and Y(hi). On exit, the carry flag is
3634 set on overflow, and clear on success. Then, the result is given
3635 in the "fr0" register.
3636 LOG $decd
3639 Compute the natural logarithm of the number given in "fr0" ($d4
3640 to $d9). Returns with the carry set on overflow, or zero or neg‐
3641 ative input, otherwise with the result in "fr0".
3642 LOG10 $ded1
3645 Compute the decadic logarithm (logarithm to the base of ten) of
3646 the number given in "fr0" ($d4 to $d9). Returns with the carry
3647 set on overflow, negative or zero input, and carry cleared and
3648 the proper result in "fr0" otherwise. This method can be
3649 expected to be faster and more precise than the original ver‐
3650 sion.
3651 ONEHALF $df6c
3654 Not a call-in, but rather a floating-point constant that is used
3655 by BASIC for various purposes, most notably for the SQR func‐
3656 tion. Its value is 0.5.
3657 ATNCOEFF $dfae
3660 This is not a call-in, but rather a table of eleven floating
3661 point constants representing the coefficients of the minimax-
3662 approximation of the arcus tangens in the interval from 0 to 1.
3663 It is used by the BASIC implementation of the ATN function.
3664 NEARONE $dfea
3667 Part of the above table, but also used by BASIC separately, this
3668 is the constant term of the above polynomial, and also used to
3669 adjust coefficients outside the interval 0..1 by means of the
3670 functional equation of ATN. The value of this constant should be
3671 exactly one in an ideal infinite-precision implementation, but
3672 due to various round-off errors, it is 0.9999999999 in the Atari
3673 ROMs. In the emulated ROM, its value is 1.0 precisely.
3674 PIOVER4 $dff0
3677 Another floating point constant used by BASIC, here the value of
3678 Pi divided by four correct to ten decimal places. It is used by
3679 the ATN function in the BASIC rom.
3680
3683 This handler is provided by the now built-in FMS that is used if disk-
3684 bootstrap was unsuccessful or aborted by the user, see also above. The
3685 FMS in ROM space is basically a reworked and bugfixed version of Dos
3686 2.XL/XA of the same author that was streamlined to fit into the low
3687 memory Os area 0xc002 to 0xcbff. It therefore provides 963 free sectors
3688 on a standard enhanced density disk while retaining Dos 2.0S compati‐
3689 bility. In specific, the VTOC layout is identical.
3690 It can read Dos 2.5 disks, but it is not write-compatible to Dos 2.5.
3692 This route was choosen basically because the author had the Dos 2.XL
3693 sources available for obvious reasons, unlike the Dos 2.5 sources. The
3694 following documents the FMS command set:
3695 CMD 3:OPEN
3697 Opens a file. Details depend on AUX1 and AUX2. For AUX1 = 0, the
3698 following modes are used:
3699 aux1 function
3701 ───────────────────────────────────────────────────────────
3702 4 open for read-only
3703 6 open for directory reading, including the disk name
3704 7 open the directory, excluding the disk name
3705 8 create/overwrite for write-only
3706 9 open for append write-only
3707 12 open for read and write (update)
3708 13 create for read, write and append
3709 Note that mode 9 does not waste a sector, unlike the Dos 2.0S
3711 implementation. Mode 12 is the update mode, it generates an EOF
3712 condition in case it is attempted to extend the file over its
3713 initial size. Mode 13 is new and automatically extends the file
3714 over its boundary should a write past the EOF be sent. Unlike
3715 mode 9, the file pointer is positioned at the start of the file
3716 initially. Mode 6 also includes a disk title should it be pro‐
3717 vided.
3718 For AUX2 = 128, things change dramatically. This mode provides
3720 full random access to the raw disk without any file management
3721 functions; thus, this mode allows “raw” access to disks. File
3722 names do not matter here as long as they are syntactically cor‐
3723 rect, and sectors are always 128 bytes long. The disk is under‐
3724 stood as one big sequential file starting at sector one and
3725 extending to its last sector. Access to sectors is provided by
3726 means of the POINT/NOTE commands. The following open modes are
3727 available for AUX1 = 128:
3728 aux1 function
3730 ──────────────────────────────────────────────────────────
3731 4 open for read-only. Reads raw sectors sequentially
3732 8 create for write-only. Writes raw sectors.
3733 12 open for simulateous raw read and write
3734 CMD 5: GET RECORD
3737 The standard CIO record reading command. Reads bytes until the
3738 record is full or an EOL is detected.
3739 CMD 7: GET CHARACTERS
3741 Reads characters into the buffer until either the buffer is full
3742 or an EOF condition is reached. The FMS tries to bypass CIO,
3743 i.e. it tries to “burst” to speed up processing.
3744 CMD 9: PUT RECORD
3746 Writes bytes to the file/disk until either the buffer becomes
3747 empty, and EOL is found in the buffer or an EOF condition is
3748 generated.
3749 CMD 11: PUT CHARACTERS
3751 Writes characters to the file until the buffer becomes empty or
3752 an EOF condition is generated. This command also implies burst‐
3753 ing, if possible.
3754 CMD 12: CLOSE
3756 Closes the file, writes the last buffer out and updates the
3757 directory unless the stream is ”raw“.
3758 CMD 13: STATUS
3760 This command works a little bit different than under DOS 2.0S
3761 and DOS 2.5 where it only checks the validity of a file specifi‐
3762 cation and the availability of a drive. Since BASIC never sup‐
3763 plies this information to STATUS , this command was actually
3764 unuseful in BASIC and never worked as intended.
3765 Instead, if the channel is already open, STATUS returns the sta‐
3767 tus of the last CIO operation on this specific channel, which
3768 allows now BASIC to check, for example, whether the next GET
3769 command will return an EOF by testing against the error code 3.
3770 If the channel is still closed, works as it did for DOS 2.0S and
3772 DOS 2.5: It checks the given filespec for validity, tests wether
3773 the given disk is available and readable, and whether the file
3774 can be written to. Otherwise, appropriate error conditions are
3775 generated. If used from BASIC, STATUS should then be rather
3776 replaced by a XIO 13 command which supplies a file name.
3777 CMD 32: RENAME
3780 Renames files. Requires the old filespec, then a comma, and the
3781 new target file name. This command may cause several identically
3782 named files. Such files can be resolved by using the /1 through
3783 /9 file specification modifier defined below. Alternatively,
3784 this command and the next four, namely DELETE, FIND, LOCK and
3785 UNLOCK, take a non-zero aux2 value which then specifies which of
3786 the specific matches to a wildcard is to be renamed, deleted,
3787 found, locked or unlocked.
3788 CMD 33: DELETE
3790 Delete one or several files on the disk.
3791 CMD 34: FIND
3793 Resolves a wild card filespec and returns a full file name in
3794 the input buffer. This command is used by the command line
3795 interpreter (“DUP”) to resolve wild-cards.
3796 CMD 35: LOCK
3798 Prevents a file or several files from getting overwritten by
3799 setting their write-protecting bits.
3800 CMD 36: UNLOCK
3802 Removes the write-protection lock on a file or several files.
3803 CMD 37: POINT
3805 Places the file pointer at a given file/sector position. Unfor‐
3806 tunately, the FMS doesn't provide simple sequential accessing of
3807 files, but rather expects an absolute sector/byte offset in
3808 AUX3,AUX4 (sector) and AUX5 (byte), similar to Dos 2.0S. If an
3809 invalid write position is specified here, then the disk might
3810 get corrupted. Only file pointers obtained by a previous NOTE
3811 onto the same file should be passed in as arguments here.
3812 Unlike under DOS 2.0S and DOS 2.5, POINT also works for files
3814 opened in write-only mode, i.e. mode 8, and can there be used to
3815 re-position the file pointer to some place in front of the EOF,
3816 overwriting data that has already been written. Similarly, POINT
3817 is very helpful to append to files in the update/append mode 13
3818 when the former EOF position has been recorded by a NOTE , which
3819 then works much faster than having the file opened in append
3820 mode. The latter has to find the EOF manually, the former will
3821 place the file pointer directly at the EOF.
3822 The POINT command is also used for absolute positioning within
3824 the disk if the corresponding stream is opened for raw mode,
3825 i.e. with AUX2 = 128.
3826 CMD 38: NOTE
3829 Returns the current file pointer as sector/byte offset to be
3830 used for a future POINT command. AUX3/4 contain the low/high-
3831 byte of the sector, AUX5 the sector offset.
3832 CMD 39: INIT
3834 Clears and initializes the disk, erasing all files, but not for‐
3835 matting the disk. This is a quick format for disks that have
3836 been formatted already. Optionally, a disk title can be given
3837 behind the device specification. This title will then appear in
3838 reverse video on each directory listing.
3839 CMD 40: FIND
3841 Similar to CMD 34 to maintain Dos 2.XL compatibility.
3842 CMD 41: BINARY LOAD
3844 Loads a binary file from disk, possibly initializing and running
3845 the binary. AUX2 specifies whether the loaded file shall be
3846 initialized or run. If set to 192, the file is initialized and
3847 run, 128 means “init only”, 64 just runs, but does not initial‐
3848 ize the file, and 0 neither runs nor initializes the file. Note
3849 that Atari specified CMD 41 (and not CMD 40) for the binary load
3850 command.
3851 CMD 42: FORMAT
3853 Formats a disk in various sizes. If AUX1 is set to 33, then the
3854 disk is formatted in single density to 707 sectors. For AUX1 set
3855 to 34, then an enhanced density format is initiated, resulting
3856 in a 963 sector disk. All other values are reserved. This com‐
3857 mand also accepts a disk title.
3858 CMD 43: FORMAT ENHANCED
3860 Initiates a standard enhanced density format, independent of
3861 AUX1 and AUX2. This also accepts a disk name, similar to the
3862 above.
3863 CMD 254: FORMAT ENHANCED
3865 Identical to CMD 43.
3866 FMS FILE SPECS
3869 The built-in FMS defines the following rules for filenames; these rules
3870 are very close to those formulated by Dos 2.0S.
3871 The first character must be an uppercase letter, all remaining charac‐
3873 ters must be uppercase letters or digits. A file name consists of at
3874 most eight characters, and an optional three character extender behind
3875 a dot (“.”). Three wild card-characters are understood: The question
3876 mark “?” that matches one single arbitrary character, the asterisk “*”
3877 that matches a sequence of arbitrary characters except the dot, and the
3878 dash “-” that is equivalent to the wild-card sequence “*.*” and thus
3879 matches any file.
3880 Additionally, the FMS supports access mode modifiers that can be
3882 appended to a file name to change the behaivour of the command. These
3883 modifiers are appended behind a slash, “/”, e.g. “D:FILE/A”. The fol‐
3884 lowing modifiers are understood:
3885 /A Open a file for append mode instead of write mode, i.e. change
3888 mode 8 to mode 9. Also changes the plain directory mode to the
3889 restricted directory mode that suppresses the disk name, and
3890 modifies mode 12 to mode 13. All other combinations are invalid.
3891 This modifier is useful in the FMS command line in combination
3892 with the COPY command to append one file to another.
3893 /D Changes the open mode from reading to directory reading, i.e.
3896 changes mode 4 to mode 6. This is, for example, useful in the
3897 FMS command line to print the directory by means of COPY
3898 D:-/D,P:
3899 /O Does not modify the open mode, but rather disables verify writes
3902 and uses the faster write without verify disk command. This
3903 makes writes faster at the price of possibly hiding write errors
3904 on bad disks.
3905 /V Similar to the above, though it enables verify writes.
3908 /N Only used together with the BINARY LOAD command to disable
3911 launching the program after having loaded it.
3912 /1../9 If several identically named files exist, access the n-th file
3915 of them. This access modifier allows to specify one of several
3916 identically named files as they could have been created by the
3917 Rename command.
3918 Note that the file spec “DOS.SYS” is not at all special for the FMS,
3920 unlike DOS 2.0S; it will refer to a standard regular file. The FMS will
3921 never ever try to write itself to disk. Thus, even the FMS can write
3922 the disk structure of Dos 2.XL fine on disk initialization, these disks
3923 will not be bootable without the ROM FMS.
3924 FMS ERROR CODES
3927 The FMS generates the following error codes; Not listed here are
3928 generic SIO errors that are generated by the Os kernel, not by the FMS:
3929 Error 160, IllegalUnit
3932 The requested disk unit is not available.
3933 Error 161, TooManyFiles
3936 Too many files are open at once, the FMS run out of buffers.
3937 Error 162, DiskFull
3940 No more free store on the disk.
3941 Error 164, FileLinkBroken
3944 Fms structure found damaged, possibly because of an invalid
3945 POINT.
3946 Error 165, FileNameInvalid
3949 The file name is invalid.
3950 Error 166, InvalidPoint
3953 An argument to POINT was out of range.
3954 Error 167, FileProtected
3957 A write operation to a locked file was attempted.
3958 Error 169, DirectoryFull
3961 Could not create a file since the directory was filled.
3962 Error 170, FileNotFound
3965 The specified filespec does not exist.
3966 Error 175, NoBinaryFile
3969 The specified file is not a binary load file.
3970 Error 176, BadLinkage
3973 Found a bad sector link to sector #0, the disk structure is dam‐
3974 aged.
3975 Error 177, InvalidMode
3978 The specified open mode is invalid.
3979 Error 178, NotADosDisk
3982 The structure of the inserted disk is not compatible to Dos
3983 2.++.
3984 THE COMMAND LINE PROCESSOR (DUP)
3987 The built-in FMS also provides a disk utility package (a “DUP”). It is
3988 activated from BASIC via the DOS command, or is run automatically if no
3989 cart is found inserted.
3990 The command line accepts commands similar to a Linux shell, except that
3992 its commands are much more restrictive. If the command entered is just
3993 a device specification, i.e. a one- or two-letter string terminated by
3994 a colon, then the active device is changed. Otherwise, the command line
3995 tries to locate the command as file on disk, as a binary, and then runs
3996 it. It does NOT append a file extender, unlike OS/A+ which would always
3997 append “.COM”. The file name is loaded and executed exactly as entered.
3998 The full command line including the command and its arguments is placed
4000 in a 128 byte buffer at $580 where the executed binary may find it, and
4001 may parse it itself if required. The command line does not provide
4002 functions to parse this buffer.
4003 NOTE This is not the way how Dos OS/A+ executes external commands.
4005 There was unfortunately not enough ROM space available to implement
4006 command line parsing service functions as OS/A+.
4007 If the command starts with a double quote, or is not found on disk,
4009 then the command line processor tries to locate this as an internal
4010 command. The following internal commands are available: Optional argu‐
4011 ments are here denoted in square brackets, these are not part of the
4012 command syntax. filespec is a file specification, optionally contain‐
4013 ing wildcards, and optionally containing a device specification sepa‐
4014 rated from the file name by a colon. If no device name is given, the
4015 curently active device in front of the command is used.
4016 DIR [filespec]
4019 Lists the disk directory. If a filespec is given, only the files
4020 matching the filespec will be listed. DIR is not able to list
4021 the directory to some other device. For that, use the COPY com‐
4022 mand and a source filespec with the “/D” access modifier.
4023 DELETE filespec
4026 Deletes the file or files that match the filespec. Note that
4027 this command performs its work immediately and without asking
4028 further question.
4029 RENAME filespec,newname
4032 Renames a file or several files to a target filename on the same
4033 device. If more than one file matches the wildcard, all of them
4034 are renamed to the same target name. You can pick between vari‐
4035 ous identically named files by means of the /1 to /9 modifiers,
4036 allowing you to rename some of them back.
4037 LOCK filespec
4040 Marks the file or files as write-protected. Any kind of write
4041 operation, or deletion of the file is then prohibited.
4042 UNLOCK filespec
4045 Removes the write protection again, the opposite of the above.
4046 CAR Runs the cartridge should there be one inserted. If no cart is
4049 available, and neither any reset resident program is found, the
4050 command processor will be entered again.
4051 FORMAT [title]
4054 Formats the specified disk to enhanced density, erasing all its
4055 contents. An optional disk name can be specified here that will
4056 be printed in inverse video when listing the directory contents.
4057 CLEAR [title]
4060 Similar to the above, this command clears the entire disk con‐
4061 tents and installs an optional disk name. However, the CLEAR
4062 command only re-initializes an already formatted disk. By that,
4063 CLEAR is much faster than FORMAT and intended to be a quick-for‐
4064 mat.
4065 RUN [hexaddress]
4068 Runs a machine code program at the specified address. If no
4069 address has been given, the previously loaded command will be
4070 run, or run again.
4071 SAVE filespec,from,to,[[,init],run]
4074 Saves a binary file to disk, starting at the given hex address,
4075 up to the given address. An optional init and run address can be
4076 given here as well. Note that you can always append to a file,
4077 and thus extend a binary load file, by using the “/A” access
4078 modifier behind the file name.
4079 LOAD filespec
4082 Loads a file from disk, but does not start it. You can run this
4083 file later by means of the RUN command without additional argu‐
4084 ments.
4085 COPY filespec,target
4088 Copies one or several files from one disk to the same or another
4089 disk. COPY will first read the file from the source, and will
4090 then wait for you to swap disks. If the source and the target
4091 disk are identically, just press RETURN, otherwise swap disks
4092 first. COPY will then write the target file, and might ask you
4093 again to insert the source disk if the file is too large to be
4094 read in one go, or if more than one file is to be copied.
4095 COPY tries to avoid using user RAM contents whenever possible.
4097 Application memory that is reserved correctly by setting the Os
4098 vector APPMEMHI will be preserved, and BASIC source code will be
4099 spared. However, not all applications adjust APPMEMHI correctly,
4100 Mac/65 is such an example.
4101 NEW will erase user memory and will make this memory available for
4104 the COPY command, i.e. you will require to swap disks less
4105 often. The NEW command is also necessary to inform some car‐
4106 tridges or application programs that its memory has been over‐
4107 written after performing a copy operation. This is necessary if
4108 the corresponding program does not set APPMEMHI correctly.
4109 FMS HINTS AND TWEAKS
4112 Sometimes an external command has the same name as an internal one. In
4113 this case, the external command is prefered to the internal one and is
4114 loaded, bypassing the internal one. If this is undesired, place a dou‐
4115 ble quote in front of the command. This will avoid the external command
4116 lookup.
4117 You might have noted that the DIR command is not able to list the
4119 directory to anything but to the screen. However, the COPY command can
4120 perform a similar operation by using the /D access specifier:
4121 COPY -/D,P:
4123 will print out the contents of the directory by copying the contents of
4125 the directory to the printer device, though invalidating RAM contents
4126 due to the additional buffering COPY performs.
4127 The LOAD command can be emulated by using the no-run specifier when you
4129 just want to load, but not to run an external command. Thus, LOAD foo‐
4130 bar and foobar/N are equivalent.
4131 FMS BOOTSTRAP PROCESS
4134 If the FMS is initiated by the built-in Os, and a disk is found active
4135 and usable, the following additional bootstrap steps take place:
4136 FMS Configuration
4139 The FMS tries to load and execute the binary load file D:CON‐
4140 FIG.SYS. This file should modify the FMS settings by writing
4141 into its configuration area. The FMS will then re-allocate buf‐
4142 fers according to its new settings. Note that this is the only
4143 way how to modify the FMS parameters since it is ROM based.
4144 Handler bootstrap
4147 Next, the FMS tries to load and execute the binary file D:HAN‐
4148 DLERS.SYS. This file should contain the bootstrap code for any
4149 additional boot-time handlers that must be linked into the sys‐
4150 tem. For example, this file could load and run the 850 interface
4151 box firmware (easiest by simply calling the Os vector BOOT850,
4152 $e48f).
4153 Command execution
4156 Last, the FMS runs the traditional D:AUTORUN.SYS file. This is a
4157 user defined binary load file that could contain about anything
4158 the user may consider.
4159 OS EQUATES
4162 In most cases, the built-in Os uses the same memory locations as the
4163 Atari 800XL ROM, though some extensions have been made. Note that mem‐
4164 ory cells reserved within the XL operating system for parallel port and
4165 tape usage are likely to be no longer in use. However, these should
4166 remain reserved for future versions of the Atari++ operating system.
4167 $15 FMSTMP
4170 Used by the FMS for various issues.
4171 $16 DIRENTRYOFFSET
4174 Used by the FMS to point into the directory buffer for the cur‐
4175 rently processed file.
4176 $1a FILECOUNTER
4179 In case a wildcard matches several files and the user specified
4180 a /1 to /9 access modifier to select one of these matches, this
4181 location records the user selection. This location stays at $ff
4182 if the FMS shall operate on all matches.
4183 $1b FREEDIRCODE
4186 Keeps the file number times four of the first free directory
4187 entry a new file could populate.
4188 $43 FMSPTR
4191 Temporary pointer variables for miscellaneous uses in the FMS.
4192 This pointer typically points to the directory entry of the cur‐
4193 rently processed file.
4194 $45 DISKBUFFER
4197 Points within the FMS to the VTOC buffer for the currently pro‐
4198 cessed disk drive.
4199 $47 FILEBUFFER
4202 Points within the FMS to the file input/output buffer for the
4203 currently processed file.
4204 $24e VECNMI
4207 The Os jumps thru this vector in case it detects an interrupt on
4208 ANTIC's NMI-input pin. This pin is routed to the RESET key on
4209 the 400 and 800 machines, and is open on the XL and later
4210 machines.
4211 $2b8 OVERRUNFLAG
4214 This flag is set by the E: handler in case the line is nearly
4215 full and the buzzer should be run.
4216 $318 SCREENSTACK
4219 This byte is traditionally used by SIO, and so it is by the
4220 built-in Os. It is, however, also used by the S: and E: handler
4221 to keep the stack pointer to make error handling easier.
4222 $3f5 FMSBOOTFLAG
4225 Specifies the FMS bootstrap modes and various other related
4226 issues as listed in the following table:
4227 Bit function
4229 ─────────────────────────────────────────────────
4230 Bit 0 If set, the next reset shall signal the
4231 cart a coldstart. This bit gets set by
4232 the command line processor in case the
4233 memory contents gets invalidated by the
4234 COPY command.
4235 Bit 4 If set, the FMS places MEMLO at the end
4237 of its globals instead at the end of the
4238 FMS buffers. User programs, most notably
4239 a CONFIG.SYS file may relocate FMS
4240 buffers elsewhere and may then select
4241 to set this bit. Never set by the FMS
4242 itself.
4243 Bit 6 Is set if the command processor shall
4245 be launched on the next warmstart.
4246 Bit 7 Is set if the FMS should be initialized
4248 on Reset. Note that the FMS no longer
4249 requires the DosInit vector.
4250 $3f6,$3f7 DUPVECTOR
4253 DupVector (hi) This address is jumped at instead of the cart run
4254 vector during a warmstart if bit 6 of the FmsBootFlag is set. A
4255 program that jumps thru DOSVECTOR ($a,$b) will set bit 6 of the
4256 FMSBOOTFLAG, then cause a reset which in turn will run the com‐
4257 mand processor thru this vector.
4258 The next addresses are only used if the FMS is initialized. They can be
4260 modified from the CONFIG.SYS file to change the FMS parameters when
4261 booting.
4262 $70a FMSDRIVEMASK
4265 Contains a bitmask that defines which drives should be address‐
4266 able. A one-bit enables the corresponding disk unit, a zero dis‐
4267 ables it. Bit #0 enables/disables drive 1, bit #1 controls drive
4268 2 and so on. The default value is 3, meaning a two-disk system
4269 is supported. Each supported drive requires 128 bytes additional
4270 storage.
4271 $709 FMSBUFFERS
4274 Number of file buffers the FMS shall allocate. This controls
4275 how many files can be opened at once. The default value is five,
4276 allowing to open at most five files at once. Each file buffer
4277 requires 128 bytes of storage.
4278 $779 WRITECMD
4281 The SIO command the FMS shall use for writing sectors. This can
4282 be either $50 ("P") for writing without or $57 ("W") for writing
4283 with verify. It is however suggested to use the file name exten‐
4284 ders "/V" and "/O" to switch between verify on and off instead.
4285 $70C,$70D DISKBUFFERBASE
4288 Points to the first disk buffer used by the FMS. The "CON‐
4289 FIG.SYS" file may change this base address to point elsewhere,
4290 in which case disk buffers will be allocated from this memory
4291 address on. If in addition bit 4 of FMSBOOTFLAG is set, the FMS
4292 init routine will neither try to increase MEMLO to point behind
4293 the FMS buffers, but will keep it at the end of its state flags.
4294 $712,$713 FILEBUFFERBASE
4297 This pair points to the first file data buffer within the disk
4298 buffers. It cannot be adjusted, but is always allocated by the
4299 FMS.
4300 $700 to $7ff FMS STATE FLAGS
4303 Addresses $700-$7ff except those above contain FMS state vari‐
4304 ables that remain undocumented.
4305 $800 FMS BUFFERS
4308 FMS buffers for drives and file buffers are allocated from $800
4309 up. In the default configuration, they extend up to $a7f, leav‐
4310 ing RAM from $a80 and up to the user. Thus, the memory footprint
4311 of the built-in FMS is much better than for DOS 2.0S. FMS buf‐
4312 fers may be relocated by adjusting DISKBUFFERBASE accordingly by
4313 a suitable CONFIG.SYS file.
4314
4317 Atari++ includes an emulated Basic ROM in case an original Atari Basic
4318 ROM image is not available. The Basic dialect emulated here closely
4319 reessembles the Atari Basic dialect and is to a major degree compatible
4320 to it.
4321 Basic++ is, however, quite a bit faster due smarter stack and branch
4323 handling, it is heavily bug-fixed, and slighly extended:
4324 DIR [filenspec]
4327 This statement lists the directory of the given drive, looking
4328 for the files that match the file specification in its argument.
4329 For example,
4330 DIR "D2:*.*"
4332 will list all files on the second disk drive. If no filename is
4334 given, DIR will list all files on the first disk. The DIR com‐
4335 mand is compatible both in its syntax and its internal encoding
4336 to the same TurboBasic command.
4337 LIST [filespec,][firstline[,[lastline]]
4340 A second notable extension is that the “lastline” argument of
4341 the list statement can be dropped while keeping the comma
4342 upfront. This instructs LIST to start listing at the line given
4343 by the first argument, but continue up to the end of the pro‐
4344 gram. This extension is identical to the extension of LIST in
4345 TurboBasic. For example,
4346 LIST 1000,
4348 will list all lines starting from line 1000 up to the last line.
4350 The remaining extensions are minor and consist mostly of bug-
4352 fixes, speed improvements and improvements of the numerical
4353 accuracy of the floating point model. They are described in more
4354 detail in the Basic++ manual.
4355
4358 Atari++ comes with a build-in mini-monitor that can be helpful for
4359 debugging programs, or for finding bugs in the emulator. The following
4360 section describes briefly the front-end and the commands of this moni‐
4361 tor, assuming that the emulator has been compiled with curses support.
4362 Otherwise, the front-end is less user-friendly (or even more user un-
4363 friendly than it used to be before, but that is another topic).
4364 ENTERING THE MONITOR
4366 The monitor is entered either by pressing F12 while the emulation is
4367 active, by pressing ^C in the shell that launched Atari++, or if the
4368 CPU core emulator crashes. The crash could be either due to an instruc‐
4369 tion that is not implemented, an instruction that would otherwise stop
4370 the CPU completely or an unstable instruction whose function depends on
4371 some floating bus signals that are hard or not at all emulatable. Other
4372 than that, Atari++ emulates all known stable “extra opcodesrq some
4373 lesser quality programs tend to use.
4374 Another way of entering the monitor is due to hitting a break point, or
4376 by finishing a single-stepped instruction.
4377 MONITOR COMMANDS
4380 The monitor is entirely command line driven. Commands are four charac‐
4381 ters long, non-case sensitive, with a possible abbreviation of one
4382 character. Commands furthermore have an optional extension given by a
4383 dot (.) and a single additional character. This extender typically
4384 modifies the command somewhat, or sets some parameter for the command,
4385 as for example the output format. The extender for each command is
4386 remembered by the command itself up to the next time the very same com‐
4387 mand is used. Hence, you won't need to type the same extender every
4388 time. Using the question mark “?” as extender lists the available
4389 extenders for the command.
4390 Most commands also remember the last address they operated on. If typed
4392 without arguments, they silently re-use the last address used. This is
4393 handy for disassembling long routines since you just have to re-type
4394 the disassembly command to continue the listing.
4395 ALGEBRAIC EXPRESSIONS
4398 The monitor is capable of evaluating simple algebraic expressions in C
4399 syntax containing the basic operators +,-,*,/, the binary operators
4400 &,|,^,~ the logical operators ||,&&,! , the comparisons <,<=,>=,==,!=
4401 and the shifts <<,>>. The precedence of the operators follows mainly
4402 the C syntax except that priority of the shifts has been “fixed” to
4403 follow more closely the (or at least my) intuition, brackets are sup‐
4404 ported with their obvious meaning. Furthermore, the contents of the
4405 registers are available as the algebraic expressions A,X,Y,P,S,PC. Oth‐
4406 erwise, numerical constants are understood in hex (sedecimal) notation.
4407 If a ca65 debug file is loaded (see ENVI.S below), then labels or
4409 equates can also be used in expressions; they are then substituted by
4410 the value they have been assigned to in the debug file.
4411 A nice gymmick are the indirection operators [],[].b,[].w with the
4413 first two being equivalent. They evaluate their contents as an address,
4414 and then return the contents of this (emulator) address as their value.
4415 The first two are byte versions reading a single byte, the latter is a
4416 word version that reads two bytes in little-endian notation to form a
4417 sixteen bit integer.
4418 COMMAND DESCRIPTION
4420 The following commands are available in the monitor:
4421 HELP=? This command prints a command summary.
4423 DUMP=D [expr]; extenders: A,S,V
4425 Dumps the memory contents at the address given by the argument
4426 or continuing the last dump. The A extender switches to mixed
4427 hex-ATASCII output, emulating inverse video as much as possible
4428 thru curses, the S extender uses hex-ANTIC screen code dumps.
4429 The V extender doesn't dump anything at all but rather sets the
4430 number of lines to dump in one go.
4431 EDIT=E [expr]; extenders: X,D,A,S,I
4433 Edit memory starting at the given address either in hex, deci‐
4434 mal, ATASCII or Antic Screen codes, respectively. For hex and
4435 decimal input, memory contents are lines separated by blanks,
4436 and the input is aborted by an empty line, i.e. by just pressing
4437 RETURN. For ATASCII and screen code editing, the text given as
4438 input is placed directly in the memory of the Atari, possibly
4439 first converting to the target format. The I extender doesn't
4440 edit any memory but toggles the seventh bit of the ATASCII resp.
4441 screen code entries on or off.
4442 FILL=L addr size; extenders: X,D,A,S,I
4444 Fill the given memory range, given by base address and size with
4445 a byte pattern. You will be prompted for the fill pattern sepa‐
4446 rately in a second stange: With the X extender, the byte pattern
4447 is given as a space-separated list of hexadecimal (sedecimal)
4448 byte values, with the D extender, this pattern is given in deci‐
4449 mal notation instead. Using the A extender allows to enter the
4450 bytes as ATASCII codes, and the S extender, last but not least,
4451 encodes the pattern in the ANTIC screen codes.
4452 The I extender toggles the seventh bit of the entered ATASCII or
4454 screen code pattern on or off. Its setting is ignored for hex or
4455 decimal input.
4456 MOVE=M from to size; extenders: S,C,A
4458 Move a memory block of the given size from the start location to
4459 the target location. Source and target may overlap, the move
4460 command will be smart enough to copy memory blocks correctly in
4461 all circumstances. The S extender will perform a simple memory
4462 copy operation within the current address space, no matter which
4463 one has been selected by the ENVI command (see below). The C
4464 extender, however, will move bytes from the selected address
4465 space into the address space as seen from the 6502. This allows
4466 you to copy data from the ANTIC space to the CPU space. The A
4467 extender works in the reverse direction by always writing into
4468 the ANTIC space.
4469 FIND=F [expr]; extenders: X,D,A,S,I,V
4471 Scans the memory starting at the given location for a byte pat‐
4472 tern, possibly filtering the pattern thru a mask. You are first
4473 prompted to enter the byte string to look for, and then for a
4474 possible mask, that must be either left blank or as long as the
4475 pattern entered first. If left blank, the byte string in memory
4476 must match the entered string precisely for a match. Otherwise,
4477 only the one-bits in the mask are significant and all zero bits
4478 in the mask are not compared against the search pattern. This
4479 allows, for example, scanning for a text in non-case-sensitive
4480 mode: Just set all pattern bytes to “5F” for ignoring case and
4481 inverse video bits.
4482 The extenders work similar to the extenders of the EDIT or FILL
4484 commands: X expects hexadecimal input, D requests decimal input,
4485 A allows ATASCII and S screen code patterns. The pattern mask,
4486 however, is always given in hexadecimal notation. As always, the
4487 I extender toggles the seventh bit on or off for the A and S
4488 extenders. Last but not least, the V extender defines the maxi‐
4489 mal number of matches that will be printed before the search is
4490 aborted.
4491 EVAL== expr; takes no extenders
4493 Evaluates its argument and prints the result on the screen.
4494 SKTB=K [expr];
4496 Prints a stack traceback, optionally starting at the given stack
4497 address. For this option, the monitor will find the locations
4498 from which the current routine has been called. The locations of
4499 the JSR instructions are printed on the screen.
4500 BRKP=B [expr]; extenders: S,C,D,E,A,L,V,W
4502 Controls breakpoints. Once a breakpoint is hit, and the break‐
4503 point is enabled, the monitor is re-entered. Breakpoints can be
4504 set in either RAM or ROM. They do not alter the memory at all
4505 but are rather emulated directly in the CPU core. Hence, they
4506 cannot interact with software reading or interpreting the code.
4507 BRKP.S installs and activates a breakpoint at the address given
4509 by its argument. BRKP.C removes it again. The D and E extenders
4510 disable, resp. enable breakpoints that have been set before. A
4511 disabled breakpoint is temporarely turned off, but remembered,
4512 and can be turned on later on.
4513 The V and W extenders install watch points. Unlike regular break
4515 points, the trapping condition is not execution of an instruc‐
4516 tion at a specific location, but the access of a specific memory
4517 address.
4518 BRKP.W installs a watch point, i.e. the monitor is entered as
4520 soon as a program tries to write to the target address. Reading
4521 does not trigger it. Watch points can be disabled and removed as
4522 all other break points.
4523 BRKP.V installs a read/write watch point that unlike the above,
4525 also reacts on read accesses to its target address.
4526 The A extender removes all breakpoints at once and the L exten‐
4528 der lists all breakpoints and their status, i.e. wether they are
4529 disabled or enabled.
4530 DLST=A [expr]; extenders: L,S,V
4532 displays the antic Display List and the ANTIC status. The L
4533 extender prints a disassembly of the ANTIC program, or short the
4534 Display List. This is useful for getting an idea how the screen
4535 is generated. The S extender prints the contents of the ANTIC
4536 register set, for example to find the start address of the dis‐
4537 play list. Finally, the V extender sets the number of lines the
4538 ANTIC disassembler prints in one go.
4539 UNAS=U [expr]; extenders: L,V
4541 This is the 6502 disassembler. The L extender does exactly this;
4542 it disassembles at the address given by its argument. The disas‐
4543 sembler knows all “extra instructions” of the 6502 and prints
4544 them as four character rather than three character opcodes.
4545 If a ca65 debug file has been (see ENVI.S below), then the dis‐
4547 assembler automatically substitutes numeric values with the con‐
4548 stants, labels and equates recorded in the debug file.
4549 The V extender sets the number of lines the disassembler prints
4551 at a time.
4552 RSET=P; extenders: W,C,I
4554 Various reset commands. The W extender warm-starts the emulator,
4555 the C extender runs into a coldstart. Both instructions also
4556 leave the monitor as its full working environment is reset as
4557 well. If you need to debug instructions directly following the
4558 cold-start sequence, consider using the -traceonreset on command
4559 line switch.
4560 Note that the warm-reset really holds the reset signal of the
4562 CPU. This is unlike the Reset Console Key on the Atari 800 and
4563 400 models work; they just raise a special Antic NMI signal and
4564 leave it to the Os to detect this signal and jump to the reset
4565 vector. This kind of reset is reached with the I extender,
4566 though note that the detection of this NMI interrupt has been
4567 removed in Os ROM of the XL and XE models.
4568 EXIT=X; no extenders
4570 Takes no arguments and no extenders and leaves the emulator
4571 immediately.
4572 GOPG=G; extenders: P,U,M
4574 Takes no arguments and re-starts the emulation at the current
4575 program counter value for the P extender. Hence, this leaves the
4576 monitor and continues emulation. For the M extender, the emula‐
4577 tion also continues, but the configuration menu is entered as
4578 soon as possible after leaving the monitor, as if F1 has been
4579 pressed. This may take as long as a vertical retrace of the emu‐
4580 lated screen, and some code might have been run when the menu is
4581 entered. The U extender, finally, runs the program until the
4582 stack pointer gets larger than its current value. This is useful
4583 to terminate a current subroutine call and to return to the
4584 calling function immediately.
4585 STEP=Z; extenders: S,I
4587 Single step thru a program. If used with the S extender, the
4588 simple interface is used and similar to the GOPG command, the
4589 program is run, but the monitor is re-entered immediately after
4590 execution of the command under the PC, printing the command that
4591 was executed last. This is most useful for debugging purposes
4592 and single-stepping thru critical sections of a program.
4593 If the I extender is selected, a full-screen graphical debugger
4595 is entered provided the curses library was available at compile
4596 time. If so, a full screen of disassembled code is printed and
4597 the monitor waits for further commands. The Z key single steps
4598 then, the N key works similar to the NEXT command (see below)
4599 and steps over subroutines and loops, the G key re-starts the
4600 program and leaves the monitor, the B key sets a break point at
4601 the current program location and, finally, the U command runs
4602 the emulated CPU until the stack pointer is increased, thus usu‐
4603 ally up to the end of the current sub-program.
4604 NEXT=N; no extenders
4607 Similar to STEP though this command does not step into subrou‐
4608 tines. For any operation that places data onto the hardware
4609 stack, this command will run the program up to the location
4610 where the data is again popped from the stack; if the current
4611 instruction is not a JSR instruction, then the emulator is run
4612 until the program counter of the emulated CPU gets larger than
4613 its current value. This is for example useful to complete a
4614 larger loop with a backwards branch at its end by just one moni‐
4615 tor command.
4616 STAT=T [comp]; extenders: L,S
4618 Prints status information about various system components,
4619 including internal hardware register sets, port settings and
4620 configuration. The L extender lists all system components for
4621 which a status information is available, and STAT.S followed by
4622 the name of this component prints the status of the mentioned
4623 component.
4624 SETR=S register=expr; no extenders
4626 Sets a CPU register to a specified value given by an expression.
4627 The syntax of this command is non-standard for convenience rea‐
4628 sons. Register and desired register contents are separated by an
4629 equals sign, and not by a blank. For example, SETR A=ff would
4630 set the contents of the accumulator to 255=0xff.
4631 REGS=R; no extenders
4633 displays the contents of the CPU in a brief listing. This com‐
4634 mand is ideal for the SPLT command explained next.
4635 SPLT=/ [cmds]; extenders: C,S
4637 This command is special as it modifies the behaviour of the mon‐
4638 itor and does not perform a direct action on the emulation com‐
4639 ponents. The S extender splits off the top part of the monitor
4640 output window and prints there the contents of the commands fol‐
4641 lowing the SPLT command. For example, SPLT.S R would continously
4642 display the register dump of the 6502 CPU on top of the screen.
4643 Several commands can be run at once by separating them with a
4645 colon. The split-off output is updated on each command, making
4646 the screen splitting an ideal feature for the single stepping
4647 and debugging. The C extender cleans and removes this split-off
4648 part of the screen again.
4649 ENVI=V [value]; extenders: A,L,S,C
4651 Controls various (currently one) monitor environment settings.
4652 The A extender controls the view on the memory. As the 130XE
4653 offers 128K of memory that can be selectively banked for the CPU
4654 and for ANTIC, it matters whether the memory is seen by the CPU
4655 or by ANTIC as both may have selected different banks for it.
4656 This environment switch toggles the view of the monitor onto the
4657 memory as either comming from ANTIC or from the CPU.
4658 L This extender expects a file name as argument. The status of
4660 the emulated CPU is then logged into the file, including the
4661 register set and the timing information, i.e. horizontal and
4662 vertical beam position. Note that this file may grow very fast
4663 and becomes huge shortly. To disable logging, supply an empty
4664 file name.
4665 S This extender loads a debug file into the monitor, which
4667 defines labels, equates and constants. This information is used
4668 by the disassembler and the expression evaluator; the former
4669 substitutes numerical values by their label names and hence
4670 makes the output of the disassembler more readable, the latter
4671 also accepts labels and equates as input and replaces them by
4672 their value. This environment setting accepts files in the
4673 “debugfile” format generated by the ca65 assembler. They are
4674 created with the --dbgfile command line option of the assembler.
4675 The ENVI.S command takes a single argument, namely the file name
4676 of the debug file to be parsed. Information in this file is then
4677 added to the internal label database of the monitor.
4678 C This extender clears the internal label database, i.e. it for‐
4680 gets all label, equate and constant names that have been defined
4681 by a ENVI.S command before.
4682 PROF=O; extenders: S,L,C,X
4685 This monitor command controls the built-in profiler, allowing
4686 you to find performance bottlenecks in machine language programs
4687 running on the emulated 6502. The S extender starts recording
4688 profile information. After issuing this command, return to the
4689 emulator with GOPG and start and/or continue execution of the
4690 program you want to profile. Re-enter the monitor any time you
4691 want to access the collected profile data.
4692 L lists the execution counts per memory, sorted in descending
4694 order. The first column of the profiler output lists the memory
4695 location, in hex or symbolic form, at which the profiled
4696 instruction was recorded. The next column shows the absolute
4697 count how often that location was accessed. The last column
4698 lists the percentage of how often the listed instruction has
4699 been executed compared to the overall instruction count col‐
4700 lected by the profiler. If several consecutive instructions have
4701 exactly the same hit-count, these instructions are not listed
4702 separately, only the first instruction of the instruction block
4703 is shown. Note that this command extender lists instruction hit
4704 counts, i.e. it performs a coverage analysis, and not a cycle
4705 count analysis.
4706 C lists the cumulative execution time of subroutines in cycles,
4708 listed in descending frequencies. Unlike the output of the L
4709 extender, this list shows the total number of cycles the CPU
4710 required to execute a subroutine, together with all the children
4711 it called. It sorts the output by cycle count, with the function
4712 taking the longest time on top. This is typically the main pro‐
4713 gram. The percentage of time the code spend in a subroutine is
4714 also shown.
4715 X This extender stops the profiler and clears the profiler data‐
4717 base.
4718
4721 /etc/atari++/atari++.conf
4722 The system global configuration files
4723 ~/.atari++.conf
4725 The user specific configuration file
4726 ./.atari++.conf
4728 The directory specific configuration file.
4729
4731 No emulator specific variables. Atari++ is controlled completely by its
4732 configuration files and command line arguments.
4733
4735 David Firth for his Atari800 emulator. Atari++ is not based on this
4736 earlier work, though influenced. Atari++ was entirely and completely
4737 rewritten from scratch, in C++, avoiding some of the constructional
4738 difficulties of David's work. Especially, the way how graphics output
4739 is constructed and how player/missile graphic priorities are generated
4740 is quite different from his implementation.
4741 Ron Fries for the Pokey emulation routine that got used in early
4743 releases of the Atari800 emulator. The strategy that has been utilized
4744 for sound build-up has been used in the pokey emulation of this emula‐
4745 tor as well, though the implementation details are a bit different and
4746 the overall quality of the sound emulation has been improved heavily.
4747 Specifically, high-pass filters, sound muting and anti-aliasing are new
4748 to the emulation model.
4749 Jean-loup Gailly and Mark Adler for the Z compression library that gets
4751 used if available for .gz compressed disk images.
4752 Sam Lantinga and the SDL group for the Simple DirectMedia Layer
4754 library, or short, SDL, that offers one of the possible front-ends of
4755 the Atari++ emulator if it is available.
4756 Jindroush and the Atari Cartridge Dumping project for providing insight
4758 into the details of the cart emulation. Specifically, SDX and XEGS cart
4759 emulation would have been impossible without him.
4760 Petr Stehlik and the remaining atari800 team for cooperation and for
4762 working out the licencing conditions of this emulator. Specifically, I
4763 thank Petr for keeping cool in the hot days of working out all the
4764 details of making this project available.
4765 Andreas Magenheimer and the ABBUC team for providing some hardware
4767 insight that was otherwise not available. Specifically, emulation of
4768 various bank switching logics is due to ABBUC.
4769 Jason Duerstock's for its analyzation of the RT8 cartridge. Unfortu‐
4771 nately, something seems to be still not quite right with it. The cur‐
4772 rent implementation in Atari++ uses a somewhat different route how the
4773 register assignment might work. This is all an educated guess, though.
4774 B. Watson for keeping pushing me to re-implement the math-pack; it's
4776 been done, now, providing a full free implementation of the Atari oper‐
4777 ating system.
4778 Konrad Kokoszkiewicz for finding and fixing many bugs in the emulation
4780 of floppy disks. Part of the "speedy" comments were broken or poten‐
4781 tially mis-interpreted, and floppy sizes weren't detected and supported
4782 correctly under all circumstances. Thanks, folks!
4783 Ralph "pps" for redesigning the Atari++ home page and hosting the whole
4785 project. Unfortunately, my employer can no longer host it when I moved.
4786 "Phaeron" for documenting many undocumented chipset and CPU features
4788 and for answering all my questions. Many of the improvements made in
4789 release 1.70 are due to his work.
4790
4793 DE RE ATARI
4794 by John Eckstrom, Michael A. Eckberg, Gus Makreas, Lane Winner
4795 and Elizabeth Hernaton.
4796 Das Atari Profibuch
4798 by Julian Reschke and Andreas Wiethoff, Sybex, 1985.
4799 6502 Assembly Language Programming
4801 by Lance A. Leventhal, McGraw-Hill, 1979.
4802 Atari Technical Documentation
4804 from The Atari Historical Society at www.atari-history.com
4805 Your Atari Computer
4807 by Lon Pool, Martin McNiff & Steven Cook, McGraw-Hill, 1982.
4808 German translation “Mein Atari Computer” by te-wi, 1983.
4809
4811 Thomas Richter (thor@math.tu-berlin.de)
4812
4814 An Atari800.
4815 atari++ Emulator atari++(6)