KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
fs_socket.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  kos/fs_socket.h
4  Copyright (C) 2006, 2009, 2010, 2012 Lawrence Sebald
5 
6 */
7 
8 /** \file kos/fs_socket.h
9  \brief Definitions for a sockets "filesystem".
10 
11  This file provides definitions to support the BSD-sockets-like filesystem
12  in KallistiOS. Technically, this filesystem mounts itself on /sock, but it
13  doesn't export any files there, so that point is largely irrelevant. The
14  filesystem is designed to be extensible, making it possible to add
15  additional socket family handlers at runtime. Currently, the kernel only
16  implements UDP sockets over IPv4 and IPv6, but as mentioned, this can be
17  extended in a fairly straightforward manner. In general, as a user of
18  KallistiOS (someone not interested in adding additional socket family
19  drivers), there's very little in this file that will be of interest.
20 
21  \author Lawrence Sebald
22 */
23 
24 #ifndef __KOS_FS_SOCKET_H
25 #define __KOS_FS_SOCKET_H
26 
27 #include <sys/cdefs.h>
28 
29 __BEGIN_DECLS
30 
31 #include <arch/types.h>
32 #include <kos/limits.h>
33 #include <kos/fs.h>
34 #include <kos/net.h>
35 #include <sys/queue.h>
36 #include <sys/socket.h>
37 #include <stdint.h>
38 
39 struct fs_socket_proto;
40 
41 /** \brief Internal representation of a socket for fs_socket.
42 
43  This structure is the internal representation of a socket "file" that is
44  used within fs_socket. A normal user will never deal with this structure
45  directly (only protocol handlers and fs_socket itself ever sees this
46  structure directly).
47 
48  \headerfile kos/fs_socket.h
49 */
50 typedef struct net_socket {
51  /** \cond */
52  /* List handle */
53  LIST_ENTRY(net_socket) sock_list;
54  /** \endcond */
55 
56  /** \brief File handle from the VFS layer. */
57  file_t fd;
58 
59  /** \brief The protocol handler for this socket. */
60  struct fs_socket_proto *protocol;
61 
62  /** \brief Protocol-specific data. */
63  void *data;
64 } net_socket_t;
65 
66 /** \brief Internal sockets protocol handler.
67 
68  This structure is a protocol handler used within fs_socket. Each protocol
69  that is supported has one of these registered for it within the kernel.
70  Generally, users will not come in contact with this structure (unless you're
71  planning on writing a protocol handler), and it can generally be ignored.
72 
73  For a complete list of appropriate errno values to return from any functions
74  that are in here, take a look at the Single Unix Specification (aka, the
75  POSIX spec), specifically the page about sys/socket.h (and all the functions
76  that it defines, which is available at
77  http://www.opengroup.org/onlinepubs/9699919799/basedefs/sys_socket.h.html .
78 
79  \headerfile kos/fs_socket.h
80 */
81 typedef struct fs_socket_proto {
82  /** \brief Entry into the global list of protocols.
83 
84  Contrary to what Doxygen might think, this is <b>NOT</b> a function.
85  This should be initialized with the FS_SOCKET_PROTO_ENTRY macro before
86  adding the protocol to the kernel with fs_socket_proto_add().
87  */
88  TAILQ_ENTRY(fs_socket_proto) entry;
89 
90  /** \brief Domain of support for this protocol handler.
91 
92  This field determines which sockets domain this protocol handler
93  actually supports. This corresponds with the domain argument of the
94  ::socket() function.
95  */
96  int domain;
97 
98  /** \brief Type of support for this protocol handler.
99 
100  This field determines which types of sockets that this protocol handler
101  pays attention to. This corresponds with the type argument of the
102  ::socket() function.
103  */
104  int type;
105 
106  /** \brief Protocol of support for this protocol handler.
107 
108  This field determines the protocol that this protocol handler actually
109  pays attention to. This corresponds with the protocol argument of the
110  ::socket() function.
111  */
112  int protocol;
113 
114  /** \brief Create a new socket for the protocol.
115 
116  This function must create a new socket, initializing any data that the
117  protocol might need for the socket, based on the parameters passed in.
118  The socket passed in is already initialized prior to the handler being
119  called, and will be cleaned up by fs_socket if an error is returned from
120  the handler (a return value of -1).
121 
122  \param s The socket structure to initialize
123  \param domain Domain of the socket
124  \param type Type of the socket
125  \param protocol Protocol of the socket
126  \retval -1 On error (errno should be set appropriately)
127  \retval 0 On success
128  */
129  int (*socket)(net_socket_t *s, int domain, int type, int protocol);
130 
131  /** \brief Close a socket that was created with the protocol.
132 
133  This function must do any work required to close a socket and destroy
134  it. This function will be called when a socket requests to be closed
135  with the close system call. There are no errors defined for this
136  function.
137 
138  \param s The socket to close
139  */
140  void (*close)(net_socket_t *hnd);
141 
142  /** \brief Accept a connection on a socket created with the protocol.
143 
144  This function should implement the ::accept() system call for the
145  protocol. The semantics are exactly as expected for that function.
146 
147  \param s The socket to accept a connection on
148  \param addr The address of the incoming connection
149  \param alen The length of the address
150  \return A newly created socket for the incoming connection
151  or -1 on error (with errno set appropriately)
152  */
153  int (*accept)(net_socket_t *s, struct sockaddr *addr, socklen_t *alen);
154 
155  /** \brief Bind a socket created with the protocol to an address.
156 
157  This function should implement the ::bind() system call for the
158  protocol. The semantics are exactly as expected for that function.
159 
160  \param s The socket to bind to the address
161  \param addr The address to bind to
162  \param alen The length of the address
163  \retval -1 On error (set errno appropriately)
164  \retval 0 On success
165  */
166  int (*bind)(net_socket_t *s, const struct sockaddr *addr, socklen_t alen);
167 
168  /** \brief Connect a socket created with the protocol to a remote system.
169 
170  This function should implement the ::connect() system call for the
171  protocol. The semantics are exactly as expected for that function.
172 
173  \param s The socket to connect with
174  \param addr The address to connect to
175  \param alen The length of the address
176  \retval -1 On error (with errno set appropriately)
177  \retval 0 On success
178  */
179  int (*connect)(net_socket_t *s, const struct sockaddr *addr,
180  socklen_t alen);
181 
182  /** \brief Listen for incoming connections on a socket created with the
183  protocol.
184 
185  This function should implement the ::listen() system call for the
186  protocol. The semantics are exactly as expected for that function.
187 
188  \param s The socket to listen on
189  \param backlog The number of connections to queue
190  \retval -1 On error (with errno set appropriately)
191  \retval 0 On success
192  */
193  int (*listen)(net_socket_t *s, int backlog);
194 
195  /** \brief Recieve data on a socket created with the protocol.
196 
197  This function should implement the ::recvfrom() system call for the
198  protocol. The semantics are exactly as expected for that function. Also,
199  this function should implement the ::recv() system call, which will
200  call this function with NULL for addr and alen.
201 
202  \param s The socket to receive data on
203  \param buffer The buffer to save data in
204  \param len The length of the buffer
205  \param flags Flags to the function
206  \param addr Space to store the address that data came from (NULL
207  if this was called by ::recv())
208  \param alen Space to store the length of the address (NULL if
209  this was called by ::recv())
210  \retval -1 On error (set errno appropriately)
211  \retval 0 No outstanding data and the peer has disconnected
212  cleanly
213  \retval n The number of bytes received (may be less than len)
214  */
215  ssize_t (*recvfrom)(net_socket_t *s, void *buffer, size_t len, int flags,
216  struct sockaddr *addr, socklen_t *alen);
217 
218  /** \brief Send data on a socket created with the protocol.
219 
220  This function should implement the ::sendto() system call for the
221  protocol. The semantics are exactly as expected for that function. Also,
222  this function should implement the ::send() system call, which will
223  call this function with NULL for addr and 0 for alen.
224 
225  \param s The socket to send data on
226  \param msg The data to send
227  \param len The length of data to send
228  \param flags Flags to the function
229  \param addr The address to send data to (NULL if this was called
230  by ::send())
231  \param alen The length of the address (0 if this was called by
232  ::send())
233  \retval -1 On error (set errno appropriately)
234  \retval n The number of bytes actually sent (may be less than
235  len)
236  */
237  ssize_t (*sendto)(net_socket_t *s, const void *msg, size_t len, int flags,
238  const struct sockaddr *addr, socklen_t alen);
239 
240  /** \brief Shut down a socket created with the protocol.
241 
242  This function should implement the ::shutdown() system call for the
243  protocol. The semantics are exactly as expected for that function.
244 
245  \param s The socket to shut down
246  \param how What should be shut down on the socket
247  \retval -1 On error (set errno appropriately)
248  \retval 0 On success
249  */
250  int (*shutdownsock)(net_socket_t *s, int how);
251 
252  /** \brief Input a packet into a protocol.
253 
254  This function should read in the packet specified by the arguments and
255  sort out what exactly to do with it. This usually involves checking if
256  there is an open socket with the source address and adding it to a
257  packet queue if there is.
258 
259  \param src The interface the packet was input on
260  \param domain The low-level protocol used (AF_INET or AF_INET6)
261  \param hdr The low-level protocol header
262  \param data The packet itself, including any protcol headers,
263  but not any from lower-level protocols
264  \param size The size of the packet, not including any lower-
265  level protocol headers
266  \retval -1 On error (the packet is discarded)
267  \retval 0 On success
268  */
269  int (*input)(netif_t *src, int domain, const void *hdr, const uint8 *data,
270  int size);
271 
272  /** \brief Get socket options.
273 
274  This function should implement the ::getsockopt() system call for the
275  given protocol. The semantics are exactly as defined for that function.
276 
277  Currently all options (regardless of level) are passed onto the
278  protocol handler.
279 
280  \param s The socket to get options for.
281  \param level The protocol level to get options at.
282  \param option_name The option to look up.
283  \param option_value Storage for the value of the option.
284  \param option_len The length of option_value on call, and the real
285  option length (if less than the original value)
286  on return.
287  \retval -1 On error (set errno appropriately).
288  \retval 0 On success.
289  */
290  int (*getsockopt)(net_socket_t *s, int level, int option_name,
291  void *option_value, socklen_t *option_len);
292 
293  /** \brief Set socket options.
294 
295  This function should implement the ::setsockopt() system call for the
296  given protocol. The semantics are exactly as defined for that function.
297 
298  Currently all options (regardless of level) are passed onto the
299  protocol handler.
300 
301  \param s The socket to set options for.
302  \param level The protocol level to set options at.
303  \param option_name The option to set.
304  \param option_value The value to set for the option.
305  \param option_len The length of the option_value value.
306  \retval -1 On error (set errno appropriately).
307  \retval 0 On success.
308  */
309  int (*setsockopt)(net_socket_t *s, int level, int option_name,
310  const void *option_value, socklen_t option_len);
311 
312  /** \brief Manipulate file options.
313 
314  This function should implement the fcntl() system call for the given
315  protocol. The semantics are exactly as defined for that function.
316 
317  \param s The socket to manipulate.
318  \param cmd The fcntl command to run.
319  \param ap Arguments to the command.
320  \retval -1 On error (generally, set errno appropriately).
321  */
322  int (*fcntl)(net_socket_t *s, int cmd, va_list ap);
323 
324  /** \brief Poll for events.
325 
326  This function should check the given socket for any events that may have
327  already occured that are specified. This is used to back the ::poll()
328  system call. This function should not block to wait for any events. This
329  function may be called in an interrupt.
330 
331  \param s The socket to poll.
332  \param events The events to check for.
333  \retval A mask of any of the events specified that are
334  currently true in the socket. 0 if none are true.
335  */
336  short (*poll)(net_socket_t *s, short events);
337 } fs_socket_proto_t;
338 
339 /** \brief Initializer for the entry field in the fs_socket_proto_t struct. */
340 #define FS_SOCKET_PROTO_ENTRY { NULL, NULL }
341 
342 /* \cond */
343 /* Init/shutdown */
344 int fs_socket_init();
345 int fs_socket_shutdown();
346 /* \endcond */
347 
348 /** \brief Open a socket without calling the protocol initializer.
349 
350  This function creates a new socket, but does not call the protocol's
351  socket() function. This is meant to be used for things like accepting an
352  incoming connection, where calling the regular socket initializer could
353  cause issues. You shouldn't really have any need to call this function
354  unless you are implementing a new protocol handler.
355 
356  \param proto The protocol to use for the socket.
357  \return The newly created socket on success, NULL on failure.
358 
359  \par Error Conditions:
360  \em EWOULDBLOCK - if the function would block in an IRQ \n
361  \em ENOMEM - out of memory \n
362  \em EMFILE - too many files open
363 */
364 net_socket_t *fs_socket_open_sock(fs_socket_proto_t *proto);
365 
366 /** \defgroup sock_flags Socket flags
367 
368  These are the available flags defined for sockets.
369 
370  Every flag after FS_SOCKET_FAM_MAX is for internal-use only, and should
371  never be passed into any functions.
372  @{
373 */
374 #define FS_SOCKET_NONBLOCK 0x00000001 /** \brief Non-blocking operations */
375 #define FS_SOCKET_V6ONLY 0x00000002 /** \brief IPv6 Only */
376 
377 #define FS_SOCKET_GEN_MAX 0x00008000 /** \brief Maximum generic flag */
378 #define FS_SOCKET_FAM_MAX 0x00800000 /** \brief Maximum family flag */
379 /** @} */
380 
381 /** \brief Input a packet into some socket family handler.
382 
383  This function is used by the lower-level network protocol handlers to input
384  packets for further processing by upper-level protocols. This will call the
385  input function on the family handler, if one is found.
386 
387  \param src The network interface the packet came in on
388  \param domain The low-level protocol used (AF_INET or AF_INET6)
389  \param protocol The upper-level protocol that we're looking for
390  \param hdr The low-level protocol header
391  \param data The upper-level packet, without any lower-level protocol
392  headers, but with the upper-level ones intact
393  \param size The size of the packet (the data parameter)
394  \retval -2 The protocol is not known
395  \retval -1 Protocol-level error processing packet
396  \retval 0 On success
397 */
398 int fs_socket_input(netif_t *src, int domain, int protocol, const void *hdr,
399  const uint8 *data, int size);
400 
401 /** \brief Add a new protocol for use with fs_socket.
402 
403  This function registers a protocol handler with fs_socket for use when
404  creating and using sockets. This protocol handler must implement all of the
405  functions in the fs_socket_proto_t structure. See the code in
406  kos/kernel/net/net_udp.c for an example of how to do this.
407 
408  This function is NOT safe to call inside an interrupt.
409 
410  \param proto The new protocol handler to register
411  \retval 0 On success (no error conditions are currently defined)
412 */
413 int fs_socket_proto_add(fs_socket_proto_t *proto);
414 
415 /** \brief Unregister a protocol from fs_socket.
416 
417  This function does the exact opposite of fs_socket_proto_add, and removes
418  a protocol from use with fs_socket. It is the programmer's responsibility to
419  make sure that no sockets are still around that are registered with the
420  protocol to be removed (as they will not work properly once the handler has
421  been removed).
422 
423  \param proto The protocol handler to remove
424  \retval -1 On error (This function does not directly change errno)
425  \retval 0 On success
426 */
427 int fs_socket_proto_remove(fs_socket_proto_t *proto);
428 
429 __END_DECLS
430 
431 #endif /* __KOS_FS_SOCKET_H */
432 
Generated by   doxygen 1.8.1.1