doc: net: Add socket service API usage documentation

Add information how to use socket service API from application
point of view.

Signed-off-by: Jukka Rissanen <[email protected]>

Author: jukkar

doc/connectivity/networking/api/apis.rst

@@ -7,6 +7,7 @@ Network APIs
    :maxdepth: 1
 
    sockets.rst
+   socket_service.rst
    ip_4_6.rst
    dns_resolve.rst
    net_mgmt.rst

doc/connectivity/networking/api/socket_service.rst

@@ -0,0 +1,142 @@
+.. _socket_service_interface:
+
+Socket Service
+##############
+
+.. contents::
+    :local:
+    :depth: 2
+
+Overview
+********
+
+The socket service API can be used to install a handler that is called if there
+is data received to a socket. The API helps to avoid creating a dedicated thread
+for each TCP or UDP services that the application provides. Instead one thread
+is created which can serve data to multiple listening sockets which saves memory
+as only one thread needs to be created in the system in this case.
+
+See :zephyr:code-sample:`sockets-service-echo` sample application to learn how
+to create a simple BSD socket based server application using the sockets service API.
+The source code for this sample application can be found at:
+:zephyr_file:`samples/net/sockets/echo_service`.
+
+API Description
+***************
+
+Socket service API is enabled using :kconfig:option:`CONFIG_NET_SOCKETS_SERVICE`
+config option and implements the following operations:
+
+* :c:macro:`NET_SOCKET_SERVICE_SYNC_DEFINE`
+
+  Define a network socket service. This socket service is created with extern
+  scope so it can be used from multiple C source files.
+
+* :c:macro:`NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC`
+
+  Define a network socket service with static scope. This socket service can only
+  be used within one C source file.
+
+* :c:func:`net_socket_service_register`
+
+  Register pollable sockets for this service. User must create the sockets
+  before this call.
+
+* :c:func:`net_socket_service_unregister`
+
+  Remove pollable sockets for this service. User can close the sockets after
+  this call.
+
+* :c:type:`net_socket_service_handler_t`
+
+  User specified callback which is called when data is received to the
+  listening socket.
+
+Application Overview
+********************
+
+When socket service API is enabled, the application must create the service like
+this:
+
+.. code-block:: c
+
+   #define MAX_BUF_LEN 1500
+   #define MAX_SERVICES 1
+
+   static void udp_service_handler(struct net_socket_service_event *pev)
+   {
+	struct pollfd *pfd = &pev->event;
+	int client = pfd->fd;
+	struct sockaddr_in6 addr;
+	socklen_t addrlen = sizeof(addr);
+
+	/* In this example we use one static buffer in order to avoid
+	 * having large stack.
+	 */
+	static char buf[MAX_BUF_LEN];
+
+	len = recvfrom(client, buf, sizeof(buf), 0,
+		       (struct sockaddr *)&addr, &addrlen);
+	if (len <= 0) {
+		/* Error */
+		...
+		return;
+	}
+
+	/* Do something with the received data. The pev variable contains
+	 * user data that was saved in the socket service was registered.
+	 */
+   }
+
+   NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC(udp_service, udp_service_handler, MAX_SERVICES);
+
+The application needs to create the sockets, then register them to the socket
+service after which the socket service thread will start to call the callback
+for any incoming data.
+
+.. code-block:: c
+
+   /* Create one or multiple sockets */
+
+   struct pollfd sockfd_udp[1] = { 0 };
+   int sock, ret;
+
+   sock = socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDP);
+   if (sock < 0) {
+	LOG_ERR("socket: %d", -errno);
+	return -errno;
+   }
+
+   /* Set possible socket options after creation */
+   ...
+
+   /* Then bind the socket to local address */
+   if (bind(sock, (struct sockaddr *)addr, sizeof(*addr)) < 0) {
+	LOG_ERR("bind: %d", -errno);
+	return -errno;
+   }
+
+   /* Set the polled sockets */
+   sockfd_udp[0].fd = sock;
+   sockfd_udp[0].events = POLLIN;
+
+   /* Register UDP socket to service handler */
+   ret = net_socket_service_register(&service_udp, sockfd_udp,
+				     ARRAY_SIZE(sockfd_udp), NULL);
+   if (ret < 0) {
+	LOG_ERR("Cannot register socket service handler (%d)", ret);
+	return ret;
+   }
+
+   /* Application logic happens here. When application is ready to
+    * quit, one should unregister the socket service and close the
+    * socket.
+    */
+
+   (void)net_socket_service_unregister(&service_udp);
+   close(sock);
+
+API Reference
+*************
+
+.. doxygengroup:: bsd_socket_service