# SM
[UMAC]

The Station Manager (SM) module is responsible for all the procedures related to the STA role. More...

Collaboration diagram for SM:

## Data Structures
struct | sm_env_tag
| station environment structure More...
## Modules
| TASK_SM

| Declaration of the SM state machine.
## Defines
#define | SM_EXTERNAL_AUTH_TIMEOUT 600000
| Timeout, in us, for external authentication.
#define | SM_MAX_IE_LEN 256
| Maximum length of the AssocReq IEs.
## Functions
static void | sm_frame_tx_cfm_handler (void *env, uint32_t status)
| Frame transmission confirmation handler If the frame is not successfully transmitted it is pushed again until the timeout expires.
static void | sm_bss_config_init (void)
| Initialize the BSS configuration list.
static void | sm_bss_config_push (void *param)
| Push a BSS configuration message to the list.
static void | sm_deauth_cfm (void *env, uint32_t status)
| DEAUTH frame transmission confirmation handler Once the transmission is confirmed we can continue the disconnection process.
static void | sm_delete_resources (struct vif_info_tag *vif)
| Delete the different SW resources that were allocated for this connection.
void | sm_init (void)
| Initialize the SM context.
void | sm_get_bss_params (struct mac_addr const **bssid, struct mac_chan_def const **chan)
| Search for the BSSID and Channel information in the scan results and/or the connection parameters.
void | sm_scan_bss (struct mac_addr const *bssid, struct mac_chan_def const *chan)
| Launch the scan to find the target BSS.
void | sm_join_bss (struct mac_addr const *bssid, struct mac_chan_def const *chan, bool passive)
| Try to join the BSS indicated by the parameters.
uint8_t | sm_add_chan_ctx (uint8_t *chan_idx)
| Add the channel context for the new connection.
void | sm_set_bss_param (void)
| Set the BSS parameters This function prepares the list of BSS configuration messages that will be transmitted to the Lower MAC.
void | sm_bss_config_send (void)
| Send the next BSS parameter message present in the list.
void | sm_disconnect (uint8_t vif_index, uint16_t reason_code)
| Start the disconnection procedure upon the reception of a SM_DISCONNECT_REQ.
void | sm_disconnect_process (struct vif_info_tag *vif, uint16_t reason)
| Terminates the disconnection procedure after reception of a DEAUTH/DISASSOC or the transmission of a DEAUTH frame.
void | sm_connect_ind (uint16_t status)
| Function called at any time during the connection, used to indicate to the host the completion of the procedure (either successful or not).
void | sm_auth_send (uint16_t auth_seq, uint32_t *challenge)
| Send Authentication frame.
void | sm_assoc_req_send (void)
| Send MAC_FCTRL_ASSOCREQ or MAC_FCTRL_REASSOCREQ to the air.
void | sm_assoc_done (uint16_t aid)
| Association completed operations.
void | sm_auth_handler (struct rxu_mgt_ind const *param)
| Function called upon reception of a AUTH frame from the AP.
void | sm_assoc_rsp_handler (struct rxu_mgt_ind const *param)
| Function called upon reception of a ASSOC_RSP frame from the AP.
int | sm_deauth_handler (struct rxu_mgt_ind const *param)
| Function called upon reception of a DEAUTH or DISASSOC frame from the AP.
void | sm_sa_query_handler (struct rxu_mgt_ind const *param)
| Function called upon reception of a SA QUERY action frame.
void | sm_external_auth_start (uint32_t akm)
| Start External Authentication procedure.
void | sm_external_auth_end (uint16_t status)
| End External Authentication procedure.
bool | sm_external_auth_in_progress (void)
| Check if external authentication is in progress.
int | sm_get_rsnie_pmkid_count (uint32_t ies, uint16_t ies_len)
| Return PMKID count from RSN IE.
## Variables
struct sm_env_tag | sm_env
| SM module environment.
struct sm_env_tag | sm_env
| SM module environment.

## Detailed Description

The Station Manager (SM) module is responsible for all the procedures related to the STA role.

It implements the state machines and functions that are involved in the connection and disconnection procedures.

## Function Documentation

uint8_t sm_add_chan_ctx | ( | uint8_t * | chan_idx | ) |

Add the channel context for the new connection.

Parameters:

  `[in,out]` | chan_idx | Pointer to the value that will contain the allocated channel index.

Returns:
  the status of the MM_CHAN_CTXT_ADD_REQ handling

Referenced by scanu_join_cfm_handler().

void sm_assoc_done | ( | uint16_t | aid | ) |

Association completed operations.

Parameters:

  `[in]` | aid | Association Identifier provided by AP on connection (0 if IBSS).

void sm_assoc_req_send | ( | void |  | ) |

Send MAC_FCTRL_ASSOCREQ or MAC_FCTRL_REASSOCREQ to the air.

Referenced by me_set_active_cfm_handler().

void sm_assoc_rsp_handler | ( | struct rxu_mgt_ind const * | param | ) |

Function called upon reception of a ASSOC_RSP frame from the AP.

Parameters:

  `[in]` | param | Pointer to the kernel message containing the ASSOC_RSP frame.

Referenced by rxu_mgt_ind_handler().

void sm_auth_handler | ( | struct rxu_mgt_ind const * | param | ) |

Function called upon reception of a AUTH frame from the AP.

Parameters:

  `[in]` | param | Pointer to the kernel message containing the AUTH frame.

Referenced by rxu_mgt_ind_handler().

void sm_auth_send | ( | uint16_t | auth_seq,
|  | uint32_t * | challenge |
| ) |  |  |

Send Authentication frame.

Parameters:

  `[in]` | auth_seq | Authentication sequence
  `[in]` | challenge | Pointer on authentication challenge. Only needed for third sequence of SHARED_KEY authentication. Should be NULL otherwise

Referenced by me_set_active_cfm_handler().

static void sm_bss_config_push | ( | void * | param | ) | `[static]`

Push a BSS configuration message to the list.

Parameters:

  `[in]` | param | Pointer to the message parameters

Definition at line 108 of file sm.c.

References sm_env_tag::bss_config, co_list_push_back(), ke_msg::hdr, ke_param2msg(), and sm_env.

Referenced by sm_delete_resources().

void sm_bss_config_send | ( | void |  | ) |

Send the next BSS parameter message present in the list.

Referenced by me_set_ps_disable_cfm_handler(), mm_bss_param_setting_handler(), mm_chan_ctxt_unlink_cfm_handler(), mm_set_vif_state_cfm_handler(), mm_sta_del_cfm_handler(), and sm_delete_resources().

void sm_connect_ind | ( | uint16_t | status | ) |

Function called at any time during the connection, used to indicate to the host the completion of the procedure (either successful or not).

Parameters:

  `[in]` | status | Status of the connection procedure (MAC_ST_SUCCESSFUL or any other 802.11 status code)

Referenced by me_set_active_cfm_handler(), mm_set_vif_state_cfm_handler(), mm_sta_add_cfm_handler(), scanu_join_cfm_handler(), scanu_start_cfm_handler(), and sm_rsp_timeout_ind_handler().

static void sm_deauth_cfm | ( | void * | env,
|  | uint32_t | status |
| ) |  |  | `[static]`

DEAUTH frame transmission confirmation handler Once the transmission is confirmed we can continue the disconnection process.

Parameters:

  `[in]` | env | Pointer to the VIF
  `[in]` | status | Status of the transmission

Definition at line 124 of file sm.c.

References sm_disconnect_process().

int sm_deauth_handler | ( | struct rxu_mgt_ind const * | param | ) |

Function called upon reception of a DEAUTH or DISASSOC frame from the AP.

Parameters:

  `[in]` | param | Pointer to the kernel message containing the DEAUTH/DISASSOC frame.

Returns:
  The message status to be returned to the kernel (KE_MSG_CONSUMED or KE_MSG_SAVED)

Referenced by rxu_mgt_ind_handler().

static void sm_delete_resources | ( | struct vif_info_tag * | vif | ) | `[static]`

Delete the different SW resources that were allocated for this connection.

Parameters:

  `[in]` | vif | Pointer to the VIF

Definition at line 136 of file sm.c.

References me_set_active_req::active, mm_set_vif_state_req::active, vif_info_tag::active, bam_delete_all_ba_agg(), vif_info_tag::chan_ctxt, vif_info_tag::index, mm_set_vif_state_req::inst_nbr, INVALID_STA_IDX, KE_MSG_ALLOC, ME_SET_ACTIVE_REQ, ME_SET_PS_DISABLE_REQ, MM_CHAN_CTXT_UNLINK_REQ, MM_SET_VIF_STATE_REQ, MM_STA_DEL_REQ, me_set_ps_disable_req::ps_disable, sm_bss_config_init(), sm_bss_config_push(), sm_bss_config_send(), vif_info_tag::sta, mm_sta_del_req::sta_idx, TASK_ME, TASK_MM, TASK_SM, vif_info_tag::u, me_set_active_req::vif_idx, me_set_ps_disable_req::vif_idx, and mm_chan_ctxt_unlink_req::vif_index.

void sm_disconnect | ( | uint8_t | vif_index,
|  | uint16_t | reason_code |
| ) |  |  |

Start the disconnection procedure upon the reception of a SM_DISCONNECT_REQ.

Parameters:

  `[in]` | vif_index | Index of the VIF that has to disconnect
  `[in]` | reason_code | 802.11 reason code that needs to be included in the DEAUTH frame.

Referenced by sm_disconnect_req_handler().

void sm_disconnect_process | ( | struct vif_info_tag * | vif,
|  | uint16_t | reason |
| ) |  |  |

Terminates the disconnection procedure after reception of a DEAUTH/DISASSOC or the transmission of a DEAUTH frame.

Parameters:

  `[in]` | vif | Pointer to the environment structure of the VIF that is disconnected
  `[in]` | reason | 802.11 reason code that will be forwarded to the host in the SM_DISCONNECT_IND

Referenced by mm_connection_loss_ind_handler(), sm_connect_req_handler(), and sm_deauth_cfm().

void sm_external_auth_end | ( | uint16_t | status | ) |

End External Authentication procedure.

Called when host send status for external authentication.

Parameters:

  `[in]` | status | Status (as in Status code of AUTH frame) of the external authentication procedure

Referenced by sm_external_auth_required_rsp_handler().

bool sm_external_auth_in_progress | ( | void |  | ) |

Check if external authentication is in progress.

Returns:
  true if external authentication is in progress and false otherwise

Referenced by rxu_mgt_route().

void sm_external_auth_start | ( | uint32_t | akm | ) |

Start External Authentication procedure.

Used when fw doesn't support an authentication method. In this case the authentication is offloaded to the host.

Parameters:

  `[in]` | akm | Authentication Key Management used for this connection

Referenced by me_set_active_cfm_handler().

static void sm_frame_tx_cfm_handler | ( | void * | env,
|  | uint32_t | status |
| ) |  |  | `[static]`

Frame transmission confirmation handler If the frame is not successfully transmitted it is pushed again until the timeout expires.

Parameters:

  `[in]` | env | Pointer to the frame descriptor
  `[in]` | status | Status of the transmission

Definition at line 58 of file sm.c.

References AC_VO, DESC_DONE_SW_TX_BIT, ke_state_get(), txl_frame_desc_tag::keep_desc, LIFETIME_EXPIRED_BIT, RETRY_LIMIT_REACHED_BIT, SM_ASSOCIATING, SM_AUTHENTICATING, sm_state, TASK_SM, and txl_frame_push().

void sm_get_bss_params | ( | struct mac_addr const ** | bssid,
|  | struct mac_chan_def const ** | chan |
| ) |  |  |

Search for the BSSID and Channel information in the scan results and/or the connection parameters.

Parameters:

  `[out]` | bssid | Pointer to the BSSID to join
  `[out]` | chan | Pointer to the channel on which the BSSID is

Referenced by me_set_active_cfm_handler(), scanu_join_cfm_handler(), scanu_start_cfm_handler(), and sm_connect_req_handler().

int sm_get_rsnie_pmkid_count | ( | uint32_t | ies,
|  | uint16_t | ies_len |
| ) |  |  |

Return PMKID count from RSN IE.

Find PMKID count field of RSN IE in a buffer of several IE.

Parameters:

  `[in]` | ies | HW Address of IEs buffer
  `[in]` | ies_len | Size, in bytes, of IEs buffer

Returns:
  PMKID count inside RSN IE. If RSN IE is not present or PMKID count is not present then 0 is returned

Referenced by sm_connect_req_handler().

void sm_join_bss | ( | struct mac_addr const * | bssid,
|  | struct mac_chan_def const * | chan,
|  | bool | passive |
| ) |  |  |

Try to join the BSS indicated by the parameters.

Parameters:

  `[in]` | bssid | Pointer to the BSSID to join
  `[in]` | chan | Pointer to the channel on which the BSSID is
  `[in]` | passive | Indicate if passive scan has to be started

Referenced by me_set_active_cfm_handler(), scanu_join_cfm_handler(), scanu_start_cfm_handler(), and sm_connect_req_handler().

void sm_sa_query_handler | ( | struct rxu_mgt_ind const * | param | ) |

Function called upon reception of a SA QUERY action frame.

Only SA QUERY Request received on STA interfaces are handled.

Parameters:

  `[in]` | param | Pointer to the kernel message containing SA_QUERY Action frame.

Referenced by rxu_mgt_ind_handler().

void sm_scan_bss | ( | struct mac_addr const * | bssid,
|  | struct mac_chan_def const * | chan |
| ) |  |  |

Launch the scan to find the target BSS.

Parameters:

  `[in]` | bssid | Pointer to the BSSID to join, if known. If not the WildCard BSSID will be used for the scan.
  `[in]` | chan | Pointer to the channel on which the BSSID is, if known. If not the scan is performed on all channels.

Referenced by sm_connect_req_handler().