Foenix index server_protocol
*** Unofficial Foenix Manual (68k focus) ***
// Introduction
What is Foenix?
This is a project to build a new computer system, based around vintage
processor architectures.
It is coordinated at https://c256foenix.com/ (not by me).
The platform grew up on a WDC 65816 cpu.
In mid 2021, the project shifted focus to the 68000 and its successors.
There may be some other chips supported as well via drop-in cards.
What is this resource?
The centre of the Foenix community is a chat area on Discord. This
contains a growing body of knowledge, but it is not organised.
This page aims to act as a curated perspective of knowledge that passes
through there.
In particular, this resource seeks to be useful to new community members
who are coming up to speed.
Change requests,
If you would like to see discuss changes to this page, send me a private
message on the Discord channel (user cratuki).
Audience,
There is almost no downloadable software available for the platform, and
all the activity in the community is oriented around software development.
Most of that is focused on building operating system layers for this
platform.
As of January 2022, if you are thinking about getting into this community,
you should know the basics of computer architecture and have an ambition
to write assembly or C in order to develop your own software for this
system.
Getting started on development,
As of writing, the lowest friction path into development is using vasm on
a workstation to build assembly, then uploading that to your device with
c256mgr. See section [Getting started with Vasm, program in assembly]
below.
System architecture
This is an English translation of a resource created by vinz67 that gives
an overview of the platform.
https://vinz51-fr.translate.goog/a2560u/?_x_tr_sl=fr&_x_tr_tl=en&_x_tr_hl=fr
// Model history
https://wiki.c256foenix.com/index.php?title=Models
This needs a tidy-up from someone who knows the history better.
C256 Foenix Early Adopters' Edition
WDC65816 chip. This original unit only shipped in a small number, and did
not have much in the way of custom chips. But there seems to have been an
upgrade card offered for it (Sera board) that would upgrade these initial
units to a FMX.
C256 Foenix FMX
WDC65816 chip. This had a wide selection of audio chips and midi, and sets
the standard for the selection of audio chips on the platform.
There have been several revisions of this, with different case colourings.
From what I can tell,
There seem to have been several generations of this in white, black and
red (short-run). It is possible that most of the difference between the
revisions happened in FPGA, and that the early units can be upgraded to be
equivalent of mid-2021 store versions of the FMX.
C256 Foenix U
WDC65816. This is a light version of the FMX, and has fewer audio chips
than the FMX. But, it has a more flexible FPGA situation than the FMX.
This is still being offered on the store as of early 2022. Can be
purchased without a case.
A2560U
68000. This is the first of the 68k systems. It should be seen as a
development board, produced as a warm-up for the 68k Foenix platform. It
has limited audio chips. Can be purchased without a case.
A2560K (may be referred to as "The K")
68040. This is a 68-based system in an Amiga 600 form factor: a high
quality mechanical keyboard is built into the unit. It has a floppy disk
drive on the side.
Gen X (model C2560X)
This is to be a hybrid system that consists of both a WDC65816 and a
pluggable 32-bit chip on the same motherboard. The two chips will not be
usable at the same time.
It comes in a purple cube case that has a mini-ITX motherboard.
The pluggable CPU can be one of a variety of 68x or x86 chips. Initial
focus is on 68k chips such as 68000, 68020, 68030, 68040.
A2560X
This is a reduced verison of the C2560X that has the pluggable chips, but
which does not have the WDC65816 infrastructure.
It comes in a teal cube case that has a mini-ITX motherboard
C256 Junior
This is a 6502-based platform that Stefanie is working on as of June 2022.
It may have a similar architecture to the Commander 16.
A2560M
This does not exist, but has been speculated about as a Foenix with a form
factor similar to the original Macintosh.
// Equipment
Organise to have the following,
A 68k-based Foenix board purchased from https://c256foenix.com
A Windows 10 or Linux workstation as a base for development
A 12V power adapter with a 2.5mm power jack
# I have had success with a 'BLUCO AC DC Adapter' from Amazon.
A keyboard with a PS2 adapter
# Some older keyboards have this rather than USB. Or, you can get a
# USB-to-PS2 adapter and use a USB keyboard.
A Terasic USB Blaster
# This allows you to modify the FPGA, useful when Stefanie releases
# architecture updates. Can source from Digikey.
A "Mini-USB" to USB-A cable
# This is used for data transfer between your development workstation
# and the Foenix device. Careful! This is not the same as the
# "Micro-USB" cable you will have lying around for your kindle or as
# part of old phone chargers.
A compliant SD card
# The Foenix boards are fiddly about this, see the section below
# discussing SDcards. TLDR, get a 2Gb Transcend SD card from Amazon.
The most recent A2560U memory map documentation. A2560U_UM_Rev0.0.2.pdf
Optional: mouse with a PS2 adapter.
Optional: persistent storage. See [Persistent storage via IDE] below.
// SD cards
The systems are touchy about SDcards. Original design SDcards work, variants
do not. e.g. I have a 10-year old SanDisk SDCard. but it is SDHC rather than
SD and it does not work.
As of 20211228 I have been able to find non-HD Transcend SD cards on Amazon
UK.
Here is the output of fdisk for Transcend SD card,
# fdisk /dev/sdd
Welcome to fdisk (util-linux 2.33.1).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
Command (m for help): p
Disk /dev/sdd: 1.9 GiB, 2008022528 bytes, 3921919 sectors
Disk model: Storage Device
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x00000000
Device Boot Start End Sectors Size Id Type
/dev/sdd1 255 3921919 3921665 1.9G 6 FAT16
Command (m for help):
PJW wrote on 20210712,
"""
SD card should be a plain SD card (no HC or XC) and formatted with 512
byte allocation blocks.
I've been using a 2GB Transcend SD card formatted with a single partition.
The first limitation, by the way, is hardware related. The SD card
controller on the C256 only uses the base SD protocol.
The second limitation (on allocation block / cluster size) is kernel
related, and more sophisticated code can use larger clusters.
Oh and the file system the kernel recognizes on the SDC is FAT32.
"""
Elswhere I have seen Stefanie say that the partition size must be within 2G.
If I did not have a working sdcard, this next sequence of commands is
something I would try. Note that the fs type is not consistent with the
details above. These steps are not testing, feedback welcome.
Use fdisk to partition the sdcard.
Have fdisk, set the disk type to be '6'.
mkfs.fat -F 16 /dev/sdd1
// Morfe Emulator
Systems developers lean on emulators while they are bootstrapping new Foenix
models.
There are limitations of emulators: custom chips are important to the
character of the Foenix platform. Morfe support for custom chips is weak.
Morfe does enough that you should be able to get started in development for
either 65816 or 68k Foenix development in this setting.
Link,
https://github.com/aniou/morfe
Building this relies a recent golang. Two pieces of advice for this,
// Building on an unmodified debian/ubuntu
Ensure you have,
- make (works with the one the apt package manager installs for you)
- libsdl2-dev (works with the one the apt package manager installs for you)
- golang: a much newer version than is available in apt (see below)
// Golang
Option 1: install from tarball.
Via the official Golang site, download a recent tarball, unpack it, and
follow instructions to make the binaries available from your PATH.
Option 2: use snap
snap install go
// Build morfe
Follow the instructions in the README.MD file in the git repository.
The author has not tested these steps. If you want more help with Morfe,
recommend you private-message Blue or René in Discord.
// Using the official manual
This section shows you how to use the official 2560U manual to make some basic
interactions with a Foenix device.
These steps will teach you how to read a manual, but make sure you are using
the manual that matches your hardware.
If you are using something that is not a 2560U (e.g. 2560K, Morfe), then you
will need to consult the memory map documentation for that device, as it will
be different then the steps below. For example, rather than 0xb60000 in the
first example below, the text block might instead start at 0xc60000.
It is important to understand how the manual talks about memory addresses.
The 68k architecture was designed around 32-bit of addressable memory, but
the first model (68000 chip) could only address 24-bit of memory.
You would write a full 32-bit address by representing four bytes,
0x00112233
The manual shows some addresses in their 24-bit form,
0x112233
Both addresses above are equivalent.
Early in the A2560U manual, there is a page headed Memory Map. Here you can
see the blocks of memory reserved for various purposes, laid out in 24-bit
convention.
The manual shows that the Text Memory Block starts at 0xB60000.
Let's see what is in there. On your 2560U Foenix, type this -
peek8 0xb60000
On my clean-booted 2560U system, this shows 20. This is a hexidecimal number.
0x20 is the same as decimal 32. In the ascii character range, that is a space
character.
Let's change it to something else. On your 2560U Foenix, type in this,
poke8 0xb60000 0x41
You should see an A character at the top-left of your display.
Next, we will change the colour of the cell that character is in.
Look in the manual under the heading "Text Colour Memory Block". You should
see that text memory is covered in area 0x00B6 (first two address bytes), with
offset 0x8000 (last two address bytes). Hence, the first address in that area
is 0x00b68000 or just 0xb68000.
Change the colour of the letter we added,
poke8 0xb68000 0x80
If you want to view or change several bytes at once, there are multi-byte
versions of the peek and poke commands. Type "help" to see commands. The dump
command shows larger blocks of memory.
There are some gotchas about the way that multi-byte inserts work. Try using
poke32 to put a 32-bit sequence of four characters into the memory that starts
with 0xb600000. You may find the resulting character order to be unexpected.
// Capypsi toolchain by Hakan (hth33): assembler, compiler, linker
@20220625 1952
=========================================
In my experience, this is far and away the easiest way to get developing
for the foenix platform.
=========================================
Discord user hth313 has built a toolchain over many years for several
architectures. It is working for Foenix 68k since Q2 2022.
Binary distribution only, it is not open-source. Author says the system is
built in Haskell.
Website
https://www.calypsi.cc/
Debian Linux note,
At one point this tool was built for 32-bit linux only. As a result,
it was necessary to reconfigure your debian install to support multiarch
binaries in order to get it working.
There is a link to a manual at the website. At the time of writing, section
3.2 of that document gives a simple tutorial that shows you how to download
a starting-point development tree, and how to create a pgz binary.
Once you have created that, transfer it to a SDcard, and send that to your
foenix. On the foenix you may need to reboot it to see the updated contents of
the sdcard. Run "dir" to see entries and "hello.pgz" to run the sample app.
// Transferring apps over USB
** This does not work on my machine, but may be due to a hardware fault
Above, we transferred a pgz file to a sdcard. This section describes a method
that should be faster, but which is more fiddly to set up.
Instead of generating hello.pgz, here we will generate hello.hex. This file is
in Intel Hex format. This is a plain-text format that captures the binary.
Then, we need to convert that to another plaintext format, Motorola Srecord.
Setup,
Install the srecord tooling,
sudo apt install srecord
Get a checkout of some serial-port tooling,
git clone https://github.com/pweingar/C256Mgr
cd C256Mgr
python3 -B -m venv venv
. venv/bin/activate
pip install pyserial
In your dev directory,
make hello.hex
srec_cat hello.hex -Intel -o hello.s28 -Motorola
cd C256Mgr
. venv/bin/activate
python3 -B -m src.main upload-s28 /dev/ttyUSB0 ../hello.s28
You should see your foenix reset and then run the app.
// Machine code REPL
@20220101 1640
As of today, there is no support for 'call' functionality discussed here
in MCP, but there seems to be appetite for it in the forums. Working on
it. And there is a hack that can be used to simulate it, described below.
It should be possible to bootstrap a development environment on the Foenix
without use of third-party tools or a separate computer.
This approach echoes the way that programs were built in the earliest days of
the PC, using debug.com.
Key commands,
poke8, poke16, poke32: place a value into memory
peek8, peek16, peek32: inspect a memory address
dump: print a memory dump
call: (not yet in the MCP) set the program counter to jump to the supplied
address.
Although call is not yet in the MCP, you can simulate it as follows,
Write the address you want to jump to in the interrupt table entry for
divide-by-zero interrupts.
Use the test command in the MCP to create a divide-by-zero error.
// Getting started with Vasm (assembly programming)
Building vbcc/vasm from source is awkward. Instead, get this package from
Dr Volker Barthelmann.
http://www.compilers.de/vbcc.html
# At the bottom of this page, you will see binary distributions for both
# windows and linux.
Linux,
Example build script,
#!/bin/bash
export VBCC=/home/cturner/vbcc
# ^- CHANGE ME
PATH=$PATH:$VBCC/bin
vasmm68k_mot -chklabels -m68000 -align -Fsrec -s28 -exec=start -o hello.srec -L hello.lst hello.asm
# see bottom of page for hello.asm
Then use c256mgr to transfer the srec file to the target system. (c256mgr
is described further down)
Windows,
xxx
// Preparing to upload code via USB cable on Windows
Even if the device is recognised when you first attach it, you still need to
install a driver.
From https://wiki.c256foenix.com/index.php?title=Using_the_Debug_Interface
"""
The drivers for the serial USB device (XR21B1411) can be found at:
https://www.maxlinear.com/support/design-tools/software-drivers.
"""
I found the file xrusbser_2600_signed_win7.zip to be effective on Windows
10.
Python setup
Download and install the latest stable python3 from python.org.
As it installs, there should be an option to add it to your PATH. Ensure
this is selected.
You can check/edit this by doing WindowsKey+Break, selecting [Advanged
system settings], clicking [Environment Variables...] and then editing the
values for Path within this. Hopefully you won't need to do this. If you
/do/ change the values for Path here, you will need to click [OK] to save
your changes and then to restart any cmd prompt that you want the changes
to appear in.
You can inspect your PATH in windows by typing 'echo %PATH%' in cmd.
C256Mgr setup
Get C256Mgr. This tool enables command-line upload to the Foenix.
https://github.com/pweingar/C256Mgr
To run this, you will need the python lib pyserial to be installed. If you
are happy to do a global install of pyserial, 'pip install pyserial'. If
you know what you are doing with venv, you can use that instead.
Continue to the section [Using c256mgr to upload code] below.
// Preparing to upload code via USB cable on Linux
@20220101 1619
At the time of writing there is a bug in either C256mgr or Pyserial that
causes upload to fail on one of my linux boxes but not others. The
machines that work identify the new device as /dev/ttyUSB0. The machine
that fails identifies the new device as /dev/ttyACM0. That machine has a
PCIe serial card installed, unrelated to this project, and my best guess
is that this is confusing c256mgr or the pyserial library.
For this, I ran kernel 5.12.4 on Debian. Linux kernel build instructions
The drivers for the device seem to come standard in this kernel. I plugged it
in, and was able to use the C256mgr program described below.
On debian, your unix user will need to be in a group called dialout to access
the foenix device for upload.
sudo gpasswd --add ${USER} dialout
You may need to reboot for this to take effect. (Getting a fresh login did not
work for me).
If you have continuing problems, this is blunt-force way to make the port
accessible to all users, but it is annoying because you need to do it each
time you plug the cable in,
This assumes the Foenix is already plugged into your workstation via
USB-Mini.
Use the --list-ports usage below to work out what the port name is
sudo chmod 666 [port name]
Get C256Mgr - this allows for command-line upload to the Foenix.
https://github.com/pweingar/C256Mgr
To run this, you will need the python lib pyserial to be installed. Here is
how you create a virtual-env with this lib installed,
cd to the base of your copy of the C256 directory
python3 -B -m venv venv
. venv/bin/activate
pip install pyserial
Continue to the section [Using c256mgr to upload code] below.
// Using c256mgr to upload code
Switch on your Foenix, and use the USB-Mini cable to connect it to your
workstation.
Now cd into the C256Mgr source subdirectory (which is also called C256Mgr),
Some of the commands below are given as 'python3', which is what works on
Debian. On Windows that command will instead be 'python'.
# List the com ports on your system
python3 c256mgr.py --list-ports
# On my system, the Foenix is /dev/ttyACM0. On Windows it might be
# COM3.
# Upload the binary file
python3 c256mgr.py --port /dev/ttyACM0 --binary file.bin
# This should upload the contents of file.bin to your Foenix, and then
# jump into the code it has just uploaded.
// Persistent storage via IDE
** Incomplete section
You do not need persistent storage on your Foenix, but may want it.
There is some choice in how you go about this, detailed below.
Note that you do not need a separate power cable. Power for the device comes
through the IDE connection.
Strategy/1: use an old laptop hard disk drive,
I think this is the strategy that Stefany uses for her own equipment.
The riser information below is vague. You may run into problems with
incompatible threading. This section could use a review from someone who
has gone through this process.
Another thing to be wary of is that hard disk failure is a fact of life,
and ebay-sourced second-hand laptop disks may not have much life left in
them.
Equipment,
Female-to-female 44-pin IDE cable. If you are planning to mount the
disk to the board, short is good. If you want to have the disk
alongside, long is good.
2.5 inch IDE laptop from ebay or similar.
4x risers of the sorts you would use to attach a PC motherboard to its
case.
4x screws suitable for the riser.
Screw the risers into the disk. Then screw the risers into the
motherboard, upside down. Voila, your disk is mounted to the board.
Note that there are mounting points on the motherboards of some Foenix
devices.
Strategy/2: use an IDE-to-compact-flash adapter and Compact Flash storage
This is the approach used by vinz67, "for IDE I use a IDE->Compact
Flash adapter, like what is used on computers like the Amiga 600, it works
perfectly with EmuTOS"
vinz67 continues, "I have a 256Mo compact flash card from an old digital
camera, that's more than enough to get started. For EmuTOS I formatted it
in FAT16 because FAT32 is not managed by EmuTOS. But the FoenixMCP kernel
uses the FATFS package, which manages FAT32 ok."
@20220625 1943
I am not sure what you do once you have the IDE-to-compact-flash adapter
plugged in - how you access the disk from the foenix.
Below are some older notes that do not make much sense to me.
Stefanie wrote on 20201102,
"""
in terms of HDD right now, having a smaller driver in terms of density is
better than a bigger one.
The limitation of the size of the partition is still the same as the
SDCard. The partition can't be bigger than 2G and the Sector Size needs to
be 512Bytes.
Now, you also need to make sure the drive is Partition in FAT32 LBA, which
means that the partition Code needs to be $0C (if you read about it, you
will know what I am talking about)
I bought a bunch of refurb 80G on Ebay and they worked great
"""
Hardware setup page,
https://wiki.c256foenix.com/index.php?title=Hardware_Setup
// FPGA patching
Each Foenix system incorporates one or more FPGA chips. The novelty of FPGA is
that it is a chip that can be reprogrammed to have different behaviour (it is
"Field-Programmable".) If you need to upgrade the FPGA behaviour of your
board, you may find this section useful.
FPGA images
From time to time, Stefany will issue a FPGA release.
SOF, "SRAM Object File". I /think/ this allows you to upload to the
FPGA so that the data lives in RAM. i.e. good for testing releases.
JLC files: I think these are applied to the flash memory of the FPGA.
In a section below, we will discuss the Quartus tooling. You can open
these files in that tooling.
FPGA imaging with the USB Blaster (Quartus tooling)
OS situation,
Debian linux: I did not get this working on Linux. Failed at
Autodetect (described below).
Windows 10: succeeded.
Links to the tools,
You want "Quartus Prime (includes Nios II EDS)" and "Cyclone IV device
support"
Windows: https://fpgasoftware.intel.com/18.1/?edition=lite&platform=windows
Linux: https://fpgasoftware.intel.com/18.1/?edition=lite&platform=linux
Driver installation process for Windows 10,
Install the Quartus tooling on your Windows box. I think that if the
Cyclone IV device is in the same directory as the main installer, the
main installer offers to install it for you as part of its default
flow.
Make sure your Foenix device is off.
Install the USB Blaster ribbon cable end to the JTAG pinout on the board.
Switch your Foenix device on.
Plug the USB Blaster into your system.
In Windows /Device Manager/.
Find the new device, under a heading called something like
"Undefined".
Right click it, go to Properties.
There will be a button saying something like Update Driver on the
General tab. Click it.
Manually search for a driver. Make sure the Subdirectories
checkbox is selected. Point it to the drivers subdir of the
Quartus install directory. It will be something like
C:\intelFPGA_lite\18.1\quartus\drivers
Load the Quartus GUI. If you don't see a button Hardware Setup in the
top left, look for a Programmer icon in the toolbar. On my linux host,
it has a rainbow going into a diamond. Click that, look for the
Hardware Setup button.
These are the general stages of using your USB Blaster -
(1) Does the OS detect the USB Blaster?
(2) If you run "Autodetect", does it do Jtag discovery?
(3) Successful upload.
When you autodetect, it will ask you which of several cryptic chips it
should use. The fact that it has detected any is a good sign. Don't worry
about the specific chip to select. When you open the file that Stefany has
sent you, it will show you what the appropriate chip is in the GUI anyway.
These are the chips I saw on the 2560U: 10CL040Y, 10CL040Z, EP3C40,
EP4CE30, EP4CE40.
On 20 November 2021, Stefany referred to 10CL040Y as "Red Version" and
EP4CE40 as "Black Version". I don't know what this means.
Other materials,
This is old and you probably don't need it if the steps above worked.
https://www.youtube.com/watch?v=0laamngVrvM
// Vicky II graphics engine
See https://wiki.c256foenix.com/index.php?title=VICKY_II
// Vicky font layout
In #apps-development, vinz67 asked, "@PJW @gadget do you know how VICKY's font
memory is organised please ?"
Gadget replied, "If it's the same as on the C256 line, each character consists
of 8 bytes. Upper left hand corner is the high-bit of byte zero, upper right
is the low bit of byte zero, lower left is the high bit of byte 7, lower right
is the low bit of byte 7. The bytes are placed in memory from character zero
to character 255, 0..7, 0..7, 0..7, etc."
PJW added, "Yeah, C256 and A2560U fonts are the same layout. The A2560K is a
little different. The mostly-text-mode screen supports an 8x16 font layout,
where the structure is essentially the same, but each character is 16 bytes
rather than 8."
// Reset vectors
Imagine that you upload your code to your Foenix, and want the ability to
then jump into that code. How does this work?
You can modify the reset vector (interrupt handler?) ahead of your upload
in order that the reset will cause a jump into your code like this,
poke32 4 0x100000
vinz67 writes that this will "set the 68000 reset vector to the memory
location where [code] is".
Once you have typed the code above, then use c256mgr to upload the code.
This technique will not work for over-riding the behaviour of the reset button
on the motherboard. vinz67 writes, "If/when you press the reset button, GAVIN
copies the first 64K of flash memory to system ram, starting with address 0.
So it will overwrite anything you would have set in the reset vector. "
// System DMA Block
Found here,
https://wiki.c256foenix.com/index.php?title=System_DMA_Block
Purpose as described,
"""
The System DMA block is a portion of the Vicky II chip which is
responsible for high speed memory transfers to or from system memory
SDMA can copy data between different locations within system RAM, it can
be used in conjunction with the Video DMA Block to transfer data between
video RAM and system RAM.
IMPORTANT! SDMA halts the processor while it is in operation. The CPU will
be unable to perform any tasks while an SDMA transfer is in operation.
This includes handling interrupts of any sort.
"""
// Ethernet Controller
I found a link to some docs on the wiki page via Random Page surfing,
Product,
https://www.microchip.com/en-us/product/LAN9221
Spec,
https://ww1.microchip.com/downloads/en/DeviceDoc/00002416A.pdf