Main concepts

Boards, ports and instances

Throughout this documentation, we will refer to three main entities in a hierarchical fashion.

                          ---------
                          | Board |
                          ---------
                          /   ^   \
                         /    |    \
                        /     |     \
                       /      |      \
                      /       |       \  
                ------------  |  ------------                  ------------  
                | Physical |  |  | Physical |                  |   TcAP   | 
                |   Port   |  |  |   Port   |                  |   Port   | 
                ------------  |  ------------                  ------------
                              |      |      \                     |      \
                        ------------ |       \                    |       \
                        |   BAP    | |        \                   |        \ 
                        |   Port   | |         \                  |         \
                        ------------ |          \                 |          \
                         /      |    |           \                |           \
                        /       |    |            \               |            \
                       /        | ------------   ------------   ------------   ------------
                      /         | | Instance |   | Instance |   | Instance |   | Instance |
                     /          | ------------   ------------   ------------   ------------
                    /           | 
                ------------   ------------
                | Instance |   | Instance |
                ------------   ------------

Packet storage

Packets are stored (either during reception or in transmission) as aggregates called packets buffers. A packets buffer can be imagined as a contiguous buffer containing a sequence of packet headers and packet data, as shown in the figure below. The beginning of each packet header is aligned on a 64bit boundary. Extra bytes (0-7 bytes) of padding are added at the end of each packet to preserve such header alignment. The macro TC_ALIGN_USHORT_TO_64BIT can be used to align the packet data size to a 64 bit quantity. Packet headers already have a size multiple of 64bit.

            -------------------------------------------------------------------
            | Header | Data    |P| Header | Data | Header | Data          | P |
            -------------------------------------------------------------------
                            
            |         \     
            |          \    
            |           \         
            |            \        
            |             \       
            |              \      
            |               \     
            |                \    
                                  
            -------------------   
            | Length          |   
            | CapturedLength  |
            | Timestamp       |
            | Flags           |
            -------------------

The header has a fixed size, and it's an instance of the TC_PACKET_HEADER structure.

Two methods are available for accessing the packets inside a packet buffer:

Note:
  • The contiguous buffer is actually an abstraction of the internal structure of the packets buffer data structure. The actual internal implementation of the packets buffer is not documented and it's subject to change without any notice.
  • The suggested method to access the packets is by using the TcPacketsBufferQueryNextPacket. Accessing the packets manually with TcPacketsBufferGetBuffer can incur in a performance penalty due to additional memory copies involved in the operation. Also, great care should be taken in seeking through the packets because of the 64bit alignment requirement.
  • There's no guarantee that the pointers to the packets returned by TcPacketsBufferQueryNextPacket are pointers within the buffer returned by TcPacketsBufferGetBuffer.

TurboCap API documentation. Copyright (c) 2007-2008 CACE Technologies. All rights reserved.