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