BCMSupport_SendPropertyBuffer (changes)
Showing changes from revision #0 to #1:
Added | Removed | Changed
BCMSupport
» SWI Calls
» BCMSupport_SendPropertyBuffer
BCMSupport_SendPropertyBuffer
(SWI &591C4)
| Entry | |
|---|---|
| R0 | Pointer to buffer (16 byte aligned) |
| R1 | Flags: |
| Bit 0: | |
| 0 => Block and wait for response | |
| 1 => Don’t block, call callback specified in R2-R4 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 | |
| If R1 bit 0 is set: | |
| R2 | Response callback R0 |
| R3 | Response callback R12 |
| R4 | Response callback function pointer |
| Exit | |
|---|---|
| All registers preserved | |
Use
This SWI is used to send a buffer via the mailbox property interface. The buffer must be filled with a sequence of tagged messages, as described on the Raspberry Pi GitHub wiki
Notes
The buffer pointer must be at least 16 byte aligned, and located in a region of non-cacheable, physically contiguous memory. BCMSupport_AllocPropertyBuffer can be used to allocate a buffer which meets these requirements. There is no requirement for the caller to use memory barriers after writing the request to the buffer or before reading the response; BCMSupport will perform the correct barrier operations on your behalf.
Care must be taken to ensure that the buffer is not freed or used for another purpose while the GPU is processing the contents.
If you want to avoid the hassle of managing your own non-cacheable buffers, consider using the simpler BCMSupport_SendTempPropertyBuffer call.
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.
Callback functions are called as follows:
| Entry | |
|---|---|
| R0 | R2 value from send SWI |
| R1 | Buffer pointer (R0 value from send SWI) |
| R12 | R3 value from send SWI |
| CPU in privileged mode | |
| Interrupts disabled | |
| Exit |
|---|
| R0-R3, R12 can be corrupted |
Unlike BCMSupport_SendMBMessage, it is not possible to request an async operation with a null callback. This is because to do so would mean you have no way of knowing when it is safe to free or re-use the buffer. It is also recommended that once an operation has completed you check the buffer for any received error codes.
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)
As with the standard mailbox messages, BCMSupport_MBSync can be used to wait for completion of (async) messages. However it is not currently possible to specify the buffer address to wait for; you are limited to using the callback R0/R12/PC values, or to block for all messages.
See also
Social
and
ROOL Store
Buy RISC OS Open merchandise here, including SD cards for Raspberry Pi and more.