FreeRTOS on Z80

[Phillip Stevens]

I'm sure most here know FreeRTOS as a preemptive multitasking system for micro-controllers. Its probably one of the best known in the industry.

Here's the Reference Manual for FreeRTOS.

But, while the industry is pushing to low power 32-bit and 64-bit processors, we're pushing on with 8-bit machines.

And FreeRTOS hasn't shown much love for 8-bit machines for some time, so let's pick up that baton for 8-bits...

So I've dredged the swamp of the Interwebs and, out of what I found, built a modern (v10.3.0) release of FreeRTOS for Z80.

At this stage there are only two targets supported, but because target or platform specific code is all in one file, it is pretty easy to support additional targets.

The two targets working are:

• SCZ180 (SC126 & SC130) on RomWBW HBIOS
• YAZ180 running as an application

FreeRTOS is present as a library in z88dk. As a library it can only run in one 64kB memory space, and doesn't support memory banking.

It is going to be useful where you need to manage a number simultaneous of tasks in parallel, rather than being considered an operating system (like FUZIX).

It is fully preemptive, running separate stacks for each Task, and it provides queues, semaphores, and event management for inter-Task communications.

As FreeRTOS is written in C, there are only a few architecture specifics that need to be adjusted, and they're mainly found in the portmacro.h file. These architecture specifics are going to be the same for any Z80 machine.

All the target or platform specifics are in one file FreeRTOSBoardDefs.h, and to add a new target just four macros need to be built...

• configure the Timer and make sure the Timer ISR is always available
• reset / reload the Timer if needed (as on z180)
• manage Task switching to when vTaskSwitchContext() banked in.
• stop the Timer (not really necessary)

I've made some assumptions about how much of the FreeRTOS API should be available, and number of priorities, etc. They're in the FreeRTOSConfig.h file, and can be adjusted (and the library rebuilt and installed) as desired.

If the header files are changed, then this should also be reflected in the z88dk headers, or use your own personal headers if preferred.

There's not a lot of testing been done on this yet, and I'm sure there'll still be things to fix and improve.

But now at least simple applications work fine.

Enjoy,

Phillip

[Marten Feldtmann]

That is cool !

[Wayne Warthen]

Very nice Phillip.  I am thrilled to see RomWBW HBIOS leveraged in this way.

-Wayne

[Phillip Stevens]

Phillip Stevens wrote:

I'm sure most here know FreeRTOS as a preemptive multitasking system for micro-controllers. Its probably one of the best known in the industry.

But, while the industry is pushing to low power 32-bit and 64-bit processors, we're pushing on with 8-bit machines.

And FreeRTOS hasn't shown much love for 8-bit machines for some time, so let's pick up that baton for 8-bits...

FreeRTOS is implemented as a library in z88dk. As a library it can only run in one 64kB memory space, and doesn't support memory banking.

It is going to be useful where you need to manage a number simultaneous of tasks in parallel, rather than being considered an operating system (like FUZIX).

It is fully preemptive, running separate stacks for each Task, and it provides queues, semaphores, and event management for inter-Task communications.

Over the past two weeks Wayne and I have been improving the interactions between freeRTOS and the RomWBW HBIOS implementation, to make the implementation more robust.

And off the back of that work, Wayne has today released the RomWBW v2.9.2 Pre-release 34.

Support is still limited to the SCZ180 platform (SC126, SC130, and also the upcoming SC131), but we've made sure that adding platforms in the future will be very easy.

The whole conversation is recorded at RomWBW Issue #87 if you're masochistically interested in reading the whole story.

But in the interest of your time here's the TL;DR on what was done.

On the freeRTOS side.

• Make sure that the User TPA Bank is selected, before each Tick Increment (which moves Tasks into the Ready List for the next Yield).
• Make sure that the User TPA Bank is selected and ensure that the Stack Pointer is not in the HBIOS Proxy, before each Yield (Task swap based on prioritised Ready List).

On the HBIOS side.

• Move the stack for the HB_INVOKE function to share a bigger free space in buffer, to ensure that Tick Increments can be processed at any time the User TPA bank is selected.
• Bracket the HB_INVOKE function with a mutex to ensure that only one concurrent Task can be "inside" the HBIOS API.
• Bracket the HBX_BNKCPY function with state preserving interrupt management, to ensure the freeRTOS Timer doesn't interrupt during a banked buffer copy.

Whilst these look like small changes, they took quite a few evenings of thought to implement. So I think we're pretty happy with the outcome.

It is only a few Bytes of code in the end, but it makes FreeRTOS very reliable on the SCZ180 hardware.

Because a video is always nice. Here's one showing a SC130 running some Tasks, exercising the HBIOS Disk I/O and the Character I/O.

I'll try to build some further code examples over the next few days.

Enjoy, Phillip & Wayne.

[Phillip Stevens]

Phillip Stevens wrote:

I'm sure most here know FreeRTOS as a preemptive multitasking system for micro-controllers. Its probably one of the best known in the industry.

FreeRTOS is implemented as a library in z88dk. As a library it can only run in one 64kB memory space, and doesn't support memory banking.

It is going to be useful where you need to manage a number simultaneous of tasks in parallel, rather than being considered an operating system (like FUZIX).

It is fully preemptive, running separate stacks for each Task, and it provides queues, semaphores, and event management for inter-Task communications.

Over the past two weeks Wayne and I have been improving the interactions between freeRTOS and the RomWBW HBIOS implementation, to make the implementation more robust.

And off the back of that work, Wayne has today released the RomWBW v2.9.2 Pre-release 34.

Support is still limited to the SCZ180 platform (SC126, SC130, and also the upcoming SC131), but we've made sure that adding platforms in the future will be very easy.

I'll try to build some further code examples over the next few days.

I've built an example based on the standard FreeRTOS common tests.

Compared to other implementation demonstrations, quite a few Tasks are running at once, and our implementation seems very stable.

Integer Math -  4 Tasks

Polled Queue - 2 Tasks

Semaphore - 4 Tasks

Counting Semaphore - 2 Tasks

Making a total of 12 Tasks sharing the processor.

Most of the FreeRTOS API can be exercised with these Tasks, so I'm now more sure that the z88dk build of freeRTOS is working properly.

I've also added the HBIOS torture demo I built to test the HBIOS API. This has two Tasks that hammer the HBIOS API extensively.

By playing with different priorities it is possible to get the system to be unreliable. If you go looking for trouble, it is sure to find you.

Enjoy,

Phillip

[Interocitor Steve]

AWESOME.  I want an rtos for the Interocitor.  I had a few in mind, but I will gladly use anything with a user group.

I am wearing my HW hat now, but would love to use your RTOS port in the future.

=Steve.

On Friday, February 28, 2020 at 9:23:44 PM UTC-5, Phillip Stevens wrote:

I'm sure most here know FreeRTOS as a preemptive multitasking system for micro-controllers. . .

[Phillip Stevens]

Phillip Stevens wrote:

Over the past two weeks Wayne and I have been improving the interactions between freeRTOS and the RomWBW HBIOS implementation, to make the implementation more robust.

And off the back of that work, Wayne has today released the RomWBW v2.9.2 Pre-release 34.

Support is still limited to the SCZ180 platform (SC126, SC130, and also the upcoming SC131), but we've made sure that adding platforms in the future will be very easy.

Just a quick update on SC126, SC130, and SC131, which are all supported by RomWBW.

We decided to remove the special HBIOS MUTEX builds because it was unnecessary to do a special build for just one option.

Now from RomWBW v2.9.2 Pre-release 36, there is a setting (for SC126, SC130, and SC131) which can flipped to TRUE to enable HBIOS mutual exclusion.

Thus protecting HBIOS (which is not re-entrant) from multiple Tasks attempting to use the API simultaneously.

At z88dk we also just updated sdcc to r11556, as this sdcc release just cleaned some long-standing bugs which prevented freeRTOS from compiling.

So if you like to change some freeRTOS configurations, it is best to get the latest nightly for z88dk too.

P.