[RFC PATCH 4/7] docs: media: v4l2-memtrack: Add driver API documentation

[ming.qian@oss.nxp.com]

From: Ming Qian <ming.qian@oss.nxp.com>

Add comprehensive documentation for the V4L2 memory tracking infrastructure
in the driver API documentation. This documentation covers:

- Overview of the hierarchical memory tracking system
- Basic usage examples showing root node creation and memory tracking
- Hierarchical tracking with parent-child node relationships
- debugfs interface for runtime memory inspection
- Notification callback registration and usage warnings
- Visual examples of tree structure and debugfs output

The documentation provides driver developers with practical examples
of how to integrate memory tracking into their V4L2 drivers, including
proper setup during probe/remove, buffer allocation tracking, and
per-context memory monitoring.

Add the new v4l2-memtrack documentation to the v4l2-core index to make
it accessible in the generated documentation.

Signed-off-by: Ming Qian <ming.qian@oss.nxp.com>
---
 Documentation/driver-api/media/v4l2-core.rst  |   1 +
 .../driver-api/media/v4l2-memtrack.rst        | 140 ++++++++++++++++++
 2 files changed, 141 insertions(+)
 create mode 100644 Documentation/driver-api/media/v4l2-memtrack.rst

diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst
index a5f5102c64cc..09765d028375 100644
--- a/Documentation/driver-api/media/v4l2-core.rst
+++ b/Documentation/driver-api/media/v4l2-core.rst
@@ -28,3 +28,4 @@ Video4Linux devices
     v4l2-tveeprom
     v4l2-jpeg
     v4l2-isp
+    v4l2-memtrack
diff --git a/Documentation/driver-api/media/v4l2-memtrack.rst b/Documentation/driver-api/media/v4l2-memtrack.rst
new file mode 100644
index 000000000000..bca6954cfa0b
--- /dev/null
+++ b/Documentation/driver-api/media/v4l2-memtrack.rst
@@ -0,0 +1,140 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+V4L2 Memory Usage Tracker
+=========================
+
+Overview
+--------
+
+The V4L2 memory tracking module provides hierarchical memory allocation
+tracking for V4L2 devices. It is useful for debugging memory leaks and
+monitoring buffer usage in video drivers.
+
+Features:
+
+- Tree-structured memory usage monitoring
+- Per-device and per-context tracking
+- debugfs interface for runtime inspection
+- Optional notification callbacks for memory changes
+- V4L2 control integration
+
+Usage Example
+-------------
+
+Basic usage in a V4L2 driver:
+
+.. code-block:: c
+
+    #include <media/v4l2-memtrack.h>
+
+    struct my_device {
+        struct v4l2_memtrack_node *memtrack;
+        /* ... */
+    };
+
+    static int my_probe(struct platform_device *pdev)
+    {
+        struct my_device *dev;
+
+        dev->memtrack = v4l2_memtrack_create_root("my-device");
+        if (!dev->memtrack)
+            return -ENOMEM;
+
+        return 0;
+    }
+
+    static void my_remove(struct platform_device *pdev)
+    {
+        v4l2_memtrack_destroy_node(dev->memtrack);
+    }
+
+    static int my_alloc_buffer(struct my_device *dev, size_t size)
+    {
+        void *buf = dma_alloc_coherent(dev, size, &dma_addr, GFP_KERNEL);
+        if (!buf)
+            return -ENOMEM;
+
+        v4l2_memtrack_add(dev->memtrack, size);
+        return 0;
+    }
+
+    static void my_free_buffer(struct my_device *dev, size_t size)
+    {
+        dma_free_coherent(dev, size, buf, dma_addr);
+        v4l2_memtrack_sub(dev->memtrack, size);
+    }
+
+Hierarchical Tracking
+---------------------
+
+For more detailed tracking, create child nodes:
+
+.. code-block:: c
+
+    struct my_context {
+        struct v4l2_memtrack_node *memtrack;
+    };
+
+    static int my_open(struct file *file)
+    {
+        struct my_context *ctx;
+
+        ctx->memtrack = v4l2_memtrack_create_node(dev->memtrack, "context");
+        return 0;
+    }
+
+    static int my_close(struct file *file)
+    {
+        v4l2_memtrack_destroy_node(ctx->memtrack);
+        return 0;
+    }
+
+This creates a tree structure::
+
+    my-device (root)
+    ├── context (pid=1234)
+    │   ├── buffer: 4096 bytes
+    │   └── buffer: 8192 bytes
+    └── context (pid=5678)
+        └── buffer: 4096 bytes
+
+debugfs Interface
+-----------------
+
+Memory usage is exposed via debugfs at::
+
+    /sys/kernel/debug/v4l2-memtrack/<device-name>
+
+Example output::
+
+    Total memory usage: 16384 bytes
+    my-device (tgid=1000, pid=1000) usage: 16384
+      context (tgid=1234, pid=1234) usage: 12288 (count=2)
+      context (tgid=5678, pid=5678) usage: 4096 (count=1)
+
+Notification Callbacks
+----------------------
+
+Register callbacks to be notified of memory changes:
+
+.. code-block:: c
+
+    static void my_notify(struct v4l2_memtrack_node *node,
+                          size_t total, void *priv)
+    {
+        pr_info("Memory usage changed: %zu bytes\n", total);
+    }
+
+    v4l2_memtrack_register_notify(dev->memtrack, my_notify, dev);
+
+.. warning::
+
+   Callbacks are executed without holding internal locks, so most kernel
+   functions may be called safely. However, the callback MUST NOT call
+   v4l2_memtrack_unregister_notify() or v4l2_memtrack_destroy_node() on
+   the same node, as this will cause a deadlock.
+
+API Reference
+-------------
+
+.. kernel-doc:: include/media/v4l2-memtrack.h
-- 
2.53.0