The WinSupport module provides a number of SWIs (SoftWare Interrupts). The module has got an official SWI number from Acorn. The module is viewed as an operating system extension and has the SWI chunk number is &43EC0 and the SWI prefix of "WinSupport"
SWI: WinSupport_Lock (&43EC0)
Use: Identical action to *command of same name
On Entry: -
On Exit: -
Processor mode: SVC
Re-entrancy: Undefined (unlikely to happen in any case)
10: Minimise task's memory requirement as much as possible
Re-entrancy: These SWI's are re-entrant as long as they are re-entered using a different heap pointer. Use of the SWI's in IRQ mode is possible as long as IRQ interrupts are disabled during the call and that the calls that in turn return or claim wimp memory are NEVER used. (if they aren't an interrupt can occur while in a heap manager SWI's, in this scenario, the heap manager would propably pick up the error before it got to exception stage, but your interrupt handler would probably be rendered useless). As SWI's should NEVER be used in FIQ mode, this obviously rules out the heap manger.
SWI WinSupport_FlexHeap (rc. 0 - Initialise heap)
On Entry: r0: Reason Code (0)
Bit 8 set: Initialise heap memory to zero
r1: Pointer to memory to be claimed
r3: Size of heap or r3=-1 for auto size
r1: Undefined
r2: End of code (r2>&8000)
r4: Size of fixed variable and anchor point area
r5: Size of 'Stack' block (fixed - 0 for none)
On Exit: r0 & r2-r3 Preserved
r1: Address of start of heap (if not set already)
r4: Address of variable/Anchor area
r5: Address of Heap block
Re-entrancy: See above
Errors: Address Range invalid. (memory specified possibly doesn't exist). Shouldn't occur when using automatic slot size calculation.
Not a multiple of eight. (slot size must be a multiple of eight). Shouldn't occur when using automatic slot size calculation.
Not enough memory to define heap headers. (Total heap size smaller than sizes of header, var/anchor area and stack area). If using automatic slot calculation, try increasing minimum slot size.
Notes: If the size of the heap is not a multiple of eight, it will be rouded down to the next multiple. Always store r1 on return somewhere, it is the pointer to the base of the heap and is needed for all heap manager calls. In future versions of the heap manager, the base of the heap might be rounded up to a multiple of sixteen to speed the operation up slightly (Crossing a sixteen bytes boundary when loading a lot of memory can slow things down by a small amount). By aligning to sixteen bytes, there is a 50/50 chance of a chunk being on the boundary
SWI WinSupport_FlexHeap (rc. 1 - Describe heap)
On Entry: r0: Reason code (1)
r1: Pointer to heap
On Exit: r0-r1 Preserved
r2: Largest block free - Same as r3
r3: Total memory free
r4: Size of Variable/Anchor area
r5: Stack block size
r6: Memory awaiting return
Errors: Only simple heap validation errors described above.
On Entry: r0: Reason Code (2) (Bit 8 set: Expand Slot if necessary)
r1: Heap pointer
r3: Size of block required
r4: Anchor offset
ON Exit: r0-r1: Preserved
r2: Address of block
r3-r4: Preserved
Errors: Not a multiple of eight.
No memory to expand heap (when heap expansion is used due to lack of room)
Notes: The heap manager doesn't keep track of allocated anchor points. If a claimed anchor point is reused when it still points to a block, you will have completely screwed up your heap! The call will be allowed but the next call that validates the heap won't be, so take care. This one may be sorted out in the next version.
Any extra memory that was borrowed from the WIMP (Bit 8 set on entry) is returned by free block and resize block (with negative change).
On Entry: r0: Reason code (4) (Bit 8: Return/claim memory)
r1: Heap Pointer
r2: Block Pointer
r3: Size change (negative for release, positive for claim)
On Exit: r0-r3: Preserved
Errors: Invalid heap pointer, invalid heap, invalid heap block, no memory to expand heap (bit 8 clear and not enough memory), unable to expand heap (bit 8 set, not memory in Wimp 'free' slot), Not a multiple of eight. You can't reduce size to zero. Negative change bigger that heap block.
Notes: Bit 8 set enables automatic claim/release. The M.P.R. Value is altered accordingly. See claim/release for more info
At the moment, you cannot shrink a block to zero (release it completely). I consider this to be an advantage rather than a disadvantage, I think it is unlikely that you would ever need to do it. ie. it would only happen due to error. Obviously, heap blocks cannot assume negative sizes!
Unlike the Acorn heap manager, the block stays put, but everything after it move so read their anchors points again.
SWI WinSupport_FlexHeap (rc. 5 - Resize heap)
On Entry: r0: Reason code (5) (Bit 8: Return/claim memory)
r1: Heap Pointer
r3: Size change (negative for release, positive for claim)
On Exit: r0-r1,r2: Preserved
Errors: Invalid heap, Invalid heap pointer, no memory to expand heap, Heap cannot contract this far (not enough free space in heap)
Notes: If bit 8 is set, memory is claimed or release (dependant on r3 on entry). If bit 8 is clear, the heap manager assumes you have got some memory for it to expand into. As it is not checked, you could get an address exception or data abort. Again, obviously, you cannot contract the heap below the header block, or smaller than the top of the heap (above the blocks).
Errors: Heap invalid, Heap pointer invalid (only on some operations)
Notes: Three info numbers are supported at present. If you've got a suggestion for other heap info you need to know, please let me know.....
SWI WinSupport_FlexHeap (rc. 8 Compact heap)
On Entry: r0: Reason code (8)
r1: Heap pointer
On Exit: r0-r1: Preserved
Errors: Invalid heap, Invalid heap pointer
Notes: This SWI forces heap compaction, the only reason I can see for this is to save processor time in long processing. (Call a while before). As compaction is forced for any heap manager SWIs that resizes the heap or heap block, therefore, whenever bit 8 is set, I cannot see much use for it. Well anyway it's here if you want it.........
SWI WinSupport_FlexHeap (rc. 9 Process wimp slot size message)
On Entry: r0: Reason code (9)
r1: Pointer to block returned from Wimp_Poll
r2: Heap Pointer
r3: Task Handle
On Exit: r0-r3: Preserved
Errors: No errors will be returned from this SWI, if errors do occur, they are just suppressed and the message gets acknowledged but not processed.
Notes: Of course only call this SWI if it is a SetSlot message (&400C5). If it is this message, just call the SWI and then return to your polling loop on return. The SWI compacts the heap, then either claims more memory or releases memory as necessary. The applications task manager slot will become a red one (user dragable).
Notes: This SWI will simply minimise the size of the heap by compacting it and automatically returning memory to the Wimp. The use of this is that minimising memory in the task manager can be difficult
SWI WinSupport_Debug (&43EC3)
This SWI provides debug code that may be called from your code. It is generally best to put the routine on the bottom of the icon bar memu. Again, just call this SWI
The important addresses in the heap are listed and a *Command prompt provided. Just press return on an empty prompt to end. From my experience, this the the best way to debug wimp applications.
Watch what you type on the prompt, anyting that loads another application or starts another task, will take your task's domain (ie quit it automatically).
without return.
On Entry: r1: Base of heap
r2: Buffer (256 bytes long or more, The Poll block is fine)
On Exit: r1-r2 Preserved
SWI WinSupport_MemMove (&43EC4)
Use fast memory move routines employed in heap.
On Entry: r1: Source block
r2: Destination block (-1 to read address of negative mem routine)
r3: Length of block (-1 to read addess of positive mem routine)
On Exit: r1-r3: Preserved
if r2=-1, address of routine
if r3=-1, address of routine
Errors: None
Notes: Uses extremely fast memory move routine, moves in multiples of 40 bytes (providing there are 40) and then finds the most economical combination of moves for the rest (32,24,16,8,4,3,2,1 in fact). These are in fact the routines used in the heap for compaction (negative) and block expand (positive) and they have been optimised considerably. Ratio: for 240 bytes/31 Instrctions for large quantities. Progressively lower ratios for smaller quantities. Best used for 40+ bytes although they are reasonably efficient for smaller quantities. Address of routines: These are provided for programmers who need fast memory move many times (more than two) in a routine, saving the accumulated effect of calling the SWI handler a few times. Read address at the beginning of the routine and put somewhere safe. Call as necessary. They work in any processor mode and preserve all registers. Entry to both routines is identical but the effect is very different!!!!
On Entry: r0: Number of bytes to move. NEVER zero or negative
r3: Destination block
r4: Source block
r13: Full descending stack (if entering in same processor mode)
On Exit: all registers preserved (r0-12,r14}
Further optimisation can be achieved by using quad-word aligning blocks (at a sixteen byte boundary). According to what I have heard, you should be able to knock off 1 instruction per 16 Bytes this way.
Example:
\\\\ r0,r3 & r4 set up. r11 contain routine address
SWI "OS_EnterOS" \\ Do this if you want to do it in SVC mode
MOV r14,pc \ make it work like a BL instruction (12 bytes ahead)
either BIC r14,r14,#3 \ if using SVC clear to USR mode for return
or ADDNV r0,r0,#0 \ if not waste a processor instrcution.
\ but not neither!!!!
MOVS pc,r11 \ go to routine
.return \ with any luck we end up here! (if not don't ask)
SYS "WinSupport_XTemplate" (&43EC5)
Use: Open/Load Template/Close extended template file. Extended Template calls complement the Wimp ones by providing a menu template system, housed in the same file as window templates (use the wimp for these).
SYS "WinSupport_XTemplate"
rc: 0 - Load template file'
1 - Load menu template
2 - Close template
SYS "WinSupport_XTemplate" (rc: 0)
On Entry: r0 - Reason code (0)
r1 - Zero terminated filename
On Exit: r0-r1 Preserved
Notes: This in fact load the template file into module workspace to save time when actually loading templates. Only one can be opened at once (Remember to close it when finished)
SYS "WinSupport_XTemplate" (rc: 1)
On Entry: r0 - Reason Code (1)
r1 - Buffer for Menu
r2 - Pointer to indirected icon workspace
r3 - Pointer to end of indirected icon workspace
r4 - Pointer to font table (-1 if non are to be used)
r5 - Pointer to template name.
r6 - Index into template list (0 for first call)
On Exit: r0-r2 & r4-r5 Preserved
r2 - Next Free byte in indirected icon workspace
r6 - Index
Notes: The entry and exit is very similar to Wimp_LoadTemplate and the wildcarded template names work in a similar way: '*' - End of string wildcard (if it is found the string is automatically passed) '.' - single character wildcard. If found any character is matched to it. The wildcard index is used when there are many templates with similar names and a wildcarded search string is used. On exit, the index points to the template that has just been loaded, so if you pass it back in through the SWI the next template will be found (if it exists).
The idirected icon buffer will never exceded if the correct end is specified in r3.
Fonts are treated in the same way as they are in Wimp_LoadTemplate. If the font array pointer is -1 fonts and fonts are found a the template, the references to fonts are turned into references to the system font and an error is returned after the process has finished so that the template is usable.
Due to the recursive nature of the routine used in this SWI, error trapping is handled unusually. An error flag is kept, and if at the end of processing, it is set, the relevant error is returned. Unfortunately, only the first error is returned so other errors may well also have occured.
Don't put menus into sliding heap blocks unless you use SWI "WinSupport_RelocateMenu" before creating the menu each time or the block are unlikely to move
File format: I originally intended to include menu templates into normal template files with a different object tag, but Acorn doesn't approve of this idea..... Instead, they suggest that a data (&FFD) file is used instead. The file format is identical to normal template except that that there is a file header "MENU" before the normal header word (&FFFFFFFF). See Page 1789 (Appendix E in Volume IV) of the RISC OS programmer's reference manual for more information. The menu template has an entry in the Index just as a normal template has with a tag type of 2.
The Menu template data block as pointed to by the index contains the menu and all associated indirected data. Fonts are numbered internally and refer to the template file font table.
All absolute address are substituted with file offsets (from word 0 of the file) and are replaced by real address on being loaded.
A menu must appear at the beginning of the block, but after that, indirected icon data and further submenus can appear in any order.
The word at byte 4 of menu items is treated differently:
Bit 31 set: No submenu/window. Translated into -1 when loaded
Bit 30 set: Submenu. Bit 0-26: File Offset: Translated to real address
Bit 30+31 set: Window used instead. (you store window handle here later)
SWI "XWinSupport_RelocateMenu" (&43EC6)
Provided with old and new addresses, this routine will correct all pointers to absolute addresses in the menu structure which may have become corrupt due to the movement of heap blocks.
On Entry:
r2 -Old Menu pointer
r3- Old Indirected data pointer
r4- New Menu Pointer
r5- New Indirected data pointer
On Exit:
r2-r5 preserved
SWI "XWinSupport_FindMessage" (&43EC7)
This routine is designed to find messages in a file. Messages are identified by their position in the file. The first word of the file is expected to the size of the file in bytes. You can create the files in edit leaving out the size. The file format you use and how you load the messages doesn't really matter as long as the message area is valid. The SWI is designed to be convenient to pass the message to SWI"Wimp_ReportError". NB terminators of 10 (LF) and 13 (CR) are used in files. If you need the terminator to be 0 (NULL) you will have to change it after requesting a message. There is no problem with putting message files in sliding heap blocks as there are no absolute pointers.
On Entry:
r0 - Message number
r1 - Pointer beginning of file in memory (size word)
On Exit:
r0 - Pointer to message (if you need to change mesage, copy it into your own memory)
r1 - Preserved.
NB. This SWI may well provide facilities similar to those provided by MessageTrans which is provided on ROM in RISCOS III and with the Acorn printer drivers (release 2.44 or above). Unfortunately, I have not found documentation of the module anywhere.
Note about the use of sliding heap blocks
If you claim a number of blocks at the beginning of the heap and then do not release or resize any of them, they all should stay at the same position in memory, therefore meaning it is safe to put data that is pointed to by something else in them. (useful for indirected icon data etc.)
What can go in a 'loose' heap block. (block that could move)
Sprite areas
WinSupport Messagefiles
Menus definitions (if you always use WinSupport_RelocateMenu)
Most wimp parameter blocks
Anything else that does not keep absolute pointers.
