# SCANU
[UMAC]

Declaration of all structures and functions used by the SCAN module. More...

Collaboration diagram for SCANU:

## Data Structures
struct | scanu_mbssid_profile_tag
| nonTransmitted BSSID information structure More...
struct | scanu_mbssids_tag
| nonTransmitted BSSID database More...
struct | scanu_env_tag
| The SCAN environment. More...
struct | scanu_add_ie_tag
| Definition of an additional IE buffer. More...
## Modules
| TASK_SCANU

| Declaration of all structures and functions used by the SCAN module.
## Defines
#define | SCANU_MAX_IE_LEN 200
| Maximum length of the additional ProbeReq IEs.
#define | SCANU_MAX_RESULTS 32
| Maximum number of scan results that can be stored.
#define | SCANU_MAX_NONTXED_BSSID_PER_BEACON 16
| Maximum number of nonTxed BSSID information we can store for one received beacon.
#define | SCAN_ENABLE_TIME 2000000
| Scan time to enable or disable the scan (2sec).
## Functions
static uint32_t | scanu_build_ie (void)
| Build the probe request IE.
static void | scanu_dma_cb (void *env, int dma_type)
| DMA callback, called upon download of the scan information elements to be added to the ProbeReq.
static void | scanu_ie_download (void)
| Prepare the download of the additional IEs.
static void | scanu_get_security_info (uint32_t ies, uint16_t ies_len, uint16_t capa, struct mac_scan_result *res)
| Parse security info from provided Elements.
static bool | scanu_new_bssid_set (struct scanu_mbssid_profile_tag *mbssid, uint8_t max_bss_ind, struct mac_scan_result const *res)
| Allocate a scan database element and copy the information about the nonTransmitted BSSID.
static void | scanu_store_multi_bssid_info (struct mac_scan_result const *res)
| Store the found nonTransmitted BSSIDs into the scan data base.
static void | scanu_get_multi_bssid_info (uint32_t ies, uint16_t ies_len)
| Parse potential multiple BSSID elements within the Beacon/ProbeRsp.
static bool | scanu_is_scanned_ssid (struct mac_ssid *ssid)
| Check if the SSID passed as parameter (retrieved from the beacon or probe response) matches one of the SSIDs we are scanning for.
static bool | scanu_check_ssid (struct mac_scan_result *res)
| Go through the SSIDs found in the Beacon/ProbeRsp and check if one is matching the SSIDs we are looking for.
static int | scanu_join_frame_handler (struct rxu_mgt_ind const *frame)
| Handle the reception of a beacon or probe response frame when such a frame is received during the joining process.
static int | scanu_scan_frame_handler (struct rxu_mgt_ind const *frame)
| Handle the reception of a beacon or probe response frame when such a frame is received during the scanning process.
void | scanu_confirm (uint8_t status)
| Send the appropriate confirmation to the source task.
void | scanu_init (void)
| Initialize the SCAN environment and task.
int | scanu_frame_handler (struct rxu_mgt_ind const *frame)
| Handle the reception of a beacon or probe response frame.
struct mac_scan_result * | scanu_find_result (struct mac_addr const *bssid_ptr, bool allocate)
| Look for a given BSS in the scan results and returns its parameters.
struct mac_scan_result * | scanu_search_by_bssid (struct mac_addr const *bssid)
| Look for a given BSS from its BSSID.
struct mac_scan_result * | scanu_search_by_ssid (struct mac_ssid const *ssid)
| Look for a given BSS from its SSID.
void | scanu_start (void)
| Start scanning process.
void | scanu_scan_next (void)
| Send a scan request to LMAC for the next band to scan.
## Variables
struct scanu_env_tag | scanu_env
| SCAN module environment definition.
struct scanu_env_tag | scanu_env
| SCAN module environment declaration.
struct scanu_add_ie_tag | scanu_add_ie
| Variable used to store the addition information elements downloaded.
struct scanu_add_ie_tag | scanu_add_ie
| Variable used to store the addition information elements downloaded.

## Detailed Description

Declaration of all structures and functions used by the SCAN module.

## Function Documentation

static uint32_t scanu_build_ie | ( | void |  | ) | `[static]`

Build the probe request IE.

The IE buffer will then be used by the LMAC to build the ProbeReq sent.

Returns:
  The complete length of the information elements

Definition at line 68 of file scanu.c.

References scanu_start_req::add_ie_len, ASSERT_ERR, scanu_env_tag::band, scan_probe_req_ie_tag::buf, scanu_add_ie_tag::buf, co_copy8p(), co_pack8p(), co_read8p(), co_write8p(), CPU2HW, LOCAL_CAPA, MAC_ELTID_DS, MAC_ELTID_EXT_RATES, MAC_ELTID_RATES, MAC_ELTID_REQUEST, MAC_ELTID_SUPP_OPER_CLASS, mac_id2rate, MAC_RATES_ELMT_MAX_LEN, MAC_RATESET_LEN, me_add_ie_ht_capa(), scanu_start_req::no_cck, scanu_env_tag::param, PHY_BAND_2G4, PHY_BAND_5G, SCAN_MAX_IE_LEN, scan_probe_req_ie, scanu_add_ie, scanu_env, and SCANU_MAX_IE_LEN.

static bool scanu_check_ssid | ( | struct mac_scan_result * | res | ) | `[static]`

Go through the SSIDs found in the Beacon/ProbeRsp and check if one is matching the SSIDs we are looking for.

The function first checks the "main" SSID (i.e. the one of the reference BSSID), and then goes through the nonTransmitted BSSID elements if any.

Parameters:

  `[in]` | res | Pointer to the scan result element

Returns:
  true if we have a match on one of the SSIDs, false otherwise

Definition at line 641 of file scanu.c.

References mac_ssid::array, scanu_mbssids_tag::bssids, co_unpack8p(), mac_ssid::length, mac_ie_len(), MAC_INFOELT_INFO_OFT, MAC_SSID_SSID_OFT, scanu_mbssids_tag::mbssid_cnt, scanu_env_tag::mbssids, scanu_env, scanu_is_scanned_ssid(), mac_scan_result::ssid, and scanu_mbssid_profile_tag::ssid_ie_addr.

Referenced by scanu_scan_frame_handler().

void scanu_confirm | ( | uint8_t | status | ) |

Send the appropriate confirmation to the source task.

Parameters:

  `[in]` | status | Status to be sent to the source task

Referenced by scan_start_cfm_handler().

static void scanu_dma_cb | ( | void * | env,
|  | int | dma_type |
| ) |  |  | `[static]`

DMA callback, called upon download of the scan information elements to be added to the ProbeReq.

This function proceeds to the next step of the scanning procedure.

Parameters:

  `[in]` | env | Not used
  `[in]` | dma_type | Not used

Definition at line 184 of file scanu.c.

References scanu_scan_next().

struct mac_scan_result * scanu_find_result | ( | struct mac_addr const * | bssid_ptr,
|  | bool | allocate |
| ) |  |  | `[read]`

Look for a given BSS in the scan results and returns its parameters.

Parameters:

  `[in]` | bssid_ptr | Pointer to the BSSID looked for.
  `[in]` | allocate | Set to true only a result location is required for allocation.

Returns:
  If the allocation parameter was set, return the pointer to this BSS parameters if the BSS exists or the pointer to the first free BSS entry. In this case, if return NULL, then no space was found. If the allocation parameter was not set, return NULL if the BSS was not found.

Referenced by scanu_join_frame_handler(), scanu_join_req_handler(), scanu_new_bssid_set(), and scanu_scan_frame_handler().

int scanu_frame_handler | ( | struct rxu_mgt_ind const * | frame | ) |

Handle the reception of a beacon or probe response frame.

It extracts all required information from them and save them in scan result array.

Parameters:

  `[in]` | frame | Pointer to the received beacon/probe-response message.

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

Referenced by rxu_mgt_ind_handler().

static void scanu_get_multi_bssid_info | ( | uint32_t | ies,
|  | uint16_t | ies_len |
| ) |  |  | `[static]`

Parse potential multiple BSSID elements within the Beacon/ProbeRsp.

This function will store in the scanu_env the information about the nonTransmitted BSSIDs (BSSID index, SSID element address, etc.) for the received beacon/proberesp. The function is doing a quite complex parsing of the frame. The reason for that is the fact the nonTransmitted BSSID profiles can be split across several Multiple BSSID elements. Moreover the profiles are not included directly in the Multiple BSSID elements, but in Nontransmitted BSSID Profile sub-elements.

Parameters:

  `[in]` | ies | Pointer to elements
  `[in]` | ies_len | Size, in bytes, of the elements

Definition at line 506 of file scanu.c.

References scanu_mbssid_profile_tag::bssid_index, scanu_mbssids_tag::bssids, scanu_mbssid_profile_tag::capa, co_read16p(), co_read8p(), mac_ie_len(), mac_ie_multi_bssid_find(), mac_ie_multi_bssid_index_find(), mac_ie_non_txed_bssid_capa_find(), mac_ie_ssid_find(), mac_ie_sub_non_txed_bssid_find(), MAC_MULTI_BSSID_INDEX_OFT, MAC_MULTI_BSSID_MAX_INDICATOR_OFT, MAC_MULTI_BSSID_SUB_IES_OFT, MAC_NON_TXED_BSSID_CAPA_LEN, MAC_NON_TXED_BSSID_CAPA_OFT, scanu_mbssids_tag::max_bssid_ind, scanu_mbssids_tag::mbssid_cnt, scanu_env_tag::mbssids, scanu_env, SCANU_MAX_NONTXED_BSSID_PER_BEACON, and scanu_mbssid_profile_tag::ssid_ie_addr.

Referenced by scanu_scan_frame_handler().

static void scanu_get_security_info | ( | uint32_t | ies,
|  | uint16_t | ies_len,
|  | uint16_t | capa,
|  | struct mac_scan_result * | res |
| ) |  |  | `[static]`

Parse security info from provided Elements.

Parameters:

  `[in]` | ies | Pointer to elements
  `[in]` | ies_len | Size, in bytes, of the elements
  `[out]` | res | Scan result to update with security info

Definition at line 241 of file scanu.c.

References mac_scan_result::akm, CO_BIT, co_read16p(), co_wtohs(), mac_scan_result::group_cipher, MAC_AKM_NONE, MAC_AKM_PRE_RSN, MAC_CAPA_PRIVA, MAC_CIPHER_BIP_CMAC_128, MAC_CIPHER_WEP40, mac_ie_rsn_find(), mac_ie_wapi_find(), mac_ie_wpa_find(), MAC_INFOELT_INFO_OFT, MAC_RSNIE_GROUP_CIPHER_OFT, MAC_RSNIE_RSN_PMKID_SIZE, MAC_WAPI_AKM_SUITE_CNT_OFT, MAC_WPA_GROUP_CIPHER_OFT, and mac_scan_result::pairwise_cipher.

Referenced by scanu_scan_frame_handler().

static void scanu_ie_download | ( | void |  | ) | `[static]`

Prepare the download of the additional IEs.

If no additional IEs are present, or too long, then this function proceeds directly to the scan.

Definition at line 198 of file scanu.c.

References scanu_start_req::add_ie_len, scanu_start_req::add_ies, scanu_add_ie_tag::buf, scanu_env_tag::dma_desc, scanu_add_ie_tag::dma_desc, DMA_DL, hal_dma_push(), dma_desc::length, scanu_env_tag::param, scanu_add_ie, scanu_env, SCANU_MAX_IE_LEN, scanu_scan_next(), and dma_desc::src.

static bool scanu_is_scanned_ssid | ( | struct mac_ssid * | ssid | ) | `[static]`

Check if the SSID passed as parameter (retrieved from the beacon or probe response) matches one of the SSIDs we are scanning for.

Parameters:

  `[in]` | ssid | Pointer to the SSID present in the beacon/probe response

Returns:
  true if SSID matches one we searched for, false otherwise

Definition at line 597 of file scanu.c.

References mac_ssid::array, mac_ssid::length, MAC_SSID_CMP, scanu_env_tag::p2p_scan, P2P_SSID_WILDCARD, P2P_SSID_WILDCARD_LEN, scanu_env_tag::param, scanu_env, scanu_start_req::ssid, and scanu_start_req::ssid_cnt.

Referenced by scanu_check_ssid().

static int scanu_join_frame_handler | ( | struct rxu_mgt_ind const * | frame | ) | `[static]`

Handle the reception of a beacon or probe response frame when such a frame is received during the joining process.

The function copies the information present in the scan database element into the BSS information structure, and then extracts all the remaining information from the frame.

Parameters:

  `[in]` | frame | Pointer to the received beacon/probe-response message.

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

Definition at line 684 of file scanu.c.

References mac_hdr::addr3, mac_chan_def::band, bcn_frame::bcnint, BSS_CAPA, BSS_CAPA_RESET, BSS_CAPA_SET, vif_info_tag::bss_info, mac_scan_result::bssid, scanu_env_tag::bssid, mac_scan_result::bsstype, mac_scan_result::chan, co_clz(), CPU2HW, mac_chan_def::flags, mac_chan_def::freq, bcn_frame::h, HW_RATE_2MBPS, scanu_env_tag::join_status, KE_MSG_CONSUMED, rxu_mgt_ind::length, LOCAL_CAPA, MAC_ADDR_CMP, MAC_BEACON_VARIABLE_PART_OFT, mac_ie_ht_oper_find(), mac_ie_vht_oper_find(), mac_scan_result::max_bssid_indicator, me_bw_check(), me_extract_country_reg(), me_extract_edca_params(), me_extract_ht_capa(), me_extract_mobility_domain(), me_extract_power_constraint(), me_extract_rate_set(), me_extract_vht_capa(), me_legacy_rate_bitfield_build(), mac_scan_result::multi_bssid_index, scanu_env_tag::param, rxu_mgt_ind::payload, PHY_BAND_2G4, scanu_env_tag::ref_bssid, scanu_env, scanu_find_result(), mac_scan_result::ssid, tpc_update_vif_tx_power(), mac_chan_def::tx_power, bcn_frame::variable, scanu_start_req::vif_idx, and vif_info_tab.

static bool scanu_new_bssid_set | ( | struct scanu_mbssid_profile_tag * | mbssid,
|  | uint8_t | max_bss_ind,
|  | struct mac_scan_result const * | res |
| ) |  |  | `[static]`

Allocate a scan database element and copy the information about the nonTransmitted BSSID.

The function first generates the BSSID value based on the reference BSSID and the nonTransmitted BSSID index.

Parameters:

  `[in]` | mbssid | Pointer to the found nonTransmitted BSSID profile information
  `[in]` | max_bss_ind | Maximum BSSID indicator
  `[out]` | res | Scan result element linked to the reference BSSID

Returns:
  true if the new nonTransmitted BSSID was correctly configured, false otherwise

Definition at line 437 of file scanu.c.

References mac_ssid::array, mac_scan_result::bssid, scanu_mbssid_profile_tag::bssid_index, co_unpack8p(), mac_ssid::length, mac_ie_len(), MAC_INFOELT_INFO_OFT, mac_nontxed_bssid_get(), MAC_SSID_SSID_OFT, mac_scan_result::max_bssid_indicator, mac_scan_result::multi_bssid_index, scanu_env_tag::result_cnt, scanu_env, scanu_find_result(), mac_scan_result::ssid, scanu_mbssid_profile_tag::ssid_ie_addr, and mac_scan_result::valid_flag.

Referenced by scanu_store_multi_bssid_info().

static int scanu_scan_frame_handler | ( | struct rxu_mgt_ind const * | frame | ) | `[static]`

Handle the reception of a beacon or probe response frame when such a frame is received during the scanning process.

The function allocates a free element from the scan database and then extracts some part of the information present in the frame (BSSID, SSID, RSSI, etc.).

Parameters:

  `[in]` | frame | Pointer to the received beacon/probe-response message.

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

Definition at line 826 of file scanu.c.

References mac_hdr::addr3, mac_ssid::array, rxu_mgt_ind::band, mac_scan_result::bssid, scanu_env_tag::bssid, mac_scan_result::bsstype, bcn_frame::capa, rxu_mgt_ind::center_freq, mac_scan_result::chan, co_read8p(), co_unpack8p(), CPU2HW, bcn_frame::h, KE_MSG_CONSUMED, ke_msg_forward_and_change_id(), KE_MSG_NO_FREE, mac_ssid::length, rxu_mgt_ind::length, MAC_ADDR_CMP, MAC_ADDR_CPY, MAC_ADDR_GROUP, MAC_BEACON_VARIABLE_PART_OFT, MAC_CAPA_ESS, MAC_DS_CHANNEL_OFT, mac_ie_ds_find(), mac_ie_ssid_find(), MAC_SSID_SSID_OFT, me_freq_to_chan_ptr(), rxu_mgt_ind::payload, phy_channel_to_freq(), scanu_env_tag::result_cnt, mac_scan_result::rssi, rxu_mgt_ind::rssi, scanu_check_ssid(), scanu_env, scanu_find_result(), scanu_get_multi_bssid_info(), scanu_get_security_info(), SCANU_RESULT_IND, scanu_store_multi_bssid_info(), mac_scan_result::ssid, TASK_SCANU, mac_scan_result::valid_flag, and bcn_frame::variable.

void scanu_scan_next | ( | void |  | ) |

Send a scan request to LMAC for the next band to scan.

Referenced by scan_done_ind_handler(), scanu_dma_cb(), and scanu_ie_download().

struct mac_scan_result * scanu_search_by_bssid | ( | struct mac_addr const * | bssid | ) | `[read]`

Look for a given BSS from its BSSID.

Parameters:

  `[in]` | bssid | Pointer to the BSSID looked for.

Returns:
  If found, return the pointer to the BSS parameters, and NULL otherwise

struct mac_scan_result * scanu_search_by_ssid | ( | struct mac_ssid const * | ssid | ) | `[read]`

Look for a given BSS from its SSID.

If several entries in the database have the same SSID, then the function returns the one having the highest RSSI.

Parameters:

  `[in]` | ssid | Pointer to the SSID looked for.

Returns:
  If found, return the pointer to the BSS parameters, and NULL otherwise

static void scanu_store_multi_bssid_info | ( | struct mac_scan_result const * | res | ) | `[static]`

Store the found nonTransmitted BSSIDs into the scan data base.

Parameters:

  `[in]` | res | Pointer to the reference BSSID scan result element

Definition at line 480 of file scanu.c.

References scanu_mbssids_tag::bssids, scanu_mbssids_tag::max_bssid_ind, scanu_mbssids_tag::mbssid_cnt, scanu_env_tag::mbssids, scanu_env, and scanu_new_bssid_set().

Referenced by scanu_scan_frame_handler().

## Variable Documentation

struct scanu_env_tag scanu_env

SCAN module environment definition.

SCAN module environment declaration.

Definition at line 53 of file scanu.c.

Referenced by rxu_mgt_route(), scan_done_ind_handler(), scanu_build_ie(), scanu_check_ssid(), scanu_get_multi_bssid_info(), scanu_get_scan_result_req_handler(), scanu_ie_download(), scanu_is_scanned_ssid(), scanu_join_cfm_handler(), scanu_join_frame_handler(), scanu_join_req_handler(), scanu_new_bssid_set(), scanu_scan_frame_handler(), scanu_start_req_handler(), and scanu_store_multi_bssid_info().