doc: net: Add network configuration guide

Add a simple document describing various network related
configuration options and how they affect the available
resources in the system.

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

Author: jukkar

doc/connectivity/networking/index.rst

@@ -12,6 +12,7 @@ operation of the stacks and how they were implemented.
 
    overview.rst
    net-stack-architecture.rst
+   net_config_guide.rst
    networking_with_host.rst
    network_monitoring.rst
    api/index.rst

doc/connectivity/networking/net_config_guide.rst

@@ -0,0 +1,273 @@
+.. _network_configuration_guide:
+
+Network Configuration Guide
+###########################
+
+.. contents::
+    :local:
+    :depth: 2
+
+This document describes how various network configuration options can be
+set according to available resources in the system.
+
+Network Buffer Configuration Options
+************************************
+
+The network buffer configuration options control how much data we
+are able to either send or receive at the same time.
+
+:kconfig:option:`CONFIG_NET_PKT_RX_COUNT`
+  Maximum amount of network packets we can receive at the same time.
+
+:kconfig:option:`CONFIG_NET_PKT_TX_COUNT`
+  Maximum amount of network packet sends pending at the same time.
+
+:kconfig:option:`CONFIG_NET_BUF_RX_COUNT`
+  How many network buffers are allocated for receiving data.
+  Each net_buf contains a small header and either a fixed or variable
+  length data buffer. The :kconfig:option:`CONFIG_NET_BUF_DATA_SIZE`
+  is used when :kconfig:option:`CONFIG_NET_BUF_FIXED_DATA_SIZE` is set.
+  This is the default setting. The default size of the buffer is 128 bytes.
+
+  The :kconfig:option:`CONFIG_NET_BUF_VARIABLE_DATA_SIZE` is an experimental
+  setting. There each net_buf data portion is allocated from a memory pool and
+  can be the amount of data we have received from the network.
+  When data is received from the network, it is placed into net_buf data portion.
+  Depending on device resources and desired network usage, user can tweak
+  the size of the fixed buffer by setting :kconfig:option:`CONFIG_NET_BUF_DATA_SIZE`, and
+  the size of the data pool size by setting :kconfig:option:`CONFIG_NET_BUF_DATA_POOL_SIZE`
+  if variable size buffers are used.
+
+  When using the fixed size data buffers, the memory consumption of network buffers
+  can be tweaked by selecting the size of the data part according to what kind of network
+  data we are receiving. If one sets the data size to 256, but only receives packets
+  that are 32 bytes long, then we are "wasting" 224 bytes for each packet because we
+  cannot utilize the remaining data. One should not set the data size too low because
+  there is some overhead involved for each net_buf. For these reasons the default
+  network buffer size is set to 128 bytes.
+
+  The variable size data buffer feature is marked as experimental as it has not
+  received as much testing as the fixed size buffers. Using variable size data
+  buffers tries to improve memory utilization by allocating minimum amount of
+  data we need for the network data. The extra cost here is the amount of time
+  that is needed when dynamically allocating the buffer from the memory pool.
+
+  For example, in Ethernet the maximum transmission unit (MTU) size is 1500 bytes.
+  If one wants to receive two full frames, then the net_pkt RX count should be set to 2,
+  and net_buf RX count to (1500 / 128) * 2 which is 24.
+  If TCP is being used, then these values need to be higher because we can queue the
+  packets internally before delivering to the application.
+
+:kconfig:option:`CONFIG_NET_BUF_TX_COUNT`
+  How many network buffers are allocated for sending data. This is similar setting
+  as the receive buffer count but for sending.
+
+
+Connection Options
+******************
+
+:kconfig:option:`CONFIG_NET_MAX_CONN`
+  This option tells how many network connection endpoints are supported.
+  For example each TCP connection requires one connection endpoint. Similarly
+  each listening UDP connection requires one connection endpoint.
+  Also various system services like DHCP and DNS need connection endpoints to work.
+  The network shell command **net conn** can be used at runtime to see the
+  network connection information.
+
+:kconfig:option:`CONFIG_NET_MAX_CONTEXTS`
+  Number of network contexts to allocate. Each network context describes a network
+  5-tuple that is used when listening or sending network traffic. Each BSD socket in the
+  system uses one network context.
+
+
+Socket Options
+**************
+
+:kconfig:option:`CONFIG_NET_SOCKETS_POLL_MAX`
+  Maximum number of supported poll() entries. One needs to select proper value here depending
+  on how many BSD sockets are polled in the system.
+
+:kconfig:option:`CONFIG_POSIX_MAX_FDS`
+  Maximum number of open file descriptors, this includes files, sockets, special devices, etc.
+  One needs to select proper value here depending on how many BSD sockets are created in
+  the system.
+
+:kconfig:option:`CONFIG_NET_SOCKETPAIR_BUFFER_SIZE`
+  This option is used by socketpair() function. It sets the size of the
+  internal intermediate buffer, in bytes. This sets the limit how large
+  messages can be passed between two socketpair endpoints.
+
+
+TLS Options
+***********
+
+:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CONTEXTS`
+  Maximum number of TLS/DTLS contexts. Each TLS/DTLS connection needs one context.
+
+:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CREDENTIALS`
+  This variable sets maximum number of TLS/DTLS credentials that can be
+  used with a specific socket.
+
+:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CIPHERSUITES`
+  Maximum number of TLS/DTLS ciphersuites per socket.
+  This variable sets maximum number of TLS/DTLS ciphersuites that can
+  be used with specific socket, if set explicitly by socket option.
+  By default, all ciphersuites that are available in the system are
+  available to the socket.
+
+:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_APP_PROTOCOLS`
+  Maximum number of supported application layer protocols.
+  This variable sets maximum number of supported application layer
+  protocols over TLS/DTLS that can be set explicitly by a socket option.
+  By default, no supported application layer protocol is set.
+
+:kconfig:option:`CONFIG_NET_SOCKETS_TLS_MAX_CLIENT_SESSION_COUNT`
+  This variable specifies maximum number of stored TLS/DTLS sessions,
+  used for TLS/DTLS session resumption.
+
+:kconfig:option:`CONFIG_TLS_MAX_CREDENTIALS_NUMBER`
+   Maximum number of TLS credentials that can be registered.
+   Make sure that this value is high enough so that all the
+   certificates can be loaded to the store.
+
+
+IPv4/6 Options
+**************
+
+:kconfig:option:`CONFIG_NET_IF_MAX_IPV4_COUNT`
+   Maximum number of IPv4 network interfaces in the system.
+   This tells how many network interfaces there will be in the system
+   that will have IPv4 enabled.
+   For example if you have two network interfaces, but only one of them
+   can use IPv4 addresses, then this value can be set to 1.
+   If both network interface could use IPv4, then the setting should be
+   set to 2.
+
+:kconfig:option:`CONFIG_NET_IF_MAX_IPV6_COUNT`
+   Maximum number of IPv6 network interfaces in the system.
+   This is similar setting as the IPv4 count option but for IPv6.
+
+
+TCP Options
+***********
+
+:kconfig:option:`CONFIG_NET_TCP_TIME_WAIT_DELAY`
+  How long to wait in TCP *TIME_WAIT* state (in milliseconds).
+  To avoid a (low-probability) issue when delayed packets from
+  previous connection get delivered to next connection reusing
+  the same local/remote ports,
+  `RFC 793 <https://www.rfc-editor.org/rfc/rfc793>`_ (TCP) suggests
+  to keep an old, closed connection in a special *TIME_WAIT* state for
+  the duration of 2*MSL (Maximum Segment Lifetime). The RFC
+  suggests to use MSL of 2 minutes, but notes
+
+  *This is an engineering choice, and may be changed if experience indicates
+  it is desirable to do so.*
+
+  For low-resource systems, having large MSL may lead to quick
+  resource exhaustion (and related DoS attacks). At the same time,
+  the issue of packet misdelivery is largely alleviated in the modern
+  TCP stacks by using random, non-repeating port numbers and initial
+  sequence numbers. Due to this, Zephyr uses much lower value of 1500ms
+  by default. Value of 0 disables *TIME_WAIT* state completely.
+
+:kconfig:option:`CONFIG_NET_TCP_RETRY_COUNT`
+  Maximum number of TCP segment retransmissions.
+  The following formula can be used to determine the time (in ms)
+  that a segment will be be buffered awaiting retransmission:
+
+  .. math::
+
+     \sum_{n=0}^{\mathtt{NET\_TCP\_RETRY\_COUNT}} \bigg(1 \ll n\bigg)\times
+     \mathtt{NET\_TCP\_INIT\_RETRANSMISSION\_TIMEOUT}
+
+  With the default value of 9, the IP stack will try to
+  retransmit for up to 1:42 minutes.  This is as close as possible
+  to the minimum value recommended by
+  `RFC 1122 <https://www.rfc-editor.org/rfc/rfc1122>`_ (1:40 minutes).
+  Only 5 bits are dedicated for the retransmission count, so accepted
+  values are in the 0-31 range.  It's highly recommended to not go
+  below 9, though.
+
+  Should a retransmission timeout occur, the receive callback is
+  called with :code:`-ETIMEDOUT` error code and the context is dereferenced.
+
+:kconfig:option:`CONFIG_NET_TCP_MAX_SEND_WINDOW_SIZE`
+  Maximum sending window size to use.
+  This value affects how the TCP selects the maximum sending window
+  size. The default value 0 lets the TCP stack select the value
+  according to amount of network buffers configured in the system.
+  Note that if there are multiple active TCP connections in the system,
+  then this value might require finetuning (lowering), otherwise multiple
+  TCP connections could easily exhaust net_buf pool for the queued TX data.
+
+:kconfig:option:`CONFIG_NET_TCP_MAX_RECV_WINDOW_SIZE`
+  Maximum receive window size to use.
+  This value defines the maximum TCP receive window size. Increasing
+  this value can improve connection throughput, but requires more
+  receive buffers available in the system for efficient operation.
+  The default value 0 lets the TCP stack select the value
+  according to amount of network buffers configured in the system.
+
+:kconfig:option:`CONFIG_NET_TCP_RECV_QUEUE_TIMEOUT`
+  How long to queue received data (in ms).
+  If we receive out-of-order TCP data, we queue it. This value tells
+  how long the data is kept before it is discarded if we have not been
+  able to pass the data to the application. If set to 0, then receive
+  queueing is not enabled. The value is in milliseconds.
+
+  Note that we only queue data sequentially in current version i.e.,
+  there should be no holes in the queue. For example, if we receive
+  SEQs 5,4,3,6 and are waiting SEQ 2, the data in segments 3,4,5,6 is
+  queued (in this order), and then given to application when we receive
+  SEQ 2. But if we receive SEQs 5,4,3,7 then the SEQ 7 is discarded
+  because the list would not be sequential as number 6 is be missing.
+
+
+Traffic Class Options
+*********************
+
+It is possible to configure multiple traffic classes (queues) when receiving
+or sending network data. Each traffic class queue is implemented as a thread
+with different priority. This means that higher priority network packet can
+be placed to a higher priority network queue in order to send or receive it
+faster or slower. Because of thread scheduling latencies, in practice the
+fastest way to send a packet out, is to directly send the packet without
+using a dedicated traffic class thread. This is why by default the
+:kconfig:option:`CONFIG_NET_TC_TX_COUNT` option is set to 0 if userspace is
+not enabled. If userspace is enabled, then the minimum TX traffic class
+count is 1. Reason for this is that the userspace application does not
+have enough permissions to deliver the message directly.
+
+In receiving side, it is recommended to have at least one receiving traffic
+class queue. Reason is that typically the network device driver is running
+in IRQ context when it receives the packet, in which case it should not try
+to deliver the network packet directly to the upper layers, but to place
+the packet to the traffic class queue. If the network device driver is not
+running in IRQ context when it gets the packet, then the RX traffic class
+option :kconfig:option:`CONFIG_NET_TC_RX_COUNT` could be set to 0.
+
+
+Stack Size Options
+******************
+
+There several network specific threads in a network enabled system.
+Some of the threads might depend on a configure option which can be
+used to enable or disable a feature. Each thread stack size is optimized
+to allow normal network operations.
+
+The network management API is using a dedicated thread by default. The thread
+is responsible to deliver network management events to the event listeners that
+are setup in the system if the :kconfig:option:`CONFIG_NET_MGMT` and
+:kconfig:option:`CONFIG_NET_MGMT_EVENT` options are enabled.
+If the options are enabled, the user is able to register a callback function
+that the net_mgmt thread is calling for each network management event.
+By default the net_mgmt event thread stack size is rather small.
+The idea is that the callback function does minimal things so that new
+events can be delivered to listeners as fast as possible and they are not lost.
+The net_mgmt event thread stack size is controlled by
+:kconfig:option:`CONFIG_NET_MGMT_EVENT_QUEUE_SIZE` option. It is recommended
+to not do any blocking operations in the callback function.
+
+The network thread stack utilization can be monitored from kernel shell by
+the **kernel threads** command.