-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathsys-calls.txt
341 lines (278 loc) · 16.9 KB
/
sys-calls.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
SYS calls in Matrix Brandy
==========================
On RISC OS builds, all host SWIs are available. Additionally, the
Brandy-specific calls which are implemented by Matrix Brandy are also
recognised and are available for use.
A number of SYS calls are supported in Matrix Brandy, some of which are
emulations of the equivalent RISC OS SWIs. Where a RISC OS SWI is emulated,
the SWI number used is the same as that used by RISC OS, in order to allow
code that uses the number rather than the name for performance reasons to run
correctly.
In this document, the parameters listed are labelled as ARM registers as
if the SWI were called in RISC OS.
Where a parameter returns a pointer to a string, it MUST be picked up with a
string variable; picking it up with a numeric variable and attempting to
access the buffer will not work.
OS_xxx
======
OS_WriteC R0: Send (R0 AND &FF) to the VDU stream.
Matrix Brandy extension:
If R1 and R2 are both set to 42, the character is
output to the controlling terminal on the stderr
stream.
OS_Write0: R0: Pointer to NULL-terminated string, to be sent to
the VDU stream.
Matrix Brandy extension:
If R1 and R2 are both set to 42, the string is
output to the controlling terminal on the stderr
stream.
OS_NewLine Sends \r\n (&0D, &0A) to the VDU stream.
OS_ReadC Reads a character from the keyboard, returned in R0.
OS_ReadLine and
OS_ReadLine32 Returns a string input from the keyboard, pointed in R0.
OS_Mouse Returns mouse state.
OS_ReadPalette Read the colour palette. Only R1=16 supported.
OS_ReadModeVariable Read a mode variable into R2.
OS_ReadVduVariables Read VDU variables requested in block pointed in R0
into block pointed in R1. R0 and R1 may point to the
same block.
OS_ReadMonotonicTime Return centisecond timer in R0.
Matrix Brandy extension:
As the centisecond timer is centiseconds since the
start of the instance, the offset from the raw value
is returned in R1.
OS_Plot Executes a PLOT function. Note that this bypasses the
VDU driver so plotting this way will not be picked up
by *SPOOL.
OS_ScreenMode Only R0=0,1,7,8,9,10 are supported.
OS_SWINumberToString Returns SWI string from number.
On RISC OS this is NOT intercepted so it does not
recognise Brandy-specific calls.
OS_SWINumberFromString Returns SWI number from name.
On RISC OS this call is intercepted so we can also
recognise Brandy-specific calls.
OS_WriteI block (SWIs 256-511). Call by number.
Matrix Brandy extension:
If R1 and R2 are both set to 42, the character is
output to the controlling terminal on the stderr
stream.
OS_Byte R0, R1, R2 are A, X and Y.
Calls the OSBYTE system call, see docs/osbyte.txt
OS_Word R0 is A, R1 is the address of the data block.
Only R0=9, 10, 139, 140 are supported.
139 and 140 are specific to Matrix Brandy and
BBCSDL. Details in docs/Mode7.txt
OS_File Calls 0, 6, 7, 8, 12, 14, 16, 19, 24 and 255 only.
Calls 12, 14, 16 and 255 are identical (for now).
Implementation is incomplete.
OS_SetColour Implemented mostly, apart from calls relating to
ECF (which Matrix Brandy does not support), and
the call to read the colour, as this is undocumented
in RISC OS aside from its existence.
ColourTrans_xxx
===============
ColourTrans_SetGCOL
ColourTrans_GCOLToColourNumber
ColourTrans_ColourNumberToGCOL
ColourTrans_SetTextColour
BRANDY-SPECIFIC CALLS
=====================
Brandy_xxx (SWI numbers start &140000)
&140000 Brandy_Version Returns
R0: Major version number
R1: Minor version number
R2: Patchlevel number
R3: Git commit SHA (if available)
R4: Pointer to host OS name string
R5: 1 if SDL build, otherwise 0.
R6: Returns a fixed 64-bit value on 64-bit
hardware (truncated on 32-bit):
&123456789ABCDEF0
R7: 1 if 64-bit build, otherwise 0.
&140001 Brandy_Swap16Palette Returns nothing.
In 16-colour modes, as Flash isn't supported,
this swaps the dimmed colours at 8-15 with the
standard brightness at 0-7. Calling again
switches back. Some other BBC BASIC versions
use 0-7 as dimmed colours.
&140002 Brandy_GetVideoDriver Returns:
R0: Pointer to SDL video driver name string
R1: Length of string in R0
R2: Pointer to screen memory base
R3: Size of screen memory.
R4: Base of MODE 7 frame buffer
R5: SDL surface handle (pointer)
R6: Pointer to SDL_PixelFormat structure of
the display surface.
R7: OS-native window handle
&140003 Brandy_SetFailoverMode R0: Set mode to be selected should chosen screen
mode be unavailable (instead of returning
"Screen mode is unavailable). Set to 255 to
disable.
&140004 Brandy_AccessVideoRAM If R0=0, return pixel value at pixel offset R1
into R2.
If R0 non-zero, write R2 into pixel offset R1.
R1 is pixel offset, so each step of 1 is the
next pixel irrespective of screen mode.
Note this writes directly to the 24bpp frame
buffer so bypasses any screen mode palette or
colour depth limit. The top 8 bits, which are
ignored by SDL, are used to carry the logical
colour number in paletted modes to support
VDU19 palette changing.
&140005 Brandy_INTusesFloat This enables a BB4W/BBCSDL extension that allows
INT() to handle numbers > 2^31-1 by using a
float if the number is out of range for a 32-bit
signed integer.
R0=1 to enable, 0 to disable. Default: disabled.
&140006 Brandy_LegacyIntMaths This allows integer mathematics to be handled in
the way BBC BASIC 1 to 4 on the Acorn 8-bit
machines, and RISC OS ARM BBC BASIC V,
including the rather questionable wrap-around
on integers. RISC OS ARM BBC BASIC VI, BB4W
and BBCSDL do not have this wrap-around issue
and will promote to float when needed.
R0=1 to enable, 0 to disable. Default: disabled.
&140007 Brandy_Hex64 This controls whether Brandy renders and
interprets Base 16 (Hexadecimal) values as
64-bit.
R0=1 to enable, 0 to disable. Default: disabled.
&140008 Brandy_DELisBS Toggles whether the DEL key functions as
backspace (DELETE in old BBC terminology).
R0=1 to enable, 0 to disable.
Default: Enabled on UNIX text-mode builds,
Disabled otherwise.
&140009 Brandy_PseudovarsUnsigned
Only effective on 32-bit hardware. Toggles
whether memory pseudo-variables (e.g. PAGE,
HIMEM etc) return large positive numbers
above &7FFFFFFF.
R0=1 to enable, 0 to disable. Default: disabled.
&14000A Brandy_TekEnabled Only effective on the 'tbrandy' build, ignored
without error on other builds.
This switch enables Tektronix graphics to
be generated for graphics operations, with
particular reference to the Tek emulation
in xterm.
R0=1 to enable, 0 to disable. Default: disabled
R1=simulated baud rate, 0 to run at full speed.
&14000B Brandy_uSleep Calls the OS function usleep(R0).
&14000C Brandy_dlopen Calls the OS function
dlopen(R0,RTLD_NOW|RTLD_GLOBAL).
Handle is returned in R0.
&14000D Brandy_dlcall Locates the symbol in R0, and calls it with
parameters from R1..R9.
&14000E Brandy_MAlloc Allocates memory from system call malloc(R0).
Pointer to base returned in R0.
DEPRECATED, please use DIM HIMEM instead.
&14000F Brandy_Free Frees memory pointed to in R0 from earlier
malloc. Nothing returned.
DEPRECATED, please use DIM HIMEM <var> -1
instead.
&140010 Brandy_BitShift64 This controls whether Brandy calculates bit
shifts in 64-bit space. 32-bit space is used
when disabled as per ARM BBC BASIC VI.
R0=1 to enable, 0 to disable. Default: disabled.
&140011 Brandy_Platform Similar to Brandy_Version, but more focused on
the platform Brandy is running on.
R0: Pointer to host OS name string
R1: Pointer to CPU family string
R2: 64-bit? (1 or 0)
R3: SDL build? (1 or 0)
R4: Machine type (as returned by OSBYTE 0)
R5: "Legacy" INKEY-256 (e.g. &F9 for Linux)
R6: The PID of the current process.
R7: The Parent PID of the current process.
Note: PPID not returned on Windows.
&140012 Brandy_CascadedIFtweak Change behaviour of cascaded IF calls to try
to match the behaviour of Richard Russell's
BBC BASICs. Enabled by default, but can be
disabled to match the Acorn behaviour.
As this affects the parser and tokeniser, if
the block of code has been seen before this
call, then the behaviour won't be changed.
If used, it is recommended this be called at
the top of a program as it affects the way
the tokeniser updates jumps as the program is
scanned upon first execute..
&140013 Brandy_MouseEventExpire Sets the mouse event expiry time in
centiseonds, 0 disables.
With a zero event expiry time, a maximum
event queue length is used (7 events) which
mirrors RISC OS behaviour.
&140014 Brandy_dlgetaddr Fetches the address of the library function
call given in R0, with the library handle
from Brandy_dlopen optionally provided in R1,
and returns the address in R0. If the symbol
isn't found and the X flag is set, R0 contains
-1, else an error is raised.
&140015 Brandy_dlcalladdr Similar to Brandy_dlcall (above), but takes
the address of the symbol in R0 instead of
the symbol name.
&140016 Brandy_Strict Enable/disable strict execution mode (as also
set by command-line -strict/-ignore options).
Default: Disabled if built with DEFAULT_IGNORE
otherwise enabled.
&140017 Brandy_TranslateFNames Enable/disable transparent translation of
filenames between Linux and RISC OS formats.
R0=0: No translation happens.
R0=1: Autodetect on read, translate on write
(OPENUP follows read behaviour)
R0=2: Autodetect on read, no translation on
write, but if translation required on
read this value is changed to 1.
Any other value is ignored.
Return: R0 contains old value.
Default value: 2
&140018 Brandy_MemSet Writes a value to a block of memory.
This call fills the first R1 bytes of the
memory area pointed to by R0 with the constant
byte R2.
&140019 Brandy_AllowLowercase This sets whether or not Brandy accepts
keywords in lowercase. This may also be set
using the '-lck' command line option or the
'lowercase' config file option.
Default: R0=0 (disabled)
RaspberryPi_xxx (SWI numbers start &140100)
-- see also docs/raspi-gpio.txt
&140100 RaspberryPi_GPIOInfo Returns:
R0: 1 if available, 0 otherwise
R1: If available, memory-mapped I/O base.
&140101 RaspberryPi_GetGPIOPortMode
R0 contains GPIO port number
Returns:
R0 contains GPIO port mode:
0: Input
1: Output
2: ALT5
3: ALT4
4: ALT0
5: ALT1
6: ALT2
7: ALT3
&140102 RaspberryPi_SetGPIOPortMode
R0 contains GPIO port number
R1 contains GPIO port mode (as above).
&140103 RaspberryPi_SetGPIOPortPullUpDownMode
R0 contains GPIO port number
R1 contains GPIO Pull-Up/Pull-Down mode:
0: Off
1: Down
2: Up
&140104 RaspberryPi_ReadGPIOPort
R0 contains GPIO port number
Returns:
R0 contains GPIO port state
&140105 RaspberryPi_WriteGPIOPort
R0 contains GPIO port number
R1 contains GPIO port state
A few of the RISC OS GPIO module (SWI base &58F80) are also recognised:
&58FBE GPIO_GetBoard
Returns board model code local to the module in R0,
the board type string in R1
and additionally, local to Brandy, the 32-bit model code from /proc/cpuinfo
into R2.
&58F80 GPIO_ReadData: mapped to RaspberryPi_ReadGPIOPort
&58F81 GPIO_WriteData: mapped to RaspberryPi_WriteGPIOPort
&58F8F GPIO_ReadMode: mapped to RaspberryPi_GetGPIOPortMode
&58F90 GPIO_WriteMode: mapped to RaspberryPi_SetGPIOPortMode