mOS API description
Data Structures | Macros | Typedefs | Enumerations | Functions
mtcp_api.h File Reference
#include <stdint.h>
#include <netinet/in.h>
#include <sys/uio.h>
Include dependency graph for mtcp_api.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mtcp_context
 mTCP context More...
 
struct  mtcp_conf
 
struct  app_context
 
struct  app_ops
 

Macros

#define UNUSED(x)   (void)x
 
#define INPORT_ANY   (uint16_t)0
 
#define APP_NAME_LEN   40
 Maximum length of application name. More...
 
#define MOS_APP   20
 Maximum concurrently runable application. More...
 
#define MOS_APP_ARGC   20
 

Typedefs

typedef unsigned char byte
 
typedef struct mtcp_contextmctx_t
 
typedef void(* mtcp_sighandler_t) (int)
 mTCP signal handler type More...
 

Enumerations

enum  socket_type {
  MOS_SOCK_UNUSED, MOS_SOCK_STREAM_LISTEN, MOS_SOCK_PROXY_LISTEN, MOS_SOCK_MONITOR_STREAM,
  MOS_SOCK_STREAM, MOS_SOCK_PROXY, MOS_SOCK_MONITOR_STREAM_ACTIVE, MOS_SOCK_MONITOR_RAW,
  MOS_SOCK_EPOLL, MOS_SOCK_PIPE
}
 Socket types. More...
 

Functions

int mtcp_init (const char *config_file)
 Initialize mOS context with parameters mentioned in the config file. More...
 
int mtcp_destroy ()
 Destroy the global mOS context. More...
 
int mtcp_getconf (struct mtcp_conf *conf)
 Load current mtcp configuration in *conf. More...
 
int mtcp_setconf (const struct mtcp_conf *conf)
 Update mOS base with parameters mentioned in *conf. More...
 
int mtcp_core_affinitize (int cpu)
 Bind a thread to a specific CPU core. More...
 
mctx_t mtcp_create_context (int cpu)
 Create mOS/mtcp context thread based on the parameters passed by mtcp_init() & mtcp_setconf() functions. More...
 
int mtcp_destroy_context (mctx_t mctx)
 Destory mtcp context that was created by mOS/mTCP thread. More...
 
mtcp_sighandler_t mtcp_register_signal (int signum, mtcp_sighandler_t handler)
 Register signal handler (mtcp_sighandler_t handler ) for int signum. More...
 
int mtcp_pipe (mctx_t mctx, int pipeid[2])
 Create pipe. More...
 
int mtcp_getsockopt (mctx_t mctx, int sock, int level, int optname, void *optval, socklen_t *optlen)
 Get socket options. More...
 
int mtcp_setsockopt (mctx_t mctx, int sock, int level, int optname, const void *optval, socklen_t optlen)
 Set socket options. More...
 
int mtcp_setsock_nonblock (mctx_t mctx, int sock)
 Set socket as nonblock. More...
 
int mtcp_ioctl (mctx_t mctx, int sock, int request, void *argp)
 Control socket. More...
 
int mtcp_socket (mctx_t mctx, int domain, int type, int protocol)
 Create a socket. More...
 
int mtcp_bind (mctx_t mctx, int sock, const struct sockaddr *addr, socklen_t addrlen)
 Bind a socket, same as bind() More...
 
int mtcp_listen (mctx_t mctx, int sock, int backlog)
 Listen a listening socket, same as listen() More...
 
int mtcp_accept (mctx_t mctx, int sock, struct sockaddr *addr, socklen_t *addrlen)
 Accept new flow, same as accept() More...
 
int mtcp_init_rss (mctx_t mctx, in_addr_t saddr_base, int num_addr, in_addr_t daddr, in_addr_t dport)
 Initialize RSS pool for decide appropriate port numbers. More...
 
int mtcp_connect (mctx_t mctx, int sock, const struct sockaddr *addr, socklen_t addrlen)
 Connect new flow, same as connect() More...
 
int mtcp_close (mctx_t mctx, int sock)
 Close flow, same as close() More...
 
int mtcp_abort (mctx_t mctx, int sock)
 Abort flow by sending RST. More...
 
ssize_t mtcp_read (mctx_t mctx, int sock, char *buf, size_t len)
 Read byte stream from flow, same as read() More...
 
ssize_t mtcp_readv (mctx_t mctx, int sock, struct iovec *iov, int numIOV)
 Read byte stream from flow in vector, same as readv() More...
 
ssize_t mtcp_write (mctx_t mctx, int sock, char *buf, size_t len)
 Write byte stream to flow, same as write() More...
 
ssize_t mtcp_writev (mctx_t mctx, int sock, struct iovec *iov, int numIOV)
 Write byte stream to flow in vector, same as writev() More...
 
uint32_t mtcp_get_connection_cnt (mctx_t mctx)
 Get concurrent flow count of the underlying mtcp manager context (per-thread) More...
 

Macro Definition Documentation

#define APP_NAME_LEN   40

Maximum length of application name.

#define INPORT_ANY   (uint16_t)0
#define MOS_APP   20

Maximum concurrently runable application.

#define MOS_APP_ARGC   20
#define UNUSED (   x)    (void)x

Typedef Documentation

typedef unsigned char byte
typedef struct mtcp_context* mctx_t
typedef void(* mtcp_sighandler_t) (int)

mTCP signal handler type

Enumeration Type Documentation

Socket types.

Enumerator
MOS_SOCK_UNUSED 

unused

MOS_SOCK_STREAM_LISTEN 

regular mTCP connection listen socket

MOS_SOCK_PROXY_LISTEN 

MOS proxy socket listening socket.

MOS_SOCK_MONITOR_STREAM 

MOS monitor socket listening socket.

MOS_SOCK_STREAM 

regular mTCP connection socket

MOS_SOCK_PROXY 

MOS proxy socket.

MOS_SOCK_MONITOR_STREAM_ACTIVE 

MOS monitor socket.

MOS_SOCK_MONITOR_RAW 

MOS monitor socket (raw, stateless)

MOS_SOCK_EPOLL 
MOS_SOCK_PIPE 

Function Documentation

int mtcp_abort ( mctx_t  mctx,
int  sock 
)

Abort flow by sending RST.

Returns
Zero on success, -1 on error

Different from mtcp_close() which processes 4way handshake by FIN

int mtcp_accept ( mctx_t  mctx,
int  sock,
struct sockaddr *  addr,
socklen_t *  addrlen 
)

Accept new flow, same as accept()

Parameters
[in]mctxmtcp context
[in]socksocket id for MOS_SOCK_STREAM
[in]addraddress of the peer host(s)
[in]addrlenlength of addr
Returns
Zero on success, -1 on error
int mtcp_bind ( mctx_t  mctx,
int  sock,
const struct sockaddr *  addr,
socklen_t  addrlen 
)

Bind a socket, same as bind()

Returns
Zero on success, -1 on error
int mtcp_close ( mctx_t  mctx,
int  sock 
)

Close flow, same as close()

Returns
Zero on success, -1 on error
int mtcp_connect ( mctx_t  mctx,
int  sock,
const struct sockaddr *  addr,
socklen_t  addrlen 
)

Connect new flow, same as connect()

Returns
Zero on success, -1 on error
int mtcp_core_affinitize ( int  cpu)

Bind a thread to a specific CPU core.

Parameters
[in]cpuCPU ID
Returns
0 on success, -1 on error
mctx_t mtcp_create_context ( int  cpu)

Create mOS/mtcp context thread based on the parameters passed by mtcp_init() & mtcp_setconf() functions.

Parameters
[in]cpuCore id to affinitize new mtcp thread
Returns
mtcp context, NULL on error
int mtcp_destroy ( )

Destroy the global mOS context.

Returns
0 on success, -1 on error
int mtcp_destroy_context ( mctx_t  mctx)

Destory mtcp context that was created by mOS/mTCP thread.

Parameters
[in]mctxmtcp context
Returns
0 on success, -1 on error
uint32_t mtcp_get_connection_cnt ( mctx_t  mctx)

Get concurrent flow count of the underlying mtcp manager context (per-thread)

Parameters
[in]mctxmtcp context
Returns
concurrent flow count
int mtcp_getconf ( struct mtcp_conf conf)

Load current mtcp configuration in *conf.

Parameters
[out]confconfigurations
Returns
0 on success, -1 on error
int mtcp_getsockopt ( mctx_t  mctx,
int  sock,
int  level,
int  optname,
void *  optval,
socklen_t *  optlen 
)

Get socket options.

  1. MOS_TCP_STATE_CLI and MOS_TCP_STATE_SVR
    Returns a TCP state variable. This socket option is read-only.

  2. MOS_INFO_CLIBUF and MOS_INFO_SVRBUF
    Returns a structured information for upstream and downstream TCP buffer. The argument is a tcp_buf_info structure. This socket option is read-only.

  3. MOS_FRAGINFO_CLIBUF and MOS_FRAGINFO_SVRBUF
    Returns a TCP fragment buffer list information of TCP ring buffer. The argument is an array of tcp_ring_fragment structure, including the first contiguous data in the ring buffer. If there is no data in the TCP ring buffer, optval will be NULL. This socket option is read-only. For this option, note that optval represents the number of object entries that are allocated to read (input) and have been read (output).

Parameters
[in]mctxmtcp context
[in]socksocket id
[in]levelSOL_MONSOCKET
[in]optnamevariable
[out]optvalvalue of getting option
[out]optlenlength of getting option
Returns
Zero on success, -1 on error
int mtcp_init ( const char *  config_file)

Initialize mOS context with parameters mentioned in the config file.

Parameters
[in]config_filelocation of config file
Returns
0 on success, -1 on error

Setting dpdk devices, interface, load configuration from config file, routing table, arp table, etc.

int mtcp_init_rss ( mctx_t  mctx,
in_addr_t  saddr_base,
int  num_addr,
in_addr_t  daddr,
in_addr_t  dport 
)

Initialize RSS pool for decide appropriate port numbers.

Parameters
[in]mctxmtcp context
[in]saddr_basesource IP address base
[in]num_addrnumber of source IP address to use
[in]daddrdestination IP address
[in]dportdestination port number
Returns
Zero on success, -1 on error

w.r.t source IP addr, destination IP addr, destination port

int mtcp_ioctl ( mctx_t  mctx,
int  sock,
int  request,
void *  argp 
)

Control socket.

Parameters
[in]mctxmtcp context
[in]socksocket id
[in]requestrequested operation
[in,out]argppointer to argument
Returns
Zero on success, -1 on error
Operations Description
FIONREAD number of data bytes in receive buffer
FIONBIO for non-blocking I/O
int mtcp_listen ( mctx_t  mctx,
int  sock,
int  backlog 
)

Listen a listening socket, same as listen()

Returns
Zero on success, -1 on error

Only MOS_SOCK_LISTENER, MOS_SOCK_PROXY are allowed

int mtcp_pipe ( mctx_t  mctx,
int  pipeid[2] 
)

Create pipe.

Parameters
[in]mctxmtcp context
[out]pipeidcreated pipe
Returns
0 on success, -1 on error
ssize_t mtcp_read ( mctx_t  mctx,
int  sock,
char *  buf,
size_t  len 
)

Read byte stream from flow, same as read()

Returns
number of bytes read on success, -1 on error
ssize_t mtcp_readv ( mctx_t  mctx,
int  sock,
struct iovec *  iov,
int  numIOV 
)

Read byte stream from flow in vector, same as readv()

Returns
number of bytes read on success, -1 on error
mtcp_sighandler_t mtcp_register_signal ( int  signum,
mtcp_sighandler_t  handler 
)

Register signal handler (mtcp_sighandler_t handler ) for int signum.

Parameters
[in]signumSignal number to handle
[in]handlerHandler function
Returns
Same handler as input
int mtcp_setconf ( const struct mtcp_conf conf)

Update mOS base with parameters mentioned in *conf.

Parameters
[in]confconfigurations to set
Returns
0 on success, -1 on error
int mtcp_setsock_nonblock ( mctx_t  mctx,
int  sock 
)

Set socket as nonblock.

Parameters
[in]mctxmtcp context
[in]socksocket id
Returns
Zero on success, -1 on error

DEPRECATED

int mtcp_setsockopt ( mctx_t  mctx,
int  sock,
int  level,
int  optname,
const void *  optval,
socklen_t  optlen 
)

Set socket options.

  1. MOS_CLIBUF and MOS_SVRBUF
    Resize tcp ring buffer. Putting 0 disables tcp ring buffer. Takes integer as argument.

  2. MOS_FRAG_CLIBUF and MOS_FRAG_SVRBUF
    This version is `suppressed' at the moment (works but not advertised for the sake of simplicity). Sets the metadata tracking range to the specified value.

  3. MOS_STOP_MON
    Stop the monitoring for the specific side (passed via optval)
Parameters
[in]mctxmtcp context
[in]socksocket id
[in]levelSOL_MONSOCKET
[in]optnamevariable
[in]optvalvalue of setting option
[in]optlenlength of setting option
Returns
Zero on success, -1 on error
int mtcp_socket ( mctx_t  mctx,
int  domain,
int  type,
int  protocol 
)

Create a socket.

Parameters
[in]mctxmtcp context
[in]domainAF_INET, Not used
[in]typeAny of the following keyword
  • MOS_SOCK_STREAM (End TCP)
  • MOS_SOCK_MONITOR_RAW (Packet-level monitor)
  • MOS_SOCK_MONITOR_STREAM (Flow-level monitor) (MOS_SOCK_PROXY: To be supported)
[in]protocolNULL, Not used
Returns
Zero on success, -1 on error
ssize_t mtcp_write ( mctx_t  mctx,
int  sock,
char *  buf,
size_t  len 
)

Write byte stream to flow, same as write()

Returns
number of bytes write on success, -1 on error
ssize_t mtcp_writev ( mctx_t  mctx,
int  sock,
struct iovec *  iov,
int  numIOV 
)

Write byte stream to flow in vector, same as writev()

Returns
number of bytes write on success, -1 on error