> net#arf:$.a500.RiscOS+.doc.ROM_apps
Author: Neil Raine
Title: RISC OS+ Applications in ROM
Status: draft
History:
24-Aug-89 NRaine File created.
7-Sep-89 NRaine Stuff about !Chars and !Magnifier added.
12-Sep-89 NRaine Comment about !TinyDirs being the only application
removed. Comments about configuration files and
internationalisation added.
23-Feb-90 NRaine Updated to deal with ResourceFS
Issues (this section will be removed in the final version)
BASIC 1.05 (24-Aug-89) is required to run the ROM-based applications, if the Desktop module is in the RMA (the old one objects to PAGE being set inside the RMA).
The RISC OS+ desktop has a new icon called "Apps" on the iconbar. When clicked, a filer viewer containing the icons for the ROM applications is displayed, and these can be double-clicked to run the applications.
The application icons represent application directories which live in a special ROM filing system called "Resources:". They each invoke the application directly in ROM, thus saving a considerable amount of RAM space.
It is also possible to configure each of the applications to start up automatically when the desktop starts, without requiring a boot file.
A new module called ResourceFS implements the "Resources:" filing system, and allows other modules to "register" files in this filing system (see doc.ResourceFS for further details).
This allows each ROM application to be built as a single module, that consists of the application itself, the resource files it requires, and a small amount of code which deals with registering the resource files with ResourceFS. See the section "Building ROM applications" at the end of this document for details of how these modules are built.
In addition, there is a "Resource Filer" module, which displays a directory icon of "Resources:$.Apps" on the icon bar. This is similar to a TinyDirs directory, but uses the sprite "romapps" rather than "directory", and does not allow the icon to be removed. Clicking SELECT on the icon opens the Apps directory, while the menu allows the auto-start options to be set or "Resources:$" to be opened.
Thus the average punter will initially see a desktop which is the same as before except for the "Apps" directory on the iconbar, which he can use to get at the applications.
The following directory structure is used:
Resources:$.Apps.!<appnames> ; the ROM applications
Resources:$.Fonts ; the ROM fonts
Resources:$.Resources.<modulenames> ; the Desktop resources
Resources:$.Resources.<appnames> ; resources for the ROM apps
The relevant modules are:
Module name Language Path variable (if any)
----------- -------- -------------
!Alarm BASIC
!Chars BASIC
!Configure C
!Draw C
!Edit C
!FontCtrl BASIC
!Help BASIC
!Magnifier BASIC
!Paint C
!PrinterDM BASIC
ADFSFiler Assembler ADFSFiler$Path
NetFiler Assembler NetFiler$Path
Filer Assembler Filer$Path
FilerAct C FilerAct$Path
FilerSWIs C FilerSWIs$Path
Palette Assembler Palette$Path
RAMFSFiler Assembler RAMFSFiler$Path
ResFiler Assembler ResFiler$Path
Switcher Assembler Switcher$Path
TinyDirs Assembler TinyDirs$Path
Wimp Assembler WindowManager$Path
ROMFonts Assembler Font$Path
The Fonts directory contains the ROM-based fonts, and are accessed by the ROMFonts module setting up Font$Path as follows:
*SetMacro Font$Path <Font$Prefix>.,Resources:$.Fonts.
(it only does this if Font$Path was previously set to "<Font$Prefix>.").
All the Desktop modules (ADFSFiler, NetFiler etc.) access their resource files (Messages and Templates) via path variables, eg: "NetFiler:Messages". On initialisation, they check for the existence of the relevant path variable and set up the appropriate default if it is not defined, eg:
*Set NetFiler$Path Resources:$.Resources.NetFiler.
This allows the user to set up any or all of these path variables to point to his own message files.
Note that the Wimp uses "WindowManager$Path" rather than "Wimp$Path", to allow Wimp$Path to remain separate. Its resources are:
Resources:$.Resources.Wimp.Sprites
Resources:$.Resources.Wimp.Sprites23
Resources:$.Resources.Wimp.Templates
The Sprites files contain the Wimp's ROM sprite pool, and cannot be redirected (since the Wimp needs direct access to their ROM addresses).
The Apps directory contains the ROM applications, which each have a !foo directory, and can be started up by "/Resources:$.Apps.!foo". The Desktop module will automatically start the applications using such commands, if the corresponding bits in CMOS RAM are set, by issuing Wimp_StartTask as appropriate. It does this on *Desktop : after the normal modules have been started, and before any parameters to the *Desktop command have been decoded.
The CMOS RAM bytes 'DeskbootCMOS' (&D7) and 'Deskboot2CMOS' (&D8) are used as follows:
&D7: bit 0 set => auto-start !Alarm
bit 1 set => auto-tinydir !Chars
bit 2 set => auto-start !Configure
bit 3 set => auto-start !Draw
bit 4 set => auto-start !Edit
bit 5 set => auto-tinydir !FontCtrl
bit 6 set => auto-start !Help
bit 7 set => auto-start !Magnifier
&D8: bit 0 set => auto-start !Paint
bit 1 set => auto-start !PrinterDM
bit 2 set => auto-start !TinyDirs
bits 3..7 reserved
The default value of these bytes is 0,0 (ie. no applications are auto-started).
Note that !Chars and !Magnifier are not auto-started, since they have no iconbar icons of their own: instead they are put onto the iconbar using the "*AddTinyDir" command.
Note that this auto-starting procedure does not occur if the *Desktop command has a filename parameter, since in this case it is assumed that the Desktop Boot file will start any applications that are required. The configuration options are provided to allow discless operation of the machine.
The two applications "!Alarm" and "!PrinterDM" both need to store the user's preferred settings somewhere. Normally this is saved inside the application directory, but clearly there are problems if this is in ROM.
The solution is that the actual !Alarm and !PrinterDM applications do not contain the entire application, but simply the !Run files and the initial configuration files. The !Run file then sets up a path variable, consisting of the current value of <Obey$Dir> (ie. the application directory itself) and another directory in Resources:$ (eg. Resources:$.Resources.Alarm).
If an attempt is made to save configuration data into Resources:, the error message "Copy !Alarm onto the application disc and run it from there" results. If the application is then copied onto disc and run from there, alarms can be saved in the new application directory on the disc, while the main body of the program is still located in the ROM.
Because !Alarm uses a path variable to access its resource files, it is possible for the system administrator to put an updated copy of the 'Messages' file into the application directory on disc, and this will take precedence over the version in the ROM directory, which is accessed via the second path element.
Thus the messages file is not normally copied onto the disc when the user copies !Alarm from the "Apps" directory, but can be included there if required.
It is envisaged that an "internationalised" machine would include the whole of the "Apps" directory on a disc (with new Message files), and the "Apps" directory would be configured not to appear on the icon bar.
[ Another way to internationalise the ROM would be to add a module that replaced the Message files in the Resources: filing system, by using the fact that files declared to ResourceFS will obscure those declared earlier with the same name. However, this would require all the message files for the applications to be RAM-resident all the time. ]
The applications are built in one of three ways:
Assembler programs: run as modules
C programs: run as modules, with a special module wrapper
BASIC programs: set PAGE to an address in ROM, and RUN
Assembler programs:
This is the simplest case. There is only one instantiation of each module, which is started up by the Desktop module when the desktop is entered, using the Service_StartWimp protocol.
These modules typically require a Messages file and a Templates file, which they create in Resources: using ResourceFS_RegisterFiles, and access via a path variable, to allow user-modification.
C programs:
Using C release 3 and cmhg, it is possible to compile a C program to run as a module. In addition, there is an extra piece of module wrapper which allows multiple copies of the same application to be started by means of a *command. This *command is then invoked by the !Run file in Resources:$.Apps.!<app>.
In the directory "net#arf:$.a500.AAsm164.make-a-mod" you will find the bits needed to make a C module that can also include its own resource files. Note that you will need ObjAsm 1.64, which supports the "BIN" directive.
BASIC programs:
The application directory in Resources:$.Apps.!<app> should only contain a !Run file, which sets up a path variable as follows:
Set <app>$path <Obey$Dir>.,Resources:$.Resources.<app>.
and then invokes "<app>:!RunLink". This is a small BASIC program that opens the file "<app>:!RunImage", and then calls OS_FSControl (21) to read the filing system number and internal file handle of the file. If the filing system number is 46 (ResourceFS), then it knows that the internal file handle is equal to the address of the file in ROM, so it sets PAGE to this value and then RUNs the main program directly in ROM. Note that LOMEM is still set to application space, so the WimpSlot command in the !Run file should set up enough memory for the variables without the program body.
In the directory "net#arf:$.a500.AAsm164.make-basic" you will find the bits needed to make a BASIC ROM application.