[PATCH 02/13] cxl/core/bus: Add kernel docs for decoder ops

[Ben Widawsky <ben.widawsky@intel.com>]

Since the code to add decoders for switches and endpoints is on the
horizon, document the new interfaces that will be consumed by them.

Signed-off-by: Ben Widawsky <ben.widawsky@intel.com>
---
 drivers/cxl/core/bus.c | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/drivers/cxl/core/bus.c b/drivers/cxl/core/bus.c
index 3991ac231c3e..9d98dd50d424 100644
--- a/drivers/cxl/core/bus.c
+++ b/drivers/cxl/core/bus.c
@@ -453,6 +453,19 @@ int cxl_add_dport(struct cxl_port *port, struct device *dport_dev, int port_id,
 }
 EXPORT_SYMBOL_GPL(cxl_add_dport);
 
+/**
+ * cxl_decoder_alloc - Allocate a new CXL decoder
+ * @port: owning port of this decoder
+ * @nr_targets: downstream targets accessible by this decoder
+ *
+ * A port should contain one or more decoders. Each of those decoders enable
+ * some address space for CXL.mem utilization. Therefore, it is logical to
+ * allocate decoders while enumerating a port. While >= 1 is defined by the CXL
+ * specification, due to error conditions it is possible that a port may have 0
+ * decoders.
+ *
+ * Return: A new cxl decoder which wants to be added with cxl_decoder_add()
+ */
 struct cxl_decoder *cxl_decoder_alloc(struct cxl_port *port, int nr_targets)
 {
 	struct cxl_decoder *cxld;
@@ -491,6 +504,21 @@ struct cxl_decoder *cxl_decoder_alloc(struct cxl_port *port, int nr_targets)
 }
 EXPORT_SYMBOL_GPL(cxl_decoder_alloc);
 
+/**
+ * cxl_decoder_add - Add a decoder with targets
+ * @host: The containing struct device. This is typically the PCI device that is
+ *        CXL capable
+ * @cxld: The cxl decoder allocated by cxl_decoder_alloc()
+ * @target_map: A list of downstream ports that this decoder can direct memory
+ *              traffic to. These numbers should correspond with the port number
+ *              in the PCIe Link Capabilities structure.
+ *
+ * Return: 0 if decoder was successfully added.
+ *
+ * Certain types of decoders may not have any targets. The main example of this
+ * is an endpoint device. A more awkward example is a hostbridge whose root
+ * ports get hot added (technically possible, though unlikely).
+ */
 int cxl_decoder_add(struct device *host, struct cxl_decoder *cxld,
 		    int *target_map)
 {
-- 
2.33.0