breakintoprogram / agon-mos

Official AGON QUARK Firmware: eZ80 MOS

agon-mos

Part of the official Quark firmware for the Agon series of microcomputers

What is the Agon

Agon is a modern, fully open-source, 8-bit microcomputer and microcontroller in one small, low-cost board. As a computer, it is a standalone device that requires no host PC: it puts out its own video (VGA), audio (2 identical mono channels), accepts a PS/2 keyboard and has its own mass-storage in the form of a µSD card.

https://www.thebyteattic.com/p/agon.html

What is a MOS

The MOS is a command line machine operating system, similar to CP/M or DOS, that provides a human interface to the Agon file system.

It also provides an API for file I/O and other common operations for BBC Basic for Z80 and other third-party applications.

Loadig BBC Basic for Z80

1. Download bbcbasic.bin from agon-bbc-basic releases
2. Copy it to the root directory of the Agon SD card
3. Insert the SD card into the AGON and reset/boot it
4. Check the file is on the SD card with a CAT or . command
5. Type the following commands into MOS:
   • LOAD bbcbasic.bin
   • RUN
6. You should then be greeted with the BBC Basic for Z80 prompt

Etiquette

Please do not issue pull requests or issues for this project; it is very much a work-in-progress. I will review this policy once the code is approaching live status and I have time to collaborate more.

Build

The eZ80 is programmed via the ZDI connector on the left-hand side of the board. This requires a Zilog Smart Cable that can be purchased from online stockists such as Mouser or RS Components.

There are three compatible cables with the following part numbers:

• ZUSBSC00100ZACG: USB Smart Cable (discontinued)
• ZUSBASC0200ZACG: USB Smart Cable (in stock - this requires ZDS II version 5.3.5)
• ZENETSC0100ZACG: Ethernet Smart Cable (in stock)

Important! Make sure you get the exact model of cable; there are variants for the Zilog Encore CPU that have similar part numbers, but are not compatible with the Acclaim! eZ80 CPU.

You can download the ZDS II tools for free via these links. The software contains an IDE, Debugger, C Compiler and eZ80 Assembler.

• Zilog ZDS II Tools version 5.3.4
• Zilog ZDS II Tools version 5.3.5

You will also need a Hex2Bin utility to convert the MOS.hex file to MOS.bin ready for release.

NB:

• The tools are only available for Windows PC.
• The tools are compatible with Wine on Linux / OSX, but the USB Smart Cable drivers do not work
• The Ethernet Smart Cable may be compatible with the tools running on Wine, though this combination has not been tested by me

I currently build the official Quark software on a Windows XP KVM running on Ubuntu 20.04 LTS, using ZDS II Tools version 5.3.4, connecting to the Agon with the discontinued USB smart cable.

It is recommended that building and testing the MOS is done via the ZDS II tools and a Zilog Smart Cable, otherwise there is an increased risk of bricking the Agon.

Other options for developing C and eZ80 on the Agon are available. Please check the Agon Programmers Group on Facebook for more information.

Any custom settings for Agon development is contained within the project files, so no further configuration will need to be done.

Documentation

The AGON documentation can now be found on the Agon Light Documentation Wiki

Licenses

This code is released under an MIT license, with the following exceptions:

• FatFS: The license for the FAT filing system by ChaN can be found here src_fatfs/LICENSE along with the accompanying code.

Links

• Zilog eZ80 User Manual
• ZiLOG Developer Studio II User Manual
• FatFS - Generic File System
• AVRC Tutorials - Initialising an SD Card

agon-mos's Issues

Improve boot sequence

Improve the sync between the eZ80 and the ESP32
Acceptance Criteria

• The eZ80 must poll the ESP32, and only start when it receives a general poll packet back
• If it times out, it must try again at a lower baud rate

USB Keyboard Support

Just received an Agon Light from Olimex. It has the new USB port but it doesn’t actually support USB keyboards. It supports keyboards that speak PS2 protocol (over USB connector?) Unfortunately I don’t have a keyboard that does that. I do remember when keyboards were made like this. Basically they supported both protocols and you used a passive converter. Ideally MOS would support USB HID? Maybe there is another option?

CAT command not working in autoexec.txt

When using the following autoexec.txt file, the CAT output is not visible:
SET KEYBOARD 1
LOAD bbcbasic.bin
CD tests
CAT
RUN

MOS should be able to call Z80 and ADL mode binaries

MOS executable files should contain a header that determines what kind of file this is:

• Secret word
• Version number
• Mode (ADL or Z80)

The MOS should read the header and either execute the code in a Z80 64K segment (current and default behaviour) or in ADL mode (what the MOS runs in).

Examples of both types should be provided

Add *VDU command to MOS

Requested by Fred Smith. A useful enhancement that will enable users to do things like change modes via the command line / autoexec.tx

Implement the low-level FatFS commands in MOS (Stage 2)

Implement the following methods:

• ffs_api_ftruncate
• ffs_api_fsync
• ffs_api_fforward
• ffs_api_fexpand
• ffs_api_fgets
• ffs_api_fputc
• ffs_api_fputs
• ffs_api_fprintf
• ffs_api_ftell
• ffs_api_fsize
• ffs_api_ferror
• ffs_api_dopen
• ffs_api_dclose
• ffs_api_dread
• ffs_api_dfindfirst
• ffs_api_dfindnext
• ffs_api_unlink
• ffs_api_rename
• ffs_api_chmod
• ffs_api_utime
• ffs_api_mkdir
• ffs_api_chdir
• ffs_api_chdrive
• ffs_api_getcwd
• ffs_api_mount
• ffs_api_mkfs
• ffs_api_fdisk
• ffs_api_getfree
• ffs_api_getlabel
• ffs_api_setlabel
• ffs_api_setcp

Extend MOS to support setting of keyboard delay and rate, and get/set the LED state

Handle the packet return data and store in system variables.

Load custom video modelines from file on SD card

As an Agon user
I want to be able to load custom modelines from a file on the SD card
So that I can set a particular resolution without changing and compiling the VDP source code

Enhancement: From command prompt, add ability to toggle between the last issued command and an empty prompt

Sometimes when I type the cursor up key from the command prompt, I change my mind (the last entered command is not what I wanted).

When that happens, I can either hit the enter key to re-submit that last entered command, or I can hit the escape key to cancel, with the caveat that the Escape mechanism will be invoked (i.e. "Escape" is displayed and the prompt is advanced a couple of lines).

As an alternative, I would like to be able to simply type the cursor up key again to get back to the empty > prompt. Typing the cursor key multiple times could alternate between displaying the empty prompt or the last command entered.

IT layout Keyboard

Hi!

I've finally found a PS/2 compatible keyboard, but its Italian layout is currently not supported by the AegonLight 2.

Would it be possible to add this particular layout besides the US and UK ones with a new parameter value to SET KEYBOARD in the autoexec.txt file ?

Thanks a lot.

Add clock support to MOS

Acceptance criteria:

• The ability to set the time with a star command (maybe *TIME, or split into *DATE and *TIME)
• The ability to read the time with a star command (maybe the same command, no parameters)
• Time can be set and read using MOS api calls
• Time can be used in FatFS as a timestamp

Nice to have:

• Check whether the EZ80F92 has a RTC (yes, but not fully plumbed in - see comments below)
• Check whether the ESP32 has a RTC (yes)

[trivial/admin] add agon-light topic

Could you add the agon-light GitHub topic to this and other Agon Light-related repositories, to aid in community discovery of related resources? Thanks! 🙏🏻

Make MOS error messages a bit less intimidating

• Changed "Access denied due to prohibited access or directory full" to "Access denied or directory full"
• Changed "Access denied due to prohibited access" to "Access denied"

Enhancement: Add support for * and ? wildcards for file matching

Having support for wildcards would be very useful, such as when one needs to delete several files that match a pattern.
e.g. *DELETE *.BBC

The line editor goes a bit weird when inserting characters in the middle of lines that are longer than a screen width at the bottom of the screen.

This is probably down to the edit cursor position not being updated when the screen scrolls during an edit. Had a similar issue with the Next editor.

Use CTRL+ALT+DEL instead of CTRL+SHIFT+ESC to soft reboot

As a PC user
I want to be able to use CTRL+ALT+DEL to soft boot my Agon
As I can remember that

Provide bin files for MOS RC releases

Looks like bin files for the MOS RC releases are removed from the project. Please provide the bin files as before so we can install them alongside with BBC BASIC.
Thanks.

mos_uclose doesn't appear to remove registered interrupts

mos_uclose calls close_UART1 in mos.c, which doesn't appear to remove the previously registered interrupt(s) from the UART1_IER register. This causes an issue later on, when the old interrupt vector is put back in place.
When I use the MOS API mos_setintvector to set my uart1 handler, then mos_uopen using a uart structure, call my own closing routine and put back the previous vector with mos_setintvector, everything runs just fine.
I'm using this close to close out the UART1 before returning the old vector:

VOID close_UART1( VOID )
{
UART1_IER = 0 ; //! Disable all UART1 interrupts.
UART1_LCTL = 0 ; //! Bring line control register to reset value.
UART1_MCTL = 0x00 ; //! Bring modem control register to reset value.
UART1_FCTL = 0 ; //! Bring FIFO control register to reset value.

init_UART1();													// set port pins to original values
return ;

}

perhaps it's unnecessary to again init the UART1, but I was just being cautious.

Update the MOS from SD card

LOAD and RUN alias

I'd like have possibility load and run something with one command.

I think it can be called 'CHAIN' like in BBC Basic or it's possible execute just by filename in current directory(like *-commands form /mos/).

First way will look more BBCish but second will looks more in common way.

Improve keyboard handling

Never been 100% happy with the way the keyboard debounce/repeat is handled in MOS, esp. when returning keycodes to BASIC. Look at improving it so that INKEY$ will always show the keycode, rather than the debounced version used in MOS/GET$

Use FF_FS_TINY in FatFS

Each file object (FFOBJID, FIL, DIR) contains a 512 byte buffer cache for file operations. By setting FF_FS_TINY to 1 in ffconf.h this buffer is removed and a global buffer is used. This will make the FatFS file IO a bit easier on memory for user apps.

Acceptance Criteria:

• The code is not significantly slower after the change
• No other issues are reported

Benchmarking:

The BASIC file benchm9,bas will run a read/write operation. Base timings before the mod are:

• Write: 29.85s
• Read: 14.2s

MOS commands should be case insensitive

Need to add a silent mode to the mos_OSCLI command so that I don't get the OK prompt after executing a command from the API

MOS commands should be abbreviated with a dot like BBC BASIC

Missing UART refactor commits?

Hi there,

I think in your last round of commits while refactoring UART you might have missed a couple of commits from local:

• XDEF _serialFlags and (I assume) _serialFlags DS 1 are missing from the committed globals.asm
• Various references to serial_PUTCH remain in the version of vectors16.asm committed, rather than new UART0_serial_PUTCH

With those changes made manually here it all compiles, flashes and runs happily.

Regards,

Greg

Add a block transfer function from MOS to VDP

As a SureCloud developer
I want to be able to pass a block of data to the VDP
Without the overhead of doing lots of RST 10h calls in a loop
As I am concerned about performance

Support for *KEY command

To redefine function keys as specified in BBC BASIC:
*KEY n [str]

Buffer overrun potential in mos_exec

Unsafe use of sprintf in mos_exec (mos.c)

sprintf(path, "/mos/%s.bin", ptr);

Enhancement: Add support for DEL key and ability to temporarily show a hidden cursor by holding down a key

I was not sure if this belonged here or in the Quark VDP project.

The backspace key works great for deleting the character immediately to the left of the cursor. It would also be very useful to be able to delete the character immediately to the right of the cursor by typing the DEL key.

IDEA: I don't know if this would be a hassle to implement, but it would be useful to be able to reveal on-demand the location of an invisible cursor (i.e. a cursor that has been hidden via the VDU 23,1,0 operation). Perhaps it could temporarily be revealed as a flashing (or solid) cursor while a particular key (e.g. the left Alt key) is being held down.

MOS does not return correct Screen Height

Reported by Lennart Benschop on Facebook Messenger:

In agon-mos/src/vdp_protocol.asm. function vdp_protocol_MODE. You read the screen height from the VDP packet into HL, then you store A into the sysvar. Screen height is returned incorrectly in system vars.

Refactor SD card delay 10ms to remove reliance on interrupt

There is no need for this to be running in the background all the time. Just enable around SD card initialisation, and disable once complete.

Acceptance Criteria:

• Rewrite the timer delay code to avoid using interrupts.
• Only use the timer in SD_init when mounting the SD card.

Testing:

• Make sure the timer code is working.

VDU command crashes hard on VDU 23 & VDU 25

1 parameter VDU functions such as CLS seem to be fine but errors in the VDU 23 & VDU 25 (think it's the ;'s) cause the Agon to freeze up such that a warm boot doesn't work and needs to be power cycled either by pulling the plug or pressing the reset button. Sometime it seems that correct VDU 23 & VDU 25 also freeze up too but can't confirm that 100% yet

Add a second serial device

Use the following GPIO pins:

• PC0: TxD1
• PC1: RxD1
• PC2: RTS1
• PC3: CTS1

Acceptance Criteria

• I must be able to enable and disable the peripheral so that I can use those pins for other GPIO purposes
• A MOS API interface for:
  • Enable (set baud rate, control bits, flow control, etc)
  • Disable
  • Send
  • Receive
  • Interrupt handler

Increase baud rate ESP32->EZ80 to 1152000

Increase in main.c
Fix maths overflow bug in init_UART0 (uart.c) to cater for higher baud rates

Bug in C implementations of putch

C implementation of putch (used in C code for writing to the UART) does not wait for CTS (hardware handshaking). This manifested itself when testing the page display mode in MOS - BASIC listings (using serial.asm) would pause fine, *DIR (using the C code) would not.

HT to Lennart Benschop for observing this in the wild.

Improve line editor

HOME takes you to the start of the line
END takes you to the end
If you cursor off the left, it will wrap to the right, and go up a line - DONE
If you cursor off the right, it will wrap to the left, and go down one line - DONE

API call for setting interrupt vectors

As an Agon developer
I want to be able to set and reset interrupt vector calls
So that I can write applications that take full advantage of the eZ80 peripherals

Acceptance Criteria:

• The function must return the previous handler address after setting
• It will be the developer's responsibility to restore the status quo once finished
• No attempts will be made to determine whether the call points to a valid interrupt

Concerns about available stack space for MOS commands

This issue was raised by Reinhard Schu on Facebook:

I have written a stacktest program that runs as a MOS command. Please see the output in the attached screenshot. My init.inc code automatically detects when its running as a MOS command and re-adjusts the SPS to $7FFE. Without this adjustment, if you study the output of my stacktest program, you will see that a MOS command that pushes more than 256 bytes onto the SPS with PUSH and POP instructions in Z80 (16-bit) mode will conflict with the SPL, as the top of both SPL and SPS will be at $08FFFF.

I have written my own init.inc code to correct this, but I would suggest it is best to fix the MOS to set the SPS to $7FFE when spawning a MOS ccommand, otherwise MOS commands could have unpredictable results due to SPS/SPL stack conflict.

Provide HELP command

Please provide a HELP command similar to that of BBC Micro:
HELP module

For example:

*HELP MOS

should display the version of MOS and all available commands. And

*HELP BASIC
should display the version of the installed BASIC

Enhancement: Add native MOS support for a TYPE command

The MOS command MORE is wonderful, but it would be very helpful to have an always available command from the MOS shell to quickly list the contents of a text file.

Implement the low-level FatFS commands in MOS (Stage 1)

Replicate the following C structures in asm:

• FFOBJID - done
• FIL - done
• DIR - done
• FILINFO - done

Add the following methods:

• mos_GETFIL
• mos_FREAD
• mos_FWRITE
• mos_FLSEEK

Implement the following methods:

• ffs_api_fopen - done
• ffs_api_fclose - done
• ffs_api_fread - done
• ffs_api_fwrite - done
• ffs_api_flseek - done
• ffs_api_feof - done
• ffs_api_stat - done

Feature request: sysvar access to the __2nd_jump_table

Can you insert a static sysvar to the __2nd_jump_table? That way ppl would have access to the vectors to change IRQ handlers
I have coded GPIO serial access for my hexload utility, but that currently needs to use a static address from the MOS 1.02 build. It would be great if programs could just retrieve the 2nd_jump_table and access it cleanly from MOS 1.0x onwards.

Access to _set_vector would be ever better, but it's not much code to copy over if we have just the sysvar. Thnx!

Add command history

As an AGON user
I would like the MOS to remember the last few lines line entered
So that I don't have to keep retyping them it

Acceptance Criteria:

• Store a single command
• Accessed by pressing the UP arrow if the buffer is empty

Extend MOS file command line

*DIR - add path parameters
*COPY - copy a file
*MOVE - move a file

mos_fopen returns 0 after bbcbasic exits

Hi Dean,

An ADL=1 binary, written in C with the standard init.asm from the 'Hello World' example, that opens a file using the bare minimum assembly code for mos_fopen, mos_fopen only works when no bbcbasic.bin has been running previously.
After *bye from bbcbasic, mos_fopen just returns 0
Before running bbcbasic, manually, or from the autoexec.txt, mos_fopen returns a valid filehandle.

I'm attaching a minimalistic example that just fopens/fcloses 'autoexec.txt', and does it statically to avoid using the C arg parser. But opening other existing files behave similarly.
fopenbug.zip

I have reverted back to running MOS 1.02/VDP 1.02 and also tried bbcbasic 1.02/1.03/1.04.
Thnx!

Add a *credits command

Acceptance Criteria:

Call from standard shipped autoexec.txt so that it is available on first boot.
Credit all third-party libs for MOS and include the version number.

• FabGL
• FatFS

*BYE command takes a long time to return to the MOS prompt.

When I type the *BYE command in Basic, it takes a long time (sometimes a few seconds, sometimes tens of seconds) before it returns to the MOS prompt. When I type keys while waiting, it seems to make that quicker.

It looks like something is amiss with MOS rather than Basic, as the same thing happens with the BYE command in Forth. They both do RST.L 0.

Turn off LF/CRLF conversion in FatFS string functions

Raised by envenomator on Twitter:

If an 0x0D (\r) is written to a file, the byte 0x0A (\n) is also written.

MOS has no call for writes to binary files

mos_fputc calls f_putch from fatfs, which writes textfiles, not binary files, adding 0x0a at end of lines.
Would it be possible to create an extra mos_fwrite call to handle byte writes for binary files?

Or, if the intention was to transparently write bytes, then this solves the issue for me - old code commented out

void mos_FPUTC(UINT8 fh, char c) {
unsigned int num;
if(fh > 0 && fh <= MOS_maxOpenFiles) {
//f_putc(c, &mosFileObjects[fh - 1].fileObject);
f_write(&mosFileObjects[fh - 1].fileObject, &c, 1, &num); // single byte write
}
}