home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / Module < prev    next >
Text File  |  1997-02-21  |  17KB  |  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.     I