Appendix : Appendix N: Allocate request file formats

Overview

This appendix documents the request formats used when preparing allocations for the RISC OS Open allocations service. The build environment's riscos-allocate command uses a UTF-8 YAML description as its editable form and can recreate the historical binary Allocate request file used by the !Allocate desktop application.

The YAML description is intended for inspection, editing, and source control. The binary request file is intended for interchange with the historical application and for submission workflows that still expect the saved Allocate request format.

YAML description format

Top-level structure

The YAML document is a mapping with the following top-level keys:

Key	Meaning
SchemaVersion	Version of the YAML description schema. The current tool writes 1.
FormatVersion	Allocate request-file version. The current Allocate file format uses 1.00, corresponding to binary value 100.
Developer	Mapping containing the requestor details.
Registrations	Sequence of registration objects in the same order as the binary request file.

Empty optional scalar fields are written as YAML null.

Developer mapping

The Developer mapping contains these keys:

Key	Contents
Name	Requestor name.
Company	Company or organisation name.
DeveloperNumber	Developer number, if any.
Address1	First address line.
Address2	Second address line.
Address3	Third address line.
Address4	Fourth address line.
Phone	Telephone number.
Fax	Fax number.
Email	Email address.

Registration sequence

Each entry in Registrations is a mapping containing exactly one registration type name and its field mapping. The type names written by the tool are:

Type	Fields
SWIChunk	Prefix, Description.
MessageBlock	Description.
Reservation	Type, Text.
Filetype	ApplicationName, Name, DoubleClicking, and attachment fields.
ErrorBlock	Description.
Podule	AllocateManufacturer, ManufacturerId, PoduleName, Description.
DrawTagBlock	Description.
DrawObjectBlock	Description.
FilingSystem	Name, Selector.
ServiceBlock	Description.
Device	Name, Description.

For compatibility, the creator also accepts space-separated and title-cased variants of these names, such as SWIChunk and SWI chunk.

Filetype attachments

Filetype registrations carry three attachments: a sprite file, a product description, and a format description.

In inline YAML output:

Sprite contains the sprite data encoded as base64 text.
ProductDescription contains the product description as decoded text.
FormatDescription contains the format description as decoded text.

When detached exports are used, those inline fields are replaced by filename references:

Key	Referenced file
SpriteFile	Sprite attachment, normally written with host suffix ,ff9.
ProductDescriptionFile	Product description attachment, written as a text file.
FormatDescriptionFile	Format description attachment, written as a text file.

If both an inline field and the corresponding detached-file field are present when creating a request, the detached file takes precedence and a warning is emitted.

Text encoding

Developer-detail fields and fixed text fields in the binary Allocate format are stored as fixed-width Latin-1 byte arrays. Text attachments within filetype registrations are also treated as Latin-1. The YAML description is written as UTF-8, so binary Latin-1 text is decoded to Unicode when extracting and is encoded back to Latin-1 when creating a request file.

If a YAML value contains characters outside Latin-1, the creator warns and replaces each unrepresentable character with ? during creation.

Binary request file format

Conventions

The historical Allocate application stores an allocation request as a binary data file with RISC OS filetype &FB0. The file contains the requestor's developer details followed by a sequence of allocation request objects.

All integer fields are written as native C int values by the historical implementation. In the supplied sources these are 32-bit little-endian values. Text fields are fixed-length byte arrays written exactly as stored in memory.

Fixed-length text fields are not length-prefixed. The application initialises new structures to zero, then copies user text into them, so unused bytes are normally NUL padded. Readers should treat the last byte of each field as part of the stored field width rather than as guaranteed spare space.

The request file magic is the eight ASCII bytes ALLOCATE with no terminator.

Overall layout

Offset	Size	Name	Contents
0	8	magic	ASCII ALLOCATE, without a terminator.
8	4	version	File format version multiplied by 100. The supplied implementation writes 100.
12	4	object_count	Number of request objects following the developer details block.
16	452	developer_details	Developer details block; see the next subsection.
468		objects	Sequence of Object records entries.

Developer details block

The developer details block is stored inline in every binary request file. The same structure is also used for the standalone details file used by historical Allocate versions.

Offset	Size	Field	Contents
0	40	name	Requestor name.
40	50	company	Company or organisation name.
90	12	developer_number	Developer number.
102	50	address1	First address line.
152	50	address2	Second address line.
202	50	address3	Third address line.
252	50	address4	Fourth address line.
302	50	phone	Telephone number.
352	50	fax	Fax number.
402	50	email	Email address.

Object records

Each request object begins with a two-word header:

Offset	Size	Field	Contents
0	4	id	Object type identifier.
4	4	size	Size in bytes of the object payload that follows, not including this header.
8		payload	Object-specific data for the type named by id.

The object identifiers are:

ID	Object type
0	SWI chunk
1	Message block
2	Reservation
3	Filetype request
4	Error block
5	Podule allocation
6	Draw tag block
7	Draw object block
8	Filing system
9	Service call block
10	Device number

Object payloads

SWI chunk object

Offset	Size	Field	Contents
0	20	prefix	Requested SWI prefix.
20	100	description	Description of the module or use.

Message block object

Offset	Size	Field	Contents
0	100	description	Description of the protocol or message usage.

Reservation object

Offset	Size	Field	Contents
0	40	text	Name to reserve.
40	20	type	Reservation class, such as AppName or ModName.

Filetype object

The filetype request is the only variable-length object type. Its payload begins with a fixed part followed by three embedded file blocks. Historical files were commonly written from a 32-bit C structure, so many real request files include 3 bytes of padding between the 9-byte filetype name and the Boolean double-click flag. The converter accepts both the padded and the packed layout.

Offset	Size	Field	Contents
0	12	appname	Application name associated with the filetype.
12	9	fname	Requested filetype name.
21-23			Reserved, must be zero
24	4	double_clicking	Boolean flag indicating whether double-click loading is supported.
28	4	sprite_size	Size in bytes of the sprite file data.
32		sprite_data	Sprite file contents.
32+sprite_size	4	prod_desc_size	Size in bytes of the product description file.
36+sprite_size		prod_desc_data	Product description file contents.
36+sprite_size+prod_desc_size	4	format_size	Size in bytes of the file format description file.
40+sprite_size+prod_desc_size		format_data	Format description contents.

Error block object

Offset	Size	Field	Contents
0	100	description	Description of the module or purpose requiring the error numbers.

Podule object

Offset	Size	Field	Contents
0	4	allocate_manf	Boolean flag. Non-zero means a manufacturer number is also required.
4	4	manf	Existing manufacturer number when allocate_manf is zero; otherwise the field is not significant.
8	20	podule_name	Podule name.
28	100	description	Description of the podule.

Draw tag object

Offset	Size	Field	Contents
0	100	description	Description of the use for the tagged object range.

Draw object object

Offset	Size	Field	Contents
0	100	description	Description of the use for the Draw object range.

Filing system object

Offset	Size	Field	Contents
0	20	name	Filing system name.
20	20	select	Selection name used to choose the filing system.

Service block object

Offset	Size	Field	Contents
0	100	description	Description of the module or interface using the service calls.

Device object

Offset	Size	Field	Contents
0	20	name	Device name.
20	100	description	Description of the device or its use.

Related historical exports

Historical Allocate versions also store the requestor details in a standalone details file, generate a plain-text email export containing a uuencoded copy of the binary request, can save reservation objects as a CSV file, and can save a plain-text reply form for the allocations service.

Those additional formats are derived directly from the in-memory request and do not replace the binary request file or the YAML description as the canonical editable forms in this build environment.

Examples

Minimal reservation request

The following YAML reserves a module name:

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

Create the binary request file with:

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

Appendix48Appendix N: Allocate request file formats