home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / HPC < prev    next >
Text File  |  1997-02-21  |  20KB  |  735 lines
  1. File        : HPC
  2. Date        : 21-Feb-97
  3. Author      : © A.Thoukydides, 1995, 1996, 1997
  4. Description : High-level Procedure Call (HPC) services implemented by the
  5.               ARMEdit module.
  6.  
  7.  
  8. INTRODUCTION
  9.  
  10. The ARMEdit module provides a number of HPC services. To allow development to
  11. start before HPC is included in the PC front-end software, and to support
  12. earlier releases of the front-end software, a simplified interface via I/O
  13. ports is also supported.
  14.  
  15. All of the services in this document use the HPC service identifier &105
  16. which has been allocated by Aleph One.
  17.  
  18.  
  19. I/O PORT ACCESS
  20.  
  21. The following I/O port assignments are currently used:
  22.  
  23.     &2E0    PORT_STATUS Word read
  24.     &2E0    PORT_CMD    Word write
  25.     &2E2    PORT_DATA   Byte or word read/write
  26.  
  27. The following sequence of operations should occur to perform an HPC call:
  28.  
  29.     Read PORT_STATUS. The possible return codes are:
  30.     
  31.         &454D   System is available and ready.
  32.  
  33.         &4D45   System is currently busy processing another HPC call, and
  34.                 cannot currently be used for another call.
  35.  
  36.         Any other code indicates that the service is not available.
  37.  
  38.     Write &0000 to PORT_CMD to start transfer of data.
  39.  
  40.     Write the HPC packet data to PORT_DATA as either bytes or words.
  41.  
  42.     Write &0001 to PORT_CMD to perform the HPC call.
  43.     
  44.     Write &0002 to PORT_CMD to start reading the reply.
  45.     
  46.     Read the HPC reply packet from PORT_DATA as either bytes or words.
  47.     
  48.     Write &0003 to PORT_CMD to reset the HPC system.
  49.  
  50. The port based HPC packets have the same 16384 byte limit that proper HPC
  51. packets have.
  52.  
  53. Note that only HPC services provided by the ARMEdit module can be called
  54. using this I/O port system; other services can only be called via the normal
  55. HPC system. However, the HPC identifier is still checked.
  56.  
  57.  
  58. HPC CALLS
  59.  
  60. For details of making HPC calls directly (which is potentially much more
  61. efficient) contact Aleph One, as the information is covered by a Non
  62. Disclosure Agreement.
  63.  
  64.  
  65. RETURN CODES
  66.  
  67. All of the HPC calls place a 4 byte return code at the start of the return
  68. block. The generic values are
  69.  
  70.     &0000   The operation was successful.
  71.  
  72.     &0001   The operation failed. The exact meaning of this depends upon the
  73.             reason code, but in general it indicates that the rest of the
  74.             return block is invalid.
  75.     
  76.     &FFFF   Service or reason code is unknown.
  77.  
  78. See the individual reason codes for details of any other codes returned, and
  79. any contents of the remainder of the return block.
  80.  
  81.  
  82. HPC_ARMEDIT_SWI
  83.  
  84.     Calls a specified RISC OS SWI by number. The SWI is always called with
  85.     the X (error returning) bit set.
  86.     
  87.     Data sent:
  88.     
  89.         Offset  Size    Description
  90.         
  91.         0       2       HPC service ID.
  92.         2       2       Reason code = &0000.
  93.         4       4       SWI number.
  94.         8       40      Values for registers R0 to R9 on entry to the SWI.
  95.     
  96.     Data returned:
  97.     
  98.         Offset  Size    Description
  99.         
  100.         0       4       Return code.
  101.         4       256     RISC OS style error block returned by SWI if the
  102.                         return code is &0001.
  103.         260     40      Values of registers R0 to R9 on exit from the SWI if
  104.                         the return code is &0000.
  105.  
  106.  
  107. HPC_ARMEDIT_READ
  108.  
  109.     Read ARM memory.
  110.     
  111.     Data sent:
  112.     
  113.         Offset  Size    Description
  114.         
  115.         0       2       HPC service ID.
  116.         2       2       Reason code = &0001.
  117.         4       4       Start address of memory to read.
  118.         8       4       Number of bytes to read. (n <= 16380)
  119.  
  120.     Data returned:
  121.     
  122.         Offset  Size    Description
  123.         
  124.         0       4       Return code.
  125.         4       n       The contents of the specified memory.
  126.  
  127.  
  128. HPC_ARMEDIT_WRITE
  129.  
  130.     Write ARM memory.
  131.     
  132.     Data sent:
  133.     
  134.         Offset  Size    Description
  135.         
  136.         0       2       HPC service ID.
  137.         2       2       Reason code = &0002.
  138.         4       4       Start address of memory to read.
  139.         8       4       Number of bytes to write. (n <= 16372)
  140.         12      n       The data to write.
  141.  
  142.     Data returned:
  143.     
  144.         Offset  Size    Description
  145.         
  146.         0       4       Return code.
  147.  
  148.  
  149. HPC_ARMEDIT_ALLOC
  150.  
  151.     Claim a block of ARM memory. This is automatically released when the PC
  152.     is shutdown or reset, but it is better to free it when no longer required
  153.     using HPC_ARMEDIT_FREE.
  154.         
  155.     Data sent:
  156.     
  157.         Offset  Size    Description
  158.         
  159.         0       2       HPC service ID.
  160.         2       2       Reason code = &0003.
  161.         4       4       Amount of memory to claim.
  162.  
  163.     Data returned:
  164.     
  165.         Offset  Size    Description
  166.         
  167.         0       4       Return code.
  168.         4       4       Address of the block of memory allocated.
  169.  
  170.  
  171. HPC_ARMEDIT_FREE
  172.  
  173.     Release a block of ARM memory previously claimed using HPC_ARMEDIT_ALLOC.
  174.         
  175.     Data sent:
  176.     
  177.         Offset  Size    Description
  178.         
  179.         0       2       HPC service ID.
  180.         2       2       Reason code = &0004.
  181.         4       4       The address of the block of memory.
  182.  
  183.     Data returned:
  184.     
  185.         Offset  Size    Description
  186.         
  187.         0       4       Return code.
  188.  
  189.  
  190. HPC_ARMEDIT_EXTTYPE
  191.  
  192.     Convert a DOS extension into a RISC OS filetype.
  193.         
  194.     Data sent:
  195.     
  196.         Offset  Size    Description
  197.         
  198.         0       2       HPC service ID.
  199.         2       2       Reason code = &0005.
  200.         4       4       The extension in upper case padded with 0 bytes to
  201.                         four characters.
  202.  
  203.     Data returned:
  204.     
  205.         Offset  Size    Description
  206.         
  207.         0       4       Return code.
  208.         4       4       The RISC OS filetype.
  209.  
  210.  
  211. HPC_ARMEDIT_TYPEEXT
  212.  
  213.     Convert a RISC OS filetype into a DOS extension.
  214.         
  215.     Data sent:
  216.     
  217.         Offset  Size    Description
  218.         
  219.         0       2       HPC service ID.
  220.         2       2       Reason code = &0006.
  221.         4       4       The RISC OS filetype.
  222.  
  223.     Data returned:
  224.     
  225.         Offset  Size    Description
  226.         
  227.         0       4       Return code.
  228.         4       4       The extension in upper case padded with 0 bytes to
  229.                         four characters.
  230.  
  231.  
  232. HPC_ARMEDIT_FOPEN
  233.  
  234.     Open a RISC OS file. This is automatically closed when the PC is shutdown
  235.     or reset, but it is better to close it when no longer required using
  236.     HPC_ARMEDIT_CLOSE. A file opened using this call should not be closed
  237.     using RISC OS routines directly.
  238.         
  239.     Data sent:
  240.     
  241.         Offset  Size    Description
  242.         
  243.         0       2       HPC service ID.
  244.         2       2       Reason code = &0007.
  245.         4       4       -1 to open existing file, or initial size of file to
  246.                         create a new one.
  247.         8       4       Non-zero to automatically delete the file when closed.
  248.         12      n       Name of file to open.
  249.  
  250.     Data returned:
  251.     
  252.         Offset  Size    Description
  253.         
  254.         0       4       Return code.
  255.         4       4       RISC OS file handle.
  256.  
  257.  
  258. HPC_ARMEDIT_FCLOSE
  259.  
  260.     Close a RISC OS file previously opened using HPC_ARMEDIT_OPEN. The file
  261.     is deleted if specified when the file was opened.
  262.         
  263.     Data sent:
  264.     
  265.         Offset  Size    Description
  266.         
  267.         0       2       HPC service ID.
  268.         2       2       Reason code = &0008.
  269.         4       4       RISC OS file handle.
  270.  
  271.     Data returned:
  272.     
  273.         Offset  Size    Description
  274.         
  275.         0       4       Return code.
  276.  
  277.  
  278. HPC_ARMEDIT_FREAD
  279.  
  280.     Read from a RISC OS file.
  281.         
  282.     Data sent:
  283.     
  284.         Offset  Size    Description
  285.         
  286.         0       2       HPC service ID.
  287.         2       2       Reason code = &0009.
  288.         4       4       RISC OS file handle.
  289.         8       4       Sequential file pointer for start of block, or -1 for
  290.                         current position.
  291.         12      4       Number of bytes to read.
  292.  
  293.     Data returned:
  294.     
  295.         Offset  Size    Description
  296.         
  297.         0       4       Return code.
  298.         4       4       Number of bytes read.
  299.         8       n       The data read from the file.
  300.  
  301.  
  302.