Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /** @file
8 : *
9 : * @brief Utility functions to be used by the Wi-Fi subsystem.
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_NET_WIFI_UTILS_H_
13 : #define ZEPHYR_INCLUDE_NET_WIFI_UTILS_H_
14 :
15 : #ifdef __cplusplus
16 : extern "C" {
17 : #endif
18 :
19 : /**
20 : * @addtogroup wifi_mgmt
21 : * @{
22 : */
23 :
24 : /**
25 : * @name Wi-Fi utility functions.
26 : *
27 : * Utility functions for the Wi-Fi subsystem.
28 : * @{
29 : */
30 :
31 : /** Maximum length of the band specification string */
32 1 : #define WIFI_UTILS_MAX_BAND_STR_LEN 3
33 :
34 : /** Maximum length of the channel specification string */
35 1 : #define WIFI_UTILS_MAX_CHAN_STR_LEN 4
36 :
37 : /**
38 : * @brief Convert a band specification string to a bitmap representing the bands.
39 : *
40 : * @details The function will parse a string which specifies Wi-Fi frequency band
41 : * values as a comma separated string and convert it to a bitmap. The string can
42 : * use the following characters to represent the bands:
43 : *
44 : * - 2: 2.4 GHz
45 : * - 5: 5 GHz
46 : * - 6: 6 GHz
47 : *
48 : * For the bitmap generated refer to ::wifi_frequency_bands
49 : * for bit position of each band.
50 : *
51 : * E.g. a string "2,5,6" will be converted to a bitmap value of 0x7
52 : *
53 : * @param scan_bands_str String which spe.
54 : * @param band_map Pointer to the bitmap variable to be updated.
55 : *
56 : * @retval 0 on success.
57 : * @retval -errno value in case of failure.
58 : */
59 1 : int wifi_utils_parse_scan_bands(char *scan_bands_str, uint8_t *band_map);
60 :
61 :
62 : /**
63 : * @brief Append a string containing an SSID to an array of SSID strings.
64 : *
65 : * @param scan_ssids_str string to be appended in the list of scanned SSIDs.
66 : * @param ssids Pointer to an array where the SSIDs pointers are to be stored.
67 : * @param num_ssids Maximum number of SSIDs that can be stored.
68 : *
69 : * @retval 0 on success.
70 : * @retval -errno value in case of failure.
71 : */
72 1 : int wifi_utils_parse_scan_ssids(char *scan_ssids_str,
73 : const char *ssids[],
74 : uint8_t num_ssids);
75 :
76 :
77 : /**
78 : * @brief Convert a string containing a specification of scan channels to an array.
79 : *
80 : * @details The function will parse a string which specifies channels to be scanned
81 : * as a string and convert it to an array.
82 : *
83 : * The channel string has to be formatted using the colon (:), comma(,), hyphen (-) and
84 : * underscore (_) delimiters as follows:
85 : * - A colon identifies the value preceding it as a band. A band value
86 : * (2: 2.4 GHz, 5: 5 GHz 6: 6 GHz) has to precede the channels in that band (e.g. 2: etc)
87 : * - Hyphens (-) are used to identify channel ranges (e.g. 2-7, 32-48 etc)
88 : * - Commas are used to separate channel values within a band. Channels can be specified
89 : * as individual values (2,6,48 etc) or channel ranges using hyphens (1-14, 32-48 etc)
90 : * - Underscores (_) are used to specify multiple band-channel sets (e.g. 2:1,2_5:36,40 etc)
91 : * - No spaces should be used anywhere, i.e. before/after commas,
92 : * before/after hyphens etc.
93 : *
94 : * An example channel specification specifying channels in the 2.4 GHz and 5 GHz bands is
95 : * as below:
96 : * 2:1,5,7,9-11_5:36-48,100,163-167
97 : *
98 : * @param scan_chan_str List of channels expressed in the format described above.
99 : * @param chan Pointer to an array where the parsed channels are to be stored.
100 : * @param max_channels Maximum number of channels to store
101 : *
102 : * @retval 0 on success.
103 : * @retval -errno value in case of failure.
104 : */
105 1 : int wifi_utils_parse_scan_chan(char *scan_chan_str,
106 : struct wifi_band_channel *chan,
107 : uint8_t max_channels);
108 :
109 :
110 : /**
111 : * @brief Validate a channel against a band.
112 : *
113 : * @param band Band to validate the channel against.
114 : * @param chan Channel to validate.
115 : *
116 : * @retval true if the channel is valid for the band.
117 : * @retval false if the channel is not valid for the band.
118 : */
119 1 : bool wifi_utils_validate_chan(uint8_t band,
120 : uint16_t chan);
121 :
122 : /**
123 : * @brief Validate a channel against the 2.4 GHz band.
124 : *
125 : * @param chan Channel to validate.
126 : *
127 : * @retval true if the channel is valid for the band.
128 : * @retval false if the channel is not valid for the band.
129 : */
130 1 : bool wifi_utils_validate_chan_2g(uint16_t chan);
131 :
132 : /**
133 : * @brief Validate a channel against the 5 GHz band.
134 : *
135 : * @param chan Channel to validate.
136 : *
137 : * @retval true if the channel is valid for the band.
138 : * @retval false if the channel is not valid for the band.
139 : */
140 1 : bool wifi_utils_validate_chan_5g(uint16_t chan);
141 :
142 : /**
143 : * @brief Validate a channel against the 6 GHz band.
144 : *
145 : * @param chan Channel to validate.
146 : *
147 : * @retval true if the channel is valid for the band.
148 : * @retval false if the channel is not valid for the band.
149 : */
150 1 : bool wifi_utils_validate_chan_6g(uint16_t chan);
151 :
152 : /**
153 : * @}
154 : */
155 :
156 : /**
157 : * @}
158 : */
159 :
160 : #ifdef __cplusplus
161 : }
162 : #endif
163 : #endif /* ZEPHYR_INCLUDE_NET_WIFI_UTILS_H_ */
|
