1 /*
2  *  Copyright (c) 2020, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * @brief
32  *   This file defines the link metrics interface for OpenThread platform radio drivers.
33  *
34  *   APIs defined in this module could be used by a platform to implement Enhanced-ACK Based Probing feature
35  *   (Probing Subject side) in its radio driver.
36  */
37 
38 #ifndef OPENTHREAD_UTILS_LINK_METRICS_H
39 #define OPENTHREAD_UTILS_LINK_METRICS_H
40 
41 #include <openthread/link_metrics.h>
42 
43 #include "mac_frame.h"
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 /**
50  * Initializes the Link Metrics util module.
51  *
52  * @param[in]  aNoiseFloor    The noise floor used by Link Metrics. It should be set to the platform's
53  *                            noise floor (measured noise floor, receiver sensitivity or a constant).
54  */
55 void otLinkMetricsInit(int8_t aNoiseFloor);
56 
57 /**
58  * Sets/clears Enhanced-ACK Based Probing for a specific Initiator.
59  *
60  * Can start/stop Enhanced-ACK Based Probing for a neighbor that has the address @p aShortAddress and
61  * @p aExtAddress. Once the Probing is started, the device would record the Link Metrics data of link layer frames
62  * sent from that neighbor and include the data into header IE in Enhanced-ACK sent to that neighbor.
63  *
64  * @param[in]  aShortAddress    The short address of the Initiator.
65  * @param[in]  aExtAddress      A pointer to the extended address of the Initiator.
66  * @param[in]  aLinkMetrics     Flags specifying what metrics to query (Pdu Count would be omitted). When
67  *                              @p aLinkMetrics is equal to `0`, this method clears the Initiator.
68  *
69  * @retval  OT_ERROR_NONE            Successfully configured the Enhanced-ACK Based Probing.
70  * @retval  OT_ERROR_INVALID_ARGS    @p aExtAddress is `nullptr`.
71  * @retval  OT_ERROR_NOT_FOUND       The Initiator indicated by @p aShortAddress is not found when trying to clear.
72  * @retval  OT_ERROR_NO_BUFS         No more Initiator can be supported.
73  */
74 otError otLinkMetricsConfigureEnhAckProbing(otShortAddress      aShortAddress,
75                                             const otExtAddress *aExtAddress,
76                                             otLinkMetrics       aLinkMetrics);
77 
78 /**
79  * Generates the Link Metrics data (assessed for the acknowledged frame) bytes that would be included in
80  * Vendor-Specific IE.
81  *
82  * First checks what Link Metrics are specified by the Initiator indicated by @p aMacAddress. And then
83  * write the values to @p aData.
84  *
85  * @param[in]  aMacAddress    The Mac address of the Initiator.
86  * @param[in]  aLqi           LQI value of the acknowledged frame.
87  * @param[in]  aRssi          RSSI value of the acknowledged frame.
88  * @param[out] aData          A pointer to the buffer where the data would be written to. The caller should make
89  *                            sure that the size of the buffer is not less than the size of Link Metrics data
90  *                            configured before.
91  *
92  * @returns  The size of data read. Would be `0` if the Initiator is not found or @p aData is invalid.
93  */
94 uint8_t otLinkMetricsEnhAckGenData(const otMacAddress *aMacAddress, uint8_t aLqi, int8_t aRssi, uint8_t *aData);
95 
96 /**
97  * Returns the data length of Enhanced-ACK Based Probing for a specific Initiator.
98  *
99  * @param[in]  aMacAddress    The Mac address of the Initiator.
100  *
101  * @returns  The size of data. `0` if it's not configured for the Initiator.
102  */
103 uint8_t otLinkMetricsEnhAckGetDataLen(const otMacAddress *aMacAddress);
104 
105 /**
106  * This method resets Enhanced-ACK Based Probing data.
107  */
108 void otLinkMetricsResetEnhAckProbing(void);
109 
110 #ifdef __cplusplus
111 } // extern "C"
112 #endif
113 
114 #endif // OPENTHREAD_UTILS_LINK_METRICS_H
115