This module describes all MCL Request API's.
Functions | |
| void | mcps_data_request (uint8_t *msg) |
| Builds the data frame for transmission. More... | |
| void | mcps_purge_request (uint8_t *msg) |
| Processes a MCPS-PURGE.request primitive. More... | |
| void | mlme_associate_request (uint8_t *m) |
| Handles the MLME associate request command from the NWK layer. More... | |
| void | mlme_disassociate_request (uint8_t *m) |
| Handles the MLME disassociate request command from the NWK layer. More... | |
| void | mlme_get_request (uint8_t *m) |
| Handles an MLME-GET.request. More... | |
| void | mlme_poll_request (uint8_t *m) |
| Implements MLME-POLL.request. More... | |
| void | mlme_reset_request (uint8_t *m) |
| Resets the MAC layer. More... | |
| void | mlme_rx_enable_request (uint8_t *m) |
| Implement the MLME-RX-ENABLE.request primitive. 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... | |
| void | mlme_set_request (uint8_t *m) |
| Handles an MLME-SET.request primitive. 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_request (uint8_t *m) |
| Implements the MLME-SYNC request. More... | |
| void mcps_data_request | ( | uint8_t * | msg | ) |
Builds the data frame for transmission.
This function builds the data frame for transmission. The NWK layer has supplied the parameters. The frame_info_t data type is constructed and filled in. Also the FCF is constructed based on the parameters passed.
| msg | Pointer to the MCPS-DATA.request parameter |
References ADDR_COPY_DST_SRC_16, BMM_BUFFER_POINTER, BROADCAST, frame_info_tag::buffer_header, build_data_frame(), CSMA_SLOTTED, CSMA_UNSLOTTED, mcps_data_req_tag::DstAddr, mcps_data_req_tag::DstAddrMode, FAILURE, FCF_NO_ADDR, FCF_RESERVED_ADDR, FCF_SECURITY_ENABLED, FCF_SHORT_ADDR, indirect_data_q, frame_info_tag::indirect_in_transit, MAC_ASSOCIATED, MAC_CHANNEL_ACCESS_FAILURE, mac_check_persistence_timer(), MAC_COORDINATOR, mac_pib_tag::mac_CoordShortAddress, mac_gen_mcps_data_conf(), MAC_INVALID_ADDRESS, MAC_INVALID_PARAMETER, MAC_PAN_COORD_STARTED, mac_pib, MAC_POLL_IDLE, mac_poll_state, MAC_SCAN_IDLE, mac_scan_state, mac_sleep_trans(), mac_state, MAC_SUCCESS, MAC_TRANSACTION_OVERFLOW, mac_pib_tag::mac_TransactionPersistenceTime, mac_trx_wakeup(), MAKE_MAC_BUSY, MCPS_MESSAGE, frame_info_tag::mpdu, mcps_data_req_tag::msduHandle, frame_info_tag::msduHandle, frame_info_tag::msg_type, NON_BEACON_NWK, frame_info_tag::persistence_time, qmm_queue_append(), QUEUE_FULL, mcps_data_req_tag::SrcAddrMode, tal_pib, tal_tx_frame(), mcps_data_req_tag::TxOptions, WPAN_TXOPT_ACK, WPAN_TXOPT_GTS, and WPAN_TXOPT_INDIRECT.
| void mcps_purge_request | ( | uint8_t * | msg | ) |
Processes a MCPS-PURGE.request primitive.
This functions processes a MCPS-PURGE.request from the NHLE. The MCPS-PURGE.request primitive allows the next higher layer to purge an MSDU from the transaction queue. On receipt of the MCPS-PURGE.request primitive, the MAC sublayer attempts to find in its transaction queue the MSDU indicated by the msduHandle parameter. If an MSDU matching the given handle is found, the MSDU is discarded from the transaction queue, and the MAC sublayer issues the MCPSPURGE. confirm primitive with a status of MAC_SUCCESS. If an MSDU matching the given handle is not found, the MAC sublayer issues the MCPS-PURGE.confirm primitive with a status of INVALID_HANDLE.
| msg | Pointer to the MCPS-PURGE.request parameter |
References BMM_BUFFER_POINTER, mcps_purge_conf_tag::cmdcode, mac_buffer_purge(), MAC_INVALID_HANDLE, mac_nhle_q, MAC_SUCCESS, MCPS_PURGE_CONFIRM, mcps_purge_req_tag::msduHandle, mcps_purge_conf_tag::msduHandle, qmm_queue_append(), and mcps_purge_conf_tag::status.
| void mlme_associate_request | ( | uint8_t * | m | ) |
Handles the MLME associate request command from the NWK layer.
The MLME associate request primitive is generated by the next higher layer of an unassociated device and issued to its MAC to request an association with a coordinator.
| m | Pointer to MLME association request parameters |
References ADDR_COPY_DST_SRC_16, ADDR_COPY_DST_SRC_64, Assert, ASSOC_REQ_PAYLOAD_LEN, ASSOCIATIONREQUEST, BMM_BUFFER_POINTER, BROADCAST, frame_info_tag::buffer_header, mlme_associate_req_tag::CapabilityInformation, CCPU_ENDIAN_TO_LE16, mlme_associate_req_tag::ChannelPage, convert_16_bit_to_byte_array(), convert_64_bit_to_byte_array(), convert_spec_16_bit_to_byte_array(), mlme_associate_req_tag::CoordAddress, mlme_associate_req_tag::CoordAddrMode, mlme_associate_req_tag::CoordPANId, CSMA_SLOTTED, CSMA_UNSLOTTED, FCF_ACK_REQUEST, FCF_FRAMETYPE_MAC_CMD, FCF_LONG_ADDR, FCF_SET_DEST_ADDR_MODE, FCF_SET_FRAMETYPE, FCF_SET_SOURCE_ADDR_MODE, FCF_SHORT_ADDR, INVALID_SHORT_ADDRESS, LARGE_BUFFER_SIZE, mlme_associate_req_tag::LogicalChannel, address_field_t::long_address, MAC_CHANNEL_ACCESS_FAILURE, mac_conf_buf_ptr, mac_pib_tag::mac_CoordExtendedAddress, mac_pib_tag::mac_CoordShortAddress, mac_pib_tag::mac_DSN, mac_gen_mlme_associate_conf(), MAC_INVALID_PARAMETER, MAC_NO_SHORT_ADDR_VALUE, mac_pib, mac_sleep_trans(), MAC_SUCCESS, MAC_SYNC_BEFORE_ASSOC, mac_sync_state, mac_trx_wakeup(), macPANId, MAKE_MAC_BUSY, frame_info_tag::mpdu, frame_info_tag::msg_type, phyCurrentChannel, phyCurrentPage, set_tal_pib_internal(), address_field_t::short_address, tal_pib, and tal_tx_frame().
| void mlme_disassociate_request | ( | uint8_t * | m | ) |
Handles the MLME disassociate request command from the NWK layer.
The MLME-DISASSOCIATE.request primitive is generated by the next higher layer of an associated device and issued to its MLME to request disassociation from the PAN. It is also generated by the next higher layer of the coordinator and issued to its MLME to instruct an associated device to leave the PAN.
| m | Pointer to the MLME-DISASSOCIATION.Request message passed by NHLE |
References BMM_BUFFER_POINTER, frame_info_tag::buffer_header, convert_16_bit_to_byte_address(), convert_16_bit_to_byte_array(), convert_64_bit_to_byte_array(), convert_spec_16_bit_to_byte_array(), mlme_disassociate_req_tag::DeviceAddress, mlme_disassociate_req_tag::DeviceAddrMode, mlme_disassociate_req_tag::DevicePANId, DISASSOC_PAYLOAD_LEN, mlme_disassociate_req_tag::DisassociateReason, DISASSOCIATIONNOTIFICATION, FCF_ACK_REQUEST, FCF_FRAMETYPE_MAC_CMD, FCF_LONG_ADDR, FCF_PAN_ID_COMPRESSION, FCF_SET_DEST_ADDR_MODE, FCF_SET_FRAMETYPE, FCF_SET_SOURCE_ADDR_MODE, FCF_SHORT_ADDR, indirect_data_q, frame_info_tag::indirect_in_transit, LARGE_BUFFER_SIZE, mac_awake_disassociate(), MAC_CHANNEL_ACCESS_FAILURE, mac_check_persistence_timer(), mac_pib_tag::mac_CoordExtendedAddress, MAC_COORDINATOR, mac_pib_tag::mac_DSN, mac_gen_mlme_disassociate_conf(), MAC_INVALID_PARAMETER, MAC_PAN_COORD_STARTED, mac_pib, mac_sleep_trans(), mac_state, MAC_TRANSACTION_OVERFLOW, mac_pib_tag::mac_TransactionPersistenceTime, mac_trx_wakeup(), macCoordShortAddress, frame_info_tag::mpdu, frame_info_tag::msg_type, frame_info_tag::persistence_time, qmm_queue_append(), QUEUE_FULL, tal_pib, mlme_disassociate_req_tag::TxIndirect, WPAN_ADDRMODE_LONG, and WPAN_ADDRMODE_SHORT.
| void mlme_get_request | ( | uint8_t * | m | ) |
Handles an MLME-GET.request.
This function handles an MLME-GET.request. The MLME-GET.request primitive requests information about a given PIB attribute.
| m | Pointer to the request structure |
References BMM_BUFFER_POINTER, mlme_get_conf_tag::cmdcode, mac_nhle_q, MAC_SUCCESS, mlme_get(), MLME_GET_CONFIRM, mlme_get_conf_tag::PIBAttribute, mlme_get_conf_tag::PIBAttributeValue, qmm_queue_append(), and mlme_get_conf_tag::status.
| void mlme_poll_request | ( | uint8_t * | m | ) |
Implements MLME-POLL.request.
This function handles an MLME-POLL.request primitive. The MLME-POLL.request primitive is generated by the next higher layer and issued to its MLME when data are to be requested from a coordinator.
| m | Pointer to the message |
References ADDR_COPY_DST_SRC_16, ADDR_COPY_DST_SRC_64, BMM_BUFFER_POINTER, mlme_poll_req_tag::CoordAddress, mlme_poll_req_tag::CoordAddrMode, mlme_poll_req_tag::CoordPANId, FCF_LONG_ADDR, FCF_SHORT_ADDR, gen_mlme_poll_conf(), address_field_t::long_address, mac_build_and_tx_data_req(), MAC_CHANNEL_ACCESS_FAILURE, mac_conf_buf_ptr, MAC_PAN_COORD_STARTED, MAC_POLL_IDLE, mac_poll_state, MAC_SCAN_IDLE, mac_scan_state, MAC_START_REQUEST_CONFIRM, mac_state, mac_trx_wakeup(), and address_field_t::short_address.
| void mlme_reset_request | ( | uint8_t * | m | ) |
Resets the MAC layer.
The MLME-RESET.request primitive allows the next higher layer to request that the MLME performs a reset operation.
| m | Pointer to the MLME_RESET.request given by the NHLE |
References BMM_BUFFER_POINTER, flush_queues(), mac_reset(), mac_sleep_trans(), mac_trx_wakeup(), send_reset_conf(), and mlme_reset_req_tag::SetDefaultPIB.
| void mlme_rx_enable_request | ( | uint8_t * | m | ) |
Implement the MLME-RX-ENABLE.request primitive.
The MLME-RX-ENABLE.request primitive is generated by the next higher layer and issued to MAC to enable the receiver for a fixed duration, at a time relative to the start of the current or next superframe on a beacon-enabled PAN or immediately on a nonbeacon-enabled PAN. The receiver is enabled exactly once per primitive request.
| m | Pointer to the MLME-RX-ENABLE.request message |
References BMM_BUFFER_POINTER, mlme_rx_enable_req_tag::DeferPermit, FUNC_PTR, gen_rx_enable_conf(), handle_rx_on(), MAC_INVALID_PARAMETER, MAC_PAST_TIME, MAC_POLL_IDLE, mac_poll_state, MAC_SCAN_IDLE, mac_scan_state, MAC_SUCCESS, mac_t_rx_off_cb(), MAC_TX_ACTIVE, MIN_TIMEOUT, NON_BEACON_NWK, pal_get_current_time(), pal_timer_start(), pal_timer_stop(), mlme_rx_enable_req_tag::RxOnDuration, mlme_rx_enable_req_tag::RxOnTime, T_Rx_Enable, tal_add_time_symbols(), TAL_CONVERT_SYMBOLS_TO_US, TAL_CONVERT_US_TO_SYMBOLS, TAL_GET_BEACON_INTERVAL_TIME, tal_pib, tal_sub_time_symbols(), and TIMEOUT_ABSOLUTE.
| void mlme_scan_request | ( | uint8_t * | m | ) |
The MLME-SCAN.request primitive makes a request for a node to start a scan procedure.
802.15.4. Section 7.1.11.1.
The MLME-SCAN.request primitive is used to initiate a channel scan over a given list of channels. A device can use a channel scan to measure the energy on the channel, search for the coordinator with which it associated, or search for all coordinators transmitting beacon frames within the POS of the scanning device.
The MLME-SCAN.request primitive is generated by the next higher layer and issued to its MLME to initiate a channel scan to search for activity within the POS of the device. This primitive can be used to perform an ED scan to determine channel usage, an active or passive scan to locate beacon frames containing any PAN identifier, or an orphan scan to locate a PAN to which the device is currently associated.
ED or active scans can be performed before an FFD starts operation as a PAN coordinator. Active or passive scans can be performed prior to selecting a PAN for association. Orphan scans can be performed to attempt to locate a specific coordinator with which communication has been lost.
All devices shall be capable of performing passive scans and orphan scans; ED scans and active scans are optional for an RFD.
When the MLME receives the MLME-SCAN.request primitive, it initiates a scan in all channels specified in the ScanChannels parameter. The MLME suspends all beacon transmissions for the duration of the scan. During a scan, the MAC sublayer only accepts frames received over the PHY data service that are relevant to the scan being performed (see 7.5.2.1).
An ED scan allows a device to obtain a measure of the peak energy in each requested channel. The ED scan is performed on each channel by the MLMEs repeatedly issuing the PLME-ED.request primitive to the PHY until [aBaseSuperframeDuration * (2n + 1)] symbols, where n is the value of the ScanDuration parameter, have elapsed. The MLME notes the maximum energy measurement and moves on to the next channel in the channel list. A device will be able to store between one and an implementation-specified maximum number of channel ED measurements. The ED scan terminates when the number of channel ED measurements stored equals this implementation-specified maximum or when every channel specified in the channel list has been scanned.
An active scan is used by an FFD to locate all coordinators transmitting beacon frames within its POS. The active scan is performed on each channel by the MLMEs first sending a beacon request command (see 7.3.2.4). The MLME then enables the receiver and records the information contained in each received beacon in a PAN descriptor structure (see Table 41 in 7.1.5.1.1). A device will be able to store between one and an implementation-specified maximum number of PAN descriptors. The active scan on a particular channel terminates when the number of PAN descriptors stored equals this implementation-specified maximum or when [aBaseSuperframeDuration*(2n + 1)] symbols, where n is the value of the ScanDuration parameter, have elapsed. If the latter condition has been satisfied, the channel is considered to have been scanned. Where possible, the scan is repeated on each channel and terminates when the number of PAN descriptors stored equals the implementation-specified maximum or when every channel in the set of available channels has been scanned.
A passive scan, like an active scan, is used to locate all coordinators transmitting beacon frames within the POS of the scanning device; the difference is that the passive scan is a receive-only operation and does not transmit the beacon request command. The passive scan is performed on each channel by the MLMEs enabling its receiver and recording the information contained in each received beacon in a PAN descriptor structure (see Table 41 in 7.1.5.1.1). A device will be able to store between one and an implementation-specified maximum number of PAN descriptors. The passive scan on a particular channel terminates when the number of PAN descriptors stored equals this implementation-specified maximum or when [aBaseSuperframeDuration * (2n + 1)] symbols, where n is the value of the ScanDuration parameter, have elapsed. If the latter condition has been satisfied, the channel is considered to have been scanned. Where possible, the scan is repeated on each channel and terminates when the number of PAN descriptors stored equals the implementation-specified maximum or when every channel in the set of available channels has been scanned.
An orphan scan is used to locate the coordinator with which the scanning device had previously associated. The orphan scan is performed on each channel by the MLME first sending an orphan notification command (see 7.3.2.3). The MLME then enables its receiver for at most aResponseWaitTime symbols. If the device receives a coordinator realignment command within this time, the MLME will disable its receiver. Otherwise, the scan is repeated on the next channel in the channel list. The scan terminates when the device receives a coordinator realignment command (see 7.3.2.5) or when every channel in the set of available channels has been scanned.
The results of an ED scan are recorded in a list of ED values and reported to the next higher layer through the MLME-SCAN.confirm primitive with a status of MAC_SUCCESS. The results of an active or passive scan are recorded in a set of PAN descriptor values and reported to the next higher layer through the MLME-SCAN.confirm primitive. If no beacons were found, the MLME-SCAN.confirm primitive will contain a null set of PAN descriptor values and a status of NO_BEACON. Otherwise, the MLME-SCAN.confirm primitive will contain the set of PANDescriptor values found, a list of unscanned channels, and a status of MAC_SUCCESS.
The results of an orphan scan are reported to the next higher layer through the MLME-SCAN.confirm primitive. If successful, the MLME-SCAN.confirm primitive will contain a status of MAC_SUCCESS. If the device did not receive a coordinator realignment command, MLME-SCAN.confirm primitive will contain a status of NO_BEACON. In either case, the PANDescriptorList and EnergyDetectList parameters of the MLMESCAN.confirm primitive are null.
If any parameter in the MLME-SCAN.request primitive is not supported or is out of range, the MAC sublayer will issue the MLME-SCAN.confirm primitive with a status of MAC_INVALID_PARAMETER.
| m | The MLME_SCAN.request message |
References BEACON_NETWORK_MAX_BO, BMM_BUFFER_POINTER, mlme_scan_req_tag::ChannelPage, mlme_scan_conf_tag::ChannelPage, mlme_scan_conf_tag::cmdcode, scan_result_list_t::ed_value, INVERSE_CHANNEL_MASK, mac_awake_scan(), mac_conf_buf_ptr, MAC_INVALID_PARAMETER, mac_nhle_q, MAC_POLL_IDLE, mac_poll_state, MAC_SCAN_IDLE, mac_scan_orig_channel, mac_scan_orig_page, mac_scan_state, mac_trx_wakeup(), MLME_SCAN_CONFIRM, MLME_SCAN_TYPE_ED, qmm_queue_append(), mlme_scan_conf_tag::ResultListSize, scan_channels, scan_curr_page, scan_duration, mlme_scan_conf_tag::scan_result_list, scan_type, mlme_scan_req_tag::ScanChannels, mlme_scan_req_tag::ScanDuration, mlme_scan_req_tag::ScanType, mlme_scan_conf_tag::ScanType, mlme_scan_conf_tag::status, tal_pib, and mlme_scan_conf_tag::UnscannedChannels.
| void mlme_set_request | ( | uint8_t * | m | ) |
Handles an MLME-SET.request primitive.
This function handles the MLME-SET.request. The MLME-SET.request primitive attempts to write the given value to the indicated PIB attribute.
| m | Pointer to the request structure |
References BMM_BUFFER_POINTER, mlme_set_conf_tag::cmdcode, mac_nhle_q, MAC_SUCCESS, mlme_set(), MLME_SET_CONFIRM, mlme_set_req_tag::PIBAttribute, mlme_set_conf_tag::PIBAttribute, mlme_set_req_tag::PIBAttributeValue, qmm_queue_append(), and mlme_set_conf_tag::status.
| 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.
| m | Pointer to MLME_START.request message issued by the NHLE |
References mlme_start_req_tag::BeaconOrder, BMM_BUFFER_POINTER, BROADCAST, mlme_start_req_tag::ChannelPage, check_start_parameter(), COORDINATORREALIGNMENT, mlme_start_req_tag::CoordRealignment, gen_mlme_start_conf(), mlme_start_req_tag::LogicalChannel, MAC_COORDINATOR, mac_i_pan_coordinator, MAC_INVALID_PARAMETER, MAC_NO_SHORT_ADDRESS, MAC_PAN_COORD_STARTED, mac_sleep_trans(), mac_state, MAC_SUCCESS, mac_trx_wakeup(), mac_tx_coord_realignment_command(), macBattLifeExt, macBeaconOrder, macPANId, macSuperframeOrder, NON_BEACON_NWK, mlme_start_req_tag::PANCoordinator, mlme_start_req_tag::PANId, PHY_RX_ON, phyCurrentChannel, phyCurrentPage, set_tal_pib_internal(), mlme_start_req_tag::SuperframeOrder, tal_pib, and tal_rx_enable().
| void mlme_sync_request | ( | uint8_t * | m | ) |
Implements the MLME-SYNC request.
The MLME-SYNC.request primitive requests to synchronize with the coordinator by acquiring and, if specified, tracking its beacons. The MLME-SYNC.request primitive is generated by the next higher layer of a device on a beacon-enabled PAN and issued to its MLME to synchronize with the coordinator.
Enable receiver and search for beacons for at most an interval of [aBaseSuperframeDuration * ((2 ^ (n))+ 1)] symbols where n is the value of macBeaconOrder. If a beacon frame containing the current PAN identifier of the device is not received, the MLME shall repeat this search. Once the number of missed beacons reaches aMaxLostBeacons, the MLME shall notify the next higher layer by issuing the MLME-SYNC-LOSS.indication primitive with a loss reason of BEACON_LOSS.
| m | Pointer to the MLME sync request parameters. |
1.8.5