From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id A45C3A0550; Fri, 26 Aug 2022 14:44:49 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 732FB42B8E; Fri, 26 Aug 2022 14:44:08 +0200 (CEST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mails.dpdk.org (Postfix) with ESMTP id D7E954282B for ; Fri, 26 Aug 2022 14:44:06 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1661517846; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZgYygOksH2QWrLkJaE/qMQipTv5n537fDmkpzZOEzic=; b=Z/tsBHXvwShG2h+jhkDKjCEIgNH2KxetTohyKu/EB/BrEtqyJPQ6hkox2O+UcXYIhhOMRa dsQp3pTlA6OsC4f3Ui4GpUTUCe6eIryNrWO8f06dD2oF53/s3oIMXNxs3LARlQOjvwx/eI sFAKaAOT35Bvbo6gpKdKnMcXauLT6Ss= Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-515-gSPLmn8BPoe0utANQoD7rg-1; Fri, 26 Aug 2022 08:44:05 -0400 X-MC-Unique: gSPLmn8BPoe0utANQoD7rg-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 09BB11C05151; Fri, 26 Aug 2022 12:44:04 +0000 (UTC) Received: from fchome.redhat.com (unknown [10.40.193.251]) by smtp.corp.redhat.com (Postfix) with ESMTP id BDA22C15BB3; Fri, 26 Aug 2022 12:43:59 +0000 (UTC) From: David Marchand To: dev@dpdk.org Cc: thomas@monjalon.net, bruce.richardson@intel.com, Ray Kinsella , Parav Pandit , Xueming Li , Hemant Agrawal , Sachin Saxena , Rosen Xu , Anatoly Burakov , Stephen Hemminger , Long Li , Matan Azrad , Viacheslav Ovsiienko , Kevin Laatz , Chas Williams , "Min Hu (Connor)" , Gaetan Rivet , Maxime Coquelin , Chenbo Xia , Ferruh Yigit , Andrew Rybchenko , Reshma Pattan Subject: [PATCH v4 21/27] bus: hide bus object Date: Fri, 26 Aug 2022 14:42:02 +0200 Message-Id: <20220826124208.671400-22-david.marchand@redhat.com> In-Reply-To: <20220826124208.671400-1-david.marchand@redhat.com> References: <20220628144643.1213026-1-david.marchand@redhat.com> <20220826124208.671400-1-david.marchand@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="US-ASCII"; x-default=true X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Make rte_bus opaque for non internal users. This will make extending this object possible without breaking the ABI. Introduce a new driver header and move rte_bus definition and helpers. Update drivers and library to use the internal header. Some applications may have been dereferencing rte_bus objects, mark this object's accessors as stable. Signed-off-by: David Marchand Acked-by: Bruce Richardson --- Changes since RFC v2: - updated release notes, - marked accessors as stable, Changes since RFC v1: - update all existing users of the public header to use the internal one, --- app/test/test_devargs.c | 2 +- app/test/test_vdev.c | 2 +- doc/guides/rel_notes/deprecation.rst | 6 - doc/guides/rel_notes/release_22_11.rst | 6 + drivers/bus/auxiliary/auxiliary_common.c | 2 +- drivers/bus/auxiliary/auxiliary_params.c | 2 +- drivers/bus/auxiliary/private.h | 2 +- drivers/bus/dpaa/dpaa_bus.c | 2 +- drivers/bus/fslmc/fslmc_bus.c | 2 +- drivers/bus/fslmc/private.h | 2 +- drivers/bus/ifpga/ifpga_bus.c | 2 +- drivers/bus/pci/linux/pci_vfio.c | 2 +- drivers/bus/pci/pci_common.c | 2 +- drivers/bus/pci/pci_params.c | 2 +- drivers/bus/pci/private.h | 2 +- drivers/bus/vdev/vdev.c | 2 +- drivers/bus/vmbus/private.h | 2 +- drivers/common/mlx5/mlx5_common_pci.c | 2 +- drivers/dma/idxd/idxd_bus.c | 2 +- drivers/net/bonding/rte_eth_bond_args.c | 2 +- drivers/net/failsafe/failsafe.c | 2 +- drivers/net/failsafe/failsafe_eal.c | 2 +- drivers/net/mlx5/linux/mlx5_os.c | 2 +- drivers/net/netvsc/hn_ethdev.c | 2 +- drivers/net/vdev_netvsc/vdev_netvsc.c | 2 +- drivers/net/virtio/virtio_pci.c | 2 +- drivers/raw/ioat/idxd_bus.c | 2 +- lib/eal/common/eal_common_bus.c | 2 +- lib/eal/common/eal_common_dev.c | 2 +- lib/eal/common/eal_common_devargs.c | 2 +- lib/eal/common/hotplug_mp.c | 2 +- lib/eal/include/bus_driver.h | 296 +++++++++++++++++++++++ lib/eal/include/meson.build | 4 + lib/eal/include/rte_bus.h | 278 +-------------------- lib/eal/linux/eal_dev.c | 2 +- lib/eal/version.map | 8 +- lib/ethdev/rte_ethdev.c | 2 +- lib/pcapng/rte_pcapng.c | 2 +- 38 files changed, 343 insertions(+), 319 deletions(-) create mode 100644 lib/eal/include/bus_driver.h diff --git a/app/test/test_devargs.c b/app/test/test_devargs.c index ac5bc34c18..0a4c34a1ad 100644 --- a/app/test/test_devargs.c +++ b/app/test/test_devargs.c @@ -9,7 +9,7 @@ #include #include #include -#include +#include #include #include "test.h" diff --git a/app/test/test_vdev.c b/app/test/test_vdev.c index 3cc3abe70b..c3a8ad64bb 100644 --- a/app/test/test_vdev.c +++ b/app/test/test_vdev.c @@ -8,7 +8,7 @@ #include #include -#include +#include #include #include "test.h" diff --git a/doc/guides/rel_notes/deprecation.rst b/doc/guides/rel_notes/deprecation.rst index 5b4ffc992d..98a00da385 100644 --- a/doc/guides/rel_notes/deprecation.rst +++ b/doc/guides/rel_notes/deprecation.rst @@ -47,12 +47,6 @@ Deprecation Notices * mempool: The mempool API macros ``MEMPOOL_PG_*`` are deprecated and will be removed in DPDK 22.11. -* bus: The ``rte_bus`` object will be made opaque in DPDK 22.11. - The goal is to remove it from the public ABI and make this object extendable. - As a side effect, registering a bus will be marked as an internal API: - external users may still register their bus using a new driver header - (see ``enable_driver_sdk`` meson option). - * drivers: As a follow-up of the work on the ``rte_bus`` object, the ``rte_driver`` and ``rte_device`` objects (and as a domino effect, their bus-specific counterparts) will be made opaque in DPDK 22.11. diff --git a/doc/guides/rel_notes/release_22_11.rst b/doc/guides/rel_notes/release_22_11.rst index e08a548285..36df0ccf93 100644 --- a/doc/guides/rel_notes/release_22_11.rst +++ b/doc/guides/rel_notes/release_22_11.rst @@ -88,6 +88,12 @@ API Changes in the future. Applications can use ``devtools/cocci/func_or_ret.cocci`` to update their code. +* bus: Registering a bus has been marked as an internal API. + External users may still register their bus using the ``bus_driver.h`` + driver header (see ``enable_driver_sdk`` meson option). + The ``rte_bus`` object is now opaque and must be manipulated through added + accessors. + * drivers: Registering a driver on the ``auxiliary``, ``ifpga``, ``pci``, ``vdev``, ``vmbus`` buses has been marked as an internal API. External users may still register their driver using the associated driver diff --git a/drivers/bus/auxiliary/auxiliary_common.c b/drivers/bus/auxiliary/auxiliary_common.c index 6cf6c170ec..259ff152c4 100644 --- a/drivers/bus/auxiliary/auxiliary_common.c +++ b/drivers/bus/auxiliary/auxiliary_common.c @@ -12,7 +12,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/drivers/bus/auxiliary/auxiliary_params.c b/drivers/bus/auxiliary/auxiliary_params.c index 0289777922..a889e392c6 100644 --- a/drivers/bus/auxiliary/auxiliary_params.c +++ b/drivers/bus/auxiliary/auxiliary_params.c @@ -4,7 +4,7 @@ #include -#include +#include #include #include #include diff --git a/drivers/bus/auxiliary/private.h b/drivers/bus/auxiliary/private.h index 3f49f62493..3dee13e1d1 100644 --- a/drivers/bus/auxiliary/private.h +++ b/drivers/bus/auxiliary/private.h @@ -9,7 +9,7 @@ #include #include -#include +#include #include "bus_auxiliary_driver.h" diff --git a/drivers/bus/dpaa/dpaa_bus.c b/drivers/bus/dpaa/dpaa_bus.c index 1ac6aa314f..682427ba2c 100644 --- a/drivers/bus/dpaa/dpaa_bus.c +++ b/drivers/bus/dpaa/dpaa_bus.c @@ -29,7 +29,7 @@ #include #include #include -#include +#include #include #include diff --git a/drivers/bus/fslmc/fslmc_bus.c b/drivers/bus/fslmc/fslmc_bus.c index b9b0981329..8503004e3d 100644 --- a/drivers/bus/fslmc/fslmc_bus.c +++ b/drivers/bus/fslmc/fslmc_bus.c @@ -9,7 +9,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/bus/fslmc/private.h b/drivers/bus/fslmc/private.h index 60d68155e1..6f14085d98 100644 --- a/drivers/bus/fslmc/private.h +++ b/drivers/bus/fslmc/private.h @@ -5,7 +5,7 @@ #ifndef BUS_FSLMC_PRIVATE_H #define BUS_FSLMC_PRIVATE_H -#include +#include #include diff --git a/drivers/bus/ifpga/ifpga_bus.c b/drivers/bus/ifpga/ifpga_bus.c index 27e2de7072..bb943b58b5 100644 --- a/drivers/bus/ifpga/ifpga_bus.c +++ b/drivers/bus/ifpga/ifpga_bus.c @@ -14,7 +14,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/bus/pci/linux/pci_vfio.c b/drivers/bus/pci/linux/pci_vfio.c index cd0d0b1670..fab3483d9f 100644 --- a/drivers/bus/pci/linux/pci_vfio.c +++ b/drivers/bus/pci/linux/pci_vfio.c @@ -18,7 +18,7 @@ #include #include #include -#include +#include #include #include diff --git a/drivers/bus/pci/pci_common.c b/drivers/bus/pci/pci_common.c index 0d61d49287..c26aacd364 100644 --- a/drivers/bus/pci/pci_common.c +++ b/drivers/bus/pci/pci_common.c @@ -13,7 +13,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/drivers/bus/pci/pci_params.c b/drivers/bus/pci/pci_params.c index 61a868707f..39d702a418 100644 --- a/drivers/bus/pci/pci_params.c +++ b/drivers/bus/pci/pci_params.c @@ -4,7 +4,7 @@ #include -#include +#include #include #include #include diff --git a/drivers/bus/pci/private.h b/drivers/bus/pci/private.h index 4e40a2ed85..fddf49251d 100644 --- a/drivers/bus/pci/private.h +++ b/drivers/bus/pci/private.h @@ -8,7 +8,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/bus/vdev/vdev.c b/drivers/bus/vdev/vdev.c index 7d78cf93bc..809a8bb08f 100644 --- a/drivers/bus/vdev/vdev.c +++ b/drivers/bus/vdev/vdev.c @@ -12,7 +12,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/bus/vmbus/private.h b/drivers/bus/vmbus/private.h index 3d233fa83c..e33424675c 100644 --- a/drivers/bus/vmbus/private.h +++ b/drivers/bus/vmbus/private.h @@ -9,7 +9,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/common/mlx5/mlx5_common_pci.c b/drivers/common/mlx5/mlx5_common_pci.c index e82cb881bf..73178ce0f3 100644 --- a/drivers/common/mlx5/mlx5_common_pci.c +++ b/drivers/common/mlx5/mlx5_common_pci.c @@ -9,7 +9,7 @@ #include #include #include -#include +#include #include #include "mlx5_common_log.h" diff --git a/drivers/dma/idxd/idxd_bus.c b/drivers/dma/idxd/idxd_bus.c index 13cb967f6d..e30dcfc281 100644 --- a/drivers/dma/idxd/idxd_bus.c +++ b/drivers/dma/idxd/idxd_bus.c @@ -8,7 +8,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/net/bonding/rte_eth_bond_args.c b/drivers/net/bonding/rte_eth_bond_args.c index 1a86eb3c00..6553166f5c 100644 --- a/drivers/net/bonding/rte_eth_bond_args.c +++ b/drivers/net/bonding/rte_eth_bond_args.c @@ -4,7 +4,7 @@ #include #include -#include +#include #include #include diff --git a/drivers/net/failsafe/failsafe.c b/drivers/net/failsafe/failsafe.c index 5d4d52c341..32811403b4 100644 --- a/drivers/net/failsafe/failsafe.c +++ b/drivers/net/failsafe/failsafe.c @@ -11,7 +11,7 @@ #include #include #include -#include +#include #include #include "failsafe_private.h" diff --git a/drivers/net/failsafe/failsafe_eal.c b/drivers/net/failsafe/failsafe_eal.c index 130344dce2..d71b512f81 100644 --- a/drivers/net/failsafe/failsafe_eal.c +++ b/drivers/net/failsafe/failsafe_eal.c @@ -3,7 +3,7 @@ * Copyright 2017 Mellanox Technologies, Ltd */ -#include +#include #include #include diff --git a/drivers/net/mlx5/linux/mlx5_os.c b/drivers/net/mlx5/linux/mlx5_os.c index efb262e368..4f0a6f4d55 100644 --- a/drivers/net/mlx5/linux/mlx5_os.c +++ b/drivers/net/mlx5/linux/mlx5_os.c @@ -19,7 +19,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/drivers/net/netvsc/hn_ethdev.c b/drivers/net/netvsc/hn_ethdev.c index 188d92ffac..ccc06bdda6 100644 --- a/drivers/net/netvsc/hn_ethdev.c +++ b/drivers/net/netvsc/hn_ethdev.c @@ -31,7 +31,7 @@ #include #include #include -#include +#include #include #include diff --git a/drivers/net/vdev_netvsc/vdev_netvsc.c b/drivers/net/vdev_netvsc/vdev_netvsc.c index 65043a04eb..dc90569df1 100644 --- a/drivers/net/vdev_netvsc/vdev_netvsc.c +++ b/drivers/net/vdev_netvsc/vdev_netvsc.c @@ -24,7 +24,7 @@ #include #include -#include +#include #include #include #include diff --git a/drivers/net/virtio/virtio_pci.c b/drivers/net/virtio/virtio_pci.c index 632451dcbe..9cf4d760b4 100644 --- a/drivers/net/virtio/virtio_pci.c +++ b/drivers/net/virtio/virtio_pci.c @@ -9,7 +9,7 @@ #endif #include -#include +#include #include "virtio_pci.h" #include "virtio_logs.h" diff --git a/drivers/raw/ioat/idxd_bus.c b/drivers/raw/ioat/idxd_bus.c index 539f51b1b1..f32d811055 100644 --- a/drivers/raw/ioat/idxd_bus.c +++ b/drivers/raw/ioat/idxd_bus.c @@ -10,7 +10,7 @@ #include #include -#include +#include #include #include #include "ioat_private.h" diff --git a/lib/eal/common/eal_common_bus.c b/lib/eal/common/eal_common_bus.c index cbf382f967..be64d31b0f 100644 --- a/lib/eal/common/eal_common_bus.c +++ b/lib/eal/common/eal_common_bus.c @@ -6,7 +6,7 @@ #include #include -#include +#include #include #include #include diff --git a/lib/eal/common/eal_common_dev.c b/lib/eal/common/eal_common_dev.c index b6f0392f30..62a598957c 100644 --- a/lib/eal/common/eal_common_dev.c +++ b/lib/eal/common/eal_common_dev.c @@ -7,7 +7,7 @@ #include #include -#include +#include #include #include #include diff --git a/lib/eal/common/eal_common_devargs.c b/lib/eal/common/eal_common_devargs.c index d5833af373..03e6e59baf 100644 --- a/lib/eal/common/eal_common_devargs.c +++ b/lib/eal/common/eal_common_devargs.c @@ -10,7 +10,7 @@ #include #include -#include +#include #include #include #include diff --git a/lib/eal/common/hotplug_mp.c b/lib/eal/common/hotplug_mp.c index 1614a57752..5202bd5658 100644 --- a/lib/eal/common/hotplug_mp.c +++ b/lib/eal/common/hotplug_mp.c @@ -3,7 +3,7 @@ */ #include -#include +#include #include #include #include diff --git a/lib/eal/include/bus_driver.h b/lib/eal/include/bus_driver.h new file mode 100644 index 0000000000..d2e615a736 --- /dev/null +++ b/lib/eal/include/bus_driver.h @@ -0,0 +1,296 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2022 Red Hat, Inc. + */ + +#ifndef BUS_DRIVER_H +#define BUS_DRIVER_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include +#include +#include +#include +#include + +struct rte_devargs; +struct rte_device; + +/** Double linked list of buses */ +RTE_TAILQ_HEAD(rte_bus_list, rte_bus); + +/** + * Bus specific scan for devices attached on the bus. + * For each bus object, the scan would be responsible for finding devices and + * adding them to its private device list. + * + * A bus should mandatorily implement this method. + * + * @return + * 0 for successful scan + * <0 for unsuccessful scan with error value + */ +typedef int (*rte_bus_scan_t)(void); + +/** + * Implementation specific probe function which is responsible for linking + * devices on that bus with applicable drivers. + * + * This is called while iterating over each registered bus. + * + * @return + * 0 for successful probe + * !0 for any error while probing + */ +typedef int (*rte_bus_probe_t)(void); + +/** + * Device iterator to find a device on a bus. + * + * This function returns an rte_device if one of those held by the bus + * matches the data passed as parameter. + * + * If the comparison function returns zero this function should stop iterating + * over any more devices. To continue a search the device of a previous search + * can be passed via the start parameter. + * + * @param cmp + * Comparison function. + * + * @param data + * Data to compare each device against. + * + * @param start + * starting point for the iteration + * + * @return + * The first device matching the data, NULL if none exists. + */ +typedef struct rte_device * +(*rte_bus_find_device_t)(const struct rte_device *start, rte_dev_cmp_t cmp, + const void *data); + +/** + * Implementation specific probe function which is responsible for linking + * devices on that bus with applicable drivers. + * + * @param dev + * Device pointer that was returned by a previous call to find_device. + * + * @return + * 0 on success. + * !0 on error. + */ +typedef int (*rte_bus_plug_t)(struct rte_device *dev); + +/** + * Implementation specific remove function which is responsible for unlinking + * devices on that bus from assigned driver. + * + * @param dev + * Device pointer that was returned by a previous call to find_device. + * + * @return + * 0 on success. + * !0 on error. + */ +typedef int (*rte_bus_unplug_t)(struct rte_device *dev); + +/** + * Bus specific parsing function. + * Validates the syntax used in the textual representation of a device, + * If the syntax is valid and ``addr`` is not NULL, writes the bus-specific + * device representation to ``addr``. + * + * @param[in] name + * device textual description + * + * @param[out] addr + * device information location address, into which parsed info + * should be written. If NULL, nothing should be written, which + * is not an error. + * + * @return + * 0 if parsing was successful. + * !0 for any error. + */ +typedef int (*rte_bus_parse_t)(const char *name, void *addr); + +/** + * Parse bus part of the device arguments. + * + * The field name of the struct rte_devargs will be set. + * + * @param da + * Pointer to the devargs to parse. + * + * @return + * 0 on successful parsing, otherwise rte_errno is set. + * -EINVAL: on parsing error. + * -ENODEV: if no key matching a device argument is specified. + * -E2BIG: device name is too long. + */ +typedef int (*rte_bus_devargs_parse_t)(struct rte_devargs *da); + +/** + * Device level DMA map function. + * After a successful call, the memory segment will be mapped to the + * given device. + * + * @param dev + * Device pointer. + * @param addr + * Virtual address to map. + * @param iova + * IOVA address to map. + * @param len + * Length of the memory segment being mapped. + * + * @return + * 0 if mapping was successful. + * Negative value and rte_errno is set otherwise. + */ +typedef int (*rte_dev_dma_map_t)(struct rte_device *dev, void *addr, + uint64_t iova, size_t len); + +/** + * Device level DMA unmap function. + * After a successful call, the memory segment will no longer be + * accessible by the given device. + * + * @param dev + * Device pointer. + * @param addr + * Virtual address to unmap. + * @param iova + * IOVA address to unmap. + * @param len + * Length of the memory segment being mapped. + * + * @return + * 0 if un-mapping was successful. + * Negative value and rte_errno is set otherwise. + */ +typedef int (*rte_dev_dma_unmap_t)(struct rte_device *dev, void *addr, + uint64_t iova, size_t len); + +/** + * Implement a specific hot-unplug handler, which is responsible for + * handle the failure when device be hot-unplugged. When the event of + * hot-unplug be detected, it could call this function to handle + * the hot-unplug failure and avoid app crash. + * @param dev + * Pointer of the device structure. + * + * @return + * 0 on success. + * !0 on error. + */ +typedef int (*rte_bus_hot_unplug_handler_t)(struct rte_device *dev); + +/** + * Implement a specific sigbus handler, which is responsible for handling + * the sigbus error which is either original memory error, or specific memory + * error that caused of device be hot-unplugged. When sigbus error be captured, + * it could call this function to handle sigbus error. + * @param failure_addr + * Pointer of the fault address of the sigbus error. + * + * @return + * 0 for success handle the sigbus for hot-unplug. + * 1 for not process it, because it is a generic sigbus error. + * -1 for failed to handle the sigbus for hot-unplug. + */ +typedef int (*rte_bus_sigbus_handler_t)(const void *failure_addr); + +/** + * Bus scan policies + */ +enum rte_bus_scan_mode { + RTE_BUS_SCAN_UNDEFINED, + RTE_BUS_SCAN_ALLOWLIST, + RTE_BUS_SCAN_BLOCKLIST, +}; + +/** + * A structure used to configure bus operations. + */ +struct rte_bus_conf { + enum rte_bus_scan_mode scan_mode; /**< Scan policy. */ +}; + + +/** + * Get common iommu class of the all the devices on the bus. The bus may + * check that those devices are attached to iommu driver. + * If no devices are attached to the bus. The bus may return with don't care + * (_DC) value. + * Otherwise, The bus will return appropriate _pa or _va iova mode. + * + * @return + * enum rte_iova_mode value. + */ +typedef enum rte_iova_mode (*rte_bus_get_iommu_class_t)(void); + +/** + * A structure describing a generic bus. + */ +struct rte_bus { + RTE_TAILQ_ENTRY(rte_bus) next; /**< Next bus object in linked list */ + const char *name; /**< Name of the bus */ + rte_bus_scan_t scan; /**< Scan for devices attached to bus */ + rte_bus_probe_t probe; /**< Probe devices on bus */ + rte_bus_find_device_t find_device; /**< Find a device on the bus */ + rte_bus_plug_t plug; /**< Probe single device for drivers */ + rte_bus_unplug_t unplug; /**< Remove single device from driver */ + rte_bus_parse_t parse; /**< Parse a device name */ + rte_bus_devargs_parse_t devargs_parse; /**< Parse bus devargs */ + rte_dev_dma_map_t dma_map; /**< DMA map for device in the bus */ + rte_dev_dma_unmap_t dma_unmap; /**< DMA unmap for device in the bus */ + struct rte_bus_conf conf; /**< Bus configuration */ + rte_bus_get_iommu_class_t get_iommu_class; /**< Get iommu class */ + rte_dev_iterate_t dev_iterate; /**< Device iterator. */ + rte_bus_hot_unplug_handler_t hot_unplug_handler; + /**< handle hot-unplug failure on the bus */ + rte_bus_sigbus_handler_t sigbus_handler; + /**< handle sigbus error on the bus */ +}; + +/** + * Register a Bus handler. + * + * @param bus + * A pointer to a rte_bus structure describing the bus + * to be registered. + */ +__rte_internal +void rte_bus_register(struct rte_bus *bus); + +/** + * Helper for Bus registration. + * The constructor has higher priority than PMD constructors. + */ +#define RTE_REGISTER_BUS(nm, bus) \ +RTE_INIT_PRIO(businitfn_ ##nm, BUS) \ +{\ + (bus).name = RTE_STR(nm);\ + rte_bus_register(&bus); \ +} + +/** + * Unregister a Bus handler. + * + * @param bus + * A pointer to a rte_bus structure describing the bus + * to be unregistered. + */ +__rte_internal +void rte_bus_unregister(struct rte_bus *bus); + +#ifdef __cplusplus +} +#endif + +#endif /* BUS_DRIVER_H */ diff --git a/lib/eal/include/meson.build b/lib/eal/include/meson.build index fd6e844224..77d8621a51 100644 --- a/lib/eal/include/meson.build +++ b/lib/eal/include/meson.build @@ -55,6 +55,10 @@ headers += files( 'rte_vfio.h', ) +driver_sdk_headers = files( + 'bus_driver.h', +) + # special case install the generic headers, since they go in a subdir generic_headers = files( 'generic/rte_atomic.h', diff --git a/lib/eal/include/rte_bus.h b/lib/eal/include/rte_bus.h index 3848b44db0..dfe756fb11 100644 --- a/lib/eal/include/rte_bus.h +++ b/lib/eal/include/rte_bus.h @@ -20,284 +20,21 @@ extern "C" { #include -#include #include -#include -/** Double linked list of buses */ -RTE_TAILQ_HEAD(rte_bus_list, rte_bus); - -/** - * Bus specific scan for devices attached on the bus. - * For each bus object, the scan would be responsible for finding devices and - * adding them to its private device list. - * - * A bus should mandatorily implement this method. - * - * @return - * 0 for successful scan - * <0 for unsuccessful scan with error value - */ -typedef int (*rte_bus_scan_t)(void); - -/** - * Implementation specific probe function which is responsible for linking - * devices on that bus with applicable drivers. - * - * This is called while iterating over each registered bus. - * - * @return - * 0 for successful probe - * !0 for any error while probing - */ -typedef int (*rte_bus_probe_t)(void); - -/** - * Device iterator to find a device on a bus. - * - * This function returns an rte_device if one of those held by the bus - * matches the data passed as parameter. - * - * If the comparison function returns zero this function should stop iterating - * over any more devices. To continue a search the device of a previous search - * can be passed via the start parameter. - * - * @param cmp - * Comparison function. - * - * @param data - * Data to compare each device against. - * - * @param start - * starting point for the iteration - * - * @return - * The first device matching the data, NULL if none exists. - */ -typedef struct rte_device * -(*rte_bus_find_device_t)(const struct rte_device *start, rte_dev_cmp_t cmp, - const void *data); - -/** - * Implementation specific probe function which is responsible for linking - * devices on that bus with applicable drivers. - * - * @param dev - * Device pointer that was returned by a previous call to find_device. - * - * @return - * 0 on success. - * !0 on error. - */ -typedef int (*rte_bus_plug_t)(struct rte_device *dev); - -/** - * Implementation specific remove function which is responsible for unlinking - * devices on that bus from assigned driver. - * - * @param dev - * Device pointer that was returned by a previous call to find_device. - * - * @return - * 0 on success. - * !0 on error. - */ -typedef int (*rte_bus_unplug_t)(struct rte_device *dev); - -/** - * Bus specific parsing function. - * Validates the syntax used in the textual representation of a device, - * If the syntax is valid and ``addr`` is not NULL, writes the bus-specific - * device representation to ``addr``. - * - * @param[in] name - * device textual description - * - * @param[out] addr - * device information location address, into which parsed info - * should be written. If NULL, nothing should be written, which - * is not an error. - * - * @return - * 0 if parsing was successful. - * !0 for any error. - */ -typedef int (*rte_bus_parse_t)(const char *name, void *addr); - -/** - * Parse bus part of the device arguments. - * - * The field name of the struct rte_devargs will be set. - * - * @param da - * Pointer to the devargs to parse. - * - * @return - * 0 on successful parsing, otherwise rte_errno is set. - * -EINVAL: on parsing error. - * -ENODEV: if no key matching a device argument is specified. - * -E2BIG: device name is too long. - */ -typedef int (*rte_bus_devargs_parse_t)(struct rte_devargs *da); - -/** - * Device level DMA map function. - * After a successful call, the memory segment will be mapped to the - * given device. - * - * @param dev - * Device pointer. - * @param addr - * Virtual address to map. - * @param iova - * IOVA address to map. - * @param len - * Length of the memory segment being mapped. - * - * @return - * 0 if mapping was successful. - * Negative value and rte_errno is set otherwise. - */ -typedef int (*rte_dev_dma_map_t)(struct rte_device *dev, void *addr, - uint64_t iova, size_t len); - -/** - * Device level DMA unmap function. - * After a successful call, the memory segment will no longer be - * accessible by the given device. - * - * @param dev - * Device pointer. - * @param addr - * Virtual address to unmap. - * @param iova - * IOVA address to unmap. - * @param len - * Length of the memory segment being mapped. - * - * @return - * 0 if un-mapping was successful. - * Negative value and rte_errno is set otherwise. - */ -typedef int (*rte_dev_dma_unmap_t)(struct rte_device *dev, void *addr, - uint64_t iova, size_t len); - -/** - * Implement a specific hot-unplug handler, which is responsible for - * handle the failure when device be hot-unplugged. When the event of - * hot-unplug be detected, it could call this function to handle - * the hot-unplug failure and avoid app crash. - * @param dev - * Pointer of the device structure. - * - * @return - * 0 on success. - * !0 on error. - */ -typedef int (*rte_bus_hot_unplug_handler_t)(struct rte_device *dev); - -/** - * Implement a specific sigbus handler, which is responsible for handling - * the sigbus error which is either original memory error, or specific memory - * error that caused of device be hot-unplugged. When sigbus error be captured, - * it could call this function to handle sigbus error. - * @param failure_addr - * Pointer of the fault address of the sigbus error. - * - * @return - * 0 for success handle the sigbus for hot-unplug. - * 1 for not process it, because it is a generic sigbus error. - * -1 for failed to handle the sigbus for hot-unplug. - */ -typedef int (*rte_bus_sigbus_handler_t)(const void *failure_addr); - -/** - * Bus scan policies - */ -enum rte_bus_scan_mode { - RTE_BUS_SCAN_UNDEFINED, - RTE_BUS_SCAN_ALLOWLIST, - RTE_BUS_SCAN_BLOCKLIST, -}; - -/** - * A structure used to configure bus operations. - */ -struct rte_bus_conf { - enum rte_bus_scan_mode scan_mode; /**< Scan policy. */ -}; - - -/** - * Get common iommu class of the all the devices on the bus. The bus may - * check that those devices are attached to iommu driver. - * If no devices are attached to the bus. The bus may return with don't care - * (_DC) value. - * Otherwise, The bus will return appropriate _pa or _va iova mode. - * - * @return - * enum rte_iova_mode value. - */ -typedef enum rte_iova_mode (*rte_bus_get_iommu_class_t)(void); - - -/** - * A structure describing a generic bus. - */ -struct rte_bus { - RTE_TAILQ_ENTRY(rte_bus) next; /**< Next bus object in linked list */ - const char *name; /**< Name of the bus */ - rte_bus_scan_t scan; /**< Scan for devices attached to bus */ - rte_bus_probe_t probe; /**< Probe devices on bus */ - rte_bus_find_device_t find_device; /**< Find a device on the bus */ - rte_bus_plug_t plug; /**< Probe single device for drivers */ - rte_bus_unplug_t unplug; /**< Remove single device from driver */ - rte_bus_parse_t parse; /**< Parse a device name */ - rte_bus_devargs_parse_t devargs_parse; /**< Parse bus devargs */ - rte_dev_dma_map_t dma_map; /**< DMA map for device in the bus */ - rte_dev_dma_unmap_t dma_unmap; /**< DMA unmap for device in the bus */ - struct rte_bus_conf conf; /**< Bus configuration */ - rte_bus_get_iommu_class_t get_iommu_class; /**< Get iommu class */ - rte_dev_iterate_t dev_iterate; /**< Device iterator. */ - rte_bus_hot_unplug_handler_t hot_unplug_handler; - /**< handle hot-unplug failure on the bus */ - rte_bus_sigbus_handler_t sigbus_handler; - /**< handle sigbus error on the bus */ - -}; +struct rte_bus; +struct rte_device; /** * Retrieve a bus name. * - * @warning - * @b EXPERIMENTAL: this API may change without prior notice - * * @param bus * A pointer to a rte_bus structure. * @return * A pointer to the bus name string. */ -__rte_experimental const char *rte_bus_name(const struct rte_bus *bus); -/** - * Register a Bus handler. - * - * @param bus - * A pointer to a rte_bus structure describing the bus - * to be registered. - */ -void rte_bus_register(struct rte_bus *bus); - -/** - * Unregister a Bus handler. - * - * @param bus - * A pointer to a rte_bus structure describing the bus - * to be unregistered. - */ -void rte_bus_unregister(struct rte_bus *bus); - /** * Scan all the buses. * @@ -387,17 +124,6 @@ struct rte_bus *rte_bus_find_by_name(const char *busname); */ enum rte_iova_mode rte_bus_get_iommu_class(void); -/** - * Helper for Bus registration. - * The constructor has higher priority than PMD constructors. - */ -#define RTE_REGISTER_BUS(nm, bus) \ -RTE_INIT_PRIO(businitfn_ ##nm, BUS) \ -{\ - (bus).name = RTE_STR(nm);\ - rte_bus_register(&bus); \ -} - #ifdef __cplusplus } #endif diff --git a/lib/eal/linux/eal_dev.c b/lib/eal/linux/eal_dev.c index 02ae1cde29..098a2c3076 100644 --- a/lib/eal/linux/eal_dev.c +++ b/lib/eal/linux/eal_dev.c @@ -13,7 +13,7 @@ #include #include #include -#include +#include #include #include diff --git a/lib/eal/version.map b/lib/eal/version.map index aa53064db1..6ec15f1147 100644 --- a/lib/eal/version.map +++ b/lib/eal/version.map @@ -12,10 +12,9 @@ DPDK_23 { rte_bus_find_by_device; rte_bus_find_by_name; rte_bus_get_iommu_class; + rte_bus_name; rte_bus_probe; - rte_bus_register; rte_bus_scan; - rte_bus_unregister; rte_calloc; rte_calloc_socket; rte_cpu_get_flag_enabled; @@ -424,14 +423,13 @@ EXPERIMENTAL { rte_thread_self; rte_thread_set_affinity_by_id; rte_thread_set_priority; - - # added in 22.11 - rte_bus_name; }; INTERNAL { global: + rte_bus_register; + rte_bus_unregister; rte_eal_get_baseaddr; rte_firmware_read; rte_intr_allow_others; diff --git a/lib/ethdev/rte_ethdev.c b/lib/ethdev/rte_ethdev.c index 9e358d187a..0c2c1088c0 100644 --- a/lib/ethdev/rte_ethdev.c +++ b/lib/ethdev/rte_ethdev.c @@ -11,7 +11,7 @@ #include #include -#include +#include #include #include #include diff --git a/lib/pcapng/rte_pcapng.c b/lib/pcapng/rte_pcapng.c index 5b079cd14a..72aabd4dd0 100644 --- a/lib/pcapng/rte_pcapng.c +++ b/lib/pcapng/rte_pcapng.c @@ -11,7 +11,7 @@ #include #include -#include +#include #include #include #include -- 2.37.2