Line data    Source code

       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2025 Project CHIP Authors
       4              :  *
       5              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       6              :  *    you may not use this file except in compliance with the License.
       7              :  *    You may obtain a copy of the License at
       8              :  *
       9              :  *        http://www.apache.org/licenses/LICENSE-2.0
      10              :  *
      11              :  *    Unless required by applicable law or agreed to in writing, software
      12              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      13              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      14              :  *    See the License for the specific language governing permissions and
      15              :  *    limitations under the License.
      16              :  */
      17              : 
      18              : /**
      19              :  *    @file
      20              :  *      This file defines types and an object for the chip over
      21              :  *      WiFiPAF (CHIPoPAF) links.
      22              :  *
      23              :  */
      24              : 
      25              : #pragma once
      26              : 
      27              : #include <algorithm>
      28              : #include <cstdint>
      29              : #include <cstring>
      30              : #include <lib/core/CHIPError.h>
      31              : #include <system/SystemPacketBuffer.h>
      32              : 
      33              : namespace chip {
      34              : namespace WiFiPAF {
      35              : 
      36              : inline constexpr size_t kTransferProtocolHeaderFlagsSize = 1; // Size in bytes of encoded PAFTP fragment header flag bits
      37              : inline constexpr size_t kTransferProtocolMgmtOpSize      = 1; // Size of bytes of encoded PAFTP management OpCode
      38              : inline constexpr size_t kTransferProtocolSequenceNumSize = 1; // Size in bytes of encoded PAFTP sequence number
      39              : inline constexpr size_t kTransferProtocolAckSize         = 1; // Size in bytes of encoded PAFTP fragment acknowledgement number
      40              : inline constexpr size_t kTransferProtocolMsgLenSize      = 2; // Size in byte of encoded PAFTP total fragmented message length
      41              : 
      42              : constexpr size_t kTransferProtocolMaxHeaderSize =
      43              :     kTransferProtocolHeaderFlagsSize + kTransferProtocolAckSize + kTransferProtocolSequenceNumSize + kTransferProtocolMsgLenSize;
      44              : constexpr size_t kTransferProtocolMidFragmentMaxHeaderSize =
      45              :     kTransferProtocolHeaderFlagsSize + kTransferProtocolAckSize + kTransferProtocolSequenceNumSize;
      46              : constexpr size_t kTransferProtocolStandaloneAckHeaderSize =
      47              :     kTransferProtocolHeaderFlagsSize + kTransferProtocolAckSize + kTransferProtocolSequenceNumSize;
      48              : 
      49              : using ::chip::System::PacketBufferHandle;
      50              : 
      51              : typedef uint8_t SequenceNumber_t;
      52              : 
      53              : typedef enum
      54              : {
      55              :     kType_Data    = 0, // Default 0 for data
      56              :     kType_Control = 1,
      57              : } PacketType_t; // PAFTP packet types
      58              : #define CHIP_PAFTP_RXHIST_SIZE 8u
      59              : 
      60           22 : inline SequenceNumber_t IncSeqNum(SequenceNumber_t & a_seq_num)
      61              : {
      62           22 :     return static_cast<SequenceNumber_t>(0xff & ((a_seq_num) + 1));
      63              : }
      64              : 
      65              : /*
      66              :     Offset from "tgtSeqNum" to "baseSeqNum"
      67              : */
      68              : SequenceNumber_t OffsetSeqNum(SequenceNumber_t & tgtSeqNum, SequenceNumber_t & baseSeqNum);
      69              : 
      70              : class WiFiPAFTP // PAFTP Engine
      71              : {
      72              :     friend class TestWiFiPAFLayer;
      73              : 
      74              : public:
      75              :     typedef enum
      76              :     {
      77              :         kState_Idle       = 0,
      78              :         kState_InProgress = 1,
      79              :         kState_Complete   = 2,
      80              :         kState_Error      = 3
      81              :     } State_t; // [READ-ONLY] Current state
      82              : 
      83              :     // Masks for PAFTP fragment header flag bits.
      84              :     enum class HeaderFlags : uint8_t
      85              :     {
      86              :         kStartMessage     = 0x01,
      87              :         kContinueMessage  = 0x02,
      88              :         kEndMessage       = 0x04,
      89              :         kFragmentAck      = 0x08,
      90              :         kManagementOpcode = 0x20,
      91              :         kHankshake        = 0x40,
      92              :     };
      93              : 
      94              :     static const uint16_t sDefaultFragmentSize;
      95              :     static const uint16_t sMaxFragmentSize;
      96              :     static const uint16_t sMinFragmentSize;
      97              : 
      98              :     // Public functions:
      99              :     CHIP_ERROR Init(void * an_app_state, bool expect_first_ack);
     100              : 
     101            6 :     inline void SetTxFragmentSize(uint16_t size) { mTxFragmentSize = std::clamp(size, sMinFragmentSize, sMaxFragmentSize); }
     102            6 :     inline void SetRxFragmentSize(uint16_t size) { mRxFragmentSize = std::clamp(size, sMinFragmentSize, sMaxFragmentSize); }
     103              : 
     104            5 :     uint16_t GetRxFragmentSize() const { return mRxFragmentSize; }
     105            5 :     uint16_t GetTxFragmentSize() const { return mTxFragmentSize; }
     106              : 
     107              :     SequenceNumber_t GetAndIncrementNextTxSeqNum();
     108              :     SequenceNumber_t GetAndRecordRxAckSeqNum();
     109            9 :     inline SequenceNumber_t GetRxNextSeqNum() const { return mRxNextSeqNum; }
     110              : 
     111            1 :     inline SequenceNumber_t GetLastReceivedSequenceNumber() const { return mRxNewestUnackedSeqNum; }
     112            5 :     inline SequenceNumber_t GetNewestUnackedSentSequenceNumber() const { return mTxNewestUnackedSeqNum; }
     113              : 
     114            5 :     inline bool ExpectingAck() const { return mExpectingAck; }
     115              : 
     116            7 :     inline State_t RxState() { return mRxState; }
     117           35 :     inline State_t TxState() { return mTxState; }
     118              : 
     119              :     bool HasUnackedData() const;
     120              : 
     121              :     CHIP_ERROR HandleCharacteristicReceived(System::PacketBufferHandle && data, SequenceNumber_t & receivedAck,
     122              :                                             bool & didReceiveAck);
     123              :     bool HandleCharacteristicSend(System::PacketBufferHandle data, bool send_ack);
     124              :     CHIP_ERROR EncodeStandAloneAck(const PacketBufferHandle & data);
     125              : 
     126              :     PacketBufferHandle TakeRxPacket();
     127              :     PacketBufferHandle BorrowRxPacket() { return mRxBuf.Retain(); }
     128            9 :     void ClearRxPacket() { (void) TakeRxPacket(); }
     129              :     PacketBufferHandle TakeTxPacket();
     130            8 :     PacketBufferHandle BorrowTxPacket() { return mTxBuf.Retain(); }
     131            9 :     void ClearTxPacket() { (void) TakeTxPacket(); }
     132              : 
     133              :     void LogState() const;
     134              :     void LogStateDebug() const;
     135              : 
     136              : protected:
     137              :     State_t mRxState;
     138              :     uint16_t mRxLength;
     139              :     void * mAppState;
     140              :     System::PacketBufferHandle mRxBuf;
     141              :     SequenceNumber_t mRxNextSeqNum;
     142              :     SequenceNumber_t mRxNewestUnackedSeqNum;
     143              :     SequenceNumber_t mRxOldestUnackedSeqNum;
     144              :     uint16_t mRxFragmentSize;
     145              :     SequenceNumber_t mRxSeqHist[CHIP_PAFTP_RXHIST_SIZE];
     146              :     uint8_t mRxSeqHistId;
     147              : 
     148              :     State_t mTxState;
     149              :     uint16_t mTxLength;
     150              :     System::PacketBufferHandle mTxBuf;
     151              :     SequenceNumber_t mTxNextSeqNum;
     152              :     SequenceNumber_t mTxNewestUnackedSeqNum;
     153              :     SequenceNumber_t mTxOldestUnackedSeqNum;
     154              :     bool mExpectingAck;
     155              :     uint16_t mTxFragmentSize;
     156              : 
     157              :     uint16_t mRxCharCount;
     158              :     uint16_t mRxPacketCount;
     159              :     uint16_t mTxCharCount;
     160              :     uint16_t mTxPacketCount;
     161              : 
     162              :     // Private functions:
     163              :     bool IsValidAck(SequenceNumber_t ack_num) const;
     164              :     CHIP_ERROR HandleAckReceived(SequenceNumber_t ack_num);
     165              : };
     166              : 
     167              : } /* namespace WiFiPAF */
     168              : } /* namespace chip */