# MNT ZZ9000 FW2.0 Concept
## Preview/Developer Release (1.9a1...n)
Intermediate Version 1.9alpha which moves development focus away from ZZ9000OS over to the kernel module.
Main problem: Second system effect. There is a wealth of functionality in ZZ9000OS that needs to be ported. Porting every and each feature will take a long time.
- Complex RTG drawing/acceleration functions
- RTG mode/resolution switching
- Amiga video capture ("videocap") incl. switching between native and RTG
- USB Storage driver
- Ethernet packet driver
- Extra 256MB Zorro RAM
- Bidirectional DMA access from FPGA to ARM memory
- **Memory window:** When integrating with Linux, we must make sure that all (DMA) accesses via the FPGA are contained in a fixed memory window, so Linux memory does not get corrupted. This is already prototyped. We need to decide the size and structure of this window including all special buffers for things like video capture, block and ethernet buffers. The linux module currently allocates a 64MB CMA block (needs kernel cma parameter).
- **Proposition:** Make this memory window 128MB, since there seemed to be some extreme difficulties with autoconfig handling PICs of any size except for 128MB and 256MB, possibly larger, but 64MB and below caused some very strange memory range issues and reboot loops. This would leave P96 with a comfortable 48MB for the "video RAM" reported to the P96 driver, and USB/eth buffers could live at the very end of the memory space. In addition, the last 64MB would be available for any of the advanced video/audio acceleration functionality. (Which, granted, nothing really uses.)
- *Thought:* Actually, USB and eth buffers only need to be out of the way of anything else accessing memory, these are currently mapped to the end of the 1GB address range, I believe. The reason they need to be out of the way of anything else is because otherwise anything accessing those memory causes the ARM CPU to go into some data something interrupt that it can't actually get out of. If on the other hand these no longer have to be assigned through the Vivado address editor, that ARM interrupt wouldn't be as much of an issue.
- **AXI DMA:** The address of the shared memory block (containing framebuffer and other buffers) is dynamic as it is allocated by the linux kernel module. In the current implementation, all Zorro reads and writes are translated by the kernel module to offsets from the main buffer address. This works fine, but for AXI DMA, there is no filtering by the ARM side. We need to pass the base address and window size to the FPGA via a register at Linux module startup time. This is now already prototyped for the videocap function: the kernel module can set the address and pitch of videocap and turn it on and off.
- This feels like a Linux side thing, but we already know both the size, format and memory offset of the current *RTG* frame buffer (if RTG is active) based on data provided by P96. The problem with lack of AXI DMA is mostly one of performance, since non-DMA access tops out at ~3MB/sec, while AXI DMA access comfortably maxes out the usual 10MB/sec limit.
- **Proposition:** Make Z3 Fast RAM optional, though I believe that any Fast RAM mapped without AXI DMA enabled will be very much useless in terms of performance. However I also question the need for 256MB of Fast RAM on an Amiga of any kind... but people will dispute me on this. :D
- **Framebuffer and Input Device Sharing:** How do we organize framebuffer sharing between Linux and Amiga side? This is mostly a UI/UX design decision. As ZZ9000 is an Amiga product, the AmigaOS side should be the primary interface.
- In the first version, we could reserve one 1280x720 (example) screen buffer for Linux /dev/fb0 near the end of shared framebuffer memory. This requires a helper on the Amiga side (based on `zz9k-new`):
- [ ] Helper opens a dummy Intuition screen with 1280x720 resolution
- [ ] Whenever the screen is activated, switch VDMA offset to Linux framebuffer instead via register
- [ ] Whenever the screen is active, grab Amiga mouse and keyboard input (raw, already implemented) and forward to Linux virtual mouse and keyboard devices with scancode conversion (already implemented)
- **Storage Sharing:** This is a question mark. I would leave this out of FW1.9a in favor of networking and layer storage on top of that (FTP/NFS/SAMBA/SSH).
- **Network Sharing:** Networking will be primarily driven by the Linux side. The Amiga side should benefit from Linux' networking capabilities.
- [ ] How do we implement a shared network device?
- (Needs research) TUN/TAP device in the linux module that has ethernet buffers inside the shared memory window
- **Minimum Viable P96 Accel and Videocap:** The most important RTG acceleration functions should be ported over to the kernel module:
- [ ] Setting all screen modes and color depths
- [ ] Videocap by default with PAL/NTSC and interlace support
- [ ] Block copying and filling
- [ ] BlitTemplate/BlitPattern without DMA
- *Thought:* The easiest way to do this would most likely be to have the first 128MB of RAM sectioned off for use only by what's traditionally known as the "RTG portion" of the ZZ9000, although this has historically been the part that handled USB storage/ethernet as well. As long as Linux can catch register reads and writes, this will work fine even for the current AXI DMA RTG variant. This can always be mmaped on the Linux side for easy access as a shared memory region (for instance in order to find the position of the main ZZ9KGfx struct).
- *Thought II:* If RTG DMA is disabled in the P96 driver, DMA or not wouldn't matter all that much, aside from faster register writes.
- **Boot Time:** A typical systemd-based Linux userland needs a while to boot from SD card. This is an unacceptable delay for an Amiga user. The boot time needs to be optimized and videocap must be available as early as possible.
- [x] ~~Main outstanding challenge~~ (solved): Port the HDMI I2C pokes over to the kernel module. Maybe needs a second driver that attaches to I2C, or we move the whole module as a I2C driver into the DTS.
- **Reset:** We now have two systems that can reset independently from each other. I think a Linux system typically does not need rebooting, but Amiga, due to lack of memory protection, is crashy and reboots often. I think we can recognize Amiga resets on the Linux side and return services to sane defaults.
- **TTY:** If things go wrong or you need to examine the Linux system, you can use zztty, which is a virtual serial port connection between the AmigaOS and Linux sides. This is implemented but potentially buggy and/or slow. Needs someone with expertise to debug and optimize, esp. on the Amiga side.
- **Audio:** There isn't yet an audio module for ZZ9000. The easiest proof of concept would be to select a USB audio device that can mix in the analog audio from the Amiga side.
- [x] proof of concept with USB audio interface works, but needs powered USB hub (at least my amiga has unstable 5V)
- **Zorro III Fast RAM:** This is a pretty tough one. While it would by far be the easiest way to share data between Linux and Amiga, plus a very fast way to transfer data from the Linux side to the Amiga side without a lot of complicated register queries for memory offsets with relevant data, it would never work on boot without having a memory range partitoned off for it. While I feel that 768MB would likely be enough for Linux, some people may not agree and would argue that having 896MB available would be the sweet spot, the users that want as much RAM as possible available to Linux may not care very much for the Amiga side, other than being able to run all the software that it usually does without any major enhancements. (Aside from RTG output.)
- This would also open up to not section off any memory for RTG and just have Linux dynamically allocate it. (Since it takes a while for the Amiga to boot up anyway, and to get into an RTG mode on top of that.)
- It would (just like before AXI DMA access was added) be a lot slower, but that might not matter too much for a user that primarly uses Linux.
## Beta Releases (2.0b1...n)
- Bring back all acceleration functions and ensure (mostly) P96 speed parity
- Bring back splitscreen
- Block device integration (if it makes sense vs. internal networking)
- Ability to blit (part of) Linux screen into Amiga workbench window, acting similar to a (fast) VNC or VM session
- Ability to blit or overlay videocap on Linux screen. Possibly implement V4L2 device if we find someone with experience.
- Headless acceleration services implemented on the Linux side, made available to Amiga applications/datatypes (de/compression of images, sound formats etc). There is no design concept for this yet.
- Clipboard integration:
- On Amiga side, introduce a commodity that watches for clipboard (copy) actions and forward them to the X clipboard on the linux side. For paste operations, query linux side clipboard.
- New FPGA side register to query for available/initialized Linux features.
- If something's not available directly at boot, such as file systems mounted on the Linux side, memory allocated for something, this register can be written/read to indicate which features are currently available/enabled.
## Release Goals (2.0)
- Possibly dedicated audio codec PCB and backplate
## Secondary Strategic Goals
- We would like to turn the technology in ZZ9000 into a small (open source) box that serves as a 2D video card/HDMI adapter for USB2/3 hosts, and as a digital RGB capture functionality with a modular cable for other retro systems.