RIOT's TCP implementation for the GNRC network stack. More...

Detailed Description

RIOT's TCP implementation for the GNRC network stack.

Modules

 GNRC TCP compile configurations
 

Calculating RTO

To calculate retransmission timeout (RTO), Round Trip Time (RTT) needs to be taken into account.
 

Files

file  config.h
 GNRC TCP configuration.
 
file  tcb.h
 GNRC TCP transmission control block (TCB)
 
file  tcp.h
 GNRC TCP API.
 
file  gnrc_tcp_common.h
 Internally used defines, macros and variable declarations.
 
file  gnrc_tcp_eventloop.h
 TCP event loop declarations.
 
file  gnrc_tcp_fsm.h
 TCP finite state maschine declarations.
 
file  gnrc_tcp_option.h
 TCP option handling declarations.
 
file  gnrc_tcp_pkt.h
 TCP packet handling declarations.
 
file  gnrc_tcp_rcvbuf.h
 Functions for allocating and freeing the receive buffer.
 

Data Structures

struct  gnrc_tcp_ep_t
 Address information for a single TCP connection endpoint. More...
 

Macros

#define GNRC_TCP_NO_TIMEOUT   (UINT32_MAX)
 Special timeout value representing no timeout.
 

Functions

int gnrc_tcp_ep_init (gnrc_tcp_ep_t *ep, int family, const uint8_t *addr, size_t addr_size, uint16_t port, uint16_t netif)
 Initialize TCP connection endpoint. More...
 
int gnrc_tcp_ep_from_str (gnrc_tcp_ep_t *ep, const char *str)
 Construct TCP connection endpoint from string. More...
 
int gnrc_tcp_init (void)
 Initialize TCP. More...
 
void gnrc_tcp_tcb_init (gnrc_tcp_tcb_t *tcb)
 Initialize Transmission Control Block (TCB) More...
 
void gnrc_tcp_tcb_queue_init (gnrc_tcp_tcb_queue_t *queue)
 Initialize Transmission Control Block (TCB) queue. More...
 
int gnrc_tcp_open (gnrc_tcp_tcb_t *tcb, const gnrc_tcp_ep_t *remote, uint16_t local_port)
 Opens a connection. More...
 
int gnrc_tcp_listen (gnrc_tcp_tcb_queue_t *queue, gnrc_tcp_tcb_t *tcbs, size_t tcbs_len, const gnrc_tcp_ep_t *local)
 Configures a sequence of TCBs to wait for incoming connections. More...
 
int gnrc_tcp_accept (gnrc_tcp_tcb_queue_t *queue, gnrc_tcp_tcb_t **tcb, const uint32_t user_timeout_duration_ms)
 Accept TCP connection from listening queue. More...
 
ssize_t gnrc_tcp_send (gnrc_tcp_tcb_t *tcb, const void *data, const size_t len, const uint32_t user_timeout_duration_ms)
 Transmit data to connected peer. More...
 
ssize_t gnrc_tcp_recv (gnrc_tcp_tcb_t *tcb, void *data, const size_t max_len, const uint32_t user_timeout_duration_ms)
 Receive Data from the peer. More...
 
void gnrc_tcp_close (gnrc_tcp_tcb_t *tcb)
 Close a TCP connection. More...
 
void gnrc_tcp_abort (gnrc_tcp_tcb_t *tcb)
 Abort a TCP connection. More...
 
void gnrc_tcp_stop_listen (gnrc_tcp_tcb_queue_t *queue)
 Close connections and stop listening on TCB queue. More...
 
int gnrc_tcp_get_local (gnrc_tcp_tcb_t *tcb, gnrc_tcp_ep_t *ep)
 Get the local end point of a connected TCB. More...
 
int gnrc_tcp_get_remote (gnrc_tcp_tcb_t *tcb, gnrc_tcp_ep_t *ep)
 Get the remote end point of a connected TCB. More...
 
int gnrc_tcp_queue_get_local (gnrc_tcp_tcb_queue_t *queue, gnrc_tcp_ep_t *ep)
 Gets the local end point of a TCB queue. More...
 
int gnrc_tcp_calc_csum (const gnrc_pktsnip_t *hdr, const gnrc_pktsnip_t *pseudo_hdr)
 Calculate and set checksum in TCP header. More...
 
gnrc_pktsnip_tgnrc_tcp_hdr_build (gnrc_pktsnip_t *payload, uint16_t src, uint16_t dst)
 Adds a TCP header to a given payload. More...
 

Function Documentation

◆ gnrc_tcp_abort()

void gnrc_tcp_abort ( gnrc_tcp_tcb_t tcb)

Abort a TCP connection.

Precondition
gnrc_tcp_tcb_init() must have been successfully called.
tcb must not be NULL.
Parameters
[in,out]tcbTCB holding the connection information.

◆ gnrc_tcp_accept()

int gnrc_tcp_accept ( gnrc_tcp_tcb_queue_t queue,
gnrc_tcp_tcb_t **  tcb,
const uint32_t  user_timeout_duration_ms 
)

Accept TCP connection from listening queue.

Precondition
queue must not be NULL
tcb must not be NULL
Note
Function blocks if user_timeout_duration_us is not zero.
Parameters
[in]queueListening queue to accept connection from.
[out]tcbPointer to TCB associated with a established connection.
[in]user_timeout_duration_msUser specified timeout in milliseconds. If GNRC_TCP_NO_TIMEOUT the function blocks until a connection was established or an error occurred.
Returns
0 on success.
-ENOMEM if all connection in queue were already accepted.
-EINVAL if listen was never called on queue.
-EAGAIN if user_timeout_duration_ms was 0 and no connection is ready to accept.
-ETIMEDOUT if user_timeout_duration_ms was not 0 and no connection could be established.

◆ gnrc_tcp_calc_csum()

int gnrc_tcp_calc_csum ( const gnrc_pktsnip_t hdr,
const gnrc_pktsnip_t pseudo_hdr 
)

Calculate and set checksum in TCP header.

Parameters
[in]hdrGnrc_pktsnip that contains TCP header.
[in]pseudo_hdrGnrc_pktsnip that contains network layer header.
Returns
0 on success.
-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.

◆ gnrc_tcp_close()

void gnrc_tcp_close ( gnrc_tcp_tcb_t tcb)

Close a TCP connection.

Precondition
gnrc_tcp_tcb_init() must have been successfully called.
tcb must not be NULL.
Parameters
[in,out]tcbTCB holding the connection information.

◆ gnrc_tcp_ep_from_str()

int gnrc_tcp_ep_from_str ( gnrc_tcp_ep_t ep,
const char *  str 
)

Construct TCP connection endpoint from string.

Note
This function expects str in the IPv6 "URL" notation. The following strings specify a valid endpoint:
  • [fe80::0a00:27ff:fe9f:7a5b%5]:8080 (with Port and Interface)
  • [2001::0200:f8ff:fe21:67cf]:8080 (with Port)
  • [2001::0200:f8ff:fe21:67cf] (addr only)
Parameters
[in,out]epEndpoint to initialize.
[in]strString containing IPv6-Address to parse.
Returns
0 on success.
-EINVAL if parsing of str failed.

◆ gnrc_tcp_ep_init()

int gnrc_tcp_ep_init ( gnrc_tcp_ep_t ep,
int  family,
const uint8_t *  addr,
size_t  addr_size,
uint16_t  port,
uint16_t  netif 
)

Initialize TCP connection endpoint.

Parameters
[in,out]epEndpoint to initialize.
[in]familyAddress family of addr.
[in]addrAddress for endpoint.
[in]addr_sizeSize of addr.
[in]portPort number for endpoint.
[in]netifNetwork interface to use.
Returns
0 on success.
-EAFNOSUPPORT if address_family is not supported.
-EINVAL if addr_size does not match family.

◆ gnrc_tcp_get_local()

int gnrc_tcp_get_local ( gnrc_tcp_tcb_t tcb,
gnrc_tcp_ep_t ep 
)

Get the local end point of a connected TCB.

Precondition
tcb must not be NULL
ep must not be NULL
Parameters
[in]tcbTCB holding the connection information.
[out]epThe local end point.
Returns
0 on success.
-EADDRNOTAVAIL, when tcb in not in a connected state.

◆ gnrc_tcp_get_remote()

int gnrc_tcp_get_remote ( gnrc_tcp_tcb_t tcb,
gnrc_tcp_ep_t ep 
)

Get the remote end point of a connected TCB.

Precondition
tcb must not be NULL
ep must not be NULL
Parameters
[in]tcbTCB holding the connection information.
[out]epThe remote end point.
Returns
0 on success.
-ENOTCONN, when tcb in not in a connected state.

◆ gnrc_tcp_hdr_build()

gnrc_pktsnip_t* gnrc_tcp_hdr_build ( gnrc_pktsnip_t payload,
uint16_t  src,
uint16_t  dst 
)

Adds a TCP header to a given payload.

Parameters
[in]payloadPayload that follows the TCP header.
[in]srcSource port number.
[in]dstDestination port number.
Returns
Not NULL on success.
NULL if TCP header was not allocated.

◆ gnrc_tcp_init()

int gnrc_tcp_init ( void  )

Initialize TCP.

Returns
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.

◆ gnrc_tcp_listen()

int gnrc_tcp_listen ( gnrc_tcp_tcb_queue_t queue,
gnrc_tcp_tcb_t tcbs,
size_t  tcbs_len,
const gnrc_tcp_ep_t local 
)

Configures a sequence of TCBs to wait for incoming connections.

Precondition
All TCBs behind tcbs must have been initialized via gnrc_tcp_tcb_init().
queue must not be NULL.
tcbs must not be NULL.
tcbs_len must be greater 0.
local len must be NULL.
local->port must not be 0.
Parameters
[in,out]queueListening queue for incoming connections.
[in]tcbsTCBs associated with queue.
[in]tcbs_lenNumber of TCBs behind tcbs.
[in]localEndpoint specifying address and port to listen on.
Returns
0 on success.
-EAFNOSUPPORT given address family in local is not supported.
-EINVAL address_family in tcbs and local do not match.
-EISCONN a TCB in tcbs is already connected.
-ENOMEM all available receive buffers are in use. Increase GNRC_TCP_RCV_BUFFERS.

◆ gnrc_tcp_open()

int gnrc_tcp_open ( gnrc_tcp_tcb_t tcb,
const gnrc_tcp_ep_t remote,
uint16_t  local_port 
)

Opens a connection.

Precondition
gnrc_tcp_tcb_init() must have been successfully called.
tcb must not be NULL
remote must not be NULL.
remote->port must not be 0.
Note
Blocks until a connection was established or an error occurred.
Parameters
[in,out]tcbTCB for this connection.
[in]remoteRemote endpoint to connect to.
[in]local_portIf zero or PORT_UNSPEC, the connections source port is randomly selected. If local_port is non-zero it is used as source port.
Returns
0 on success.
-EAFNOSUPPORT if remote address_family is not supported.
-EINVAL if remote and tcb address_family do not match or target_addr is invalid.
-EISCONN if tcb is already connected.
-ENOMEM if there are no receive buffer left to use for tcb.
-EADDRINUSE if local_port is already in use.
-ETIMEDOUT if the connection attempt timed out.
-ECONNREFUSED if the connection attempt was reset by the peer.

◆ gnrc_tcp_queue_get_local()

int gnrc_tcp_queue_get_local ( gnrc_tcp_tcb_queue_t queue,
gnrc_tcp_ep_t ep 
)

Gets the local end point of a TCB queue.

Precondition
queue must not be NULL
ep must not be NULL
Parameters
[in]queueTCB queue to stop listening
[out]epThe local end point.
Returns
0 on success.
-EADDRNOTAVAIL, when queue has no local end point.

◆ gnrc_tcp_recv()

ssize_t gnrc_tcp_recv ( gnrc_tcp_tcb_t tcb,
void *  data,
const size_t  max_len,
const uint32_t  user_timeout_duration_ms 
)

Receive Data from the peer.

Precondition
gnrc_tcp_tcb_init() must have been successfully called.
tcb must not be NULL.
data must not be NULL.
Note
Function blocks if user_timeout_duration_us is not zero.
Parameters
[in,out]tcbTCB holding the connection information.
[out]dataPointer to the buffer where the received data should be copied into.
[in]max_lenMaximum amount to bytes that should be read into data.
[in]user_timeout_duration_msTimeout for receive in milliseconds. 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_ms milliseconds passed. If GNRC_TCP_NO_TIMEOUT, causing the function to block until some data was available or an error occurred.
Returns
The number of bytes read into data.
0, if the connection is closing and no further data can be read or max_len was 0.
-ENOTCONN if connection is not established.
-EAGAIN if user_timeout_duration_us is zero and no data is available.
-ECONNRESET if connection was reset by the peer.
-ECONNABORTED if the connection was aborted.
-ETIMEDOUT if user_timeout_duration_ms expired.

◆ gnrc_tcp_send()

ssize_t gnrc_tcp_send ( gnrc_tcp_tcb_t tcb,
const void *  data,
const size_t  len,
const uint32_t  user_timeout_duration_ms 
)

Transmit data to connected peer.

Precondition
gnrc_tcp_tcb_init() must have been successfully called.
tcb must not be NULL.
data must not be NULL.
Note
Blocks until up to len bytes were transmitted or an error occurred.
Parameters
[in,out]tcbTCB holding the connection information.
[in]dataPointer to the data that should be transmitted.
[in]lenNumber of bytes that should be transmitted.
[in]user_timeout_duration_msIf not zero and there was not data transmitted the function returns after user_timeout_duration_ms. If zero, no timeout will be triggered. If GNRC_TCP_NO_TIMEOUT the timeout is disabled causing the function to block until some data was transmitted or and error occurred.
Returns
The number of successfully transmitted bytes.
-ENOTCONN if connection is not established.
-ECONNRESET if connection was reset by the peer.
-ECONNABORTED if the connection was aborted.
-ETIMEDOUT if user_timeout_duration_ms expired.

◆ gnrc_tcp_stop_listen()

void gnrc_tcp_stop_listen ( gnrc_tcp_tcb_queue_t queue)

Close connections and stop listening on TCB queue.

Precondition
queue must not be NULL
Note
: Blocks until all currently opened connections maintained by queue were closed.
Parameters
[in,out]queueTCB queue to stop listening

◆ gnrc_tcp_tcb_init()

void gnrc_tcp_tcb_init ( gnrc_tcp_tcb_t tcb)

Initialize Transmission Control Block (TCB)

Precondition
tcb must not be NULL.
Parameters
[in,out]tcbTCB that should be initialized.

◆ gnrc_tcp_tcb_queue_init()

void gnrc_tcp_tcb_queue_init ( gnrc_tcp_tcb_queue_t queue)

Initialize Transmission Control Block (TCB) queue.

Precondition
queue must not be NULL.
Parameters
[in,out]queueTCB queue to initialize.