Port system documentation updated

[TheSMoG]

Check the changes here; reflect changes in the current core 2.00.11

https://www.specnext.com/tbblue-io-port-system/

[Stefan123]

Nice that you also added a table of all the ports, very useful to have that information in one place

[TheSMoG]

Nice that you also added a table of all the ports, very useful to have that information in one place

Yes it was missing

[Ped7g]

In "(R/W) 0x06 (06) => Peripheral 2 setting:" ... last line "Audio chip mode (00 = AY, 10 = YM, 10 = Disabled)" ... that's @10 "10" values, which is a one too many.

In "(R/W) 0x17 (23) => Layer2 Offset Y" - any chance to define in documentation, what happens for values above 191? Or do you want to keep it "UB"? (I mean, I can understand if you want to keep it undefined for possible changes in future, but then UB explicitly written helps people like me, who are partially OCD )

(and "(R/W) 0x33 (51) => LoRes Offset Y" is even more interesting, if the behaviour is specified for 0x17, then if it will survive the half-pixel adjustment for 0x33)

Same question for L2-clip-window Y1 and Y2, and also what happens when Y1 > Y2 and/or X1 > X2, makes the L2 invisible, or will it confuse the HW and random effect happens ("UB")?

Reading about "(R/W) 0x40 (64) => Palette Index" ... wait, in case one does use custom palette, even in Layer2+LoRes combination, the border colours are still picked from ULA 128..135 colours (which is also LowRes palette, right?)? That should probably get big WARNING letters to catch attention of anyone designing their custom palette ... so they will find it in couple of hours after wondering why their colour cycling animation of background is flashing the borders as well... )

In "(R/W) 0x4A (74) => Transparency colour fallback" there is "(0 = black on reset on reset)" ... that's 2x "on reset".

Also from the text it's not 100% clear, if it's index into palette, or one more extra RRRGGGBB colour, outside of any palette, seems to me like extra 8 bit colour outside of palette (actually it's like 90% clear, but adding that RRRG... would make it 100%).

In "(W) 0x61 (97) => Copper control LO bit" ... the comment "After the write, the index is auto-incremented to the next memory position." ... shouldn't it be rather at previous 0x60 paragraph?

And question about 0x62... so if the copper is in the middle of something, you can set up only LO bits of index, otherwise write into b7-6 of HI register would cause the copper either stop or restart? It's sort of missing some "just change the index but don't affect current execution mode" variant.

####

Thanks for update, seems now quite complete, nice. Now it asks for some hyperlinks to more detailed descriptions for complete newcomers, or for old Speccy coders who forgot how some old ports work (like me). But those would require first some pages with the detailed info, like sprites and sounds do have articles already, so that's possible to interlink.

[Black_Cat]

I have a few comments:
1) Ports #BFFD, #FFFD have decoding conflict. For exUSSR computers, this conflict is resolved as follows:
| |*||1|1|0|X|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xdffd |ZX Spectrum Profi memory |
|*|*||1|1|1|X|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xfffd |AY reg |

2) Port group # xxFD conflicts with ports #F1, #F9. This is due to the incorrect decoding architecture in ZX Next. For a true ZX Spectrum Altwasser architecture, all system ports must have the lowest decoding priority and peripheral ports, respectively, a higher priority. This is achieved by using the IORQGE signal. Therefore, it is wrong to simultaneously decoding peripheral device ports together with system ports #FE, #xxFD. You must first decoding the ports #F1, #F9, and only if these ports are not selected, allow decoding of system ports. In this case, the resolving signal IORQGE is generated only by decoding the address and signal M1 / =1. The IORQ / signal is not used to generate an IORQGE enable signal.

3) Port address #57 Sprite attributes was chosen unsuccessfully. This address is used in the Z-controller to access the SD card. Please select a different address that does not conflict with the equipment used by exUSSR. I would also not recommend using the address #5B.

[Alcoholics Anonymous]

I have a few comments:
1) Ports #BFFD, #FFFD have decoding conflict. For exUSSR computers, this conflict is resolved as follows:
| |*||1|1|0|X|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xdffd |ZX Spectrum Profi memory |
|*|*||1|1|1|X|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xfffd |AY reg |

Ah, thanks for that. We didn't know how or if the conflict was resolved on the existing machines.

2) Port group # xxFD conflicts with ports #F1, #F9.

There's no conflict in the next as priority is given to the complete decoding of 0xf1 and 0xf9.

3) Port address #57 Sprite attributes was chosen unsuccessfully. This address is used in the Z-controller to access the SD card. Please select a different address that does not conflict with the equipment used by exUSSR. I would also not recommend using the address #5B.

I looked it up and can see the z-controller is probably fairly important but I think it's too late to change port 0x57. Software has already been published and shipped using it. I think disabling the sprite ports when using the z-controller would be the best way to do it.

[Alcoholics Anonymous]

In "(R/W) 0x17 (23) => Layer2 Offset Y" - any chance to define in documentation, what happens for values above 191? Or do you want to keep it "UB"?

The last time I tried it, the hw fetched layer 2 data past the end of the 48k that layer 2 occupied. It's undefined behaviour

Same question for L2-clip-window Y1 and Y2, and also what happens when Y1 > Y2 and/or X1 > X2, makes the L2 invisible, or will it confuse the HW and random effect happens ("UB")?

I haven't actually tried it (and I wish I did because at one point I was erroneously complaining about getting a single pixel when x1=x2 and y1=y2) but it looks like layer 2 will just be invisible.

Reading about "(R/W) 0x40 (64) => Palette Index" ... wait, in case one does use custom palette, even in Layer2+LoRes combination, the border colours are still picked from ULA 128..135 colours (which is also LowRes palette, right?)?

That's right! And I'm sure it will come as a surprise to someone palette animating those ula indices.

In "(R/W) 0x4A (74) => Transparency colour fallback" there is "(0 = black on reset on reset)" ... that's 2x "on reset".
Also from the text it's not 100% clear, if it's index into palette, or one more extra RRRGGGBB colour, outside of any palette

It is an RRRGGGBB colour - the language has hopefully been consistent where colour is used to mean colour and index for index into a palette.

In "(W) 0x61 (97) => Copper control LO bit" ... the comment "After the write, the index is auto-incremented to the next memory position." ... shouldn't it be rather at previous 0x60 paragraph?

Yes I think that has been wrong for a while.

And question about 0x62... so if the copper is in the middle of something, you can set up only LO bits of index, otherwise write into b7-6 of HI register would cause the copper either stop or restart? It's sort of missing some "just change the index but don't affect current execution mode" variant.

What's not mentioned there is that if bits 7:6 do not change, the index will not reset. If you are in mode 01 and you want to reset the instruction index to 0, you will first have to stop the cooper (mode 00) and then start it again (mode 01).

[Alcoholics Anonymous]

I have a few comments:
1) Ports #BFFD, #FFFD have decoding conflict. For exUSSR computers, this conflict is resolved as follows:
| |*||1|1|0|X|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xdffd |ZX Spectrum Profi memory |
|*|*||1|1|1|X|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xfffd |AY reg |

We did some testing with this arrangement and found that afxplayer wrote to port DFFD accidentally while sending output to the AY. An extra bit in the decoding of port DFFD solves that problem. But thanks again, the conflict between port FFFD and DFFD is fixed up.

| |*||1|1|0|1|Χ|Χ|Χ|Χ|Χ|Χ|Χ|Χ|X|X|0|1| 0xdffd |ZX Spectrum Profi memory |

[Ped7g]

In "(R/W) 0x17 (23) => Layer2 Offset Y" - any chance to define in documentation, what happens for values above 191? Or do you want to keep it "UB"?

The last time I tried it, the hw fetched layer 2 data past the end of the 48k that layer 2 occupied. It's undefined behaviour

Ok, so just document it like UB, so it's clear one should not expect any particular effect in future and that it may change per revision of core.

I haven't actually tried it (and I wish I did because at one point I was erroneously complaining about getting a single pixel when x1=x2 and y1=y2) but it looks like layer 2 will just be invisible.

I got a bit crazy idea, which would probably require extra HW implementation ... been pondering on it for a while, I can actually generalize it, let's say the clip window is [x1,y1,x2,y2] (like now), and the rules are:

should_draw_pixel(x,y) = ((x1 < x2) ^ ((x1 <= x) ^ (x <= x2))) && ((y1 < y2) ^ ((y1 <= y) ^ (y <= y2))) (^ is XOR, && is AND)

Now for classic clip window like [10,10,100,100] you will get same behaviour as current system, i.e. pixels are displayed only inside the clip window.

Bur for clip window like [100,10,10,100] (x2 < x1) it will clip the inside part (i.e. for L2, the ULA is visible then above/under and in middle, L2 is visible left/right in the middle part) and for clip window like [100,100,10,10] (both x2 < x1 and y2 < y1) it will make content visible in corners only (i.e. for L2 the ULA is visible in "cross" in middle, while L2 is visible in corners. May be handy for animated screen transformations...

But then clip window can't be used to disable plane display, the real disable has to be used for that.

----

One more question, I haven't seen it document anywhere, how does clip window relate to the scrolling registers? I guess the clipping applied absolutely (without scrolling) makes sense for more use cases (although I can imagine some extra use case where scrolled clip would be nice, but generally for games like side scrolling you want clip window fixed, while graphic moving under it by hw scroll). Yeah, sounds quite obvious when I put it like that.

[sol_hsa]

should_draw_pixel(x,y) = ((x1 < x2) ^ ((x1 <= x) ^ (x <= x2))) && ((y1 < y2) ^ ((y1 <= y) ^ (y <= y2))) (^ is XOR, && is AND)

6 adders, 6 logic ops. No idea how tight the fpga is at the moment, though..