BCMSupport_SendMBMessage (changes)
Showing changes from revision #0 to #1:
Added | Removed | Changed
BCMSupport
» SWI Calls
» BCMSupport_SendMBMessage
BCMSupport_SendMBMessage
(SWI &591C0)
| Entry | |
|---|---|
| R0 | Mailbox channel (bits 0-3) and data (bits 4-31) |
| R1 | Flags: |
| Bit 0: | |
| 0 => Block and wait for response | |
| 1 => Don’t block, call callback specified in R4-R6 on receipt of response | |
| Bit 1: | |
| 0 => Block if the send buffer is full | |
| 1 => Return error if the send buffer is full | |
| Other bits reserved, should be zero | |
| R2 | Response mask |
| R3 | Response value |
| If R1 bit 0 is set: | |
| R4 | Response callback R0 |
| R5 | Response callback R12 |
| R6 | Response callback function pointer |
| Exit | |
|---|---|
| R0 | Response word (If flags bit 0 is clear, and a response is expected (R2 != 0)) |
| Else preserved | |
| All other registers preserved | |
Use
This is the lowest-level interface for sending messages via the mailbox. The word provided in R0 is written directly to the send channel.
Notes
The values of R2 and R3 are used to identify the response in the receive channel, using the following logic:
if ((response AND R2) == R3)
{
// this is my response
}
else
{
// this is not my response
}
Specifying a response mask of 0 indicates that no response is expected.
Each sent message which is expecting a response is pushed onto a queue. When a response is received from the GPU the queue is searched in FIFO order until a match is found. By correctly setting the response mask and value in R2 and R3 this allows the interface to cope with mailbox channels which only respond to messages in-order (e.g. channels 0 and 1) versus those that reply out-of-order (e.g. channel 8)
If the call is operating in a blocking manner (R1 bit 0 or bit 1 are unset) then it must be called with interrupts enabled.
Any response which fails to match against an entry in the expected-responses list will be discarded.
Callback functions are called as follows:
| Entry | |
|---|---|
| R0 | R4 value from send SWI |
| R1 | Response word |
| R12 | R5 value from send SWI |
| CPU in privileged mode | |
| Interrupts disabled | |
| Exit |
|---|
| R0-R3, R12 can be corrupted |
The callback function pointer can also be null, which is taken as an indication that the response should be ignored.
Callback functions are called directly from the mailbox interrupt handler, and so must be quick and must not enable interrupts. Sending further messages from within a callback is discouraged (non-blocking sends are possible via making sure bits 0 and 1 are set, but because there is no guarantee the send will succeed the ability is of limited use)
If a non-blocking send is requested, and the mailbox is full, a “mailbox full” error is returned (error number &81F200)
See also
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.