Altirra Hardware Ref Guide

[phaeron]

Wow, that part was totally wrong. Where the heck did bits 4-7 come from? Fixed for next edition, along with the stuff others found.

 

Altirra did not support a 64K + 192K configuration when that section was written, no. It does now, including the main bank aliasing. That section isn't very comprehensive, though, as the 8-bit FAQ contains many, many more expansions. I'll probably just stick to what's supported in the emulator along with a general note about other expansions using different combinations of bits. I haven't written code using extended memory myself and haven't researched it much.

[phaeron]

2019-12-30 edition:

 

Some minor fixes and oddball bits like the 400/800 System Reset NMI, but added new info in Disk Drives for the 810 Turbo, Astra 1001, Amdek AMDC-I/II, and the 6532 RIOT and 177X/277X FDC chips commonly used in disk drives.

 

The major new addition in this edition is two new appendices on the analog video and audio output paths in an attempt to establish a comprehensive and reasonably accurate model for Atari sound and color, based on scope measurements from the real hardware and research on historical NTSC color decoding.

 

HWMan-20191230.pdf

[phaeron]

2020-10-23 edition:

 

Couple of 80-column cards, the Bit-3 and the Atari 1090 80CVC.

 

New disk drive stuff: Atari 815, Percom AT88-S1, and Percom AT88-SPD. Some specific firmware revision related behavior for the 1050, Indus GT, and Percom RFD. 1050 diagnostic commands. How various drives respond to read commands when no disk is inserted (turns out a couple return NAK!).

 

Hopefully everything in the doc is OK. I had a failed attempt to upgrade to LibreOffice 7 which I had to roll back because it was way too buggy, and it autosaved with several drawings damaged that I had to manually fix in LibreOffice 6.3 again.

 

The attached copy is the same as the updated file on my website.

HWMan-20201023.pdf

[mono]

Thanks a lot for this manual.

I found small bug on the page 254 chapter 11.2. Common memory map (PBI devices section).

Now there is "The address pages $D1xx, D5xx, and D6xx are reserved for the currently active PBI device."

but IMHO should be "(...) pages $D1xx, $D6xx and $D7xx (...)".

[drpeter]

Good afternoon @phaeron

 

Thanks as always for this essential documentation of our beloved machines.

 

I've spotted a small apparent inconsistency in 2.1 Registers:

 

Break (B) flag

Bit 4 of the processor status register is the (B)reak bit and is used to indicate whether an IRQ or a BRK

instruction caused the IRQ routine to be run. It is set if the trigger was an BRK and cleared if it was a IRQ.

Contrary to both official and unofficial documentation, the B bit does not actually exist in the P register.

Attempting to clear bit 4 of P and reading the result back always gives a 1 bit. The only time the B flag is visible

is when the 6502 pushes the P register on the stack as part of interrupt handling. In that case, the P value

pushed onto the stack will have bit 4 cleared for a BRK.

[drpeter]

3 hours ago, drpeter said:

Good afternoon @phaeron

 

Thanks as always for this essential documentation of our beloved machines.

 

I've spotted a small apparent inconsistency in 2.1 Registers:

 

Break (B) flag

Bit 4 of the processor status register is the (B)reak bit and is used to indicate whether an IRQ or a BRK

instruction caused the IRQ routine to be run. It is set if the trigger was an BRK and cleared if it was a IRQ.

Contrary to both official and unofficial documentation, the B bit does not actually exist in the P register.

Attempting to clear bit 4 of P and reading the result back always gives a 1 bit. The only time the B flag is visible

is when the 6502 pushes the P register on the stack as part of interrupt handling. In that case, the P value

pushed onto the stack will have bit 4 cleared for a BRK.

 

Apologies, have reread this and think I misunderstood what this paragraph is saying.  When the P register is pushed to the stack, the BRK (B) flag (bit 4) of the value pushed is clear if the push occurs as part of interrupt handling.  Otherwise, if the P register is pushed to the stack as part of handling a BRK or for other purposes, the BRK (B) flag (bit 4) of the value pushed is always set.

Edited November 26, 2020 by drpeter

[drpeter]

@phaeron

 

Another query:

 

Mapped mode playfield DMA
The mapped graphics modes have three horizontal densities, resulting in fetches every eight clock cycles
(modes 8-9), four cycles (modes A-C), or two cycles (D-F). These occur on the first scan line of the mode. ANTIC
internally buffers the data so that modes that span more than one scan line do not need to fetch any data on
subsequent scan lines. This is used to powerful effect in the so called “GTIA 9++” modes, where mode F lines
are extended to four scan lines by vertical scroll trickery, resulting in one-fourth vertical resolution with one-fourth
the bandwidth requirements.
Mapped playfield DMA begins at clock 26, 18, or 10 depending on width.
Character mode playfield DMA
Character modes have two horizontal densities, resulting in name fetches every two clock cycles (modes 2-5) or
every four clocks (modes 6-7). The character names are fetched with the same timing as for mapped mode data,
at clocks 28, 20, and 12 for the various widths.

 

The colour-mapped charts of DMA timing also indicate that playfield DMA for mapped graphics modes begins at clock 28, 20 or 12.

Is this correct?

Edited November 27, 2020 by drpeter

[drpeter]

@phaeron

 

Apologies, this is another DMA timing issue that is confusing me:

 

 

 

This is Altirra's DMA analysis of a Rastaconverter display list (MODE E, LMS every line + PMG enabled, no fine scrolling).  The screen kernel makes an update to COLOR2, which appears at the 8th pixel, implying as I understand it that the write to COLOR2 completes on the the machine cycle contemporaneous with the 5th & 6th pixels (1 colour clock delay before the change appears on screen).

 

However, Altirra shows this cycle as being a screen memory fetch DMA cycle, with the 6502 frozen...

 

The pattern of DMA Altirra shows on this screenshot matches the one for Mode E in the Hardware Manual, but doesn't seem to match the emulated behaviour?  Or am I being dumb and missing something obvious?

 

Edited November 27, 2020 by drpeter

[phaeron]

9 hours ago, drpeter said:

@phaeron

 

Another query:

 

Mapped mode playfield DMA
The mapped graphics modes have three horizontal densities, resulting in fetches every eight clock cycles
(modes 8-9), four cycles (modes A-C), or two cycles (D-F). These occur on the first scan line of the mode. ANTIC
internally buffers the data so that modes that span more than one scan line do not need to fetch any data on
subsequent scan lines. This is used to powerful effect in the so called “GTIA 9++” modes, where mode F lines
are extended to four scan lines by vertical scroll trickery, resulting in one-fourth vertical resolution with one-fourth
the bandwidth requirements.
Mapped playfield DMA begins at clock 26, 18, or 10 depending on width.
Character mode playfield DMA
Character modes have two horizontal densities, resulting in name fetches every two clock cycles (modes 2-5) or
every four clocks (modes 6-7). The character names are fetched with the same timing as for mapped mode data,
at clocks 28, 20, and 12 for the various widths.

 

The colour-mapped charts of DMA timing also indicate that playfield DMA for mapped graphics modes begins at clock 28, 20 or 12.

Is this correct?

Ha, no, that text is wrong and the chart is correct. I probably screwed this up when I renumbered the cycles in the manual. The relative offsets are: +0 for character names, +2 for bitmap data, +3 for character data. I'll rewrite this section.

 

7 hours ago, drpeter said:

@phaeron

 

Apologies, this is another DMA timing issue that is confusing me:

 

 

 

This is Altirra's DMA analysis of a Rastaconverter display list (MODE E, LMS every line + PMG enabled, no fine scrolling).  The screen kernel makes an update to COLOR2, which appears at the 8th pixel, implying as I understand it that the write to COLOR2 completes on the the machine cycle contemporaneous with the 5th & 6th pixels (1 colour clock delay before the change appears on screen).

 

However, Altirra shows this cycle as being a screen memory fetch DMA cycle, with the 6502 frozen...

 

The pattern of DMA Altirra shows on this screenshot matches the one for Mode E in the Hardware Manual, but doesn't seem to match the emulated behaviour?  Or am I being dumb and missing something obvious?

What's missing is that the ANTIC>GTIA display is pipelined. It takes multiple cycles to process all of the memory and register data into output pixels across both chips, and crucially, that data is input into different points of the pipeline, with varying delays to the output. This means that writes on the same cycles to the bitmap memory or to the color registers will show up at different horizontal offsets. You can't see this from the DMA overlay because it only shows you one specific offset; it would require multiple offsets for each distinct kind of data you can write.

 

The manual is unfortunately still a little vague on how it specifies delays for each register type -- this only makes sense relative to some other delay. I need to go back and rework those into cohesive charts that show all of the delays for different register types together relative to cycle number and horizontal position.

 

 

 

[+Stephen]

Your level of knowledge of this hardware is simply stunning.

[drpeter]

2 hours ago, phaeron said:

What's missing is that the ANTIC>GTIA display is pipelined. It takes multiple cycles to process all of the memory and register data into output pixels across both chips, and crucially, that data is input into different points of the pipeline, with varying delays to the output. This means that writes on the same cycles to the bitmap memory or to the color registers will show up at different horizontal offsets.

OK, that makes sense.

 

Like the idea of a 'Grand Unified Theory' of pipeline timings to tie all this definitively together- it's been driving me nuts trying to get my head round it all!

 

Thanks ++++ for the response

[drpeter]

PS Apologies for anyone who might be confused by the above account- RastaConverter uses non-standard equates in its Assembly output, such that COLOR2 is equivalent to the more usual COLPF2, i.e. in RastaConverter Assembly output, COLOR2  refers to the hardware colour register on the GTIA chip, not the corresponding shadow byte in RAM.

 

Obviously, writing to the the RAM shadow of COLPF2 would not generally be expected to produce any in-scanline change in displayed colour, as this value would generally only be written to the actual GTIA register by the OS during vertical blank.

Edited November 29, 2020 by drpeter

[drpeter]

Minor errata from 7.1:

 

The Atari 8-bit computer series uses the same digital joystick used by the 2600 VCS. The direction sensors are
connected to four contiguous bits on the PIA. Ports 1 and 2 use port A, whereas ports 3 and 4 on the 600/800
use port B:

 

this should read 400/800

[mono]

Page 347 ANTIC CHBASE description:

 

Now it is

Quote

D7:D1 Bits 9-15 of character data base address (ANTIC modes 2, 3, 4 and 5)
D7:D2 Bits 10-15 of character data base address (ANTIC modes 6 and 7)

but should be:

Quote

D7:D2 Bits 10-15 of character data base address (ANTIC modes 2, 3, 4 and 5)
D7:D1 Bits 9-15 of character data base address (ANTIC modes 6 and 7)

Correct me if I'm wrong but I can't find PORTA description in PIA registers section. Page 337 contains SKSTAT description and next one describes PORTB.

 

Following there is lack of POTGO ($D20B) register on the page 354 with POKEY registers table.

Edited December 17, 2020 by mono
POTGO

[phaeron]

45 minutes ago, mono said:

Page 347 ANTIC CHBASE description:

 

Now it is

but should be:

Correct me if I'm wrong but I can't find PORTA description in PIA registers section. Page 337 contains SKSTAT description and next one describes PORTB.

 

Following there is lack of POTGO ($D20B) register on the page 354 with POKEY registers table.

Ah, thanks, I've fixed the CHBASE/PMBASE descriptions and added the POTGO register to the table. I didn't have PORTA in the detailed listings because its meaning depends almost entirely on what you have plugged in, but I guess it wouldn't hurt to add.

[sup8pdct]

ATR8000 responds to Z device. commands are Read memory, Write memory, Set location and Goto address. I have used that to send atr the cpm system create file to create a cpm system disk.

 

Also in the printer section. All printers respond to P1. however other Atari direct printers respond to unique printer numbers as well.

850      P2:
1025    P3:
1020    P4:

1027    P5:

1029    P6:

not sure about the X?? series tho.   James

[ijor]

Quote

On power-on or reset, ANTIC automatically clears the following items:

   -   Refresh row address counter

...

Chapter 4 - ANTIC47

 

That is not accurate. It is cleared, or more correctly, it is supposed to be cleared, on power-on only. Not on hardware reset. And likely by design because you don't want to disrupt ram refresh operation during reset.

 

Should probably be included together with the vertical and horizontal counters that you comment about the power-on circuitry that doesn't seem always to work.

[phaeron]

59 minutes ago, ijor said:

That is not accurate. It is cleared, or more correctly, it is supposed to be cleared, on power-on only. Not on hardware reset. And likely by design because you don't want to disrupt ram refresh operation during reset.

 

Should probably be included together with the vertical and horizontal counters that you comment about the power-on circuitry that doesn't seem always to work.

Your re-schematics show the refresh counter being tied to the synchronized reset signal, is that not correct?

[ijor]

12 minutes ago, phaeron said:

Your re-schematics show the refresh counter being tied to the synchronized reset signal, is that not correct?

It is the same power up reset signal that attempts to reset the horizontal and vertical counters.

 

That circuit that looks like a synchronization chain it's really a power up detector, or again, it attempt to do so. If you analyze the first NOR of the circuit, the one with three inputs, it would assert only if external resets toggles too fast. That should not happen, except at power up before the clock stabilizes.

[phaeron]

2021-10-02 edition:

• System architecture
  • Added brief overview of top-level system architecture.
• CPU
  • Expanded discussion of flags.
• ANTIC
  • Fixed erroneous starting cycles for playfield DMA in the text (the charts were correct).
• POKEY
  • Clarified some details about counter timing and distortion selection.
  • Added section on two-tone counter timing.
• Accessories
  • Note on XEP80 baud rate limits, row advance timing anomaly, and delete line behavior.
• Cartridges
  • New section on SIDE 3.
• Serial I/O bus
  • New section on 820 Printer.
• Disk drives
  • Removed Indus GT from list of disk drives that do not update PERCOM block on density detection.
  • Expanded information on PERCOM disk drive firmware revisions.
• Physical disk format
  • Added measured capture range for bit cell periods.
• Reference
  • Fixed swapped mode reference for the CHBASE register.
  • Fixed missing POTGO register in register listing.

HWMan-20211002.pdf

[oo7]

13 hours ago, phaeron said:

2021-10-02 edition:

• System architecture
  • Added brief overview of top-level system architecture.
• CPU
  • Expanded discussion of flags.
• ANTIC
  • Fixed erroneous starting cycles for playfield DMA in the text (the charts were correct).
• POKEY
  • Clarified some details about counter timing and distortion selection.
  • Added section on two-tone counter timing.
• Accessories
  • Note on XEP80 baud rate limits, row advance timing anomaly, and delete line behavior.
• Cartridges
  • New section on SIDE 3.
• Serial I/O bus
  • New section on 820 Printer.
• Disk drives
  • Removed Indus GT from list of disk drives that do not update PERCOM block on density detection.
  • Expanded information on PERCOM disk drive firmware revisions.
• Physical disk format
  • Added measured capture range for bit cell periods.
• Reference
  • Fixed swapped mode reference for the CHBASE register.
  • Fixed missing POTGO register in register listing.

HWMan-20211002.pdf 1.91 MB · 45 downloads

Just a heads up the link on your website still says 2018-08-12 even though its linked to this version.

[phaeron]

2 hours ago, oo7 said:

Just a heads up the link on your website still says 2018-08-12 even though its linked to this version.

Yeah I know, lazy. There's only one link on the website and it always points to current.

 

[Keatah]

Avery how about the Altirra Programmer's Reference Guide? The last version I have on hand is the 2019-03-09 Edition. Want to make a link for that too?

[flashjazzcat]

Page 165: should be Jonathan Halliday, not Holliday.

 

But thanks for this fantastic update; SIDE3 stuff is of course most appreciated.

[oo7]

4 hours ago, phaeron said:

Yeah I know, lazy. There's only one link on the website and it always points to current.

 

Told you in case it was an oversight. And lol no not lazy. The amount you have done amazes me. Im being serious. My wife uses altirra as well (she only uses it for running her childhood games, she grew up with a 400) and just last night i was trying to explain to her the amount of dedication behind your project and how lucky people are that people like you share this with us.