mirror of
https://github.com/afska/gba-link-connection.git
synced 2026-04-26 02:02:25 -05:00
Adding LinkCableMultiboot::Async documentation
This commit is contained in:
Rodrigo Alfonso
parent
2a11159182
commit
55ba174de1
32
README.md
32
README.md
|
|
@ -126,7 +126,7 @@ You can also change these compile-time constants:
|
|||
| `read(playerId)` | **u16** | Dequeues and returns the next message from player #`playerId`. If there's no data from that player, a `0` will be returned. |
|
||||
| `peek(playerId)` | **u16** | Returns the next message from player #`playerId` without dequeuing it. If there's no data from that player, a `0` will be returned. |
|
||||
| `send(data)` | - | Sends `data` to all connected players. If `data` is invalid or the send queue is full, a `false` will be returned. |
|
||||
| `didQueueOverflow()` | **bool** | Returns whether the internal receive queue lost messages at some point due to being full. This can happen if your queue size is too low, if you receive too much data without calling `sync(...)` enough times, or if you don't `read(...)` enough messages before the next `sync()` call. After this call, the overflow flag is cleared if `clear` is `true` (default behavior). |
|
||||
| `didQueueOverflow([clear])` | **bool** | Returns whether the internal receive queue lost messages at some point due to being full. This can happen if your queue size is too low, if you receive too much data without calling `sync(...)` enough times, or if you don't `read(...)` enough messages before the next `sync()` call. After this call, the overflow flag is cleared if `clear` is `true` (default behavior). |
|
||||
| `resetTimer()` | - | Restarts the send timer without disconnecting. Call this if you changed `config.interval` |
|
||||
|
||||
⚠️ `0xFFFF` and `0x0` are reserved values, so don't send them!
|
||||
|
|
@ -146,8 +146,13 @@ You can change these compile-time constants:
|
|||
- `LINK_CABLE_MULTIBOOT_PALETTE_DATA`: to control how the logo is displayed.
|
||||
- Format: `0b1CCCDSS1`, where `C`=color, `D`=direction, `S`=speed.
|
||||
- Default: `0b10010011`.
|
||||
- `LINK_CABLE_MULTIBOOT_ASYNC_DISABLE_NESTED_IRQ`: to disable nested IRQs. In the async version, SERIAL IRQs can be interrupted (once they clear their time-critical needs) by default, which helps prevent issues with audio engines. However, if something goes wrong, you can disable this behavior.
|
||||
|
||||
## Methods
|
||||
## Sync version
|
||||
|
||||
This version is simpler and blocks the system thread until completion. It doesn't require interrupt service routines.
|
||||
|
||||
### Methods
|
||||
|
||||
| Name | Return type | Description |
|
||||
| --------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
|
|
@ -155,7 +160,26 @@ You can change these compile-time constants:
|
|||
|
||||
⚠️ stop DMA before sending the ROM! _(you might need to stop your audio player)_
|
||||
|
||||
⚠️ ^^^ this restriction only applies to the sync version
|
||||
⚠️ this restriction only applies to the sync version!
|
||||
|
||||
## Async version
|
||||
|
||||
This version (`LinkCableMultiboot::Async`) allows more advanced use cases like displaying animations and/or audio during the transfers, probing the connections and marking the transfer as 'ready' to start. It requires adding the provided interrupt service routines.
|
||||
|
||||
### Methods
|
||||
|
||||
| Name | Return type | Description |
|
||||
| --------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `sendRom(rom, romSize, [waitForReadySignal], [mode])` | **bool** | Sends the `rom` (must be 4-byte aligned). The `romSize` must be a number between `448` and `262144`, and a multiple of `16`. If `waitForReadySignal` is `true`, it will wait until the `markReady()` method is called to start the transfer. The `mode` can be either `LinkCableMultiboot::TransferMode::MULTI_PLAY` for GBA cable (default value) or `LinkCableMultiboot::TransferMode::SPI` for GBC cable. Once completed, `getState()` should return `LinkCableMultiboot::Async::State::STOPPED` and `getResult()` should return `LinkCableMultiboot::Async::Result::SUCCESS`. Returns `false` if there's a pending transfer or the size is invalid. |
|
||||
| `reset()` | - | Deactivates the library, canceling the in-progress transfer, if any. |
|
||||
| `getState()` | **LinkCableMultiboot::Async::State** | Returns the current state. |
|
||||
| `getResult([clear])` | **LinkCableMultiboot::Async::Result** | Returns the result of the last operation. After this call, the result is cleared if `clear` is `true` (default behavior). |
|
||||
| `playerCount()` | **u8** | Returns the number of connected players (`1~4`). |
|
||||
| `getPercentage()` | **u32** | Returns the completion percentage. |
|
||||
| `isReady()` | **bool** | Returns whether the ready mark is active or not. This is only useful when using the `waitForReadySignal` parameter. |
|
||||
| `markReady()` | **bool** | Marks the transfer as ready. This is only useful when using the `waitForReadySignal` parameter. |
|
||||
|
||||
⚠️ never call `reset()` inside an interrupt handler!
|
||||
|
||||
# 🔧👾 LinkRawCable
|
||||
|
||||
|
|
@ -264,7 +288,7 @@ You can also change these compile-time constants:
|
|||
| `isServerClosed()` | **bool** | Returns `true` if the server was closed with `closeServer()`. |
|
||||
| `playerCount()` | **u8** _(1~5)_ | Returns the number of connected players. |
|
||||
| `currentPlayerId()` | **u8** _(0~4)_ | Returns the current player ID. |
|
||||
| `didQueueOverflow()` | **bool** | Returns whether the internal receive queue lost messages at some point due to being full. This can happen if your queue size is too low, if you receive too much data without calling `receive(...)` enough times, or if excessive `receive(...)` calls prevent the ISR from copying data. After this call, the overflow flag is cleared if `clear` is `true` (default behavior). |
|
||||
| `didQueueOverflow([clear])` | **bool** | Returns whether the internal receive queue lost messages at some point due to being full. This can happen if your queue size is too low, if you receive too much data without calling `receive(...)` enough times, or if excessive `receive(...)` calls prevent the ISR from copying data. After this call, the overflow flag is cleared if `clear` is `true` (default behavior). |
|
||||
| `getLastError([clear])` | **LinkWireless::Error** | If one of the other methods returns `false`, you can inspect this to know the cause. After this call, the last error is cleared if `clear` is `true` (default behavior). |
|
||||
| `resetTimer()` | - | Restarts the send timer without disconnecting. Call this if you changed `config.interval`. |
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@
|
|||
// --------------------------------------------------------------------------
|
||||
// considerations:
|
||||
// - stop DMA before sending the ROM! (you might need to stop your audio player)
|
||||
// - ^^^ this restriction only applies to the sync version
|
||||
// - this restriction only applies to the sync version!
|
||||
// --------------------------------------------------------------------------
|
||||
|
||||
#ifndef LINK_DEVELOPMENT
|
||||
|
|
@ -485,12 +485,13 @@ class LinkCableMultiboot {
|
|||
/**
|
||||
* @brief Sends the `rom`. Once completed, `getState()` should return
|
||||
* `LinkCableMultiboot::Async::State::STOPPED` and `getResult()` should
|
||||
* return `LinkCableMultiboot::Async::Result::SUCCESS`.
|
||||
* return `LinkCableMultiboot::Async::Result::SUCCESS`. Returns `false` if
|
||||
* there's a pending transfer or the size is invalid.
|
||||
* @param rom A pointer to ROM data. Must be 4-byte aligned.
|
||||
* @param romSize Size of the ROM in bytes. It must be a number between
|
||||
* `448` and `262144`, and a multiple of `16`.
|
||||
* @param waitForReadySignal Whether the code should wait for a `ready()`
|
||||
* call to start the actual transfer.
|
||||
* @param waitForReadySignal Whether the code should wait for a
|
||||
* `markReady()` call to start the actual transfer.
|
||||
* @param mode Either `TransferMode::MULTI_PLAY` for GBA cable (default
|
||||
* value) or `TransferMode::SPI` for GBC cable.
|
||||
*/
|
||||
|
|
@ -523,7 +524,7 @@ class LinkCableMultiboot {
|
|||
/**
|
||||
* @brief Returns the current state.
|
||||
*/
|
||||
State getState() { return state; }
|
||||
[[nodiscard]] State getState() { return state; }
|
||||
|
||||
/**
|
||||
* @brief Returns the result of the last operation. After this
|
||||
|
|
@ -540,12 +541,14 @@ class LinkCableMultiboot {
|
|||
/**
|
||||
* @brief Returns the number of connected players (`1~4`).
|
||||
*/
|
||||
u32 playerCount() { return dynamicData.confirmedObservedPlayers; }
|
||||
[[nodiscard]] u8 playerCount() {
|
||||
return dynamicData.confirmedObservedPlayers;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Returns the completion percentage.
|
||||
*/
|
||||
u32 getPercentage() {
|
||||
[[nodiscard]] u32 getPercentage() {
|
||||
if (state == STOPPED || fixedData.size == 0)
|
||||
return 0;
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user