fox32/docs/io_bus.md

I/O bus

The I/O bus is accessed using the in and out instructions. Every access is 32 bits wide; there is no byte-addressing on the I/O bus and addresses don’t have to be aligned to multiples of four.

When a peripheral has multiple instances (e.g. 32 display overlays, 4 disks), the lowest bits of the address usually indicate the instance number, while higher bits indicate the function to be performed.

start	end	description
0x00000000	0x00000000	serial port
0x80000000	0x8000031f	display
0x80000400	0x80000401	mouse
0x80000500	0x80000500	keyboard
0x80000600	0x80000600	audio
0x80000700	0x80000706	RTC and uptime
0x80001000	0x80005003	disk
0x80010000	0x80010000	power controller

0x00000000: Serial port

0x00: Data register

Writing to this register outputs the lowest 8 bits as a byte on the debug serial port (stdout in case of the fox32 emulator). If necessary, the CPU is stalled long enough to ensure that the byte is output rather than discarded.

0x80000000: Display

The display controller manages a background framebuffer and 32 overlays, and composes them into the picture seen on screen.

The background framebuffer is located at the fixed RAM address 0x2000000, or 32 MiB. The screen resolution is 640x480 (307200 pixels, 1228800 bytes).

The pixel format is RGBA. The alpha channel determines transparency in overlays insofar that a non-zero alpha value causes a pixel to be fully opaque and a zero alpha value causes it to be fully transparent.

When multiple overlays are active at a specific pixel position, the highest numbered overlay that provides an opaque pixel “wins”: Its pixel RGB value is output on screen.

0x00-0x1f: Overlay position

bits	description
31:16	Y (vertical) position
15:0	X (horizontal) position

0x100-0x11f: Overlay size

bits	description
31:16	height (vertical size)
15:0	width (horizontal size)

0x200-0x21f: Overlay buffer pointer

RAM address of the framebuffer for this overlay.

0x300-0x31f: Overlay enable

• Write non-zero to enable this overlay, zero to disable
• Read 1 if enabled, 0 of disabled

0x80000400: Mouse

The mouse position and button states can be read and written, but hardware may change them on incoming mouse events.

0x00: Button states

bits	description
2	mouse button is currently held
1	mouse button has been released
0	mouse button has been pressed

0x01: Mouse position

bits	description
31:16	Y (vertical) position
15:0	X (horizontal) position

0x80000500: Keyboard

0x00: Get key event (read-only)

Read this register to get a key event from the key event queue, or 0 if none is currently available.

bits	description
8	0=pressed, 1=released
7:0	PC-compatible keyboard scancode

0x80000600: Audio

TODO

0x80000700: Real-Time Clock (RTC) and Uptime

offset	description
0x00	year (e.g. 2023)
0x01	month (1-12)
0x02	day (1-31)
0x04	minute (0-59)
0x05	second (0-59)
0x06	milliseconds since startup

0x80001000: Disk

The disk controller supports four disk ports. Each of them may be connected to a disk (or not) at any time.

Disks are organized in sectors of 512 bytes each.

0x80001000-0x80001003: Disk size (read-only)

Read this register to get the disk size in bytes.

0x80002000-0x80002003: Buffer pointer

Address of RAM buffer to be used for read/write transfers.

0x80003000-0x80003003: Initiate disk read (write-only)

Write a sector number to this register to initate a disk read from the specified sector. The CPU is stalled until the read completes.

0x80004000-0x80004003: Initiate disk write (write-only)

Write a sector number to this register to initate a disk write to the specfied sector. The CPU is stalled until the write completes.

0x80005000-0x80005003: Remove disk (write-only)

Write any value to this register to remove or eject the specified disk.

0x80010000: Power controller

0x00: Poweroff

Write 0 to this register to power the computer off (or terminate the emulator).

Poweroff does not take effect immediately, so software should do something safe (such as spinning in a loop) after triggering the poweroff.