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 <cstdint>
      28              : #include <cstring>
      29              : #include <lib/core/CHIPError.h>
      30              : #include <system/SystemPacketBuffer.h>
      31              : 
      32              : namespace chip {
      33              : namespace WiFiPAF {
      34              : 
      35              : inline constexpr size_t kTransferProtocolHeaderFlagsSize = 1; // Size in bytes of encoded PAFTP fragment header flag bits
      36              : inline constexpr size_t kTransferProtocolMgmtOpSize      = 1; // Size of bytes of encoded PAFTP management OpCode
      37              : inline constexpr size_t kTransferProtocolSequenceNumSize = 1; // Size in bytes of encoded PAFTP sequence number
      38              : inline constexpr size_t kTransferProtocolAckSize         = 1; // Size in bytes of encoded PAFTP fragment acknowledgement number
      39              : inline constexpr size_t kTransferProtocolMsgLenSize      = 2; // Size in byte of encoded PAFTP total fragmented message length
      40              : 
      41              : constexpr size_t kTransferProtocolMaxHeaderSize =
      42              :     kTransferProtocolHeaderFlagsSize + kTransferProtocolAckSize + kTransferProtocolSequenceNumSize + kTransferProtocolMsgLenSize;
      43              : constexpr size_t kTransferProtocolMidFragmentMaxHeaderSize =
      44              :     kTransferProtocolHeaderFlagsSize + kTransferProtocolAckSize + kTransferProtocolSequenceNumSize;
      45              : constexpr size_t kTransferProtocolStandaloneAckHeaderSize =
      46              :     kTransferProtocolHeaderFlagsSize + kTransferProtocolAckSize + kTransferProtocolSequenceNumSize;
      47              : 
      48              : using ::chip::System::PacketBufferHandle;
      49              : 
      50              : typedef uint8_t SequenceNumber_t;
      51              : 
      52              : typedef enum
      53              : {
      54              :     kType_Data    = 0, // Default 0 for data
      55              :     kType_Control = 1,
      56              : } PacketType_t; // PAFTP packet types
      57              : #define CHIP_PAFTP_RXHIST_SIZE 8u
      58              : 
      59           21 : inline SequenceNumber_t IncSeqNum(SequenceNumber_t & a_seq_num)
      60              : {
      61           21 :     return static_cast<SequenceNumber_t>(0xff & ((a_seq_num) + 1));
      62              : }
      63              : 
      64              : /*
      65              :     Offset from "tgtSeqNum" to "baseSeqNum"
      66              : */
      67              : SequenceNumber_t OffsetSeqNum(SequenceNumber_t & tgtSeqNum, SequenceNumber_t & baseSeqNum);
      68              : 
      69              : class WiFiPAFTP // PAFTP Engine
      70              : {
      71              :     friend class TestWiFiPAFLayer;
      72              : 
      73              : public:
      74              :     typedef enum
      75              :     {
      76              :         kState_Idle       = 0,
      77              :         kState_InProgress = 1,
      78              :         kState_Complete   = 2,
      79              :         kState_Error      = 3
      80              :     } State_t; // [READ-ONLY] Current state
      81              : 
      82              :     // Masks for PAFTP fragment header flag bits.
      83              :     enum class HeaderFlags : uint8_t
      84              :     {
      85              :         kStartMessage     = 0x01,
      86              :         kContinueMessage  = 0x02,
      87              :         kEndMessage       = 0x04,
      88              :         kFragmentAck      = 0x08,
      89              :         kManagementOpcode = 0x20,
      90              :         kHankshake        = 0x40,
      91              :     };
      92              : 
      93              :     static const uint16_t sDefaultFragmentSize;
      94              :     static const uint16_t sMaxFragmentSize;
      95              : 
      96              :     // Public functions:
      97              :     CHIP_ERROR Init(void * an_app_state, bool expect_first_ack);
      98              : 
      99            2 :     inline void SetTxFragmentSize(uint16_t size) { mTxFragmentSize = size; }
     100            2 :     inline void SetRxFragmentSize(uint16_t size) { mRxFragmentSize = size; }
     101              : 
     102            2 :     uint16_t GetRxFragmentSize() const { return mRxFragmentSize; }
     103            2 :     uint16_t GetTxFragmentSize() const { return mTxFragmentSize; }
     104              : 
     105              :     SequenceNumber_t GetAndIncrementNextTxSeqNum();
     106              :     SequenceNumber_t GetAndRecordRxAckSeqNum();
     107            7 :     inline SequenceNumber_t GetRxNextSeqNum() const { return mRxNextSeqNum; }
     108              : 
     109              :     inline SequenceNumber_t GetLastReceivedSequenceNumber() const { return mRxNewestUnackedSeqNum; }
     110            4 :     inline SequenceNumber_t GetNewestUnackedSentSequenceNumber() const { return mTxNewestUnackedSeqNum; }
     111              : 
     112            4 :     inline bool ExpectingAck() const { return mExpectingAck; }
     113              : 
     114            4 :     inline State_t RxState() { return mRxState; }
     115           24 :     inline State_t TxState() { return mTxState; }
     116              : 
     117              :     bool HasUnackedData() const;
     118              : 
     119              :     CHIP_ERROR HandleCharacteristicReceived(System::PacketBufferHandle && data, SequenceNumber_t & receivedAck,
     120              :                                             bool & didReceiveAck);
     121              :     bool HandleCharacteristicSend(System::PacketBufferHandle data, bool send_ack);
     122              :     CHIP_ERROR EncodeStandAloneAck(const PacketBufferHandle & data);
     123              : 
     124              :     PacketBufferHandle TakeRxPacket();
     125              :     PacketBufferHandle BorrowRxPacket() { return mRxBuf.Retain(); }
     126            2 :     void ClearRxPacket() { (void) TakeRxPacket(); }
     127              :     PacketBufferHandle TakeTxPacket();
     128            7 :     PacketBufferHandle BorrowTxPacket() { return mTxBuf.Retain(); }
     129            2 :     void ClearTxPacket() { (void) TakeTxPacket(); }
     130              : 
     131              :     void LogState() const;
     132              :     void LogStateDebug() const;
     133              : 
     134              : protected:
     135              :     State_t mRxState;
     136              :     uint16_t mRxLength;
     137              :     void * mAppState;
     138              :     System::PacketBufferHandle mRxBuf;
     139              :     SequenceNumber_t mRxNextSeqNum;
     140              :     SequenceNumber_t mRxNewestUnackedSeqNum;
     141              :     SequenceNumber_t mRxOldestUnackedSeqNum;
     142              :     uint16_t mRxFragmentSize;
     143              :     SequenceNumber_t mRxSeqHist[CHIP_PAFTP_RXHIST_SIZE];
     144              :     uint8_t mRxSeqHistId;
     145              : 
     146              :     State_t mTxState;
     147              :     uint16_t mTxLength;
     148              :     System::PacketBufferHandle mTxBuf;
     149              :     SequenceNumber_t mTxNextSeqNum;
     150              :     SequenceNumber_t mTxNewestUnackedSeqNum;
     151              :     SequenceNumber_t mTxOldestUnackedSeqNum;
     152              :     bool mExpectingAck;
     153              :     uint16_t mTxFragmentSize;
     154              : 
     155              :     uint16_t mRxCharCount;
     156              :     uint16_t mRxPacketCount;
     157              :     uint16_t mTxCharCount;
     158              :     uint16_t mTxPacketCount;
     159              : 
     160              :     // Private functions:
     161              :     bool IsValidAck(SequenceNumber_t ack_num) const;
     162              :     CHIP_ERROR HandleAckReceived(SequenceNumber_t ack_num);
     163              : };
     164              : 
     165              : } /* namespace WiFiPAF */
     166              : } /* namespace chip */