 |
www.riscos.com Technical Support: |
The Acorn Freeway Module
Freeway is a narrow software layer which maintains information about the location of objects on a network, in a decentralised fashion.
Objects are classified according to Freeway Type. At the Freeway level the attributes of an object are its name, location, an optional descriptor and an optional authentication value. All other characteristics are undefined.
Freeway itself only knows about the IP location of objects on the network.
It is not concerned with how those objects may be accessed, or with any specific access control mechanisms. These areas are handled by higher-level type-specific application software, as needed. Each type will have a 'controlling' application.
Freeway types are created by Acorn as required : third parties may request a type via the usual defined channel for allocation requests. Each type has a unique identifier : for example, if there is a need for software to enable 'Bach partitas' to be shared across a network, then an available Freeway type number will be allocated by Acorn - e.g. 97=BachPartitas - and then the controlling application will be written to 'share' Bach partitas - whatever that means.
Identifiers
Type number
This is a 16-bit integer identifying a Freeway type. The following type numbers are allocated to Acorn Access+. (Informal names with no significance in software will also be allocated, for easier human reference).
1 = Discs 2 = Printers 5 = Hosts
In Acorn Access, ShareFS is the controlling application for types Discs and Hosts, and !Printers is the controlling application for type Printers.
Object name
This is the name of an object.
An object name is unique within the set of objects of the same type within a site. Object names are terminated by a control character (and will return a terminator of zero on output), case independent, alphanumeric strings, created by users or application software. Maximum length is 64 bytes, including the terminator.
Object descriptor
This provides extra information about the object.
Its format is undefined at this level - it has significance to higher-level application software. Object descriptors are arrays of bytes of any value, maximum length 255.
In Acorn Access+ the descriptor for type Discs indicates whether a disc is shared protected or unprotected, or as a CDROM or subdirectory, and visible or invisible to other desktop users.
The descriptor for type Printers is a 'Printer Type' string.
The descriptor for type Hosts is null.
Object authentication value
Objects are either authenticated or unauthenticated. Authenticated objects require an authentication value to be provided before their attributes are made visible. An authentication value is a 32 bit integer. The authentication value of zero is reserved and should not be used.
Refresh interval
The Freeway software in each computer will periodically re-notify other computers about unauthenticated objects which are held by the local machine, so that they know that the objects continue to be accessible. This permits, for example, other machines to know when a computer holding Freeway objects has been powered down. The renotification period is called the "refresh interval", and is determined by the Freeway software and is typically 30 seconds.
Freeway SWIs
Unless noted otherwise, no Freeway SWIs are reentrant, nor is their effect on the interrupt status defined.
Freeway_Register (SWI &47a80)
Register or deregister interest in objects of a given Freeway type.
On entry:
R0 = flags: bit meaning
0 0 - register interest
1 - deregister interest
1 0 - interested in unauthenticated objects
1 - interested in authenticated objects
2 0 - R3 not valid
1 - R3 => type 'name' (<=15 characters, 0
terminated)
3-31 reserved - must be set to 0
R1 = type number
R2 = authentication value if R0 bit 1 is set, otherwise undefined
R3 = pointer to type 'name' if R0 bit 2 is set, otherwise undefined
On exit:
All registers preserved
This SWI enables a controlling application to register interest in authenticated or unauthenticated objects of a particular Freeway type with the local Freeway software, and also to give a 'name' to that type (this name is of no significance to the software, it's just for the convenience of the human user). Freeway will hold information arriving from the network about a remote object only if one or more registrations of interest have been made locally in that object's type. If the object is authenticated then at least one of those registrations must have included an authentication value which matches the object's own. An error is returned if insufficient free memory exists.
Freeway_Write (SWI &47a81)
Add or remove an object of a given type.
On entry:
R0 = flags: bit meaning
0 0 - add object
1 - remove object
1 1 - object is authenticated
2-31 reserved - must be set to 0
R1 = Freeway type number
R2 = pointer to object name, 0 terminated
R3 = length of object descriptor
R4 = pointer to object descriptor, or 0 for null descriptor or when R0
bit 0 is set
R5 = object authentication value if R0 bit 1 is set, otherwise undefined
On exit:
All registers preserved
This SWI adds or removes a locally held object of a given type. If the object is unauthenticated then other computers are notified immediately, otherwise notification is withheld until a remote computer requests it. An error is returned if the type number is not known (i.e. if Freeway_Register has not been called with this type number), or if an object is added and a remote object of the given name and type already exists, or if an object is removed and no local object of the given name and type is currently held, or if no memory exists to store information about the object.
If R0 bit 0 is set and the object named is already held as a local object, the object's descriptor and authentication value are updated if they differ from those passed to the SWI.
N.B.: Controlling applications should be prepared to receive upcall UpCall_Freeway, reason code object deleted (see Section 2.5), referring to any object previously added successfully via SWI Freeway_Write. This is to cover the possibility of Freeway deciding at any time that the information held about an object is unreliable and so deciding to remove it unilaterally, for any reason, e.g. if a remote object is created with the same name as a local object.
Freeway_Read (SWI &47a82)
Read attributes of an object.
On entry:
R0 = flags: bit meaning
0 1 = authentication value provided
1-31 reserved - must be set to 0
R1 = Freeway type number
R2 = pointer to object name, 0 terminated
R3 = length of buffer for object descriptor
R4 = pointer to buffer for object descriptor, or 0
R5 = authentication value if present, otherwise undefined
On exit: R0 - R2 preserved R3 = length of held object descriptor R4 preserved R5 = IP address of computer which holds the object
This SWI reads information about the attributes of an object. The type number and object name must be provided. The SWI returns the IP address of the holder, and optionally the descriptor. The length of a held object descriptor may be read by setting R4=0 on entry. However in this case there is no guarantee that the object attributes will not have changed, or that the object will still exist, if the SWI is called again some time later with the same object name. An error is returned if the type number is unknown, or the object name is unknown, or if a supplied authentication value does not match the object's own authentication value, or if a supplied object descriptor buffer is too short; in this case the actual length is returned in R3.
Freeway_Enumerate (SWI &47a83)
Enumerate objects of a given type.
On entry:
R0 = flags: bit meaning
0 0 = enumerate unauthenticated objects only
1 = enumerate authenticated objects only
1-31 reserved - must be set to 0
R1 = Freeway type number
R2 = length of buffer for object name
R3 = pointer to buffer for object name, or 0
R4 = length of buffer for object descriptor
R5 = pointer to buffer for object descriptor, or 0
R6 = 0 or undefined
R7 = enumeration reference (0 to start)
R8 = authentication value if R0 bit 0 is set, otherwise undefined
On exit: R0 - R1 preserved R2 = length of held object name, including 0 terminator R3 preserved R4 = length of held object descriptor R5 preserved R6 = IP address of computer which holds the object R7 = next enumeration reference, or -1 to indicate end reached R8 = preserved
This SWI allows a controlling application to enumerate currently held authenticated or unauthenticated objects of a given type, obtaining their names, location IP addresses, and descriptors if present. If an authentication value is provided then only those objects whose actual authentication value matches the supplied value are enumerated. If no authentication value is supplied then only unauthenticated objects are enumerated. The length of the held object name or descriptor may be read without filling in buffers by setting R3=0 or R5=0 respectively, on entry. However in this case there is no guarantee that the object attributes will not have changed, or that the object will still exist, if the SWI is called again some time later with the same enumeration reference.
If R7 is returned -1 then there were no further known objects of that type - the object name buffer will not have been filled in, and R6 is undefined.
An error is returned if the type number is unknown, or if a supplied name or descriptor buffer is too short. In the latter cases the actual name and descriptor lengths are returned in R2 and R4.
Freeway_Serial
This SWI is for internal use only.
Freeway Service calls
(Note that no Freeway SWIs may be called when these service calls are received)
Service_FreewayStarting (Service Call &95)
Freeway is starting up.
On entry:
R1 = &95 (reason code)
R2 = flags: bit meaning
0-31 reserved - must be set to 0
On exit: R1 preserved to pass on (must not be claimed)
Service_FreewayTerminating (Service Call &96)
Freeway is terminating.
On entry:
R1 = &96 (reason code)
R2 = flags: bit meaning
0-31 reserved - must be set to 0
On exit: R1 preserved to pass on (must not be claimed)
Freeway UpCall
UpCall_Freeway (UpCall 12)
Warns that an object has been added or changed, removed (by the holder), or deleted (by Freeway).
On entry:
R0 = &12 (reason code)
R1 = Freeway reason code
0 = object added
1= object removed
2 = object attributes have changed
3 = local object deleted by Freeway
R2 = object type
R3 = pointer to object name
R4 = length of object descriptor
R5 = pointer to object descriptor
R6 = IP address of device which holds or held this object.
On exit:
Registers preserved
This call warns controlling applications that the named object has been added, removed or changed. It is also issued when Freeway has detected that the information held about a locally held object is unreliable, (as a result of possible temporary name duplication, for example) and has removed it unilaterally. It is issued on callback, and the contents of the supplied name and descriptor buffers are guaranteed not to change provided they are read from within the application's UpCall handler.
Freeway CLI command
-*FWShow
Show currently known unauthenticated objects.
Syntax: *FWShow
Use : shows the names and holder IP addresses of all unauthenticated objects of all types currently known about by this machine. Local objects are indicated via a leading asterisk.