Re: [PATCH 5/6] cxl/pmem: Fix Documentation warning

[Jonathan Cameron <Jonathan.Cameron@Huawei.com>]

On Fri, 3 Sep 2021 19:21:01 -0700
Dan Williams <dan.j.williams@intel.com> wrote:

> Commit 06737cd0d216 ("cxl/core: Move pmem functionality") neglected to
> add a DOC header for the new drivers/cxl/core/pmem.c file.
> 
> Reported-by: Ben Widawsky <ben.widawsky@intel.com>
> Signed-off-by: Dan Williams <dan.j.williams@intel.com>
Trivial comment inline, but otherwise looks fine to me.

Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huwei.com>



> ---
>  Documentation/driver-api/cxl/memory-devices.rst |    2 +-
>  drivers/cxl/core/pmem.c                         |   30 +++++++++++++++++++++--
>  2 files changed, 29 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst
> index 46847d8c70a0..df799cdf1c3f 100644
> --- a/Documentation/driver-api/cxl/memory-devices.rst
> +++ b/Documentation/driver-api/cxl/memory-devices.rst
> @@ -40,7 +40,7 @@ CXL Core
>     :doc: cxl core
>  
>  .. kernel-doc:: drivers/cxl/core/pmem.c
> -   :internal:
> +   :doc: cxl pmem
>  
>  .. kernel-doc:: drivers/cxl/core/regs.c
>     :internal:
> diff --git a/drivers/cxl/core/pmem.c b/drivers/cxl/core/pmem.c
> index 69c97cc0d945..d24570f5b8ba 100644
> --- a/drivers/cxl/core/pmem.c
> +++ b/drivers/cxl/core/pmem.c
> @@ -1,13 +1,25 @@
>  // SPDX-License-Identifier: GPL-2.0-only
>  /* Copyright(c) 2020 Intel Corporation. */
> -
>  #include <linux/device.h>
>  #include <linux/slab.h>
>  #include <cxlmem.h>
>  #include <cxl.h>
> -

Grumpy hat:  Unrelated changes, but honestly I don't really care
given the small size of the patch anyway.

>  #include "core.h"
>  
> +/**
> + * DOC: cxl pmem
> + *
> + * The core CXL PMEM infrastructure supports persistent memory
> + * provisioning and serves as a bridge to the LIBNVDIMM subsystem. A CXL
> + * 'bridge' device is added at the root of a CXL device topology if
> + * platform firmware advertises at least one persistent memory capable
> + * CXL window. That root-level bridge corresponds to a LIBNVDIMM 'bus'
> + * device. Then for each cxl_memdev in the CXL device topology a bridge
> + * device is added to host a LIBNVDIMM dimm object. When these bridges
> + * are registered native LIBNVDIMM uapis are translated to CXL
> + * operations, for example, namespace label access commands.
> + */
> +
>  static void cxl_nvdimm_bridge_release(struct device *dev)
>  {
>  	struct cxl_nvdimm_bridge *cxl_nvb = to_cxl_nvdimm_bridge(dev);
> @@ -85,6 +97,13 @@ static void unregister_nvb(void *_cxl_nvb)
>  	device_unregister(&cxl_nvb->dev);
>  }
>  
> +/**
> + * devm_cxl_add_nvdimm_bridge() - add the root of a LIBNVDIMM topology
> + * @host: platform firmware root device
> + * @port: CXL port at the root of a CXL topology
> + *
> + * Return: bridge device that can host cxl_nvdimm objects
> + */
>  struct cxl_nvdimm_bridge *devm_cxl_add_nvdimm_bridge(struct device *host,
>  						     struct cxl_port *port)
>  {
> @@ -173,6 +192,13 @@ static struct cxl_nvdimm *cxl_nvdimm_alloc(struct cxl_memdev *cxlmd)
>  	return cxl_nvd;
>  }
>  
> +/**
> + * devm_cxl_add_nvdimm() - add a bridge between a cxl_memdev and an nvdimm
> + * @host: same host as @cxlmd
> + * @cxlmd: cxl_memdev instance that will perform LIBNVDIMM operations
> + *
> + * Return: 0 on success negative error code on failure.
> + */
>  int devm_cxl_add_nvdimm(struct device *host, struct cxl_memdev *cxlmd)
>  {
>  	struct cxl_nvdimm *cxl_nvd;
>