OSWORD

Miscellaneous actions with a control block

Specification

6502	Z80	6809	PDP11	80x86	32016	ARM	RISC-V	On entry:	On exit:
A	A	A	R0	AL	R1	R0	A0	= function code	undefined
XY	HL	X	R1	BX	R2	R1	A1	=>control block	undefined, control block updated
Y	H	Y	R2	BH	R3	R2	A2		OSWORD &00: returned length
Control block for calls>&7F
&00	Length of sent control block
&01	Length of received control block
&02...	Any other parameters

OSWORD &00 is the only call that is allowed to return data in registers. All other calls return data in the control block.

OSWORD calls with numbers &15-&7F must only have a maximum of 16 bytes in the control block. OSWORD calls with numbers greater than &7F must contain the number of parameters to send in the first byte of the parameter block, and the number of parameters to receive in the second byte of the parameter block, inclusive of the first two bytes. There are some calls that break this and will not work in all cases.

While it is not enforced by the API, the convention for high-numbered OSWORDs is for the control block contents to be:

• XY?0: length of sent block (required, &02-&7F)
• XY?1: length of received block (required, &02-&7F)
• XY?2: action
• XY?3: result, set to zero when calling
• XY!4 onwards: parameter data

Then calls are made with code along the lines of:

• !XY%=&2008:XY%?2=6:XY%!4=data:CALL OSWORD:result=XY%?3

OSWORD calls with numbers &E0 to &FF are "available for use by the user" and are passed directly to USERV on the 6502 I/O processor. This makes them easier to implement as only USERV needs to be hooked into instead of WORDV, and &F0/&F1 is already prepared pointing at the control block.

Calling from BBC BASIC

• INPUT calls OSWORD &00
• =TIME calls OSWORD &01
• TIME= calls OSWORD &02
• SOUND calls OSWORD &07
• ENVELOPE calls OSWORD &08
• =POINT calls OSWORD &09
• =TIME$ calls OSWORD &0E
• TIME$= calls OSWORD &0F

Entry points

• BBC BASIC Entry Address: &FFF1
• 6502 Entry Address: &FFF1, vectors via &020C
• Z80 Entry Address: &FFF1, vectors via &FFF2
• 6809 Entry Address: &FFF1, vectors via &FFF2
• 80x86 Entry Address: INT &4A, vectors via &0000:0128
• 32000 Entry Address: SVC &07
• PDP11 Entry Address: EMT 3, vector &03
• ARM Entry Address: SWI &07 "OS_Word", vector &07
• RISC-V Entry Address: ECALL &AC0003

Bugs in implementations

Some ROMs OSWORD handlers have flaws that either cause their OSWORDs to not work properly, or cause other OSWORDs to not work properly. Of note are the following.

DFS 0.90

DFS 0.90 traps all' OSWORDs above &7F and treat them as OSWORD &7D due to the omission of a BMI exit instruction. This means that any high numbered OSWORD in any other ROM will fail to execute if it is in a lower ROM than DFS, and instead it attempts to read the disk.

DumpOut

DumpOut 3's teletext pixel reading OSWORDs use high numbered calls but without the correct header, meaning they fail on any second processor system or similar.

Morley RAMdisk

Uses a high numbered OSWORD without the correct header, so cannot be used from a second processor. The call is a data-transfer call and also only uses a 16-bit address, so cannot transfer across the Tube.

Calling over the Tube

As mentioned above, OSWORD calls have a defined structure to be passed over the Tube. Calls with numbers greater than &7F must contain the number of parameters to send and receive. The Client's OSWORD handler will wait for the Host to reply to fill in the returned control block.

If the caller on the client specifies zero bytes to return, then the Client's OSWORD handler will not wait for a reply and return immediately to the caller. With appropriate coding this can be done deliberately to approach asynchronous processing by both sides of the Tube. The Client will return to the caller without waiting for the OSWORD call to finish, the Host will take as much time as it needs to complete the OSWORD call then return to the Tube polling loop.

The Client and Host will next synchronise the next time the Client requests a Tube action - that is, the next time a Tube MOS API call is made. Essentially, the "wait until Host has finished" portion is defered until the start of the next API call. See StarDot thread.

Maximum block size

The Tube specification specifies that the OSWORD control block can be between &00 (0) and &80 (128) bytes long. Some Tube Clients incorrectly deal with a length of &80, and the Host has no space for a control block longer than &80 bytes, so it is recommended to only ever use a maximum of &7F bytes.

See Also

• OSWORD Index
• StarDot thread: How to tell if Tube transfer finished
• http://mdfs.net/Docs/Comp/BBC/Oswords
• http://mdfs.net/Docs/Comp/BBC/Osword

References

Jgharston 17:03, 6 November 2009 (UTC) Jgharston (talk) 00:10, 13 May 2020 (CEST) Jgharston (talk) 18:37, 29 July 2020 (CEST)