Foenix F256 / Wildbits/K2 Wiki - User contributions [en]

Use the Core2x

2025-12-27T08:26:22Z

Minstrel Dragon: Added link to Core2X introduction video

New Features Documentation for the Core2x for K2 and Jr2

[https://256-foenix.us-east-1.linodeobjects.com/F256K2x_Cores%2FCore2x_ShortFormSpec_Aug7th.pdf Core2x_ShortForm_Documentation]

Stefany Allaire's video on the Core2x features:

https://www.youtube.com/watch?v=ECu1Z3AwZEw

Use the Sam2695 Dream MIDI chip

2025-07-04T11:18:52Z

Minstrel Dragon: Add examples for panning MIDI channels to left and right of stereo field

== Sam2695 Dream IC is in the F256K2 and F256Jr2 only ==

The SAM2695 datasheet can be found in this goodies github repo: https://github.com/Mu0n/F256MiscGoodies/blob/main/datasheets/SAM2695.pdf

The MIDI specification from MIDI.org can be found in the organization's website https://midi.org/specs

There are many tutorials and overview of useful MIDI commands, here is one of them: https://www.cs.cmu.edu/~music/cmsip/readings/MIDI%20tutorial%20for%20programmers.html

Here's a reference list of General MIDI instruments by number: https://www.ccarh.org/courses/253/handout/gminstruments/ 
{| class="wikitable"
|+
!Register Name
!Address
!Description
|-
|MIDI_STATUS
|0xDDA0
|Read: Bit[1] = Rx_empty, Bit[2] = Tx_empty
|-
|MIDI_FIFO_DATA_PORT
|0xDDA1
|read and write Data Port
|-
|MIDI_RXD_COUNT_LOW
|0xDDA2
|Rx FIFO Data Count LOW
|-
|MIDI_RXD_COUNT_HI
|0xDDA3
|Rx FIFO Data Count Hi - Only the 4 first bit are valid
|-
|MIDI_TXD_COUNT_LOW
|0xDDA4
|Tx FIFO Data Count LOW
|-
|MIDI_TXD_COUNT_HI
|0xDDA5
|Tx FIFO Data Count Hi - Only the 4 first bit are valid
|}

=== Steps in order to use MIDI OUT ===

'''MIDI OUT picks data from your program and sends it out to the SAM2695 chip as well as the MIDI Out port to an external device.'''

Send a MIDI command to 0xDDA1 by writing all the bytes of the MIDI command in rapid sequence.


Note On as a moderately heavy middle C to channel 0: 0x90, 0x3C, 0x40 
Note Off as a softly released middle C to channel 0: 0x80, 0x3C, 0x00 
Panning channel 0 to the left of the stereo field: 0xB0, 0x0A, 0x00 
Panning channel 2 to the right of the stereo field: 0xB2, 0x0A, 0x7F 
Changing the instrument of channel 2 to a Slap Bass 1: 0xC2, 0x24 
Shut the 6th channel off: 0xB5, 0x7B, 0x00

=== Steps in order to use MIDI IN ===

'''MIDI IN refers to an external MIDI controller (i.e. piano keyboard) that sends MIDI formatted bytes into the Foenix' MIDI in port'''

First, verify if there are bytes pending in the FIFO buffer by checking if MIDI_STATUS register bit 0 is set to 1 - if so, then create the following loop with steps 2,3,4 
Second, read MIDI_RXD_COUNT_LOW as the low byte of a 16-bit value and MIDI_RXD_COUNT_HI as the high byte of the same value to see how many loop iterations must be done 
Third, read a byte from MIDI_FIFO_DATA_PORT. Keep in mind that reading a byte from the buffer 'consumes & removes it' and will reduce the FIFO count by one. 
Fourth, if you just want to blindly send the bytes to the SAM2695, then write each byte back to MIDI_FIFO_DATA_PORT as they are parsed 
Optionally, you may want to react to the bytes, analyze them, modify them before sending them off to MIDI_FIFO_DATA_PORT

IRQ Programming

2025-07-02T16:42:47Z

Minstrel Dragon: Custom IRQ Handling by User Programs

=== Basic IRQ handling on the 6502 ===
The 65C02 processor (or 65816 in compatibility mode) contains an interrupt system which allows for code to be executed outside the normal program flow on the occurrence of an external event. Such event can be the start of a new frame, the expiration of a VIA timer, reception of data on a serial input line etc.

Here is a short explanation of how an interrupt is handled:

==== '''1. IRQ Line Goes Low''' ====

* The '''IRQ pin''' on the 6502 is '''active low'''.
* When the IRQ pin is pulled low by a device and '''interrupts are enabled''', the CPU will respond.

==== '''2. IRQ Timing''' ====

* The CPU checks for IRQ at the '''end of each instruction cycle'''.
* If IRQ is active and not masked, the CPU starts the '''interrupt sequence'''.

==== '''3. Interrupt Sequence''' ====
When an IRQ is accepted:

# '''Complete the current instruction.'''
# '''Push the Program Counter (PC)''' to the stack (2 bytes, high byte first).
# '''Push the Processor Status Register (P)''' to the stack.
# '''Set the Interrupt Disable (I) flag''' in the status register (to prevent nested IRQs).
# '''Read the IRQ vector''' from memory address <code>$FFFE</code> (low byte) and <code>$FFFF</code> (high byte).
# '''Jump to the address fetched from the IRQ vector.'''

==== '''4. Returning from Interrupt''' ====

* The interrupt handler ends with the '''RTI (Return from Interrupt)''' instruction.
* RTI does the reverse:
** Pulls the status register from the stack.
** Pulls the program counter (2 bytes) from the stack.
** Resumes execution where it left off.

=== Standard IRQ Handling by MicroKernel ===
By default, the interrupts in the F256 machines are handled by the MicroKernel:

* Since the MicroKernel is mapped into memory space at $e000-$ffff, the IRQ vector is defined by the MicroKernel.
* Therefore, whenever an interrupt condition occurs, the 6502 jumps into the IRQ service routine located within the MicroKernel.
* The Kernel does the appropriate event handling within the IRQ.
* It clears the interrupt source that triggered the IRQ.
* Finally, it returns control back to normal program execution.

=== Custom IRQ Handling by User Programs ===

Sometimes it is useful for user programs to intercept interrupt handling in order to have minimal latency in handling events. Possible reasons for this include:

* Precise music playback in the background of normal program execution.
* Timing game play at timing intervals different from the start of frame.
* Graphics effects like sprite reuse.
* ...

In order to handle interrupts within user land roughly requires the following steps:

# Disable interrupts during the following steps in order to avoid interrupt processing while we are reconfiguring the interrupt handling.
# Set up the interrupt source. This typically includes something like configuring a timer counter interval, and start the timer. A good source for timer interrupts is the VIA chip which has a timer that runs on a 6 MHz timer clock.
# Copy the Kernel memory to a suitable location in RAM. This step is necessary because by default the Kernel is running from Read-Only flash memory. However, we need to modify the IRQ vector at $fffe/$ffff in order to re-route the interrupt service routine to our own custom routine.
# Reconfigure the Memory Management Unit (MMU) in order to access the Kernel in RAM rather than in ROM. While the memory is still being addressed through the address window at $e000-$ffff, the physical memory accessed by the MMU will be pointed to our RAM copy of the Kernel rather than the ROM version.
# Install our custom Interrupt Service Routine (ISR). This step ensures that our own interrupt routine resides in a location in memory that is accessible when the Interrupt occurs, which may be almost any time, i.e. either when the user program runs, or when the kernel is being executed. In particular this means, we need to be able to access the ISR even if our main program memory is banked out by the Kernel!
# Enable our custom interrupt source. For example, this may include setting various registers in the VIA chip which trigger the timer to raise an interrupt.
# Re-enable interrupts, kicking off our interrupt processing.

----

IRQ Programming

2025-07-02T16:22:59Z

Minstrel Dragon: added section on standard IRQ Handling by MicroKernel

IRQ Programming

2025-07-02T15:25:26Z

Minstrel Dragon: Basic IRQ handling (with the help of ChatGPT, some details may need additional reviewing)

Use the Sam2695 Dream MIDI chip

2025-06-11T12:16:23Z

Minstrel Dragon: corrected middle C in Note On to 0x3C (decimal 60)

== Sam2695 Dream IC is in the F256K2 and F256Jr2 only ==

The SAM2695 datasheet can be found in this goodies github repo: https://github.com/Mu0n/F256MiscGoodies/blob/main/datasheets/SAM2695.pdf

The MIDI specification from MIDI.org can be found in the organization's website https://midi.org/specs

There are many tutorials and overview of useful MIDI commands, here is one of them: https://www.cs.cmu.edu/~music/cmsip/readings/MIDI%20tutorial%20for%20programmers.html

Here's a reference list of General MIDI instruments by number: https://www.ccarh.org/courses/253/handout/gminstruments/ 
{| class="wikitable"
|+
!Register Name
!Address
!Description
|-
|MIDI_STATUS
|0xDDA0
|Read: Bit[1] = Rx_empty, Bit[2] = Tx_empty
|-
|MIDI_FIFO_DATA_PORT
|0xDDA1
|read and write Data Port
|-
|MIDI_RXD_COUNT_LOW
|0xDDA2
|Rx FIFO Data Count LOW
|-
|MIDI_RXD_COUNT_HI
|0xDDA3
|Rx FIFO Data Count Hi - Only the 4 first bit are valid
|-
|MIDI_TXD_COUNT_LOW
|0xDDA4
|Tx FIFO Data Count LOW
|-
|MIDI_TXD_COUNT_HI
|0xDDA5
|Tx FIFO Data Count Hi - Only the 4 first bit are valid
|}

=== Steps in order to use MIDI OUT ===

'''MIDI OUT picks data from your program and sends it out to the SAM2695 chip as well as the MIDI Out port to an external device.'''

Send a MIDI command to 0xDDA1 by writing all the bytes of the MIDI command in rapid sequence.


Note On as a moderately heavy middle C to channel 0: 0x90, 0x3C, 0x40 
Note Off as a softly released middle C to channel 0: 0x80, 0x3C, 0x00 
Changing the instrument of channel 2 to a Slap Bass 1: 0xC2, 0x24 
Shut the 6th channel off: 0xB5, 0x7B, 0x00 

=== Steps in order to use MIDI IN ===

'''MIDI IN refers to an external MIDI controller (i.e. piano keyboard) that sends MIDI formatted bytes into the Foenix' MIDI in port'''

First, verify if there are bytes pending in the FIFO buffer by checking if MIDI_STATUS register bit 0 is set to 1 - if so, then create the following loop with steps 2,3,4 
Second, read MIDI_RXD_COUNT_LOW as the low byte of a 16-bit value and MIDI_RXD_COUNT_HI as the high byte of the same value to see how many loop iterations must be done 
Third, read a byte from MIDI_FIFO_DATA_PORT. Keep in mind that reading a byte from the buffer 'consumes & removes it' and will reduce the FIFO count by one. 
Fourth, if you just want to blindly send the bytes to the SAM2695, then write each byte back to MIDI_FIFO_DATA_PORT as they are parsed 
Optionally, you may want to react to the bytes, analyze them, modify them before sending them off to MIDI_FIFO_DATA_PORT

Memory Management

2024-02-11T09:48:22Z

Minstrel Dragon: corrected start of Flash (old: $80:0000 new: $08:0000)

The F256 line comes with 512 KB of RAM and 512 KB of flash memory. Up to 256 KB additional Memory, either RAM or Flash, can be added through the [[Expansion Port]].

=== Physical Memory Layout ===

The address bus is 21 bits wide, allowing a total of 221 = 2 MB to be addressed.

{| class="wikitable"
!Address!!Purpose
|-
|$00:0000 - $07:FFFF||RAM
|-
|$08:0000 - $0F:FFFF||Flash
|-
|$10:0000 - $13:FFFF||Expansion Memory
|-
|$14:0000 - $1F:FFFF||Reserved
|}

=== Memory Management Unit (MMU) ===

While the address bus is generally 21 bits wide, the CPU address bus of the 65c02 and the FNX6809 is only 16 bits wide. Even though the 65816 does have a 24 bit wide address bus, it is currently not used. However, this might change with a future update.

To allow the addressing of the whole address space, 4 Memory Management Units (MMU) are provided, that translate the CPU logical address space to physical addresses.

To achieve this, each MMU has 8 slots, each representing an 8 KB block of the CPU addressable memory space.

The physical address space is also divided into 8 KB blocks, dividing the available 2 MB into 256 blocks.

To map a block of physical addresses into CPU address space, the block number is written into the according slot register of the MMU.

{| class="wikitable"
!Slot!!CPU Address Space!!Slot Register Address
|-
|0||$0000 - $1FFF|| $0008
|-
|1||$2000 - $3FFF|| $0009
|-
|2||$4000 - $5FFF|| $000A
|-
|3||$6000 - $7FFF|| $000B
|-
|4||$8000 - $9FFF|| $000C
|-
|5||$A000 - $BFFF|| $000D
|-
|6||$C000 - $DFFF|| $000E
|-
|7||$E000 - $FFFF|| $000F
|}

Only one MMU is active at any one time. To select the active MMU, the lower two bits of address $0000 (MMU_MEM_CTRL) are used.

Editing of MMUs is also controlled by MMU_MEM_CTRL ($0000): Bits 4 and 5 determine which set of MMU registers is to be edited, while bit 7 has to be set to 1 to enable editing.
When editing is enable, the block number of a physical memory area can be written to the slot register address to map that area to the address in CPU address space. If editing is not enabled (bit 7 of $0000 is 0), the slot register addresses act as ordinary memory with no side effect.

=== Memory Block Tables ===
The following table shows which block number has to be written into a slot register to make the each 8 KB block of memory available to the CPU.

{| class="wikitable" style="border: none; background: none;"
! colspan=2 scope=col| RAM
| rowspan=66 style="border: none; background: none;" |
! colspan=2 scope=col| Flash
| rowspan=66 style="border: none; background: none;" |
! colspan=2 scope=col| Expansion
|-
! scope=col | Block Number
! scope=col | Physical Address

! scope=col | Block Number
! scope=col | Physical Address

! scope=col | Block Number
! scope=col | Physical Address
|-
|$00||$00:0000 - $00:1FFF||$40||$08:0000 - $08:1FFF||$80||$10:0000 - $10:1FFF
|-
|$01||$00:2000 - $00:3FFF||$41||$08:2000 - $08:3FFF||$81||$10:2000 - $10:3FFF
|-
|$02||$00:4000 - $00:5FFF||$42||$08:4000 - $08:5FFF||$82||$10:4000 - $10:5FFF
|-
|$03||$00:6000 - $00:7FFF||$43||$08:6000 - $08:7FFF||$83||$10:6000 - $10:7FFF
|-
|$04||$00:8000 - $00:9FFF||$44||$08:8000 - $08:9FFF||$84||$10:8000 - $10:9FFF
|-
|$05||$00:A000 - $00:BFFF||$45||$08:A000 - $08:BFFF||$85||$10:A000 - $10:BFFF
|-
|$06||$00:C000 - $00:DFFF||$46||$08:C000 - $08:DFFF||$86||$10:C000 - $10:DFFF
|-
|$07||$00:E000 - $00:FFFF||$47||$08:E000 - $08:FFFF||$87||$10:E000 - $10:FFFF
|-
|$08||$01:0000 - $01:1FFF||$48||$09:0000 - $09:1FFF||$88||$11:0000 - $11:1FFF
|-
|$09||$01:2000 - $01:3FFF||$49||$09:2000 - $09:3FFF||$89||$11:2000 - $11:3FFF
|-
|$0A||$01:4000 - $01:5FFF||$4A||$09:4000 - $09:5FFF||$8A||$11:4000 - $11:5FFF
|-
|$0B||$01:6000 - $01:7FFF||$4B||$09:6000 - $09:7FFF||$8B||$11:6000 - $11:7FFF
|-
|$0C||$01:8000 - $01:9FFF||$4C||$09:8000 - $09:9FFF||$8C||$11:8000 - $11:9FFF
|-
|$0D||$01:A000 - $01:BFFF||$4D||$09:A000 - $09:BFFF||$8D||$11:A000 - $11:BFFF
|-
|$0E||$01:C000 - $01:DFFF||$4E||$09:C000 - $09:DFFF||$8E||$11:C000 - $11:DFFF
|-
|$0F||$01:E000 - $01:FFFF||$4F||$09:E000 - $09:FFFF||$8F||$11:E000 - $11:FFFF
|-
|$10||$02:0000 - $02:1FFF||$50||$0A:0000 - $0A:1FFF||$90||$12:0000 - $12:1FFF
|-
|$11||$02:2000 - $02:3FFF||$51||$0A:2000 - $0A:3FFF||$91||$12:2000 - $12:3FFF
|-
|$12||$02:4000 - $02:5FFF||$52||$0A:4000 - $0A:5FFF||$92||$12:4000 - $12:5FFF
|-
|$13||$02:6000 - $02:7FFF||$53||$0A:6000 - $0A:7FFF||$93||$12:6000 - $12:7FFF
|-
|$14||$02:8000 - $02:9FFF||$54||$0A:8000 - $0A:9FFF||$94||$12:8000 - $12:9FFF
|-
|$15||$02:A000 - $02:BFFF||$55||$0A:A000 - $0A:BFFF||$95||$12:A000 - $12:BFFF
|-
|$16||$02:C000 - $02:DFFF||$56||$0A:C000 - $0A:DFFF||$96||$12:C000 - $12:DFFF
|-
|$17||$02:E000 - $02:FFFF||$57||$0A:E000 - $0A:FFFF||$97||$12:E000 - $12:FFFF
|-
|$18||$03:0000 - $03:1FFF||$58||$0B:0000 - $0B:1FFF||$98||$13:0000 - $13:1FFF
|-
|$19||$03:2000 - $03:3FFF||$59||$0B:2000 - $0B:3FFF||$99||$13:2000 - $13:3FFF
|-
|$1A||$03:4000 - $03:5FFF||$5A||$0B:4000 - $0B:5FFF||$9A||$13:4000 - $13:5FFF
|-
|$1B||$03:6000 - $03:7FFF||$5B||$0B:6000 - $0B:7FFF||$9B||$13:6000 - $13:7FFF
|-
|$1C||$03:8000 - $03:9FFF||$5C||$0B:8000 - $0B:9FFF||$9C||$13:8000 - $13:9FFF
|-
|$1D||$03:A000 - $03:BFFF||$5D||$0B:A000 - $0B:BFFF||$9D||$13:A000 - $13:BFFF
|-
|$1E||$03:C000 - $03:DFFF||$5E||$0B:C000 - $0B:DFFF||$9E||$13:C000 - $13:DFFF
|-
|$1F||$03:E000 - $03:FFFF||$5F||$0B:E000 - $0B:FFFF||$9F||$13:E000 - $13:FFFF
|-
|$20||$04:0000 - $04:1FFF||$60||$0C:0000 - $0C:1FFF
|-
|$21||$04:2000 - $04:3FFF||$61||$0C:2000 - $0C:3FFF
|-
|$22||$04:4000 - $04:5FFF||$62||$0C:4000 - $0C:5FFF
|-
|$23||$04:6000 - $04:7FFF||$63||$0C:6000 - $0C:7FFF
|-
|$24||$04:8000 - $04:9FFF||$64||$0C:8000 - $0C:9FFF
|-
|$25||$04:A000 - $04:BFFF||$65||$0C:A000 - $0C:BFFF
|-
|$26||$04:C000 - $04:DFFF||$66||$0C:C000 - $0C:DFFF
|-
|$27||$04:E000 - $04:FFFF||$67||$0C:E000 - $0C:FFFF
|-
|$28||$05:0000 - $05:1FFF||$68||$0D:0000 - $0D:1FFF
|-
|$29||$05:2000 - $05:3FFF||$69||$0D:2000 - $0D:3FFF
|-
|$2A||$05:4000 - $05:5FFF||$6A||$0D:4000 - $0D:5FFF
|-
|$2B||$05:6000 - $05:7FFF||$6B||$0D:6000 - $0D:7FFF
|-
|$2C||$05:8000 - $05:9FFF||$6C||$0D:8000 - $0D:9FFF
|-
|$2D||$05:A000 - $05:BFFF||$6D||$0D:A000 - $0D:BFFF
|-
|$2E||$05:C000 - $05:DFFF||$6E||$0D:C000 - $0D:DFFF
|-
|$2F||$05:E000 - $05:FFFF||$6F||$0D:E000 - $0D:FFFF
|-
|$30||$06:0000 - $06:1FFF||$70||$0E:0000 - $0E:1FFF
|-
|$31||$06:2000 - $06:3FFF||$71||$0E:2000 - $0E:3FFF
|-
|$32||$06:4000 - $06:5FFF||$72||$0E:4000 - $0E:5FFF
|-
|$33||$06:6000 - $06:7FFF||$73||$0E:6000 - $0E:7FFF
|-
|$34||$06:8000 - $06:9FFF||$74||$0E:8000 - $0E:9FFF
|-
|$35||$06:A000 - $06:BFFF||$75||$0E:A000 - $0E:BFFF
|-
|$36||$06:C000 - $06:DFFF||$76||$0E:C000 - $0E:DFFF
|-
|$37||$06:E000 - $06:FFFF||$77||$0E:E000 - $0E:FFFF
|-
|$38||$07:0000 - $07:1FFF||$78||$0F:0000 - $0F:1FFF
|-
|$39||$07:2000 - $07:3FFF||$79||$0F:2000 - $0F:3FFF
|-
|$3A||$07:4000 - $07:5FFF||$7A||$0F:4000 - $0F:5FFF
|-
|$3B||$07:6000 - $07:7FFF||$7B||$0F:6000 - $0F:7FFF
|-
|$3C||$07:8000 - $07:9FFF||$7C||$0F:8000 - $0F:9FFF
|-
|$3D||$07:A000 - $07:BFFF||$7D||$0F:A000 - $0F:BFFF
|-
|$3E||$07:C000 - $07:DFFF||$7E||$0F:C000 - $0F:DFFF
|-
|$3F||$07:E000 - $07:FFFF||$7F||$0F:E000 - $0F:FFFF
|}