.. include:: header.txt .. comment Heading levels: *** top and bottom , === bottom , --- bottom, +++ bottom ***************** AUXROMs Internals ***************** Make sure we cover these topics ............................... * list of all the architectural details * Calling conventions * Mailboxes and Ownership * Flowchart of transactions * Impact of DMA on interrupts * can't do DMA to memory we provide (85A only) * Performance measurements * File sizes * File name constraints * Other gotchas During Boot, the HP-85 only sees AUXROM ID 361 (octal). This image contains the correct signature in the bottom two bytes, the correct checksums in the top 4 bytes, and during initializing, it registers all the Keywords supported by all the AUXROMs. (A requirement of AUXROM 361 is that it is the gateway for all AUXROM functionality, and as such it must register all the Keywords. There is an upper limit of 254 Keywords.) The 13 additional AUXROM IDs are managed by AUXROM 361. These additional AUXROMs are not detected at boot time because they deliberately do not have the correct second byte of the ROM signature at address 060001. This allows for more ROM based software than the HP-85 was designed to support. All 14 AUXROM IDs have the following: * Unique ROM Regions for the lower 4096 bytes from addresses 060000 to 067777 * Unique ROM Regions for the upper 1024 bytes from addresses 076000 to 077777 |br| (but see `Fast inter-ROM jumps`_ ) * A shared RAM area of 3072 bytes from address 070000 to 075777. This is nominally partitioned into six 256 byte blocks and one 1024 byte block. :ref:`See this diagram. ` This partitioning is not enforced by the hardware, so alternative partitioning plans are possible, provided the firmware on EBTKS and AUXROM use the same plan This RAM region (in what is normally considered ROM space) is visible to the HP-85 processor whenever any of the 14 AUXROM IDs are in the RSELEC register. AUXROM Shared RAM: Buffers .......................... There are 7 **Buffers** defined in the shared AUXROM RAM. As shown in the above diagram and table, 6 of the buffers are 256 bytes each, and there is 1 buffer of 1024 bytes. The buffers and their associated Length and Usage are numbered 0 to 6. These buffers are used to pass data between the HP-85 and EBTKS. Each buffer has an associated Mailbox (1 byte), Length (2 bytes), and Usage Code (2 bytes). AUXROM Shared RAM: Mailboxes ............................ There are 32 **Mailbox** locations, each 1 byte, that should only have the value 0 or 1. Mailboxes 0 to 6 are pre-assigned to manage access to Buffers 0 to 6. The remaining mailboxes (7 to 31) are available for as yet unwritten Keywords that may need to manage shared resources. I'll hold off the rest of the description of mailboxes until after the next few paragraphs. AUXROM Shared RAM: Buffer Lengths ................................. There are 8 **Buffer Lengths** that hold a 16 bit integer and are associated with their respective buffers (0 to 6). The 8th one is currently a spare. Total 16 bytes. AUXROM Shared RAM: Usage Code ............................. There are 8 **Usage Codes** that hold a 16 bit integer and are associated with their respective buffers (0 to 6). The 8th one is currently a spare. Total 16 bytes. Usage Codes are discussed in the :ref:`AUXROM Keywords` section. Briefly they are used to identify which keyword is to be processed, and on return, the success/failure of the processing the keyword. How Mailboxes, Buffers, Buffer Lengths, and Usage Codes Work ............................................................ The shared memory area contains 7 buffers (6 * 256 bytes and 1 * 1024). For each buffer there is * A Buffer of either 256 or 1024 bytes * A 1 byte Mailbox. Values 0 or 1 * A 2 byte Buffer Length. Values 0 to 256 or 0 to 1024 * A 2 byte Buffer Usage. Values 0 to N Buffers are numbered 0 to 6, as are the Mailboxes, Buffer Lengths, and Buffer Usages. Each resource uses contiguous memory, i.e. all the mailboxes are contiguous. This diagram :ref:`Detailed view of the AUXROM shared RAM area` gives the addresses for each resource, with the lowest address for each resource being for Buffer 0, or its associated Mailbox, Length, or Usage Code. **The Mailboxes control the access rights for the Mailbox, Buffer, Length, and Usage** Each mailbox has a value of either 0 or 1, and the first 7 mailboxes have been assigned to manage the access to the 7 buffers that are located in the shared RAM and also the associated Length and Usage. When a mailbox has the value 0, the HP-85 AUXROM software may read or write to the associated buffer without interference from EBTKS. The same is true for the Length and Usage Code. While in this state, the EBTKS will not read or write the buffer. Likewise, when the mailbox has the value 1, the associated buffer can be read and written by EBTKS (and also the Length and Usage), but the HP-85 AUXROM software should not read or write the buffer. Note that the ability to *read/write*, *read-only*, and *should not access* are not enforced by hardware. Rather, they are a convention that is managed by the current state of the mailboxes, and for reliable and predictable system operation, both the AUXROM software and the EBTKS firmware must abide by these rules. While a buffers should not be read or written by the side that is not allowed to, it is expected that both sides can read the mailboxes at any time. This is the mechanism by which ownership of the buffers is passed back and forth between the EBTKS and the HP-85 AUXROM software. **Ownership can be given, but not taken** Since only the owner of mailbox (and the associated buffer, length and usage code) may write to a mailbox, only the owner may change its value. Thus, if the HP-85 has ownership (mailbox is 0), it can give ownership to EBTKS by writing a 1 to the mailbox, and concurrently the ownership of the buffer, length and usage code are also transferred. The correct way to do this is to make all required changes to the buffer, length, and usage code, and finally transfer ownership by changing the state of the mailbox. The same process occurs when EBTKS has ownership of a mailbox (and associated resources) and wants to pass ownership back to the HP-85. The idle state for ownership is that the AUXROMs own the resources. All mailboxes are initialized to 0 when the system boots, giving ownership to the AUXROMs. .. raw:: html
Mailbox
State
AUXROM
Access to
Mailbox
AUXROM Access
to Buffer, Length,
Usage
EBTKS
Access to
Mailbox
EBTKS Access
to Buffer, Length,
Usage
0 Read and
Write
Read and
Write
Read Only None
1 Read Only None Read and
Write
Read and
Write
**All transfers of data between the HP-85 and EBTKS originate with some activity on the HP-85 side** Scenario 1: AUXROM wants to pass 256 bytes to EBTKS .................................................... For example, writing a FAT32 disk file to the SD card (This is not a totally complete example) * Mailbox 0 is 0: Indicates HP-85 AUXROMs have ownership * AUXROM software fills buffer 0 with 256 bytes of data, maybe as a result of BASIC function calls * AUXROM software set the Buffer Length for buffer 0 to 256 * AUXROM software set the Buffer Usage for buffer 0 to a code indicating which operation is being performed (for example, write) * When AUXROM software has finished writing data to the buffer, it sets Mailbox 0 to value 1. It has thus relinquished control of the Buffer 0, and its Length, Usage, and Mailbox, and has assigned them to EBTKS. * AUXROM software then writes 0 (the number of the mailbox and buffer) to I/O register 177740, thus alerting EBTKS that something has changed * EBTKS then processes the data that was sent. Depending on the task performed, if there is data to be returned, it is placed in the same buffer and the Length is set appropriately. The Usage is the standard way of passing back success or failure status for the function just performed. By convention, 0 indicates success, and other values may indicate success with additional info or information about a failing status. This is not standardized, and different Keywords may use the returned Usage in their own specific way. After the buffer, Length and Usage have been updated, the final operation that EBTKS performs as part of the processing of the keyword is to pass ownership of the buffer, Length, and Usage back to AUXROMs by setting mailbox 0 back to value 0. * While EBTKS was processing the data that the AUXROMs sent it, the scenario branches depending on whether there is more data to send - More data to send: The AUXROMs just loops, monitoring the mailbox waiting for it to return to 0, and when it does, it goes back to the beginning of this scenario to send more data. An example of this might be the AUXROMs sending 2 kb of data, as multiple blocks of 256 bytes. - No more data to send: After handing off the buffer to the EBTKS, the AUXROMs can continue on to other tasks. Currently no keyword does this. They all wait for EBTKS to finish, since there is always the possibility of an error status being returned. Scenario 2: A Keyword on the HP-85 is Executed to pass a string to EBTKS ......................................................................... For example, selecting a file name to be associated with the Tape Drive Emulation * The HP-85 is executing a BASIC program and gets to a token for a keyword that is handled by AUXROMs. AUXROM software gets control. Note that by the time this token is reached, the address and length of the string will have been put on the operation stack that is managed by register R12. * Mailbox 0 has value 0: Indicates HP-85 AUXROMs have ownership * Code in the AUXROM performs any necessary tasks prior to setting up a buffer with a copy of the string. * AUXROM software copies the string into buffer 0 * AUXROM software set the buffer Length for buffer 0 to the length of the string * AUXROM software set the Buffer Usage for buffer 0 to a code indicating that the statement to be processed is "set filename of emulated tape" * AUXROM software has now finished setting things up, and can now let EBTKS take over. AUXROM changes Mailbox 0 to value 1. It has thus relinquished control of the buffer 0, and its Length, Usage, and Mailbox, are assigned to EBTKS. * AUXROM software then writes 0 (the number of the mailbox and buffer) to I/O register 177740, thus alerting EBTKS that something has changed * AUXROM enters a loop monitoring Mailbox 0, waiting for it to change back to 0 * EBTKS sees the write to 177740 and knows there is a new task to be performed, and the value written is 0, so it knows that the information about what is to be done is in buffer 0 (and its associated Length and Usage Code) * EBTKS reads the Usage code, sees that it is a File name setting for the emulated Tape Drive. It expects that the file name is in buffer 0 and the Length is in the associated Length location. * EBTKS fetches the string and does whatever is needed to treat it as a directory path and file name, and associate that file with the Tape Drive emulation. * Depending on success or failure, EBTKS sets the Usage value either to 0 for success, or some other value to indicate what type of error occurred * Finally, the EBTKS writes a 0 to the mailbox. This ends its involvement with the BASIC Statement. * The AUXROM software (which has been looping, watching the mailbox) sees that ownership has been returned. It handles the value in the Usage location, that indicates either success or failure. * The AUXROM software does any cleanup, and exits back to wherever it was called from. Scenario 3: AUXROM wants to receive 256 bytes from EBTKS ......................................................... For example, getting data from an ADC (This is not a totally complete example) * A set of command bytes (maybe looking like an HPIB request to an ADC) is placed in Buffer 3, possible info may include voltage range, ADC channel, sample rate, data format, number of samples * The Length value for buffer 3 is set appropriately * The Usage value for buffer 3 is set appropriately * Mailbox 3 is set to 1, thus passing ownership to EBTKS * AUXROM software then writes 3 (the number of the mailbox and buffer) to I/O register 177740, thus alerting EBTKS that something has changed * AUXROM enters a loop monitoring Mailbox 3, waiting for it to change back to 0 * EBTKS performs the requested ADC operation, and places the results in Buffer 3. It also sets the Length and Usage values. * Lastly, EBTKS sets Mailbox 3 back to 0, relinquishing ownership. * If more data is to be received, a different buffer could be passed to EBTKS, to continue to receive data, while the buffer just received (3) could be processed. * Using 2 buffers this way (1 being processed, 1 receiving) the system ping-pongs between the two buffers, maximizing data transfer rate and system utilization. Fast inter-ROM jumps .................... It is currently expected that there will be a small block of code in the upper AUXROM region that is identical in all of the AUXROMs, and this will support very fast switching between different AUXROMs by changing the RSELEC register and doing a JSB to a branch table in the destination AUXROM. This will be much faster than how traditional HP-85 ROMS branch between co-operating ROMs (like EMS and EDISK ROMs)