1 /*
2  *  Copyright (c) 2017, 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  *   This file includes definitions for source address match controller.
32  */
33 
34 #ifndef SOURCE_MATCH_CONTROLLER_HPP_
35 #define SOURCE_MATCH_CONTROLLER_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #if OPENTHREAD_FTD
40 
41 #include "common/error.hpp"
42 #include "common/locator.hpp"
43 #include "common/non_copyable.hpp"
44 
45 namespace ot {
46 
47 class Child;
48 
49 /**
50  * @addtogroup core-source-match-controller
51  *
52  * @brief
53  *   This module includes definition for source address match controller.
54  *
55  * @{
56  */
57 
58 /**
59  * Implements the "source address match" controller.
60  *
61  * The source address match feature controls how the radio layer decides the "frame pending" bit for acks sent in
62  * response to data request commands from sleepy children.
63  *
64  * Updates the source match table and also controls when to enable or disable the source matching
65  * feature.
66  *
67  * The source address match table provides the list of children for which there is a pending frame. Either a short
68  * address or an extended/long address can be added to the source address match table.
69  *
70  */
71 class SourceMatchController : public InstanceLocator, private NonCopyable
72 {
73 public:
74     /**
75      * Initializes the object.
76      *
77      * @param[in]  aInstance    A reference to the OpenThread instance
78      *
79      */
80     explicit SourceMatchController(Instance &aInstance);
81 
82     /**
83      * Returns the current state of source address matching.
84      *
85      * @returns `true` if source address matching is enabled, `false` otherwise.
86      *
87      */
IsEnabled(void) const88     bool IsEnabled(void) const { return mEnabled; }
89 
90     /**
91      * Increments the message count for a child and updates the source match table.
92      *
93      * @param[in] aChild    A reference to the child.
94      *
95      */
96     void IncrementMessageCount(Child &aChild);
97 
98     /**
99      * Decrements the message count for a child and updates the source match table.
100      *
101      * @param[in] aChild    A reference to the child.
102      *
103      */
104     void DecrementMessageCount(Child &aChild);
105 
106     /**
107      * Resets the message count for a child to zero and updates the source match table.
108      *
109      * @param[in] aChild    A reference to the child.
110      *
111      */
112     void ResetMessageCount(Child &aChild);
113 
114     /**
115      * Sets whether or not to perform source address matching on the extended or short address for
116      * a child.
117      *
118      * @param[in] aChild            A reference to the child.
119      * @param[in] aUseShortAddress  `true` to match on short source address, `false` otherwise.
120      *
121      */
122     void SetSrcMatchAsShort(Child &aChild, bool aUseShortAddress);
123 
124 private:
125     /**
126      * Clears the source match table.
127      *
128      */
129     void ClearTable(void);
130 
131     /**
132      * Enables or disables the source matching.
133      *
134      * If enabled, the radio uses the source match table to determine whether to set or clear the "frame pending" bit
135      * in an acknowledgment to a MAC Data Request command. If disabled, the radio layer sets the "frame pending" on all
136      * acknowledgment frames in response to MAC Data Request commands.
137      *
138      * @param[in] aEnable   `true` to enable, `false` to disable.
139      *
140      */
141     void Enable(bool aEnable);
142 
143     /**
144      * Adds an entry to source match table for a given child and updates the state of source matching
145      * feature accordingly.
146      *
147      * If the entry is added successfully, source matching feature is enabled (if not already enabled) after ensuring
148      * that there are no remaining pending entries. If the entry cannot be added (no space in source match table),
149      * the child is marked to remember the pending entry and source matching is disabled.
150      *
151      * @param[in] aChild    A reference to the child.
152      *
153      */
154     void AddEntry(Child &aChild);
155 
156     /**
157      * Clears an entry in source match table for a given child and updates the state of source matching
158      * feature accordingly.
159      *
160      * If the entry is removed successfully and frees up space in the source match table, any remaining pending
161      * entries are added. If all pending entries are successfully added, source matching is enabled.
162      *
163      * @param[in] aChild    A reference to the child.
164      *
165      */
166     void ClearEntry(Child &aChild);
167 
168     /**
169      * Adds a given child's address (short or extended address depending on child's setting) to the source
170      * source match table (@sa SetSrcMatchAsShort.
171      *
172      * @param[in] aChild            A reference to the child
173      *
174      * @retval kErrorNone     Child's address was added successfully to the source match table.
175      * @retval kErrorNoBufs   No available space in the source match table.
176      *
177      */
178     Error AddAddress(const Child &aChild);
179 
180     /**
181      * Adds all pending entries to the source match table.
182      *
183      * @retval kErrorNone     All pending entries were successfully added.
184      * @retval kErrorNoBufs   No available space in the source match table.
185      *
186      */
187     Error AddPendingEntries(void);
188 
189     bool mEnabled;
190 };
191 
192 /**
193  * @}
194  *
195  */
196 
197 } // namespace ot
198 
199 #endif // OPENTHREAD_FTD
200 
201 #endif // SOURCE_MATCH_CONTROLLER_HPP_
202