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