ws_llc.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef WS_LLC_H_
00019 #define WS_LLC_H_
00020 
00021 #include "6LoWPAN/ws/ws_neighbor_class.h"
00022 #include "Service_Libs/mac_neighbor_table/mac_neighbor_table.h"
00023 
00024 struct protocol_interface_info_entry;
00025 struct mcps_data_ind_s;
00026 struct mcps_data_ie_list;
00027 struct channel_list_s;
00028 struct ws_pan_information_s;
00029 struct mlme_security_s;
00030 struct ws_hopping_schedule_s;
00031 struct ws_neighbor_class_entry;
00032 struct mac_neighbor_table_entry;
00033 struct ws_neighbor_temp_class_s;
00034 
00035 
00036 /**
00037  * @brief wh_ie_sub_list_t ws asynch header IE elemnt request list
00038  */
00039 typedef struct wh_ie_sub_list_s {
00040     bool utt_ie: 1;  /**< Unicast Timing and Frame type information */
00041     bool bt_ie: 1;   /**< Broadcast timing information */
00042     bool fc_ie: 1;   /**< Flow Control for Extended Direct Frame Exchange */
00043     bool rsl_ie: 1;  /**< Received Signal Level information */
00044     bool vh_ie: 1;   /**< Vendor header information */
00045     bool ea_ie: 1;   /**< EAPOL autheticator EUI-64 header information */
00046 } wh_ie_sub_list_t;
00047 
00048 /**
00049  * @brief wp_nested_ie_sub_list_t ws asynch Nested Payload sub IE element request list
00050  */
00051 typedef struct wp_nested_ie_sub_list_s {
00052     bool us_ie: 1;          /**< Unicast Schedule information */
00053     bool bs_ie: 1;          /**< Broadcast Schedule information */
00054     bool vp_ie: 1;          /**< Vendor Payload information */
00055     bool pan_ie: 1;         /**< PAN Information */
00056     bool net_name_ie: 1;    /**< Network Name information */
00057     bool pan_version_ie: 1; /**< Pan configuration version */
00058     bool gtkhash_ie: 1;     /**< GTK Hash information */
00059 } wp_nested_ie_sub_list_t;
00060 
00061 /**
00062  * @brief asynch_request_t Asynch message request parameters
00063  */
00064 typedef struct asynch_request_s {
00065     unsigned  message_type: 3;                              /**< Asynch message type: WS_FT_PAN_ADVERT, WS_FT_PAN_ADVERT_SOL, WS_FT_PAN_CONF or WS_FT_PAN_CONF_SOL. */
00066     wh_ie_sub_list_t wh_requested_ie_list;                  /**< WH-IE header list to message. */
00067     wp_nested_ie_sub_list_t wp_requested_nested_ie_list;    /**< WP-IE Nested IE list to message. */
00068     struct mlme_security_s security;                               /**< Request MAC security paramaters */
00069     struct channel_list_s channel_list;                     /**< Channel List. */
00070 } asynch_request_t;
00071 
00072 
00073 /**
00074  * @brief LLC neighbour info request parameters
00075  */
00076 typedef struct llc_neighbour_req {
00077     struct mac_neighbor_table_entry *neighbor;                  /**< Generic Link Layer Neighbor information entry. */
00078     struct ws_neighbor_class_entry *ws_neighbor;                /**< Wi-sun Neighbor information entry. */
00079 } llc_neighbour_req_t;
00080 
00081 /**
00082  * Neighbor temporary structure for storage FHSS data before create a real Neighbour info
00083  */
00084 typedef struct ws_neighbor_temp_class_s {
00085     struct ws_neighbor_class_entry neigh_info_list ;  /*!< Allocated hopping info array*/
00086     uint8_t mac64[8];
00087     uint8_t mpduLinkQuality;
00088     int8_t signal_dbm;
00089     ns_list_link_t link;
00090 } ws_neighbor_temp_class_t;
00091 
00092 typedef NS_LIST_HEAD (ws_neighbor_temp_class_t, link) ws_neighbor_temp_list_t;
00093 
00094 /**
00095  * @brief ws_asynch_ind ws asynch data indication
00096  * @param interface Interface pointer
00097  * @param data MCPS-DATA.indication specific values
00098  * @param ie_ext Information element list
00099  */
00100 typedef void ws_asynch_ind(struct protocol_interface_info_entry *interface, const struct mcps_data_ind_s *data, const struct mcps_data_ie_list *ie_ext, uint8_t message_type);
00101 
00102 /**
00103  * @brief ws_asynch_confirm ws asynch data confirmation to asynch message request
00104  * @param api The API which handled the response
00105  * @param data MCPS-DATA.confirm specific values
00106  * @param user_id MPX user ID
00107  */
00108 typedef void ws_asynch_confirm(struct protocol_interface_info_entry *interface, uint8_t asynch_message);
00109 
00110 /**
00111  * @brief ws_asynch_confirm ws asynch data confirmation to asynch message request
00112  * @param interface The interface pointer
00113  * @param mac_64 Neighbor 64-bit address
00114  * @param neighbor_buffer Buffer where neighbor infor is buffered
00115  * @param request_new true if is possible to allocate new entry
00116  *
00117  * @return true when neighbor info is available
00118  * @return false when no neighbor info
00119  */
00120 typedef bool ws_neighbor_info_request(struct protocol_interface_info_entry *interface, const uint8_t *mac_64, llc_neighbour_req_t *neighbor_buffer, bool request_new);
00121 
00122 /**
00123  * @brief ws_llc_create ws LLC module create
00124  * @param interface Interface pointer
00125  * @param asynch_ind_cb Asynch indication
00126  * @param ie_ext Information element list
00127  *
00128  * Function allocate and init LLC class and init it 2 supported 2 API: ws asynch and MPX user are internally registered.
00129  */
00130 int8_t ws_llc_create(struct protocol_interface_info_entry *interface, ws_asynch_ind *asynch_ind_cb, ws_asynch_confirm *asynch_cnf_cb, ws_neighbor_info_request *ws_neighbor_info_request_cb);
00131 
00132 /**
00133  * @brief ws_llc_reset Reset ws LLC parametrs and clean messages
00134  * @param interface Interface pointer
00135  *
00136  */
00137 void ws_llc_reset(struct protocol_interface_info_entry *interface);
00138 
00139 /**
00140  * @brief ws_llc_delete Delete LLC interface. ONLY for Test purpose.
00141  * @param interface Interface pointer
00142  *
00143  */
00144 int8_t ws_llc_delete(struct protocol_interface_info_entry *interface);
00145 
00146 /**
00147  * @brief ws_llc_mpx_api_get Get MPX api for registration purpose.
00148  * @param interface Interface pointer
00149  *
00150  * @return NULL when MPX is not vailabale
00151  * @return Pointer to MPX API
00152  *
00153  */
00154 mpx_api_t *ws_llc_mpx_api_get(struct protocol_interface_info_entry *interface);
00155 
00156 /**
00157  * @brief ws_llc_asynch_request ws asynch message request to all giving channels
00158  * @param interface Interface pointer
00159  * @param request Asynch message parameters: type, IE and channel list
00160  *
00161  * @return 0 Asynch message pushed to MAC
00162  * @return -1 memory allocate problem
00163  * @return -2 Parameter problem
00164  *
00165  */
00166 int8_t ws_llc_asynch_request(struct protocol_interface_info_entry *interface, asynch_request_t *request);
00167 
00168 
00169 /**
00170  * @brief ws_llc_set_vendor_header_data Configure WS vendor Header data information (Data of WH_IE_VH_TYPE IE element)
00171  * @param interface Interface pointer
00172  * @param vendor_header pointer to vendor header this pointer must keep alive when it is configured to LLC
00173  * @param vendor_header_length configured vendor header length
00174  *
00175  */
00176 void ws_llc_set_vendor_header_data(struct protocol_interface_info_entry *interface, uint8_t *vendor_header, uint8_t vendor_header_length);
00177 
00178 /**
00179  * @brief ws_llc_set_vendor_payload_data Configure WS vendor payload data information (Data of WP_PAYLOAD_IE_VP_TYPE IE element)
00180  * @param interface Interface pointer
00181  * @param vendor_payload pointer to vendor payload this pointer must keep alive when it is configured to LLC
00182  * @param vendor_payload_length configured vendor payload length
00183  *
00184  */
00185 void ws_llc_set_vendor_payload_data(struct protocol_interface_info_entry *interface, uint8_t *vendor_payload, uint8_t vendor_payload_length);
00186 
00187 /**
00188  * @brief ws_llc_set_network_name Configure WS Network name (Data of WP_PAYLOAD_IE_NETNAME_TYPE IE element)
00189  * @param interface Interface pointer
00190  * @param name_length configured network name length
00191  * @param name pointer to network name this pointer must keep alive when it is configured to LLC
00192  *
00193  */
00194 void ws_llc_set_network_name(struct protocol_interface_info_entry *interface, uint8_t *name, uint8_t name_length);
00195 
00196 /**
00197  * @brief ws_llc_set_gtkhash Configure WS GTK hash information (Data of WP_PAYLOAD_IE_GTKHASH_TYPE IE element)
00198  * @param interface Interface pointer
00199  * @param gtkhash pointer to GTK hash which length is 32 bytes this pointer must keep alive when it is configured to LLC
00200  *
00201  */
00202 void  ws_llc_set_gtkhash(struct protocol_interface_info_entry *interface, uint8_t *gtkhash);
00203 
00204 /**
00205  * @brief ws_llc_set_pan_information_pointer Configure WS PAN information (Data of WP_PAYLOAD_IE_PAN_TYPE IE element)
00206  * @param interface Interface pointer
00207  * @param pan_information_pointer pointer to Pan information this pointer must keep alive when it is configured to LLC
00208  *
00209  */
00210 void ws_llc_set_pan_information_pointer(struct protocol_interface_info_entry *interface, struct ws_pan_information_s *pan_information_pointer);
00211 
00212 /**
00213  * @brief ws_llc_hopping_schedule_config Configure channel hopping
00214  * @param interface Interface pointer
00215  * @param hopping_schedule pointer to Channel hopping schedule
00216  *
00217  */
00218 void ws_llc_hopping_schedule_config(struct protocol_interface_info_entry *interface, struct ws_hopping_schedule_s *hopping_schedule);
00219 
00220 ws_neighbor_temp_class_t *ws_llc_get_multicast_temp_entry(struct protocol_interface_info_entry *interface, const uint8_t *mac64);
00221 
00222 void ws_llc_free_multicast_temp_entry(struct protocol_interface_info_entry *interface, ws_neighbor_temp_class_t *neighbor);
00223 
00224 #endif /* WS_LLC_H_ */