[dpdk-dev] [RFC PATCH] ethdev: clarify flow action PORT ID semantics

[Andrew Rybchenko]

On 6/8/21 9:49 PM, Thomas Monjalon wrote:
> 08/06/2021 18:32, Andrew Rybchenko:
>> On 6/8/21 7:13 PM, Thomas Monjalon wrote:
>>> We will be at least 4 tomorrow Wednesday 3pm UTC.
>>> Everybody is welcome to join the community meeting:
>>> 	https://zoom.us/j/93391811485
>> Invite has July, 7. Typo?
> Yes was a typo, sorry.
> The invite was updated to tomorrow Wednesday June 9th.

Some input for the meeting. Done very quickly and a bit
late, but I hope still useful for the discussion.

Below is a very quick review of the ethdev API in attempt to understand
meaning of various functions if representor is a real ethdev port or
a shadow (configuration interface) of represented entity (VF, PF, SF
and may be even network port).

1. API with port_id+queue_id does not make sense if representor is
   a shadow of VF. Queues are fully controlled by guest OS.
    - rte_eth_tx_done_cleanup()
    - rte_eth_dev_rx_intr_enable()
    - rte_eth_dev_rx_intr_disable()
    - rte_eth_dev_rx_intr_ctl_q()
    - rte_eth_dev_rx_intr_ctl_q_get_fd()
    - rte_eth_set_queue_rate_limit()
    - rte_eth_add_rx_callback()
    - rte_eth_add_first_rx_callback()
    - rte_eth_remove_rx_callback()
    - rte_eth_add_tx_callback()
    - rte_eth_remove_tx_callback()
    - rte_eth_rx_queue_setup()
    - rte_eth_rx_hairpin_queue_setup()
    - rte_eth_tx_queue_setup()
    - rte_eth_tx_hairpin_queue_setup()
    - rte_eth_dev_rx_queue_start()
    - rte_eth_dev_rx_queue_stop()
    - rte_eth_dev_tx_queue_start()
    - rte_eth_dev_tx_queue_stop()
    - rte_eth_rx_queue_info_get()
    - rte_eth_tx_queue_info_get()
    - rte_eth_dev_set_tx_queue_stats_mapping()
    - rte_eth_dev_set_rx_queue_stats_mapping()
    - rte_eth_dev_set_vlan_strip_on_queue()
    - rte_eth_dev_rss_reta_update()
    - rte_eth_dev_rss_reta_query()
    - rte_eth_rx_burst_mode_get()
    - rte_eth_tx_burst_mode_get()
    - rte_eth_get_monitor_addr()
    - rte_eth_rx_burst()
    - rte_eth_rx_queue_count()
    - rte_eth_rx_descriptor_done()
    - rte_eth_rx_descriptor_status()
    - rte_eth_tx_descriptor_status()
    - rte_eth_tx_burst()
    - rte_eth_tx_prepare()
    - rte_eth_tx_buffer_flush()
    - rte_eth_tx_buffer()
    - rte_eth_dev_pool_ops_supported()
   Of course, we can say that representor port_id is a real
   ethdev port in this case, but it looks inconsistent.

2. Some API functions are essential in ethdev port life-cycle.

    2.1) rte_eth_dev_configure() is required to be real if
         representors are used for HW offload to receive
         slow path traffic. It configures real ethdev port
         queues, offloads, steering, interrupts etc.
         It never configures represented function (VF).

    2.2) rte_eth_dev_close() closes ethdev port itself (not VF)

    2.3) rte_eth_dev_start()/rte_eth_dev_stop() are required
         to be real similar to rte_eth_dev_configure()

    2.4) rte_eth_dev_info_get() could be a mixture in fact

3. A number of functions makes sense in both cases and
   looks a bit more natural if representor is a shadow of
   represented function (e.g. VF)

    3.1) rte_eth_dev_set_link_up()/rte_eth_dev_set_link_down()
         to administratively control if a VF can send/receive
         traffic.

    3.2) rte_eth_dev_reset() to enforce represented function
         reset to apply new settings.

    3.3) rte_eth_promiscuous_enable()/rte_eth_promiscuous_disable()/
         rte_eth_promiscuous_get()/rte_eth_allmulticast_enable()/
         rte_eth_allmulticast_disable()/rte_eth_allmulticast_get()
         to control if represented entity can receive corresponding
         traffic

    3.4) rte_eth_link_get()/rte_eth_link_get_nowait() ???

    3.5) rte_eth_macaddr_get()/rte_eth_dev_default_mac_addr_set()
         to provide and control administratively configured
         (and possibly enforced) MAC address of the represented entity

    3.6) rte_eth_dev_vlan_filter() can control (enforced?) VLAN
         filtering on represented entity

    3.7) rte_eth_dev_set_vlan_ether_type()/rte_eth_dev_set_vlan_pvid()
         may be used to configure transparent VLAN insertion
         (doable using RTE flow API VLAN_PUSH on transfer level)

    3.8) rte_eth_dev_set_vlan_offload()/rte_eth_dev_get_vlan_offload()
         may be used to control transparent VLAN stripping
         (doable using RTE flow API VLAN_POP on transfer level)
         See filter above.

    3.9) rte_eth_led_on()/rte_eth_led_off()
         makes sense for network port representors only

    3.10) rte_eth_fec_get_capability()/rte_eth_fec_get()/rte_eth_fec_set()
          makes sense for network port representors only

    3.11) rte_eth_dev_flow_ctrl_get()/rte_eth_dev_flow_ctrl_set()
          rte_eth_dev_priority_flow_ctrl_set()
          makes sense for network port representors only

    3.12) rte_eth_dev_mac_addr_add()/rte_eth_dev_mac_addr_remove()
          to control allowed MAC addresses for represented entity

    3.13) rte_eth_dev_udp_tunnel_port_add()/
          rte_eth_dev_udp_tunnel_port_delete()
          to administratively control UDP tunnels configuration and
          inform represented entity (set allowed entries)

    3.14) rte_eth_dev_set_mc_addr_list() to control allowed groups
          membership

4. Another group of functions which make sense in both cases, but
   more natural if representor is a real port.

    4.1) rte_eth_stats_get()/rte_eth_stats_reset()
         First of all, these stats report how many packets/bytes are
         received/sent by the DPDK application including per-queue
         figures.
         Of course, it makes sense for represented entity as well,
         but does not look as a primary meaning.

    4.2) rte_eth_xstats_get_names()/rte_eth_xstats_get()/
         rte_eth_xstats_get_names_by_id()/rte_eth_xstats_get_by_id()/
         rte_eth_xstats_get_id_by_name()/rte_eth_xstats_reset()
         similar to standard stats since include standard stats.
         Could provide information for both cases simultaneously in fact.

    4.3) rte_eth_dev_get_supported_ptypes()/rte_eth_dev_set_ptypes()
         it says what classification of packets DPDK app will see on Rx

    4.4) rte_eth_dev_get_mtu()/rte_eth_dev_set_mtu() since it is
         tightly related to size of Rx buffers and Rx offloads
         configuration, but definitely makes sense for represented
         entity.

    4.5) rte_eth_dev_callback_register()/rte_eth_dev_callback_unregister()
         seems to be more natural if representor is a real ethdev port

    4.6) rte_eth_dev_rss_hash_update()/rte_eth_dev_rss_hash_conf_get()
         but it could make sense for represented entity if we'd like
         to enforce something (unclear why we need it)

5. It does not matter for a number of functions since talking to HW anyway
    - rte_eth_dev_fw_version_get()
    - rte_eth_dev_get_reg_info()
    - rte_eth_dev_get_eeprom_length()
    - rte_eth_dev_get_eeprom()
    - rte_eth_dev_set_eeprom()
    - rte_eth_dev_get_module_info()
    - rte_eth_dev_get_module_eeprom()
    - rte_eth_timesync_enable()
    - rte_eth_timesync_disable()
    - rte_eth_timesync_read_rx_timestamp()
    - rte_eth_timesync_read_tx_timestamp()
    - rte_eth_timesync_adjust_time()
    - rte_eth_timesync_read_time()
    - rte_eth_timesync_write_time()
    - rte_eth_read_clock()
    - rte_eth_dev_hairpin_capability_get()
    - rte_eth_representor_info_get()

6. Not covered
    - rte_eth_dev_uc_hash_table_set()
    - rte_eth_dev_uc_all_hash_table_set()
    - rte_eth_mirror_rule_set()
    - rte_eth_mirror_rule_reset()
    - rte_eth_dev_get_dcb_info()
    - rte_eth_dev_get_sec_ctx()

Andrew.