home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / Module < prev    next >
Encoding:
Text File  |  1997-02-21  |  16.6 KB  |  555 lines
  1. File        : Module
  2. Date        : 21-Feb-97
  3. Author      : © A.Thoukydides, 1995, 1996, 1997
  4. Description : Description of the ARMEdit module.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9. The ARMEdit module forms the core of the ARMEdit suite of software. It
  10. provides the communications between software running on the PC card and
  11. RISC OS.
  12.  
  13. The module should normally be loaded after the desktop has been started,
  14. but before the PC front-end has been loaded. However, if Wimp$ScrapDir is
  15. set to a suitable value then the module may be loaded before the desktop
  16. has been entered. A good place for loading the ARMEdit module is in the
  17. !Run file of the PC front-end.
  18.  
  19. The current version of this module will work with versions of the PC
  20. front-end software 1.87 and above. However, significantly better performance
  21. will be obtained if PCPro (!PC version 2.00 of higher) is used. The version
  22. number is displayed in the Info window from the icon-bar icon. See the
  23. Contacts documentation for details of obtaining upgrades.
  24.  
  25.  
  26. SYSTEM VARIABLES
  27.  
  28. The ARMEdit module sets and uses the following system variables:
  29.  
  30.     ARMEdit$Path
  31.     
  32.         Path used to access Messages file. This is normally set to point to
  33.         the file contained within the module and placed in ResourceFS.
  34.         
  35.     
  36.     ARMEdit$ScrapDir
  37.     
  38.         Directory used for temporary files. This is normally set to
  39.         <Wimp$Scrap>.ARMEdit, but may be changed if required. If there is
  40.         sufficient memory in the computer then better performance would
  41.         result from placing this in a RAM disc.
  42.         
  43.         The module sets and uses this variable (if not already defined)
  44.         during initialisation. Hence it is necessary for <Wimp$Scrap> to be
  45.         defined before the module is loaded.
  46.     
  47.  
  48. *COMMANDS
  49.  
  50. The following *commands are provided by the ARMEdit module:
  51.         
  52.  
  53.     *ARMEdit_Clients
  54.     
  55.         This command displays details of the clients that have registered
  56.         with the ARMEdit module for communication purposes.
  57.  
  58.  
  59.     *ARMEdit_Devices
  60.     
  61.         List the RISC OS path of all active emulated devices.
  62.  
  63.  
  64.     *ARMEdit_DevicesRelog [-now]
  65.     
  66.         Force a relog of the RISC OS directory structure. This releases most
  67.         of the memory claimed to support device driver operation and closes
  68.         open files.
  69.  
  70.         Note that this may not take immediate effect - DOS must acknowledge
  71.         a change of disc before any relog occurs. This normally occurs if
  72.         no files are open on the device, and a simple operation (such as
  73.         typing DIR) is performed on the drive. Note that each emulated device
  74.         is treated seperately; some devices may be reset before others.
  75.         
  76.         The -now switch forces an immediate reset. This should only be used
  77.         if essential, and must never be used in the middle of a disc access,
  78.         otherwise DOS could be confused by an inconsistent disc image.
  79.         
  80.         It can be useful to call this from the DOS command line using the
  81.         OSCLI command (supplied as part of the ARMEdit suite) - perhaps it
  82.         should be placed in a DOS batch file for easier use.
  83.  
  84.  
  85.     *ARMEdit_DOSMap
  86.     
  87.         This command updates the cached list of mappings between DOS
  88.         extensions and RISC OS filetypes. These details are read initially
  89.         from DOSFS, but may be re-read at any time using this command.
  90.         
  91.  
  92.     *ARMEdit_Files
  93.  
  94.         This command displays details of the RISC OS files currently open for
  95.         PC software. For each open file the file handle and filename is
  96.         displayed. There is also a field that indicates whether the file will
  97.         automatically be deleted when it is closed (either explicitly by the
  98.         PC software, or when the PC is reset or quit).
  99.         
  100.  
  101.     *ARMEdit_Memory
  102.  
  103.         This command displays details of the RISC OS memory currently being
  104.         used by PC software. For each block of memory claimed the base
  105.         address and size of the block is displayed.
  106.         
  107.         The memory is currently allocated from the RMA, but a header is
  108.         attached to the start of each block. Hence the address displayed is
  109.         not the start of a heap block. The information in the header is used
  110.         to automatically release the memory when the PC is reset or quit if
  111.         the PC software fails to do so.
  112.  
  113.  
  114.     *ARMEdit_Polling [[-fore] <polls>] [[-back] <polls>]
  115.  
  116.         This command allows the multitasking speed of the PC card to be
  117.         controlled. Larger values increase the performance of the PC card
  118.         at the expense of slowing down the desktop. A value of 0 results
  119.         in the normal behaviour.
  120.         
  121.         Use with no parameters to display the current settings. If only
  122.         a single value is specified (without switches) then both settings
  123.         are updated.
  124.         
  125.  
  126.     *ARMEdit_Version
  127.     
  128.         This command displays the version numbers of the data structures used
  129.         by the most recently used PC front-end. It also displays the range of
  130.         versions catered for by this version of the module.
  131.  
  132.  
  133. SWIs
  134.  
  135. The following SWIs are provided by the ARMEdit module. For more details
  136. regarding the use of the communciations SWIs see the Code documentation.
  137.  
  138.  
  139. SWI "ARMEdit_ControlPC" (&4BC40)
  140.  
  141.     Control the PC front-end.
  142.     
  143.     On entry:
  144.     
  145.         R0 = Operation to perform:
  146.         
  147.                 0   Suspend full screen mode
  148.                 1   Freeze running in a window
  149.                 2   Reset the PC
  150.                 3   Quit the front-end
  151.  
  152.     On exit:
  153.     
  154.         All registers preserved.
  155.     
  156.     Interrupts:
  157.     
  158.         Interrupt status is undefined.
  159.         Fast interrupts are enabled.
  160.  
  161.     Processor mode:
  162.     
  163.         Processor is in SVC mode.
  164.  
  165.     Re-entrancy:
  166.     
  167.         SWI is not re-entrant.
  168.  
  169.     Use:
  170.     
  171.         This call allows the PC front-end to be controlled. Note that if the
  172.         PC front-end is not the current application then this will only take
  173.         effect the next time the front-end is paged in.
  174.         
  175.         Note that suspending full screen mode only starts execution in a
  176.         window if enabled by the current configuration.
  177.  
  178.  
  179. SWI "ARMEdit_TalkStart" (&4BC41)
  180.  
  181.     Register a new client task.
  182.     
  183.     On entry:
  184.     
  185.         R0 = Pre-allocated ID for this task.
  186.         R1 = Flags (see below).
  187.         R2 = Pointer to a function to be called when a message is available,
  188.              or 0 for none.
  189.         R3 = Value for R12 to contain when function pointed to by R2 is
  190.              called.
  191.  
  192.     On exit:
  193.     
  194.         R0 = A unique client handle.
  195.         R1 = Pointer to a poll word for this task.
  196.     
  197.     Interrupts:
  198.     
  199.         Interrupt status is undefined.
  200.         Fast interrupts are enabled.
  201.  
  202.     Processor mode:
  203.     
  204.         Processor is in SVC mode.
  205.  
  206.     Re-entrancy:
  207.     
  208.         SWI is not re-entrant.
  209.  
  210.     Use:
  211.     
  212.         An application that provides services to PC software should call this
  213.         when it is starting. A message buffer is allocated and a unique
  214.         handle for this task assigned. This handle should be stored and used
  215.         in all other calls relating to this task.
  216.         
  217.         The currently defined flag bits are:
  218.         
  219.             Bit     Meaning if set
  220.             
  221.             0       Messages from the ARMEdit module are required.
  222.         
  223.         All other bits should be set to 0 to allow for future expansion.
  224.         
  225.         The poll word is initially set to zero. When there is potentially a
  226.         message waiting for this task the poll word is set to a non-zero
  227.         value. The poll word is cleared when either the message has been
  228.         read, or no message is available for some other reason. Note that a
  229.         non-zero poll word does not imply that a message will be available;
  230.         another task might have read the message if it was not directed to
  231.         a specific handle. The poll word must not be written to; it must only
  232.         be modified by the ARMEdit module.
  233.  
  234.  
  235. SWI "ARMEdit_TalkEnd" (&4BC42)
  236.  
  237.     Deregister a client task.
  238.     
  239.     On entry:
  240.     
  241.         R0 = The previously assigned handle for this client task.
  242.  
  243.     On exit:
  244.     
  245.         All registers preserved.
  246.     
  247.     Interrupts:
  248.     
  249.         Interrupt status is undefined.
  250.         Fast interrupts are enabled.
  251.  
  252.     Processor mode:
  253.     
  254.         Processor is in SVC mode.
  255.  
  256.     Re-entrancy:
  257.     
  258.         SWI is not re-entrant.
  259.  
  260.     Use:
  261.     
  262.         All applications that call ARMEdit_TalkStart must call this before
  263.         they terminate. This releases the message buffer and allows other
  264.         tasks to detect whether particular services are available.
  265.  
  266.  
  267. SWI "ARMEdit_TalkTX" (&4BC43)
  268.  
  269.     Send a message to another client task.
  270.     
  271.     On entry:
  272.     
  273.         R0 = Client handle for this task.
  274.         R1 = Either the ID or client handle for the recipient (if R2 not 0).
  275.         R2 = Pointer to block containing the message to send, or 0 to check if
  276.              the buffer already contains a message.
  277.  
  278.     On exit:
  279.     
  280.         R2 = Pointer to message buffer, or 0 if no message is waiting to be
  281.              delivered.
  282.     
  283.     Interrupts:
  284.     
  285.         Interrupt status is undefined.
  286.         Fast interrupts are enabled.
  287.  
  288.     Processor mode:
  289.     
  290.         Processor is in SVC mode.
  291.  
  292.     Re-entrancy:
  293.     
  294.         SWI is not re-entrant.
  295.  
  296.     Use:
  297.     
  298.         Send a message to another task. The destination task can be specified
  299.         using either it's ID or client handle. If the ID is specified then it
  300.         will be offered to each matching task that polls it until it is
  301.         acknowledged. A particular message is only offered to each task once.
  302.         When sending messages to PC software (ID = 0) the handle should
  303.         always be specified.
  304.         
  305.         Note that the message buffer for each task can only contain a single
  306.         message to send; if there is already a message waiting to be
  307.         delivered then it is overwritten. When multiple clients are used,
  308.         this SWI should first be called with R2 = 0 to check if a message
  309.         is still waiting. Broadcast messages are never cleared automatically.
  310.  
  311.  
  312. SWI "ARMEdit_TalkRX" (&4BC44)
  313.  
  314.     Check for any waiting messages for this client task.
  315.     
  316.     On entry:
  317.     
  318.         R0 = Client handle for this task.
  319.  
  320.     On exit:
  321.     
  322.         R0 = Pointer to block containing waiting message, or 0 if no messages
  323.              waiting.
  324.         R1 = Source ID.
  325.         R2 = Source client handle.
  326.     
  327.     Interrupts:
  328.     
  329.         Interrupt status is undefined.
  330.         Fast interrupts are enabled.
  331.  
  332.     Processor mode:
  333.     
  334.         Processor is in SVC mode.
  335.  
  336.     Re-entrancy:
  337.     
  338.         SWI is not re-entrant.
  339.  
  340.     Use:
  341.  
  342.         Check for any waiting messages. If none are available R0 contains 0
  343.         on exit, otherwise it contains a pointer to the first message. The
  344.         message should be checked, and if it is claimed ARMEdit_TalkAck or
  345.         ARMEdit_TalkReply should be called to prevent it being passed to
  346.         other clients. Any information required from the message must be read
  347.         or copied immediately, since the message could be overwritten by a
  348.         new message.
  349.         
  350.         The specified source client handle should be used for any reply;
  351.         unlike the ID it uniquely identifies a particular instantiation of a
  352.         client.
  353.         
  354.         If this call is successful then it should be called again; it is
  355.         possible for multiple messages to be pending for a single client.
  356.  
  357.  
  358. SWI "ARMEdit_TalkAck" (&4BC45)
  359.  
  360.     Claim the most recently read message.
  361.     
  362.     On entry:
  363.     
  364.         R0 = Client handle for this task.
  365.  
  366.     On exit:
  367.     
  368.         All registers preserved.
  369.     
  370.     Interrupts:
  371.     
  372.         Interrupt status is undefined.
  373.         Fast interrupts are enabled.
  374.  
  375.     Processor mode:
  376.     
  377.         Processor is in SVC mode.
  378.  
  379.     Re-entrancy:
  380.     
  381.         SWI is not re-entrant.
  382.  
  383.     Use:
  384.     
  385.         After reading a message with ARMEdit_TalkRX, this call should be
  386.         used to claim the message, and to prevent it being offered to other
  387.         clients. This should be used before calling any other SWIs from this
  388.         module.
  389.         
  390.         If the message was sent by the ARMEdit module then calling this SWI
  391.         has no effect; other clients still receive the message.
  392.  
  393.  
  394. SWI "ARMEdit_HPC" (&4BC46)
  395.  
  396.     Call an ARMEdit HPC service.
  397.     
  398.     On entry:
  399.     
  400.         R0 = Length of first input block.
  401.         R1 = Pointer to first input block.
  402.         R2 = Length of second input block.
  403.         R3 = Pointer to second input block.
  404.         R4 = Length of first output block.
  405.         R5 = Pointer to first output block.
  406.         R6 = Length of second output block.
  407.         R7 = Pointer to second output block.
  408.  
  409.     On exit:
  410.     
  411.         All registers preserved.
  412.  
  413.     Interrupts:
  414.     
  415.         Interrupt status is undefined.
  416.         Fast interrupts are enabled.
  417.  
  418.     Processor mode:
  419.     
  420.         Processor is in SVC mode.
  421.  
  422.     Re-entrancy:
  423.     
  424.         SWI is not re-entrant.
  425.  
  426.     Use:
  427.     
  428.         This call may either be used to test HPC services, or to provide
  429.         access to the routines from a system that does not support either of
  430.         the communications systems used normally by the ARMEdit system.
  431.         
  432.         For convenience the input and output data may be split into two
  433.         portions. Any length value may be zero to omit that portion. The
  434.         input data must be at least two bytes long to contain a valid ID.
  435.  
  436.  
  437. SWI "ARMEdit_Polling" (&4BC47)
  438.  
  439.     Control the multitasking speed of the PC card.
  440.     
  441.     On entry:
  442.     
  443.         R0 = Foreground speed, or -1 to read the current setting.
  444.         R1 = Background speed, or -1 to read the current setting.
  445.  
  446.     On exit:
  447.     
  448.         R0 = The current foreground speed.
  449.         R1 = The current background speed.
  450.     
  451.     Interrupts:
  452.     
  453.         Interrupt status is undefined.
  454.         Fast interrupts are enabled.
  455.  
  456.     Processor mode:
  457.     
  458.         Processor is in SVC mode.
  459.  
  460.     Re-entrancy:
  461.     
  462.         SWI is not re-entrant.
  463.  
  464.     Use:
  465.     
  466.         This call has has a similar use to *ARMEdit_Polling.
  467.  
  468.         Larger values increase the performance of the PC card at the expense
  469.         of slowing down the desktop. A value of 0 results in the normal
  470.         behaviour.
  471.  
  472.  
  473. SWI "ARMEdit_TalkReply" (&4BC48)
  474.  
  475.     Reply to a message from another client task.
  476.     
  477.     On entry:
  478.     
  479.         R0 = Client handle for this task.
  480.         R1 = The client handle for the recipient.
  481.         R2 = Pointer to block containing the message to send.
  482.  
  483.     On exit:
  484.     
  485.         All registers preserved.
  486.     
  487.     Interrupts:
  488.     
  489.         Interrupt status is undefined.
  490.         Fast interrupts are enabled.
  491.  
  492.     Processor mode:
  493.     
  494.         Processor is in SVC mode.
  495.  
  496.     Re-entrancy:
  497.     
  498.         SWI is not re-entrant.
  499.  
  500.     Use:
  501.     
  502.         This is like ARMEdit_TalkTX, except that the message is stored in the
  503.         destination task's message buffer. The destination task must be
  504.         specified by it's client handle; it is not possible to send the
  505.         message to an ID.
  506.         
  507.         The main use of this call is to support the easy creation of RISC OS
  508.         tasks acting as a server for multiple PC tasks.
  509.  
  510.  
  511. THINGS TO DO
  512.  
  513. The following are changes that may be made to the ARMEdit module sometime in
  514. the future.
  515.  
  516.     None at the moment!
  517.  
  518.  
  519. VERSION HISTORY
  520.  
  521. 0.00 (12-Nov-95)    Original development version.
  522.  
  523. 0.01 (14-Nov-95)    Fixed bugs in file handling. Removed stray debugging code.
  524.                     Sets variable for scrap directory and ensure it exists.
  525.  
  526. 0.02 (15-Nov-95)    Included extra command to display PC front-end version.
  527.                     Fixed workspace handling for *commands. (Oops!)
  528.  
  529. 0.03 (17-Nov-95)    Uses correct HPC service identifier.
  530.                     Includes development versions of device driver support.
  531.  
  532. 0.04 (21-Nov-95)    Implemented the *commands and real HPC support.
  533.  
  534. 0.06 (22-Dec-95)    Added SWI to control the PC front-end.
  535.  
  536. 0.07 (28-Dec-95)    Added message passing protocol.
  537.  
  538. 1.00 (12-Jan-96)    First official release version.
  539.  
  540. 1.01 (11-Feb-96)    Does not crash when no DOSMap mappings defined.
  541.                     Module can be loaded after new versions of the PC front-end.
  542.  
  543. 1.02 (06-Aug-96)    Some memory management moved to a dynamic area if available.
  544.                     Device driver support added.
  545.                     Routines to convert date and time stamps included.
  546.                     Added SWI to call internal HPC services.
  547.                     Corrected command help texts.
  548.                     Added command to set multitasking speed of PC front-end.
  549.                     Provided mechanism for checking delivery of messages.
  550.  
  551. 1.03 (21-Feb-97)    Added SWI to set multitasking speed of PC front-end.
  552.                     Added SWI to reply to a message.
  553.                     Broadcast messages from the ARMEdit module are now sent.
  554.                     Speed control now works correctly with PC front-end 2v02.
  555.                     Extended *ARMEdit_DevicesRelog to force immediate relog.