

 JOYCE for PCW programmers

JOYCE makes the following special opcodes available to Z80
programs. Some functions may only be present in certain
versions; in this case, a version number in brackets, such
as (v1.28+) will show the minimum version that supports
this call. If so, programs must first check that the JOYCE
version number is greater than or equal to the number shown.

 ED FD: Replace BIOS function

If this opcode is executed at 0FC4Eh, reads the PC's real-time
clock and sets the time fields of the SCB. Thus the BIOS
"TIME" jump can be replaced by 0EDh 0FDh 0C9h. This is done
by RTC.COM. 

(v1.28+) Similarly, this can be inserted at 0FC0Fh (LIST)
and 0FC2Dh (LISTST) to capture printing - CENPORT.COM does
this.

In ANNE, the same instruction sequence is inserted automatically
into the Rosanne BIOS jumpblock by the 'Rosanne Acceleration'
menu.

In the future, other functions may be replaced in this way.

 ED FE: JOYCE API. 

This is the main entry point for JOYCE functions. What function
is executed is determined by the A register.

 A=0: Test for JOYCE. 

Returns A=0FFh, HL=JOYCE version number (packed BCD). If
A is not 0 and not 0FFh, then JOYCE has been changed in
a way that would break existing programs.

 A=1: Boot. 

Enter with B = boot disc number (bootb.dsk). Reads the first
sector and jumps to it. Only returns if the disc was not
bootable. 

 A=2: Set screen colours. 

Enter with BCD = RGB for "white", EHL = RGB for "black".

 A=3: FID_D_LOGIN for JOYCEDRV.FID

Parameters and results as for the corresponding Z80 routine.

 A=4: FID_D_READ for JOYCEDRV.FID

Parameters and results as for the corresponding Z80 routine.

 A=5: FID_D_WRITE for JOYCEDRV.FID

Parameters and results as for the corresponding Z80 routine.

 A=6: FID_D_FLUSH for JOYCEDRV.FID

Parameters and results as for the corresponding Z80 routine.

 A=7: FID_EMS helper for JOYCEDRV.FID 

Enter with:

BC= FID flags. If C=0FFh, the FID only supports MYZ80-format
  hard drives.

D= reason for call:

  0: Drive successfully added (drive number in E).

  1: Drive not added - no memory available

  2: Drive not added - all drive letters in use

  3: Incorrect FID environment - JOYCEDRV cannot run.

  4: Initialise - this is the first call made to this function
    by JOYCEDRV.FID.

HL= address of message buffer; messages can be copied to
  here by JOYCE.

Returns:

A=0 Return with carry clear and message at HL.

A=1 Return with carry set and message at HL.

A=2 Attempt to add a drive. B=drive number; HL IX IY hold
  parameters for the SVC_D_HOOK routine.

 A=8: Save JOYCE settings.

 A=9: Set/Get current LPT port.

(DOS only) This call does not have any effect in JOYCE 1.9.0+.
In earlier versions, it switches to the LPT port indicated
by DE, and returns the previous port number in HL.. DE=0,1,2
for LPT1, LPT2, LPT3; or 0FFFFh to return current assignment
in HL.

 A=10: Operations on host filesystem files. 

The operations are selected using the C register:

C=0Fh: Open existing file for read/write. DE->pathname
  (0 terminated). Returns HL=handle or 0 if failed.

C=10h: Close file. DE=handle. Returns HL=0 if failed, 1
  if OK.

C=14h: Read byte from open file. DE=handle. Returns byte
  in B; HL=0 if end of file, 1 if OK.

C=15h: Write a byte to open file. DE=handle, B=byte. Returns
  HL=0 if failed, 1 if OK.

C=16h: Create new file for read/write, DE->name (0 terminated).
  Returns HL=0 if failed, file handle if succeeded.

C=69h: Get the local time from the PC clock. DE->time buffer
  (in CP/M datestamp format). Returns A=BCD seconds, and
  buffer filled.

C=91h: Expand filename with wildcards.

  DE-> ambiguous filename, 0-terminated.

  HL-> result buffer

  B= which file (0=first, 1=second...)

  Returns HL=0 if not found, 1 if found. 

  First 11 bytes of buffer hold filename in FCB form

  Remainder of buffer holds ASCIIZ filename with path

 A=11: (v1.10+) Screen operations 

The subfunction to perform is given in the C register:

0 Select standard emulated PCW screen.

1 Select 800x600x256 screen.

2 Write character in E to the 800x600 screen.

3 Write status line character in E to the 800x600 screen.

4 (v1.20+) Execute a GSX call. DE->GSX PB

5 FID_EMS helper for VGA.FID. Expands an error number in
  D to a message at HL. Error numbers are:

  0 OK.

  1 Device table full

  2 Attempt to load VGA.FID twice

  3 CP/M environment is not compatible.

6 (v1.20+) Get capabilities bitmap for screen into HL. 

  Bit 0 set if 800x600 mode is possible. 

  Bit 1 set if GSX is possible (currently it is only
    possible in the DOS version (pre v1.9.0)).

  Bit 2 set if LIOS is possible.

  Other bits of HL, DE BC IX IY all zero (reserved)

  For versions < 1.10, none of these is possible.

  For versions < 1.20, 800x600 mode (only) is possible.

 A=12: (v1.12+) Keyboard operations

The subfunction is given by C:

0: Get mapping for key DE, into HL.

1: Set mapping for key DE, in HL.

2: Set mapping for <DE> keys, at (IX). Each mapping is
  4 bytes: 

DW de_value

DW hl_value

In each case, the "de_value"
is the SDL key number (see SDL_keysym.h). The low byte of
the "hl_value" is the offset of the byte
corresponding to the key, minus 0FFF0h (so it will be 0-16;
0-15 for PCW keys and 16 for JOYCE special functions). The
high byte of the "hl_value"
is the mask of bits to set/clear in that byte.

 A=13: (v1.21-v1.36) Serial port operations

This function is a stub in v1.9.0+; serial comms should instead
go via the emulated CPS8256. All the subfunctions may still
be called, but they will either be no-ops or return dummy
values.

C = subfunction:

0: Reset buffers

1: Set handshaking lines. E=lines:

  bit 0 => DTR

  bit 1 => RTS

  bit 2 => USER

  bit 4 => LOOPBACK

2: Set Baud rate & stop bits

  HL= encoded baud rate.

   1:50     2:75     3:110    4:134    5:150

   6:300    7:600    8:1200   9:1800  10:2400

  11:3600  12:4800  13:7200  14:9600

  15:19200 16:14400 17:28800 18:33600

  19:38400 20:57600 21:115200

  E= settings:

    bit 0 set for 8-bits, reset for 7

    bit 1 = 1

    bit 2 set for 2 stop bits, reset for 1

    bit 3 set if parity, else 0

    bit 4 set if parity even, clear if odd

3: Character input status. Returns A=0 if no character
  available, 1 if there is.

4: Poll for character, return it in A (A=0 if none)

5: Character output status. Returns A=0 if no, 1 if yes

6: Output character in E

7: FID_EMS helper for COM port FID

8: Switch to using COM port no. E

9: Get COM port no. into A

 A=14: (v1.22+) FID_D_MESSAGE for JOYCEDRV.FID

All parameters and results the same as for the corresponding
Z80 routine.

 A=15: (v1.22+) Call the Logo I/O system.

 E = LIOS function number; SP->parameters. Results returned
  in HL 

 E=0FFh to initialise, SP->DW address of info area, HL=address
  of message area. Returns HL=0 if error, 1 if OK

 A=16: (v1.22+) Parse the boot list (joycebt.xml).

B=number of boot disc (0-9, or 0FFh). HL->16-byte buffer
for name. 

Returns A=1 if entry exists, else 0.

(v1.9.0+) If B = 0FFh, special function in C. Returns A=1
if OK, A=0 if function not supported. Special function is:

0 Choose boot disc using JOYCE menus, not Z80 code. 

1 Display helpscreen. 

This function is present in ANNE (v2.1.2+) but if B=0FFh
it always returns A=0.

 A=0FCh: (v1.30+) BDOS filter for REDIR.COM and its programs. 

Entered with:

 Carry set. 

 C = BDOS function 

 DE = BDOS parameter 

 HL = address of REDIR.RSX in memory.

Returns Carry set to continue BDOS call, Carry clear to return
to caller.

 A=0FDh: (v1.27+) Poll the mouse

If an automatic mouse patch has been applied, this will update
the correct memory locations with the mouse coordinates
and button status. If no such patch has been applied, nothing
happens.

 A=0FEh: Set / Get timing parameters.

This allows the timing of JOYCE functions to be adjusted.

A:=Screen refresh rate (900 / Hz value).

HL=Number of Z80 cycles that should be executed every \frac{1}{900}of
a second. 

C = if nonzero, new refresh rate (900 / Hz).

DE = if nonzero, new number of Z80 cycles to execute every
\frac{1}{900}of a second. This changes the ratio between
the speed of the processor and the speed of the PCW, rather
than the overall speed.

Since JOYCE v2.x has automatic speed regulation, it should
not be necessary to alter these figures from program code.

 ED FF: (v2.1.2+) Stop emulation.

This opcode causes the emulated Z80 to stop. In normal use,
it will cause the emulator to shut down instantly without
asking for confirmation.

It is also used by the emulators if a native code function
needs to call a Z80 function (JOYCE does not do this at
the moment, but ANNE does). At the end of the Z80 function,
the ED FF opcode will be executed to return to native code.
