OS-9: Difference between revisions

From F256 Foenix
Jump to navigationJump to search
VisualWikitext
(Changes to add FoenixMgr configuration instructions)
 
(24 intermediate revisions by 3 users not shown)
Line 5: Line 5:


== A word about platforms ==
== A word about platforms ==
This page assumes you're running on Linux or macOS. If you're using Windows, someone will have to step up and write a document for that platform.
This page assumes you're running on Linux or macOS. If you're using Windows, these instructions don't apply, and someone will have to step up and write steps to develop on that platform.


== Foenix-specific tools ==
== Tooling ==
To get code into the F256, you need [https://github.com/pweingar/FoenixMgr FoenixMgr]. Download this package and follow the instructions to install it on your machine.
Cross-hosted development is the fastest way to develop for the F256. For this you need the following:
 
Note, if you're using a Mac, you won't be able to upload code into the F256 due to the [https://www.maxlinear.com/support/design-tools/software-drivers driver manufacturer] being so behind on updates. I have a Linux VM and use FoenixMgr tools in bridge mode on there. This allows me to run the commands on my Mac and direct them to the Linux VM.
 
== Cross-hosted software ==
Cross-hosted development is the fastest way to develop code for the F256. For this you need the following:


* [http://www.lwtools.ca lwtools] - an assembler/linker package
* [http://www.lwtools.ca lwtools] - an assembler/linker package
* [https://github.com/nitros9project/toolshed ToolShed] - a set of tools for creating disk images
* [https://github.com/nitros9project/toolshed ToolShed] - a set of tools for creating disk images
* [https://github.com/nitros9project/nitros9 NitrOS-9] - the NitrOS-9 operating system in source form
* [https://github.com/nitros9project/nitros9 NitrOS-9] - the NitrOS-9 operating system in source form
* [https://github.com/pweingar/FoenixMgr FoenixMgr] - tools to load code into RAM or Flash of the F256.


You can pull these down individually, or better yet, use [https://github.com/strickyak @strickyak]'s great [https://github.com/strickyak/coco-shelf/ CoCo Shelf repository]. It has a <code>Makefile</code> which gets all of the above and puts it in a convenient location (note that you'll have to update your shell script of choice to include the locations of the binaries in the <code>PATH</code> environment variable).
You can pull these down individually, or better yet, use [https://github.com/strickyak @strickyak]'s great [https://github.com/strickyak/coco-shelf/ CoCo Shelf repository]. It has a <code>Makefile</code> which gets all of the above and puts it in a convenient location (note that you'll have to update your shell script of choice to include the locations of the binaries in the <code>PATH</code> environment variable).


Here are the commands to type at the terminal to pull down all the required software:
Here are the terminal commands for Linux and macOS to pull down all the required software:
  <code>cd
  cd
  git clone <nowiki>https://github.com/strickyak/coco-shelf.git</nowiki>
  git clone <nowiki>https://github.com/strickyak/coco-shelf.git</nowiki>
  cd coco-shelf
  cd coco-shelf
  export PATH=$PATH:$HOME/coco-shelf/bin
  export PATH="$PATH:$HOME/coco-shelf/bin"
  make mirror-stuff done-lwtools done-cmoc done-toolshed done-nitros9</code>
  make ANON=1 nitros9/done FoenixMgr/done
 
(If you have a github account and your github ssh key is loaded,
you can omit `ANON=1` on the last command,
so it will check out git repositories using your github username,
in case you want to push changes.)


== Compiling OS-9 Level 2 ==
There is a special Make target for re-flashing the F256Jr or F256K,
Note: This assumes you have already built the '''''feu boot loader''''' and flashed it to the F256. Compiling NitrOS-9 requires lwtools and ToolShed.
but first time you run this command, it should fail. 
Then you have to edit the `port=` line in `FoenixMgr/foenixmgr.ini`
and run the command again (with the cable plugged in):
make ANON=1 run-f256-flash        # Old command for F256Jr that works?
or
make ANON=1 run-f256jr-flash      # TODO fix this
or
make ANON=1 run-f256k-flash      # TODO fix this


==== Set the NITROS9DIR environment variable to the nitros9 directory ====
=== Configure FoenixMgr ===
If you forget to do this, you will see an error when you compile like "*** No rule to make target '/rules.mak'."
The makefiles for f256 NitrOS-9 use the <code>bulk-flash</code> command from FoenixMgr.  This command is in the <code>bin</code> directory of coco-shelf.  The <code>bin</code> directory must be in your <code>PATH</code> in order for the flash procedure to work from the NitrOS-9 makefile. On linux, add a line to your <code>.profile</code> similar to:


PATH="$HOME/coco-shelf/bin:$PATH"
FoenixMgr's <code>foenixmgr.ini</code> file must also be configured with the correct port to flash the f256.  The F256 Jr.Jr. and F256 K2 both have a USB-C serial port that requires no additional drivers.  The F256 Jr. and F256-K have a USB debug port which requires a special driver to work.  The procedure for the F256 Jr.Jr. and F256 K2:  plug the usb cable to your computer and the F256 and turn on the F256. On linux, type lsusb to verify the connection.  The output should show an FT4232 UART:
~/coco-shelf/FoenixMgr $ lsusb
Bus 002 Device 002: ID 174c:55aa ASMedia Technology Inc. ASM1051E SATA 6Gb/s bridge, ASM1053E SATA 6Gb/s bridge, ASM1153 SATA 3Gb/s bridge, ASM1153E SATA 6Gb/s bridge
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
'''Bus 001 Device 017: ID 0403:6011 Future Technology Devices International, Ltd FT4232H Quad HS USB-UART/FIFO IC'''
Bus 001 Device 003: ID 248a:8367 Maxxter Telink Wireless Receiver
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
Next change directory to coco-shelf/FoenixMgr and run python <code>FoenixMgr/FoenixMgr.py --list-ports</code>.
~/coco-shelf/FoenixMgr $ python FoenixMgr/fnxmgr.py --list-ports
 
++ python3 FoenixMgr/fnxmgr.py --list-ports
  Description: n/a
  Manufacturer: None
  Product: None
/dev/ttyUSB3
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
/dev/ttyUSB2
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
/dev/ttyUSB1
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
/dev/ttyUSB0</code>
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
The second port,<code>/dev/ttyUSB1</code>, should be the correct port.  Change the port line in <code>foenixmgr.ini</code> to this port and save it (you don't have to worry about the other settings):
~/coco-shelf/FoenixMgr/foenixmgr.ini
[DEFAULT]
'''port=/dev/ttyUSB1'''
labels=sample.lbl
flash_address=380000
chunk_size=1024
cpu=65816
FoenixMgr should now be configured to flash the <code>FEU</code>.
== Building FEU and OS-9 Level 1 from scratch ==
FEU is the Foenix Executive Utility. It resides in flash and hosts a debugger and booters that can bring up operating systems like OS-9. FEU runs under OS-9 Level 1, so go ahead and build the entire operating system:
  cd nitros9
  cd nitros9
  export NITROS9DIR=$PWD
  export NITROS9DIR=$PWD
cd level1/f256
make
cd feu
Now you can flash the image into the F256. You must have a USB cable connected to the system from your computer. Note: if you're using a Mac, you won't be able to upload code into the F256 due to the [https://www.maxlinear.com/support/design-tools/software-drivers driver manufacturer] being so behind on updates. You can use a Linux VM and FoenixMgr tools in bridge mode on the Mac.


==== Build lib and Rogue (if you want to play Rogue) ====
There are distinct builds of FEU for the F256 Jr and the F256K. Power up the machine, then select the correct command:
From the nitros9 directory:
cd feu
make flash_f256jr
or
cd feu
make flash_f256k


cd lib
Then (this is in addition to make flash_f256jr or make flash_f256k):
make
cd ../3rdparty/packages/rogue
make


==== Build Level 2 for the F256 ====
make flash_f0
From the nitros9 directory:


  cd level2/f256
Once the flash completes, restart the machine and FEU should come up.
 
== Building OS-9 Level 2 ==
To build OS-9 Level 2, run these commands (this assumes you have added the NITROS9DIR environment variable as above:  export NITROS9DIR=$PWD from the top level nitros9 directory):
  cd ../../level2/f256
  make dsk
  make dsk


: Note: ''do not type'' <code>make</code> ''in the root nitros9 directory.  The nitros9 directory contains builds for every version and build of NitrOS-9 (coco, coco3, etc.).  Make sure to invoke ''<code>make</code> ''from the level2/f256 directory to avoid compiling every possible iteration of the system. ''
This produces the following disk images for the F256 Jr and the F256K:
 
NOS9_6809_L2_v030300_f256jr_dw.dsk
  NOS9_6809_L2_v030300_f256jr_sd.dsk
NOS9_6809_L2_v030300_f256k_dw.dsk
  NOS9_6809_L2_v030300_f256k_sd.dsk


This will produce 2 dsk images:
The ''dw'' disk images are for booting from DriveWire. The ''sd'' disk image are for booting from the SD card. You need to write the images onto an SD card, then insert the SD card into the F256 and restart.


NOS9_6809_L2_v030300_f256_dw.dsk
Here's how to image the SD card.
NOS9_6809_L2_v030300_f256_sd.dsk


The ''dw'' disk image will boot from DriveWire (if you have installed an ESP32 or ESP8266 and have a DriveWire server).  The ''sd'' disk image will boot from the SD card. Use dd on linux,etc. to flash the disk to an SD card. On linux, '''''IF''''' the card is mounted in /dev/sdx:
==== Linux ====
On Linux, insert the SD card into your computer. Ttype <code>lsblk</code> to find the correct device and replace ''sdx'' on the command line below with it:


  dd if=NOS9_6809_L2_v030300_f256_sd.dsk of=/dev/sdx
  dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/''sdx''


Note:  '''This is just a sample command, your SD card might not be named /dev/sdx'''. Check and make sure you are writing to the correct device. In linux, type <code>lsblk</code> in a terminal to find the correct device. Substitute /dev/sdb in the above command with the correct device name for your SD card on your system.  Double check the device name to avoid data loss.
==== macOS ====
On macOS, insert the SD card into your Mac. A dialog will likely appear telling you that the disk you attached isn't readable. Click the "ignore" button, then type <code>diskutil list external</code> to obtain the device name of the SD card and replace ''diskx'' on the command line below with it:
sudo dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/''diskx''
Once the command completes, type:
diskutil eject /dev/''diskx''
You can then safely remove the SD card.

Latest revision as of 06:46, 18 May 2025

Introduction

The FNX6809 combined with the F256 makes a great system for running OS-9/6809. OS-9 is a real-time, embedded operating system created by Microware Systems Corporation. While it was used in many areas of industry, home computer users know it best for its implementation on the Tandy Color Computer sold by Radio Shack

Today, a community effort has led to the creation of NitrOS-9, an open source version of the OS-9 operating system. Throughout this page, I'll refer to NitrOS-9 as OS-9.

A word about platforms

This page assumes you're running on Linux or macOS. If you're using Windows, these instructions don't apply, and someone will have to step up and write steps to develop on that platform.

Tooling

Cross-hosted development is the fastest way to develop for the F256. For this you need the following:

  • lwtools - an assembler/linker package
  • ToolShed - a set of tools for creating disk images
  • NitrOS-9 - the NitrOS-9 operating system in source form
  • FoenixMgr - tools to load code into RAM or Flash of the F256.

You can pull these down individually, or better yet, use @strickyak's great CoCo Shelf repository. It has a Makefile which gets all of the above and puts it in a convenient location (note that you'll have to update your shell script of choice to include the locations of the binaries in the PATH environment variable).

Here are the terminal commands for Linux and macOS to pull down all the required software: 

cd
git clone https://github.com/strickyak/coco-shelf.git
cd coco-shelf
export PATH="$PATH:$HOME/coco-shelf/bin"
make ANON=1 nitros9/done FoenixMgr/done

(If you have a github account and your github ssh key is loaded, you can omit `ANON=1` on the last command, so it will check out git repositories using your github username, in case you want to push changes.)

There is a special Make target for re-flashing the F256Jr or F256K, but first time you run this command, it should fail. Then you have to edit the `port=` line in `FoenixMgr/foenixmgr.ini` and run the command again (with the cable plugged in): 

make ANON=1 run-f256-flash        # Old command for F256Jr that works?

or 

make ANON=1 run-f256jr-flash      # TODO fix this

or 

make ANON=1 run-f256k-flash       # TODO fix this

Configure FoenixMgr

The makefiles for f256 NitrOS-9 use the bulk-flash command from FoenixMgr. This command is in the bin directory of coco-shelf. The bin directory must be in your PATH in order for the flash procedure to work from the NitrOS-9 makefile. On linux, add a line to your .profile similar to: 

PATH="$HOME/coco-shelf/bin:$PATH"

FoenixMgr's foenixmgr.ini file must also be configured with the correct port to flash the f256. The F256 Jr.Jr. and F256 K2 both have a USB-C serial port that requires no additional drivers. The F256 Jr. and F256-K have a USB debug port which requires a special driver to work. The procedure for the F256 Jr.Jr. and F256 K2: plug the usb cable to your computer and the F256 and turn on the F256. On linux, type lsusb to verify the connection. The output should show an FT4232 UART: 

~/coco-shelf/FoenixMgr $ lsusb

Bus 002 Device 002: ID 174c:55aa ASMedia Technology Inc. ASM1051E SATA 6Gb/s bridge, ASM1053E SATA 6Gb/s bridge, ASM1153 SATA 3Gb/s bridge, ASM1153E SATA 6Gb/s bridge
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 017: ID 0403:6011 Future Technology Devices International, Ltd FT4232H Quad HS USB-UART/FIFO IC
Bus 001 Device 003: ID 248a:8367 Maxxter Telink Wireless Receiver
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub

Next change directory to coco-shelf/FoenixMgr and run python FoenixMgr/FoenixMgr.py --list-ports. 

~/coco-shelf/FoenixMgr $ python FoenixMgr/fnxmgr.py --list-ports
 
++ python3 FoenixMgr/fnxmgr.py --list-ports
  Description: n/a
  Manufacturer: None
  Product: None
/dev/ttyUSB3
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
/dev/ttyUSB2
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
/dev/ttyUSB1
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer
/dev/ttyUSB0
  Description: New Retro Computer - New Retro Computer
  Manufacturer: Xilinx
  Product: New Retro Computer

The second port,/dev/ttyUSB1, should be the correct port. Change the port line in foenixmgr.ini to this port and save it (you don't have to worry about the other settings): 

~/coco-shelf/FoenixMgr/foenixmgr.ini

[DEFAULT]
port=/dev/ttyUSB1
labels=sample.lbl
flash_address=380000
chunk_size=1024
cpu=65816

FoenixMgr should now be configured to flash the FEU.

Building FEU and OS-9 Level 1 from scratch

FEU is the Foenix Executive Utility. It resides in flash and hosts a debugger and booters that can bring up operating systems like OS-9. FEU runs under OS-9 Level 1, so go ahead and build the entire operating system: 

cd nitros9
export NITROS9DIR=$PWD
cd level1/f256
make 
cd feu

Now you can flash the image into the F256. You must have a USB cable connected to the system from your computer. Note: if you're using a Mac, you won't be able to upload code into the F256 due to the driver manufacturer being so behind on updates. You can use a Linux VM and FoenixMgr tools in bridge mode on the Mac.

There are distinct builds of FEU for the F256 Jr and the F256K. Power up the machine, then select the correct command: 

cd feu
make flash_f256jr

or 

cd feu
make flash_f256k

Then (this is in addition to make flash_f256jr or make flash_f256k): 

make flash_f0

Once the flash completes, restart the machine and FEU should come up.

Building OS-9 Level 2

To build OS-9 Level 2, run these commands (this assumes you have added the NITROS9DIR environment variable as above: export NITROS9DIR=$PWD from the top level nitros9 directory): 

cd ../../level2/f256
make dsk

This produces the following disk images for the F256 Jr and the F256K: 

NOS9_6809_L2_v030300_f256jr_dw.dsk
NOS9_6809_L2_v030300_f256jr_sd.dsk
NOS9_6809_L2_v030300_f256k_dw.dsk
NOS9_6809_L2_v030300_f256k_sd.dsk

The dw disk images are for booting from DriveWire. The sd disk image are for booting from the SD card. You need to write the images onto an SD card, then insert the SD card into the F256 and restart.

Here's how to image the SD card.

Linux

On Linux, insert the SD card into your computer. Ttype lsblk to find the correct device and replace sdx on the command line below with it: 

dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/sdx

macOS

On macOS, insert the SD card into your Mac. A dialog will likely appear telling you that the disk you attached isn't readable. Click the "ignore" button, then type diskutil list external to obtain the device name of the SD card and replace diskx on the command line below with it: 

sudo dd if=NOS9_6809_L2_v030300_f256k_sd.dsk of=/dev/diskx

Once the command completes, type: 

diskutil eject /dev/diskx

You can then safely remove the SD card.

Retrieved from "http://wiki.f256foenix.com/index.php?title=OS-9&oldid=38075"