> 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).

Overview

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.

Structure

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.

ResourceFS directory structure

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

Path variables

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).

Auto-starting applications

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.

Storing configuration data

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.

Internationalisation

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. ]

Building ROM applications

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.