TCP

RIOT’s TCP implementation for the GNRC network stack.

STATUS_PASSIVE

TCB status flags. 

1
(1 << 0)
STATUS_ALLOW_ANY_ADDR
1
(1 << 1)
STATUS_NOTIFY_USER
1
(1 << 2)
STATUS_WAIT_FOR_MSG
1
(1 << 3)
TCP_EVENTLOOP_MSG_QUEUE_SIZE

Defines for “eventloop” thread settings. 

1
(8U)
TCP_EVENTLOOP_PRIO
1
(THREAD_PRIORITY_MAIN - 2U)
TCP_EVENTLOOP_STACK_SIZE
1
(THREAD_STACKSIZE_DEFAULT)
MSK_FIN

Bitmasks for control bit field handling. 

1
(0x0001)
MSK_SYN
1
(0x0002)
MSK_RST
1
(0x0004)
MSK_PSH
1
(0x0008)
MSK_ACK
1
(0x0010)
MSK_URG
1
(0x0020)
MSK_FIN_ACK
1
(0x0011)
MSK_SYN_ACK
1
(0x0012)
MSK_RST_ACK
1
(0x0014)
MSK_SYN_FIN_ACK
1
(0x0013)
MSK_FIN_ACK_PSH
1
(0x0019)
MSK_CTL
1
(0x003F)
MSK_OFFSET
1
(0xF000)
MSG_TYPE_CONNECTION_TIMEOUT

Message types for GNRC TCPs internal message passing. 

1
(GNRC_NETAPI_MSG_TYPE_ACK + 101)
MSG_TYPE_PROBE_TIMEOUT
1
(GNRC_NETAPI_MSG_TYPE_ACK + 102)
MSG_TYPE_USER_SPEC_TIMEOUT
1
(GNRC_NETAPI_MSG_TYPE_ACK + 103)
MSG_TYPE_RETRANSMISSION
1
(GNRC_NETAPI_MSG_TYPE_ACK + 104)
MSG_TYPE_TIMEWAIT
1
(GNRC_NETAPI_MSG_TYPE_ACK + 105)
MSG_TYPE_NOTIFY_USER
1
(GNRC_NETAPI_MSG_TYPE_ACK + 106)
LSS_32_BIT( x, y)

Overflow tolerant comparision operators for sequence and acknowledgement number comparison. 

1
(((int32_t) (x)) - ((int32_t) (y)) <  0)
LEQ_32_BIT( x, y)
1
(((int32_t) (x)) - ((int32_t) (y)) <= 0)
GRT_32_BIT( x, y)
1
(!LEQ_32_BIT(x, y))
GEQ_32_BIT( x, y)
1
(!LSS_32_BOT(x, y))
enum fsm_state_t
FSM_STATE_CLOSED = 0
FSM_STATE_LISTEN
FSM_STATE_SYN_SENT
FSM_STATE_SYN_RCVD
FSM_STATE_ESTABLISHED
FSM_STATE_CLOSE_WAIT
FSM_STATE_LAST_ACK
FSM_STATE_FIN_WAIT_1
FSM_STATE_FIN_WAIT_2
FSM_STATE_CLOSING
FSM_STATE_TIME_WAIT
enum fsm_event_t
FSM_EVENT_CALL_OPEN
FSM_EVENT_CALL_SEND
FSM_EVENT_CALL_RECV
FSM_EVENT_CALL_CLOSE
FSM_EVENT_CALL_ABORT
FSM_EVENT_RCVD_PKT
FSM_EVENT_TIMEOUT_TIMEWAIT
FSM_EVENT_TIMEOUT_RETRANSMIT
FSM_EVENT_TIMEOUT_CONNECTION
FSM_EVENT_SEND_PROBE
FSM_EVENT_CLEAR_RETRANSMIT
struct _transmission_control_block gnrc_tcp_tcb_t

Transmission control block of GNRC TCP.

struct rcvbuf_entry rcvbuf_entry_t

Receive buffer entry.

struct rcvbuf rcvbuf_t

Stuct holding receive buffers.

kernel_types.h::kernel_pid_t gnrc_tcp_pid

PID of GNRC TCP event handling thread.

tcb.h::gnrc_tcp_tcb_t * _list_tcb_head

Head of linked TCB list.

mutex_t _list_tcb_lock

Mutex to protect TCB list.

int gnrc_tcp_init(void)

Initialize TCP.

Return values

  • PID of TCP thread on success -1 if TCB is already running. -EINVAL, if priority is greater than or equal SCHED_PRIO_LEVELS -EOVERFLOW, if there are too many threads running.
void gnrc_tcp_tcb_init(tcb.h::gnrc_tcp_tcb_t * tcb)

Initialize Transmission Control Block (TCB)

Parameters

tcb:TCB that should be initialized.

int gnrc_tcp_open_active(tcb.h::gnrc_tcp_tcb_t * tcb, uint8_t address_family, char * target_addr, uint16_t target_port, uint16_t local_port)

Opens a connection actively.

Note

Blocks until a connection has been established or an error occured.

Parameters

tcb:TCB holding the connection information.
address_family:Address family of target_addr.
target_addr:Pointer to target address.
target_port:Target port number.
local_port:If zero or PORT_UNSPEC, the connections source port is randomly chosen. If local_port is non-zero the local_port is used as source port.

Return values

  • Zero on success. -EAFNOSUPPORT if address_family is not supported. -EINVAL if address_family is not the same the address_family use by the TCB. or target_addr is invalid. -EISCONN if TCB is already in use. -ENOMEM if the receive buffer for the TCB could not be allocated. -EADDRINUSE if local_port is already used by another connection. -ETIMEDOUT if the connection could not be opened. -ECONNREFUSED if the connection was resetted by the peer.
int gnrc_tcp_open_passive(tcb.h::gnrc_tcp_tcb_t * tcb, uint8_t address_family, const char * local_addr, uint16_t local_port)

Opens a connection passively, by waiting for an incomming request.

Note

Blocks until a connection has been established (incomming connection request to local_port) or an error occured.

Parameters

tcb:TCB holding the connection information.
address_family:Address family of local_addr. If local_addr == NULL, address_family is ignored.
local_addr:If not NULL the connection is bound to local_addr. If NULL a connection request to all local ip addresses is valied.
local_port:Port number to listen on.

Return values

  • Zero on success. -EAFNOSUPPORT if local_addr != NULL and address_family is not supported. -EINVAL if address_family is not the same the address_family used in TCB. or target_addr is invalid. -EISCONN if TCB is already in use. -ENOMEM if the receive buffer for the TCB could not be allocated. Hint: Increase “GNRC_TCP_RCV_BUFFERS”.
msp430_types.h::ssize_t gnrc_tcp_send(tcb.h::gnrc_tcp_tcb_t * tcb, const void * data, const msp430_types.h::size_t len, const uint32_t user_timeout_duration_us)

Transmit data to connected peer.

Note

Blocks until up to len bytes were transmitted or an error occured.

Parameters

tcb:TCB holding the connection information.
data:Pointer to the data that should be transmitted.
len:Number of bytes that should be transmitted.
user_timeout_duration_us:
 If not zero and there was not data transmitted the function returns after user_timeout_duration_us. If zero, no timeout will be triggered.

Return values

  • The number of successfully transmitted bytes. -ENOTCONN if connection is not established. -ECONNRESET if connection was resetted by the peer. -ECONNABORTED if the connection was aborted. -ETIMEDOUT if user_timeout_duration_us expired.
msp430_types.h::ssize_t gnrc_tcp_recv(tcb.h::gnrc_tcp_tcb_t * tcb, void * data, const msp430_types.h::size_t max_len, const uint32_t user_timeout_duration_us)

Receive Data from the peer.

Note

Function blocks if user_timeout_duration_us is not zero.

Parameters

tcb:TCB holding the connection information.
data:Pointer to the buffer where the received data should be copied into.
max_len:Maximum amount to bytes that should be read into data.
user_timeout_duration_us:
 Timeout for receive in microseconds. If zero and no data is available, the function returns immediately. If not zero the function blocks until data is available or user_timeout_duration_us microseconds passed.

Return values

  • The number of bytes read into data. -ENOTCONN if connection is not established. -EAGAIN if user_timeout_duration_us is zero and no data is available. -ECONNRESET if connection was resetted by the peer. -ECONNABORTED if the connection was aborted. -ETIMEDOUT if user_timeout_duration_us expired.
void gnrc_tcp_close(tcb.h::gnrc_tcp_tcb_t * tcb)

Close a TCP connection.

Parameters

tcb:TCB holding the connection information.

void gnrc_tcp_abort(tcb.h::gnrc_tcp_tcb_t * tcb)

Abort a TCP connection.

Parameters

tcb:TCB holding the connection information.

int gnrc_tcp_calc_csum(const include/net/gnrc/pkt.h::gnrc_pktsnip_t * hdr, const include/net/gnrc/pkt.h::gnrc_pktsnip_t * pseudo_hdr)

Calculate and set checksum in TCP header.

Parameters

hdr:Gnrc_pktsnip that contains TCP header.
pseudo_hdr:Gnrc_pktsnip that contains network layer header.

Return values

  • Zero on succeed. -EFAULT if hdr or pseudo_hdr were NULL -EBADMSG if hdr is not of type GNRC_NETTYPE_TCP -ENOENT if pseudo_hdr protocol is unsupported.
include/net/gnrc/pkt.h::gnrc_pktsnip_t * gnrc_tcp_hdr_build(include/net/gnrc/pkt.h::gnrc_pktsnip_t * payload, uint16_t src, uint16_t dst)

Adds a TCP header to a given payload.

Parameters

payload:Payload that follows the TCP header.
src:Source port number.
dst:Destination port number.

Return values

  • Not NULL on success. NULL if TCP header was not allocated.
void * _event_loop(void * arg)

GNRC TCPs main processing thread.

Parameters

arg:Thread arguments (unused).

Return values

  • Never, its an endless loop
int _fsm(tcb.h::gnrc_tcp_tcb_t * tcb, fsm.h::fsm_event_t event, include/net/gnrc/pkt.h::gnrc_pktsnip_t * in_pkt, void * buf, msp430_types.h::size_t len)

TCP finite state maschine.

Parameters

tcb:TCB holding the connection information.
event:Current event that triggers FSM transition.
in_pkt:Incomming packet. Only not NULL in case of event RCVD_PKT.
buf:Buffer for send and receive functions.
len:Number of bytes to send or receive.

Return values

  • Zero on success Positive Number, number of bytes sent from or copied into buf. -ENOSYS if event is not implemented
uint32_t _option_build_mss(uint16_t mss)

Helper function to build the MSS option.

Parameters

mss:MSS value that should be set.

Return values

  • MSS option value.
uint16_t _option_build_offset_control(uint16_t nopts, uint16_t ctl)

Helper function to build the combined option and control flag field.

Parameters

nopts:Number of options.
ctl:Control flag field.

Return values

  • Bitfield with encoded control bits and number of options.
int _option_parse(tcb.h::gnrc_tcp_tcb_t * tcb, tcp_hdr_t * hdr)

Parses options of a given TCP header.

Parameters

tcb:TCB holding the connection information.
hdr:TCP header to be parsed.

Return values

  • Zero on success. Negative value on error.
int _pkt_build_reset_from_pkt(include/net/gnrc/pkt.h::gnrc_pktsnip_t ** out_pkt, include/net/gnrc/pkt.h::gnrc_pktsnip_t * in_pkt)

Build a reset packet from an incomming packet.

Note

This function builds a reset from an incomming packet in cases where the connection has not been established.

Parameters

out_pkt:Outgoing reset packet
in_pkt:Incomming packet

Return values

  • Zero on success -ENOMEM if pktbuf is full.
int _pkt_build(tcb.h::gnrc_tcp_tcb_t * tcb, include/net/gnrc/pkt.h::gnrc_pktsnip_t ** out_pkt, uint16_t * seq_con, const uint16_t ctl, const uint32_t seq_num, const uint32_t ack_num, void * payload, const msp430_types.h::size_t payload_len)

Build and allocate a TCB paket, TCB stores pointer to new paket.

Parameters

tcb:TCB holding the connection information.
out_pkt:Pointer to paket to build.
seq_con:Sequence number consumption of built packet.
ctl:Control bits to set in out_pkt.
seq_num:Sequence number of the new packet.
ack_num:Acknowledgment number of the new packet.
payload:Pointer to payload buffer.
payload_len:Payload size.

Return values

  • Zero on success. -ENOMEM if pktbuf is full.
int _pkt_send(tcb.h::gnrc_tcp_tcb_t * tcb, include/net/gnrc/pkt.h::gnrc_pktsnip_t * out_pkt, const uint16_t seq_con, const bool retransmit)

Sends packet to peer.

Parameters

tcb:TCB holding the connection information.
out_pkt:Pointer to paket to send.
seq_con:Sequence number consumption of the packet to send.
retransmit:Flag so mark that packet this is a retransmission.

Return values

  • Zero on success. -EINVAL if out_pkt was NULL.
int _pkt_chk_seq_num(const tcb.h::gnrc_tcp_tcb_t * tcb, const uint32_t seq_num, const uint32_t seg_len)

Verify sequence number.

Parameters

tcb:TCB holding the connection information.
seq_num:Sequence number from the segment.
seg_len:Length of a segments payload.

Return values

  • Zero if the sequence number is acceptable. Negative value if the sequence number is not acceptable.
uint32_t _pkt_get_seg_len(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt)

Extracts the length of a segment.

Parameters

pkt:Packet to calculate the segments length.

Return values

  • Segments length in bytes (== sequence number consumption).
uint32_t _pkt_get_pay_len(include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt)

Calculates a packets payload length.

Parameters

pkt:Packet to calculate payload length.

Return values

  • The packets payload length in bytes.
int _pkt_setup_retransmit(tcb.h::gnrc_tcp_tcb_t * tcb, include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt, const bool retransmit)

Adds a packet to the retransmission mechanism.

Parameters

tcb:TCB holding the connection information.
pkt:Packet to add to the retransmission mechanism.
retransmit:Flag used to indicate that pkt is a retransmit.

Return values

  • Zero on success. -ENOMEM if the retransmission queue is full. -EINVAL if pkt is null.
int _pkt_acknowledge(tcb.h::gnrc_tcp_tcb_t * tcb, const uint32_t ack)

Acknowledges and removes packet from the retransmission mechanism.

Parameters

tcb:TCB holding the connection information.
ack:Acknowldegment number used to acknowledge packets.

Return values

  • Zero on success. -ENODATA if there is nothing to acknowledge.
uint16_t _pkt_calc_csum(const include/net/gnrc/pkt.h::gnrc_pktsnip_t * hdr, const include/net/gnrc/pkt.h::gnrc_pktsnip_t * pseudo_hdr, const include/net/gnrc/pkt.h::gnrc_pktsnip_t * payload)

Calculates checksum over payload, TCP header and network layer header.

Parameters

hdr:Gnrc_pktsnip_t to TCP header.
pseudo_hdr:Gnrc_pktsnip_t to network layer header.
payload:Gnrc_pktsnip_t to payload.

Return values

  • Non-zero checksum if given network layer is supported. Zero if given network layer is not supported.
void _rcvbuf_init(void)

Initializes global receive buffer.

int _rcvbuf_get_buffer(tcb.h::gnrc_tcp_tcb_t * tcb)

Allocate receive buffer and assign it to TCB.

Parameters

tcb:TCB that aquires receive buffer.

Return values

  • Zero on success. -ENOMEM if all receive buffers are currently used.
void _rcvbuf_release_buffer(tcb.h::gnrc_tcp_tcb_t * tcb)

Release allocated receive buffer.

Parameters

tcb:TCB holding the receive buffer that should be released.

GNRC_TCP_CONNECTION_TIMEOUT_DURATION

Timeout duration for user calls. 

1
(120U * US_PER_SEC)

Default is 2 minutes.

GNRC_TCP_MSL

Maximum segment lifetime (MSL). 

1
(30U * US_PER_SEC)

Default is 30 seconds.

GNRC_TCP_MSS

Maximum Segement Size (MSS). 

1
(1220U)

If IPv6 is used. Get MSS = 1280 - IPv6 Hdr - TCP Hdr = 1220

GNRC_TCP_MSS_MULTIPLICATOR

MSS Multiplicator = Number of MSS sized packets stored in receive buffer. 

1
(1U)
GNRC_TCP_DEFAULT_WINDOW

Default receive window size. 

1
(GNRC_TCP_MSS * GNRC_TCP_MSS_MULTIPLICATOR)
GNRC_TCP_RCV_BUFFERS

Number of preallocated receive buffers. 

1
(1U)
GNRC_TCP_RCV_BUF_SIZE

Default receive buffer size. 

1
(GNRC_TCP_DEFAULT_WINDOW)
GNRC_TCP_RTO_LOWER_BOUND

Lower bound for RTO = 1 sec (see RFC 6298) 

1
(1U * US_PER_SEC)
GNRC_TCP_RTO_UPPER_BOUND

Upper bound for RTO = 60 sec (see RFC 6298) 

1
(60U * US_PER_SEC)
GNRC_TCP_RTO_GRANULARITY

Assumes clock granularity for TCP of 10 ms (see RFC 6298) 

1
(10U * MS_PER_SEC)
GNRC_TCP_RTO_A_DIV

Alpha value for RTO calculation, default is 1/8. 

1
(8U)
GNRC_TCP_RTO_B_DIV

Beta value for RTO calculation, default is 1/4. 

1
(4U)
GNRC_TCP_RTO_K

K value for RTO calculation, default is 4. 

1
(4U)
GNRC_TCP_PROBE_LOWER_BOUND

Lower bound for the duration between probes. 

1
(1U * US_PER_SEC)
GNRC_TCP_PROBE_UPPER_BOUND

Upper bound for the duration between probes. 

1
(60U * US_PER_SEC)
GNRC_TCP_TCB_MBOX_SIZE

Size of the TCB mbox. 

1
(8U)
PORT_UNSPEC

Port number unspecified. 

1
(0)

See also

https://www.ietf.org/rfc/rfc1700.txt

RTO_UNINITIALIZED

Define for marking that time measurement is uninitialized. 

1
(-1)
INSIDE_WND( l_ed, seq_num, r_ed)

Check if a given sequence number falls into receive window. 

1
(LEQ_32_BIT(l_ed, seq_num) && LSS_32_BIT(seq_num, r_ed))
GET_OFFSET( x)

Extract offset value from “offctl” field in TCP header. 

1
(((x) & MSK_OFFSET) >> 12)
struct _transmission_control_block

Transmission control block of GNRC TCP.

uint8_t address_family

Address Family of local_addr / peer_addr.

uint8_t local_addr()

Local IP address.

uint8_t peer_addr()

Peer IP address.

int8_t ll_iface

Link layer interface id to use.

uint16_t local_port

Local connections port number.

uint16_t peer_port

Peer connections port number.

uint8_t state

Connections state.

uint8_t status

A connections status flags.

uint32_t snd_una

Send unacknowledged.

uint32_t snd_nxt

Send next.

uint16_t snd_wnd

Send window.

uint32_t snd_wl1

SeqNo.

from last window update

uint32_t snd_wl2

AckNo.

from last window update

uint32_t rcv_nxt

Receive next.

uint16_t rcv_wnd

Receive window.

uint32_t iss

Initial sequence sumber.

uint32_t irs

Initial received sequence number.

uint16_t mss

The peers MSS.

uint32_t rtt_start

Timer value for rtt estimation.

int32_t rtt_var

Round trip time variance.

int32_t srtt

Smoothed round trip time.

int32_t rto

Retransmission timeout duration.

uint8_t retries

Number of retransmissions.

xtimer.h::xtimer_t tim_tout

Timer struct for timeouts.

msg_t msg_tout

Message, sent on timeouts.

include/net/gnrc/pkt.h::gnrc_pktsnip_t * pkt_retransmit

Pointer to packet in “retransmit queue”.

msg_t mbox_raw()

Msg queue for mbox.

mbox_t mbox

TCB mbox for synchronization.

uint8_t * rcv_buf_raw

Pointer to the receive buffer.

ringbuffer_t rcv_buf

Receive buffer data structure.

mutex_t fsm_lock

Mutex for FSM access synchronization.

mutex_t function_lock

Mutex for function call synchronization.

struct _transmission_control_block * next

Pointer next TCB.

struct rcvbuf_entry

Receive buffer entry.

uint8_t used

Flag: Is buffer in use?

uint8_t buffer()

Receive buffer storage.

struct rcvbuf

Stuct holding receive buffers.

mutex_t lock

Lock for allocation synchronization.

rcvbuf.h::rcvbuf_entry_t entries()

Maintained receive buffers.