From ce2a043e86120b734d3ea98a13fe93d528700e29 Mon Sep 17 00:00:00 2001 From: Sektor van Skijlen Date: Tue, 19 Sep 2023 08:38:11 +0200 Subject: [PATCH] Apply SOME suggestions from the doc review (others pending) Co-authored-by: stevomatthews --- docs/API/API-socket-options.md | 62 ++++++++++++++++------------------ 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/docs/API/API-socket-options.md b/docs/API/API-socket-options.md index ec2f5400d..cb6b88f2e 100644 --- a/docs/API/API-socket-options.md +++ b/docs/API/API-socket-options.md @@ -947,20 +947,19 @@ following cases: * when the current socket's binding address is of IPv4 domain * when the peer's address is an IPv6-mapped-IPv4 address -The IPv6 in-transmission IP version is assumed only if the peer's address -is a true IPv6 address (not IPv4 mapped). It is then not possible to determine -what the payload size limit until the connection is established. Parts of the -SRT facilities that must allocate any resources according to this value prior -to connecting are using the layout as per IPv4 because this way they allocate -more space than needed in the worst case. +The IPv6 transmission case is assumed only if the peer's address is a true IPv6 address +(not IPv4 mapped). It is then not possible to determine the payload size limit +until the connection is established. SRT operations that must allocate any +resources according to this value prior to connecting will assume IPv4 transmission +because this way, in the worst case, they allocate more space than needed . This value can be set on both connection parties independently, but after -connection this option gets an effectively negotiated value, which is the less -one from both parties. If this effective value is too small on any of the +connection `SRTO_MSS` gets a negotiated value, which is the lesser +of the two. If this effective value is too small for either of the connection peers, the connection is rejected (or late-rejected on the caller side). -This value then effectively controls: +This value then controls: * The maximum size of the payload in a single UDP packet ("remaining space"). @@ -970,24 +969,23 @@ in the IPv4 layout case (1472 bytes per packet for MSS=1500). The reason for it is that some buffer resources are allocated prior to the connection, so this value must fit both IPv4 and IPv6 for buffer memory allocation. -The default value 1500 matches the standard MTU size for network devices. It -is recommended that this value be set at maximum to the value of MTU size of -the network device that you will use for connection. - -Detailed recommendations for this value differ in the file and live mode. - -In the live mode a single call to `srt_send*` function may only send data -that fit in one packet. This size is defined by the `SRTO_PAYLOADSIZE` -option (defult: 1316) and it is also the size of the data in a single UDP -packet. To save memory space, you may want then to set MSS in live mode to -a value for which the "remaining space" matches `SRTO_PAYLOADSIZE` value (for -default 1316 it will be 1360 for IPv4 and 1372 for IPv6). This is not done by -default for security reasons: this may potentially lead to inability to read an -incoming UDP packet if its size is by some reason bigger than the negotiated MSS. -This may lead to misleading situations and hard to detect errors. You should -set such a value only if the peer is trusted (that is, you can be certain that -it will never come to a situation of having received an oversized UDP packet -over the link used for the connection). See also limitations for +The default value of 1500 corresponds to the standard MTU size for network devices. It +is recommended that this value be set to the maximum MTU size of +the network device that you will use for the connection. + +The recommendations for the value of `SRTO_MSS` differ between file and live modes. + +In live mode a single call to the `srt_send*` function may only send data +that fits in one packet. This size is defined by the `SRTO_PAYLOADSIZE` +option (defult: 1316), and it is also the size of the data in a single UDP +packet. To save memory space, you may want then to set `SRTO_MSS` in live mode to +a value for which the "remaining space" matches the `SRTO_PAYLOADSIZE` value (for +the default value of 1316 this will be 1360 for IPv4 and 1372 for IPv6). For security reasons, +this is not done by default: it may potentially lead to the inability to read an incoming UDP +packet if its size is for some reason bigger than the negotiated MSS, which may in turn lead +to unpredictable behaviour and hard-to-detect errors. You should set such a value only if +the peer is trusted (that is, you can be certain that you will never receive an oversized UDP +packet over the link used for the connection). You should also consider the limitations of `SRTO_PAYLOADSIZE`. In the file mode `SRTO_PAYLOADSIZE` has a special value 0 that means no limit @@ -998,12 +996,12 @@ the current network device's MTU size. Setting a greater value is possible (maximum for the system API is 65535), but it may lead to packet fragmentation on the system level. This is highly unwanted in SRT because: -* Here SRT does also its own fragmentation, so it would be counter-productive -* It would use more system resources with no advantage -* SRT is unaware of it, so the statistics will be slightly falsified +* SRT also performs its own fragmentation, so it would be counter-productive +* It would use more system resources to no advantage +* SRT is unaware of it, so the resulting statistics would be slightly misleading -The system-level packet fragmentation cannot be however reliably turned off; -the best approach is then to avoid it by using appropriate parameters. +System-level packet fragmentation cannot be reliably turned off, +so safest approach is to avoid it by using appropriate parameters. [Return to list](#list-of-options)