Re: [PATCH net-next v1 3/8] net: ieee8021q: clarify the tt_to_tc() traffic-class mapping

[Luiz Angelo Daros de Luca]

> Document that the tt_to_tc() traffic-class numbers are the pre-computed
> composition of Table I-2 (traffic type -> priority) with Table 8-5
> (priority -> traffic class). Note that Table 8-5 is the mapping for
> implementations without the credit-based shaper, so the helper's scope
> is clear; credit-based-shaper implementations use Table 34-1/34-2
> instead.
>
> The existing kdoc cited Annex I Table I-1 as the mapping basis, but
> Table I-1 only partitions traffic types into classes; it does not assign
> the class numbers.
>
> Signed-off-by: Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx>

Looks good to me. Please just make sure `make htmldocs` builds cleanly
without warnings and renders the ASCII diagram properly.

Reviewed-by: Luiz Angelo Daros de Luca <luizluca@xxxxxxxxx>

> ---
>  net/core/ieee8021q_helpers.c | 30 +++++++++++++++++-------------
>  1 file changed, 17 insertions(+), 13 deletions(-)
>
> diff --git a/net/core/ieee8021q_helpers.c b/net/core/ieee8021q_helpers.c
> index a5bd5e039b47..520d86d592eb 100644
> --- a/net/core/ieee8021q_helpers.c
> +++ b/net/core/ieee8021q_helpers.c
> @@ -12,10 +12,10 @@
>         compiletime_assert(ARRAY_SIZE(tbl) == IEEE8021Q_TT_MAX, \
>                            #tbl " size mismatch")
>
> -/* The following arrays map Traffic Types (TT) to traffic classes (TC) for
> - * different number of queues as shown in the example provided by
> - * IEEE 802.1Q-2022 in Annex I "I.3 Traffic type to traffic class mapping" and
> - * Table I-1 "Traffic type to traffic class mapping".
> +/* The following arrays map a traffic type (TT) to a traffic class (TC) for
> + * each supported number of queues. The mapping is the traffic-type -> priority
> + * -> traffic-class composition documented in the ieee8021q_tt_to_tc() kdoc
> + * below, reduced for the given number of queues.
>   */
>  static const u8 ieee8021q_8queue_tt_tc_map[] = {
>         [IEEE8021Q_TT_BK] = 0,
> @@ -84,17 +84,21 @@ static const u8 ieee8021q_1queue_tt_tc_map[] = {
>  };
>
>  /**
> - * ieee8021q_tt_to_tc - Map IEEE 802.1Q Traffic Type to Traffic Class
> - * @tt: IEEE 802.1Q Traffic Type
> - * @num_queues: Number of queues
> + * ieee8021q_tt_to_tc - Map an IEEE 802.1Q traffic type to a traffic class
> + * @tt: IEEE 802.1Q traffic type
> + * @num_queues: number of traffic classes (queues) available, 1..8
>   *
> - * This function maps an IEEE 802.1Q Traffic Type to a Traffic Class (TC) based
> - * on the number of queues configured on the NIC. The mapping is based on the
> - * example provided by IEEE 802.1Q-2022 in Annex I "I.3 Traffic type to traffic
> - * class mapping" and Table I-1 "Traffic type to traffic class mapping".
> + * Return the traffic-class number for @tt. It is the pre-computed composition
> + * of two IEEE 802.1Q-2022 mappings:
>   *
> - * Return: Traffic Class corresponding to the given Traffic Type or negative
> - * value in case of error.
> + *   traffic type --[Table I-2]--> priority --[Table 8-5]--> traffic class
> + *
> + * Table 8-5 is the priority-to-traffic-class mapping for implementations that
> + * do NOT support the credit-based shaper (8.6.8.2). Credit-based-shaper
> + * implementations use a different mapping (Table 34-1 for SR classes A and B,
> + * or Table 34-2 for SR class B only), which this helper does not implement.
> + *
> + * Return: the traffic class, or a negative value on error.
>   */
>  int ieee8021q_tt_to_tc(enum ieee8021q_traffic_type tt, unsigned int num_queues)
>  {
> --
> 2.47.3
>