1 /*
2  *    Copyright (c) 2016, 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" AND
17  *    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  *    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  *    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20  *    DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  *    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  *    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  *    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  *    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25  *    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 
28 /**
29  * @file
30  *   This file includes definitions for an HDLC-lite encoder and decoder.
31  */
32 
33 #ifndef HDLC_HPP_
34 #define HDLC_HPP_
35 
36 #include <stdint.h>
37 #include <stdlib.h>
38 #include <string.h>
39 
40 #include <openthread/error.h>
41 
42 #include "lib/spinel/multi_frame_buffer.hpp"
43 
44 namespace ot {
45 
46 /**
47  * @namespace ot::Hdlc
48  *
49  * @brief
50  *   This namespace includes definitions for the HDLC-lite encoder and decoder.
51  */
52 namespace Hdlc {
53 
54 /**
55  * Implements the HDLC-lite encoder.
56  */
57 class Encoder
58 {
59 public:
60     /**
61      * Initializes the object.
62      *
63      * @param[in] aWritePointer   The `FrameWritePointer` used by `Encoder` to write the encoded frames.
64      */
65     explicit Encoder(Spinel::FrameWritePointer &aWritePointer);
66 
67     /**
68      * Begins an HDLC frame.
69      *
70      * @retval OT_ERROR_NONE     Successfully started the HDLC frame.
71      * @retval OT_ERROR_NO_BUFS  Insufficient buffer space available to start the HDLC frame.
72      */
73     otError BeginFrame(void);
74 
75     /**
76      * Encodes a single byte into current frame.
77      *
78      * If there is no space to add the byte, the write pointer in frame buffer remains the same.
79      *
80      * @param[in]    aByte       A byte value to encode and add to frame.
81      *
82      * @retval OT_ERROR_NONE     Successfully encoded and added the byte to frame buffer.
83      * @retval OT_ERROR_NO_BUFS  Insufficient buffer space available to encode and add the byte.
84      */
85     otError Encode(uint8_t aByte);
86 
87     /**
88      * Encodes a given block of data into current frame.
89      *
90      * Returns success only if there is space in buffer to encode the entire block of data. If there is no
91      * space to encode the entire block of data, the write pointer in frame buffer remains the same.
92      *
93      * @param[in]    aData       A pointer to a buffer containing the data to encode.
94      * @param[in]    aLength     The number of bytes in @p aData.
95      *
96      * @retval OT_ERROR_NONE     Successfully encoded and added the data to frame.
97      * @retval OT_ERROR_NO_BUFS  Insufficient buffer space available to add the frame.
98      */
99     otError Encode(const uint8_t *aData, uint16_t aLength);
100 
101     /**
102      * Ends/finalizes the HDLC frame.
103      *
104      * @retval OT_ERROR_NONE     Successfully ended the HDLC frame.
105      * @retval OT_ERROR_NO_BUFS  Insufficient buffer space available to end the HDLC frame.
106      */
107     otError EndFrame(void);
108 
109 private:
110     Spinel::FrameWritePointer &mWritePointer;
111     uint16_t                   mFcs;
112 };
113 
114 /**
115  * Implements the HDLC-lite decoder.
116  */
117 class Decoder
118 {
119 public:
120     /**
121      * Pointer is called when either a complete frame has been decoded or an error occurs during
122      * decoding.
123      *
124      * The decoded frame (or the partially decoded frame in case of an error) is available in `aFrameWritePointer`
125      * buffer given in `Decoder` constructor.
126      *
127      * @param[in] aContext A pointer to arbitrary context information.
128      * @param[in] aError   OT_ERROR_NONE    if the frame was decoded successfully,
129      *                     OT_ERROR_PARSE   if the Frame Check Sequence (FCS) was incorrect in decoded frame,
130      *                     OT_ERROR_NO_BUFS insufficient buffer space available to save the decoded frame.
131      */
132     typedef void (*FrameHandler)(void *aContext, otError aError);
133 
134     /**
135      * Initializes the object.
136      */
137     Decoder(void);
138 
139     /**
140      * Initializes the decoder.
141      *
142      * @param[in] aFrameWritePointer   The `FrameWritePointer` used by `Decoder` to write the decoded frames.
143      * @param[in] aFrameHandler        The frame handler callback function pointer.
144      * @param[in] aContext             A pointer to arbitrary context information.
145      */
146     void Init(Spinel::FrameWritePointer &aFrameWritePointer, FrameHandler aFrameHandler, void *aContext);
147 
148     /**
149      * Feeds a block of data into the decoder.
150      *
151      * If during decoding, a full HDLC frame is successfully decoded or an error occurs, the `FrameHandler` callback
152      * is called. The decoded frame (or the partially decoded frame in case of an error) is available in
153      * `aFrameWritePointer` buffer from the constructor. The `Decoder` user (if required) must update/reset the write
154      * pointer from this callback for the next frame to be decoded.
155      *
156      * @param[in]  aData    A pointer to a buffer containing data to be fed to decoder.
157      * @param[in]  aLength  The number of bytes in @p aData.
158      */
159     void Decode(const uint8_t *aData, uint16_t aLength);
160 
161     /**
162      * Resets internal states of the decoder.
163      */
164     void Reset(void);
165 
166 private:
167     enum State
168     {
169         kStateNoSync,
170         kStateSync,
171         kStateEscaped,
172     };
173 
174     State                      mState;
175     Spinel::FrameWritePointer *mWritePointer;
176     FrameHandler               mFrameHandler;
177     void                      *mContext;
178     uint16_t                   mFcs;
179     uint16_t                   mDecodedLength;
180 };
181 
182 } // namespace Hdlc
183 } // namespace ot
184 
185 #endif // HDLC_HPP_
186