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 class SourceMatchController : public InstanceLocator, private NonCopyable
71 {
72 public:
73     /**
74      * Initializes the object.
75      *
76      * @param[in]  aInstance    A reference to the OpenThread instance
77      */
78     explicit SourceMatchController(Instance &aInstance);
79 
80     /**
81      * Returns the current state of source address matching.
82      *
83      * @returns `true` if source address matching is enabled, `false` otherwise.
84      */
IsEnabled(void) const85     bool IsEnabled(void) const { return mEnabled; }
86 
87     /**
88      * Increments the message count for a child and updates the source match table.
89      *
90      * @param[in] aChild    A reference to the child.
91      */
92     void IncrementMessageCount(Child &aChild);
93 
94     /**
95      * Decrements the message count for a child and updates the source match table.
96      *
97      * @param[in] aChild    A reference to the child.
98      */
99     void DecrementMessageCount(Child &aChild);
100 
101     /**
102      * Resets the message count for a child to zero and updates the source match table.
103      *
104      * @param[in] aChild    A reference to the child.
105      */
106     void ResetMessageCount(Child &aChild);
107 
108     /**
109      * Sets whether or not to perform source address matching on the extended or short address for
110      * a child.
111      *
112      * @param[in] aChild            A reference to the child.
113      * @param[in] aUseShortAddress  `true` to match on short source address, `false` otherwise.
114      */
115     void SetSrcMatchAsShort(Child &aChild, bool aUseShortAddress);
116 
117 private:
118     /**
119      * Clears the source match table.
120      */
121     void ClearTable(void);
122 
123     /**
124      * Enables or disables the source matching.
125      *
126      * If enabled, the radio uses the source match table to determine whether to set or clear the "frame pending" bit
127      * in an acknowledgment to a MAC Data Request command. If disabled, the radio layer sets the "frame pending" on all
128      * acknowledgment frames in response to MAC Data Request commands.
129      *
130      * @param[in] aEnable   `true` to enable, `false` to disable.
131      */
132     void Enable(bool aEnable);
133 
134     /**
135      * Adds an entry to source match table for a given child and updates the state of source matching
136      * feature accordingly.
137      *
138      * If the entry is added successfully, source matching feature is enabled (if not already enabled) after ensuring
139      * that there are no remaining pending entries. If the entry cannot be added (no space in source match table),
140      * the child is marked to remember the pending entry and source matching is disabled.
141      *
142      * @param[in] aChild    A reference to the child.
143      */
144     void AddEntry(Child &aChild);
145 
146     /**
147      * Clears an entry in source match table for a given child and updates the state of source matching
148      * feature accordingly.
149      *
150      * If the entry is removed successfully and frees up space in the source match table, any remaining pending
151      * entries are added. If all pending entries are successfully added, source matching is enabled.
152      *
153      * @param[in] aChild    A reference to the child.
154      */
155     void ClearEntry(Child &aChild);
156 
157     /**
158      * Adds a given child's address (short or extended address depending on child's setting) to the source
159      * source match table (@sa SetSrcMatchAsShort.
160      *
161      * @param[in] aChild            A reference to the child
162      *
163      * @retval kErrorNone     Child's address was added successfully to the source match table.
164      * @retval kErrorNoBufs   No available space in the source match table.
165      */
166     Error AddAddress(const Child &aChild);
167 
168     /**
169      * Adds all pending entries to the source match table.
170      *
171      * @retval kErrorNone     All pending entries were successfully added.
172      * @retval kErrorNoBufs   No available space in the source match table.
173      */
174     Error AddPendingEntries(void);
175 
176     bool mEnabled;
177 };
178 
179 /**
180  * @}
181  */
182 
183 } // namespace ot
184 
185 #endif // OPENTHREAD_FTD
186 
187 #endif // SOURCE_MATCH_CONTROLLER_HPP_
188