OS_ClaimDeviceVector (changes)

Showing changes from revision #4 to #5: Added | Removed | Changed

OS SWI Calls

» OS_ClaimDeviceVector

OS_ClaimDeviceVector

(SWI &4B)

Use

The purpose of this call is to claim a device vector.

Notes

This installs the device driver. If the same driver has already been installed on the vector then the old copy is removed from the vector. This does not enable interrupts from the device. The previous driver is added to the list of earlier claimants. Your driver is called if the interrupt controller receives an interrupt from the appropriate device and your driver was the last to claim the vector.

For IO expansion cards (device numbers 8 or 13) there may be multiple cards all sharing the same interrupt line (and therefore device number) the values in R3 and R4 will be used to determine the true owner. A byte read will be performed of the interrupt status and your driver will be called if (status AND R4) is non zero. From RISC OS 5.00, bits 8-15 of R4 can specify an EOR mask to permit active low interrupts to be supported, ie. when ((status EOR R4[15:8]) AND R4[7:0]) is non zero.

When Under your code is being called, you’ll find the following entry conditions:RISC OS 5, your driver routine will be called as follows:

• The ARM is in IRQ32 mode and interrupts are disabledIRQ mode and interrupts are disabled
• On R0 systems is with the either device an number (with no flags in the high bits)IOC or IOMD IO controller R3 points to the base of its address space, on HAL versions of RISC OS it is value returned in R3 from HAL_IRQSource.
• R12 has R2’s value when claiming the vector
• R13 points to the IRQ stack. The word pointed to by R13 is a return address for claiming the vector.
• R14 contains a return address for passing on the call to the next device driver.

Your On routine exit: should:

• Service Processor the mode and interrupt state must be preserved
• Stop R1-R3, R12, and R14 may be corrupted by the device call. from generating interrupts, when necessary
• Return R0 to must kernel be using preserved if you are passing on an unhandled sharedMOV PC, R14IRQ. If you are claiming the IRQ, it can be corrupted.
• For non-shared IRQs, returning via R14 is functionally equivalent to returning via the stacked return address. This also means that R0 doesn’t need to be preserved when returning via R14.

You should ensure:

• A very high execution speed
• If your routine takes more than 100µs, you should re-enable interrupts, if previously disabled, to ensure other devices’ interrupts can be serviced – e.g. disc ops. With interrupts enabled your routine must cope with being re-entered.
• Saving R14_svc to a stack before calling SWIs and reloading it after it returns to prevent double use of R14_svc
• Strictly avoiding the use of non re-entrant SWIs, because the supervisor stack would become corrupted if used
• Clearing the interrupt flags when finishing
• You cope with SWI-error handling. You must use XSWIs. As there is no-one to pass the error on to, you must either handle it yourself or store an error indicator, so that the next SWI call (or the current, if already threaded) to this module will generate an error.

See also

• HAL_IRQSource
• OS_ClaimDeviceVector Flag
• OS_ReleaseDeviceVector
• System Device Numbers