Struct capsules::ieee802154::driver::RadioDriver

pub struct RadioDriver<'a> {
    mac: &'a MacDevice<'a>,
    neighbors: MapCell<[DeviceDescriptor; 4]>,
    num_neighbors: Cell<usize>,
    keys: MapCell<[KeyDescriptor; 4]>,
    num_keys: Cell<usize>,
    apps: Grant<App>,
    current_app: Cell<Option<AppId>>,
    kernel_tx: TakeCell<'static, [u8]>,
}

Fields

mac: &'a MacDevice<'a>

Underlying MAC device, possibly multiplexed

neighbors: MapCell<[DeviceDescriptor; 4]>

List of (short address, long address) pairs representing IEEE 802.15.4 neighbors.

num_neighbors: Cell<usize>

Actual number of neighbors in the fixed size array of neighbors.

keys: MapCell<[KeyDescriptor; 4]>

List of (security level, key_id, key) tuples representing IEEE 802.15.4 key descriptors.

num_keys: Cell<usize>

Actual number of keys in the fixed size array of keys.

apps: Grant<App>

Grant of apps that use this radio driver.

current_app: Cell<Option<AppId>>

ID of app whose transmission request is being processed.

kernel_tx: TakeCell<'static, [u8]>

Buffer that stores the IEEE 802.15.4 frame to be transmitted.

Methods

impl<'a> RadioDriver<'a>

pub fn new(
    mac: &'a MacDevice<'a>,
    grant: Grant<App>,
    kernel_tx: &'static mut [u8]
) -> RadioDriver<'a>

fn add_neighbor(&self, new_neighbor: DeviceDescriptor) -> Option<usize>

Add a new neighbor to the end of the list if there is still space for one, returning its new index. If the neighbor already exists, returns the index of the existing neighbor. Returns None if there is no remaining space.

fn remove_neighbor(&self, index: usize) -> ReturnCode

Deletes the neighbor at index if index is valid, returning ReturnCode::SUCCESS. Otherwise, returns ReturnCode::EINVAL. Ensures that the neighbors list is compact by shifting forward any elements after the index.

fn get_neighbor(&self, index: usize) -> Option<DeviceDescriptor>

Gets the DeviceDescriptor corresponding to the neighbor at a particular index, if the index is valid. Otherwise, returns None

fn add_key(&self, new_key: KeyDescriptor) -> Option<usize>

Add a new key to the end of the list if there is still space for one, returning its new index. If the key already exists, returns the index of the existing key. Returns None if there is no remaining space.

fn remove_key(&self, index: usize) -> ReturnCode

Deletes the key at index if index is valid, returning ReturnCode::SUCCESS. Otherwise, returns ReturnCode::EINVAL. Ensures that the keys list is compact by shifting forward any elements after the index.

fn get_key(&self, index: usize) -> Option<KeyDescriptor>

Gets the DeviceDescriptor corresponding to the key at a particular index, if the index is valid. Otherwise, returns None

fn do_with_app<F>(&self, appid: AppId, closure: F) -> ReturnCode where
    F: FnOnce(&mut App) -> ReturnCode, 

Utility function to perform an action on an app in a system call.

fn do_with_cfg<F>(&self, appid: AppId, len: usize, closure: F) -> ReturnCode where
    F: FnOnce(&[u8]) -> ReturnCode, 

Utility function to perform an action using an app's config buffer.

fn do_with_cfg_mut<F>(&self, appid: AppId, len: usize, closure: F) -> ReturnCode where
    F: FnOnce(&mut [u8]) -> ReturnCode, 

Utility function to perform a write to an app's config buffer.

fn get_next_tx_if_idle(&self) -> Option<AppId>

If the driver is currently idle and there are pending transmissions, pick an app with a pending transmission and return its AppId.

fn perform_tx_async(&self, appid: AppId)

Performs appid's pending transmission asynchronously. If the transmission is not successful, the error is returned to the app via its tx_callback. Assumes that the driver is currently idle and the app has a pending transmission.

fn perform_tx_sync(&self, appid: AppId) -> ReturnCode

Performs appid's pending transmission synchronously. The result is returned immediately to the app. Assumes that the driver is currently idle and the app has a pending transmission.

fn do_next_tx_async(&self)

Schedule the next transmission if there is one pending. Performs the transmission asynchronously, returning any errors via callbacks.

fn do_next_tx_sync(&self, new_appid: AppId) -> ReturnCode

Schedule the next transmission if there is one pending. If the next transmission happens to be the one that was just queued, then the transmission is synchronous. Hence, errors must be returned immediately. On the other hand, if it is some other app, then return any errors via callbacks.

Trait Implementations

impl<'a> DeviceProcedure for RadioDriver<'a>

fn lookup_addr_long(&self, addr: MacAddress) -> Option<[u8; 8]>

Gets the long address corresponding to the neighbor that matches the given MAC address. If no such neighbor exists, returns None.

impl<'a> KeyProcedure for RadioDriver<'a>

fn lookup_key(&self, level: SecurityLevel, key_id: KeyId) -> Option<[u8; 16]>

Gets the key corresponding to the key that matches the given security level level and key ID key_id. If no such key matches, returns None.

impl<'a> Driver for RadioDriver<'a>

fn allow(
    &self,
    appid: AppId,
    allow_num: usize,
    slice: AppSlice<Shared, u8>
) -> ReturnCode

Setup buffers to read/write from.

allow_num

• 0: Read buffer. Will contain the received frame.
• 1: Write buffer. Contains the frame payload to be transmitted.
• 2: Config buffer. Used to contain miscellaneous data associated with some commands because the system call parameters / return codes are not enough to convey the desired information.

fn subscribe(&self, subscribe_num: usize, callback: Callback) -> ReturnCode

Setup callbacks.

subscribe_num

• 0: Setup callback for when frame is received.
• 1: Setup callback for when frame is transmitted.

fn command(
    &self,
    command_num: usize,
    arg1: usize,
    _: usize,
    appid: AppId
) -> ReturnCode

IEEE 802.15.4 MAC device control.

For some of the below commands, one 32-bit argument is not enough to contain the desired input parameters or output data. For those commands, the config slice app_cfg is used as a channel to shuffle information between kernel space and user space. The expected size of the slice varies by command, and acts essentially like a custom FFI. That is, the userspace library MUST allow() a buffer of the correct size, otherwise the call is EINVAL. When used, the expected format is described below.

command_num

• 0: Driver check.
• 1: Return radio status. SUCCESS/EOFF = on/off.
• 2: Set short MAC address.
• 3: Set long MAC address. app_cfg (in): 8 bytes: the long MAC address.
• 4: Set PAN ID.
• 5: Set channel.
• 6: Set transmission power.
• 7: Commit any configuration changes.
• 8: Get the short MAC address.
• 9: Get the long MAC address. app_cfg (out): 8 bytes: the long MAC address.
• 10: Get the PAN ID.
• 11: Get the channel.
• 12: Get the transmission power.
• 13: Get the maximum number of neighbors.
• 14: Get the current number of neighbors.
• 15: Get the short address of the neighbor at an index.
• 16: Get the long address of the neighbor at an index. app_cfg (out): 8 bytes: the long MAC address.
• 17: Add a new neighbor with the given short and long address. app_cfg (in): 8 bytes: the long MAC address.
• 18: Remove the neighbor at an index.
• 19: Get the maximum number of keys.
• 20: Get the current number of keys.
• 21: Get the security level of the key at an index.
• 22: Get the key id of the key at an index. app_cfg (out): 1 byte: the key ID mode + up to 9 bytes: the key ID.
• 23: Get the key at an index. app_cfg (out): 16 bytes: the key.
• 24: Add a new key with the given descripton. app_cfg (in): 1 byte: the security level + 1 byte: the key ID mode + 9 bytes: the key ID (might not use all bytes) + 16 bytes: the key.
• 25: Remove the key at an index.

impl<'a> TxClient for RadioDriver<'a>

fn send_done(&self, spi_buf: &'static mut [u8], acked: bool, result: ReturnCode)

When transmission is complete or fails, return the buffer used for transmission to the client. result indicates whether or not the transmission was successful.

impl<'a> RxClient for RadioDriver<'a>

fn receive<'b>(
    &self,
    buf: &'b [u8],
    header: Header<'b>,
    data_offset: usize,
    data_len: usize
)

When a frame is received, this callback is triggered. The client only receives an immutable borrow of the buffer. Only completely valid, unsecured frames that have passed the incoming security procedure are exposed to the client.