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

Raspberry Pi Pico Update

2026-02-14T23:14:22Z

Cibee: Corrected filename for gzip compressed fpga cores

== Raspberry Pi Pico Update ==

=== Overview ===

There is an onboard RP2040 chip (pi pico). It is NOT PRESENT on the Jr2. It's only present on the K2. It's responsible for the following things:

* the bootloader procedure that loads the right core while booting the K2.
* it is also known as the "FPGA Manager"
* Has modifiable code that can invite more features and possibly a faster bootup

=== Preparing new pico flash files ===

Check this [https://github.com/wildbitscomputing/fpga-manager fpga manager] repo from Cibee which can tweak and compile such files into .uf2. This project uses VSCode, the pico sdk and openocd in order to do everything.

Here's a summary of the booting time gains that were accomplished by Cibee (see the benchmark table on the side)

bit bang (slowest): was the old method, at launch of the K2, of sending a core file to the FPGA.

pio (faster): is the new method tried by Cibee

SD raw (slowest): was the old way of storing the core file, uncompressed, as .bin files. See [[FPGA_Releases#How_to_Upgrade_the_FPGA_for_the_F256K2]] for the exact file structure needed inside the internal "left" uSD card.

SD gzip (faster): is a new method of individually storing those same core files as .bin.gz, reducing the amount of bytes to send dramatically

FLASH LZ4 (fastest): is embedding the core files inside the pi pico flash memory so that the core manager carries its own data and sends it to the fpga during bootup. This no longer involves the internal "left" uSD card at all.

When a recent enough fpga manager (January 2026) is flashed into the pi pico, it will try to prepare the fpga with this following sequence:

<nowiki>*</nowiki> Reads a 2-bit context DIP switch to select one of four FPGA slots.

<nowiki>*</nowiki> Attempts SD card programming first (LZ4 blocks, gzip, then raw .bin).

<nowiki>*</nowiki> Falls back to LZ4 images stored in fixed flash slots if SD is unavailable.

<nowiki>*</nowiki> Prints the chosen method and timing over USB stdio if enabled.
[[File:FPGA Manager Benchmark.png|thumb]]

=== Opening the case ===

You can refer to this section to learn how you can be [[Opening_the_F256K_case]]

=== Flashing using the onboard USB Header ===

Here are the steps to follow:
[[File:Rp2040-cable.jpeg|thumb|Connector location for the pico USB pin header, Switch S3 on the left, and cable orientation]]
Installation step:

* Install Cable as above (F256K2 Powered Off). '''WARNING''', with '''VERY LITTLE''' cable tension, this pin header can snap off [from Mu0n] and force you onto the next method of flashing using the SWD header, as seen in the next section.
* Plug Cable in any PC that holds the new programming file.
* Keep 1 finger on the button
* Power the F256K2
* A new folder will appear on the PC's Desktop
* Drop the new .uf2 file in the newly appeared folder.
* Power off F256K2
* Remove cable
* Reinstall the system as your heart's desire
* Power On the unit
* RP2040 is updated and running (because you need it to boot the unit)
* Bob's your uncle!

=== Flashing using the onboard SWD Header ===

SWD: Serial Wire Debug. This other pin header is a second way to update your flash and gives a little more flexibility to do it piece by piece by flashing .bin at specific flash locations or .elf in one go.
[[File:Swd connector.png|thumb|Connector location for the SWD pin header, near the FPGA]]

You'll need either:

* a [https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html Pi Debug Probe] which comes with the necessary cable that leads to 3 female Dupont endings needed here
* openocd tool from PicoSDK v1.5.1 or more recent
* a prepared .bin file with updated code.
* a conversion tool to convert .uf2 to .bin, you can use this website https://polpo.org/tmp/uf2-to-bin.html or other known tools in the pico community
* the key step is to use openocd like so: openocd -s scripts -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000; program NewFirmware.bin verify reset exit 0x10000000"

Glossary

2026-01-27T12:34:25Z

Cibee: A comprehensive glossary of terms, acronyms, and concepts from the F256 ecosystem.

= Wildbits / Foenix F256 Glossary =

{{Short description|Reference guide to F256 hardware, software, and technical terminology}}

A comprehensive glossary of terms, acronyms, and concepts from the F256 ecosystem.

__TOC__

== Computer Models ==

; F256Jr
: First-generation "Junior" model featuring WDC 65C02 CPU, 512KB SRAM, Cyclone IV FPGA, and [[TinyVicky]] graphics.

; F256Jr2 (Jr.Jr.)
: Second-generation Junior model with WDC 65C816 CPU, 2MB SRAM, Artix 7 FPGA, and TinyVicky II graphics. See [[Product_Specifications]].

; F256K
: First-generation keyboard-integrated model with same specs as F256Jr plus built-in mechanical keyboard.

; F256K2
: Second-generation keyboard model with 65816, 2MB SRAM, 128MB DDR3 DRAM, Artix 7 XC7A200T FPGA, and Vicky "The Fourth" graphics.

; Foenix
: Brand name for the retro computer line created by Stefany Allaire.

; Wildbits
: Alternative/associated brand name for the F256 computer line.

== Processors ==

; 6502
: Classic 8-bit CPU from MOS Technology (1975), the foundation architecture for the F256 series.

; WDC 65C02
: Western Design Center's CMOS version of the 6502 with lower power consumption and additional instructions. Default CPU in first-gen F256 models.

; WDC 65C816 (65816)
: 16-bit upgrade to the 65C02 with 24-bit addressing (up to 16MB) and selectable 8/16-bit registers. See [[65816_Overview]].

; FNX6809
: FPGA-based implementation of the Motorola 6809 CPU that can run on F256 hardware. See [[FNX6809_Overview]].

; Emulation Mode
: Default 65816 startup mode that behaves like a 65C02 for backwards compatibility.

; Native Mode
: 65816 mode enabling 16-bit registers, movable direct page, and full 24-bit addressing.

; Rockwell Instructions
: Extended 6502 instructions (BBS, BBR, RMB, SMB) supported by 65C02 but '''NOT''' by 65816. Avoid these for 65816 compatibility.

== FPGA & Hardware ==

; FPGA
: Field-Programmable Gate Array; reconfigurable chip implementing the F256's custom logic, graphics, and sound.

; Cyclone IV (EP4CE15)
: Intel/Altera FPGA used in first-gen F256 models (15,408 logic elements, 504kb BRAM).

; Artix 7 (XC7A35T)
: Xilinx FPGA used in F256Jr2 (33,280 logic cells, 1,800kb BRAM).

; Artix 7 (XC7A200T)
: Larger Xilinx FPGA used in F256K2 (215,360 logic cells, 13,140kb BRAM).

; Core
: FPGA configuration/bitstream that defines the computer's behavior. See [[FPGA_Releases]].

; Core2x
: Enhanced FPGA core with 2× CPU speed (12MHz), 24-bit flat addressing, 64 additional sprites, and hardware line drawing.

; JTAG
: Joint Test Action Group; interface for programming the FPGA on first-gen models.

; USB Blaster
: Hardware programmer used to flash FPGA via JTAG on F256Jr and F256K.

; RP2040
: Raspberry Pi microcontroller that initializes the FPGA and uploads cores on second-gen models.

; Context (CNTX)
: On F256K2, one of four FPGA core slots (CNTX1-CNTX4) selectable via [[DIP_switches]].

; Sii9022
: HDMI encoder chip used on black K2 boards; removed in purple K2 boards where HDMI encoding moved to FPGA.

== Graphics ==

; TinyVicky
: Graphics subsystem in first-gen F256 models (F256Jr, F256K).

; TinyVicky II
: Enhanced graphics subsystem in F256Jr2.

; Vicky "The Fourth"
: Advanced graphics subsystem in F256K2.

; VICKY
: General name for the Foenix graphics/video controller family.

; Bitmap
: Graphics layer displaying pixel-mapped images directly from SRAM. Up to 3 bitmap layers available.

; Tilemap
: Graphics layer displaying tiles from tilesets for efficient scrolling graphics. Up to 3 tilemap layers available.

; Tileset
: Collection of tile graphics (8×8 or 16×16 pixels) referenced by tilemaps. Up to 8 tilesets supported.

; Sprite
: Hardware-accelerated moveable graphic object. Sizes: 8×8, 16×16, 24×24, or 32×32 pixels. 64 sprites standard, 128 with Core2x.

; CLUT
: Color Look-Up Table; palette mapping 8-bit index values to BGR colors. 4 graphics CLUTs available.

; Gamma Correction
: Color brightness adjustment via lookup tables at $C000-$C8FF in IO Page 0.

; DMA
: Direct Memory Access; hardware-accelerated memory copying that runs during VBlank at 100MHz.

; Layer
: Graphics compositing priority. Bitmaps and tilemaps can be assigned to layers 0-2.

== Memory ==

; SRAM
: Static RAM; main system memory. 512KB on gen1 models, 2MB on gen2 models.

; DDR3 DRAM
: 128MB dynamic RAM on F256K2 (support planned but not yet implemented).

; Flash
: 512KB non-volatile memory storing [[Firmware]] and programs. Each K2 core context has its own 512KB flash area.

; MMU
: Memory Management Unit; maps 8KB blocks of physical memory into the CPU's 64KB address space. See [[Memory_Management]].

; MLUT
: Memory Lookup Table; one of four MMU configurations (MLUT 0-3) for quick switching between memory mapping states.

; Slot
: One of eight 8KB regions in the CPU's 64KB address space:
:* Slot 0: $0000-$1FFF
:* Slot 1: $2000-$3FFF
:* Slot 2: $4000-$5FFF
:* Slot 3: $6000-$7FFF
:* Slot 4: $8000-$9FFF
:* Slot 5: $A000-$BFFF
:* Slot 6: $C000-$DFFF (IO Pages overlay this)
:* Slot 7: $E000-$FFFF

; Block
: 8KB chunk of physical memory that can be mapped into a slot via the MMU.

; IO Page
: Memory-mapped I/O region at $C000-$DFFF. Six pages available (0-5). See [[IO_Pages]].

; Expansion Port
: Slot for 256KB RAM or Flash expansion cartridge. Uses PCI-Express x1 socket form factor.

; Flat Memory
: Direct 24-bit addressing without MMU banking. Available in Core2x with SRAM_EN bit enabled.

; Zero Page / Direct Page
: First 256 bytes of memory used for fast addressing. Moveable anywhere in first 64KB in 65816 native mode.

== Audio ==

; SID
: Sound Interface Device; Commodore 64's famous sound chip. FPGA emulated on gen2; real chip sockets available on F256Jr.

; PSG
: Programmable Sound Generator; AY-3-8910-style chip (FPGA emulated). Directly accessible at $D600. See [[Use_the_PSG]].

; OPL3 (YMF262)
: Yamaha FM synthesis chip. Real chip on F256K; FPGA emulated on other models. See [[Use_the_OPL3_YMF262]].

; CODEC
: Audio codec chip for digital audio output. See [[Use_the_CODEC]].

; SAM2695
: Dream MIDI wavetable synthesis chip (gen2 only). See [[Use_the_Sam2695_Dream_MIDI_chip]].

; VS1053b
: VLSI audio decoder/encoder chip supporting MP3, AAC, Ogg Vorbis, and more (gen2 only). See [[Use_the_VS1053b_chip]].

; MIDI
: Musical Instrument Digital Interface; supported via SAM2695 and hardware MIDI in/out ports on gen2 models.

== Input/Output ==

; PS/2
: Keyboard/mouse interface standard. Single port supports both keyboard and mouse. See [[Use_the_PS/2_Mouse]].

; IEC
: Commodore serial bus for connecting disk drives, printers, and other peripherals.

; VIA
: Versatile Interface Adapter (WDC 65C22). VIA0 handles Atari joysticks; VIA1 handles keyboard matrix on F256K series.

; UART
: Universal Asynchronous Receiver-Transmitter; serial communication interface at $D630.

; RTC
: Real-Time Clock; battery-backed timekeeping chip at $D690.

; SD Card
: Storage medium for programs and data. Gen1 has one slot; gen2 has internal and external slots.

; DVI
: Digital Visual Interface; video output on first-gen models (supports both digital and analog signals).

; HDMI
: High-Definition Multimedia Interface; video output using digital TMDS signaling.

; ESP32 Feather
: WiFi module for first-gen models (internal installation).

; Wiznet
: Ethernet/WiFi module for second-gen models with external antenna connector. See [[Wiznet]].

; NES/SNES Controllers
: Supported game controllers via dedicated pin header or Mini-DIN9 connector. See [[Use_the_SNES/NES_controllers]].

== Software & Firmware ==

; MicroKernel
: Primary event-based, near real-time kernel for F256 (developed by Gadget). Supports 65c02 and 65816 in emulation mode. See [[Kernels]].

; OpenFNXKernal
: Community-developed CBM-style kernal alternative with SD Card I/O support. See [[Kernels]].

; SuperBASIC
: BBC BASIC-inspired interpreter; default F256 programming environment. See [[SuperBASIC]].

; DOS
: Minimalistic file management and information shell stored in flash.

; F/Manager (fm)
: Feature-rich file manager, program launcher, and memory exploration software. See [[Firmware]].

; Moreorless (mless)
: Built-in text editor stored in flash. See [[Moreorless]].

; FoenixMgr
: Python scripts for uploading code, flashing firmware, and managing the F256 from a PC or Mac.

; xdev
: Development trampoline firmware component that reacts to FoenixMgr commands (pcopy, runpgz, runpgx).

; CartFlasher (fcart)
: Utility for programming the 256KB Flash Cartridge with 8KB prepared blocks.

; pexec
: Kernel routine for loading and executing PGX/PGZ format programs.

== File Formats ==

; KUP
: Kernel User Program; simple executable format for flash-resident or disk-loaded programs. Header contains signature ($F256), size, slot, and entry point. See [[File_Formats]].

; PGX
: Single-segment executable with 8-byte header. Similar to MS-DOS COM or Commodore PRG format. See [[File_Formats]].

; PGZ
: Multi-segment executable format; can load code/data to multiple memory locations. Supports both 24-bit ('Z') and 32-bit ('z') addressing. See [[File_Formats]].

; Binary
: Raw memory image requiring known load address and boot-to-RAM mode. Development use only.

; .bin
: FPGA core file extension used on F256K2's FPGA load SD card.

; .uf2
: RP2040 firmware file format for second-gen models.

== Technical Terms ==

; IRQ
: Interrupt Request; hardware signal for event-driven programming. See [[IRQ]] and [[IRQ_Programming]].

; NMI
: Non-Maskable Interrupt; cannot be disabled by software.

; SOF
: Start of Frame interrupt; triggered at beginning of VSYNC.

; SOL
: Start of Line interrupt; triggered at configurable scanline.

; VBlank
: Vertical blanking interval; period between video frames when DMA runs.

; PHI2
: CPU clock signal phase 2; active high when CPU is accessing the bus.

; R/W
: Read/Write signal line (Read = high, Write = low).

; BGR / BGRx
: Color format: Blue, Green, Red byte order. BGRx adds unused padding byte for 4-byte alignment.

; Little Endian
: Byte ordering with least significant byte at lowest address. Used throughout the F256.

; BCD
: Binary-Coded Decimal; number encoding where each nibble represents a decimal digit (0-9). Used in RTC.

== DIP Switch Settings ==

DIP switches configure boot behavior and hardware options. See [[DIP_switches]].

; Boot-from-RAM
: When enabled, kernel searches first 48KB of RAM for programs before checking flash.

; Gamma Enable
: Enables color gamma correction.

; Core Select (K2)
: Two switches select which FPGA context (1-4) to load on F256K2.

== Key Register Addresses ==

; $0000 (MMU_MEM_CTRL)
: MMU Memory Control Register; selects active MLUT and enables editing.

; $0001 (MMU_IO_CTRL)
: MMU I/O Control Register; selects IO page and controls memory mapping flags.

; $D000 (MSTR_CTRL)
: VICKY Master Control Register; enables text, graphics, sprites, tiles, bitmaps.

; $D660 (INT_PENDING)
: Interrupt Pending flags (24-bit).

; $D66C (INT_MASK)
: Interrupt Mask register (24-bit).

; $D6A0 (SYS0)
: System Control Register; controls LEDs, reset, and reads SD card status.

== Development Tools ==

; Calypsi
: C compiler supporting 6502, 65816, and 6809 for F256 development.

; 64tass
: Popular cross-assembler for 6502/65816.

; cc65
: C compiler and toolchain for 6502.

; Quartus Prime Lite
: Intel FPGA programming software. Version 18.1 required for Cyclone IV on gen1 models.

; openFPGALoader
: Open-source FPGA programming tool for Linux and macOS.

== See Also ==

* [[Hardware]]
* [[Memory_Management]]
* [[IO_Pages]]
* [[Firmware]]
* [[SuperBASIC]]
* [[FPGA_Releases]]
* [[Getting_Started]]

[[Category:Reference]]
[[Category:Documentation]]

DIP switches

2025-09-14T08:15:39Z

Cibee: Updated FPGA load table

== F256K DIP switches ==

The following might be slightly outdated. [[File:F256k DIP switches.png|thumb]]'''Source''': https://github.com/ghackwrench/F256_MicroKernel/tree/master/docs#dip-switches

# Enable boot-from-RAM '''AND''' don't prioritize the cart to autoboot a kernel compatible KUP header program
# Reserved (potentially for SNES gamepad support)
# Enable SLIP based networking
# Feather board installed (eg Huzzah 8266 WiFi)
# SIDs are installed
# F256: CBM keyboard installed; F256k: reduced TCP window size.
# ON: 640x480, OFF: 640x400 (''not yet implemented'')
# Enable gamma color correction

When boot-from-RAM is enabled, the kernel will search the first 48k of RAM for pre-loaded programs before starting the first program on the expansion cartridge or the first program in flash.

== F256K2 Core Select DIP switch ==

[[File:F256k2ds.png|thumb]]

{| class="wikitable"
|+
|-
! Switch !! Binary Value !! Context
|-
| 1- ON/ 2- ON || 0 0 || Load 0 - F256K2c
|-
| 1- OFF/ 2- ON || 1 0 || Load 1 - F256K2e
|-
| 1- ON/ 2- OFF || 0 1 || Load 2 - F256K2 FNX6809
|-
| 1- OFF/ 2- OFF|| 1 1 || Load 3 - F256K2x
|}

SuperBASIC

2025-09-13T11:44:53Z

Cibee: Minor formatting changes

SuperBASIC is inspired by BBC BASIC but offers quite a bit more.
* [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual].
* [[SuperBASIC Memory Map]]
* SuperBASIC Mix Bag of [[Code Snippets]]
* Watch EMWhite's excellent intro series on YouTube: [https://www.youtube.com/playlist?list=PLeHjTvk7NPiSqGz4REMH-S4hjYpLS2YNR Full Playlist].
* Read EMWhite's [https://apps.emwhite.org/shared-files/885/?Foenix-Rising-Issue-18-November-2024.pdf&download=1 Foenix Rising Issue 18] (November 2024) which goes into detail about a few of the gotchas of superbasic.

=== An informal list of tips, "gotchas": ===

===== IF, THEN, ELSE =====

====== Source of this tip: Ernesto ======
* A regular <code>if then</code> condition can't contain an <code>else</code> statement, as in this example:
10 if a=0 then x=10
* If you need to do an <code>if then else</code> structure, you actually have to do an <code>if else endif</code> structure like in the following example, skipping the <code>then</code> statement.
10 if a=0
20 x=1
30 else
40 x=2
50 endif
* If you do it in one line it needs to have some colons added, making it look weird like this:
10 if a=0:x=1:else:x=2:endif
* if you dare to omit the <code>endif</code> thinking that the <code>if</code> statement won't need it, (mmm.., everything is in one line, so no need, right?) -Nope...all hell breaks loose!-
10 if a=0:x=1:else:x=2: REM "<-- Error, omited the endif"
* be careful not to add an extra <code>then</code> statement by mistake to an <code>if else endif</code> structure, if you do -All hell breaks loose again!!-
10 if a=0 then : rem "<-- Error, THEN is not needed!!!" 20 x=1 30 else 40 x=2 50 endif
''Debugging hint: If you encounter an error like "open structure" or "endproc without a proc": do not trust the line number that you are given. The root of the problem is probably in a structure earlier on in the code.''

===== Evaluating multiple conditions in IF statements =====
SUPERBASIC doesn't have the dedicated keywords AND , OR so you have to use the bitwise operators to evaluate multiple conditions, please consider the following examples:

* AND <code>if (a=1)&(b=2) then c=1</code>
* OR <code>if (a=1)^(b=2) then c=1</code>

This should work as long as you use parenthesis in all evaluated expressions (Since parenthesis makes bitwise operators behave like logical operators).

===== Using procedures =====

* The <code>proc</code> keyword is only valid if it appears after an <code>end</code> statement.
* When calling a procedure use the procedure name followed by parenthesis (), even if the procedure has no parameters.
* Avoid any space between the procedure name and the parenthesis, else it will produce an error.

===== Keyboard shortcuts =====
{| class="wikitable"
|+
!Key combination
!Effect
|-
|<code>ctrl-c</code> or <code>RUN STOP</code> on the F256K
|Stops a listing or a running program
|-
|<code>ctrl-l</code>
|Clears the screen
|-
|<code>ctrl-a</code> or <code>CLR/HOME</code> on the F256K
|Move cursor to the first character in the current line
|-
|<code>ctrl-e</code>
|Move cursor to the last character in the current line
|-
|<code>ctrl-i</code>
|Move cursor 8 characters to the right
|-
|<code>ctrl-k</code>
|Deletes characters from cursor position to line end
|}

===== Behaviour of load and bload =====

* The <code>bload</code> statement does not print <code>Completed</code> when loading is successfull whereas <code>load</code> does.
* bload can load anywhere on memory not just under the first 64k
* An exception is that bload can't load I/O parameters that reside in $C000 - $DFFF

===== Control characters for cursor and colour control =====
In BASIC the following character codes can be used with <code>print</code> to control the cursor position and colours on the screen.
{| class="wikitable"
!Code
!Effect
|-
|chr$(1)
|Set cursor to leftmost position in current line
|-
|chr$(2)
|Cursor left
|-
|chr$(5)
|Set cursor to righmost position in current line
|-
|chr$(6)
|Cursor right
|-
|chr$(11)
|Deletes characters from cursor position to line end
|-
|chr$(12)
|Clear screen and set cursor to upper left corner
|-
|chr$(13)
|Move cursor to start of next line
|-
|chr$(14)
|Cursor down
|-
|chr$(16)
|Cursor up
|-
|chr$(128) - chr$(143)
|Set foreground color. Code 128 is black 143 is white. The rest follows the sequence given below
|-
|chr$(144) - chr$(159)
|Set background color. Code 144 is black 159 is white. The rest follows the sequence given below
|}
{| class="wikitable"
!Colour code
!Colour
!Colour code
!Colour
|-
|0
|Black
|8
|Dark grey
|-
|1
|Grey
|9
|Light grey (default foreground)
|-
|2
|Dark blue (default background colour)
|10
|Blue
|-
|3
|Green
|11
|Light green
|-
|4
|Purple
|12
|Light purple
|-
|5
|Brown
|13
|Red
|-
|6
|Orange
|14
|Yellow
|-
|7
|Light blue
|15
|White
|}The background colors do not work when the bitmap layer has been turned on. They will also not work if you have returned from the bitmap layer with a <code>bitmap off</code> command. In order to restore the background control character function you will need to make sure the MMU is set to zero by using <code>POKE 1,0</code> and then setting the text mode again by using <code>POKE $d000,1</code>.

==== Character Set / Text matrix ====
* Access to the full character set can be obtained by using the <code>CPRINT</code> command instead of the normal <code>PRINT</code> command.
* Characters can also be set on the screen text matrix using the <code>POKE</code> command starting at <code>$C000</code> providing the MMU I/O control is set to 2 by executing a <code>POKE 1,2</code> command first (remember to restore the MMU I/O once you're done).
[[File:Full char set.png|thumb|104x104px|F256 Character Set|none]]
* Color can also be set on the screen color matrix using the <code>POKE</code> command starting at <code>$C000</code> providing the MMU I/O control is set to 3 by executing a <code>POKE 1,3</code> command first (remember to restore the MMU I/O once you're done).
* When poking colors on the screen, the high nibble is the character color and the low nibble is the background color.

[[File:Colormatrix.png|alt=Default Colors|thumb|100x100px|Default Colors|none]]

===== Memcopy lockup =====

* In certain situations the <code><big>memcopy</big></code> command can lockup.
* A machine language utility that performs the same function as <code>memcopy</code> is available if <code>memcopy</code> fails.
* mlcopy is a short routine that replaces <code>memcopy</code> and is more reliable. It can be loaded into memory with a BLOAD command in your program, or with a basic loader that can be added to your program.
* In place of the <code>memcopy</code> command you would use 3 <code><big>POKEL</big></code> commands and a <code><big>CALL</big></code> command to engage the DMA engine.

POKEL $0903,data source
POKEL $0906,destination
POKEL $0909,number of bytes to copy
CALL $0900

* [https://github.com/mcassera/F256-mlcopy mlcopy github page]

===== Sprite Images =====

In BASIC you can access different SPRITE shapes through the IMAGE command as part of the sprite command: <code>SPRITE 0 IMAGE 1 TO 100,100</code>. Be aware that BASIC can only keep track of 64 Images, if you want to access and show more than 64 different shapes you need to poke the 3 bytes of the address where the image data resides into the correct sprite registers yourself.

===== Sprite Coordinates =====
In BASIC all sprites are centered on the coordinate specified, this might produce some counterintuitive effects when using different size sprites, for example if you want to align the sprite edge with the top left side of the screen you would need different values depending on the sprite size
SPRITE 0 IMAGE 1 TO 4,4: REM "8x8 Sprite"
SPRITE 1 IMAGE 1 TO 8,8: REM "16x16 Sprite"
SPRITE 2 IMAGE 2 TO 12,12: REM "24x24 Sprite"
SPRITE 3 IMAGE 3 TO 16,16: REM "32x32 Sprite"
Also, please note that you need to use the command <code>SPRITE X IMAGE Y</code> before setting the sprite coordinates or else BASIC will not know what size is the sprite, and will misalign it, for example the following code although it seems correct will misalign the sprite:
SPRITE 1 TO 8,8
SPRITE 1 IMAGE 1: REM "USe a 16x16 Sprite"

SuperBASIC

2025-09-13T11:42:58Z

Cibee: Reformatted code sections

SuperBASIC is inspired by BBC BASIC but offers quite a bit more.
* [https://github.com/FoenixRetro/f256-superbasic/blob/main/reference/source/f256jr_basic_ref.pdf SuperBASIC Reference Manual].
* [[SuperBASIC Memory Map]]
* SuperBASIC Mix Bag of [[Code Snippets]]
* Watch EMWhite's excellent intro series on YouTube: [https://www.youtube.com/playlist?list=PLeHjTvk7NPiSqGz4REMH-S4hjYpLS2YNR Full Playlist].
* Read EMWhite's [https://apps.emwhite.org/shared-files/885/?Foenix-Rising-Issue-18-November-2024.pdf&download=1 Foenix Rising Issue 18] (November 2024) which goes into detail about a few of the gotchas of superbasic.

=== An informal list of tips, "gotchas": ===

===== IF, THEN, ELSE =====

====== Source of this tip: Ernesto ======
* A regular <code>if then</code> condition can't contain an <code>else</code> statement, as in this example:
10 if a=0 then x=10
* If you need to do an <code>if then else</code> structure, you actually have to do an <code>if else endif</code> structure like in the following example, skipping the <code>then</code> statement.
10 if a=0
20 x=1
30 else
40 x=2
50 endif
* If you do it in one line it needs to have some colons added, making it look weird like this:
10 if a=0:x=1:else:x=2:endif
* if you dare to omit the <code>endif</code> thinking that the <code>if</code> statement won't need it, (mmm.., everything is in one line, so no need, right?) -Nope...all hell breaks loose!-
10 if a=0:x=1:else:x=2: REM "<-- Error, omited the endif"
* be careful not to add an extra <code>then</code> statement by mistake to an <code>if else endif</code> structure, if you do -All hell breaks loose again!!-
10 if a=0 then : rem "<-- Error, THEN is not needed!!!" 20 x=1 30 else 40 x=2 50 endif
''Debugging hint: If you encounter an error like "open structure" or "endproc without a proc": do not trust the line number that you are given. The root of the problem is probably in a structure earlier on in the code.''

===== Evaluating multiple conditions in IF statements =====
SUPERBASIC doesn't have the dedicated keywords AND , OR so you have to use the bitwise operators to evaluate multiple conditions, please consider the following examples:

* AND <code>if (a=1)&(b=2) then c=1</code>
* OR <code>if (a=1)^(b=2) then c=1</code>

This should work as long as you use parenthesis in all evaluated expressions (Since parenthesis makes bitwise operators behave like logical operators).

===== Using procedures =====

* The <code>proc</code> keyword is only valid if it appears after an <code>end</code> statement.
* When calling a procedure use the procedure name followed by parenthesis (), even if the procedure has no parameters.
* Avoid any space between the procedure name and the parenthesis, else it will produce an error.

===== Keyboard shortcuts =====
{| class="wikitable"
|+
!Key combination
!Effect
|-
|<code>ctrl-c</code> or <code>RUN STOP</code> on the F256K
|Stops a listing or a running program
|-
|<code>ctrl-l</code>
|Clears the screen
|-
|<code>ctrl-a</code> or <code>CLR/HOME</code> on the F256K
|Move cursor to the first character in the current line
|-
|<code>ctrl-e</code>
|Move cursor to the last character in the current line
|-
|<code>ctrl-i</code>
|Move cursor 8 characters to the right
|-
|<code>ctrl-k</code>
|Deletes characters from cursor position to line end
|}

===== Behaviour of load and bload =====

* The <code>bload</code> statement does not print <code>Completed</code> when loading is successfull whereas <code>load</code> does.
* bload can load anywhere on memory not just under the first 64k
* An exception is that bload can't load I/O parameters that reside in $C000 - $DFFF

===== Control characters for cursor and colour control =====
In BASIC the following character codes can be used with <code>print</code> to control the cursor position and colours on the screen.
{| class="wikitable"
!Code
!Effect
|-
|chr$(1)
|Set cursor to leftmost position in current line
|-
|chr$(2)
|Cursor left
|-
|chr$(5)
|Set cursor to righmost position in current line
|-
|chr$(6)
|Cursor right
|-
|chr$(11)
|Deletes characters from cursor position to line end
|-
|chr$(12)
|Clear screen and set cursor to upper left corner
|-
|chr$(13)
|Move cursor to start of next line
|-
|chr$(14)
|Cursor down
|-
|chr$(16)
|Cursor up
|-
|chr$(128) - chr$(143)
|Set foreground color. Code 128 is black 143 is white. The rest follows the sequence given below
|-
|chr$(144) - chr$(159)
|Set background color. Code 144 is black 159 is white. The rest follows the sequence given below
|}
{| class="wikitable"
!Colour code
!Colour
!Colour code
!Colour
|-
|0
|Black
|8
|Dark grey
|-
|1
|Grey
|9
|Light grey (default foreground)
|-
|2
|Dark blue (default background colour)
|10
|Blue
|-
|3
|Green
|11
|Light green
|-
|4
|Purple
|12
|Light purple
|-
|5
|Brown
|13
|Red
|-
|6
|Orange
|14
|Yellow
|-
|7
|Light blue
|15
|White
|}The background colors do not work when the bitmap layer has been turned on. They will also not work if you have returned from the bitmap layer with a <code>bitmap off</code> command. In order to restore the background control character function you will need to make sure the MMU is set to zero by using <code>POKE 1,0</code> and then setting the text mode again by using <code>POKE $d000,1</code>.

==== Character Set / Text matrix ====
* Access to the full character set can be obtained by using the <code>CPRINT</code> command instead of the normal <code>PRINT</code> command.
* Characters can also be set on the screen text matrix using the <code>POKE</code> command starting at <code>$C000</code> providing the MMU I/O control is set to 2 by executing a <code>POKE 1,2</code> command first (remember to restore the MMU I/O once you're done).
[[File:Full char set.png|thumb|104x104px|F256 Character Set|none]]
* Color can also be set on the screen color matrix using the <code>POKE</code> command starting at <code>$C000</code> providing the MMU I/O control is set to 3 by executing a <code>POKE 1,3</code> command first (remember to restore the MMU I/O once you're done).
* When poking colors on the screen, the high nibble is the character color and the low nibble is the background color.

[[File:Colormatrix.png|alt=Default Colors|thumb|100x100px|Default Colors|none]]

===== Memcopy lockup =====

* In certain situations the <code><big>memcopy</big></code> command can lockup.
* A machine language utility that performs the same function as <code>memcopy</code> is available if <code>memcopy</code> fails.
* mlcopy is a short routine that replaces <code>memcopy</code> and is more reliable. It can be loaded into memory with a BLOAD command in your program, or with a basic loader that can be added to your program.
* In place of the <code>memcopy</code> command you would use 3 <code><big>POKEL</big></code> commands and a <code><big>CALL</big></code> command to engage the DMA engine.

<code>POKEL $0903,data source</code>
<code>POKEL $0906,destination</code>
<code>POKEL $0909,number of bytes to copy</code>
<code>CALL $0900</code>

* [https://github.com/mcassera/F256-mlcopy mlcopy github page]

===== Sprite Images =====

In BASIC you can access different SPRITE shapes through the IMAGE command as part of the sprite command: <code>SPRITE 0 IMAGE 1 TO 100,100</code>. Be aware that BASIC can only keep track of 64 Images, if you want to access and show more than 64 different shapes you need to poke the 3 bytes of the address where the image data resides into the correct sprite registers yourself.

===== Sprite Coordinates =====
In BASIC all sprites are centered on the coordinate specified, this might produce some counterintuitive effects when using different size sprites, for example if you want to align the sprite edge with the top left side of the screen you would need different values depending on the sprite size
SPRITE 0 IMAGE 1 TO 4,4: REM "8x8 Sprite"
SPRITE 1 IMAGE 1 TO 8,8: REM "16x16 Sprite"
SPRITE 2 IMAGE 2 TO 12,12: REM "24x24 Sprite"
SPRITE 3 IMAGE 3 TO 16,16: REM "32x32 Sprite"
Also, please note that you need to use the command <code>SPRITE X IMAGE Y</code> before setting the sprite coordinates or else BASIC will not know what size is the sprite, and will misalign it, for example the following code although it seems correct will misalign the sprite:
SPRITE 1 TO 8,8 
SPRITE 1 IMAGE 1: REM "USe a 16x16 Sprite"