From efe000d3d5991494adb53b8ce91e5d5255cc6300 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Thu, 15 Apr 2021 16:16:16 +0200 Subject: [PATCH 1/7] [docs] Added buffer configuration guide --- docs/API/configure-buffers.md | 113 ++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/API/configure-buffers.md diff --git a/docs/API/configure-buffers.md b/docs/API/configure-buffers.md new file mode 100644 index 000000000..bb74a2b09 --- /dev/null +++ b/docs/API/configure-buffers.md @@ -0,0 +1,113 @@ +# Configuration Guidelines + +## Receiver Buffer Size + +The receiver buffer can be configured with `SRTO_RCVBUF` socket option. +Buffer size in bytes is expected to be passed in the `optval` argument of the `srt_setsockopt(..)` function. +However, internally the value will be converted into the number of packets stored in the receiver buffer. + +The allowed value of `SRTO_RCVBUF` is also limited by the value of the flow control window size `SRTO_FC` socket option. +See issue [#700](https://github.com/Haivision/srt/issues/700). + +The default flow control window size is 25600 packets. It is approximately: + +- **270 Mbits** of payload in the default live streaming configuration with an SRT payload size of **1316 bytes**; +- **300 Mbits** of payload with an SRT payload size of **1456 bytes**. + +The default receiver buffer size is 8192 packets. It is approximately: +- **86 Mbits** of payload with the effective SRT payload size of **1316 bytes**. + +### Setting Receiver Buffer Size + +As already mentioned, the maximum allowed size of the receiver buffer is limited by the value of `SRTO_FC`. +Setting `SRTO_RCVBUF` option value using `srt_setsockopt(..)` function converts internally the provided size in bytes to size in packets +using the configured value of `SRTO_MSS` option to estimate the maximum possible payload of a packet. + +The following function returns the buffer size in packets: + +```c++ +int getRbufSizePkts(int SRTO_RCVBUF, int SRTO_MSS, int SRTO_FC) +{ + // UDP header size is assumed to be 28 bytes + // 20 bytes IPv4 + 8 bytes of UDP + const int UDPHDR_SIZE = 28; + const in pkts = (rbuf_size / (SRTO_MSS - UDPHDR_SIZE)); + + return min(pkts, SRTO_FC); +} +``` + +If `SRTO_RCVBUF` in packets exceeds `SRTO_FC`, then it is silently set to the value in bytes corresponding to `SRTO_FC`. +Therefore, to set higher values of `SRTO_RCVBUF` the value of `SRTO_FC` must be increased first. + +### Calculating Target Size In Packets + +The minimum size of the receiver buffer in packets can be calculated + +pktsRBufSize = bps / 8 × (RTTsec + latency_sec) / bytePayloadSize, + +where + +- `bps` - is the payload bitrate of the stream in bits per second; +- `RTTsec` - RTT of the network connection in seconds; + +- `bytePayloadSize` - expected size of the payload of SRT data packet. + +If the whole remainder of the MTU is expected to be used, + +bytePayloadSize = MSS - 44 + +- 44 - size of **IPv4** headers: + - 20 bytes **IPv4** + - 8 bytes of UDP + - 16 bytes of SRT packet header). + +- `MSS` - Maximum segment size (aka MTU), see `SRTO_MSS`. + +### Calculating Target Size to Set + +To determine the value to pass in `srt_setsockopt(..)` with `SRTO_RCVBUF` +the size in packets `pktsRBufSize` must be converted to the size in bytes +assuming the internal conversion of the `srt_setsockopt(..)` function. + +The target size of the payload stored by the receiver buffer would be + +SRTO_RCVBUF = pktsRBufSize × (SRTO_MSS - UDPHDR_SIZE) + +where +- `UDPHDR_SIZE = 28` (20 bytes IPv4, 8 bytes of UDP); +- `SRTO_MSS` is the corresponding socket option value at the moment of setting `SRTO_RCVBUF`. + + +### To Summ up + + +```c++ + +auto CalculateTargetRBufSize(int msRTT, int bpsRate, int bytesPayloadSize, int msLatency, int SRTO_MSS, int SRTO_FC) +{ + const int UDPHDR_SIZE = 28; + const int targetPayloadBytes = (msLatency + msRTT / 2) * bpsRate / 1000 / 8; + const int targetNumPackets = targetPayloadBytes / bytesPayloadSize; + const int targetSizeValue = targetNumPackets * (SRTO_MSS - UDPHDR_SIZE); + return {targetNumPackets, targetSizeValue}; +} + +// Configuring + +const auto [fc, rcvbuf] = CalculateTargetRBufSize(msRTT, bpsRate, bytesPayloadSize, SRTO_RCVLATENCY, SRTO_MSS, SRTO_FC); + +int optval = fc; +int optlen = sizeof optval; +srt_setsockopt(sock, 0, SRTO_FC, (void*) &optval, optlen); + +optval = rcvbuf; +srt_setsockopt(sock, 0, SRTO_RCVBUF, (void*) &optval, optlen); + + +``` + + + + + From e53ca477175ce185bd8a3bc7535f7a611f7b12e2 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Fri, 23 Apr 2021 11:56:30 +0200 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: stevomatthews --- docs/API/configure-buffers.md | 44 ++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/docs/API/configure-buffers.md b/docs/API/configure-buffers.md index bb74a2b09..b423f4f05 100644 --- a/docs/API/configure-buffers.md +++ b/docs/API/configure-buffers.md @@ -2,11 +2,11 @@ ## Receiver Buffer Size -The receiver buffer can be configured with `SRTO_RCVBUF` socket option. +The receiver buffer can be configured with the `SRTO_RCVBUF` socket option. Buffer size in bytes is expected to be passed in the `optval` argument of the `srt_setsockopt(..)` function. However, internally the value will be converted into the number of packets stored in the receiver buffer. -The allowed value of `SRTO_RCVBUF` is also limited by the value of the flow control window size `SRTO_FC` socket option. +The allowed value of `SRTO_RCVBUF` is also limited by the value of the flow control window size `SRTO_FC` socket option. See issue [#700](https://github.com/Haivision/srt/issues/700). The default flow control window size is 25600 packets. It is approximately: @@ -20,8 +20,8 @@ The default receiver buffer size is 8192 packets. It is approximately: ### Setting Receiver Buffer Size As already mentioned, the maximum allowed size of the receiver buffer is limited by the value of `SRTO_FC`. -Setting `SRTO_RCVBUF` option value using `srt_setsockopt(..)` function converts internally the provided size in bytes to size in packets -using the configured value of `SRTO_MSS` option to estimate the maximum possible payload of a packet. +When the`SRTO_RCVBUF` option value is set using the`srt_setsockopt(..)` the function internally converts the provided size in bytes to the corresponding size in packets +using the configured value of the `SRTO_MSS` option to estimate the maximum possible payload of a packet. The following function returns the buffer size in packets: @@ -37,32 +37,34 @@ int getRbufSizePkts(int SRTO_RCVBUF, int SRTO_MSS, int SRTO_FC) } ``` -If `SRTO_RCVBUF` in packets exceeds `SRTO_FC`, then it is silently set to the value in bytes corresponding to `SRTO_FC`. +If the value of `SRTO_RCVBUF` in packets exceeds `SRTO_FC`, then it is silently set to the value in bytes corresponding to `SRTO_FC`. Therefore, to set higher values of `SRTO_RCVBUF` the value of `SRTO_FC` must be increased first. -### Calculating Target Size In Packets +### Calculating Target Size in Packets -The minimum size of the receiver buffer in packets can be calculated +The minimum size of the receiver buffer in packets can be calculated as follows: -pktsRBufSize = bps / 8 × (RTTsec + latency_sec) / bytePayloadSize, +`pktsRBufSize = bps / 8 × (RTTsec + latency_sec) / bytePayloadSize` where -- `bps` - is the payload bitrate of the stream in bits per second; -- `RTTsec` - RTT of the network connection in seconds; +- `bps` is the payload bitrate of the stream in bits per second; +- `RTTsec` is the RTT of the network connection in seconds; -- `bytePayloadSize` - expected size of the payload of SRT data packet. +- `bytePayloadSize` is the expected size of the payload of the SRT data packet. -If the whole remainder of the MTU is expected to be used, +If the whole remainder of the MTU is expected to be used, payload size is calculated as follows: -bytePayloadSize = MSS - 44 +`bytePayloadSize = MSS - 44` -- 44 - size of **IPv4** headers: +where + +- 44 is the size in bytes of an **IPv4** header: - 20 bytes **IPv4** - 8 bytes of UDP - - 16 bytes of SRT packet header). + - 16 bytes of SRT packet header. -- `MSS` - Maximum segment size (aka MTU), see `SRTO_MSS`. +- `MSS` is the Maximum Segment Size (aka MTU); see `SRTO_MSS`. ### Calculating Target Size to Set @@ -70,16 +72,17 @@ To determine the value to pass in `srt_setsockopt(..)` with `SRTO_RCVBUF` the size in packets `pktsRBufSize` must be converted to the size in bytes assuming the internal conversion of the `srt_setsockopt(..)` function. -The target size of the payload stored by the receiver buffer would be +The target size of the payload stored by the receiver buffer would be: -SRTO_RCVBUF = pktsRBufSize × (SRTO_MSS - UDPHDR_SIZE) +`SRTO_RCVBUF = pktsRBufSize × (SRTO_MSS - UDPHDR_SIZE)` where -- `UDPHDR_SIZE = 28` (20 bytes IPv4, 8 bytes of UDP); + +- `UDPHDR_SIZE` = 28 (20 bytes IPv4, 8 bytes of UDP) - `SRTO_MSS` is the corresponding socket option value at the moment of setting `SRTO_RCVBUF`. -### To Summ up +### Summing Up ```c++ @@ -110,4 +113,3 @@ srt_setsockopt(sock, 0, SRTO_RCVBUF, (void*) &optval, optlen); - From 85ef718f914658d255d0e9ba000a5fd98eeeb3cd Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Fri, 23 Apr 2021 12:02:13 +0200 Subject: [PATCH 3/7] Minor correction --- docs/API/configure-buffers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/API/configure-buffers.md b/docs/API/configure-buffers.md index b423f4f05..a13f80485 100644 --- a/docs/API/configure-buffers.md +++ b/docs/API/configure-buffers.md @@ -12,7 +12,7 @@ See issue [#700](https://github.com/Haivision/srt/issues/700). The default flow control window size is 25600 packets. It is approximately: - **270 Mbits** of payload in the default live streaming configuration with an SRT payload size of **1316 bytes**; -- **300 Mbits** of payload with an SRT payload size of **1456 bytes**. +- **300 Mbits** of payload in the default file transfer configuration with an SRT payload size of **1456 bytes**. The default receiver buffer size is 8192 packets. It is approximately: - **86 Mbits** of payload with the effective SRT payload size of **1316 bytes**. From d62664a6a87c2e35dfdf4845050ea11c8802fe20 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Fri, 23 Apr 2021 12:28:57 +0200 Subject: [PATCH 4/7] Updated API/README.md --- docs/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 2d91117d7..aca9c23d0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,13 +9,14 @@ ## SRT API Documents -| Document Title | Folder | File Name | Description | -| :-------------------------------------------------- | :---------------------------- | :------------------------------------------------- | :--------------------------------------------------- | -| [SRT API](API/API.md) | [API](API/) | [API.md](API/API.md) | Detailed description of the SRT C API. | -| [SRT API Functions](API/API-functions.md) | [API](API/) | [API-functions.md](API/API-functions.md) | Reference document for SRT API functions. | -| [SRT API Socket Options](API/API-socket-options.md) | [API](API/) | [API-socket-options.md](API/API-socket-options.md) | Instructions and list of socket options for SRT API. | -| [SRT Statistics](API/statistics.md) | [API](API/) | [statistics.md](API/statistics.md) | How to use SRT socket and socket group statistics. | -| | | | | +| Document Title | Folder | File Name | Description | +| :----------------------------------------------------- | :---------------------------- | :------------------------------------------------- | :--------------------------------------------------- | +| [SRT API](API/API.md) | [API](API/) | [API.md](API/API.md) | Detailed description of the SRT C API. | +| [SRT API Functions](API/API-functions.md) | [API](API/) | [API-functions.md](API/API-functions.md) | Reference document for SRT API functions. | +| [SRT API Socket Options](API/API-socket-options.md) | [API](API/) | [API-socket-options.md](API/API-socket-options.md) | Instructions and list of socket options for SRT API. | +| [SRT Statistics](API/statistics.md) | [API](API/) | [statistics.md](API/statistics.md) | How to use SRT socket and socket group statistics. | +| [Buffer Configuration Guide](API/configure-buffers.md) | [API](API/) | [configure-buffers.md](API/configure-buffers.md) | How to configure SRT buffers. | +| | | | | ## Build Instructions From f9d128cb910b063c0771463f18d6616c8fccd883 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Tue, 18 May 2021 11:33:49 +0200 Subject: [PATCH 5/7] Renamed to configuration-guidelines.md --- docs/API/{configure-buffers.md => configuration-guidelines.md} | 0 docs/README.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/API/{configure-buffers.md => configuration-guidelines.md} (100%) diff --git a/docs/API/configure-buffers.md b/docs/API/configuration-guidelines.md similarity index 100% rename from docs/API/configure-buffers.md rename to docs/API/configuration-guidelines.md diff --git a/docs/README.md b/docs/README.md index aca9c23d0..2cf43db52 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,7 @@ | [SRT API Functions](API/API-functions.md) | [API](API/) | [API-functions.md](API/API-functions.md) | Reference document for SRT API functions. | | [SRT API Socket Options](API/API-socket-options.md) | [API](API/) | [API-socket-options.md](API/API-socket-options.md) | Instructions and list of socket options for SRT API. | | [SRT Statistics](API/statistics.md) | [API](API/) | [statistics.md](API/statistics.md) | How to use SRT socket and socket group statistics. | -| [Buffer Configuration Guide](API/configure-buffers.md) | [API](API/) | [configure-buffers.md](API/configure-buffers.md) | How to configure SRT buffers. | +| [Configuration Guidelines](API/configuration-guidelines.md) | [API](API/) | [configuration-guidelines.md](API/configuration-guidelines.md) | How to configure SRT buffers. | | | | | | ## Build Instructions From cc97f52ca170a410240189f6b77d67c1bbff5720 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Tue, 18 May 2021 11:35:38 +0200 Subject: [PATCH 6/7] Added some links --- docs/API/configuration-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/API/configuration-guidelines.md b/docs/API/configuration-guidelines.md index a13f80485..a8aeec815 100644 --- a/docs/API/configuration-guidelines.md +++ b/docs/API/configuration-guidelines.md @@ -2,11 +2,11 @@ ## Receiver Buffer Size -The receiver buffer can be configured with the `SRTO_RCVBUF` socket option. +The receiver buffer can be configured with the [`SRTO_RCVBUF`](./API-socket-options.md#SRTO_RCVBUF) socket option. Buffer size in bytes is expected to be passed in the `optval` argument of the `srt_setsockopt(..)` function. However, internally the value will be converted into the number of packets stored in the receiver buffer. -The allowed value of `SRTO_RCVBUF` is also limited by the value of the flow control window size `SRTO_FC` socket option. +The allowed value of `SRTO_RCVBUF` is also limited by the value of the flow control window size [`SRTO_FC`]((./API-socket-options.md#SRTO_FC) socket option. See issue [#700](https://github.com/Haivision/srt/issues/700). The default flow control window size is 25600 packets. It is approximately: From 645a822f76c94e2f8c26081ad1288d985c23e5d3 Mon Sep 17 00:00:00 2001 From: Maxim Sharabayko Date: Tue, 18 May 2021 11:40:35 +0200 Subject: [PATCH 7/7] Minor corrections --- docs/API/configuration-guidelines.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/API/configuration-guidelines.md b/docs/API/configuration-guidelines.md index a8aeec815..f0566d7d0 100644 --- a/docs/API/configuration-guidelines.md +++ b/docs/API/configuration-guidelines.md @@ -20,7 +20,8 @@ The default receiver buffer size is 8192 packets. It is approximately: ### Setting Receiver Buffer Size As already mentioned, the maximum allowed size of the receiver buffer is limited by the value of `SRTO_FC`. -When the`SRTO_RCVBUF` option value is set using the`srt_setsockopt(..)` the function internally converts the provided size in bytes to the corresponding size in packets +When the `SRTO_RCVBUF` option value is set using the `srt_setsockopt(..)` function, +the provided size in bytes is internally converted to the corresponding size in packets using the configured value of the `SRTO_MSS` option to estimate the maximum possible payload of a packet. The following function returns the buffer size in packets: @@ -106,10 +107,4 @@ srt_setsockopt(sock, 0, SRTO_FC, (void*) &optval, optlen); optval = rcvbuf; srt_setsockopt(sock, 0, SRTO_RCVBUF, (void*) &optval, optlen); - - ``` - - - -