home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsa / armedit / Docs / Module < prev    next >
Encoding:
Text File  |  1996-01-12  |  10.6 KB  |  375 lines
  1. File        : Module
  2. Date        : 12-Jan-96
  3. Author      : © A.Thoukydides, 1995, 1996
  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. For any of the programs to work it is necessary to load the ARMEdit module
  14. before starting the PC front-end.
  15.  
  16. The current version of this module will work with versions of the PC
  17. front-end software 1.87 and above. However, significantly better performace
  18. will be obtained if version 2.00 or above is used. Upgrades are available
  19. from both Acorn's (ftp.acorn.co.uk) and Aleph One's (ftp.ant.co.uk) ftp
  20. sites.
  21.  
  22.  
  23. SYSTEM VARIABLES
  24.  
  25. The ARMEdit module sets and uses the following system variables:
  26.  
  27.     ARMEdit$Path
  28.     
  29.         Path used to access Messages file. This is normally set to point to
  30.         the file contained within the module and placed in ResourceFS.
  31.         
  32.     
  33.     ARMEdit$ScrapDir
  34.     
  35.         Directory used for temporary files. This is normally set to
  36.         <Wimp$Scrap>.ARMEdit, but may be changed if required. If there is
  37.         sufficient memory in the computer then better performance would
  38.         result from placing this in a RAM disc.
  39.         
  40.         The module sets and uses this variable (if not already defined)
  41.         during initialisation. Hence it is necessary for <Wimp$Scrap> to be
  42.         defined before the module is loaded.
  43.     
  44.  
  45. *COMMANDS
  46.  
  47. The following *commands are provided by the ARMEdit module:
  48.         
  49.  
  50.     *ARMEdit_Clients
  51.     
  52.         This command displays details of the clients that have registered
  53.         with the ARMEdit module for communication purposes.
  54.  
  55.     *ARMEdit_DOSMap
  56.     
  57.         This command updates the cached list of mappings between DOS
  58.         extensions and RISC OS filetypes. These details are read initially
  59.         from DOSFS, but may be re-read at any time using this command.
  60.         
  61.  
  62.     *ARMEdit_Files
  63.  
  64.         This command displays details of the RISC OS files currently open for
  65.         PC software. For each open file the file handle and filename is
  66.         displayed. There is also a field that indicates whether the file will
  67.         automatically be deleted when it is closed (either explicitly by the
  68.         PC software, or when the PC is reset or quit).
  69.         
  70.  
  71.     *ARMEdit_Memory
  72.  
  73.         This command displays details of the RISC OS memory currently being
  74.         used by PC software. For each block of memory claimed the base
  75.         address and size of the block is displayed.
  76.         
  77.         The memory is currently allocated from the RMA, but a header is
  78.         attached to the start of each block. Hence the address displayed is
  79.         not the start of a heap block. The information in the header is used
  80.         to automatically release the memory when the PC is reset or quit if
  81.         the PC software fails to do so.
  82.  
  83.  
  84.     *ARMEdit_Version
  85.     
  86.         This command displays the version numbers of the data structures used
  87.         by the most recently used PC front-end. It also displays the range of
  88.         versions catered for by this version of the module.
  89.  
  90.  
  91. SWIs
  92.  
  93. The following SWIs are provided by the ARMEdit module. For more details
  94. regarding the use of the communciations SWIs see the Code documentation.
  95.  
  96.  
  97. SWI "ARMEdit_ControlPC" (&4BC40)
  98.  
  99.     Control the PC front-end.
  100.     
  101.     On entry:
  102.     
  103.         R0 = Operation to perform:
  104.         
  105.                 0   Suspend full screen mode
  106.                 1   Freeze running in a window
  107.                 2   Reset the PC
  108.                 3   Quit the front-end
  109.  
  110.     On exit:
  111.     
  112.         All registers preserved.
  113.     
  114.     Interrupts:
  115.     
  116.         Interrupt status is undefined.
  117.         Fast interrupts are enabled.
  118.  
  119.     Processor mode:
  120.     
  121.         Processor is in SVC mode.
  122.  
  123.     Re-entrancy:
  124.     
  125.         SWI is not re-entrant.
  126.  
  127.     Use:
  128.     
  129.         This call allows the PC front-end to be controlled. Note that if the
  130.         PC front-end is not the current application then this will only take
  131.         effect the next time the front-end is paged in.
  132.         
  133.         Note that suspending full screen mode only starts execution in a
  134.         window if enabled by the current configuration.
  135.  
  136.  
  137. SWI "ARMEdit_TalkStart" (&4BC41)
  138.  
  139.     Register a new client task.
  140.     
  141.     On entry:
  142.     
  143.         R0 = Pre-allocated ID for this task.
  144.         R1 = Flags (see below).
  145.         R2 = Pointer to a function to be called when a message is available,
  146.              or 0 for none.
  147.         R3 = Value for R12 to contain when function pointed to by R2 is
  148.              called.
  149.  
  150.     On exit:
  151.     
  152.         R0 = A unique client handle.
  153.         R1 = Pointer to a poll word for this task.
  154.     
  155.     Interrupts:
  156.     
  157.         Interrupt status is undefined.
  158.         Fast interrupts are enabled.
  159.  
  160.     Processor mode:
  161.     
  162.         Processor is in SVC mode.
  163.  
  164.     Re-entrancy:
  165.     
  166.         SWI is not re-entrant.
  167.  
  168.     Use:
  169.     
  170.         An application that provides services to PC software should call this
  171.         when it is starting. A message buffer is allocated and a unique
  172.         handle for this task assigned. This handle should be stored and used
  173.         in all other calls relating to this task.
  174.         
  175.         The currently defined flag bits are:
  176.         
  177.             Bit     Meaning if set
  178.             
  179.             0       Messages from the ARMEdit module are required.
  180.         
  181.         All other bits should be set to 0 to allow for future expansion.
  182.         
  183.         The poll word is initially set to zero. When there is potentially a
  184.         message waiting for this task the poll word is set to a non-zero
  185.         value. The poll word is cleared when either the message has been
  186.         read, or no message is available for some other reason. Note that a
  187.         non-zero poll word does not imply that a message will be available;
  188.         another task might have read the message if it was not directed to
  189.         a specific handle. The poll word must not be written to; it must only
  190.         be modified by the ARMEdit module.
  191.  
  192.  
  193. SWI "ARMEdit_TalkEnd" (&4BC42)
  194.  
  195.     Deregister a client task.
  196.     
  197.     On entry:
  198.     
  199.         R0 = The previously assigned handle for this client task.
  200.  
  201.     On exit:
  202.     
  203.         All registers preserved.
  204.     
  205.     Interrupts:
  206.     
  207.         Interrupt status is undefined.
  208.         Fast interrupts are enabled.
  209.  
  210.     Processor mode:
  211.     
  212.         Processor is in SVC mode.
  213.  
  214.     Re-entrancy:
  215.     
  216.         SWI is not re-entrant.
  217.  
  218.     Use:
  219.     
  220.         All applications that call ARMEdit_TalkStart must call this before
  221.         they terminate. This releases the message buffer and allows other
  222.         tasks to detect whether particular services are available.
  223.  
  224.  
  225. SWI "ARMEdit_TalkTX" (&4BC43)
  226.  
  227.     Send a message to another client task.
  228.     
  229.     On entry:
  230.     
  231.         R0 = Client handle for this task.
  232.         R1 = Either the ID or client handle for the recipient.
  233.         R2 = Pointer to block containing the message to send.
  234.  
  235.     On exit:
  236.     
  237.         All registers preserved.
  238.     
  239.     Interrupts:
  240.     
  241.         Interrupt status is undefined.
  242.         Fast interrupts are enabled.
  243.  
  244.     Processor mode:
  245.     
  246.         Processor is in SVC mode.
  247.  
  248.     Re-entrancy:
  249.     
  250.         SWI is not re-entrant.
  251.  
  252.     Use:
  253.     
  254.         Send a message to another task. The destination task can be specified
  255.         using either it's ID or client handle. If the ID is specified then it
  256.         will be offered to each matching task that polls it until it is
  257.         acknowledged. A particular message is only offered to each task once.
  258.         When sending messages to PC software (ID = 0) the handle should
  259.         always be specified.
  260.         
  261.         Note that the message buffer for each task can only contain a single
  262.         message to send; if there is already a message waiting to be
  263.         delivered then it is overwritten.
  264.  
  265.  
  266. SWI "ARMEdit_TalkRX" (&4BC44)
  267.  
  268.     Check for any waiting messages for this client task.
  269.     
  270.     On entry:
  271.     
  272.         R0 = Client handle for this task.
  273.  
  274.     On exit:
  275.     
  276.         R0 = Pointer to block containing waiting message, or 0 if no messages
  277.              waiting.
  278.         R1 = Source ID.
  279.         R2 = Source client handle.
  280.     
  281.     Interrupts:
  282.     
  283.         Interrupt status is undefined.
  284.         Fast interrupts are enabled.
  285.  
  286.     Processor mode:
  287.     
  288.         Processor is in SVC mode.
  289.  
  290.     Re-entrancy:
  291.     
  292.         SWI is not re-entrant.
  293.  
  294.     Use:
  295.  
  296.         Check for any waiting messages. If none are available R0 contains 0
  297.         on exit, otherwise it contains a pointer to the first message. The
  298.         message should be checked, and if it is claimed ARMEdit_TalkAck
  299.         should be called to prevent it being passed to other clients. Any
  300.         information required from the message must be read or copied
  301.         immediately, since the message could be overwritten by a new message.
  302.         
  303.         The specified source client handle should be used for any reply;
  304.         unlike the ID it uniquely identifies a particular instantiation of a
  305.         client.
  306.         
  307.         If this call is successful then it should be called again; it is
  308.         possible for multiple messages to be pending for a single client.
  309.  
  310.  
  311. SWI "ARMEdit_TalkAck" (&4BC45)
  312.  
  313.     Claim the most recently read message.
  314.     
  315.     On entry:
  316.     
  317.         R0 = Client handle for this task.
  318.  
  319.     On exit:
  320.     
  321.         All registers preserved.
  322.     
  323.     Interrupts:
  324.     
  325.         Interrupt status is undefined.
  326.         Fast interrupts are enabled.
  327.  
  328.     Processor mode:
  329.     
  330.         Processor is in SVC mode.
  331.  
  332.     Re-entrancy:
  333.     
  334.         SWI is not re-entrant.
  335.  
  336.     Use:
  337.     
  338.         After reading a message with ARMEdit_TalkRX, this call should be
  339.         used to claim the message, and to prevent it being offered to other
  340.         clients. This should be used before calling any other SWIs from this
  341.         module.
  342.         
  343.         If the message was sent by the ARMEdit module then calling this SWI
  344.         has no effect; other clients still receive the message.
  345.  
  346.  
  347. THINGS TO DO
  348.  
  349. The following are changes that may be made to the ARMEdit module sometime in
  350. the future.
  351.  
  352.     None at the moment!
  353.  
  354.  
  355. VERSION HISTORY
  356.  
  357. 0.00 (12-Nov-95)    Original development version.
  358.  
  359. 0.01 (14-Nov-95)    Fixed bugs in file handling. Removed stray debugging code.
  360.                     Sets variable for scrap directory and ensure it exists.
  361.  
  362. 0.02 (15-Nov-95)    Included extra command to display PC front-end version.
  363.                     Fixed workspace handling for *commands. (Oops!)
  364.  
  365. 0.03 (17-Nov-95)    Uses correct HPC service identifier.
  366.                     Includes development versions of device driver support.
  367.  
  368. 0.04 (21-Nov-95)    Implemented the *commands and real HPC support.
  369.  
  370. 0.06 (22-Dec-95)    Added SWI to control the PC front-end.
  371.  
  372. 0.07 (28-Dec-95)    Added message passing protocol.
  373.  
  374. 1.00 (12-Jan-96)    First official release version.
  375.