mac_filter_api.h

00001 /*
00002  * Copyright (c) 2014-2017, 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 /**
00019  * \file mac_filter_api.h
00020  * \brief API to allow filtering of packets based upon link quality and received power levels.
00021  *
00022  * \section app-mac-fil Applying a  MAC filter
00023  *  - mac_filter_start(), Starts a MAC level filter.
00024  *  - mac_filter_add_short(), Adds a filter using short MAC address.
00025  *  - mac_filter_add_long(), Adds a filter using long MAC address.
00026  *
00027  * \section rem-mac-fil Removing a  MAC filter
00028  *  - mac_filter_stop(), Stops MAC level filter and clears all defaults.
00029  *  - mac_filter_clear(), Stops MAC level filter and leaves the default link configuration.
00030  *  - mac_filter_delete_short(), Deletes filter for a device specified by short MAC address.
00031  *  - mac_filter_delete_long(), Deletes filter for a device specified by long MAC address.
00032  *
00033  *  \section reg-mac-fil Setting up address mapping for filter
00034  *  -  mac_filter_set_address_mapping(), Registers address mapping functions.
00035  *
00036  * \section macr-help Helper macros
00037  * - mac_filter_start(interface_id, MAC_FILTER_BLOCKED), Black list filter.
00038  * - mac_filter_start(interface_id, MAC_FILTER_ALLOWED), White list filter not modifying the qualities.
00039  * - mac_filter_start(interface_id, MAC_FILTER_FIXED(0x01, -80)), Fixed value for default link quality (poor quality).
00040  * - mac_filter_start(interface_id, MAC_FILTER_FIXED(0xff, -20)), Fixed value for default link quality (good quality).
00041  * - mac_filter_add_short(interface_id, 0x0001, MAC_FILTER_BLOCKED)
00042  * - mac_filter_add_short(interface_id, 0x0001, MAC_FILTER_ALLOWED)
00043  * - mac_filter_add_short(interface_id, 0x0001, MAC_FILTER_FIXED(0xff,-30))
00044  * - mac_filter_add_long(interface_id, mac64, MAC_FILTER_BLOCKED)
00045  * - mac_filter_add_long(interface_id, mac64, MAC_FILTER_ALLOWED)
00046  * - mac_filter_add_long(interface_id, mac64, MAC_FILTER_FIXED(0x7f, -60))
00047  */
00048 
00049 
00050 #ifndef MAC_FILTER_API_H_
00051 #define MAC_FILTER_API_H_
00052 
00053 #include "ns_types.h"
00054 
00055 #ifdef __cplusplus
00056 extern "C" {
00057 #endif
00058 
00059 /**
00060  * \brief Start MAC level filter.
00061  * This function can be called again if default values are modified.
00062  *
00063  *
00064  * \param interface_id Network interface ID.
00065  * \param lqi_m LQI multiplier (8.8 Fixed point multiplier).
00066  * \param lqi_add Value added to LQI.
00067  * \param dbm_m DBM multiplier (8.8 Fixed point multiplier).
00068  * \param dbm_add Value added to DBM.
00069  *
00070  * \return 0, OK.
00071  * \return <0 Not OK.
00072  */
00073 
00074 int_fast8_t mac_filter_start(int8_t interface_id, int16_t lqi_m, int16_t lqi_add, int16_t dbm_m, int16_t dbm_add);
00075 
00076 /**
00077  * \brief Stop MAC level filter.
00078  *
00079  * Stops the filtering module and clears the default settings and all the filterings made.
00080  *
00081  * \param interface_id Network interface ID.
00082  *
00083  * \return 0, OK.
00084  * \return <0 Not OK.
00085  */
00086 
00087 void mac_filter_stop(int8_t interface_id);
00088 
00089 /** White list filter not modifying the qualities.*/
00090 #define MAC_FILTER_ALLOWED 0x100, 0, 0x100, 0
00091 /** Black list filter.*/
00092 #define MAC_FILTER_BLOCKED 0, 0, 0, 0
00093 /** Fixed value for default link quality.*/
00094 #define MAC_FILTER_FIXED(lqi,dbm) 0, lqi, 0, dbm
00095 
00096 /**
00097  * \brief Delete all filters.
00098  *
00099  * Leaves the default link configuration.
00100  *
00101  * \param interface_id Network interface ID.
00102  *
00103  * \return 0, OK.
00104  * \return <0 Not OK.
00105  */
00106 int_fast8_t mac_filter_clear(int8_t interface_id);
00107 
00108 /**
00109  * \brief Map the extended address to the short address.
00110  *
00111  * \param interface_id Network Interface.
00112  * \param mac64 Extended address.
00113  * \param mac16 Return the short address.
00114  *
00115  * \return 0, address resolved.
00116  * \return <0 No mapping found.
00117  */
00118 typedef int_fast8_t (mac_filter_map_extented_to_short_cb)(int8_t interface_id, uint8_t mac64[8], uint16_t *mac16);
00119 
00120 /**
00121  * \brief Map short address to extended address.
00122  *
00123  * \param interface_id Network interface ID.
00124  * \param mac64[out] Return buffer for the extended address.
00125  * \param mac16 Short address.
00126  *
00127  * return 0, address resolved.
00128  * return <0 no mapping found.
00129  */
00130 typedef int_fast8_t (mac_filter_map_short_to_extended_cb)(int8_t interface_id, uint8_t mac64[8], uint16_t mac16);
00131 
00132 /**
00133  * \brief Register address mapping functions.
00134  *
00135  * This function should be added for layer in stack that keeps up the list of address mapping functions.
00136  * If filters are enabled these functions are called if no match from filters was found.
00137  *
00138  * When this service is no longer provided call this function with NULL pointers.
00139  *
00140  * \param interface_id Network interface ID.
00141  * \param long_cb Address mapping to resolve long address from short address.
00142  * \param short_cb Address mapping to resolve short address from long address.
00143  *
00144  * \return 0, OK.
00145  * \return <0 Not OK.
00146  */
00147 int_fast8_t mac_filter_set_address_mapping(int8_t interface_id, mac_filter_map_short_to_extended_cb *long_cb, mac_filter_map_extented_to_short_cb *short_cb);
00148 
00149 /**
00150  * \brief Delete filter for device
00151  *
00152  * \param interface_id Network interface ID.
00153  * \param mac16 Short address.
00154  *
00155  * \return 0, OK.
00156  * \return <0 Not OK.
00157  */
00158 int_fast8_t mac_filter_delete_short(int8_t interface_id, uint16_t mac16);
00159 
00160 /**
00161  * \brief Delete filter for device.
00162  *
00163  * \param interface_id Network interface ID.
00164  * \param mac64 Long address.
00165  *
00166  * \return 0, OK
00167  * \return <0 Not OK
00168  */
00169 int_fast8_t mac_filter_delete_long(int8_t interface_id, uint8_t mac64[8]);
00170 
00171 /**
00172  * \brief Add MAC short address filter.
00173  *
00174  * \param interface_id Network interface ID.
00175  * \param mac16 Short address.
00176  * \param lqi_m LQI multiplier (8.8 Fixed point multiplier).
00177  * \param lqi_add Value added to LQI.
00178  * \param dbm_m DBM multiplier (8.8 Fixed point multiplier).
00179  * \param dbm_add Value added to DBM.
00180  *
00181  * \return 0, OK.
00182  * \return <0 Not OK.
00183  */
00184 int_fast8_t mac_filter_add_short(int8_t interface_id, uint16_t mac16, int16_t lqi_m, int16_t lqi_add, int16_t dbm_m, int16_t dbm_add);
00185 
00186 /**
00187  * \brief Add MAC long address filter.
00188  *
00189  * \param interface_id Network interface ID.
00190  * \param mac64 Long address.
00191  * \param lqi_m LQI multiplier (8.8 Fixed point multiplier).
00192  * \param lqi_add Value added to LQI.
00193  * \param dbm_m DBM multiplier (8.8 Fixed point multiplier).
00194  * \param dbm_add Value added to DBM.
00195  *
00196  * \return 0, OK.
00197  * \return <0 Not OK.
00198  */
00199 int_fast8_t mac_filter_add_long(int8_t interface_id, uint8_t mac64[8], int16_t lqi_m, int16_t lqi_add, int16_t dbm_m, int16_t dbm_add);
00200 
00201 #ifdef __cplusplus
00202 }
00203 #endif
00204 
00205 #endif /* MAC_FILTER_API_H_ */