mac_filter_api.h

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