[RFC v3 1/2] pci: introduce the PCIe TLP Processing Hints API

[Wathsala Vithanage <wathsala.vithanage@arm.com>]

Extend the PCI driver and the library to extract the Steering Tag (ST)
for a given Processor/Processor Container and Cache ID pair and validate
a Processing Hint from a TPH _DSM associated with a root port device.
The rte_pci_device structure passed into the rte_pci_extract_tph_st()
function could be a device or a root port. If it's a device, the
function should trace it back to the root port and use its TPH _DSM to
extract STs. The implementation of rte_pci_extract_tph_st() is dependent
on the operating system.

rte_pci_extract_tph_st() should also be supplied with a
rte_tph_acpi__dsm_args, and a rte_tph_acpi__dsm_return structures.
These two structures are defined in the PCI library and comply with the
TPH _DSM argument and return encoding specified in the PCI firmware ECN
titled "Revised _DSM for Cache Locality TPH Features.". Use of
rte_init_tph_acpi__dsm_args() is recommended for initializing the
rte_tph_acpi__dsm_args struct which is capable of converting lcore ID,
the cache level into values understood by the ACPI _DSM function.
rte_tph_acpi__dsm_return struct will be initialized with the values
returned by the TPH _DSM; it is up to the caller to use these values per
the device's capabilities.

Signed-off-by: Wathsala Vithanage <wathsala.vithanage@arm.com>
Reviewed-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
Reviewed-by: Dhruv Tripathi <dhruv.tripathi@arm.com>

---
 drivers/bus/pci/bsd/pci.c     |  12 ++++
 drivers/bus/pci/linux/pci.c   |  12 ++++
 drivers/bus/pci/rte_bus_pci.h |  22 +++++++
 drivers/bus/pci/version.map   |   3 +
 drivers/bus/pci/windows/pci.c |  14 +++++
 lib/pci/meson.build           |   2 +
 lib/pci/rte_pci.h             |   2 +
 lib/pci/rte_pci_tph.c         |  21 +++++++
 lib/pci/rte_pci_tph.h         | 111 ++++++++++++++++++++++++++++++++++
 9 files changed, 199 insertions(+)
 create mode 100644 lib/pci/rte_pci_tph.c
 create mode 100644 lib/pci/rte_pci_tph.h

diff --git a/drivers/bus/pci/bsd/pci.c b/drivers/bus/pci/bsd/pci.c
index 2f88252418..a143cecf45 100644
--- a/drivers/bus/pci/bsd/pci.c
+++ b/drivers/bus/pci/bsd/pci.c
@@ -639,3 +639,15 @@ rte_pci_ioport_unmap(struct rte_pci_ioport *p)
 
 	return ret;
 }
+
+int
+rte_pci_extract_tph_st(const struct rte_pci_device *dev,
+		       const struct rte_tph_acpi__dsm_args *args,
+		       struct rte_tph_acpi__dsm_return *ret)
+{
+	RTE_SET_USED(dev);
+	RTE_SET_USED(args);
+	RTE_SET_USED(ret);
+	/* BSD doesn't support this feature yet! */
+	return -1;
+}
diff --git a/drivers/bus/pci/linux/pci.c b/drivers/bus/pci/linux/pci.c
index 9056035b33..dffb945462 100644
--- a/drivers/bus/pci/linux/pci.c
+++ b/drivers/bus/pci/linux/pci.c
@@ -803,3 +803,15 @@ rte_pci_ioport_unmap(struct rte_pci_ioport *p)
 
 	return ret;
 }
+
+int
+rte_pci_extract_tph_st(const struct rte_pci_device *dev,
+		       const struct rte_tph_acpi__dsm_args *args,
+		       struct rte_tph_acpi__dsm_return *ret)
+{
+	RTE_SET_USED(dev);
+	RTE_SET_USED(args);
+	RTE_SET_USED(ret);
+	/* Linux doesn't support this feature yet! */
+	return -1;
+}
diff --git a/drivers/bus/pci/rte_bus_pci.h b/drivers/bus/pci/rte_bus_pci.h
index 19a7b15b99..a8167e9b4b 100644
--- a/drivers/bus/pci/rte_bus_pci.h
+++ b/drivers/bus/pci/rte_bus_pci.h
@@ -312,6 +312,28 @@ void rte_pci_ioport_read(struct rte_pci_ioport *p,
 void rte_pci_ioport_write(struct rte_pci_ioport *p,
 		const void *data, size_t len, off_t offset);
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice.
+ *
+ * Extract steering tag from the ACPI TPH _DSM of the root port
+ * of the device is connected to.
+ *
+ * @param device
+ *   A pointer to a rte_pci_device structure describing the device
+ *   to use.
+ * @param args
+ *   An initialized args object for the _DSM.
+ * @param ret
+ *   A pointer to a _DSM return object to store the extracted steering tag.
+ * @return
+ *   0 on success, -1 on error extracting the steeting tag.
+ */
+__rte_experimental
+int rte_pci_extract_tph_st(const struct rte_pci_device *device,
+			   const struct rte_tph_acpi__dsm_args *args,
+			   struct rte_tph_acpi__dsm_return *ret);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/drivers/bus/pci/version.map b/drivers/bus/pci/version.map
index cd653de5ac..5c89f80c8e 100644
--- a/drivers/bus/pci/version.map
+++ b/drivers/bus/pci/version.map
@@ -31,6 +31,9 @@ EXPERIMENTAL {
 	rte_pci_find_capability;
 	rte_pci_find_next_capability;
 	rte_pci_has_capability_list;
+
+	# added in 24.11
+	rte_pci_extract_tph_st;
 };
 
 INTERNAL {
diff --git a/drivers/bus/pci/windows/pci.c b/drivers/bus/pci/windows/pci.c
index 36e6f89093..761f714a18 100644
--- a/drivers/bus/pci/windows/pci.c
+++ b/drivers/bus/pci/windows/pci.c
@@ -500,3 +500,17 @@ rte_pci_scan(void)
 
 	return ret;
 }
+
+
+int
+rte_pci_extract_tph_st(const struct rte_pci_device *dev,
+		       const struct rte_tph_acpi__dsm_args *args,
+		       struct rte_tph_acpi__dsm_return *ret)
+{
+	RTE_SET_USED(dev);
+	RTE_SET_USED(args);
+	RTE_SET_USED(ret);
+	/* This feature is not yet implemented for windows */
+	return -1;
+}
+
diff --git a/lib/pci/meson.build b/lib/pci/meson.build
index dd41cd5068..85e17c4257 100644
--- a/lib/pci/meson.build
+++ b/lib/pci/meson.build
@@ -3,3 +3,5 @@
 
 sources = files('rte_pci.c')
 headers = files('rte_pci.h')
+headers = files('rte_pci_tph.h')
+headers = files('rte_pci_tph.c')
diff --git a/lib/pci/rte_pci.h b/lib/pci/rte_pci.h
index 9a50a12142..b7897640f1 100644
--- a/lib/pci/rte_pci.h
+++ b/lib/pci/rte_pci.h
@@ -16,6 +16,8 @@
 #include <inttypes.h>
 #include <sys/types.h>
 
+#include <rte_pci_tph.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
diff --git a/lib/pci/rte_pci_tph.c b/lib/pci/rte_pci_tph.c
new file mode 100644
index 0000000000..3b0c7d4d97
--- /dev/null
+++ b/lib/pci/rte_pci_tph.c
@@ -0,0 +1,21 @@
+#include <errno.h>
+#include <rte_pci_tph.h>
+
+int
+rte_init_tph_acpi__dsm_args(uint16_t lcore_id, uint8_t type,
+			    uint8_t cache_level, uint8_t ph,
+			    struct rte_tph_acpi__dsm_args *args)
+{
+	RTE_SET_USED(lcore_id);
+	RTE_SET_USED(type);
+	RTE_SET_USED(cache_level);
+	RTE_SET_USED(ph);
+
+	if (!args)
+		return -EINVAL;
+	/* Use libhwloc or other mechanism provided by DPDK to
+	 * map lcore_id and cache_level to hardware IDs for
+	 * initializing args.
+	 */
+	return -ENOTSUP;
+}
diff --git a/lib/pci/rte_pci_tph.h b/lib/pci/rte_pci_tph.h
new file mode 100644
index 0000000000..df851f5744
--- /dev/null
+++ b/lib/pci/rte_pci_tph.h
@@ -0,0 +1,111 @@
+/* SPDX-License-Identifier: BSD-3-Clause
+ * Copyright(c) 2024 Arm Ltd.
+ */
+
+#ifndef _RTE_PCI_TPH_H_
+#define _RTE_PCI_TPH_H_
+
+/**
+ * @file
+ *
+ * RTE PCI TLP Processing Hints helpers
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <rte_common.h>
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change, or be removed, without prior notice
+ *
+ * ACPI TPH _DSM input args structure.
+ * Refer to PCI-SIG ECN "Revised _DSM for Cache Locality TPH Features" for details.
+ */
+struct rte_tph_acpi__dsm_args {
+	uint32_t feature_id; /**< Always 0. */
+	struct {
+		/** APIC/PPTT Processor/Processor container ID. */
+		uint32_t uid;
+	} __rte_packed featureArg1; /**< 1st Arg. */
+	struct {
+		/** Intended ph bits just for validating. */
+		uint64_t ph : 2;
+		/** If type=1 uid is Processor container ID. */
+		uint64_t type :  1;
+		/** cache_reference is valid if cache_ref_valid=1. */
+		uint64_t cache_ref_valid : 1;
+		uint64_t reserved : 28;
+		/** PPTT cache ID of the desired target. */
+		uint64_t cache_refernce : 32;
+	} __rte_packed featureArg2; /**< 2ns Arg. */
+} __rte_packed;
+
+/**
+ * @warning
+ * @b EXPERIMENTAL: this structure may change, or be removed, without prior notice
+ *
+ * ACPI TPH _DSM return structure.
+ * Refer to PCI-SIG ECN "Revised _DSM for Cache Locality TPH Features" for details.
+ */
+struct rte_tph_acpi__dsm_return {
+	uint64_t vmem_st_valid : 1; /**< if set to 1, vmem_st (8-bit ST) is valid. */
+	/** if set to 1, vmem_ext_st (16-bit vmem ST) is valid. */
+	uint64_t vmem_ext_st_valid : 1;
+	/** if set to 1, ph bits in input args is valid. */
+	uint64_t vmem_ph_ignore : 1;
+	uint64_t reserved_1 : 5;
+	/** 8-bit volatile memory ST) */
+	uint64_t vmem_st : 8;
+	/** 16-bit volatile ST) */
+	uint64_t vmem_ext_st : 16;
+	uint64_t pmem_st_valid : 1;  /**< if set to 1, pmem_st (8-bit ST) is valid. */
+	/** if set to 1, pmem_ext_st (16-bit ST) is valid. */
+	uint64_t pmem_ext_st_valid : 1;
+	/** if set to 1, ph bits in input args are valid for persistent memory. */
+	uint64_t pmem_ph_ignore : 1;
+	uint64_t reserved_2 : 5;
+	/** 8-bit persistent memory ST) */
+	uint64_t pmem_st : 8;
+	/** 16-bit persistent memory ST) */
+	uint64_t pmem_ext_st : 16;
+} __rte_packed;
+
+
+/**
+ *
+ * @warning
+ * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
+ *
+ * Initializes stashing hints configuration with a platform specific stashing hint
+ * that matches the lcore_id and cache_level.
+ *
+ * @param lcore_id
+ *  The lcore_id of the processor of the cache stashing target. If is_container is set
+ *  the target is the processor container of the CPU specified by the lcore_id.
+ * @param type
+ *  If set to 1, the procssor container of the processor specified by lcore_id will be
+ *  used at the stashing target. If set to 0, processor specified by the lcore_id will be
+ *  used as the stashing target.
+ * @param cache_level
+ *  The cache level of the processor/container specified by the lcore_id.
+ * @param ph
+ *  TPH Processing Hints bits.
+ * @param args
+ *  ACPI TPH _DSM object arguments structure.
+ * @return
+ *  - (0) on Success.
+ *  - 0 < or 0 > on Failure.
+ */
+
+int rte_init_tph_acpi__dsm_args(uint16_t lcore_id, uint8_t type,
+				uint8_t cache_level, uint8_t ph,
+				struct rte_tph_acpi__dsm_args *args);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _RTE_PCI_TPH_H_ */
-- 
2.34.1