OS SWIs manual
This manual is part of a collection comprising the main public domain programming reference. The other manuals in the series are :
OS The base operating system stuff
Wimp The desktop part of the operating system
InetSWIs Internet based SWIs
InetSocket Internet socket calls
MiscSWIs Miscellaneous SWIs
VDU VDU commands
Toolbox Toolbox
Thanks go to those mentioned in the contributors list.
These manuals are kindly hosted by www.riscos.info
This page gives history and credits.
Notes on how the manual is structured
These are some very incomplete notes on how the manual should be structured. If any part of it isn't then it will eventually be updated, or I'll change this specification. It's mostly here to remind me anyhow.
The major driving principle in these manuals is that they should be free to everyone. This means that anyone capable of running RISC OS 3.1 or higher should be able to use them, providing they have a copy of StrongHelp. It it designed to be a quick reference for programmers. Anything more is a bonus. To be such it should present the information in the most easily readable form. Each page, even indexes, should be completely visible on a Mode 31 (800x600) screen, and the majority should take under ¼ of the screen so that editing and reference is easily possible. Version 2.53 of StrongHelp is assumed for the most part. This means that you may use sprite links if you wish.
Each SWI should be documented in the form :
<title> (<hex swi number>)
#Parent <something>
=><tab> R# =<tab> <contents>
<tab> R# =<tab> <contents>
[etc]
<= R#-R# preserved
R# corrupted
<tab> R# =<tab> <contents>
[etc]
This SWI does x, y and z. Short examples may be given here.
{*}Note:{*} something important.
The input or output parameters may be omitted if none are required. It is assumed that the registers are preserved, but this may be explicitly be stated. Registers should be listed it ascending order, unless a discontinuous range is being given in which case it should appear at the top of the return parameters list.
If a register or other entry may consist of multiple entries it should be listed in a subpage, with a descriptive reference to it as the link. If more than one SWI may use that set of values then the subpage should be a data file in a sensible location (usually the same directory).
The <contents> entry should be a single sentance, with clarification or alternatives in a comma seperated list, and only using brackets to indicate ranges. Where long blocks of alternatives are listed, consider using a table or split lines and use tabbing to align; the former is preferable.
Tables should consist of :
Offset<tab> Meaning
#Line
x<tab> y
[etc]
others<tab> reserved, must be zero
Others may be omitted if not relevant, offsets should be given in decimal, unless otherwise stated on the page. Bit masks are described as 'Meaning if set', and should be inversely true if unset. If this is not the case then a seperate description may be required.
Examples may be included on the page if short enough, but for preference should be on a page of their own. Examples should, if possible, be given in pseudo-code or BASIC. Proficient coders should be able to translate to whatever language they are using easily. Assembly examples should only be used where they are strictly relevant.
For services, upcalls, events, etc the reason code need not be given in the input parameters, but is it is it should be given as a number and followed by "(reason code)" or similar. For most such reasons it would be useful if the hex and decimal values were given. This has not been applied across the manuals.
If PRM references are included they should be and the bottom of the page and of the form :
#Line
See <PRM <manual>, page <page>=>PRM-<manual>:<page>>.
This is to allow for a possible future release of a StrongHelp version of the PRMs. The correct names for manuals will be : PRM-1, PRM-2, PRM-3, PRM-4, PRM-Index, PRM-5, PRM-5a. Subsequent releases of the PRMs will include their release number, eg if Ursula has volumes 1-5, it's manuals would be PRM2-1 to PRM2-5 and PRM2-Index, etc.
When highlighting words it is recommended you use Bold ('{*}') to stress words, Italic ('{/}') to indicate variables, and Code ('{fCode}') to indicate sections of literal text, code or other such text. This has not yet been applied to the entire manual.
Current 'normal' cross-referencable objects are :
Page Contents
swi_dateformat Date format string tokens
swi_errorblock Error block format
swi_bbox Generic bounding box
fsys_ident List of Filing System numbers
fsys_objattr File attribute bits
fsys_loadexec File Load/Exec word meaning
os_mousebuttons Mouse button bit mapping
os_scalefactors Standard scaler block
os_setcolouractions GCOL actions
os_spriteop_area Sprite area block
os_spriteop_ptr Sprite block
buffer_buffers List of buffer numbers
colourtrans_paletteentry Palette entry meaning
colourtrans_pixtrans Pixel translation table format
colourtrans_fixedpoint Fixed point values (like draw_transformunits)
territory_anumbers List of alphabet numbers
territory_numbers List of territory numbers
drawfile_format Drawfile format
drawfile_header Drawfile header
draw_transform Draw transformation matrix block
draw_transformunits Draw transform units (&XXXX.XXXX)
Many thanks to Nicholas Clark for helping develop the style used through out this manual.
OS History v3.00
0 AD
· The name! This is now the OS manual, most of this section should remain pretty static, the other sections, Wimp, Misc and Inet should be updated more regularly than the main operating system (hopefully)
· A large number of new services and other little things added
· Reformatting of some pages more in line with the rest of the manual
· SpriteOps updated to include hex number, and new calls
· Added a few more services
· FileEntry added, incomplete at present; needs FileEntry_Func updating, and FileEntry_GBPB adding
· Removed obsolete '\<=' usage, expanded 'ptr', 'no' and added more descriptions
· Moved some blocks from OS to Wimp as it seems more appropriate.
Next history
OS History v3.02
10 Jan 1998
· KeyV updated with reference to the keyboard ID
· Updates to CD section (Dave Thomas)
· More updates to CD section (Eddie Edwards)
· Moved Service_A7 to InetSWIs as it's more logical; more similar changes may follow.
· Territory module completely documented (J.B.Blaukopf)
· Removed spurious ScreenModes documentation
Previous history Next history
OS History v3.03
22 Jan 1998
· Font routines now completely documented (Nicholas Clark)
· Modifications to various swis (Nicholas Clark)
· FPEmulator, Hourglass_Colours, IIC, MakePSFont, Super documented (Nicholas Clark)
· OS_FSControl 37 fixed, miscellaneous Territory calls modified.
· DrawFile format moved into DrawFile from Draw
· ColourTrans now completely documented, additional vectors added (various)
· Sound SWIs documented (Nicholas Clark)
· Started making some notes on the structure
· Transformation matrix added, along with font 24 for the Sidney font so that we can use the matrix blocks
· Reorganisation of certain parts of the manual, updates to services
· Released on ftp://freenet.barnet.ac.uk/manuals/j.fletcher/
Note: This should have been a beta release, but I needed to release something on the manuals site.
Previous history Next history
OS History v3.04
24 Mar 1998
· Many changes (Econet, Service, Event, Vector, Portable, etc) by Nicholas Clark
· More changes (NetFS, ResourceFS, Squash) by Nicholas Clark
· Finally plucked up courage to run StrongTst across it again. Most of the links should now be valid.
· OS_ConvertBinary/SpacedCardinal/SpacedInteger added.
· Many service calls added, a few other changes.
· Far, far too many changes made to even think about - it's all Nick's doing.
· Updated FileCore entries to be a little more helpful.
· Generic bounding box added, and linked from other entries
· More Byte, Vector, Service, etc calls by Nick.
· DrawFile services added
· Serious note in OS_File about non-return of 'load', and expansion of variable.
· NetPrint documented, updates to various OS SWIs and RPC keyboard diagram added (Nicholas Clark)
· Reformatted, links checked and clean copied for release (phew!)
Previous history Next history
OS History v3.05
25 Mar 1998
· Succombed to public pressure and added PRM references to some pages (OS_Bytes, Services and Vectors at present).
· Spelling corrections and a few minor updates to pages.
· Numerous additions of SWI and reason code numbers to page titles
· Added PRM references to all SWIs. Apologies to those without the manuals. This will aid those with, and when the StrongHelp version becomes available it will help everyone.
· Updated SWIs to include Dynamic Area references, and fixed DrawFile bugs.
· DeviceFS calls updated
· Service_IdentifyDisc fixed (Phil Norman)
· ClaimSWI/ReleaseSWI added (but not documented)
· OS_Memory added, changes to OS_MMUControl (Dave Thomas)
· ScreenBlanker updated, PaletteV updated (James Larcombe)
· Service_FilterManagerInstalled updated
· ColourTrans palette entry data added
· Minor additions, spelling mistakes fixed.
· Changes added (Nicholas Clark)
· Added 'notfound_manual' pages, for StrongHelp 2.60.
· Added 16-bit sound system details (Alex Thoukydides)
· HTML-ification identified some parental problems
Previous history Next history
OS History v3.06
17 May 1999
· Moderator now iain truskett
· FSLock details updated.
· CMOS byte 132 updated to reflect 16-bit audio (David Thomas and Thomas Olsson)
· String termination in OS_ReadUnsigned modified (Daniel Silverstone)
· Virtualise added to OS_DynamicArea and OS_ReadDynamicArea (Alexander Thoukydides)
· various minor differences (Justin Fletcher aka gerph)
· !Configure file added and Draw documentation changed appropriately.
· Services for Freeway added.
· UpCall for Freeway added.
· Example OS_Module SWI handler code bug fixed. (Matthew Phillips)
· IIC_Control extended (Andrew Macfarlane Smith)
· Notfound pages revised.
· Introduction of some SCSI documentation.
· Some Y2K compliance revisions.
· Various minor amendments.
Previous Next history
History for OS v3.07
16 Jun 1999
· CDFS_GiveFileType page changed to mention deprecation.
· OS_DynamicAreaHandler2 error fixed.
· OS_SetMemMapEntries typo fixed.
· OS_ReadDynamicArea reformatted.
· OS_GSTrans flag information updated and corrected.
· OS_UpCall 3 pages reformatted.
· OS_SpriteOp reason code list made more useful by including the versions required for various calls.
· OS_FSControl 13 updated.
· CMOS Byte 222 updated for Wimp 3.99+
· IDEFS added to the filing systems list
· FileCore_Create r5 parameter corrected from 1076 to 1024.
· ColourTrans_ConvertCMYKToRGB exit r2 corrected to 'blue' from 'red'
Previous history Next history
History for OS v3.08
26 Nov 1999
· More RISC OS 4 APIs added
Previous history Next history
History for OS v3.20
21 May 2003
· CD_SCSIUserOp added.
· PCI section added.
· OS_HeapSort32 added.
· OS_SubstituteArgs32 added.
· OS_ReadLine32 added.
· Lots of occurrences of 'recieved' corrected.
· Podule_ReadInfo and Podule_SetSpeed added at last!
· SharedCLibrary new 32 bit SWIs added.
· Printer types expanded.
· Vector list expanded.
· FileCore_Features and FileCore_DiscOp64 added.
· FPEmulator contexts details added.
· Extra Service Calls added to table.
· UCS FontManager details added.
· SharedSound updated.
· Draw module updated.
· Other SWIs added, but don't have details of these yet (so you can't click on them)
· Made 32 bit compatible (!)
· Moderator now Christian Ludlam
Previous history Next history
History for OS v3.25
27 Jun 2003
· SCSI overhauled. Added SCSISoft driver details.
· Some typos corrected, version numbers standardised.
· IOCtl calls detailed.
· Some UpCalls added.
Previous history Next history
History for OS v3.26
21 Jul 2003
· Module MessageTrans word is present from RISC OS 3.60, not 3.50.
· Added details of HAL calls. (Steve Revill)
· Corrections to DOSFS section
Previous history Next history
History for OS v3.27
28 Jul 2003
· Corrections to DOSFS section
· Corrected OS_SpriteOp plot actions
· Updated Font_ReadDefn.
Previous history Next history
History for OS v3.28
6 September 2003
· Corrections to Portable BMU event (Justin Fletcher)
· Documented Buffer_InternalInfo
· Some grammatical changes
Previous history Next history
History for OS v3.29
06 January 2004
· Updated Service_International
· Updated OS_Byte 202
· Updated OS_ClaimDeviceVector
· Updated DeviceFS entry 0
· Updated CMOS RAM bytes
· Some grammatical changes
Previous history Next history
History for OS v3.30
29 June 2004
· Updated Territory and Alphabet numbers.
· Some grammatical changes and formatting improvements.
· Corrected FileCore_DiscOp64 SWI number (Marco Baye)
· Updated DeviceFS special field validation string.
Previous history Next history
History for OS v3.31
18 November 2004
· Corrected R1 in Service 6C (Justin Fletcher).
· Added RISC OS 3.6's 64 bit FSEntry_Func and ImageEntry_Func calls.
· Added some notes on what the 'image file extensions' flag means in filing system information blocks (Justin Fletcher).
· Corrected R1 in Sound_QSchedule, and corrected Sound_QDispatch to Sound_QSDispatch (Justin Fletcher).
· Corrected register numbers in Font_CacheAddr.
· Updated Territory numbers.
· Updated Alphabet numbers, with their encodings standards.
· Corrected exit parameters in ADFS_IDEUserOp (Andrew Hill).
Previous history Next history
History for OS v3.32
7 January 2006
· Updated UpCalls and added PRM references (Justin Fletcher).
· Added details of the page blocks and service calls issued by OS_DynamicArea.
· Added OS_ResyncTime.
· Updated Printer drivers to show RISC OS 3.6's pre-scanning (Maarten Bezemer)
· Updated the flags to ColourTrans_SelectTable (Justin Fletcher)
· Updated OS_ReadSysInfo 6 (Justin Fletcher)
· Updated KeyV reason code 0.
· Added PointerV (Theo Markettos)
· Added OS_ClaimOSSWI etc (Theo Markettos)
· Added Event 21 (Theo Markettos)
· Corrected CMOS byte 24 (Justin Fletcher)
· Marked OS_Control, OS_SetEnv, OS_CallBack, OS_BreakCtrl and OS_UnusedSWI as obsolete but reinstated them to the front index. (Sprow)
· Resorted the OS_ SWIs alphabetically. (Sprow)
· Updated OS_WriteS, OS_Write0 and OS_WriteN to reflect the kernel's unvectored approach. (Sprow)
· An assortment of small typos in OS_ SWIs fixed. (Sprow)
· Added the remaining missing OS_ SWIs to the index page, though some have never been let into the wild. (Sprow)
Previous history Next history
History for OS v3.33
30 November 2007
· Corrected Draw_TransformPath when R1 is 0 on input. (Justin Fletcher)
· OS_ReadSysInfo 1 returns configured screen mode, not current. (Justin Fletcher)
· Updated OS_ReadSysInfo 8 platform types. (David Pitt)
· Corrected and updated OS_SetColour.
· Added OS_MMUControl 1 bit 28. (James Peacock)
· Updated PaletteV
· Corrected Service_WimpSpritesMoved PRM reference
· Corrected registers in ColourTrans_ConvertDeviceColour
· Added more bits to OS_PlatformFeatures 0
· Added note about R9 from Usenet comments by Ben Avison for module SWI handlers
Previous history Next history
History for OS v3.34
18 May 2010
· Added bits 5-10 to OS_PlatformFeatures 0 (Sprow)
· Added note about R9 from Usenet comments by Ben Avison for module SWI handlers (Sprow)
· Lots of typing and grammatical errors fixed (Sprow)
Previous history Next history
History for OS v3.35
21 Jul 2012
· UnthreadV listed in vectors
· Extensions and clarifications to Territory manager's timezone handling
· Country lookup for ISO3166-1 added
· Podule manager read info bits clarified
· Tile sprite scaled documented
· Operation of OS_SpriteOp 15 detailed when in a different mode
· OS_ReadSysInfo allocations expanded
· Added bits 15-20 to OS_PlatformFeatures 0
· Controller types for OS_Memory 8 expanded
· Availability of subreasons to OS_FSControl documented
· JPEG_FileInfo and JPEG_Info flags expanded
· FileCore disc record extended for big discs with long names
· Lots of typing and grammatical errors fixed
Previous history Next history
History for OS v3.36
05 Apr 2014
· Added OS_NVMemory
· Lots of typing and grammatical errors fixed
· VIDC type 3 mode parameter list added to Service_ModeExtension
· ADFS_SectorDiscOp and SCSIFS_SectorDiscOp renamed to match reality
· OS_ChangeDynamicArea area number -1 marked as 3.50 or later
· FileCore_MiscOp7 return register corrected
· FileCore_Create flag bit 11 detailed
· OS_Hardware subreasons 2 to 5 now covered
· Bit definitions for CMOS byte 140 corrected and extended
· Added notes about alignment requirements in the module header
· OS_IICOp defined
· Added section for SDFS
· Added section for InverseTable
· Linked DDEUtils from Wimp manual
· Added section for RTSupport
Previous history Next history
History for OS v3.37
20 Jan 2016
· Noted that OS_File 20 and friends can return -1 for untyped files
· Lots of typing and grammatical errors fixed
· OS_Byte 128 now includes details of its ADVAL usage too
· OS_Byte 121 has the Windows logo and menu keys shown on the key layout
· RTC page added, though these SWIs are for internal use only
· Removed the note about filetype F95 automatically flushing the I cache, this was the intent, but Acorn Application Note 295 specifically states that it was not implemented - and still isn't
· Added OS_SerialOp 10
· Added DMA_AllocateLogicalChannels
· Added OS_ReadSysInfo subreasons 11 to 14 inclusive
· Added OS_DynamicArea subreason 20
· Added OS_PlatformFeatures subreason 32
· VDU variables 192/256/257 documented
· Econet machine peek values &F/&FFF8/&FFF9 added to table
· Added Econet_NetworkParameters, Econet_HardwareAddresses, Econet_EnumerateMap and Econet_InetRxDirect
· Rephrased OS_SpriteOp 9 to only write the area block entries that the SWI doesn't itself write for you
· Monitor type list expanded
· FSEntry Args 11 for IOCtl added
· CompressJPEG_Comment added
· Portable_ReadSensor added
· Broken links to PC in OS_IntOn and OS_IntOff pointed at PSR page
· Corrected CD_LastError as it does not return anything in R7
Previous history Next history
History for OS v3.38
09 Nov 2016
· Listed SeriousErrorV as vector &2C
· BlendTable's SWIs documented
· Lots of typing and grammatical errors fixed
· Added ScreenBlanker_Control subreason 5
· Added OS_PlatformFeatures subreason 33
· Added OS_PlatformFeatures subreason 0 extra flag bits
· Territory_Collate flags bit 2 documented
· Changed the example in OS_EnterOS to be 26/32 bit neutral, or prefer OS_LeaveOS
· Latin10 (also known as alphabet 116) listed
· Notes about Unicode handling for Font_CacheAddr and Font_CharBBox added
· Fleshed out Service_Hardware
· Added SoundCtrl SWIs
· Added HAL entry 113
· Added USBDriver SWIs and corrected USB service call block speeds
· Removed 3rd party module Audio as it exists in MiscSWIs manual too
· Added Service_RTCSynchronised and Service_TimezoneChanged
· Expanded the list of error generators
Previous history Next history
History for OS v3.39
12 Jul 2018
· OS_Module subreason 21 added
· Lots of typing and grammatical errors fixed
· Added Wimp_ClaimFreeMemory and Wimp_SetPointerShape to list of deprecated SWIs
· Added OS_PlatformFeatures subreason 35
· Added Service_IIC
· Added ScreenModes_Features
· Extra FS info word bit 4 reserved
· OS_ConvertVariform type 15 added for UUID numbers
· Added SCSIFS_Partitions
· Copied warning about same mode from OS_SpriteOp 34 to 28.
· Moved SeriousErrorV to vector &2D following the discovery of an allocations clash with RISC OS Select
· Type 15 and bit 31 of Sprite Type described
· Relationship between ImageEntry_Args 9 and ImageEntry_Close, FSEntry_Args 9 and FSEntry_Close made
Previous history Next history
History for OS v3.40
14 May 2021
· Service call cache alignment recommendation removed (Martin Avison)
· More OS_Memory subreasons added
· Corrected PCI_ReadInfo item 15 & 16 mixup
· OS_Module 21, 22 and 24 added
· Filled in service calls &94, &A5, &A6
· Expanded the list of machine types for OS_Byte 0 and identifiers for OS_Byte 129.
· Corrected sense of Sound_Mode 0
· Page access flags clarified
· IDE user operation parameter block documented
· Missing OS_Word 7 (SOUND) added
· Portable_ReadFeatures added
· FSLock_Status and FSLock_ChangeStatus added from PRM 5a
· Top level CompressPNG, VFPSupport, VideoOverlay SWIs listed
· Service calls &E3 and &E4 for 64 bit DMA added
· Colour Mapping Descriptors, available for some transformed sprite plotting, are now described
Previous history
[sh-index] Back to list of manuals
|
| |
