RISC OS Allocation Service

Overview

RISC OS maintains a central registry for resources that must not clash between software authors. The allocation service is run by RISC OS Open.

• Allocation email address: allocate@riscosopen.org
• Preferred method: Use the !Allocate desktop application to create a structured request file, then attach it to an email. Since !Allocate cannot be run in the RISC OS Build environment, a tool riscos-allocate can be used which allows an allocation file to be constructed, which can be sent by email.
• Alternative method: If requested, or the riscos-allocate tool is not available, you should send an email directly describing the resources needed.
• When to allocate: Before publicly releasing any software that uses the resource.

Response time: RISC OS Open aim to respond within 5 working days.

Important: The allocations service can be slow or unresponsive. If no reply has been received after one week, resend — forward the original email with a brief note explaining it is a resend.

What allocation does NOT cover: The service does not check for trademark, copyright, patent, or other IPR issues. That remains the requester's responsibility.

Step-by-Step Process

1. Identify what needs registering

If invoked with a project in context, examine the project to determine what allocations are needed:

• Check the CMHG file (cmhg/*) for the module title, SWI chunk base, and error base
• Check the source files for any *Commands, service calls, system variables, or filetypes
• Check VersionNum or Makefile,fe1 for the project name if not otherwise clear

If invoked without project context, ask the user:

• What software or resource needs registering?
• Which type(s) of allocation are required? (Use the table below.)
• Is a specific value already in use that should be formalised, or is a fresh allocation needed?
• Is there any documentation (e.g., a URL) describing the interface?

2. Ask how to deliver the email

Ask the user: "Would you like the email written to a text file, or displayed on screen?"

• File: write to allocate-request.txt in the current directory (or a name the user prefers)
• Screen: display the full email text in the conversation

3. Gather sender details

Ask for, or read from context:

• The user's full name
• The user's email address

For the allocation tool, this information is required. The full developer address, etc is not required, but may be useful.

These are needed for the From: header and the closing signature.

4. Compose the email

Structure the email as plain text:

To: allocate@riscosopen.org
From: <Full Name> <<email address>>
Subject: <brief description of the allocation request>

<Body>

-- 
<Full Name>

Binary allocation file construction

If the user wants a structured Allocate request file, create a YAML description for riscos-allocate first, then convert it to the native ,fb0 request file. Keep the YAML as the editable source form and generate the binary file from it.

The YAML always contains:

• SchemaVersion
• FormatVersion
• Developer
• Registrations

The Developer mapping should contain the requestor details. Unknown details may be left as null. The Registrations sequence contains one mapping per allocation request.

Minimal example for a simple module-name reservation:

SchemaVersion: 1
FormatVersion: 1.00
Developer:
  Name: Example Developer
  Company: null
  DeveloperNumber: null
  Address1: null
  Address2: null
  Address3: null
  Address4: null
  Phone: null
  Fax: null
  Email: example@example.invalid
Registrations:
  - Reservation:
      Type: ModName
      Text: ExampleModule

Example for a module which needs a module name, SWI chunk, error block, and a star command:

SchemaVersion: 1
FormatVersion: 1.00
Developer:
  Name: Example Developer
  Company: Example Software
  DeveloperNumber: null
  Address1: null
  Address2: null
  Address3: null
  Address4: null
  Phone: null
  Fax: null
  Email: example@example.invalid
Registrations:
  - Reservation:
      Type: ModName
      Text: ExampleModule
  - SWIChunk:
      Prefix: ExampleModule
      Description: SWIs for the ExampleModule module
  - ErrorBlock:
      Description: Error numbers for the ExampleModule module
  - Reservation:
      Type: StarComm
      Text: ExampleStatus

For filetype allocations, attachments may be embedded in the YAML as text or base64, or referred to by sibling filenames using the detached-file form that riscos-allocate --extract-files produces.

Convert the YAML to a binary Allocate request with:

riscos-allocate --create request.yaml -o request,fb0

Attach the resulting ,fb0 file to the email. Also include the plain-text request in the body so that the allocation team can understand the request without opening the attachment.

Keep both the YAML file and the generated binary file for the user unless they explicitly ask for a transient output.

Not all details fit naturally in the Allocate file format. If any important context, rationale, or constraints are not represented in the binary request, state them explicitly in the plain-text email body.

Plain text construction

When building the email as text, construct the mail like this:

Subject line: Keep it short and factual. Describe what is being requested. Examples:

• Module registration: ExampleModule
• Filetype allocation for YAML
• SWI chunk request: ExampleRenderer
• System variable allocation: Sys$Example

Body: Be clear and direct. State what is being requested and why. For each item, use the terminology from the table of allocation types below. If a specific value is already in use, state it. If any value will do, say so.

Example body for a module:

I would like to register the following allocations for a new module:

Module name: ExampleModule
SWI chunk (64 SWIs) and name prefix: ExampleModule
Error block (256 errors): required

*Commands provided:
    ExampleCmd
    ExampleStatus

Documentation: https://example.org/prm/examplemodule.html

Example body for a filetype:

I would like to allocate a filetype for YAML files. YAML is a human-readable
data serialisation format. JSON is allocated as &975 and XML as &980; a similar
&fxx range would be appropriate.

If a filetype has already been allocated, please let me know the number.

NEVER suggest numbers for SWI bases, error numbers or services. These will always be allocated from a pool.

5. Deliver and inform

After producing the email, tell the user:

• Send to: allocate@riscosopen.org
• Expected response: within 5 working days
• If no response after one week: resend the email by forwarding the original with a brief note at the top, such as: "Resending this request as I have not received a reply."

Resending

When composing a resend, forward the original message and add a short note:

To: allocate@riscosopen.org
From: <Full Name> <<email address>>
Subject: <original subject> (resend)

Resending this request as I have not received a reply.

<any corrections or updates since the original, if applicable>

---------- Forwarded message ----------
<original email in full>

Complete Table of Allocatable Resources

The following is taken from the official RISC OS Open allocation page (https://www.riscosopen.org/content/allocate). The !Allocate request type column shows the terminology used by the !Allocate application; use the same terms in the email where relevant.

Resources without a !Allocate request type must be requested by email only, describing the resource in plain terms.

Notes on Common Patterns

Typical module requiring SWIs

Most modules need:

• Module name (Reservation (ModName))
• SWI chunk and name prefix (SWI chunk)
• Error block (Error block)
• Any *Commands (Reservation (StarComm) for each)

Module without SWIs

A module that only provides commands and claims a service call may only need:

• Module name
• Error block (if it raises errors)
• Star command names

Filetype

State the format name, what it contains, and any relationship to existing types. Ask whether a filetype is already allocated before requesting a new one.

System variable

State the full variable name (must contain $), the format of its value, when it is set, and who sets it.