The Datafile PD-CD 5

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / HPC < prev next >

Wrap

Text File | 1997-02-21 | 19.1 KB | 735 lines

File : HPC Date : 21-Feb-97 Author : © A.Thoukydides, 1995, 1996, 1997 Description : High-level Procedure Call (HPC) services implemented by the ARMEdit module. INTRODUCTION The ARMEdit module provides a number of HPC services. To allow development to start before HPC is included in the PC front-end software, and to support earlier releases of the front-end software, a simplified interface via I/O ports is also supported. All of the services in this document use the HPC service identifier &105 which has been allocated by Aleph One. I/O PORT ACCESS The following I/O port assignments are currently used: &2E0 PORT_STATUS Word read &2E0 PORT_CMD Word write &2E2 PORT_DATA Byte or word read/write The following sequence of operations should occur to perform an HPC call: Read PORT_STATUS. The possible return codes are: &454D System is available and ready. &4D45 System is currently busy processing another HPC call, and cannot currently be used for another call. Any other code indicates that the service is not available. Write &0000 to PORT_CMD to start transfer of data. Write the HPC packet data to PORT_DATA as either bytes or words. Write &0001 to PORT_CMD to perform the HPC call. Write &0002 to PORT_CMD to start reading the reply. Read the HPC reply packet from PORT_DATA as either bytes or words. Write &0003 to PORT_CMD to reset the HPC system. The port based HPC packets have the same 16384 byte limit that proper HPC packets have. Note that only HPC services provided by the ARMEdit module can be called using this I/O port system; other services can only be called via the normal HPC system. However, the HPC identifier is still checked. HPC CALLS For details of making HPC calls directly (which is potentially much more efficient) contact Aleph One, as the information is covered by a Non Disclosure Agreement. RETURN CODES All of the HPC calls place a 4 byte return code at the start of the return block. The generic values are &0000 The operation was successful. &0001 The operation failed. The exact meaning of this depends upon the reason code, but in general it indicates that the rest of the return block is invalid. &FFFF Service or reason code is unknown. See the individual reason codes for details of any other codes returned, and any contents of the remainder of the return block. HPC_ARMEDIT_SWI Calls a specified RISC OS SWI by number. The SWI is always called with the X (error returning) bit set. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0000. 4 4 SWI number. 8 40 Values for registers R0 to R9 on entry to the SWI. Data returned: Offset Size Description 0 4 Return code. 4 256 RISC OS style error block returned by SWI if the return code is &0001. 260 40 Values of registers R0 to R9 on exit from the SWI if the return code is &0000. HPC_ARMEDIT_READ Read ARM memory. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0001. 4 4 Start address of memory to read. 8 4 Number of bytes to read. (n <= 16380) Data returned: Offset Size Description 0 4 Return code. 4 n The contents of the specified memory. HPC_ARMEDIT_WRITE Write ARM memory. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0002. 4 4 Start address of memory to read. 8 4 Number of bytes to write. (n <= 16372) 12 n The data to write. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_ALLOC Claim a block of ARM memory. This is automatically released when the PC is shutdown or reset, but it is better to free it when no longer required using HPC_ARMEDIT_FREE. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0003. 4 4 Amount of memory to claim. Data returned: Offset Size Description 0 4 Return code. 4 4 Address of the block of memory allocated. HPC_ARMEDIT_FREE Release a block of ARM memory previously claimed using HPC_ARMEDIT_ALLOC. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0004. 4 4 The address of the block of memory. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_EXTTYPE Convert a DOS extension into a RISC OS filetype. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0005. 4 4 The extension in upper case padded with 0 bytes to four characters. Data returned: Offset Size Description 0 4 Return code. 4 4 The RISC OS filetype. HPC_ARMEDIT_TYPEEXT Convert a RISC OS filetype into a DOS extension. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0006. 4 4 The RISC OS filetype. Data returned: Offset Size Description 0 4 Return code. 4 4 The extension in upper case padded with 0 bytes to four characters. HPC_ARMEDIT_FOPEN Open a RISC OS file. This is automatically closed when the PC is shutdown or reset, but it is better to close it when no longer required using HPC_ARMEDIT_CLOSE. A file opened using this call should not be closed using RISC OS routines directly. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0007. 4 4 -1 to open existing file, or initial size of file to create a new one. 8 4 Non-zero to automatically delete the file when closed. 12 n Name of file to open. Data returned: Offset Size Description 0 4 Return code. 4 4 RISC OS file handle. HPC_ARMEDIT_FCLOSE Close a RISC OS file previously opened using HPC_ARMEDIT_OPEN. The file is deleted if specified when the file was opened. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0008. 4 4 RISC OS file handle. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_FREAD Read from a RISC OS file. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0009. 4 4 RISC OS file handle. 8 4 Sequential file pointer for start of block, or -1 for current position. 12 4 Number of bytes to read. Data returned: Offset Size Description 0 4 Return code. 4 4 Number of bytes read. 8 n The data read from the file. HPC_ARMEDIT_FWRITE Write to a RISC OS file. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &000A. 4 4 RISC OS file handle. 8 4 Sequential file pointer for start of block, or -1 for current position. 12 4 Number of bytes to write. 16 n The data to write to the file. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_TALK_START Register a new client task. Note that a client ID of 0 is assumed. It does not make sense being able to request notification of reset or shutdown. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &000B. Data returned: Offset Size Description 0 4 Return code. 4 4 A unique client handle. HPC_ARMEDIT_TALK_END Deregister a client task. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &000C. 4 4 The previously assigned handle for this client task. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_TALK_TX Send a message to another client task. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &000D. 4 4 Client handle for this task. 8 4 Either the ID or client handle for the recipient. 12 1024 The message to send. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_TALK_RX Check for any waiting messages for this client task. The return code is failure if there is no message waiting. There is no acknowledge call since all messages to PC software should be addressed to a particular handle. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &000E. 4 4 Client handle for this task. Data returned: Offset Size Description 0 4 Return code. 4 4 Source ID. 8 4 Source client handle. 12 1024 The waiting message. HPC_ARMEDIT_DEVICE_INITIALISE Called during initialisation of device driver to obtain a start-up banner message and choose the number of devices. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &000F. 4 1 Drive number for first unit of this driver. 5 256 Text after equals sign on CONFIG.SYS line that loaded this driver. Data returned: Offset Size Description 0 4 Return code. 4 4 Number of devices supported. 8 256 Text of message terminated by a "$" character. HPC_ARMEDIT_DEVICE_BPB Construct a BIOS Parameter Block (BPB) for a device driver. This also informs ARMEdit that the disc contents could be changed. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0010. 4 1 Unit code (drive number), or -1 for initialisation. Data returned: Offset Size Description 0 4 Return code. 4 13 The BIOS parameter block. HPC_ARMEDIT_DEVICE_CHANGED Perform a media check for a device driver. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0011. 4 1 Unit code (drive number). Data returned: Offset Size Description 0 4 Return code. 4 4 The media change code: -1 Disc has been changed. 0 Don't know if disc has been changed. 1 Disc has not been changed. HPC_ARMEDIT_DEVICE_READ Read an emulated disc sector for a device driver. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0012. 4 1 Unit code (drive number). 5 2 Sector number. Data returned: Offset Size Description 0 4 Return code. 4 n The data read from the sector. HPC_ARMEDIT_DEVICE_WRITE Write an emulated disc sector for a device driver. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0013. 4 1 Unit code (drive number). 5 2 Sector number. 7 1 Dummy data to pad to word boundary. 8 n The data to write to the sector. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_DATE_TO_DOS Convert a time and date from the standard RISC OS 5 bytes format to the 4 byte DOS equivalent. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0014. 4 5 Centiseconds since 00:00:00 on January 1 1900. Data returned: Offset Size Description 0 4 Return code. 4 4 2 byte time (hhhhhmmmmmmsssss). 8 4 2 byte date (yyyyyyymmmmddddd). HPC_ARMEDIT_DATE_TO_RISCOS Convert a time and date from the standard DOS 4 byte format to the 5 byte RISC OS equivalent. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0015. 4 2 2 byte time (hhhhhmmmmmmsssss). 6 2 2 byte date (yyyyyyymmmmddddd). Data returned: Offset Size Description 0 4 Return code. 4 5 Centiseconds since 00:00:00 on January 1 1900. HPC_ARMEDIT_OSCLI_START Start executing a specified *command. The input and output from the command are redirected. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0016. 4 256 The command to execute. Data returned: Offset Size Description 0 4 Return code. 4 4 Handle for this command. HPC_ARMEDIT_OSCLI_POLL Continue execution of a *command. This should only include input data if requested by the previous HPC_ARMEDIT_OSCLI_POLL reply, otherwise characters may get lost. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0017. 4 4 Command handle. 8 4 Number of bytes to input. 12 256 Up to 256 bytes of input. Data returned: Offset Size Description 0 4 Return code. 4 4 Status: 0 Active. 1 Command has finished. 2 Waiting for input. 8 4 Number of bytes to output. 12 256 Up to 256 bytes of output. HPC_ARMEDIT_OSCLI_END Terminate execution of a *command. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0018. 4 4 Command handle. Data returned: Offset Size Description 0 4 Return code. 4 256 RISC OS style error block returned by SWI if the return code is &0001. HPC_ARMEDIT_TALK_REPLY Reply to a message from another client task. This is like HPC_ARMEDIT_TALK_TX, except that the message is stored in the destination task's buffer. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &0019. 4 4 Client handle for this task. 8 4 The client handle for the recipient. 12 1024 The message to send. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_FASTER Prevent multitasking to speed up operations. This should be called to reenable normal operation after the operation is completed. A sensible way to use this is with a value of 100 (for 1 second), called on a regular basis during the operation. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &001A. 4 4 Centiseconds to disable multitasking for, or 0 to restore normal operation. Data returned: Offset Size Description 0 4 Return code. HPC_ARMEDIT_TEMPORARY Produce a unique filename for a temporary RISC OS file. Data sent: Offset Size Description 0 2 HPC service ID. 2 2 Reason code = &001B. Data returned: Offset Size Description 0 4 Return code. 4 256 Suggested canonicalised filename. THINGS TO DO The following are changes that may be made to the HPC services sometime in the future. None at the moment! VERSION HISTORY 0.00 (12-Nov-95) Original development version. 0.01 (14-Nov-95) No changes to HPC. 0.02 (15-Nov-95) No changes to HPC. 0.03 (17-Nov-95) Uses correct HPC service identifier. 0.04 (21-Nov-95) Slightly more experimental device driver support. Real HPC system implemented. 0.07 (28-Dec-95) Added message passing protocol. 1.00 (15-Dec-95) First official release version. 1.01 (11-Mar-96) Version number updated to match the module. 1.02 (27-May-96) Implemented device driver calls. Added commands to convert between date and time formats. Included SWI for use by Acorn's software PC emulator. 1.03 (21-Feb-97) Added ability to reply to messages. Included ability to speed up operations when multitasking. Temporary RISC OS filenames can now be generated.