1 /* 2 * Copyright (c) 2023, 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 contains definitions of the SPI frame. 31 */ 32 33 #ifndef SPINEL_SPI_FRAME_HPP_ 34 #define SPINEL_SPI_FRAME_HPP_ 35 36 #include <stdint.h> 37 38 #include "lib/utils/endian.hpp" 39 40 namespace ot { 41 namespace Spinel { 42 43 /* 44 * SPI Framing Protocol 45 * 46 * Each SPI frame starts with a 5-byte frame header: 47 * 48 * +---------+-----+----------+----------+ 49 * | Octets: | 1 | 2 | 2 | 50 * +---------+-----+----------+----------+ 51 * | Fields: | HDR | RECV_LEN | DATA_LEN | 52 * +---------+-----+----------+----------+ 53 * 54 * - "HDR": The first byte is the header byte (defined below) 55 * - "RECV_LEN": The second and third bytes indicate the largest frame 56 * size that that device is ready to receive. If zero, then the 57 * other device must not send any data. (Little endian) 58 * - "DATA_LEN": The fourth and fifth bytes indicate the size of the 59 * pending data frame to be sent to the other device. If this value 60 * is equal-to or less-than the number of bytes that the other device 61 * is willing to receive, then the data of the frame is immediately 62 * after the header. (Little Endian) 63 * 64 * The "HDR" byte is defined as: 65 * 66 * 0 1 2 3 4 5 6 7 67 * +---+---+---+---+---+---+---+---+ 68 * |RST|CRC|CCF| RESERVED |PATTERN| 69 * +---+---+---+---+---+---+---+---+ 70 * 71 * - "RST": This bit is set when that device has been reset since the 72 * last time `CS` (chip select) was asserted. 73 * - "CRC": This bit is set when that device supports writing a 16-bit 74 * CRC at the end of the data. The CRC length is NOT included in 75 * DATA_LEN. 76 * - "CCF": "CRC Check Failure". Set if the CRC check on the last 77 * received frame failed, cleared to zero otherwise. This bit is 78 * only used if both sides support CRC. 79 * - "RESERVED": These bits are all reserved for future used. They 80 * MUST be cleared to zero and MUST be ignored if set. 81 * - "PATTERN": These bits are set to a fixed value to help distinguish 82 * valid SPI frames from garbage (by explicitly making "0xFF" and 83 * "0x00" invalid values). Bit 6 MUST be set to be one and bit 7 84 * MUST be cleared (0). A frame received that has any other values 85 * for these bits MUST be dropped. 86 * 87 * Prior to a sending or receiving a frame, the master MAY send a 88 * 5-octet frame with zeros for both the max receive frame size and the 89 * the contained frame length. This will induce the slave device to 90 * indicate the length of the frame it wants to send (if any) and 91 * indicate the largest frame it is capable of receiving at the moment. 92 * This allows the master to calculate the size of the next transaction. 93 * Alternatively, if the master has a frame to send it can just go ahead 94 * and send a frame of that length and determine if the frame was 95 * accepted by checking that the "RECV_LEN" from the slave frame is 96 * larger than the frame the master just tried to send. If the 97 * "RECV_LEN" is smaller then the frame wasn't accepted and will need to 98 * be transmitted again. 99 * 100 * This protocol can be used either unidirectionally or bidirectionally, 101 * determined by the behavior of the master and the slave. 102 * 103 * If the the master notices "PATTERN" is not set correctly, the master 104 * should consider the transaction to have failed and try again after 10 105 * milliseconds, retrying up to 200 times. After unsuccessfully trying 106 * 200 times in a row, the master MAY take appropriate remedial action 107 * (like a NCP hardware reset, or indicating a communication failure to 108 * a user interface). 109 * 110 * At the end of the data of a frame is an optional 16-bit CRC, support 111 * for which is indicated by the "CRC" bit of the "HDR" byte being set. 112 * If these bits are set for both the master and slave frames, then CRC 113 * checking is enabled on both sides, effectively requiring that frame 114 * sizes be two bytes longer than would be otherwise required. The CRC 115 * is calculated using the same mechanism used for the CRC calculation 116 * in HDLC-Lite (See Appendix A.1.2). When both of the "CRC" bits are 117 * set, both sides must verify that the "CRC" is valid before accepting 118 * the frame. If not enough bytes were clocked out for the CRC to be 119 * read, then the frame must be ignored. If enough bytes were clocked 120 * out to perform a CRC check, but the CRC check fails, then the frame 121 * must be rejected and the "CRC_FAIL" bit on the next frame (and ONLY 122 * the next frame) MUST be set. 123 */ 124 125 /** 126 * Defines a SPI frame. 127 */ 128 class SpiFrame 129 { 130 public: 131 enum 132 { 133 kHeaderSize = 5, ///< SPI header size (in bytes). 134 }; 135 136 /** 137 * Initializes an `SpiFrame` instance. 138 * 139 * @param[in] aBuffer Pointer to buffer containing the frame. 140 */ SpiFrame(uint8_t * aBuffer)141 explicit SpiFrame(uint8_t *aBuffer) 142 : mBuffer(aBuffer) 143 { 144 } 145 146 /** 147 * Gets a pointer to data portion in the SPI frame skipping the header. 148 * 149 * @returns A pointer to data in the SPI frame. 150 */ GetData(void)151 uint8_t *GetData(void) { return mBuffer + kHeaderSize; } 152 153 /** 154 * Indicates whether or not the frame is valid. 155 * 156 * In a valid frame the flag byte should contain the pattern bits. 157 * 158 * @returns TRUE if the frame is valid, FALSE otherwise. 159 */ IsValid(void) const160 bool IsValid(void) const { return ((mBuffer[kIndexFlagByte] & kFlagPatternMask) == kFlagPattern); } 161 162 /** 163 * Indicates whether or not the "RST" bit is set. 164 * 165 * @returns TRUE if the "RST" bit is set, FALSE otherwise. 166 */ IsResetFlagSet(void) const167 bool IsResetFlagSet(void) const { return ((mBuffer[kIndexFlagByte] & kFlagReset) == kFlagReset); } 168 169 /** 170 * Sets the "flag byte" field in the SPI frame header. 171 * 172 * @param[in] aResetFlag The status of reset flag (TRUE to set the flag, FALSE to clear flag). 173 */ SetHeaderFlagByte(bool aResetFlag)174 void SetHeaderFlagByte(bool aResetFlag) { mBuffer[kIndexFlagByte] = kFlagPattern | (aResetFlag ? kFlagReset : 0); } 175 176 /** 177 * Gets the "flag byte" field in the SPI frame header. 178 * 179 * @returns The flag byte. 180 */ GetHeaderFlagByte(void) const181 uint8_t GetHeaderFlagByte(void) const { return mBuffer[kIndexFlagByte]; } 182 183 /** 184 * Sets the "accept len" field in the SPI frame header. 185 * 186 * "accept len" specifies number of bytes the sender of the SPI frame can receive. 187 * 188 * @param[in] aAcceptLen The accept length in bytes. 189 */ SetHeaderAcceptLen(uint16_t aAcceptLen)190 void SetHeaderAcceptLen(uint16_t aAcceptLen) 191 { 192 Lib::Utils::LittleEndian::WriteUint16(aAcceptLen, mBuffer + kIndexAcceptLen); 193 } 194 195 /** 196 * Gets the "accept len" field in the SPI frame header. 197 * 198 * @returns The accept length in bytes. 199 */ GetHeaderAcceptLen(void) const200 uint16_t GetHeaderAcceptLen(void) const { return Lib::Utils::LittleEndian::ReadUint16(mBuffer + kIndexAcceptLen); } 201 202 /** 203 * Sets the "data len" field in the SPI frame header. 204 * 205 * "Data len" specifies number of data bytes in the transmitted SPI frame. 206 * 207 * @param[in] aDataLen The data length in bytes. 208 */ SetHeaderDataLen(uint16_t aDataLen)209 void SetHeaderDataLen(uint16_t aDataLen) 210 { 211 Lib::Utils::LittleEndian::WriteUint16(aDataLen, mBuffer + kIndexDataLen); 212 } 213 214 /** 215 * Gets the "data len" field in the SPI frame header. 216 * 217 * @returns The data length in bytes. 218 */ GetHeaderDataLen(void) const219 uint16_t GetHeaderDataLen(void) const { return Lib::Utils::LittleEndian::ReadUint16(mBuffer + kIndexDataLen); } 220 221 private: 222 enum 223 { 224 kIndexFlagByte = 0, // flag byte (uint8_t). 225 kIndexAcceptLen = 1, // accept len (uint16_t little-endian encoding). 226 kIndexDataLen = 3, // data len (uint16_t little-endian encoding). 227 228 kFlagReset = (1 << 7), // Flag byte RESET bit. 229 kFlagPattern = 0x02, // Flag byte PATTERN bits. 230 kFlagPatternMask = 0x03, // Flag byte PATTERN mask. 231 }; 232 233 uint8_t *mBuffer; 234 }; 235 236 } // namespace Spinel 237 } // namespace ot 238 #endif // SPINEL_SPI_FRAME_HPP_ 239