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

Getting Started

2024-01-14T21:23:46Z

31.192.89.70: Highlighting free to use space in ZP in Italic.

== 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 software 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

* Cards should support the V2 protocol (HC or XC); older cards that only support the V1 protocol (typically 2GB or less) won't work. By contrast, the kernels for the C256 machines generally only work with V1 cards. Note that, in both cases, this is a software limitation -- all of the Foenix machines are electrically capable of using both kinds of cards.
* Cards *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.

=== wget ===
If you have the [[wifi]] configured, you can use [https://github.com/ghackwrench/F256_wget wget] to pull programs and data right off the web!

== 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]
|}

=== Memory Map under BASIC ===
{| class="wikitable sortable"
|+ Caption text
|-
! Initial Address !! End Address !! Description !! Bytes
|-
| $0000|| -|| MMU Control Register || 1
|-
| $0001|| -|| I/O Control Register || 1
|-
| $0002|| $0007|| ''Free Zero Page Addresses'' || 6
|-
| $0008|| $000F|| MMU Control Addresses || 8
|-
| $0010|| $002F|| ''Free Zero Page Addresses'' || 32
|-
| $0030|| $003F|| Used Zero Page Addresses for (xx),Y Addressing || 16
|-
| $0040|| $0041 || Current Address on screen of start of line || 2
|-
| $0042|| $004F|| ''Avaliable Zero Page Addresses'' || 14
|-
| $0050|| $00AF|| Number / Floating Point Stack for 16 numbers || 96
|-
| $00B0||$00EF|| ''Available Zero Page'' || 64
|-
| $00F0|| $00FF|| Kernel Arguments in Zero Page || 16
|-
| $0100|| $01FF|| Hardware Stack of 6502 || 256
|-
| $0200|| $0228|| Basic mini-Kernel memory || 40
|-
| $0229|| $03FF|| Available Low Memory | Also used by Sound Command in BASIC || 470
|-
| $0400|| $041F|| Control Storage first 8 bytes control syntax highlighting || 32
|-
| $0420|| $0814|| Memory Storage || 1012
|-
| $0814|| $0FFF|| Available Low Memory || 2028
|-
| $1000|| $1FFF|| SuperBASIC Identifier Tables, allocated memory, string vars, stack || 4kb
|-
| $2000|| $77FF|| SuperBASIC Program Tokenized Code (grows Upward) || 22kb
|-
| $7800|| $7FFF|| Top 2k of SuperBASIC Program tokenize code or used for ML routines in low memory || 2kb
|-
| $8000|| $BFFF|| SUPERBASIC CODE || 16kb
|-
| $C000|| $DFFF|| I/O Memory Pages / Underlying Kernel Code (Selectable with I/O control Register)|| 8kb
|-
| $E000|| $FFEF|| KERNEL CODE || 8176
|-
| $FFF0|| $FFFF|| Reset Vectors and NMI / IRQ / BRK Vectors || 16
|-
| $01:0000|| $02:2BFF|| Default Memory used by BASIC bitmap graphics || 75kb
|-
| $02:2C00|| $02:7FFF|| Available High Memory || 21kb
|-
| $02:8000|| $02:F000|| Available High Memory | Used for BASIC Cross Development w/PC or MAC|| 32k
|-
| $03:0000|| $03:7FFF|| Used for Sprite Data in BASIC || 32kb
|-
| $03:8000|| $03:FFFF|| Available High Memory | Unless not running from Flash, Used for ROM Images|| 32k
|-
| $04:0000|| $07:DFFF|| Available High Memory || 248kb
|-
| $07:E000|| $07:FFFF|| Available High Memory | Being considered to be Reserved for Environmental Variables || 8Kb
|-
| $10:0000|| $13:FFFF|| Cartridge Expansion Memory (addresable only by CPU) || 256kb
|-
| $14:0000|| $1F:FFFF|| Future Expansions? || 768kb
|}

== 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.

Memory Management

2023-12-26T20:12:07Z

31.192.89.70: Fixed information about address $0000 aka MMU_MEM_CTRL.

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

=== Physical Memory Layout ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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