Struct capsules::ieee802154::framer::Framer

pub struct Framer<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> {
    mac: &'a M,
    aes_ccm: &'a A,
    data_sequence: Cell<u8>,
    key_procedure: Cell<Option<&'a KeyProcedure>>,
    device_procedure: Cell<Option<&'a DeviceProcedure>>,
    tx_state: MapCell<TxState>,
    tx_client: Cell<Option<&'a TxClient>>,
    rx_state: MapCell<RxState>,
    rx_client: Cell<Option<&'a RxClient>>,
}

This struct wraps an IEEE 802.15.4 radio device kernel::hil::radio::Radio and exposes IEEE 802.15.4 MAC device functionality as the trait capsules::mac::Mac. It hides header preparation, transmission and processing logic from the user by essentially maintaining multiple state machines corresponding to the transmission, reception and encryption/decryption pipelines. See the documentation in capsules/src/mac.rs for more details.

Fields

mac: &'a M

aes_ccm: &'a A

data_sequence: Cell<u8>

key_procedure: Cell<Option<&'a KeyProcedure>>

KeyDescriptor lookup procedure

device_procedure: Cell<Option<&'a DeviceProcedure>>

DeviceDescriptor lookup procedure

tx_state: MapCell<TxState>

Transmision pipeline state. This should never be None, except when transitioning between states. That is, any method that consumes the current state should always remember to replace it along with the associated state information.

tx_client: Cell<Option<&'a TxClient>>

rx_state: MapCell<RxState>

Reception pipeline state. Similar to the above, this should never be None, except when transitioning between states.

rx_client: Cell<Option<&'a RxClient>>

Methods

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> Framer<'a, M, A>

pub fn new(mac: &'a M, aes_ccm: &'a A) -> Framer<'a, M, A>

pub fn set_key_procedure(&self, key_procedure: &'a KeyProcedure)

Sets the IEEE 802.15.4 key lookup procedure to be used.

pub fn set_device_procedure(&self, device_procedure: &'a DeviceProcedure)

Sets the IEEE 802.15.4 key lookup procedure to be used.

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

Look up the key using the IEEE 802.15.4 KeyDescriptor lookup prodecure implemented elsewhere.

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

Look up the extended address of a device using the IEEE 802.15.4 DeviceDescriptor lookup prodecure implemented elsewhere.

fn outgoing_frame_security(
    &self,
    buf: &'static mut [u8],
    frame_info: FrameInfo
) -> TxState

IEEE 802.15.4-2015, 9.2.1, outgoing frame security procedure Performs the first checks in the security procedure. The rest of the steps are performed as part of the transmission pipeline. Returns the next TxState to enter.

fn incoming_frame_security(
    &self,
    buf: &'static mut [u8],
    frame_len: usize
) -> RxState

IEEE 802.15.4-2015, 9.2.3, incoming frame security procedure

fn step_transmit_state(&self) -> (ReturnCode, Option<&'static mut [u8]>)

Advances the transmission pipeline if it can be advanced.

fn step_receive_state(&self)

Advances the reception pipeline if it can be advanced.

Trait Implementations

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> MacDevice<'a> for Framer<'a, M, A>

fn set_transmit_client(&self, client: &'a TxClient)

Sets the transmission client of this MAC device

fn set_receive_client(&self, client: &'a RxClient)

Sets the receive client of this MAC device

fn get_address(&self) -> u16

The short 16-bit address of the MAC device

fn get_address_long(&self) -> [u8; 8]

The long 64-bit address (EUI-64) of the MAC device

fn get_pan(&self) -> u16

The 16-bit PAN ID of the MAC device

fn set_address(&self, addr: u16)

Set the short 16-bit address of the MAC device

fn set_address_long(&self, addr: [u8; 8])

Set the long 64-bit address (EUI-64) of the MAC device

fn set_pan(&self, id: u16)

Set the 16-bit PAN ID of the MAC device

fn config_commit(&self)

This method must be called after one or more calls to set_*. If set_* is called without calling config_commit, there is no guarantee that the underlying hardware configuration (addresses, pan ID) is in line with this MAC device implementation.

fn is_on(&self) -> bool

Returns if the MAC device is currently on.

fn prepare_data_frame(
    &self,
    buf: &'static mut [u8],
    dst_pan: PanID,
    dst_addr: MacAddress,
    src_pan: PanID,
    src_addr: MacAddress,
    security_needed: Option<(SecurityLevel, KeyId)>
) -> Result<Frame, &'static mut [u8]>

Prepares a mutable buffer slice as an 802.15.4 frame by writing the appropriate header bytes into the buffer. This needs to be done before adding the payload because the length of the header is not fixed.

fn transmit(&self, frame: Frame) -> (ReturnCode, Option<&'static mut [u8]>)

Transmits a frame that has been prepared by the above process. If the transmission process fails, the buffer inside the frame is returned so that it can be re-used.

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> TxClient for Framer<'a, M, A>

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

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> RxClient for Framer<'a, M, A>

fn receive(
    &self,
    buf: &'static mut [u8],
    frame_len: usize,
    crc_valid: bool,
    _: ReturnCode
)

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> ConfigClient for Framer<'a, M, A>

fn config_done(&self, _: ReturnCode)

impl<'a, M: Mac + 'a, A: AES128CCM<'a> + 'a> CCMClient for Framer<'a, M, A>

fn crypt_done(
    &self,
    buf: &'static mut [u8],
    res: ReturnCode,
    tag_is_valid: bool
)

res is SUCCESS if the encryption/decryption process succeeded. This does not mean that the message has been verified in the case of decryption. If we are encrypting: tag_is_valid is true iff res is SUCCESS. If we are decrypting: tag_is_valid is true iff res is SUCCESS and the message authentication tag is valid.