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