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

Kernel & SuperBASIC Updates

2025-02-13T01:28:32Z

KoolKiwi: /* Updated for the differing COM Port instructions for updating the F256K2 */

== Kernel and/or SuperBASIC Update Links ==

Here are the GitHub Links where you will find the latest F256K / F256Jr Micro-Kernel load and/or SuperBASIC:

[https://github.com/ghackwrench/F256_MicroKernel F256x Micro-Kernel Github Link]

[https://github.com/paulscottrobson/superbasic/releases F256x SuperBASIC Github Link]

Here is a complete package of both latest instances (Scripts & bulk.csv files included)

[https://github.com/FoenixRetro/f256-firmware Complete Package Kernal+SuperBASIC+Apps Link]

== Link to USB Driver for XR21B1411 (Not needed for F256K2) ==
XR21B1411 USB Driver for PC/Linux. The MAC is outdated. (Note: Driver is not needed for the F256K2)
[https://www.maxlinear.com/product/interface/uarts/usb-uarts/xr21b1411]

On the F256K2 the XR21B1411 has been replaced by a FT4232, to allow direct use as a JTAG controller for the FPGA. There are 3 virtual serial ports (channels) enabled. The first connected to the Rasberry PI Nano (on-board) that manages the FPGA loading, the second one is the Debug port and the Third one is the system UART.

Therefore on a F256K2 you want to select the second COM port that gets added to your system. On my Windows 10 system, the F256K2 USB-C connection added ports COM5, COM6 and COM7. All three coming up just as generic FTDI manufacturer USB ports.

To perform a full Kernel & SuperVASIC update, I simply downloaded the Complete Package (above), and edited the update.bat batch file to instead specify my system's COM6 (i.e. the 2nd added Port).

== Links to Software needed to do update with FoenixMgr (Python Script) ==
Python
[https://www.python.org/]

PySerial
[https://pyserial.readthedocs.io/en/latest/]

Foenix Manager (Collection of Python Scripts to use the USB Debug port)
[https://github.com/pweingar/FoenixMgr]

== Kernel and/or SuperBASIC Update Guide ==

Below, is a short video on how to install the software you will need to be able to reflash your Kernel and/or SuperBASIC.

==== How to Update your F256 Jr. / F256K Short ====

<youtube>Zgyhy_cBsM8</youtube>

FNX6809 Overview

2024-06-01T22:34:23Z

KoolKiwi: Added image of the JTAG Adapter correct orientation (from Discord).

== FNX6809 for F256Jr & F256K ==

[[File:FNX6809_Transparent_SideView.png|thumb|FNX6809 CPU Module]]
[[File:FNX6809_Adapter.jpeg|thumb|FNX6809 FPGA Flash Adapter]]

The FNX6809 is a DIP40 module that is effectively a Cycle Accurate Motorola MC6809 CPU, working @ 3.3V and capable of running @ 6.29MHz on the F256Jr or the F256K.

The FNX6809 also differs from a real Motorola MC6809 CPU in that it has the 65C02 pin-out.

For these reasons, it is not designed (at least for now) to be a direct replacement for an MC6809.

An Adapter is supplied with the FNX6809 module to be enable reflashing the on-board FPGA, if ever needed.

'''Note:'''
* No software is written for the unit to support the processor at this time (but see [[OS-9]]). It is meant for them Mavericks that are ready to take it on without any safety nets. There is a version of Calypsi that supports now if anybody wants to use it.
* Keep in mind that you will need to upload a new load for the FPGA on the F256Jr or F256K to support it, so make sure you equip yourself with a USB Blaster.

[[File:FNX6809_JTAG_Adapter_Position.jpg|thumb|left|FNX6809 JTAG Adapter Correct Orientation]]

File:FNX6809 JTAG Adapter Position.jpg

2024-06-01T22:25:13Z

KoolKiwi: KoolKiwi uploaded a new version of File:FNX6809 JTAG Adapter Position.jpg

== Summary ==
FNX6809 JTAG Adapter Position

File:FNX6809 JTAG Adapter Position.jpg

2024-06-01T21:03:13Z

KoolKiwi: FNX6809 JTAG Adapter Position

== Summary ==
FNX6809 JTAG Adapter Position

Hardware

2024-04-01T01:33:57Z

KoolKiwi: Added notes on SN74LVC8T245 and TXS010x control pins being referenced to Vcca, and typical usage.

== Hardware Overview and Comparison ==
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
! scope="row"; style="text-align:left;" |
F256Jr
! scope="row"; style="text-align:left;" |
F256K
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
CPU
|
WDC W65C02S 
WDC W65C816S 
Foenix FNX6809 
|
WDC W65C02S 
WDC W65C816S 
Foenix FNX6809 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
RAM
|
512 KB 
Optional 256K RAM expansion module available 
|
512 KB 
Optional 256K RAM expansion module available 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Flash
|
512 KB 
Optional 256K Flash Modules 
|
512 KB 
Optional 256K Flash Modules 
|- style="vertical-align:top;"
! scope="col" style="text-align:left;" |
Graphic Chip
|
TinyVicky
|
TinyVicky
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Audio
|
2 x PSG (SN76489) 
2 x SID socket 
|
2 x PSG 
2 x SID hardware emulation on board 
OPL3 
CODEC 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Connections
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3.5 
1 x RCA Line Out 
2 x Serial Port Pin-Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style Pin-Header 
1 x PIN-Header onboard for SNES/NES Joystick Connector Box 
1 x Memory Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3.5 
1 x RCA Line Out 
1 x Serial Port DB9M / 1 x Serial Pin Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style DB9 Connector 
1 x Mini-DIN9 for SNES/NES Joystick Connector Box 
1 x Memory Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|}

== Hardware Details ==

=== CPU ===
The basic setup of all F256 is the [https://westerndesigncenter.com/ Western Design Center] '''65C02''', a slightly enhanced CMOS version of the very popular 6502 CPUs. The main difference to the 6502 in the 1970s and 1980s is the faster clock speed and the lower power consumption.

The 65C02 can also be replaced with a [[Template:Main2/65816_Processor|65816]] as a drop in replacement. '''Note, however, that while the 65c02 includes the additional Rockwell instructions (BBS/BBR, RMB/SMB), the 65816 does NOT. Therefore, these instructions should be avoided to ensure compatibility with F256 machines using the 65816.'''

In the F256, the CPU is always clocked at 6,29 MHz (6,293,750 Hz to be exact, derived from 25.175 MHz / 4 as discussed on [https://discord.com/channels/691915291721990194/1054250056703815680/1177306520925524018 Discord]).

=== Memory Expansion Slot ===
The memory expansion slot, located on the top right (above the keyboard), is intended primarily for Memory Expansion. It provides Address lines A0 - A17 (for addressing 256K), and active low Chip Select signal (CS_RAM) and Ouput Enable (OE) for the 256K Expansion address range $100000 - $13FFFF.

Foenix produce a 256K RAM Expansion cartridge, based on the CY7C1010DV33-10VXI, a high speed (10ns) 2Mbit (256K × 8) 3.3V Parallel Static RAM device.

The Expansion Slot itself, is based on a 36 pin PCI-Express x1 socket.

As the Expansion Slot also features pins for IRQ input, PHI2 clock output, and Reset (all signals which are unnecessary for a simple Memory interface), the Expansion Slot is also a candidate for other expansion purposes.

==== Utilising the Expension Slot (for your own purposes) ====

'''Warning:''' All signals on the Expansion Port are 3.3V logic level, therefore it is important that no voltage exceeding 3.3V is ever presented on any Expansion Port pin, or '''you risk damage''' to your F256!

If interfacing 5V TTL level devices to the Expansion Port, it is essential that level converters are used.

As an example, if directly interfacing to the Expansion Port pins with 5V logic, then you could use the SN74LVC8T245 bi-directional level translator, with the DIR input controlled by the Port's R/Wn signal (for the D0 - D7 bi-directional data bus), and the OEn input controlled by the Port's OEn signal. For the uni-directional Address and Control lines, the DIR input can be hardwired.

Note that the SN74LVC8T245 is designed so that the control pins (DIR and OE) are referenced to Vcca ('A' side voltage supplied). Therefore, a common practice would be to use side A for the internal (3.3V) side of the voltage translation, such that DIR and OE can be directly controlled by the Expansion Port's 3.3V level R/Wn and OEn pins. Side B (and Vccb) then being the 5V TTL level referenced (external facing) side.

As another example, if you were interfacing directly to a 3.3V peripheral chip (e.g. A W65C22 VIA powered by Vdd = 3.3V), but wanting to level translate to 5V TTL levels on the VIA's Port Pins, then an auto-direction level translator like the TI TXS010x series (TXS0108, TXS0104, TXS0101), might be more appropriate.

Note that on the TXS010x series the control pin (OE) is also referenced to Vcca ('A' side voltage supplied). With the TXS series, the 'A' side is actually limited to a 1.4V - 3.6V range, so is inherently the 3.3V internal side. Side 'B' is 1.65V - 5.5V, so is used for the external 5V TTL level referenced (external facing) side. So, if you're tying the active high OE pin of a TXS device (to permanently enable), it should be pulled to Vcca (not Vccb!).

==== Expansion Slot pin-out ====
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
Signal
! scope="row"; style="text-align:left;" |
Side B
! scope="row"; style="text-align:left;" |
Side A
! scope="row"; style="text-align:left;" |
Signal
|- style="vertical-align:top;"
|
A4
! scope="col"; style="text-align:center;" |
B1
! scope="col"; style="text-align:center;" |
A1
|
nRST
|- style="vertical-align:top;"
|
A3
! scope="col"; style="text-align:center;" |
B2
! scope="col"; style="text-align:center;" |
A2
|
A5
|- style="vertical-align:top;"
|
A2
! scope="col"; style="text-align:center;" |
B3
! scope="col"; style="text-align:center;" |
A3
|
A6
|- style="vertical-align:top;"
|
A1
! scope="col"; style="text-align:center;" |
B4
! scope="col"; style="text-align:center;" |
A4
|
A7
|- style="vertical-align:top;"
|
A0
! scope="col"; style="text-align:center;" |
B5
! scope="col"; style="text-align:center;" |
A5
|
A8
|- style="vertical-align:top;"
|
CS_RAMn
! scope="col"; style="text-align:center;" |
B6
! scope="col"; style="text-align:center;" |
A6
|
OEn
|- style="vertical-align:top;"
|
D0
! scope="col"; style="text-align:center;" |
B7
! scope="col"; style="text-align:center;" |
A7
|
D7
|- style="vertical-align:top;"
|
D1
! scope="col"; style="text-align:center;" |
B8
! scope="col"; style="text-align:center;" |
A8
|
D6
|- style="vertical-align:top;"
|
3V3
! scope="col"; style="text-align:center;" |
B9
! scope="col"; style="text-align:center;" |
A9
|
GND
|- style="vertical-align:top;"
|
GND
! scope="col"; style="text-align:center;" |
B10
! scope="col"; style="text-align:center;" |
A10
|
3V3
|- style="vertical-align:top;"
|
D2
! scope="col"; style="text-align:center;" |
B11
! scope="col"; style="text-align:center;" |
A11
|
D5
|- style="vertical-align:top;"
! colspan="4"; scope="col"; style="text-align:center;" |
Key Notch
|- style="vertical-align:top;"
|
D3
! scope="col"; style="text-align:center;" |
B12
! scope="col"; style="text-align:center;" |
A12
|
D4
|- style="vertical-align:top;"
|
R/Wn
! scope="col"; style="text-align:center;" |
B13
! scope="col"; style="text-align:center;" |
A13
|
A9
|- style="vertical-align:top;"
|
A17
! scope="col"; style="text-align:center;" |
B14
! scope="col"; style="text-align:center;" |
A14
|
A10
|- style="vertical-align:top;"
|
A16
! scope="col"; style="text-align:center;" |
B15
! scope="col"; style="text-align:center;" |
A15
|
A11
|- style="vertical-align:top;"
|
A15
! scope="col"; style="text-align:center;" |
B16
! scope="col"; style="text-align:center;" |
A16
|
A12
|- style="vertical-align:top;"
|
A14
! scope="col"; style="text-align:center;" |
B17
! scope="col"; style="text-align:center;" |
A17
|
IRQn
|- style="vertical-align:top;"
|
A13
! scope="col"; style="text-align:center;" |
B18
! scope="col"; style="text-align:center;" |
A18
|
PHI2
|}

==== Expansion Slot - Signal Descriptions ====
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
Signal
! scope="row"; style="text-align:left;" |
Description
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
A0 - A17
|
Address Bus output (for addressing $100000 - $13FFFF Expansion space)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
D0 - D7
|
Data Bus (bi-directional)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
RSTn
|
Reset output (active low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
CS_RAMn
|
Chip Select output for Address Range $100000 - $13FFFF (active low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
OEn
|
Output Enable output for a Read from Address Range $100000 - $13FFFF (active low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
3V3
|
3.3V Power output from the F256 (intended to power Expansion Interface only - '''Don't Exceed 500ma''')
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
GND
|
Digital Ground reference
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
R/Wn
|
Read/Write ouput (Read = high / Write = low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
IRQn
|
Interrupt Request input - Internal pull-up and non-shared (compatible with open-drain or totem-pole driven)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
PHI2
|
Phase 2 - Clock Output

Hardware

2024-04-01T00:28:08Z

KoolKiwi: Added Section for the Memory Expansion Slot

== Hardware Overview and Comparison ==
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
! scope="row"; style="text-align:left;" |
F256Jr
! scope="row"; style="text-align:left;" |
F256K
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
CPU
|
WDC W65C02S 
WDC W65C816S 
Foenix FNX6809 
|
WDC W65C02S 
WDC W65C816S 
Foenix FNX6809 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
RAM
|
512 KB 
Optional 256K RAM expansion module available 
|
512 KB 
Optional 256K RAM expansion module available 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Flash
|
512 KB 
Optional 256K Flash Modules 
|
512 KB 
Optional 256K Flash Modules 
|- style="vertical-align:top;"
! scope="col" style="text-align:left;" |
Graphic Chip
|
TinyVicky
|
TinyVicky
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Audio
|
2 x PSG (SN76489) 
2 x SID socket 
|
2 x PSG 
2 x SID hardware emulation on board 
OPL3 
CODEC 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Connections
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3.5 
1 x RCA Line Out 
2 x Serial Port Pin-Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style Pin-Header 
1 x PIN-Header onboard for SNES/NES Joystick Connector Box 
1 x Memory Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3.5 
1 x RCA Line Out 
1 x Serial Port DB9M / 1 x Serial Pin Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style DB9 Connector 
1 x Mini-DIN9 for SNES/NES Joystick Connector Box 
1 x Memory Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|}

== Hardware Details ==

=== CPU ===
The basic setup of all F256 is the [https://westerndesigncenter.com/ Western Design Center] '''65C02''', a slightly enhanced CMOS version of the very popular 6502 CPUs. The main difference to the 6502 in the 1970s and 1980s is the faster clock speed and the lower power consumption.

The 65C02 can also be replaced with a [[Template:Main2/65816_Processor|65816]] as a drop in replacement. '''Note, however, that while the 65c02 includes the additional Rockwell instructions (BBS/BBR, RMB/SMB), the 65816 does NOT. Therefore, these instructions should be avoided to ensure compatibility with F256 machines using the 65816.'''

In the F256, the CPU is always clocked at 6,29 MHz (6,293,750 Hz to be exact, derived from 25.175 MHz / 4 as discussed on [https://discord.com/channels/691915291721990194/1054250056703815680/1177306520925524018 Discord]).

=== Memory Expansion Slot ===
The memory expansion slot, located on the top right (above the keyboard), is intended primarily for Memory Expansion. It provides Address lines A0 - A17 (for addressing 256K), and active low Chip Select signal (CS_RAM) and Ouput Enable (OE) for the 256K Expansion address range $100000 - $13FFFF.

Foenix produce a 256K RAM Expansion cartridge, based on the CY7C1010DV33-10VXI, a high speed (10ns) 2Mbit (256K × 8) 3.3V Parallel Static RAM device.

The Expansion Slot itself, is based on a 36 pin PCI-Express x1 socket.

As the Expansion Slot also features pins for IRQ input, PHI2 clock output, and Reset (all signals which are unnecessary for a simple Memory interface), the Expansion Slot is also a candidate for other expansion purposes.

==== Utilising the Expension Slot (for your own purposes) ====

'''Warning:''' All signals on the Expansion Port are 3.3V logic level, therefore it is important that no voltage exceeding 3.3V is ever presented on any Expansion Port pin, or '''you risk damage''' to your F256!

If interfacing 5V TTL level devices to the Expansion Port, it is essential that level converters are used.

As an example, if directly interfacing to the Expansion Port pins with 5V logic, then you could use the SN74LVC8T245 bi-directional level translator, with the DIR input controlled by the Port's R/Wn signal (for the D0 - D7 bi-directional data bus), and the OEn input controlled by the Port's OEn signal. For the uni-directional Address and Control lines, the DIR input can be hardwired.

As another example, if you were interfacing directly to a 3.3V peripheral chip (e.g. A W65C22 VIA powered by Vdd = 3.3V), but wanting to level translate to 5V TTL levels on the VIA's Port Pins, then an auto-direction level translator like the TI TXS010x series (TXS0108, TXS0104, TXS0101), might be more appropriate.

==== Expansion Slot pin-out ====
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
Signal
! scope="row"; style="text-align:left;" |
Side B
! scope="row"; style="text-align:left;" |
Side A
! scope="row"; style="text-align:left;" |
Signal
|- style="vertical-align:top;"
|
A4
! scope="col"; style="text-align:center;" |
B1
! scope="col"; style="text-align:center;" |
A1
|
nRST
|- style="vertical-align:top;"
|
A3
! scope="col"; style="text-align:center;" |
B2
! scope="col"; style="text-align:center;" |
A2
|
A5
|- style="vertical-align:top;"
|
A2
! scope="col"; style="text-align:center;" |
B3
! scope="col"; style="text-align:center;" |
A3
|
A6
|- style="vertical-align:top;"
|
A1
! scope="col"; style="text-align:center;" |
B4
! scope="col"; style="text-align:center;" |
A4
|
A7
|- style="vertical-align:top;"
|
A0
! scope="col"; style="text-align:center;" |
B5
! scope="col"; style="text-align:center;" |
A5
|
A8
|- style="vertical-align:top;"
|
CS_RAMn
! scope="col"; style="text-align:center;" |
B6
! scope="col"; style="text-align:center;" |
A6
|
OEn
|- style="vertical-align:top;"
|
D0
! scope="col"; style="text-align:center;" |
B7
! scope="col"; style="text-align:center;" |
A7
|
D7
|- style="vertical-align:top;"
|
D1
! scope="col"; style="text-align:center;" |
B8
! scope="col"; style="text-align:center;" |
A8
|
D6
|- style="vertical-align:top;"
|
3V3
! scope="col"; style="text-align:center;" |
B9
! scope="col"; style="text-align:center;" |
A9
|
GND
|- style="vertical-align:top;"
|
GND
! scope="col"; style="text-align:center;" |
B10
! scope="col"; style="text-align:center;" |
A10
|
3V3
|- style="vertical-align:top;"
|
D2
! scope="col"; style="text-align:center;" |
B11
! scope="col"; style="text-align:center;" |
A11
|
D5
|- style="vertical-align:top;"
! colspan="4"; scope="col"; style="text-align:center;" |
Key Notch
|- style="vertical-align:top;"
|
D3
! scope="col"; style="text-align:center;" |
B12
! scope="col"; style="text-align:center;" |
A12
|
D4
|- style="vertical-align:top;"
|
R/Wn
! scope="col"; style="text-align:center;" |
B13
! scope="col"; style="text-align:center;" |
A13
|
A9
|- style="vertical-align:top;"
|
A17
! scope="col"; style="text-align:center;" |
B14
! scope="col"; style="text-align:center;" |
A14
|
A10
|- style="vertical-align:top;"
|
A16
! scope="col"; style="text-align:center;" |
B15
! scope="col"; style="text-align:center;" |
A15
|
A11
|- style="vertical-align:top;"
|
A15
! scope="col"; style="text-align:center;" |
B16
! scope="col"; style="text-align:center;" |
A16
|
A12
|- style="vertical-align:top;"
|
A14
! scope="col"; style="text-align:center;" |
B17
! scope="col"; style="text-align:center;" |
A17
|
IRQn
|- style="vertical-align:top;"
|
A13
! scope="col"; style="text-align:center;" |
B18
! scope="col"; style="text-align:center;" |
A18
|
PHI2
|}

==== Expansion Slot - Signal Descriptions ====
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
Signal
! scope="row"; style="text-align:left;" |
Description
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
A0 - A17
|
Address Bus output (for addressing $100000 - $13FFFF Expansion space)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
D0 - D7
|
Data Bus (bi-directional)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
RSTn
|
Reset output (active low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
CS_RAMn
|
Chip Select output for Address Range $100000 - $13FFFF (active low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
OEn
|
Output Enable output for a Read from Address Range $100000 - $13FFFF (active low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
3V3
|
3.3V Power output from the F256 (intended to power Expansion Interface only - '''Don't Exceed 500ma''')
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
GND
|
Digital Ground reference
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
R/Wn
|
Read/Write ouput (Read = high / Write = low)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
IRQn
|
Interrupt Request input - Internal pull-up and non-shared (compatible with open-drain or totem-pole driven)
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
PHI2
|
Phase 2 - Clock Output

Hardware

2024-01-27T19:33:17Z

KoolKiwi: fix table style typo + left align headers + table layout consistancy

=== Overview and Comparison ===
{| class="wikitable"; style="text-align:left;"
|- style="vertical-align:top;"
! scope="row"; style="text-align:left;" |
! scope="row"; style="text-align:left;" |
F256Jr
! scope="row"; style="text-align:left;" |
F256K
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
CPU
|
WDC 65C02 
WDC 65816S 
FNX 6809 
|
WDC 65C02 
WDC 65816S 
FNX 6809 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
RAM
|
512 KB 
Optional 256K RAM expansion module available 
|
512 KB 
Optional 256K RAM expansion module available 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Flash
|
512 KB 
Optional 256K Flash Modules 
|
512 KB 
Optional 256K Flash Modules 
|- style="vertical-align:top;"
! scope="col" style="text-align:left;" |
Graphic Chip
|
TinyVicky
|
TinyVicky
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Audio
|
2 x PSG (Sn76489) 
2 x SID socket 
|
2 x PSG 
2 x SID hardware emulation on board 
OPL3 
CODEC 
|- style="vertical-align:top;"
! scope="col"; style="text-align:left;" |
Connections
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3,5 
1 x RCA Line Out 
2 x Serial Port Pin-Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style Pin-Header 
1 x PIN-Header onboard for SNES/NES Joystick Connector Box 
1 x RAM Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3,5 
1 x RCA Line Out 
1 x Serial Port DB9M / 1 x Serial Pin Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style DB9 Connector 
1 x Mini-DIN9 for SNES/NES Joystick Connector Box 
1 x RAM Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|}

=== Details ===

===== CPU =====
The basic setup of all F256 is the [https://westerndesigncenter.com/ Western Design Center] '''65C02''', a slightly enhanced CMOS version of the very popular 6502 CPUs. The main difference to the 6502 in the 1970s and 1980s is the faster clock speed and the lower power consumption.

The 65C02 can also be replaced with a [[Template:Main2/65816_Processor|65816]] as a drop in replacement. '''Note, however, that while the 65c02 includes the additional Rockwell instructions (BBS/BBR, RMB/SMB), the 65816 does NOT. Therefore, these instructions should be avoided to ensure compatibility with F256 machines using the 65816.'''

In the F256, the CPU is always clocked at 6,29 MHz (6,293,750 Hz to be exact, derived from 25.175 MHz / 4 as discussed on [https://discord.com/channels/691915291721990194/1054250056703815680/1177306520925524018 Discord]).

Hardware

2024-01-27T19:20:25Z

KoolKiwi: Table formatting for improved readability (minor edit)

=== Overview and Comparison ===
{| class="wikitable"
|+
!
!F256Jr
!F256K
|- style="vertical-align:top;"
! scope="col"; style=text-align:left;" |CPU
|
WDC 65C02 
WDC 65816S 
FNX 6809 
|
WDC 65C02 
WDC 65816S 
FNX 6809 
|- style="vertical-align:top;"
! scope="col"; style=text-align:left;" |RAM
|
512 KB 
Optional 256K RAM expansion module available 
|
512 KB 
Optional 256K RAM expansion module available 
|- style="vertical-align:top;"
! scope="col"; style=text-align:left;" |Flash
|
512 KB 
Optional 256K Flash Modules 
|
512 KB 
Optional 256K Flash Modules 
|- style="vertical-align:top;"
! scope="col"|Graphic Chip
|
TinyVicky
|
TinyVicky
|- style="vertical-align:top;"
! scope="col"; style=text-align:left;" |Audio
|
2 x PSG (Sn76489) 
2 x SID socket 
|
2 x PSG 
2 x SID hardware emulation on board 
OPL3 
CODEC 
|- style="vertical-align:top;"
! scope="col"; style=text-align:left;" |Connections
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3,5 
1 x RCA Line Out 
2 x Serial Port Pin-Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style Pin-Header 
1 x PIN-Header onboard for SNES/NES Joystick Connector Box 
1 x RAM Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3,5 
1 x RCA Line Out 
1 x Serial Port DB9M / 1 x Serial Pin Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style DB9 Connector 
1 x Mini-DIN9 for SNES/NES Joystick Connector Box 
1 x RAM Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|}

=== Details ===

===== CPU =====
The basic setup of all F256 is the [https://westerndesigncenter.com/ Western Design Center] '''65C02''', a slightly enhanced CMOS version of the very popular 6502 CPUs. The main difference to the 6502 in the 1970s and 1980s is the faster clock speed and the lower power consumption.

The 65C02 can also be replaced with a [[Template:Main2/65816_Processor|65816]] as a drop in replacement. '''Note, however, that while the 65c02 includes the additional Rockwell instructions (BBS/BBR, RMB/SMB), the 65816 does NOT. Therefore, these instructions should be avoided to ensure compatibility with F256 machines using the 65816.'''

In the F256, the CPU is always clocked at 6,29 MHz (6,293,750 Hz to be exact, derived from 25.175 MHz / 4 as discussed on [https://discord.com/channels/691915291721990194/1054250056703815680/1177306520925524018 Discord]).

Hardware

2024-01-27T19:08:32Z

KoolKiwi: /* Overview and Comparison */

=== Overview and Comparison ===
{| class="wikitable"
|+
!
!F256Jr
!F256K
|-
! scope="col"|CPU
|
WDC 65C02 
WDC 65816S 
FNX 6809 
|
WDC 65C02 
WDC 65816S 
FNX 6809 
|-
|RAM
|
512 KB 
Optional 256K RAM expansion module available 
|
512 KB 
Optional 256K RAM expansion module available 
|-
|Flash
|
512 KB 
Optional 256K Flash Modules 
|
512 KB 
Optional 256K Flash Modules 
|-
|Graphic Chip
|TinyVicky
|TinyVicky
|-
|Audio
|
2 x PSG (Sn76489) 
2 x SID socket 
|
2 x PSG 
2 x SID hardware emulation on board 
OPL3 
CODEC 
|-
|Connections
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3,5 
1 x RCA Line Out 
2 x Serial Port Pin-Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style Pin-Header 
1 x PIN-Header onboard for SNES/NES Joystick Connector Box 
1 x RAM Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|
1 x DVI (digital & analog) 
1 x PS2 (Mouse / External Keyboard) 
1 x Commodore syle IEC Port 
1 x Headphone 3,5 
1 x RCA Line Out 
1 x Serial Port DB9M / 1 x Serial Pin Header 
1 x Mini-USB Debug Port 
1 x Power 12V / 2A, 2,5mm Barrel Connector 
1 x SD Card Slot 
2 x Joystick Atari style DB9 Connector 
1 x Mini-DIN9 for SNES/NES Joystick Connector Box 
1 x RAM Expansion Slot (on Top) 
1 x JTAG Port for system updates (on bottom) 
1 x Wifi Module ESP32 Feather (internal) 
1 x Real Time Clock Battery CR2032 (internal) 
|}

=== Details ===

===== CPU =====
The basic setup of all F256 is the [https://westerndesigncenter.com/ Western Design Center] '''65C02''', a slightly enhanced CMOS version of the very popular 6502 CPUs. The main difference to the 6502 in the 1970s and 1980s is the faster clock speed and the lower power consumption.

The 65C02 can also be replaced with a [[Template:Main2/65816_Processor|65816]] as a drop in replacement. '''Note, however, that while the 65c02 includes the additional Rockwell instructions (BBS/BBR, RMB/SMB), the 65816 does NOT. Therefore, these instructions should be avoided to ensure compatibility with F256 machines using the 65816.'''

In the F256, the CPU is always clocked at 6,29 MHz (6,293,750 Hz to be exact, derived from 25.175 MHz / 4 as discussed on [https://discord.com/channels/691915291721990194/1054250056703815680/1177306520925524018 Discord]).

Getting Started

2023-12-20T03:14:05Z

KoolKiwi: Correct section ordering.

== Getting Powered Up ==

=== Powering your F256K ===

The F256K is powered via a standard 2.5mm DC Connector, which takes a centre-positive 12V 2A capable Power Supply.

This type of power supply is quite common. [https://www.amazon.com/Adapter-100-240V-Transformer-Charger-Security/dp/B091XSVV1Y Example 12V 2A capable power supply] (#)

(#) ''This specific power supply has not been verified (by the author) for use with the F256K. Please update this page with verified options!''

=== Powering your F256Jr ===

The F256Jr is supplied as a Mini-ITX form factor mainboard, with a standard 24 pin ATX power supply connector for power connectivity.

Since the F256Jr needs relatively little power, compared to a mini-ATX PC, a popular DC 12V 24pin Pico ATX PSU works well and is a compact solution.

* [https://www.amazon.com/dp/B08F57GKCL Pico PSU] - You power the Pico PSU via a 12V DC center-positive Power Supply source.
* [https://www.amazon.com/dp/B07MXXXBV8 12V DC center-positive A/C Adapter] - Commonly used to power the Pico PSU.

== Getting programs onto the F256 ==

=== SD Card ===

Both the F256K and F256JR have an SD card slot. The device sofware to read the SD card is a bit touchy (it's inherited from the Commander X16 project) and doesn't work with all SD cards

* Card should be "XC" type vs. "HC". Typically older cards in the 512MB-8GB range work pretty well, which is more than enough space anyways. Very new cards that are very large tend not to work?
* Card *MUST* be formatted FAT32 -- **NOT: FAT, FAT12, FAT16, or exFAT**. Note that while MacOS will read a FAT32 formatted card, the included disk utility won't format FAT32. Windows 10/11 works fine, but make sure to force FAT32 (or use the command line: <code>format /FS:FAT32 H:</code>)
* Some folks have had luck formatting cards with the [https://www.sdcard.org/downloads/formatter/sd-memory-card-formatter-for-windows-download/ Official SD Association formatter for Windows].

=== Demos Archive ===

* [https://github.com/FoenixRetro/Documentation/blob/main/f256/archive Download the most recent demos archive] and expand it to the root of the flash card.

=== Debug USB port ===

* This is what most developers use as it's the most convenient. Connect the debug USB port to your PC or Mac

* You can use:
** [https://github.com/pweingar/FoenixMgr FoenixMgr] - works on Windows, Mac, Linux
*** A Python script to manage the Foenix series of retro style computers through their USB debug ports. This tool allows uploading files of various formats to system RAM, and displaying memory through various means.

** [https://github.com/Trinity-11/FoenixIDE FoenixIDE] (Windows only)
*** Development and Debugging Suite for the C256 Foenix Family of Computers.

== SuperBASIC ==

The machine boots to SuperBASIC. SuperBASIC is inspired by BBC BASIC but offers quite a bit more.

* Read the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual].

* Watch EMWhite's excellent intro series on Youtube:
** Full Playlist here: [https://www.youtube.com/playlist?list=PLeHjTvk7NPiSqGz4REMH-S4hjYpLS2YNR EMWhite's Intro Series - Full Playlist].
** Part 1 can be viewed here:
<youtube>G_S2c_MsqYA</youtube>

To get started, you can type in a sample program at the command prompt:

<pre>
10 for i=1 to 5
20 print "Hello world"
30 next
run
</pre>

SuperBASIC is similar to CBM (Microsoft) BASIC but has some differences. For example, note in the sample above it's just <code>next</code> not <code>next i</code>.

The first 15 or so pages of the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual] are quite instructive.

SuperBASIC is actually much more powerful and supports structured programming (procedures, blocks etc.)

<code>dir</code> - Run this to display directory of SD card

Loading & running programs off of the SD card is similarly easy:

<pre>
load "JrWordl.bas"
run
</pre>

Similar to the C64, you can save time in loading programs from the <code>dir</code> listing by using your cursor keys to go up to the entry, typing <code>load "</code> (insert mode is active by default) etc. You can use <code>CTRL+E</code> to jump to the end of the line and use <code>CTRL+K</code> to delete any text from the cursor to the end of the line. Correctly place the closing <code>"</code> and hit <code>ENTER</code>.

<code>CTRL+C</code> acts as a "break" command and stops any running SuperBASIC program or <code>LIST</code> command.

Read built-in help/reference:

<code>/help</code> : But '''NOTE''', this erases BASIC memory! Use Backspace key to go back in menus and to exit.

Explore the included demo SuperBASIC programs:

{| class="wikitable"
! Program !! Notes !! Source
|-
| <code>JrWordl.bas</code> || Wordle game, guess 5 letter word ||
|-
| <code>mandel.bas</code> || Draws Mandlebrot set in graphics mode, takes between 2 and 3 hours || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>rpg-demo.bas</code> || UI sample that shows Zelda like RPG game. Control the character with an Atari-joystick connected to JoyPort1 || @econtrerasd
|-
| <code>Problematic_Code.bas</code> || Displays scrolling starfield ||
|-
| <code>noelrl.bas</code> || Simple integer BASIC bench mark from Noel's retro lab. Completes < 3.5 seconds, compares very favourably to other retro systems! || [https://www.youtube.com/watch?v=H05hM_Guoqk Youtube]
|-
| <code>dance.bas</code> || Animates sprite of dancer || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>luna.bas</code> || Displays simple scene ||
|-
| <code>blink.bas</code> || Blinks drive access light || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>piano.bas</code> || Play some notes with the PSG || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|}

== Native Code ==

* Binary programs for the F256 line are typically distributed as <code>pgx</code> or <code>pgz</code> files (see [[File Formats]], they are like the <code>prg</code> format in the C64 ecosystem).

* SuperBASIC: Slash (<code>/</code>) command will execute the named flash resident program, such as <code>/dos</code> or <code>/help</code> (SuperBASIC reference).

* PGZ/X files can be run from SuperBASIC with <code>/- program.pgz</code>, and from DOS with <code>- program.pgz</code>

* The <code>-</code> is also referred to as <code>pexec</code>, and is a chainloader that understands <code>pgx</code> and <code>pgz</code> formats, so <code>/- program.pgz</code> first hands over control to <code>pexec</code> which then loads the program and hands over control.

* You will typically need to reset the machine to get back to SuperBASIC.

* Switch to DOS with <code>/dos</code> and back into BASIC once there with <code>basic</code>. <code>help</code> display a list of available DOS commands.

Try the included native demo programs:

{| class="wikitable"
! Program !! Notes !! Source |
|-
| <code>wrtn0825-vcf.pgz</code> || Which Rules the Night (game) || @beethead
|-
| <code>matchit0825-vcf.pgz</code> || Match It (game) || @beethead
|-
| <code>balls.pgz</code> || Demonstrates 280 multiplexed sprites || [https://github.com/FoenixRetro/demos/blob/main/README.md GitHub]
|}

== More Resources ==

=== This Wiki ===

Explore all of the content of this Wiki, to expand your F256 series knowledge!

=== Discord ===

The [https://discord.com/invite/aAEQXZHXgM Foenix Retro Systems Discord] is the primary place to get questions answered.

Also, if you resolve your question, and you didn't find the answer here on the Wiki, '''''please consider contributing to the Wiki''''', for the benefit of others with the same question!

=== Foenix Retro Systems Newletter ===

Read back issues [http://apps.emwhite.org/foenixmarketplace/ here] (also a great source for sample programs).

Issues starting at #4 cover the F256 line. Issues 1-3 cover the previous version of the hardware (C256), although there are still many salient points.

Getting Started

2023-12-20T01:31:50Z

KoolKiwi:

== Getting programs onto the F256 ==

=== Getting Powered Up ===

==== Powering your F256K ====

The F256K is powered via a standard 2.5mm DC Connector, which takes a centre-positive 12V 2A capable Power Supply.

This type of power supply is quite common. [https://www.amazon.com/Adapter-100-240V-Transformer-Charger-Security/dp/B091XSVV1Y Example 12V 2A capable power supply] (#)

(#) ''This specific power supply has not been verified (by the author) for use with the F256K. Please update this page with verified options!''

==== Powering your F256Jr ====

The F256Jr is supplied as a Mini-ITX form factor mainboard, with a standard 24 pin ATX power supply connector for power connectivity.

Since the F256Jr needs relatively little power, compared to a mini-ATX PC, a popular DC 12V 24pin Pico ATX PSU works well and is a compact solution.

* [https://www.amazon.com/dp/B08F57GKCL Pico PSU] - You power the Pico PSU via a 12V DC center-positive Power Supply source.
* [https://www.amazon.com/dp/B07MXXXBV8 12V DC center-positive A/C Adapter] - Commonly used to power the Pico PSU.

=== SD Card ===

Both the F256K and F256JR have an SD card slot. The device sofware to read the SD card is a bit touchy (it's inherited from the Commander X16 project) and doesn't work with all SD cards

* Card should be "XC" type vs. "HC". Typically older cards in the 512MB-8GB range work pretty well, which is more than enough space anyways. Very new cards that are very large tend not to work?
* Card *MUST* be formatted FAT32 -- **NOT: FAT, FAT12, FAT16, or exFAT**. Note that while MacOS will read a FAT32 formatted card, the included disk utility won't format FAT32. Windows 10/11 works fine, but make sure to force FAT32 (or use the command line: <code>format /FS:FAT32 H:</code>)
* Some folks have had luck formatting cards with the [https://www.sdcard.org/downloads/formatter/sd-memory-card-formatter-for-windows-download/ Official SD Association formatter for Windows].

=== Demos Archive ===

* [https://github.com/FoenixRetro/Documentation/blob/main/f256/archive Download the most recent demos archive] and expand it to the root of the flash card.

=== Debug USB port ===

* This is what most developers use as it's the most convenient. Connect the debug USB port to your PC or Mac

* You can use:
** [https://github.com/pweingar/FoenixMgr FoenixMgr] - works on Windows, Mac, Linux
*** A Python script to manage the Foenix series of retro style computers through their USB debug ports. This tool allows uploading files of various formats to system RAM, and displaying memory through various means.

** [https://github.com/Trinity-11/FoenixIDE FoenixIDE] (Windows only)
*** Development and Debugging Suite for the C256 Foenix Family of Computers.

== SuperBASIC ==

The machine boots to SuperBASIC. SuperBASIC is inspired by BBC BASIC but offers quite a bit more.

* Read the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual].

* Watch EMWhite's excellent intro series on Youtube:
** Full Playlist here: [https://www.youtube.com/playlist?list=PLeHjTvk7NPiSqGz4REMH-S4hjYpLS2YNR EMWhite's Intro Series - Full Playlist].
** Part 1 can be viewed here:
<youtube>G_S2c_MsqYA</youtube>

To get started, you can type in a sample program at the command prompt:

<pre>
10 for i=1 to 5
20 print "Hello world"
30 next
run
</pre>

SuperBASIC is similar to CBM (Microsoft) BASIC but has some differences. For example, note in the sample above it's just <code>next</code> not <code>next i</code>.

The first 15 or so pages of the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual] are quite instructive.

SuperBASIC is actually much more powerful and supports structured programming (procedures, blocks etc.)

<code>dir</code> - Run this to display directory of SD card

Loading & running programs off of the SD card is similarly easy:

<pre>
load "JrWordl.bas"
run
</pre>

Similar to the C64, you can save time in loading programs from the <code>dir</code> listing by using your cursor keys to go up to the entry, typing <code>load "</code> (insert mode is active by default) etc. You can use <code>CTRL+E</code> to jump to the end of the line and use <code>CTRL+K</code> to delete any text from the cursor to the end of the line. Correctly place the closing <code>"</code> and hit <code>ENTER</code>.

<code>CTRL+C</code> acts as a "break" command and stops any running SuperBASIC program or <code>LIST</code> command.

Read built-in help/reference:

<code>/help</code> : But '''NOTE''', this erases BASIC memory! Use Backspace key to go back in menus and to exit.

Explore the included demo SuperBASIC programs:

{| class="wikitable"
! Program !! Notes !! Source
|-
| <code>JrWordl.bas</code> || Wordle game, guess 5 letter word ||
|-
| <code>mandel.bas</code> || Draws Mandlebrot set in graphics mode, takes between 2 and 3 hours || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>rpg-demo.bas</code> || UI sample that shows Zelda like RPG game. Control the character with an Atari-joystick connected to JoyPort1 || @econtrerasd
|-
| <code>Problematic_Code.bas</code> || Displays scrolling starfield ||
|-
| <code>noelrl.bas</code> || Simple integer BASIC bench mark from Noel's retro lab. Completes < 3.5 seconds, compares very favourably to other retro systems! || [https://www.youtube.com/watch?v=H05hM_Guoqk Youtube]
|-
| <code>dance.bas</code> || Animates sprite of dancer || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>luna.bas</code> || Displays simple scene ||
|-
| <code>blink.bas</code> || Blinks drive access light || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>piano.bas</code> || Play some notes with the PSG || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|}

== Native Code ==

* Binary programs for the F256 line are typically distributed as <code>pgx</code> or <code>pgz</code> files (see [[File Formats]], they are like the <code>prg</code> format in the C64 ecosystem).

* SuperBASIC: Slash (<code>/</code>) command will execute the named flash resident program, such as <code>/dos</code> or <code>/help</code> (SuperBASIC reference).

* PGZ/X files can be run from SuperBASIC with <code>/- program.pgz</code>, and from DOS with <code>- program.pgz</code>

* The <code>-</code> is also referred to as <code>pexec</code>, and is a chainloader that understands <code>pgx</code> and <code>pgz</code> formats, so <code>/- program.pgz</code> first hands over control to <code>pexec</code> which then loads the program and hands over control.

* You will typically need to reset the machine to get back to SuperBASIC.

* Switch to DOS with <code>/dos</code> and back into BASIC once there with <code>basic</code>. <code>help</code> display a list of available DOS commands.

Try the included native demo programs:

{| class="wikitable"
! Program !! Notes !! Source |
|-
| <code>wrtn0825-vcf.pgz</code> || Which Rules the Night (game) || @beethead
|-
| <code>matchit0825-vcf.pgz</code> || Match It (game) || @beethead
|-
| <code>balls.pgz</code> || Demonstrates 280 multiplexed sprites || [https://github.com/FoenixRetro/demos/blob/main/README.md GitHub]
|}

== More Resources ==

=== This Wiki ===

Explore all of the content of this Wiki, to expand your F256 series knowledge!

=== Discord ===

The [https://discord.com/invite/aAEQXZHXgM Foenix Retro Systems Discord] is the primary place to get questions answered.

Also, if you resolve your question, and you didn't find the answer here on the Wiki, '''''please consider contributing to the Wiki''''', for the benefit of others with the same question!

=== Foenix Retro Systems Newletter ===

Read back issues [http://apps.emwhite.org/foenixmarketplace/ here] (also a great source for sample programs).

Issues starting at #4 cover the F256 line. Issues 1-3 cover the previous version of the hardware (C256), although there are still many salient points.

Getting Started

2023-12-20T01:18:45Z

KoolKiwi: Added initial "Getting Powered Up" section

== Getting programs onto the F256 ==

=== Getting Powered Up ===

==== Powering your F256K ====

The F256K is powered via a standard 2.5mm DC Connector, which takes a centre-positive 12V 2A capable Power Supply.

This type of power supply is quite common. [https://www.amazon.com/Adapter-100-240V-Transformer-Charger-Security/dp/B091XSVV1Y Example 12V 2A capable power supply (#)]

(#) ''This specific power supply has not been verified (by the author) for use with the F256K. Please update this page with verified options!''

==== Powering your F256Jr ====

The F256Jr is supplied as a Mini-ITX form factor mainboard, with a standard 24 pin ATX power supply connector for power connectivity.

Since the F256Jr needs relatively little power, compared to a mini-ATX PC, a popular DC 12V 24pin Pico ATX PSU works well and is a compact solution.

* [https://www.amazon.com/dp/B08F57GKCL Pico PSU] - You power the Pico PSU via a 12V DC center-positive Power Supply source.
* [https://www.amazon.com/dp/B07MXXXBV8 12V DC center-positive A/C Adapter] - Commonly used to power the Pico PSU.

=== SD Card ===

Both the F256K and F256JR have an SD card slot. The device sofware to read the SD card is a bit touchy (it's inherited from the Commander X16 project) and doesn't work with all SD cards

* Card should be "XC" type vs. "HC". Typically older cards in the 512MB-8GB range work pretty well, which is more than enough space anyways. Very new cards that are very large tend not to work?
* Card *MUST* be formatted FAT32 -- **NOT: FAT, FAT12, FAT16, or exFAT**. Note that while MacOS will read a FAT32 formatted card, the included disk utility won't format FAT32. Windows 10/11 works fine, but make sure to force FAT32 (or use the command line: <code>format /FS:FAT32 H:</code>)
* Some folks have had luck formatting cards with the [https://www.sdcard.org/downloads/formatter/sd-memory-card-formatter-for-windows-download/ Official SD Association formatter for Windows].

=== Demos Archive ===

* [https://github.com/FoenixRetro/Documentation/blob/main/f256/archive Download the most recent demos archive] and expand it to the root of the flash card.

=== Debug USB port ===

* This is what most developers use as it's the most convenient. Connect the debug USB port to your PC or Mac

* You can use:
** [https://github.com/pweingar/FoenixMgr FoenixMgr] - works on Windows, Mac, Linux
*** A Python script to manage the Foenix series of retro style computers through their USB debug ports. This tool allows uploading files of various formats to system RAM, and displaying memory through various means.

** [https://github.com/Trinity-11/FoenixIDE FoenixIDE] (Windows only)
*** Development and Debugging Suite for the C256 Foenix Family of Computers.

== SuperBASIC ==

The machine boots to SuperBASIC. SuperBASIC is inspired by BBC BASIC but offers quite a bit more.

* Read the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual].

* Watch EMWhite's excellent intro series on Youtube:
** Full Playlist here: [https://www.youtube.com/playlist?list=PLeHjTvk7NPiSqGz4REMH-S4hjYpLS2YNR EMWhite's Intro Series - Full Playlist].
** Part 1 can be viewed here:
<youtube>G_S2c_MsqYA</youtube>

To get started, you can type in a sample program at the command prompt:

<pre>
10 for i=1 to 5
20 print "Hello world"
30 next
run
</pre>

SuperBASIC is similar to CBM (Microsoft) BASIC but has some differences. For example, note in the sample above it's just <code>next</code> not <code>next i</code>.

The first 15 or so pages of the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual] are quite instructive.

SuperBASIC is actually much more powerful and supports structured programming (procedures, blocks etc.)

<code>dir</code> - Run this to display directory of SD card

Loading & running programs off of the SD card is similarly easy:

<pre>
load "JrWordl.bas"
run
</pre>

Similar to the C64, you can save time in loading programs from the <code>dir</code> listing by using your cursor keys to go up to the entry, typing <code>load "</code> (insert mode is active by default) etc. You can use <code>CTRL+E</code> to jump to the end of the line and use <code>CTRL+K</code> to delete any text from the cursor to the end of the line. Correctly place the closing <code>"</code> and hit <code>ENTER</code>.

<code>CTRL+C</code> acts as a "break" command and stops any running SuperBASIC program or <code>LIST</code> command.

Read built-in help/reference:

<code>/help</code> : But '''NOTE''', this erases BASIC memory! Use Backspace key to go back in menus and to exit.

Explore the included demo SuperBASIC programs:

{| class="wikitable"
! Program !! Notes !! Source
|-
| <code>JrWordl.bas</code> || Wordle game, guess 5 letter word ||
|-
| <code>mandel.bas</code> || Draws Mandlebrot set in graphics mode, takes between 2 and 3 hours || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>rpg-demo.bas</code> || UI sample that shows Zelda like RPG game. Control the character with an Atari-joystick connected to JoyPort1 || @econtrerasd
|-
| <code>Problematic_Code.bas</code> || Displays scrolling starfield ||
|-
| <code>noelrl.bas</code> || Simple integer BASIC bench mark from Noel's retro lab. Completes < 3.5 seconds, compares very favourably to other retro systems! || [https://www.youtube.com/watch?v=H05hM_Guoqk Youtube]
|-
| <code>dance.bas</code> || Animates sprite of dancer || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>luna.bas</code> || Displays simple scene ||
|-
| <code>blink.bas</code> || Blinks drive access light || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>piano.bas</code> || Play some notes with the PSG || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|}

== Native Code ==

* Binary programs for the F256 line are typically distributed as <code>pgx</code> or <code>pgz</code> files (see [[File Formats]], they are like the <code>prg</code> format in the C64 ecosystem).

* SuperBASIC: Slash (<code>/</code>) command will execute the named flash resident program, such as <code>/dos</code> or <code>/help</code> (SuperBASIC reference).

* PGZ/X files can be run from SuperBASIC with <code>/- program.pgz</code>, and from DOS with <code>- program.pgz</code>

* The <code>-</code> is also referred to as <code>pexec</code>, and is a chainloader that understands <code>pgx</code> and <code>pgz</code> formats, so <code>/- program.pgz</code> first hands over control to <code>pexec</code> which then loads the program and hands over control.

* You will typically need to reset the machine to get back to SuperBASIC.

* Switch to DOS with <code>/dos</code> and back into BASIC once there with <code>basic</code>. <code>help</code> display a list of available DOS commands.

Try the included native demo programs:

{| class="wikitable"
! Program !! Notes !! Source |
|-
| <code>wrtn0825-vcf.pgz</code> || Which Rules the Night (game) || @beethead
|-
| <code>matchit0825-vcf.pgz</code> || Match It (game) || @beethead
|-
| <code>balls.pgz</code> || Demonstrates 280 multiplexed sprites || [https://github.com/FoenixRetro/demos/blob/main/README.md GitHub]
|}

== More Resources ==

=== This Wiki ===

Explore all of the content of this Wiki, to expand your F256 series knowledge!

=== Discord ===

The [https://discord.com/invite/aAEQXZHXgM Foenix Retro Systems Discord] is the primary place to get questions answered.

Also, if you resolve your question, and you didn't find the answer here on the Wiki, '''''please consider contributing to the Wiki''''', for the benefit of others with the same question!

=== Foenix Retro Systems Newletter ===

Read back issues [http://apps.emwhite.org/foenixmarketplace/ here] (also a great source for sample programs).

Issues starting at #4 cover the F256 line. Issues 1-3 cover the previous version of the hardware (C256), although there are still many salient points.

FNX6809 Overview

2023-12-18T05:37:14Z

KoolKiwi: Initial page for FNX6809

File:FNX6809 Adapter.jpeg

2023-12-18T05:31:08Z

KoolKiwi:

File:FNX6809 Transparent SideView.png

2023-12-18T05:24:25Z

KoolKiwi:

65816 Overview

2023-12-17T21:09:31Z

KoolKiwi:

The W65C816 (also 65C816 or 65816) is a 16-bit microprocessor (MPU) developed and sold by the Western Design Center (WDC). Introduced in 1983, the W65C816 is an enhanced version of the WDC W65C02 8-bit MPU, itself a CMOS enhancement of the venerable MOS Technology 6502 NMOS MPU.

The 65C816 is a CPU option supported by the Foenix F256, that can be dropped-in, in place pf the default W65C02 processor supplied with the F256.

The "65" in the part's designation comes from its 65C02 compatibility mode, and the "816" signifies that the MPU has selectable 8-bit and 16-bit register sizes. In addition to the availability of 16-bit registers, the W65C816 processor itself extends potential memory addressing to 24-bits, supporting up to 16 megabytes of random-access memory. It has an enhanced instruction set and a 16-bit stack pointer, as well as several new control signals for improved system hardware management.

Despite allowing 24-bit addressing, a 65816 installed in a Foenix F256 still utilises the same 16-bit physical address space of the original W65C02 processor.

At reset, the W65C816 starts in "emulation mode", meaning it substantially behaves as a 65C02. In fact, a 65816 in default power-up "emulation mode" is cycle-accurate with the original MOS 6502 processor, whereas the W65C02 differs on some instructions.

User programs can then switch the W65C816 to "native mode" with a two instruction sequence, causing it to enable all enhanced features, yet still maintain a substantial degree of backward compatibility with most 65C02 software.

However, unlike the DIP40 version of the W65C02, which is more-or-less a pin-compatible replacement for its NMOS ancestor (excepting mostly pin 1 - Vss / VPB), the DIP40 W65C816 is not directly pin-compatible with any other 6502 family MPU.

The W65C816 pin differences are mostly around the clock pins and some control pins. Despite this, the W65C816 can be a drop-in replacement for the W65C02 on the Foenix F256 series. No FPGA upgrade is necessary when in emulation mode (#).

(#) ''This point (noted from the main site F256K ordering page), needs more explanation by someone more knowledgable on F256 operation with a W65C816 processor installed.''

65816 Overview

2023-12-17T21:05:15Z

KoolKiwi: Initial page creation

The W65C816 (also 65C816 or 65816) is a 16-bit microprocessor (MPU) developed and sold by the Western Design Center (WDC). Introduced in 1983, the W65C816 is an enhanced version of the WDC W65C02 8-bit MPU, itself a CMOS enhancement of the venerable MOS Technology 6502 NMOS MPU.

The 65C816 is a CPU option supported by the Foenix F256, that can be dropped-in, in place pf the default W65C02 processor supplied with the F526.

The 65 in the part's designation comes from its 65C02 compatibility mode, and the 816 signifies that the MPU has selectable 8- and 16-bit register sizes. In addition to the availability of 16-bit registers, the W65C816 processor itself extends potential memory addressing to 24 bits, supporting up to 16 megabytes of random-access memory. It has an enhanced instruction set and a 16-bit stack pointer, as well as several new electrical signals for improved system hardware management.

Despite allowing 24-bit addressing, a 65816 installed in a Foenix F256 still utilises the same 16-bit physical address space of the original W65C02 processor.

At reset, the W65C816 starts in "emulation mode", meaning it substantially behaves as a 65C02. In fact, a 65816 in default power-up "emulation mode" is cycle-accurate with the original MOS 6502 processor, whereas the W65C02 differs on some instructions.

User programs can then switch the W65C816 may be switched to "native mode" with a two instruction sequence, causing it to enable all enhanced features, yet still maintain a substantial degree of backward compatibility with most 65C02 software.

However, unlike the DIP40 version of the W65C02, which is more-or-less a pin-compatible replacement for its NMOS ancestor (excepting mostly pin 1 Vss / VPB), the DIP40 W65C816 is not directly pin-compatible with any other 6502 family MPU.

The W65C816 pin differences are mostly around the clock pins and some control pins. Despite this, the W65C816 can be a drop-in replacement for the W65C02 on the Foenix F256 series. No FPGA upgrade is necessary when in emulation mode (#).

(#) ''This point (noted from the main site F256K ordering page), needs more explanation by someone more knowledgable on F256 operation with a W65C816 processor installed.''

65816 Assembly Tutorial

2023-12-17T20:27:40Z

KoolKiwi: Initial page creation

== 65816 Assembly Tutorial ==

Watch Tail Recursive's 65816 Assembly Tutorial series on Youtube:

Although this series is noted as being for the C256 Foenix, as a 65816 processor coding "Tutorial", I expect it should be just as relevant to a W65C816 processor equipped F256.

* Full Playlist here: [https://www.youtube.com/playlist?list=PLLl2XbF83eA4HPi4BFN4eMRb317o8cKgK Tail Recursive's 65816 Assembly Tutorial series - Full Playlist].

* Part 1 can be viewed here:
<youtube>tw18GG0N2iM</youtube>

Template:Main2/65816 Processor

2023-12-17T20:17:33Z

KoolKiwi: Just updating heading to the explicit WDC processor name / add tutorial page link

'''W65C816 Processor'''
* [[65816 Overview]]
* [[65816 Assembly Tutorial]]
* ...

Main Page

2023-12-17T20:14:02Z

KoolKiwi: Just updating to explicit W65C816 processor naming

<div id="mainpage"></div> __NOTOC__ __NOEDITSECTION__


<div style="margin: 0 0 15px 0; padding: 1px; border: 1px solid #CCCCCC;">
{| style="width: 100%; margin: 0; padding: 0; border: 0; background-color: #FCFCFC; color: #000000; border-collapse: collapse;"
| align="center" style="vertical-align: top;"|
<div style="font-size: 150%;">Welcome to the Foenix Retro Systems' F256x series Wiki</div>
<div style="font-size: 100%; margin-top: 0.7em; line-height: 130%;">Dedicated to the WDC65C02/WDC65C816 or FNX6809 based F256x series.</div>
|}
</div>


{| style="width: 100%; margin: 0; padding: 0; border: 0; border-collapse: collapse;"
| style="padding: 0; width: 25%; vertical-align: top;" |


{{NocatBox|subject=Getting Started|page=Main2/Getting_Started}}
{{NocatBox|subject=Technical Overview|page=Main2/Technical_Overview}}
{{NocatBox|subject=System Maintenance|page=Main2/System_Maintenance}}

| style="padding: 0 0 0 10px; width: 25%; vertical-align: top;" |


{{NocatBox|subject=Software Development|page=Main2/Software_Development}}
{{NocatBox|subject=W65C816 Processor|page=Main2/65816_Processor}}
{{NocatBox|subject=FNX6809 Processor|page=Main2/FNX6809_Processor}}
|}

Manuals

2023-12-17T20:01:55Z

KoolKiwi: Initial page creation

== F256 Reference Manual ==

* [https://github.com/pweingar/F256Manual F256 Reference Manual - Github Home (PDF available)]

== F256 SuperBASIC Reference Manual ==

* [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf F256 SuperBASIC Reference Manual (PDF)].

Getting Started

2023-12-17T04:55:10Z

KoolKiwi: Translated from https://github.com/FoenixRetro/Documentation/blob/main/f256/quick_start.md (in the interests of Wiki knowledge centralisation).

== Getting programs onto the F256 ==

=== SD Card ===

Both the F256K and F256JR have an SD card slot. The device sofware to read the SD card is a bit touchy (it's inherited from the Commander X16 project) and doesn't work with all SD cards

* Card should be "XC" type vs. "HC". Typically older cards in the 512MB-8GB range work pretty well, which is more than enough space anyways. Very new cards that are very large tend not to work?
* Card *MUST* be formatted FAT32 -- **NOT: FAT, FAT12, FAT16, or exFAT**. Note that while MacOS will read a FAT32 formatted card, the included disk utility won't format FAT32. Windows 10/11 works fine, but make sure to force FAT32 (or use the command line: <code>format /FS:FAT32 H:</code>)
* Some folks have had luck formatting cards with the [https://www.sdcard.org/downloads/formatter/sd-memory-card-formatter-for-windows-download/ Official SD Association formatter for Windows].

=== Demos Archive ===

* [https://github.com/FoenixRetro/Documentation/blob/main/f256/archive Download the most recent demos archive] and expand it to the root of the flash card.

=== Debug USB port ===

* This is what most developers use as it's the most convienent. Connect the debug USB port to your PC or Mac

* You can use:
** [https://github.com/pweingar/FoenixMgr FoenixMgr] - works on Windows, Mac, Linux
*** A Python script to manage the Foenix series of retro style computers through their USB debug ports. This tool allows uploading files of various formats to system RAM, and displaying memory through various means.

** [https://github.com/Trinity-11/FoenixIDE FoenixIDE] (Windows only)
*** Development and Debugging Suite for the C256 Foenix Family of Computers.

== SuperBASIC ==

The machine boots to SuperBASIC. SuperBASIC is inspired by BBC BASIC but offers quite a bit more.

* Read the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual].

* Watch EMWhite's excellent intro series on Youtube:
** Full Playlist here: [https://www.youtube.com/playlist?list=PLeHjTvk7NPiSqGz4REMH-S4hjYpLS2YNR EMWhite's Intro Series - Full Playlist].
** Part 1 can be viewed here:
<youtube>G_S2c_MsqYA</youtube>

To get started, you can type in a sample program at the command prompt:

<pre>
10 for i=1 to 5
20 print "Hello world"
30 next
run
</pre>

SuperBASIC is similar to CBM (Microsoft) BASIC but has some differences. For example, note in the sample above it's just <code>next</code> not <code>next i</code>.

The first 15 or so pages of the [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual] are quite instructive.

SuperBASIC is actually much more powerful and supports structured programming (procedures, blocks etc.)

<code>dir</code> - Run this to display directory of SD card

Loading & running programs off of the SD card is similarly easy:

<pre>
load "JrWordl.bas"
run
</pre>

Similar to the C64, you can save time in loading programs from the <code>dir</code> listing by using your cursor keys to go up to the entry, typing <code>load "</code> (insert mode is active by default) etc. You can use <code>CTRL+E</code> to jump to the end of the line and use <code>CTRL+K</code> to delete any text from the cursor to the end of the line. Correctly place the closing <code>"</code> and hit <code>ENTER</code>.

<code>CTRL+C</code> acts as a "break" command and stops any running SuperBASIC program or <code>LIST</code> command.

Read built-in help/reference:

<code>/help</code> : But '''NOTE''', this erases BASIC memory! Use Backspace key to go back in menus and to exit.

Explore the included demo SuperBASIC programs:

{| class="wikitable"
! Program !! Notes !! Source
|-
| <code>JrWordl.bas</code> || Wordle game, guess 5 letter word ||
|-
| <code>mandel.bas</code> || Draws Mandlebrot set in graphics mode, takes between 2 and 3 hours || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>rpg-demo.bas</code> || UI sample that shows Zelda like RPG game. Control the character with an Atari-joystick connected to JoyPort1 || @econtrerasd
|-
| <code>Problematic_Code.bas</code> || Displays scrolling starfield ||
|-
| <code>noelrl.bas</code> || Simple integer BASIC bench mark from Noel's retro lab. Completes < 3.5 seconds, compares very favourably to other retro systems! || [https://www.youtube.com/watch?v=H05hM_Guoqk Youtube]
|-
| <code>dance.bas</code> || Animates sprite of dancer || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>luna.bas</code> || Displays simple scene ||
|-
| <code>blink.bas</code> || Blinks drive access light || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|-
| <code>piano.bas</code> || Play some notes with the PSG || [https://github.com/Mu0n/F256KbasicBASICdoodles @Mu0n]
|}

== Native Code ==

* Binary programs for the F256 line are typically distributed as <code>pgx</code> or <code>pgz</code> files (see [[File Formats]], they are like the <code>prg</code> format in the C64 ecosystem).

* SuperBASIC: Slash (<code>/</code>) command will execute the named flash resident program, such as <code>/dos</code> or <code>/help</code> (SuperBASIC reference).

* PGZ/X files can be run from SuperBASIC with <code>/- program.pgz</code>, and from DOS with <code>- program.pgz</code>

* The <code>-</code> is also referred to as <code>pexec</code>, and is a chainloader that understands <code>pgx</code> and <code>pgz</code> formats, so <code>/- program.pgz</code> first hands over control to <code>pexec</code> which then loads the program and hands over control.

* You will typically need to reset the machine to get back to SuperBASIC.

* Switch to DOS with <code>/dos</code> and back into BASIC once there with <code>basic</code>. <code>help</code> display a list of available DOS commands.

Try the included native demo programs:

{| class="wikitable"
! Program !! Notes !! Source |
|-
| <code>wrtn0825-vcf.pgz</code> || Which Rules the Night (game) || @beethead
|-
| <code>matchit0825-vcf.pgz</code> || Match It (game) || @beethead
|-
| <code>balls.pgz</code> || Demonstrates 280 multiplexed sprites || [https://github.com/FoenixRetro/demos/blob/main/README.md GitHub]
|}

== More Resources ==

=== This Wiki ===

Explore all of the content of this Wiki, to expand your F256 series knowledge!

=== Discord ===

The [https://discord.com/invite/aAEQXZHXgM Foenix Retro Systems Discord] is the primary place to get questions answered.

Also, if you resolve your question, and you didn't find the answer here on the Wiki, '''''please consider contributing to the Wiki''''', for the benefit of others with the same question!

=== Foenix Retro Systems Newletter ===

Read back issues [http://apps.emwhite.org/foenixmarketplace/ here] (also a great source for sample programs).

Issues starting at #4 cover the F256 line. Issues 1-3 cover the previous version of the hardware (C256), although there are still many salient points.

Talk:Main Page

2023-12-16T22:01:40Z

KoolKiwi:

# Editing instructions

Q. How to edit the contents of the boxes shown on the main page? The source refers to "NocatBox". Where is the content?

A. Use the "Edit Source" option of the Main PAge, and then expand the "Templates used on this page:" at the bottom of the edit source page.
Then select the individiual page section you want to edit.

Kernel & SuperBASIC Updates

2023-12-16T05:53:30Z

KoolKiwi: Initial Kernel & SuperBASIC Updates page, based on main website info.

Template:Main2/System Maintenance

2023-12-16T05:35:40Z

KoolKiwi: Combine Kernel & SuperBASIC Updates page

'''System Maintenance'''
* [[FPGA Releases]]
* [[Kernel & SuperBASIC Updates]]
* [[Optional Upgrades]]
* ...

FPGA Releases

2023-12-16T05:23:31Z

KoolKiwi:

== F256K FPGA Releases ==

=== Current F256K Release ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256K
| style="white-space:nowrap;"| Release Candidate 13
| style="white-space:nowrap;"| 12-Dec-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1054250189675843736/1182993744044249149/F256K_WBh_Dec9th_RevB0x_RC13_0000.jic F256K_WBh_Dec9th_RevB0x_RC13_0000.jic]
|
* Fixes a problem with Interrupt from timer0 that was working on the Jr.
* Resolves a discrepancy between the F256Jr interrupt block and the F256K.
|}

=== Previous F256K Releases ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256K
| style="white-space:nowrap;"| Release Candidate 12
| style="white-space:nowrap;"| 19-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1054250189675843736/1175965530000212048/F256K_WBh_Nov19th_RevB0x_RC12_0011.jic F256K_WBh_Nov19th_RevB0x_RC12_0011.jic]
|
Corrects the issue with no-response from command $20 & $21 (not being processed in the early parser).
The Jr doesn't have the issue.
|}

== F256Jr FPGA Releases ==

=== Current F256Jr Release ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256Jr
| style="white-space:nowrap;"| Release Candidate 17
| style="white-space:nowrap;"| 18-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1010352563406770217/1175321652859523123/F256M_Wbh_Nov18th_2023_RC17_0100.jic F256M_Wbh_Nov18th_2023_RC17_0100.jic]
| In light of decision to dump the big ticket items and the accessories from the store...
* Removed the very SPI core introduced yesterday to drive the FNXNET51 module.
* Removed the DP memory for the MMU and replace it back with simple Registers, which means that when you reset the system, the MMU, Page0 will be reset back to the way it was. However, the caveat is that if you change between RAM to FLASH MMU default value, you need to do a reset, either a debug reset or General Reset because the MMU is now only 32bytes in Size, so, 4 pages of 8 values.
|}

=== Previous F256Jr Releases ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256Jr
| style="white-space:nowrap;"| Release Candidate 16
| style="white-space:nowrap;"| 17-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1010352563406770217/1174998797991022632/F256M_WBh_Nov17th_2023_RC16_0111.jic F256M_WBh_Nov17th_2023_RC16_0111.jic]
|
* No Write Allowed when Debug Port writes in the MMU Memory Zone
* Incorporation of a new SPI Controller to interface with the FNXNET51 module using the NES/SNES MiniDin9 Connector
* ReSync of the Debug Generated RDY to stop the CPU. (untested)
|}

== FPGA Upgrade Guide ==

If you haven’t upgraded FPGAs before, below are some great videos to guide you.

You will need to download Quartus Prime Lite 18.1 Edition, since you are going to target a EP4CE15 FPGA (Cyclone 4).

Do not update to the latest version of Quartus Prime Lite, as the latest version doesn’t support that family of FPGA anymore and the software is very big.

Also, one might want to download only the "Intel® Quartus® Prime Programmer and Tools" as opposed to download the whole software by clicking on "Addition Software"

[https://www.intel.com/content/www/us/en/software-kit/665990/intel-quartus-prime-lite-edition-design-software-version-18-1-for-windows.html Intel Quartus Prime Lite Edition 18.1 for Windows]

[https://www.intel.com/content/www/us/en/software-kit/665988/intel-quartus-prime-lite-edition-design-software-version-18-1-for-linux.html Intel Quartus Prime Lite Edition 18.1 for Linux]

=== Video Guide ===

Note that the below Video Guide applies to both the F256K & F256Jr, despite it just being titled F256K.

==== How to Upgrade the F256K FPGA (and F256Jr) ====

<youtube>U7bq7t_qjxg</youtube>

FPGA Releases

2023-12-16T05:05:39Z

KoolKiwi: Transition to embedded YouTube videos (with newly installed extension)

== F256K FPGA Releases ==

=== Current F256K Release ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256K
| style="white-space:nowrap;"| Release Candidate 13
| style="white-space:nowrap;"| 12-Dec-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1054250189675843736/1182993744044249149/F256K_WBh_Dec9th_RevB0x_RC13_0000.jic F256K_WBh_Dec9th_RevB0x_RC13_0000.jic]
|
* Fixes a problem with Interrupt from timer0 that was working on the Jr.
* Resolves a discrepancy between the F256Jr interrupt block and the F256K.
|}

=== Previous F256K Releases ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256K
| style="white-space:nowrap;"| Release Candidate 12
| style="white-space:nowrap;"| 19-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1054250189675843736/1175965530000212048/F256K_WBh_Nov19th_RevB0x_RC12_0011.jic F256K_WBh_Nov19th_RevB0x_RC12_0011.jic]
|
Corrects the issue with no-response from command $20 & $21 (not being processed in the early parser).
The Jr doesn't have the issue.
|}

== F256Jr FPGA Releases ==

=== Current F256Jr Release ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256Jr
| style="white-space:nowrap;"| Release Candidate 17
| style="white-space:nowrap;"| 18-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1010352563406770217/1175321652859523123/F256M_Wbh_Nov18th_2023_RC17_0100.jic F256M_Wbh_Nov18th_2023_RC17_0100.jic]
| In light of decision to dump the big ticket items and the accessories from the store...
* Removed the very SPI core introduced yesterday to drive the FNXNET51 module.
* Removed the DP memory for the MMU and replace it back with simple Registers, which means that when you reset the system, the MMU, Page0 will be reset back to the way it was. However, the caveat is that if you change between RAM to FLASH MMU default value, you need to do a reset, either a debug reset or General Reset because the MMU is now only 32bytes in Size, so, 4 pages of 8 values.
|}

=== Previous F256Jr Releases ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256Jr
| style="white-space:nowrap;"| Release Candidate 16
| style="white-space:nowrap;"| 17-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1010352563406770217/1174998797991022632/F256M_WBh_Nov17th_2023_RC16_0111.jic F256M_WBh_Nov17th_2023_RC16_0111.jic]
|
* No Write Allowed when Debug Port writes in the MMU Memory Zone
* Incorporation of a new SPI Controller to interface with the FNXNET51 module using the NES/SNES MiniDin9 Connector
* ReSync of the Debug Generated RDY to stop the CPU. (untested)
|}

== FPGA Upgrade Guide ==

If you haven’t upgraded FPGAs before, below are some great videos to guide you.

You will need to download Quartus Prime Lite 18.1 Edition, since you are going to target a EP4CE15 FPGA (Cyclone 4).

Do not update to the latest version of Quartus Prime Lite, as the latest version doesn’t support that family of FPGA anymore and the software is very big.

Also, one might want to download only the "Intel® Quartus® Prime Programmer and Tools" as opposed to download the whole software by clicking on "Addition Software"

[https://www.intel.com/content/www/us/en/software-kit/665990/intel-quartus-prime-lite-edition-design-software-version-18-1-for-windows.html Intel Quartus Prime Lite Edition 18.1 for Windows]

[https://www.intel.com/content/www/us/en/software-kit/665988/intel-quartus-prime-lite-edition-design-software-version-18-1-for-linux.html Intel Quartus Prime Lite Edition 18.1 for Linux]

=== Video Guides ===

==== How to Upgrade the F256K FPGA ====

<youtube>U7bq7t_qjxg</youtube>

==== Upgrading GAVIN and VICKY ====

<youtube>0laamngVrvM</youtube>

FPGA Releases

2023-12-16T02:53:18Z

KoolKiwi: Differentuated F256Jr & F256K FPGA Releases. Added NoWrap on first 4 table columns.

== F256K FPGA Releases ==

=== Current F256K Release ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256K
| style="white-space:nowrap;"| Release Candidate 13
| style="white-space:nowrap;"| 12-Dec-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1054250189675843736/1182993744044249149/F256K_WBh_Dec9th_RevB0x_RC13_0000.jic F256K_WBh_Dec9th_RevB0x_RC13_0000.jic]
|
* Fixes a problem with Interrupt from timer0 that was working on the Jr.
* Resolves a discrepancy between the F256Jr interrupt block and the F256K.
|}

=== Previous F256K Releases ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256K
| style="white-space:nowrap;"| Release Candidate 12
| style="white-space:nowrap;"| 19-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1054250189675843736/1175965530000212048/F256K_WBh_Nov19th_RevB0x_RC12_0011.jic F256K_WBh_Nov19th_RevB0x_RC12_0011.jic]
|
Corrects the issue with no-response from command $20 & $21 (not being processed in the early parser).
The Jr doesn't have the issue.
|}

== F256Jr FPGA Releases ==

=== Current F256Jr Release ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256Jr
| style="white-space:nowrap;"| Release Candidate 17
| style="white-space:nowrap;"| 18-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1010352563406770217/1175321652859523123/F256M_Wbh_Nov18th_2023_RC17_0100.jic F256M_Wbh_Nov18th_2023_RC17_0100.jic]
| In light of decision to dump the big ticket items and the accessories from the store...
* Removed the very SPI core introduced yesterday to drive the FNXNET51 module.
* Removed the DP memory for the MMU and replace it back with simple Registers, which means that when you reset the system, the MMU, Page0 will be reset back to the way it was. However, the caveat is that if you change between RAM to FLASH MMU default value, you need to do a reset, either a debug reset or General Reset because the MMU is now only 32bytes in Size, so, 4 pages of 8 values.
|}

=== Previous F256Jr Releases ===

{| class="wikitable"
! Series !! Version !! Date !! Download !! Release Notes
|-
| style="white-space:nowrap;"| F256Jr
| style="white-space:nowrap;"| Release Candidate 16
| style="white-space:nowrap;"| 17-Nov-2023
| style="white-space:nowrap;"| [https://cdn.discordapp.com/attachments/1010352563406770217/1174998797991022632/F256M_WBh_Nov17th_2023_RC16_0111.jic F256M_WBh_Nov17th_2023_RC16_0111.jic]
|
* No Write Allowed when Debug Port writes in the MMU Memory Zone
* Incorporation of a new SPI Controller to interface with the FNXNET51 module using the NES/SNES MiniDin9 Connector
* ReSync of the Debug Generated RDY to stop the CPU. (untested)
|}

== FPGA Upgrade Guide ==

If you haven’t upgraded FPGAs before, below are some great videos to guide you.

You will need to download Quartus Prime Lite 18.1 Edition, since you are going to target a EP4CE15 FPGA (Cyclone 4).

Do not update to the latest version of Quartus Prime Lite, as the latest version doesn’t support that family of FPGA anymore and the software is very big.

Also, one might want to download only the "Intel® Quartus® Prime Programmer and Tools" as opposed to download the whole software by clicking on "Addition Software"

[https://www.intel.com/content/www/us/en/software-kit/665990/intel-quartus-prime-lite-edition-design-software-version-18-1-for-windows.html Intel Quartus Prime Lite Edition 18.1 for Windows]

[https://www.intel.com/content/www/us/en/software-kit/665988/intel-quartus-prime-lite-edition-design-software-version-18-1-for-linux.html Intel Quartus Prime Lite Edition 18.1 for Linux]

=== Video Guides ===

[https://www.youtube.com/watch?v=U7bq7t_qjxg YouTube: How to Upgrade the F256K FPGA]

[https://www.youtube.com/watch?v=0laamngVrvM YouTube: Upgrading GAVIN and VICKY]

FPGA Releases

2023-12-15T20:40:30Z

KoolKiwi: Initial FPGA Releases page, replicated from a combination of c256foenix.com and Discord info.

== FPGA Releases ==

=== Current Release ===

{| class="wikitable"
! Version !! Date !! Download !! Release Notes
|-
| Release Candidate 13
| 12-Dec-2023
| [https://cdn.discordapp.com/attachments/1054250189675843736/1182993744044249149/F256K_WBh_Dec9th_RevB0x_RC13_0000.jic F256K_WBh_Dec9th_RevB0x_RC13_0000.jic]
| Fixes a problem with Interrupt from timer0 that was working on the Jr.
Resolves a discrepancy between the F256Jr interrupt block and the F256K.
|}

=== Previous Releases ===

{| class="wikitable"
! Version !! Date !! Download !! Release Notes
|-
| Release Candidate 12
| 19-Nov-2023
| [https://cdn.discordapp.com/attachments/1054250189675843736/1175965530000212048/F256K_WBh_Nov19th_RevB0x_RC12_0011.jic F256K_WBh_Nov19th_RevB0x_RC12_0011.jic]
| Corrects the issue with no-response from command $20 & $21 (not being processed in the early parser).
The Jr doesn't have the issue.
|}

== FPGA Upgrade Guide ==

If you haven’t upgraded FPGAs before, below are some great videos to guide you.

You will need to download Quartus Prime Lite 18.1 Edition, since you are going to target a EP4CE15 FPGA (Cyclone 4).

Do not update to the latest version of Quartus Prime Lite, as the latest version doesn’t support that family of FPGA anymore and the software is very big.

[https://www.intel.com/content/www/us/en/software-kit/665990/intel-quartus-prime-lite-edition-design-software-version-18-1-for-windows.html Intel Quartus Prime Lite Edition 18.1 for Windows]

[https://www.intel.com/content/www/us/en/software-kit/665988/intel-quartus-prime-lite-edition-design-software-version-18-1-for-linux.html Intel Quartus Prime Lite Edition 18.1 for Linux]

=== Video Guides ===

[https://www.youtube.com/watch?v=U7bq7t_qjxg YouTube: How to Upgrade the F256K FPGA]

[https://www.youtube.com/watch?v=0laamngVrvM YouTube: Upgrading GAVIN and VICKY]

File Formats

2023-12-14T22:40:43Z

KoolKiwi: Added example of a KUP header block definition.

The F256 line has three file formats, each with slightly different properties and use cases. Additionally, pure binary files are often used by developers. The machine will be in a slightly different state, depending on how the program was started. We will cover this in the following sections.

== Binary ==
The binary file format is not a format as such. It is an image that is loaded directly into the F256's memory by a utility program running on the PC or Mac, and the F256 is then reset. Such an image must include properly initialized interrupt vectors, especially the RESET vector.

Running such an image requires knowledge of its starting address and a properly configured USB connection between the PC or Mac and the F256. Also, a jumper on the F256 Jr. motherboard must be moved to the "Boot-to-RAM" position. This is not necessary on the F256K.

Binary images should only be used by the developer while developing, as it is a very user-unfriendly method of distributing software, requiring tethering to a PC or Mac.

== KUP ==
KUPs are very simple and can contain 40 KiB code/data when run from flash, or 32 KiB when run from disk. Contained in their header is and entry point address, and the slot number of where they should be mapped into, the first possible slot being #1 ($2000).

DOS expands on the KUP header defined by the MicroKernel in a backwards compatible way.

The header is very simple:

<pre>
Byte 0 signature: $F2
Byte 1 signature: $56
Byte 2 the size of program in 8k blocks
Byte 3 the starting slot of the program (ie where to map it)
Bytes 4-5 the start address of the program
Byte 6 header structure version (indicates version of header, current 0 or 1)
Bytes 7-9 reserved
Bytes ?-? zero-terminated name of the program.
Bytes ?-? zero-terminated string describing the arguments. (in version >= 1)
Bytes ?-? zero-terminated string describing the program's function. (in version >= 1)
</pre>

Example of a header block definition:

<pre>
EXEC = __STARTUP_LOAD__
SLOT = __STARTUP_LOAD__ >> 13
COUNT = __END_LOAD__ >> 13 ; Assumes code starts at $2000.

.byte $f2,$56 ; signature
.byte <COUNT ; block count
.byte <SLOT ; start slot
.word EXEC ; exec addr
.byte 1 ; CHANGED, structure version
.byte 0 ; reserved
.byte 0 ; reserved
.byte 0 ; reserved
.asciiz "cwrite" ; name
.asciiz " "
.asciiz "App to program the Flash Cartridge"

.segment "END"
</pre>

The MicroKernel ignores the "argument" and "function" header entries. These are printed by DOS' <code>lsf</code> command, and only if the header version is greater or equal to 1.

When instructed to start a named KUP, the kernel will search through memory to find a match. First the expansion memory is searched, this could be either RAM or ROM. Then the on-board flash memory is searched. If DIP switch #1 is in the "on" position, the kernel will search memory banks 1-5 before the expansion blocks.

This sequence is also performed when the kernel starts up, for instance when the machine is reset or is first powered on.

Testing a KUP is therefore as easy as uploading it to a block of memory, and is an excellent choice for testing a program that interacts with the kernel. Though you should remember that this program will stay in memory as long as the machine is powered on, and may also survive a short power cut. Such a program should therefore, when testing, destroy its own header by overwriting the first two bytes with some values that are not the magic signature, to avoid being started again and again.

A KUP residing in flash does not "return" in the common sense of the word. If it has to terminate, it can either reset the machine, or use `RunNamed` to start another KUP.

On the other hand, when running a KUP from disk, it is able to return to DOS in a controlled manner. Distributing software intended to be run from disk as KUP is usually discouraged, as the program can only be started from DOS and not from SuperBASIC. It can, however, be appropriate for small utility programs mostly intended for maintenance tasks and so forth. When distributing software, you should prefer using one of the PGX or PGZ formats.

A KUP loaded from disk may exit back to DOS by issuing an RTS instruction. Additionally, the carry may be set if the machine should be reset, or carry clear to continue running DOS. Be aware that you must leave the MMU configuration in the state you found it for this to work properly. You should also keep away from the $0200-$07FF range completely.

When a KUP is started from flash, LUT #3 slots 0-5 is mapped to RAM banks 0-5, *except* where the KUP's header specifies where into should be mapped.

A KUP started from disk has LUT #3 slots 0-4 mapped to RAM, some of which will be the program itself.

In both cases the kernel is intact and available for use straight away.

== PGX ==
This format is a simple, single segment executable, which can be loaded as low as $0200. A PGX is loaded using <code>pexec</code>. <code>pexec</code> treats PGX and PGZ in exactly the same way, and information on how PGZ is handled also applies to PGX.

PGZ is similar in scale to MS-DOS’s COM format, or the Commodore PRG format. It consists of a single segment of data to be loaded to
a specific address, where that address is also the starting address.

PGX starts with a header to identify the file and the starting address:

* The first three bytes are the ASCII codes for “PGX”.
* The fourth byte is the CPU and version identification byte. Bits 0 through 3 represent the CPU code, and bits 4 through 7 represent the version of PGX supported. At the moment, there is just version 0. The CPU code can be 1 for the WDC65816, or 2 for the M680x0.
* The next four bytes (that is, bytes 4 through 7) are the address of the destination, in big-endian format (most significant byte first). This address is both the address of the location in which to load the first byte of the data and is also the starting address for the file.

All bytes after the header are the contents of the file to be loaded into memory.

== PGZ ==
This is a more advanced multi-segment executable. It can be loaded as low as $0200. It is loaded using <code>pexec</code>.

When <code>pexec</code> loads a program, the program must not load itself into RAM banks 6 & 7, as these are used by the kernel, and the kernel is doing the actual loading. If the program does not need the kernel, it may of course utilize these banks once it is running. <code>pexec</code> is otherwise able to load code and data into anywhere in physical memory.

When the program starts, the state of the MMU LUTs is very similar to when a KUP starts. LUT #3 is active and slots 0-4 are mapped to RAM banks 0-4. The program's entry point must be in this region. Slots 6 and 7 are mapped to the kernel, which is intact and usable right away. Slot 5 is currently undefined.

Testing a PGZ can be done by using FoenixMgr and the <code>xdev</code> firmware component. It can of course also be copied to a disk or SD card, and manually run it on the machine.

A PGZ cannot "return" to another program, it can either start a KUP (if the kernel is intact) or reset the machine.

The first byte of the file is a file signature and also a version tag. If the first byte is an upper case Z, the file is a 24-bit PGZ file (i.e. all addresses and sizes specified in the file are 24-bits). If the file is a lower case Z, the file is a 32-bit PGZ file (all address and sizes are 32-bits in
length). Note that all addresses and sizes are in little endian format (that is, least significant
byte first).

After the initial byte, the remainder of the PGZ file consists of segments, one after the other. Each segment consists of two or three fields:

{| class="wikitable"
!Field!!Size!!Description
|-
|address||3 ('''Z''') or 4 ('''z''') bytes||The target address for this segment
|-
|size||3 ('''Z''') or 4 ('''z''') bytes||The number of bytes in the data field
|-
|data||'''size''' bytes||The data to be loaded (optional)
|}

For a particular segment, if the size field is 0, there will be no bytes in the data field, and the segment specifies the starting address of the entire program. At least one such segment must be present in the PGZ file for it to be executable. If more than one is present, the last one will
be the one used to specify the starting address.

 ''Original Information Source:'' https://github.com/FoenixRetro/Documentation/blob/main/f256/programming-file-formats.md

File Formats

2023-12-14T19:50:26Z

KoolKiwi: First content page copy & paste & re-format (with Information Source credit).

The F256 line has three file formats, each with slightly different properties and use cases. Additionally, pure binary files are often used by developers. The machine will be in a slightly different state, depending on how the program was started. We will cover this in the following sections.

== Binary ==
The binary file format is not a format as such. It is an image that is loaded directly into the F256's memory by a utility program running on the PC or Mac, and the F256 is then reset. Such an image must include properly initialized interrupt vectors, especially the RESET vector.

Running such an image requires knowledge of its starting address and a properly configured USB connection between the PC or Mac and the F256. Also, a jumper on the F256 Jr. motherboard must be moved to the "Boot-to-RAM" position. This is not necessary on the F256K.

Binary images should only be used by the developer while developing, as it is a very user-unfriendly method of distributing software, requiring tethering to a PC or Mac.

== KUP ==
KUPs are very simple and can contain 40 KiB code/data when run from flash, or 32 KiB when run from disk. Contained in their header is and entry point address, and the slot number of where they should be mapped into, the first possible slot being #1 ($2000).

DOS expands on the KUP header defined by the MicroKernel in a backwards compatible way.

The header is very simple:

<pre>
Byte 0 signature: $F2
Byte 1 signature: $56
Byte 2 the size of program in 8k blocks
Byte 3 the starting slot of the program (ie where to map it)
Bytes 4-5 the start address of the program
Byte 6 header structure version (indicates version of header, current 0 or 1)
Bytes 7-9 reserved
Bytes ?-? zero-terminated name of the program.
Bytes ?-? zero-terminated string describing the arguments. (in version >= 1)
Bytes ?-? zero-terminated string describing the program's function. (in version >= 1)
</pre>

The MicroKernel ignores the "argument" and "function" header entries. These are printed by DOS' <code>lsf</code> command, and only if the header version is greater or equal to 1.

When instructed to start a named KUP, the kernel will search through memory to find a match. First the expansion memory is searched, this could be either RAM or ROM. Then the on-board flash memory is searched. If DIP switch #1 is in the "on" position, the kernel will search memory banks 1-5 before the expansion blocks.

This sequence is also performed when the kernel starts up, for instance when the machine is reset or is first powered on.

Testing a KUP is therefore as easy as uploading it to a block of memory, and is an excellent choice for testing a program that interacts with the kernel. Though you should remember that this program will stay in memory as long as the machine is powered on, and may also survive a short power cut. Such a program should therefore, when testing, destroy its own header by overwriting the first two bytes with some values that are not the magic signature, to avoid being started again and again.

A KUP residing in flash does not "return" in the common sense of the word. If it has to terminate, it can either reset the machine, or use `RunNamed` to start another KUP.

On the other hand, when running a KUP from disk, it is able to return to DOS in a controlled manner. Distributing software intended to be run from disk as KUP is usually discouraged, as the program can only be started from DOS and not from SuperBASIC. It can, however, be appropriate for small utility programs mostly intended for maintenance tasks and so forth. When distributing software, you should prefer using one of the PGX or PGZ formats.

A KUP loaded from disk may exit back to DOS by issuing an RTS instruction. Additionally, the carry may be set if the machine should be reset, or carry clear to continue running DOS. Be aware that you must leave the MMU configuration in the state you found it for this to work properly. You should also keep away from the $0200-$07FF range completely.

When a KUP is started from flash, LUT #3 slots 0-5 is mapped to RAM banks 0-5, *except* where the KUP's header specifies where into should be mapped.

A KUP started from disk has LUT #3 slots 0-4 mapped to RAM, some of which will be the program itself.

In both cases the kernel is intact and available for use straight away.

== PGX ==
This format is a simple, single segment executable, which can be loaded as low as $0200. A PGX is loaded using <code>pexec</code>. <code>pexec</code> treats PGX and PGZ in exactly the same way, and information on how PGZ is handled also applies to PGX.

PGZ is similar in scale to MS-DOS’s COM format, or the Commodore PRG format. It consists of a single segment of data to be loaded to
a specific address, where that address is also the starting address.

PGX starts with a header to identify the file and the starting address:

* The first three bytes are the ASCII codes for “PGX”.
* The fourth byte is the CPU and version identification byte. Bits 0 through 3 represent the CPU code, and bits 4 through 7 represent the version of PGX supported. At the moment, there is just version 0. The CPU code can be 1 for the WDC65816, or 2 for the M680x0.
* The next four bytes (that is, bytes 4 through 7) are the address of the destination, in big-endian format (most significant byte first). This address is both the address of the location in which to load the first byte of the data and is also the starting address for the file.

All bytes after the header are the contents of the file to be loaded into memory.

== PGZ ==
This is a more advanced multi-segment executable. It can be loaded as low as $0200. It is loaded using <code>pexec</code>.

When <code>pexec</code> loads a program, the program must not load itself into RAM banks 6 & 7, as these are used by the kernel, and the kernel is doing the actual loading. If the program does not need the kernel, it may of course utilize these banks once it is running. <code>pexec</code> is otherwise able to load code and data into anywhere in physical memory.

When the program starts, the state of the MMU LUTs is very similar to when a KUP starts. LUT #3 is active and slots 0-4 are mapped to RAM banks 0-4. The program's entry point must be in this region. Slots 6 and 7 are mapped to the kernel, which is intact and usable right away. Slot 5 is currently undefined.

Testing a PGZ can be done by using FoenixMgr and the <code>xdev</code> firmware component. It can of course also be copied to a disk or SD card, and manually run it on the machine.

A PGZ cannot "return" to another program, it can either start a KUP (if the kernel is intact) or reset the machine.

The first byte of the file is a file signature and also a version tag. If the first byte is an upper case Z, the file is a 24-bit PGZ file (i.e. all addresses and sizes specified in the file are 24-bits). If the file is a lower case Z, the file is a 32-bit PGZ file (all address and sizes are 32-bits in
length). Note that all addresses and sizes are in little endian format (that is, least significant
byte first).

After the initial byte, the remainder of the PGZ file consists of segments, one after the other. Each segment consists of two or three fields:

{| class="wikitable"
!Field!!Size!!Description
|-
|address||3 ('''Z''') or 4 ('''z''') bytes||The target address for this segment
|-
|size||3 ('''Z''') or 4 ('''z''') bytes||The number of bytes in the data field
|-
|data||'''size''' bytes||The data to be loaded (optional)
|}

For a particular segment, if the size field is 0, there will be no bytes in the data field, and the segment specifies the starting address of the entire program. At least one such segment must be present in the PGZ file for it to be executable. If more than one is present, the last one will
be the one used to specify the starting address.

 ''Information Source:'' https://github.com/FoenixRetro/Documentation/blob/main/f256/programming-file-formats.md

Main Page

2023-12-13T23:52:05Z

KoolKiwi: Get some blueish style happening, with margins. Style as per osdev.org

<div id="mainpage"></div> __NOTOC__ __NOEDITSECTION__


<div style="margin: 0 0 15px 0; padding: 1px; border: 1px solid #CCCCCC;">
{| style="width: 100%; margin: 0; padding: 0; border: 0; background-color: #FCFCFC; color: #000000; border-collapse: collapse;"
| align="center" style="vertical-align: top;"|
<div style="font-size: 150%;">Welcome to the Foenix Retro Systems' F256x series Wiki</div>
<div style="font-size: 100%; margin-top: 0.7em; line-height: 130%;">Dedicated to the WDC65C02/WDC65C816 or FNX6809 based F256x series.</div>
|}
</div>


{| style="width: 100%; margin: 0; padding: 0; border: 0; border-collapse: collapse;"
| style="padding: 0; width: 25%; vertical-align: top;" |


{{NocatBox|subject=Getting Started|page=Main2/Getting_Started}}
{{NocatBox|subject=Technical Overview|page=Main2/Technical_Overview}}
{{NocatBox|subject=System Maintenance|page=Main2/System_Maintenance}}

| style="padding: 0 0 0 10px; width: 25%; vertical-align: top;" |


{{NocatBox|subject=Software Development|page=Main2/Software_Development}}
{{NocatBox|subject=FNX6809 Processor|page=Main2/FNX6809_Processor}}

|}

Template:Main2/FNX6809 Processor

2023-12-13T23:43:59Z