PCI: Add debugfs support for exposing PTM context

Precision Time Management (PTM) mechanism defined in PCIe spec r6.0,
sec 6.21 allows precise coordination of timing information across multiple
components in a PCIe hierarchy with independent local time clocks.

PCI core already supports enabling PTM in the root port and endpoint
devices through PTM Extended Capability registers. But the PTM context
supported by the PTM capable components such as Root Complex (RC) and
Endpoint (EP) controllers were not exposed as of now. Part of the reason is
that the spec doesn't define how the context information is exposed to the
software and left it to the vendor implementation. So there is no
standardized way to get access to the context information and each vendor
have defined their own way.

This commit adds debugfs support to expose the PTM context to userspace
from both PCIe RC and EP controllers. Since the context information is
exposed in a vendor specific way, the debugfs interface allows the
controller drivers to implement callbacks for each attribute, to be called
by the generic PTM driver.

The Controller drivers are expected to call pcie_ptm_create_debugfs() to
create the debugfs attributes for the PTM context and call
pcie_ptm_destroy_debugfs() to destroy them. The drivers should also
populate the relevant callbacks in the 'struct pcie_ptm_ops' structure
based on the controller implementation.

Below PTM context are exposed through debugfs:

PCIe RC
=======

1. PTM Local clock
2. PTM T2 timestamp
3. PTM T3 timestamp
4. PTM Context valid

PCIe EP
=======

1. PTM Local clock
2. PTM T1 timestamp
3. PTM T4 timestamp
4. PTM Master clock
5. PTM Context update

Signed-off-by: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
[kwilczynski: fix overflow issue reported by Dan Carpenter from
https://lore.kernel.org/linux-pci/b41c1754-c6b7-4805-9f14-7c643d6c5304@suswa.mountain]
Signed-off-by: Krzysztof Wilczyński <kwilczynski@kernel.org>
Link: https://patch.msgid.link/20250505-pcie-ptm-v4-1-02d26d51400b@linaro.org

diff --git a/Documentation/ABI/testing/debugfs-pcie-ptm b/Documentation/ABI/testing/debugfs-pcie-ptm
new file mode 100644 (file)
index 0000000..602d413
--- /dev/null
+++ b/Documentation/ABI/testing/debugfs-pcie-ptm
@@ -0,0 +1,70 @@
+What:          /sys/kernel/debug/pcie_ptm_*/local_clock
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RO) PTM local clock in nanoseconds. Applicable for both Root
+               Complex and Endpoint controllers.
+
+What:          /sys/kernel/debug/pcie_ptm_*/master_clock
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RO) PTM master clock in nanoseconds. Applicable only for
+               Endpoint controllers.
+
+What:          /sys/kernel/debug/pcie_ptm_*/t1
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RO) PTM T1 timestamp in nanoseconds. Applicable only for
+               Endpoint controllers.
+
+What:          /sys/kernel/debug/pcie_ptm_*/t2
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RO) PTM T2 timestamp in nanoseconds. Applicable only for
+               Root Complex controllers.
+
+What:          /sys/kernel/debug/pcie_ptm_*/t3
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RO) PTM T3 timestamp in nanoseconds. Applicable only for
+               Root Complex controllers.
+
+What:          /sys/kernel/debug/pcie_ptm_*/t4
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RO) PTM T4 timestamp in nanoseconds. Applicable only for
+               Endpoint controllers.
+
+What:          /sys/kernel/debug/pcie_ptm_*/context_update
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RW) Control the PTM context update mode. Applicable only for
+               Endpoint controllers.
+
+               Following values are supported:
+
+               * auto = PTM context auto update trigger for every 10ms
+
+               * manual = PTM context manual update. Writing 'manual' to this
+                          file triggers PTM context update (default)
+
+What:          /sys/kernel/debug/pcie_ptm_*/context_valid
+Date:          May 2025
+Contact:       Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
+Description:
+               (RW) Control the PTM context validity (local clock timing).
+               Applicable only for Root Complex controllers. PTM context is
+               invalidated by hardware if the Root Complex enters low power
+               mode or changes link frequency.
+
+               Following values are supported:
+
+               * 0 = PTM context invalid (default)
+
+               * 1 = PTM context valid

diff --git a/MAINTAINERS b/MAINTAINERS
index 96b82704950184bd71623ff41fc4df31e4c7fe87..cecd5141b0ce699d73d54575a17b5d6e49b7b4a0 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -18641,6 +18641,7 @@ Q:      https://patchwork.kernel.org/project/linux-pci/list/
 B:     https://bugzilla.kernel.org
 C:     irc://irc.oftc.net/linux-pci
 T:     git git://git.kernel.org/pub/scm/linux/kernel/git/pci/pci.git
+F:     Documentation/ABI/testing/debugfs-pcie-ptm
 F:     Documentation/devicetree/bindings/pci/
 F:     drivers/pci/controller/
 F:     drivers/pci/pci-bridge-emul.c

diff --git a/drivers/pci/pcie/ptm.c b/drivers/pci/pcie/ptm.c
index 7cfb6c0d5dcb6de2a759b56d6877c95102b3d10f..ee5f615a902333b78e2c147990c76259521f1487 100644 (file)
--- a/drivers/pci/pcie/ptm.c
+++ b/drivers/pci/pcie/ptm.c
@@ -5,6 +5,7 @@
  */
 
 #include <linux/bitfield.h>
+#include <linux/debugfs.h>
 #include <linux/module.h>
 #include <linux/init.h>
 #include <linux/pci.h>
@@ -252,3 +253,302 @@ bool pcie_ptm_enabled(struct pci_dev *dev)
        return dev->ptm_enabled;
 }
 EXPORT_SYMBOL(pcie_ptm_enabled);
+
+static ssize_t context_update_write(struct file *file, const char __user *ubuf,
+                            size_t count, loff_t *ppos)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = file->private_data;
+       char buf[7];
+       int ret;
+       u8 mode;
+
+       if (!ptm_debugfs->ops->context_update_write)
+               return -EOPNOTSUPP;
+
+       if (count < 1 || count >= sizeof(buf))
+               return -EINVAL;
+
+       ret = copy_from_user(buf, ubuf, count);
+       if (ret)
+               return -EFAULT;
+
+       buf[count] = '\0';
+
+       if (sysfs_streq(buf, "auto"))
+               mode = PCIE_PTM_CONTEXT_UPDATE_AUTO;
+       else if (sysfs_streq(buf, "manual"))
+               mode = PCIE_PTM_CONTEXT_UPDATE_MANUAL;
+       else
+               return -EINVAL;
+
+       mutex_lock(&ptm_debugfs->lock);
+       ret = ptm_debugfs->ops->context_update_write(ptm_debugfs->pdata, mode);
+       mutex_unlock(&ptm_debugfs->lock);
+       if (ret)
+               return ret;
+
+       return count;
+}
+
+static ssize_t context_update_read(struct file *file, char __user *ubuf,
+                            size_t count, loff_t *ppos)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = file->private_data;
+       char buf[8]; /* Extra space for NULL termination at the end */
+       ssize_t pos;
+       u8 mode;
+
+       if (!ptm_debugfs->ops->context_update_read)
+               return -EOPNOTSUPP;
+
+       mutex_lock(&ptm_debugfs->lock);
+       ptm_debugfs->ops->context_update_read(ptm_debugfs->pdata, &mode);
+       mutex_unlock(&ptm_debugfs->lock);
+
+       if (mode == PCIE_PTM_CONTEXT_UPDATE_AUTO)
+               pos = scnprintf(buf, sizeof(buf), "auto\n");
+       else
+               pos = scnprintf(buf, sizeof(buf), "manual\n");
+
+       return simple_read_from_buffer(ubuf, count, ppos, buf, pos);
+}
+
+static const struct file_operations context_update_fops = {
+       .open = simple_open,
+       .read = context_update_read,
+       .write = context_update_write,
+};
+
+static int context_valid_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       bool valid;
+       int ret;
+
+       if (!ptm_debugfs->ops->context_valid_read)
+               return -EOPNOTSUPP;
+
+       mutex_lock(&ptm_debugfs->lock);
+       ret = ptm_debugfs->ops->context_valid_read(ptm_debugfs->pdata, &valid);
+       mutex_unlock(&ptm_debugfs->lock);
+       if (ret)
+               return ret;
+
+       *val = valid;
+
+       return 0;
+}
+
+static int context_valid_set(void *data, u64 val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       int ret;
+
+       if (!ptm_debugfs->ops->context_valid_write)
+               return -EOPNOTSUPP;
+
+       mutex_lock(&ptm_debugfs->lock);
+       ret = ptm_debugfs->ops->context_valid_write(ptm_debugfs->pdata, !!val);
+       mutex_unlock(&ptm_debugfs->lock);
+
+       return ret;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(context_valid_fops, context_valid_get,
+                        context_valid_set, "%llu\n");
+
+static int local_clock_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       u64 clock;
+       int ret;
+
+       if (!ptm_debugfs->ops->local_clock_read)
+               return -EOPNOTSUPP;
+
+       ret = ptm_debugfs->ops->local_clock_read(ptm_debugfs->pdata, &clock);
+       if (ret)
+               return ret;
+
+       *val = clock;
+
+       return 0;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(local_clock_fops, local_clock_get, NULL, "%llu\n");
+
+static int master_clock_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       u64 clock;
+       int ret;
+
+       if (!ptm_debugfs->ops->master_clock_read)
+               return -EOPNOTSUPP;
+
+       ret = ptm_debugfs->ops->master_clock_read(ptm_debugfs->pdata, &clock);
+       if (ret)
+               return ret;
+
+       *val = clock;
+
+       return 0;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(master_clock_fops, master_clock_get, NULL, "%llu\n");
+
+static int t1_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       u64 clock;
+       int ret;
+
+       if (!ptm_debugfs->ops->t1_read)
+               return -EOPNOTSUPP;
+
+       ret = ptm_debugfs->ops->t1_read(ptm_debugfs->pdata, &clock);
+       if (ret)
+               return ret;
+
+       *val = clock;
+
+       return 0;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(t1_fops, t1_get, NULL, "%llu\n");
+
+static int t2_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       u64 clock;
+       int ret;
+
+       if (!ptm_debugfs->ops->t2_read)
+               return -EOPNOTSUPP;
+
+       ret = ptm_debugfs->ops->t2_read(ptm_debugfs->pdata, &clock);
+       if (ret)
+               return ret;
+
+       *val = clock;
+
+       return 0;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(t2_fops, t2_get, NULL, "%llu\n");
+
+static int t3_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       u64 clock;
+       int ret;
+
+       if (!ptm_debugfs->ops->t3_read)
+               return -EOPNOTSUPP;
+
+       ret = ptm_debugfs->ops->t3_read(ptm_debugfs->pdata, &clock);
+       if (ret)
+               return ret;
+
+       *val = clock;
+
+       return 0;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(t3_fops, t3_get, NULL, "%llu\n");
+
+static int t4_get(void *data, u64 *val)
+{
+       struct pci_ptm_debugfs *ptm_debugfs = data;
+       u64 clock;
+       int ret;
+
+       if (!ptm_debugfs->ops->t4_read)
+               return -EOPNOTSUPP;
+
+       ret = ptm_debugfs->ops->t4_read(ptm_debugfs->pdata, &clock);
+       if (ret)
+               return ret;
+
+       *val = clock;
+
+       return 0;
+}
+
+DEFINE_DEBUGFS_ATTRIBUTE(t4_fops, t4_get, NULL, "%llu\n");
+
+#define pcie_ptm_create_debugfs_file(pdata, mode, attr)                        \
+       do {                                                            \
+               if (ops->attr##_visible && ops->attr##_visible(pdata))  \
+                       debugfs_create_file(#attr, mode, ptm_debugfs->debugfs, \
+                                           ptm_debugfs, &attr##_fops); \
+       } while (0)
+
+/*
+ * pcie_ptm_create_debugfs() - Create debugfs entries for the PTM context
+ * @dev: PTM capable component device
+ * @pdata: Private data of the PTM capable component device
+ * @ops: PTM callback structure
+ *
+ * Create debugfs entries for exposing the PTM context of the PTM capable
+ * components such as Root Complex and Endpoint controllers.
+ *
+ * Return: Pointer to 'struct pci_ptm_debugfs' if success, NULL otherwise.
+ */
+struct pci_ptm_debugfs *pcie_ptm_create_debugfs(struct device *dev, void *pdata,
+                         const struct pcie_ptm_ops *ops)
+{
+       struct pci_ptm_debugfs *ptm_debugfs;
+       char *dirname;
+       int ret;
+
+       /* Caller must provide check_capability() callback */
+       if (!ops->check_capability)
+               return NULL;
+
+       /* Check for PTM capability before creating debugfs attrbutes */
+       ret = ops->check_capability(pdata);
+       if (!ret) {
+               dev_dbg(dev, "PTM capability not present\n");
+               return NULL;
+       }
+
+       ptm_debugfs = kzalloc(sizeof(*ptm_debugfs), GFP_KERNEL);
+       if (!ptm_debugfs)
+               return NULL;
+
+       dirname = devm_kasprintf(dev, GFP_KERNEL, "pcie_ptm_%s", dev_name(dev));
+       if (!dirname)
+               return NULL;
+
+       ptm_debugfs->debugfs = debugfs_create_dir(dirname, NULL);
+       ptm_debugfs->pdata = pdata;
+       ptm_debugfs->ops = ops;
+       mutex_init(&ptm_debugfs->lock);
+
+       pcie_ptm_create_debugfs_file(pdata, 0644, context_update);
+       pcie_ptm_create_debugfs_file(pdata, 0644, context_valid);
+       pcie_ptm_create_debugfs_file(pdata, 0444, local_clock);
+       pcie_ptm_create_debugfs_file(pdata, 0444, master_clock);
+       pcie_ptm_create_debugfs_file(pdata, 0444, t1);
+       pcie_ptm_create_debugfs_file(pdata, 0444, t2);
+       pcie_ptm_create_debugfs_file(pdata, 0444, t3);
+       pcie_ptm_create_debugfs_file(pdata, 0444, t4);
+
+       return ptm_debugfs;
+}
+EXPORT_SYMBOL_GPL(pcie_ptm_create_debugfs);
+
+/*
+ * pcie_ptm_destroy_debugfs() - Destroy debugfs entries for the PTM context
+ * @ptm_debugfs: Pointer to the PTM debugfs struct
+ */
+void pcie_ptm_destroy_debugfs(struct pci_ptm_debugfs *ptm_debugfs)
+{
+       if (!ptm_debugfs)
+               return;
+
+       mutex_destroy(&ptm_debugfs->lock);
+       debugfs_remove_recursive(ptm_debugfs->debugfs);
+}
+EXPORT_SYMBOL_GPL(pcie_ptm_destroy_debugfs);

diff --git a/include/linux/pci.h b/include/linux/pci.h
index 0e8e3fd77e96713054388bdc82f439e51023c1bf..01a29076604ffd7261f94e1dc32dde063ae605d8 100644 (file)
--- a/include/linux/pci.h
+++ b/include/linux/pci.h
@@ -1856,6 +1856,39 @@ static inline bool pci_aer_available(void) { return false; }
 
 bool pci_ats_disabled(void);
 
+#define PCIE_PTM_CONTEXT_UPDATE_AUTO 0
+#define PCIE_PTM_CONTEXT_UPDATE_MANUAL 1
+
+struct pcie_ptm_ops {
+       int (*check_capability)(void *drvdata);
+       int (*context_update_write)(void *drvdata, u8 mode);
+       int (*context_update_read)(void *drvdata, u8 *mode);
+       int (*context_valid_write)(void *drvdata, bool valid);
+       int (*context_valid_read)(void *drvdata, bool *valid);
+       int (*local_clock_read)(void *drvdata, u64 *clock);
+       int (*master_clock_read)(void *drvdata, u64 *clock);
+       int (*t1_read)(void *drvdata, u64 *clock);
+       int (*t2_read)(void *drvdata, u64 *clock);
+       int (*t3_read)(void *drvdata, u64 *clock);
+       int (*t4_read)(void *drvdata, u64 *clock);
+
+       bool (*context_update_visible)(void *drvdata);
+       bool (*context_valid_visible)(void *drvdata);
+       bool (*local_clock_visible)(void *drvdata);
+       bool (*master_clock_visible)(void *drvdata);
+       bool (*t1_visible)(void *drvdata);
+       bool (*t2_visible)(void *drvdata);
+       bool (*t3_visible)(void *drvdata);
+       bool (*t4_visible)(void *drvdata);
+};
+
+struct pci_ptm_debugfs {
+       struct dentry *debugfs;
+       const struct pcie_ptm_ops *ops;
+       struct mutex lock;
+       void *pdata;
+};
+
 #ifdef CONFIG_PCIE_PTM
 int pci_enable_ptm(struct pci_dev *dev, u8 *granularity);
 void pci_disable_ptm(struct pci_dev *dev);
@@ -1868,6 +1901,18 @@ static inline bool pcie_ptm_enabled(struct pci_dev *dev)
 { return false; }
 #endif
 
+#if IS_ENABLED(CONFIG_DEBUG_FS) && IS_ENABLED(CONFIG_PCIE_PTM)
+struct pci_ptm_debugfs *pcie_ptm_create_debugfs(struct device *dev, void *pdata,
+                                               const struct pcie_ptm_ops *ops);
+void pcie_ptm_destroy_debugfs(struct pci_ptm_debugfs *ptm_debugfs);
+#else
+static inline struct pci_ptm_debugfs
+*pcie_ptm_create_debugfs(struct device *dev, void *pdata,
+                        const struct pcie_ptm_ops *ops) { return NULL; }
+static inline void
+pcie_ptm_destroy_debugfs(struct pci_ptm_debugfs *ptm_debugfs) { }
+#endif
+
 void pci_cfg_access_lock(struct pci_dev *dev);
 bool pci_cfg_access_trylock(struct pci_dev *dev);
 void pci_cfg_access_unlock(struct pci_dev *dev);