File        : Module
Date        : 07-Dec-97
Author      :  A.Thoukydides, 1995, 1996, 1997
Description : Description of the ARMEdit module.


INTRODUCTION

The ARMEdit module forms the core of the ARMEdit suite of software. It
provides the communications between software running on the PC card and
RISCOS.

The module should normally be loaded after the desktop has been started, but
before the PC front-end has been loaded. However, if Wimp$ScrapDir is set to
a suitable value then the module may be loaded before the desktop has been
entered. A good place for loading the ARMEdit module is in the !Run file of
the PC front-end.

The current version of this module will work with versions of the PC
front-end software 1.87 and above. However, significantly better performance
will be obtained if PCPro (!PC version 2.00 of higher) is used. The version
number is displayed in the Info window from the icon-bar icon. See the
Contacts documentation for details of how to obtain upgrades.


SYSTEM VARIABLES

The ARMEdit module sets and uses the following system variables:

    ARMEdit$Path
    
        Path used to access Messages file. This is normally set to point to
        the file contained within the module and placed in ResourceFS.
        
    
    ARMEdit$ScrapDir
    
        Directory used for temporary files. This is normally set to
        <Wimp$Scrap>.ARMEdit, but may be changed if required. If there is
        sufficient memory in the computer then better performance would
        result from placing this in a RAM disc.
        
        The module sets and uses this variable (if not already defined)
        during initialisation. Hence it is necessary for <Wimp$Scrap> to be
        defined before the module is loaded.
    

*COMMANDS

The following *commands are provided by the ARMEdit module:
        

    *ARMEdit_Clients
    
        This command displays details of the clients that have registered
        with the ARMEdit module for communication purposes.


    *ARMEdit_Devices
    
        List the RISC OS path of all active emulated devices. Several other
        details are also listed for each device.


    *ARMEdit_DevicesRelog [-now]
    
        Force a relog of the RISC OS directory structure. This releases most
        of the memory claimed to support device driver operation and closes
        open files.

        Note that this may not take immediate effect - DOS must acknowledge
        a change of disc before any relog occurs. This normally occurs if
        no files are open on the device, and a simple operation (such as
        typing DIR) is performed on the drive. Note that each emulated device
        is treated seperately; some devices may be reset before others.
        
        The -now switch forces an immediate reset. This should only be used
        if essential, and must never be used in the middle of a disc access,
        otherwise DOS could be confused by an inconsistent disc image.
        
        It can be useful to call this from the DOS command line using the
        OSCLI command (supplied as part of the ARMEdit suite) - perhaps it
        should be placed in a DOS batch file for easier use.


    *ARMEdit_DOSMap
    
        This command updates the cached list of mappings between DOS
        extensions and RISC OS filetypes. These details are read initially
        from DOSFS, but may be re-read at any time using this command.
        

    *ARMEdit_Files

        This command displays details of the RISC OS files currently open for
        PC software. For each open file the file handle and filename is
        displayed. There is also a field that indicates whether the file will
        automatically be deleted when it is closed (either explicitly by the
        PC software, or when the PC is reset or quit).
        
        Any files opened for the device driver are also listed.
        

    *ARMEdit_Memory

        This command displays details of the RISC OS memory currently being
        used by PC software. For each block of memory claimed the base
        address and size of the block is displayed.
        
        The memory is currently allocated from the RMA, but a header is
        attached to the start of each block. Hence the address displayed is
        not the start of a heap block. The information in the header is used
        to automatically release the memory when the PC is reset or quit if
        the PC software fails to do so.


    *ARMEdit_Polling [[-fore] <polls>] [[-back] <polls>]

        This command allows the multitasking speed of the PC card to be
        controlled. Larger values increase the performance of the PC card
        at the expense of slowing down the desktop. A value of 0 results
        in the normal behaviour.
        
        Use with no parameters to display the current settings. If only
        a single value is specified (without switches) then both settings
        are updated.
        

    *ARMEdit_Version
    
        This command displays the version numbers of the data structures used
        by the most recently used PC front-end. It also displays the range of
        versions catered for by this version of the module.


SWIs

The following SWIs are provided by the ARMEdit module. For more details
regarding the use of the communciations SWIs see the Code documentation.


SWI "ARMEdit_ControlPC" (&4BC40)

    Control the PC front-end.
    
    On entry:
    
        R0 = Operation to perform:
        
                0   Suspend full screen mode
                1   Freeze running in a window
                2   Reset the PC
                3   Quit the front-end

    On exit:
    
        All registers preserved.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        This call allows the PC front-end to be controlled. Note that if the
        PC front-end is not the current application then this will only take
        effect the next time the front-end is paged in.
        
        Note that suspending full screen mode only starts execution in a
        window if enabled by the current configuration.


SWI "ARMEdit_TalkStart" (&4BC41)

    Register a new client task.
    
    On entry:
    
        R0 = Pre-allocated ID for this task.
        R1 = Flags (see below).
        R2 = Pointer to a function to be called when a message is available,
             or 0 for none.
        R3 = Value for R12 to contain when function pointed to by R2 is
             called.

    On exit:
    
        R0 = A unique client handle.
        R1 = Pointer to a poll word for this task.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        An application that provides services to PC software should call this
        when it is starting. A message buffer is allocated and a unique
        handle for this task assigned. This handle should be stored and used
        in all other calls relating to this task.
        
        The currently defined flag bits are:
        
            Bit     Meaning if set
            
            0       Messages from the ARMEdit module are required.
        
        All other bits should be set to 0 to allow for future expansion.
        
        The poll word is initially set to zero. When there is potentially a
        message waiting for this task the poll word is set to a non-zero
        value. The poll word is cleared when either the message has been
        read, or no message is available for some other reason. Note that a
        non-zero poll word does not imply that a message will be available;
        another task might have read the message if it was not directed to
        a specific handle. The poll word must not be written to; it must only
        be modified by the ARMEdit module.


SWI "ARMEdit_TalkEnd" (&4BC42)

    Deregister a client task.
    
    On entry:
    
        R0 = The previously assigned handle for this client task.

    On exit:
    
        All registers preserved.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        All applications that call ARMEdit_TalkStart must call this before
        they terminate. This releases the message buffer and allows other
        tasks to detect whether particular services are available.


SWI "ARMEdit_TalkTX" (&4BC43)

    Send a message to another client task.
    
    On entry:
    
        R0 = Client handle for this task.
        R1 = Either the ID or client handle for the recipient (if R2 not 0).
        R2 = Pointer to block containing the message to send, or 0 to check
             if the buffer already contains a message.

    On exit:
    
        R2 = Pointer to message buffer, or 0 if no message is waiting to be
             delivered.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        Send a message to another task. The destination task can be specified
        using either it's ID or client handle. If the ID is specified then it
        will be offered to each matching task that polls it until it is
        acknowledged. A particular message is only offered to each task once.
        When sending messages to PC software (ID = 0) the handle should
        always be specified.
        
        Note that the message buffer for each task can only contain a single
        message to send; if there is already a message waiting to be
        delivered then it is overwritten. When multiple clients are used,
        this SWI should first be called with R2 = 0 to check if a message
        is still waiting. Broadcast messages are never cleared automatically.


SWI "ARMEdit_TalkRX" (&4BC44)

    Check for any waiting messages for this client task.
    
    On entry:
    
        R0 = Client handle for this task.

    On exit:
    
        R0 = Pointer to block containing waiting message, or 0 if no messages
             waiting.
        R1 = Source ID.
        R2 = Source client handle.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:

        Check for any waiting messages. If none are available R0 contains 0
        on exit, otherwise it contains a pointer to the first message. The
        message should be checked, and if it is claimed ARMEdit_TalkAck or
        ARMEdit_TalkReply should be called to prevent it being passed to
        other clients. Any information required from the message must be read
        or copied immediately, since the message could be overwritten by a
        new message.
        
        The specified source client handle should be used for any reply;
        unlike the ID it uniquely identifies a particular instantiation of a
        client.
        
        If this call is successful then it should be called again; it is
        possible for multiple messages to be pending for a single client.


SWI "ARMEdit_TalkAck" (&4BC45)

    Claim the most recently read message.
    
    On entry:
    
        R0 = Client handle for this task.

    On exit:
    
        All registers preserved.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        After reading a message with ARMEdit_TalkRX, this call should be
        used to claim the message, and to prevent it being offered to other
        clients. This should be used before calling any other SWIs from this
        module.
        
        If the message was sent by the ARMEdit module then calling this SWI
        has no effect; other clients still receive the message.


SWI "ARMEdit_HPC" (&4BC46)

    Call an ARMEdit HPC service.
    
    On entry:
    
        R0 = Length of first input block.
        R1 = Pointer to first input block.
        R2 = Length of second input block.
        R3 = Pointer to second input block.
        R4 = Length of first output block.
        R5 = Pointer to first output block.
        R6 = Length of second output block.
        R7 = Pointer to second output block.

    On exit:
    
        All registers preserved.

    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        This call may either be used to test HPC services, or to provide
        access to the routines from a system that does not support either of
        the communications systems used normally by the ARMEdit system.
        
        For convenience the input and output data may be split into two
        portions. Any length value may be zero to omit that portion. The
        input data must be at least two bytes long to contain a valid ID.


SWI "ARMEdit_Polling" (&4BC47)

    Control the multitasking speed of the PC card.
    
    On entry:
    
        R0 = Foreground speed, or -1 to read the current setting.
        R1 = Background speed, or -1 to read the current setting.

    On exit:
    
        R0 = The current foreground speed.
        R1 = The current background speed.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        This call has has a similar use to *ARMEdit_Polling.

        Larger values increase the performance of the PC card at the expense
        of slowing down the desktop. A value of 0 results in the normal
        behaviour.


SWI "ARMEdit_TalkReply" (&4BC48)

    Reply to a message from another client task.
    
    On entry:
    
        R0 = Client handle for this task.
        R1 = The client handle for the recipient.
        R2 = Pointer to block containing the message to send.

    On exit:
    
        All registers preserved.
    
    Interrupts:
    
        Interrupt status is undefined.
        Fast interrupts are enabled.

    Processor mode:
    
        Processor is in SVC mode.

    Re-entrancy:
    
        SWI is not re-entrant.

    Use:
    
        This is like ARMEdit_TalkTX, except that the message is stored in the
        destination task's message buffer. The destination task must be
        specified by it's client handle; it is not possible to send the
        message to an ID.
        
        The main use of this call is to support the easy creation of RISC OS
        tasks acting as a server for multiple PC tasks.


THINGS TO DO

The following are changes that may be made to the ARMEdit module sometime in
the future.

    None at the moment!


VERSION HISTORY

0.00 (12-Nov-95)    Original development version.

0.01 (14-Nov-95)    Fixed bugs in file handling. Removed stray debugging code.
                    Sets variable for scrap directory and ensure it exists.

0.02 (15-Nov-95)    Included extra command to display PC front-end version.
                    Fixed workspace handling for *commands. (Oops!)

0.03 (17-Nov-95)    Uses correct HPC service identifier.
                    Includes development versions of device driver support.

0.04 (21-Nov-95)    Implemented the *commands and real HPC support.

0.06 (22-Dec-95)    Added SWI to control the PC front-end.

0.07 (28-Dec-95)    Added message passing protocol.

1.00 (12-Jan-96)    First official release version.

1.01 (11-Feb-96)    Does not crash when no DOSMap mappings defined.
                    Module can be loaded after new versions of the PC front-end.

1.02 (06-Aug-96)    Some memory management moved to a dynamic area if available.
                    Device driver support added.
                    Routines to convert date and time stamps included.
                    Added SWI to call internal HPC services.
                    Corrected command help texts.
                    Added command to set multitasking speed of PC front-end.
                    Provided mechanism for checking delivery of messages.

1.03 (21-Feb-97)    Added SWI to set multitasking speed of PC front-end.
                    Added SWI to reply to a message.
                    Broadcast messages from the ARMEdit module are now sent.
                    Speed control now works correctly with PC front-end 2v02.
                    Extended *ARMEdit_DevicesRelog to force immediate relog.

1.04 (07-Dec-97)    Extra information is displayed for *ARMEdit_Devices.
                    *ARMEdit_Files also lists files used by the device driver.