mac.h File Reference

Provides MAC API to access MAC Layer functionality.

Copyright (c) 2013-2018 Microchip Technology Inc. and its subsidiaries.

#include <stdint.h>
#include <stdbool.h>
#include "stack_config.h"
#include "tal_generic.h"
#include "return_val.h"
#include "mac_api.h"
#include "qmm.h"
#include "mac_build_config.h"

Macros
#define	FCF_ADDR_MASK   (3)
#define	FCF_GET_DEST_ADDR_MODE(x)   (((x) >> FCF_DEST_ADDR_OFFSET) & FCF_ADDR_MASK)
#define	FCF_GET_SOURCE_ADDR_MODE(x)   (((x) >> FCF_SOURCE_ADDR_OFFSET) & FCF_ADDR_MASK)
#define	MAX_ALLOWED_PAN_DESCRIPTORS
	Maximum allowed PANDescriptors that is calculated using the large buffer size. More...
#define	MAX_PANDESCRIPTORS   (MAX_ALLOWED_PAN_DESCRIPTORS > 5 ? 5 : MAX_ALLOWED_PAN_DESCRIPTORS)
	Active/passive scan: implementation-defined maximum number of PANDescriptors that can be stored. More...

Functions
uint8_t	mac_extract_mhr_addr_info (uint8_t *frame_ptr)
retval_t	mac_init (void)
	Initializes the MAC sublayer. More...
bool	mac_task (void)
	Runs the MAC scheduler. More...
void	mcps_data_conf (uint8_t *m)
	Wrapper function for messages of type mcps_data_conf_t. More...
void	mcps_data_ind (uint8_t *m)
	Wrapper function for messages of type mcps_data_ind_t. More...
void	mcps_data_request (uint8_t *msg)
	Builds the data frame for transmission. More...
void	mcps_purge_conf (uint8_t *m)
	Wrapper function for messages of type mcps_purge_conf_t. More...
void	mcps_purge_request (uint8_t *msg)
	Processes a MCPS-PURGE.request primitive. More...
void	mlme_associate_conf (uint8_t *m)
	Wrapper function for messages of type mlme_associate_conf_t. More...
void	mlme_associate_ind (uint8_t *m)
	Wrapper function for messages of type mlme_associate_ind_t. More...
void	mlme_associate_request (uint8_t *m)
	Handles the MLME associate request command from the NWK layer. More...
void	mlme_associate_response (uint8_t *m)
	Entry point from the stack for MLME associate response. More...
void	mlme_beacon_notify_ind (uint8_t *m)
	Wrapper function for messages of type mlme_beacon_notify_ind_t. More...
void	mlme_comm_status_ind (uint8_t *m)
	Wrapper function for messages of type mlme_comm_status_ind_t. More...
void	mlme_disassociate_conf (uint8_t *m)
	Wrapper function for messages of type mlme_disassociate_conf_t. More...
void	mlme_disassociate_ind (uint8_t *m)
	Wrapper function for messages of type mlme_disassociate_ind_t. More...
void	mlme_disassociate_request (uint8_t *m)
	Handles the MLME disassociate request command from the NWK layer. More...
retval_t	mlme_get (uint8_t attribute, pib_value_t *attribute_value)
void	mlme_get_conf (uint8_t *m)
	Wrapper function for messages of type mlme_get_conf_t. More...
void	mlme_get_request (uint8_t *m)
	Handles an MLME-GET.request. More...
void	mlme_gts_conf (uint8_t *m)
void	mlme_gts_ind (uint8_t *m)
void	mlme_gts_request (uint8_t *m)
void	mlme_orphan_ind (uint8_t *m)
	Wrapper function for messages of type mlme_orphan_ind_t. More...
void	mlme_orphan_response (uint8_t *m)
	Implements the MLME-ORPHAN.response. More...
void	mlme_poll_conf (uint8_t *m)
	Wrapper function for messages of type mlme_poll_conf_t. More...
void	mlme_poll_request (uint8_t *m)
	Implements MLME-POLL.request. More...
void	mlme_reset_conf (uint8_t *m)
	Wrapper function for messages of type mlme_reset_conf_t. More...
void	mlme_reset_request (uint8_t *m)
	Resets the MAC layer. More...
void	mlme_rx_enable_conf (uint8_t *m)
	Wrapper function for messages of type mlme_rx_enable_conf_t. More...
void	mlme_rx_enable_request (uint8_t *m)
	Implement the MLME-RX-ENABLE.request primitive. More...
void	mlme_scan_conf (uint8_t *m)
	Wrapper function for messages of type mlme_scan_conf_t. More...
void	mlme_scan_request (uint8_t *m)
	The MLME-SCAN.request primitive makes a request for a node to start a scan procedure. More...
retval_t	mlme_set (uint8_t attribute, pib_value_t *attribute_value, bool set_trx_to_sleep)
	Setting of MAC PIB attributes via functional access. More...
void	mlme_set_conf (uint8_t *m)
	Wrapper function for messages of type mlme_set_conf_t. More...
void	mlme_set_request (uint8_t *m)
	Handles an MLME-SET.request primitive. More...
void	mlme_start_conf (uint8_t *m)
	Wrapper function for messages of type mlme_start_conf_t. More...
void	mlme_start_request (uint8_t *m)
	The MLME-START.request primitive makes a request for the device to start using a new superframe configuration. More...
void	mlme_sync_loss_ind (uint8_t *m)
	Wrapper function for messages of type mlme_sync_loss_ind_t. More...
void	mlme_sync_request (uint8_t *m)
	Implements the MLME-SYNC request. More...

Variables
queue_t	mac_nhle_q
	Queue used by MAC for communication to next higher layer. More...
queue_t	nhle_mac_q
	NHLE to MAC queue in which NHLE pushes all the requests to the MAC layer. More...

#define FCF_ADDR_MASK   (3)

Referenced by add_pending_extended_address_cb(), add_pending_short_address_cb(), find_long_buffer(), find_short_buffer(), and mac_extract_mhr_addr_info().

#define FCF_GET_DEST_ADDR_MODE

(

x

)

(((x) >> FCF_DEST_ADDR_OFFSET) & FCF_ADDR_MASK)

#define FCF_GET_SOURCE_ADDR_MODE

(

x

)

(((x) >> FCF_SOURCE_ADDR_OFFSET) & FCF_ADDR_MASK)

#define MAX_ALLOWED_PAN_DESCRIPTORS

Value:

((LARGE_BUFFER_SIZE - \
    sizeof(mlme_scan_conf_t)) / sizeof(wpan_pandescriptor_t))

Maximum allowed PANDescriptors that is calculated using the large buffer size.

#define MAX_PANDESCRIPTORS   (MAX_ALLOWED_PAN_DESCRIPTORS > 5 ? 5 : MAX_ALLOWED_PAN_DESCRIPTORS)

Active/passive scan: implementation-defined maximum number of PANDescriptors that can be stored.

Referenced by mac_process_beacon_frame(), and scan_proceed().

uint8_t mac_extract_mhr_addr_info

(

uint8_t *

frame_ptr

)

References convert_byte_array_to_16_bit(), convert_byte_array_to_64_bit(), parse_tag::dest_addr, parse_tag::dest_addr_mode, parse_tag::dest_panid, EXT_ADDR_LEN, parse_tag::fcf, FCF_ADDR_MASK, FCF_DEST_ADDR_OFFSET, FCF_LEN, FCF_LONG_ADDR, FCF_PAN_ID_COMPRESSION, FCF_SHORT_ADDR, FCF_SOURCE_ADDR_OFFSET, FCS_LEN, address_field_t::long_address, mac_parse_data, parse_tag::mac_payload_length, parse_tag::mpdu_length, PAN_ID_LEN, SEQ_NUM_LEN, SHORT_ADDR_LEN, address_field_t::short_address, parse_tag::src_addr, parse_tag::src_addr_mode, and parse_tag::src_panid.

Referenced by parse_mpdu().

retval_t mlme_get	(	uint8_t	attribute,
		pib_value_t *	attribute_value
	)

References ADDR_COPY_DST_SRC_16, ADDR_COPY_DST_SRC_64, mac_pib_tag::mac_AssociatedPANCoord, mac_pib_tag::mac_AssociationPermit, mac_pib_tag::mac_AutoRequest, mac_pib_tag::mac_BattLifeExtPeriods, mac_beacon_payload, mac_pib_tag::mac_BeaconPayloadLength, mac_pib_tag::mac_BSN, mac_pib_tag::mac_CoordExtendedAddress, mac_pib_tag::mac_CoordShortAddress, mac_pib_tag::mac_DSN, MAC_INVALID_INDEX, mac_pib_tag::mac_MaxFrameTotalWaitTime, mac_pib, mac_pib_tag::mac_ResponseWaitTime, mac_pib_tag::mac_RxOnWhenIdle, mac_pib_tag::mac_SecurityEnabled, mac_state, MAC_SUCCESS, mac_sync_state, mac_pib_tag::mac_TransactionPersistenceTime, MAC_UNSUPPORTED_ATTRIBUTE, macAssociatedPANCoord, macAssociationPermit, macAutoRequest, macBattLifeExt, macBattLifeExtPeriods, macBeaconOrder, macBeaconPayload, macBeaconPayloadLength, macBeaconTxTime, macBSN, macCoordExtendedAddress, macCoordShortAddress, macDSN, macIeeeAddress, macMaxBE, macMaxCSMABackoffs, macMaxFrameRetries, macMaxFrameTotalWaitTime, macMinBE, macPANId, macPrivateIllegalFrameType, macPrivateMACState, macPrivateMACSyncState, macPrivateNoDataAfterAssocReq, macPrivateVirtualPANs, macPromiscuousMode, macResponseWaitTime, macRxOnWhenIdle, macSecurityEnabled, macShortAddress, macSuperframeOrder, macTransactionPersistenceTime, MEMCPY_ENDIAN, phyCCAMode, phyChannelsSupported, phyCurrentChannel, phyCurrentPage, phyMaxFrameDuration, phySHRDuration, phySymbolsPerOctet, phyTransmitPower, pib_value_t::pib_value_16bit, pib_value_t::pib_value_8bit, mac_pib_tag::privateIllegalFrameType, mac_pib_tag::privateNoDataAfterAssocReq, mac_pib_tag::privateVirtualPANs, and tal_pib.

Referenced by mlme_get_request().

void mlme_gts_conf

(

uint8_t *

m

)

References bmm_buffer_free(), BMM_BUFFER_POINTER, mlme_gts_conf_tag::GtsChar, mlme_gts_conf_tag::status, and usr_mlme_gts_conf().

void mlme_gts_ind

(

uint8_t *

m

)

References bmm_buffer_free(), BMM_BUFFER_POINTER, mlme_gts_ind_tag::DeviceAddr, mlme_gts_ind_tag::GtsChar, and usr_mlme_gts_ind().

void mlme_gts_request

(

uint8_t *

m

)

References aGTSDescPersistenceTime, BMM_BUFFER_POINTER, frame_info_tag::buffer_header, convert_16_bit_to_byte_array(), convert_spec_16_bit_to_byte_array(), CSMA_SLOTTED, mlme_gts_req_tag::DeviceShortAddr, FCF_ACK_REQUEST, FCF_FRAMETYPE_MAC_CMD, FCF_PAN_ID_COMPRESSION, FCF_SET_DEST_ADDR_MODE, FCF_SET_FRAMETYPE, FCF_SET_SOURCE_ADDR_MODE, FCF_SHORT_ADDR, GTS_ALLOCATE, GTS_DEALLOCATE, GTS_REQ_PAYLOAD_LEN, GTS_STATE_IDLE, GTS_STATE_REQ_SENT, mlme_gts_req_tag::GtsChar, gts_char_tag::GtsCharType, gts_char_tag::GtsDirection, gts_char_tag::GtsLength, GTSREQUEST, LARGE_BUFFER_SIZE, MAC_ASSOCIATED, mac_pib_tag::mac_CoordShortAddress, mac_dev_gts_table, mac_pib_tag::mac_DSN, mac_gen_mlme_gts_conf(), mac_gts_allocate(), mac_gts_deallocate(), mac_pib_tag::mac_GTSPermit, MAC_INVALID_PARAMETER, MAC_NO_DATA, MAC_NO_SHORT_ADDR_VALUE, MAC_NO_SHORT_ADDRESS, MAC_PAN_COORD_STARTED, mac_pib, mac_state, MAC_SUCCESS, mac_sync_state, MAC_SYNC_TRACKING_BEACON, mac_trx_wakeup(), MAKE_MAC_BUSY, frame_info_tag::mpdu, frame_info_tag::msg_type, tal_pib, and tal_tx_frame().

retval_t mlme_set	(	uint8_t	attribute,
		pib_value_t *	attribute_value,
		bool	set_trx_to_sleep
	)

Setting of MAC PIB attributes via functional access.

In case the highest stack layer is above MAC (e.g. NWK or even higher), it is not efficient to change PIB attributes using the standard request / confirm primitive concept via the NHLE_MAC queue. In order to allow a more efficient way to change PIB attributes residing in MAC or TAL, this function replaces the standard primitive access via a functional interface.

An additional parameter allows for forcing the transceiver back to sleep after PIB setting. Otherwise the transceiver will stay awake (if it has been woken up before). This enables the higher layer to change several PIB attributes without waking up the transceiver and putting it back to sleep several times.

Parameters

attribute	PIB attribute to be set
attribute_index	Index of the PIB attribute to be set
attribute_value	Attribute value to be set
set_trx_to_sleep	Set TRX back to sleep after this PIB access if it was before starting this TRX access. Otherwise the transceiver state will remain as it is, i.e. in case the transceiver was woken up, it will stay awake. The default value for just changing one variable is true, i.e. the transceiver will be put back to sleep if it has been woken up.

Returns

Status of the attempt to set the TAL PIB attribute: MAC_UNSUPPORTED_ATTRIBUTE if the PIB attribute was not found MAC_SUCCESS if the attempt to set the PIB attribute was successful TAL_BUSY if the TAL is not in an idle state to change PIB attributes

References aMaxBeaconPayloadLength, mac_pib_tag::mac_AssociatedPANCoord, mac_pib_tag::mac_AssociationPermit, mac_pib_tag::mac_AutoRequest, mac_pib_tag::mac_BattLifeExtPeriods, mac_beacon_payload, mac_pib_tag::mac_BeaconPayloadLength, mac_pib_tag::mac_BSN, mac_pib_tag::mac_CoordExtendedAddress, mac_pib_tag::mac_CoordShortAddress, mac_pib_tag::mac_DSN, mac_pib_tag::mac_GTSPermit, MAC_INVALID_INDEX, MAC_INVALID_PARAMETER, mac_pib_tag::mac_MaxFrameTotalWaitTime, mac_pib, mac_pib_tag::mac_ResponseWaitTime, mac_pib_tag::mac_RxOnWhenIdle, mac_pib_tag::mac_SecurityEnabled, mac_sleep_trans(), MAC_SUCCESS, mac_pib_tag::mac_TransactionPersistenceTime, mac_trx_wakeup(), MAC_UNSUPPORTED_ATTRIBUTE, macAckWaitDuration, macAssociatedPANCoord, macAssociationPermit, macAutoRequest, macBattLifeExt, macBattLifeExtPeriods, macBeaconOrder, macBeaconPayload, macBeaconPayloadLength, macBSN, macCoordExtendedAddress, macCoordShortAddress, macDSN, macGTSPermit, macIeeeAddress, macMaxBE, macMaxCSMABackoffs, macMaxFrameRetries, macMaxFrameTotalWaitTime, macMinBE, macPANCoordExtendedAddress, macPANCoordShortAddress, macPANId, macPrivateCCAFailure, macPrivateDisableACK, macPrivateIllegalFrameType, macPrivateNoDataAfterAssocReq, macPrivateVirtualPANs, macPromiscuousMode, macResponseWaitTime, macRxOnWhenIdle, macSecurityEnabled, macShortAddress, macSuperframeOrder, macTransactionPersistenceTime, PHY_RX_ON, phyCCAMode, phyCurrentChannel, phyCurrentPage, phyTransmitPower, pib_value_t::pib_value_16bit, pib_value_t::pib_value_32bit, pib_value_t::pib_value_64bit, pib_value_t::pib_value_8bit, mac_pib_tag::privateIllegalFrameType, mac_pib_tag::privateNoDataAfterAssocReq, mac_pib_tag::privateVirtualPANs, recalc_macMaxFrameTotalWaitTime(), SLEEP_MODE_1, tal_pib_set(), tal_rx_enable(), TAL_TRX_ASLEEP, tal_trx_sleep(), and tal_trx_wakeup().

Referenced by mlme_set_request().

queue_t mac_nhle_q

Queue used by MAC for communication to next higher layer.

Referenced by flush_queues(), gen_mlme_poll_conf(), gen_mlme_start_conf(), gen_rx_enable_conf(), mac_awake_scan(), mac_gen_mcps_data_conf(), mac_gen_mlme_associate_conf(), mac_gen_mlme_disassociate_conf(), mac_gen_mlme_gts_conf(), mac_gts_table_update(), mac_mlme_comm_status(), mac_process_associate_request(), mac_process_beacon_frame(), mac_process_data_frame(), mac_process_disassociate_notification(), mac_process_gts_request(), mac_process_orphan_notification(), mac_process_orphan_realign(), mac_process_tal_tx_status(), mac_ready_to_sleep(), mac_send_gts_ind(), mac_sync_loss(), mcps_purge_request(), mlme_get_request(), mlme_scan_request(), mlme_set_request(), parse_mpdu(), scan_clean_up(), scan_proceed(), and send_reset_conf().

queue_t nhle_mac_q

NHLE to MAC queue in which NHLE pushes all the requests to the MAC layer.

Referenced by flush_queues(), mac_init(), wpan_mcps_data_req(), wpan_mcps_purge_req(), wpan_mlme_associate_req(), wpan_mlme_associate_resp(), wpan_mlme_disassociate_req(), wpan_mlme_get_req(), wpan_mlme_gts_req(), wpan_mlme_orphan_resp(), wpan_mlme_poll_req(), wpan_mlme_reset_req(), wpan_mlme_rx_enable_req(), wpan_mlme_scan_req(), wpan_mlme_set_req(), wpan_mlme_start_req(), and wpan_mlme_sync_req().