source: trunk/kernel/kern/socket.h @ 659

Last change on this file since 659 was 657, checked in by alain, 5 years ago

Introduce remote_buf.c/.h & socket.c/.h files.
Update dev_nic.c/.h files.
File size: 11.7 KB
Line 
1/*
2 * socket.h - socket descriptor and API definition.
3 *
4 * Authors  Alain Greiner    (2016,2017,2018,2019,2020)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _SOCKET_H_
25#define _SOCKET_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <xlist.h>
30#include <remote_buf.h>
31#include <remote_busylock.h>
32
33/****************************************************************************************
34 * This defines the three commands that can be requested by a client thread to
35 * a TX server thread. These commands are registered in the socket descriptor.
36 ****************************************************************************************/
37
38typedef enum sock_cmd_e
39{
40    SOCKET_TX_CONNECT = 20,   /*! request 3 steps handshake (TCP socket only)           */
41    SOCKET_TX_SEND    = 21,   /*! request to send data      (TCP or UDP socket)         */
42    SOCKET_TX_CLOSE   = 22,   /*! request 3 steps handshake (TCP socket only)           */
43}
44sock_cmd_t;
45
46/*****************************************************************************************
47 * This structure defines a socket descriptor. In order to parallelize the transfers,
48 * the set of all registered sockets is split in several subsets.
49 * The number of subsets is the number of  NIC channels.
50 * The distribution key is computed from the (remote_addr/remote_port) couple.
51 * This computation is done by the NIC hardware for RX packets,
52 * and by the dev_nic_connect() function for the TX packets.
53 *
54 * A socket is attached to the NIC_TX[channel] & NIC_RX[channel] chdevs.
55 * Each socket descriptor allows the TX and TX server threads to access various buffers:
56 * - the user "send" buffer contains the data to be send by the TX server thread.
57 * - the kernel "receive" buffer contains the data received by the RX server thread.
58 * - the kernel "r2t" buffer allows the RX server thread to make direct requests
59 *   to the associated TX server (to implement the TCP 3 steps handshake).
60 *
61 * The synchronisation mechanism between the clients threads and the servers threads
62 * is different for TX and RX transfers:
63 *
64 * 1) For a TX transfer, it can exist only one client thread for a given socket,
65 *    the transfer is always initiated by the local process, and all TX commands
66 *    (CONNECT/SEND/CLOSE) are blocking for the client thread. The user buffer is
67 *    used by TCP to handle retransmissions when required.in case of re
68 *    The client thread registers the command in the thread descriptor, registers itself
69 *    in the socket descriptor, unblocks the TX server thread from the BLOCKED_CLIENT
70 *    condition, blocks itself on the BLOCKED_IO condition, and deschedules.
71 *    When the command is completed, the TX server thread unblocks the client thread.
72 *    The TX server blocks itself on the BLOCKED_CLIENT condition, when there is no
73 *    pending commands and the R2T queue is empty. It is unblocked when a client
74 *    register a new command, or when the TX server thread register a mew request
75 *    in the R2T queue.
76 *    The tx_valid flip-flop is SET by the client thread to signal a valid command.
77 *    It is RESET by the server thread when the command is completed: For a SEND,
78 *    all bytes have been sent (UDP) or acknowledged (TCP).
79 *
80 * 2) For an RX transfer, it can exist only one client thread for a given socket,
81 *    but the transfer is initiated by the remote process, and the  RECV command
82 *    is not really blocking: the data can arrive before the local RECV command is
83 *    executed, and the server thread does not wait to receive all requested data
84 *    to deliver data to client thread. Therefore each socket contains a receive
85 *    buffer (rx_buf) handled as a single-writer/single-reader fifo.
86 *    The client thread consumes data from the rx_buf when possible. It blocks on the
87 *    BLOCKED_IO condition and deschedules when the rx_buf is empty.
88 *    It is unblocked by the RX server thread when new data is available in the rx_buf.
89 *    The RX server blocks itself on the BLOCKED_ISR condition When the NIC_RX packets
90 *    queue is empty. It is unblocked by the hardware when new packets are available.
91 *
92 * Note : the socket domains and types are defined in the "shared_socket.h" file.
93 ****************************************************************************************/
94
95typedef enum udp_socket_state_e
96{
97    UDP_STATE_UNBOUND   = 0,
98    UDP_STATE_BOUND     = 1,
99    UDP_STATE_CONNECT   = 2,
100}
101udp_socket_state_t;
102
103typedef enum tcp_socket_state_e
104{
105    TCP_STATE_UNBOUND    = 10,
106    TCP_STATE_BOUND      = 11,
107    TCP_STATE_LISTEN     = 12,
108    TCP_STATE_SYN_SENT   = 13,
109    TCP_STATE_SYN_RCVD   = 14,
110    TCP_STATE_ESTAB      = 15,
111    TCP_STATE_FIN_WAIT1  = 16,
112    TCP_STATE_FIN_WAIT2  = 17,
113    TCP_STATE_CLOSING    = 18,
114    TCP_STATE_TIME_WAIT  = 19,
115    TCP_STATE_CLOSE_WAIT = 20,
116    TCP_STATE_LAST_ACK   = 21,
117}
118tcp_socket_state_t;
119
120typedef struct socket_s
121{
122    remote_busylock_t lock;          /*! lock protecting socket state                  */
123    uint32_t          domain;        /*! domain : AF_LOCAL / AF_INET                   */
124    uint32_t          type;          /*! type : SOCK_DGRAM / SOCK_STREAM               */
125    pid_t             pid;           /*! owner process identifier                      */
126    uint32_t          state;         /*! see above                                     */
127    uint32_t          local_addr;    /*! local  socket IP address                      */
128    uint32_t          remote_addr;   /*! remote socket IP address                      */
129    uint32_t          local_port;    /*! local  socket port number                     */
130    uint32_t          remote_port;   /*! remote socket port number                     */
131    uint32_t          nic_channel;   /*! derived from (remote_addr,remote_port)        */
132
133    xlist_entry_t     tx_list;       /*! sockets attached to same NIC_TX chdev         */
134    xptr_t            tx_client;     /*! extended pointer on TX client thread          */
135    sock_cmd_t        tx_cmd;        /*! command type (CONNECT/SEND/CLOSE)             */
136    uint8_t         * tx_buf;        /*! pointer on user buffer in user space          */
137    uint32_t          tx_len;        /*! number of bytes to be sent in command         */
138    uint32_t          tx_todo;       /*! number of bytes not yet sent                  */
139    uint32_t          tx_error;      /*! signal a TX command error                     */
140
141    xlist_entry_t     rx_list;       /*! sockets attached to same NIC_RX chdev         */
142    xptr_t            rx_client;     /*! extended pointer on RX client thread          */
143    remote_buf_t      rx_buf;        /*! embedded receive buffer descriptor            */
144
145    remote_buf_t      r2tq;          /*! RX_to_TX requests queue descriptor            */
146
147    remote_buf_t      crqq;          /*! connection requests queue descriptor          */         
148    /* the following fields defines the TCB used for a TCP connection                  */
149
150    uint32_t          tx_una;        /*! first unack byte in TX_data stream            */
151    uint32_t          tx_nxt;        /*! next byte to send in TX_data stream           */
152    uint32_t          tx_wnd;        /*! number of acceptable bytes in TX_data stream  */
153
154    uint32_t          rx_nxt;        /*! next expected byte in RX_data stream          */
155    uint32_t          rx_wnd;        /*! number of acceptable bytes in RX_data stream  */
156    uint32_t          rx_irs;        /*! initial sequence number in RX_data stream     */
157}
158socket_t;
159
160/****************************************************************************************
161 * This function returns a printable string for a client_to_tx_server command type.
162 ****************************************************************************************
163 * type   :  SOCKET_TX_CONNECT / SOCKET_TX_SEND / SOCKET_TX_CLOSE
164 ***************************************************************************************/
165char * socket_cmd_str( uint32_t type );
166
167/****************************************************************************************
168 * This function returns a printable string for an UDP or TCP socket state.
169 ****************************************************************************************
170 * state  :  UDP_STATE_*** / TCP_STATE***
171 ***************************************************************************************/
172char * socket_state_str( uint32_t state );
173
174/****************************************************************************************
175 * This function allocates memory in the cluster defined by the <cxy> argument for a
176 * socket descriptor defined by the <domain> and <type> aruments, for the associated
177 * file descriptor, and for the various kernel buffers descriptors contained in the
178 * socket descriptor : "rx_buf" (receive buffer), "r2tq" (RX to RX requests queue), and
179 * "crqq" (connect requests queue). It initialises the socket desccriptor static fields,
180 * (other than local_addr, local_port, remote_addr, remote_port).
181 * It registers the file descriptor in the reference process fd_array[], set the socket
182 * the socket state to UNBOUND, and returns the file identifier in the <fdid> argument.
183 ****************************************************************************************
184 * @ cxy     : [in]  target cluster identifier.
185 * @ domain  : [in]  socket protocol family (must be AF_INET).
186 * @ type    : [in]  socket type (SOCK_DGRAM / SOCK_STREAM).
187 * @ socket  : [out] buffer for a local pointer on created socket.
188 * @ fdid    : [out] buffer for file identifier.
189 * @ return 0 if success / return -1 if failure (no memory).
190 ***************************************************************************************/
191error_t socket_create( cxy_t              cxy,
192                       uint32_t           domain,
193                       uint32_t           type,
194                       struct socket_s ** socket,
195                       uint32_t         * fdid );
196                       
197/****************************************************************************************
198 * This functions releases all memory allocated to a socket identified by the <fdid>
199 * argument. This include the file descriptor, the socket descriptor, and all buffers
200 * referenced by the socket descriptor.
201 ****************************************************************************************
202 * @ fdid   : [in]  file descriptor index.
203 ***************************************************************************************/
204void socket_destroy( uint32_t fdid );
205
206/****************************************************************************************
207 * This functions registers the socket defined by the <socket_xp> argument into the
208 * lists of sockets attached to the NIC_TX and NIC_TX chdevs identified by the
209 * <nic_channel> argument.
210 ****************************************************************************************
211 * @ socket_xp   : [in]  extended pointer on socket descriptor
212 * @ nic_channel : [in]  NIC channel index.
213 ***************************************************************************************/
214void socket_link_to_servers( xptr_t    socket_xp,
215                             uint32_t  nic_channel );
216 
217#endif  /* _SOCKET_H_ */
Note: See TracBrowser for help on using the repository browser.