ZXUtils::MultitaskingIO¶ ↑

Asynchronous communication channels between tasks running in parallel with ZX Spectrum's Basic programs.

See Multitasking for more information on tasks.

This class contains Macros and kernel labels for tasks and the kernel code.

                             +----------- find_io_handles ------------+
                   CHANS     v                                        |
+----------+       +----------+  output  +------------+  input handle |
| PRINT #n | ----> | User     | -------> | I/O Buffer | <------> +-------+
| ZX Basic |       | Channel  |          +------------+          | Tasks |
| INKEY$#n | <---- |   Record | <------- | I/O Buffer | <------> +-------+
+----------+       +----------+  input   +------------+  output handle

The ZX Spectrum's I/O channels are indentified by single upper-case letters. There are four system channels: “K”, “S”, “R” and “P”. Channels in order to be used must be “opened” by associating a channel with streams # 0-15. By default streams 0-3 are occupied by the system channels. In ZX Spectrum's Basic there are dedicated OPEN # and CLOSE # statements to associate channels with streams. Unfortunately their usage is limited only to the system channels.

MultitaskingIO provides API to create its own channels and associate them with user streams. Each MultitaskingIO channel represents a pair of I/O Buffers, one for writing and one for reading from the system (full-duplex). The tasks can read or write data to any of the buffers. The most common use-case however is that the system's output provides the input for tasks and vice-versa.

To speed up things tasks are not using streams but rather acquire a direct handle to an I/O Buffer and operate on its data directly by the routines provided by MultitaskingIO::Macros.

Memory map:¶ ↑

                           TaskVarsIO                    | I/O user channel records
 +---------+-------------+-------------+-----------+----------+---+-----------+-------------+--
 | BASIC   | Display and | ZX Printer  | System    | Channel  |$80| ZX Basic  | Tasks' Code |  
 |  ROM    |  Attributes |      Buffer | Variables |     Info |   | Workspace |    and Data |  
 +---------+-------------+-------------+-----------+----------+---+-----------+-------------+--
 ^         ^             ^             ^           ^              ^           ^             ^  
 $0000     $4000         $5B00         $5C00       $5CB6 = CHANS  PROG        RAMTOP  mtio_buffers_bot
                         mtiovars

   |            <-|
 --+--------------+--------------+---------------+--------+--------------+
   | Reserved for | I/O Buffers  | Multitasking  | I/O    | Multitasking |
   |  I/O Buffers |   Data Space |   Stack Space | Kernel |       Kernel |
 --+--------------+--------------+---------------+--------+--------------+
   ^              ^              ^               ^                       ^
mtio_buffers_bot  |              |               |                  P_RAMT
                  buffers_top    tv.stack_bot    tv.stack_end

Multitasking Api¶ ↑

All of the labels and macros exported by the Multitasking kernel are being re-exported by the MultitaskingIO module.

Programs compiled for the Multitasking kernel without the MultitaskingIO will work fine, as the addresses of the Multitasking functions don't change.

ZX Basic API¶ ↑

REM Setup:
REM Initializes multitasking and I/O task variables, makes space for channels.
REM Returns the number of bytes available for new tasks' stacks.
PRINT USR open_io

REM Reset:
REM Returns the number of bytes available for new tasks' stacks.
PRINT USR api

REM Spawns a task:
1 DEF FN m(a,s) = USR api

LET tid = FN m(address,stacksize)

REM Terminates a task:
2 DEF FN t(t) = USR api

REM Returns the number of bytes available for new tasks' stacks after the task is terminated.
PRINT FN t(tid)

REM Returns the number of bytes available for new tasks' stacks.
3 DEF FN f() = USR api

PRINT FN f()

REM Opens or creates a MultitaskingIO channel and assigns a stream # to it:
4 DEF FN o(s,c$)=USR open_io

REM Initializes channel Q and allocates buffers if called for the first time with that letter.
REM Opens channel Q and assigns stream #7 to that channel. Returns previously assigned channel identifier.
PRINT CHR$ FN o(7,"Q")

REM Closes stream #7. Returns previously assigned channel identifier.
PRINT CHR$ FN o(7,"")

REM Wait for I/O data availability.
5 DEF FN w(s,n)=USR wait_io

REM Blocks an execution of a program until at least 3 characters are available to be read from an I/O buffer at stream #7.
LET ReadCharsNo=FN w(7,3): REM ReadCharsNo >= 3

REM Reads 3 characters from I/O channel #7.
LET a$=INKEY$#7+INKEY$#7+INKEY$#7

REM Blocks an execution of a program until at least 5 characters can be written to an I/O buffer at stream #7.
LET WriteCharsNo=FN w(7,-5): REM WriteCharsNo >= 5

REM Sends 5 characters into I/O channel #7.
PRINT #7;"hello";

address

Must be a task's machine code entry point address.

stacksize

Must be an even number of bytes, at least 42.

tid

Must be a number returned from a call to FN m(a,s).

Setup must be invoked once before any other function is used.

Reset can be called to terminate all tasks.

Spawn will report a “4 Out of memory” error if there is not enough room for a task info entry or stack space.

Open will report a “4 Out of memory” error if there is not enough room for I/O buffer data.

“A Invalid argument”, “B Integer out of range”, “F Invalid file name”, “O Invalid stream”, “Q Parameter error” errors may also be reported when arguments are incorrect.

Printing to the stream with the I/O buffer full will report “8 End of file” error.

When reading a stream without any data available an INKEY$# function will return an empty string.

Task API¶ ↑

To communicate with the MultitaskingIO api tasks should obtain a direct handle to the I/O buffer. This is done via one of the kernel functions:

• find_io_handles

• find_input_handle

• find_output_handle

Example:

              # import kernel macros and labels from MultitaskingIO into the "mtio" namespace
import        ZXUtils::MultitaskingIO, :mtio, code: false, macros: true, labels: ZXUtils::MultitaskingIO.kernel_org

              # ...
              # instead of invoking halt, call mtio.task_yield
              call mtio.task_yield

              # to terminate:
              jp   mtio.terminate
              # or when a stack is depleted just:
              ret

              # wait for the channel Q being available
wait_loop     ld   a, "Q".ord
              call mtio.find_io_handles
              jr   Z, got_handles # HL: input handle, DE: output handle
              call mtio.task_yield
              jr   wait_loop

              # read a character, assume HL contains an address of the input handle
              mtio_getc(a, not_ready: :eoc, subroutine: false, mtyield: mtio.task_yield)
              jr   C, got_the_character

              # write a @ character, assume HL contains an address of the output handle
              ld   a, "@".ord
              mtio_putc(a, not_ready: :eoc, subroutine: false, mtyield: mtio.task_yield)
              jr   C, character_was_written

              # read a character, block a task if not available, assume HL contains an address of the input handle
              mtio_getc(a, not_ready: :wait, subroutine: false, mtyield: mtio.task_yield)
              # do something with a character in accumulator

              # wait for data, assume HL contains an address of the input handle
              ld   c, 5 # at least 5 characters
              mtio_wait(:read, c, mtyield: mtio.task_yield)

              # write a small string up to 255 characters, assume HL contains an address of the output handle
              ld   de, hello_world
              ld   a, +hello_world
              mtio_puts(a, subroutine:false, mtyield: mtio.task_yield)
              cp   +hello_world
              jr   Z, written_all_characters
              ...
hello_world   data "Hello world!"