nRF5 SDK v13.0.0
Data Structures | Typedefs | Enumerations | Functions
MAC MLME PIB API

Module to declare MAC MLME PIB API. More...

Data Structures

union  pib_id_t
 United PIB attribute identifiers. More...
 
struct  mlme_get_conf_t
 MLME-GET.confirm. More...
 
struct  mlme_get_req_t
 MLME-GET.request. More...
 
struct  mlme_set_conf_t
 MLME-SET.confirm. More...
 
struct  mlme_set_req_t
 MLME-SET.request. More...
 

Typedefs

typedef void(* mlme_get_conf_cb_t )(mlme_get_conf_t *)
 Customer's function of confirmation. More...
 
typedef void(* mlme_set_conf_cb_t )(mlme_set_conf_t *)
 Customer's function of confirmation. More...
 

Enumerations

enum  mlme_pib_attr_id_t {
  MAC_ACK_WAIT_DURATION = 0x40,
  MAC_ASSOCIATION_PERMIT,
  MAC_AUTO_REQUEST,
  MAC_BATT_LIFE_EXT,
  MAC_BATT_LIFE_EXT_PERIODS,
  MAC_BEACON_PAYLOAD,
  MAC_BEACON_PAYLOAD_LENGTH,
  MAC_BEACON_ORDER,
  MAC_BEACON_TX_TIME,
  MAC_BSN,
  MAC_COORD_EXTENDED_ADDRESS,
  MAC_COORD_SHORT_ADDRESS,
  MAC_DSN,
  MAC_GTS_PERMIT,
  MAC_MAX_CSMA_BACKOFFS,
  MAC_MIN_BE,
  MAC_PAN_ID,
  MAC_PROMISCUOUS_MODE,
  MAC_RX_ON_WHEN_IDLE,
  MAC_SHORT_ADDRESS,
  MAC_SUPERFRAME_ORDER,
  MAC_TRANSACTION_PERSISTENCE_TIME,
  MAC_ASSOCIATED_PAN_COORD,
  MAC_MAX_BE,
  MAC_MAX_FRAME_TOTAL_WAIT_TIME,
  MAC_MAX_FRAME_RETRIES,
  MAC_RESPONSE_WAIT_TIME,
  MAC_SYNC_SYMBOL_OFFSET,
  MAC_TIMESTAMP_SUPPORTED,
  MAC_SECURITY_ENABLED,
  MAC_MIN_LIFS_PERIOD,
  MAC_MIN_SIFS_PERIOD,
  MAC_EXTENDED_ADDRESS,
  MAC_IS_PAN_COORD
}
 MAC PIB attribute identificators. More...
 

Functions

void mlme_get_req (mlme_get_req_t *req, mlme_get_conf_cb_t conf_cb)
 MLME-GET request. More...
 
void mlme_set_req (mlme_set_req_t *req, mlme_set_conf_cb_t conf_cb)
 MLME-SET request. More...
 
size_t mlme_pib_attr_size_calc (pib_id_t id, uint8_t idx)
 Counts MLME attribute size. More...
 
mac_status_t mlme_get (pib_id_t id, uint8_t idx, void *mem)
 Gets parameters from PIB directly (without request - confirm approach) More...
 
mac_status_t mlme_set (pib_id_t id, uint8_t idx, void *mem)
 Sets parameters to PIB directly (without request - confirm approach) More...
 

Detailed Description

Module to declare MAC MLME PIB API.

The MAC PIB module declares routines and necessary types to deal with the PHY Information Base functionality related to MAC. More specifically, MLME PIB Get request aka mlme_get_req(), MLME PIB Set request aka mlme_set_req(), MLME PIB confirmation callbacks aka mlme_get_conf_cb_t, and mlme_set_conf_cb_t primitives are declared. Two additional primitives not covered by the standard are declared. These are mlme_get() and mlme_set() which are synchronous versions of mlme_get_req() and mlme_set_req() accordingly. There is one helper informational routine mlme_pib_attr_size_calc() to count MLME attribute size in bytes. Refer to the mac_pib_param_test application for detailed samples of implementation of these primitives. This module also defines the MAC Table API. The tables can be used to deal with MAC attributes. A special initialization routine mac_table_init() should be called before using of any other MAC table API. The mac_table_reset() routine is used to clean up an existing (initialized) table. mac_table_idx_get() searches through a MAC table to find the item with requested idx. The mac_table_item_set() routine is needed to substitute a table item with a new value. The mac_table_item_remove() routine removes the item with the given index from the table and frees all resources associated with the item. mac_table_item_front() and mac_table_item_next() return the first and next item from the table. The mac_table_size_get() routine returns the number of items in the table, while mac_table_is_empty() checks if the table is empty.

Typedef Documentation

typedef void(* mlme_get_conf_cb_t)(mlme_get_conf_t *)

Customer's function of confirmation.

The MLME-GET.confirm primitive is generated by the MLME and issued to its next higher layer in response to an MLME-GET.request primitive. This primitive returns a status of either SUCCESS, indicating that the request to read a PIB attribute was successful, or an error code of UNSUPPORTED_ATTRIBUTE. When an error code of UNSUPPORTED_ATTRIBUTE is returned, the PIBAttribute value parameter will be set to length zero. The status values are fully described in 7.1.6.1.3.

Parameters
pointerto confirmation primitive
typedef void(* mlme_set_conf_cb_t)(mlme_set_conf_t *)

Customer's function of confirmation.

The MLME-SET.confirm primitive is generated by the MLME and issued to its next higher layer in response to an MLME-SET.request primitive. The MLME-SET.confirm primitive returns a status of either SUCCESS, indicating that the requested value was written to the indicated PIB attribute, or the appropriate error code. The status values are fully described in 7.1.13.1.3.

Parameters
pointerto confirmation primitive

Enumeration Type Documentation

MAC PIB attribute identificators.

In accordance with IEEE Std 802.15.4-2006, section 7.4.2

Enumerator
MAC_BEACON_ORDER 

Specification of how often the coordinator transmits its beacon. If BO = 15, the coordinator will not transmit a periodic beacon.

Function Documentation

mac_status_t mlme_get ( pib_id_t  id,
uint8_t  idx,
void *  mem 
)

Gets parameters from PIB directly (without request - confirm approach)

Optional. Not covered by a standard.

For non-tabled attributes this function will return value to location passed to the last argument.

For tabled attributes this function will return pointer to a descriptor structure of corresponding table.

Parameters
[in]idattribute id.
[in]idxindex inside the table in case the attribute is a table.
[out]memeither pointer to memory where attribute value is returned (for all attributes except MAC_KEY_TABLE, MAC_DEVICE_TABLE, MAC_SECURITY_LEVEL_TABLE), or pointer to memory where pointer to attribute storage place is returned.
Returns
status of operation
void mlme_get_req ( mlme_get_req_t req,
mlme_get_conf_cb_t  conf_cb 
)

MLME-GET request.

Request information about a given PIB attribute.

Parameters
[in]reqpointer to request structure.
[in]conf_cbpointer to user callback.

In accordance with IEEE Std 802.15.4-2006, section 7.1.6. See mlme_get() for more details.

size_t mlme_pib_attr_size_calc ( pib_id_t  id,
uint8_t  idx 
)

Counts MLME attribute size.

This is an implementation-specific function not covered by the standard.

Parameters
[in]idattribute id.
[in]idxindex inside the table in case the attribute is a table.
Returns
size of attribute in bytes.
mac_status_t mlme_set ( pib_id_t  id,
uint8_t  idx,
void *  mem 
)

Sets parameters to PIB directly (without request - confirm approach)

Optional. Not covered by a standard.

     This function performs copying or replacement of some attribute value
     into the PIB base memory.

     Note, that all security tables are copied into dynamic memory, that
     mlme_set is responsible to allocate. For nested tables copying is done
     in a shallow manner (in Python sense). It means that passed \a mac_key_descr_t
     is copied as-is, without creating copies of internal tables.
     Caller must allocate and prepare all nested tables such as
     #MAC_KEY_DEVICE_LIST, #MAC_KEY_ID_LOOKUP_LIST and #MAC_KEY_USAGE_LIST
     before calling this function.

     Passed attribute value will replace the current one, if the item with such
     \a id and \a idx already exists. This function is responsible for
     freeing all items during destruction of existing objects.
Note
Nested tables may be expanded and reduced with mac_table_item_set() and other similar functions.
Parameters
[in]idattribute id.
[in]idxindex inside the table in case the attribute is a table.
[out]mempointer to memory for parameter storing.
Returns
status of operation
void mlme_set_req ( mlme_set_req_t req,
mlme_set_conf_cb_t  conf_cb 
)

MLME-SET request.

Request to set a PIB attribute. After request completion, user callback will be issued with valid data stored in structure mlme_set_conf_t.

See mlme_set() for more details.

In accordance with IEEE Std 802.15.4-2006, section 7.1.13

Parameters
[in]reqMLME_SET request structure.
[in]conf_cbpointer to user callback.

Documentation feedback | Developer Zone | Subscribe | Updated