Re: [PATCH] man/netem: rework man page

[Simon Horman <simon.horman@corigine.com>]

On Wed, Mar 08, 2023 at 10:47:02AM -0800, Stephen Hemminger wrote:
> Cleanup and rewrite netem man page.
> Incorporate the examples from the old LF netem wiki
> so that it can be removed/deprecated.
> 
> Reported-by: Jakub Kicinski <kuba@kernel.org>
> Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>

Thanks Stephen,

some minor editing suggestions from my side.

> ---
>  man/man8/tc-netem.8 | 423 ++++++++++++++++++++++++++++++--------------
>  1 file changed, 289 insertions(+), 134 deletions(-)
> 
> diff --git a/man/man8/tc-netem.8 b/man/man8/tc-netem.8
> index 217758541dea..b7172cddf955 100644
> --- a/man/man8/tc-netem.8
> +++ b/man/man8/tc-netem.8

...

> +.TP
> +.BI rate " RATE [ PACKETOVERHEAD [ CELLSIZE  [ CELLOVERHEAD ]]]"
> +delays packets based on packet size to emulate a fixed link speed.
> +Optional parameters:
> +.RS
> +.TP
>  .I PACKETOVERHEAD
> -(in bytes) specify an per packet overhead and can be negative. A positive value can be

nits:

Maybe your pronunciation is different to mine here.
But for it would be ' specify a per packet'.

And perhaps: ...overhead and can be' -> 'overhead. Can be...'

> -used to simulate additional link layer headers. A negative value can be used to
> -artificial strip the Ethernet header (e.g. -14) and/or simulate a link layer

'artificial' -> 'artificially'

...

>  .SH LIMITATIONS
> -The main known limitation of Netem are related to timer granularity, since
> -Linux is not a real-time operating system.
> +Netem is limited by the timer granularity in the kernel.
> +Rate and delay maybe impacted by clock interrupts.
> +.PP
> +Mixing forms of reordering may lead to unexpected results

Missing full stop (period) at the end of the line above.

> +For any method of reordering to work, some delay is necessary.
> +If the delay is less than the inter-packet arrival time then
> +no reordering will be seen.
> +Due to mechanisms like TSQ (TCP Small Queues), for TCP performance test results to be realistic netem must be placed on the ingress of the receiver host.
> +.PP
> +Combining netem with other qdisc is possible but may not always
> +work because netem use skb control block to set delays.
>  
>  .SH EXAMPLES
>  .PP
> -tc qdisc add dev eth0 root netem rate 5kbit 20 100 5
> +.EX
> +# tc qdisc add dev eth0 root netem delay 100ms
> +.EE
> +.RS 4
> +Add fixed amount of delay to all packets going out on device eth0.
> +Each packet will have added delay to be 100ms ± 10ms.

maybe 'to be' -> 'of'

> +.RE
> +.PP
> +.EX
> +# tc qdisc change dev eth0 root netem delay 100ms 10ms 25%
> +.EE
> +.RS 4
> +This causes the added delay to be 100ms ± 10ms with the next random element depending 25% on the last one.

Ditto.

Also, possibly
* 'last' -> 'previous'; or
* 'last' -> 'most recent'

> +This isn't true statistical correlation, but an approximation.

"isn't true" -> "isn't a true"

Also, possibly:
* '... correlation, but an approximation.'
  -> '... correlation. But, rather, an approximation.'

> +.RE
> +.PP
> +.EX
> +# tc qdisc change dev eth0 root netem delay 100ms 20ms distribution normal
> +.EE
> +.RS 4
> +Delays packets according to a normal distribution (Bell curve)
> +over a range of 100ms ± 20ms.

For consistency: This delays...

> +.RE
> +.PP
> +.EX
> +# tc qdisc change dev eth0 root netem loss 0.1%
> +.EE
> +.RS 4
> +This causes 1/10th of a percent (i.e 1 out of 1000) packets to be
> +randomly dropped.
> +
> +An optional correlation may also be added.
> +This causes the random number generator to be less random and can be used to emulate packet burst losses.
> +.RE
> +.PP
> +.EX
> +# tc qdisc change dev eth0 root netem duplicate 1%
> +.EE
> +.RS 4
> +Causes one percent of the packets sent on eth0 to be duplicated.

For consistency: This causes...

...

> +
> +.PP
> +Example of using rate control and cells size.
> +.EX
> +# tc qdisc add dev eth0 root netem rate 5kbit 20 100 5
> +.EE
>  .RS 4
>  delay all outgoing packets on device eth0 with a rate of 5kbit, a per packet

'delay' -> 'Delay'

...

> +Netem was written by Stephen Hemminger at Linux foundation and was
> +inspired by NISTnet.
> +
> +Original manpage was created by Fabio Ludovici
> +<fabio.ludovici at yahoo dot it> and Hagen Paul Pfeifer
> +<hagen@jauu.net>

Missing full stop (period) at the end of the line above.