1# F-Stack API Reference 2 3F-Stack (FF) is a high-performance network framework based on DPDK. 4 5FF API provides the standard Kqueue/Epoll interface, and a micro threading framework (SPP). 6 7In order to facilitate a variety of services to use F-Stack simpler and faster, F-Stack has been integrated with Nginx and Redis。 8 9## FF API 10 11The header file ff_api.h defines the following API, which should be used to replace the system calls when using F-Stack. 12 13### Initialize 14 15#### ff_init 16 17 int ff_init(const char *conf, int argc, char * const argv[]); 18 conf:Profile path 19 argv：-c <coremask>,the coremask parameters can cover the coremask in configuration file 20 21Initialize F-Stack，including DPDK/FreeBSD network stack, etc. 22 23#### ff_run 24 25 void ff_run(loop_func_t loop, void *arg); 26loop is a callback function，the service logic is implemented by the user, and called by each poll of F-Stack . 27 28### Control API 29 30#### ff_fcntl 31 32 int ff_fcntl(int fd, int cmd, ...); 33 34 fcntl() performs one of the operations described below on the open file descriptor fd. The operation is determined by cmd. 35more info see man fcntl. 36 37#### ff_sysctl 38 39 int ff_sysctl(const int *name, u_int namelen, void *oldp, size_t *oldlenp, 40 const void *newp, size_t newlen); 41 42 ff_sysctl is used to modify kernel parameters at runtime. 43However, it is supported only before F-Stack is started. 44 45#### ff_ioctl 46 47 int ff_ioctl(int fd, unsigned long request, ...); 48 49 The ioctl() function manipulates the underlying device parameters of special files. 50 more info see man ioctl. 51 52### Network API 53 54#### ff_socket 55 56 int ff_socket(int domain, int type, int protocol); 57 58 ff_socket creates an endpoint for communication and returns a file descriptor that refers to that endpoint. 59 more info see man socket. 60 61#### ff_setsockopt & ff_getsockopt 62 63 int ff_getsockopt(int s, int level, int optname, void *optval, 64 socklen_t *optlen); 65 int ff_setsockopt(int s, int level, int optname, const void *optval, 66 socklen_t optlen); 67 68 getsockopt() and setsockopt() manipulate options for the socket denoted by the file descriptor sockfd. 69 more info see man getsockopt and man setsockopt. 70 71#### ff_socketpair 72 73 int ff_socketpair(int domain, int type, int protocol, int *sv); 74 75 The socketpair() call creates an unnamed pair of connected sockets in the given domain in the specified type, and uses the optionally given protocol. 76 more info see man socketpair. 77 78#### Socket operation function 79 80 int ff_listen(int s, int backlog); 81 int ff_bind(int s, const struct linux_sockaddr *addr, socklen_t addrlen); 82 int ff_accept(int s, struct linux_sockaddr *addr, socklen_t *addrlen); 83 int ff_connect(int s, const struct linux_sockaddr *name, socklen_t namelen); 84 int ff_close(int fd); 85 int ff_shutdown(int s, int how); 86 87 Socket operation function, more info see Linux Programmer's Manual. 88 89#### ff_getpeername 90 91 int ff_getpeername(int s, struct linux_sockaddr *name, socklen_t *namelen); 92 93 ff_getpeername() returns the address of the peer connected to the socket sockfd, in the buffer pointed to by addr. 94 more info see man getpeername. 95 96#### ff_getsockname 97 98 int ff_getsockname(int s, struct linux_sockaddr *name, 99 socklen_t *namelen); 100 101 ff_getsockname() returns the current address to which the socket sockfd is bound, in the buffer pointed to by addr. 102 more info see man getsockname. 103 104#### ff\_read & ff\_readv 105 106 ssize_t ff_read(int d, void *buf, size_t nbytes); 107 ssize_t ff_readv(int fd, const struct iovec *iov, int iovcnt); 108 109 read() attempts to read up to count bytes from file descriptor fd into the buffer starting at buf. 110 more info see man read and man readv. 111 112#### ff\_write & ff\_writev 113 114 ssize_t ff_write(int fd, const void *buf, size_t nbytes); 115 ssize_t ff_writev(int fd, const struct iovec *iov, int iovcnt); 116 117 write() writes up to count bytes from the buffer pointed buf to the file referred to by the file descriptor fd. 118 more info see man write and man readv. 119 120#### ff\_send & ff\_sendto & ff\_sendmsg 121 122 ssize_t ff_send(int s, const void *buf, size_t len, int flags); 123 ssize_t ff_sendto(int s, const void *buf, size_t len, int flags, const struct linux_sockaddr *to, socklen_t tolen); 124 ssize_t ff_sendmsg(int s, const struct msghdr *msg, int flags); 125 126 Functions to send a message on a socket. 127 more info see man send. 128 129#### ff\_recv & ff\_recvfrom & ff\_recvmsg 130 131 ssize_t ff_recv(int s, void *buf, size_t len, int flags); 132 ssize_t ff_recvfrom(int s, void *buf, size_t len, int flags, struct linux_sockaddr *from, socklen_t *fromlen); 133 ssize_t ff_recvmsg(int s, struct msghdr *msg, int flags); 134 135 Functions to receive a message from a socket. 136 more info see man recv. 137 138#### ff_select 139 140 int ff_select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); 141 142 select() allow a program to monitor multiple file descriptors, waiting until one or more of the file descriptors become "ready" for some class of I/O operation (e.g., input possible). 143 more info see man select. 144 145#### ff_poll 146 147 int ff_poll(struct pollfd fds[], nfds_t nfds, int timeout); 148 149 ff_poll waits for events on a file descriptor. 150 more info see man poll. 151 152### Kqueue API 153 154#### ff_kqueue 155 156 int ff_kqueue(void); 157 int ff_kevent(int kq, const struct kevent *changelist, int nchanges, struct kevent *eventlist, int nevents, const struct timespec *timeout); 158 159 The kqueue() system call provides a generic method of notifying the user when an event occurs or a condition holds, based on the results of small pieces of kernel code termed filters. 160 more info see man kqueue on FreeBSD System Calls Manual. 161 162### Epoll API 163 164#### ff\_epoll\_create 165 166 int ff_epoll_create(int size); 167 168 epoll_create() returns a file descriptor referring to the new epoll instance. 169 more info see man epoll_create. 170 171#### ff\_epoll\_ctl 172 173 int ff_epoll_ctl(int epfd, int op, int fd, struct epoll_event *event); 174 175 This system call performs control operations on the epoll(7) instance referred by the file descriptor epfd. 176 more info see man epoll_ctl. 177 178### Micro Thread API `micro_thread/mt_api.h` 179 180 In order to develop asynchronous program convenient without complex asynchronous logic processing (reference [SPP's micro thread framework](https://github.com/Tencent/MSEC/tree/master/spp_rpc)), F-Stack provides a micro thread framework so that synchronous programming can be achieved using asynchronous calls. 181 182#### UDP send/recv interface 183 184 int mt_udpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int& buf_size, int timeout); 185 186 Use Random socket port to send and recv udp packet. 187 188 189#### tcp send/recv interface 190 191 int mt_tcpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int& buf_size, int timeout, MtFuncTcpMsgLen chek_func); 192 193 Use connection pool to send and recv tcp packet, keep-alive default are 10 mintues. The parameter of buf can't use `static`. 194 195 196 enum MT_TCP_CONN_TYPE 197 { 198 MT_TCP_SHORT = 1, 199 MT_TCP_LONG = 2, 200 MT_TCP_SHORT_SNDONLY = 3, 201 MT_TCP_LONG_SNDONLY = 4, 202 MT_TCP_BUTT 203 }; 204 205 int mt_tcpsendrcv_ex(struct sockaddr_in* dst, void* pkg, int len, void* rcv_buf, int* buf_size, int timeout, MtFuncTcpMsgLen func, MT_TCP_CONN_TYPE type = MT_TCP_LONG); 206 207 TCP send and recv interface, you can choose if the connection is keep-alive or close.The parameter of buf can't use `static`. 208 209 210 int mt_tcpsendrcv_ex(struct sockaddr_in* dst, void* pkg, int len, void*& rcv_buf, int& recv_pkg_size, int timeout, MtFuncTcpMsgChecker check_func, void* msg_ctx=NULL, MT_TCP_CONN_TYPE type = MT_TCP_LONG, bool keep_rcv_buf=false); 211 212 Tcp send and recv interface, you can choose if the connection is keep-alive or close.The parameter of buf can't use `static`. 213 214 215 int mt_tcpsendrcv(struct sockaddr_in* dst, void* pkg, int len, void*& rcv_buf, int& recv_pkg_size, int timeout, MtFuncTcpMsgChecker check_func, void* msg_ctx=NULL, bool keep_rcv_buf=false); 216 217 218 Use connection pool to send and recv tcp packet, keep-alive default are 10 mintues. The parameter of buf can't use `static`. 219 220#### Socket API for micro threads 221 222 see `micro_thread/mt_api.h`. 223 224### Dispatch API 225 226 Packet dispatch callback function, implemented by user. 227 228 typedef int (*dispatch_func_t)(void *data, uint16_t *len, uint16_t queue_id, uint16_t nb_queues); 229 230 void ff_regist_packet_dispatcher(dispatch_func_t func); 231 232 Regist a packet dispath function. 233 234#### param 235 236 - data 237 The data pointer of this packet. 238 - len 239 The length of this packet. 240 - queue_id 241 Current queue of this packet. 242 - nb_queues 243 Number of queues to be dispatched. 244 245#### return 246 247 - 0 to (nb_queues - 1) 248 The queue id that the packet will be dispatched to. 249 - FF_DISPATCH_ERROR (-1) 250 Error occurs or packet is handled by user, packet will be freed. 251 - FF_DISPATCH_RESPONSE (-2) 252 Packet is handled by user, packet will be responsed. 253