PL011BTClaim()
Synopsis
long PL011BTClaim(
void *owner)
Function
Reserve the Bluetooth UART transport for an owner token.
Result
PL011BT_OK on success, PL011BT_ERR_ARGUMENT for NULL, or
PL011BT_ERR_BUSY if any owner already holds the resource, including
the same token. Claims are not recursive or reference-counted.
Notes
Call in task context. May wait for the resource semaphore, but does
not wait for an existing owner to release its claim. Claiming does
not power or configure the controller and does not clear receive data.
Use the same token for subsequent operations. Configure the UART
before data transfer and arrange a single reader and a single writer.
The token does not serialize calls made by the same client. Release
the claim with PL011BTRelease() after transfers have stopped.
PL011BTGetAPIVersion()
Synopsis
unsigned int PL011BTGetAPIVersion(
)
Function
Return the interface version of pl011bt.resource.
Result
PL011BT_API_VERSION, currently 1.
Notes
Obtain the resource with OpenResource("pl011bt.resource") before
calling its functions. A version result describes the software
interface; it does not establish that the controller is powered,
configured or able to receive data. No ownership claim is required.
PL011BTGetCapabilities()
Synopsis
unsigned long PL011BTGetCapabilities(
)
Function
Return the resource's transport capability flags.
Result
Bitwise combination of PL011BT_CAP_* values:
PRESENT - The resource initialized for a supported peripheral window.
RX_INTERRUPT - A receive interrupt handler has been registered.
TX_INTERRUPT - Reserved; not set by this implementation.
BAUD_CHANGE - UART divisor configuration is implemented.
POWER_CONTROL - Controller power-line control is implemented.
Notes
No ownership claim is required. RX_INTERRUPT is added after successful
handler registration during PL011BTConfigure(). It remains set after
PL011BTRelease() and does not mean receive interrupts are currently
enabled. The flags do not report controller power or UART readiness.
POWER_CONTROL does not guarantee that a firmware GPIO request can
succeed. Check the result of PL011BTSetPower(). RTS/CTS wiring is not
reported by this mask.
PL011BTRead()
Synopsis
long PL011BTRead(
void *owner, void *data, unsigned long capacity)
Function
Remove available raw bytes from the interrupt-fed receive ring.
Result
Number of bytes copied, from zero through capacity; or
PL011BT_ERR_ARGUMENT for NULL owner or NULL data with nonzero capacity,
or PL011BT_ERR_NOT_OWNER for a token without the claim.
Zero means no bytes were copied, not end of stream.
Notes
Returns without waiting for new input. Requires configuration with a
registered receive interrupt handler; verify PL011BT_CAP_RX_INTERRUPT
after PL011BTConfigure(). The ring holds at most 8191 unread bytes.
Drain it promptly to limit data loss. There is no client notification
or wait operation in this interface.
Transfers raw bytes without H:4 framing. Consumed bytes are removed
from the ring. The destination is not retained. Use one reader and
prevent configuration, power changes or release from racing with the
call; it does not take the resource semaphore.
Bugs
UART error status and receive overflow are not returned to the caller.
Bytes marked with UART errors can be delivered as ordinary data, and
ring overflow can lose bytes. Diagnostic logging is not a reliable
error-reporting interface. If interrupt registration fails, there is
no direct FIFO read fallback.
PL011BTRelease()
Synopsis
void PL011BTRelease(
void *owner)
Function
Disable the UART and release a matching ownership claim.
Notes
Call in task context after all client reads and writes have stopped.
May wait for the resource semaphore. Disables UART interrupts and the
UART, then clears the owner and saved configuration. It does not wait
for bytes already accepted for transmission to reach the controller.
Does not power down the controller, stop its low-power clock, restore
pin routing, unregister the interrupt handler or clear the receive
ring. If power-down is required, call PL011BTSetPower(owner, 0) before
release. No completion status is returned.
PL011BTSetPower()
Synopsis
long PL011BTSetPower(
void *owner, unsigned long enabled)
Function
Set the Bluetooth controller's power-enable line.
Result
PL011BT_OK after issuing the GPIO change, PL011BT_ERR_ARGUMENT for
NULL owner, PL011BT_ERR_NOT_OWNER for a token without the claim, or
PL011BT_ERR_UNAVAILABLE when the firmware GPIO path cannot complete
its request. Success does not confirm controller readiness.
Notes
Call in task context. May wait for the resource semaphore. Uses the
power pin and polarity determined during initialization, through a
SoC GPIO or firmware mailbox. The SoC path provides no hardware
acknowledgement; firmware response checks do not verify pin readback.
Power changes do not reconfigure the UART, clear receive data or
release ownership. Disabling power can interrupt controller activity
and discard its volatile state. The caller must coordinate transfers,
startup delays, reset and any firmware reload required by the radio.
Repeated calls issue the requested GPIO operations again.
Bugs
The firmware path inherits mailbox waits without an overall deadline
and can block while holding the resource semaphore. A failed request
can leave GPIO configuration partially changed.
PL011BTWrite()
Synopsis
long PL011BTWrite(
void *owner, const void *data, unsigned long length)
Function
Write as many raw bytes as the UART transmit FIFO currently accepts.
Result
Number of bytes accepted, from zero through length; or
PL011BT_ERR_ARGUMENT for NULL owner or NULL data with nonzero length,
or PL011BT_ERR_NOT_OWNER for a token without the claim.
Zero is a valid short write, not an error.
Notes
Requires a successfully configured UART and the appropriate controller
power state; these are not checked. Stops when the FIFO is full and
does not wait for room or transmission completion. Retry only the
unaccepted suffix, with a caller-defined retry or timeout policy.
No framing, packet boundaries or HCI status are added. Accepted bytes
may still be queued in the UART when the function returns. The source
buffer is not retained. Serialize writers and prevent configuration,
power changes or release from racing with this call; it does not take
the resource semaphore.