git: 0c7aa9afb163 - stable/14 - new-bus: Add comments for resource_*_map_request*

The branch stable/14 has been updated by jhb:

URL: https://cgit.FreeBSD.org/src/commit/?id=0c7aa9afb1633f1fc068dc043732c18e18facb2a

commit 0c7aa9afb1633f1fc068dc043732c18e18facb2a
Author:     John Baldwin <jhb@FreeBSD.org>
AuthorDate: 2023-11-24 18:33:57 +0000
Commit:     John Baldwin <jhb@FreeBSD.org>
CommitDate: 2024-01-03 20:47:18 +0000

    new-bus: Add comments for resource_*_map_request*
    
    Requested by:   mhorne
    
    (cherry picked from commit 46971d38de334a9418e2b66b37cea7d051b6731a)
---
 sys/kern/subr_bus.c | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/sys/kern/subr_bus.c b/sys/kern/subr_bus.c
index 4c44c264a5c0..4d21382f2de7 100644
--- a/sys/kern/subr_bus.c
+++ b/sys/kern/subr_bus.c
@@ -2707,6 +2707,15 @@ device_set_unit(device_t dev, int unit)
  * Some useful method implementations to make life easier for bus drivers.
  */
 
+/**
+ * @brief Initialize a resource mapping request
+ *
+ * This is the internal implementation of the public API
+ * resource_init_map_request.  Callers may be using a different layout
+ * of struct resource_map_request than the kernel, so callers pass in
+ * the size of the structure they are using to identify the structure
+ * layout.
+ */
 void
 resource_init_map_request_impl(struct resource_map_request *args, size_t sz)
 {
@@ -2715,6 +2724,18 @@ resource_init_map_request_impl(struct resource_map_request *args, size_t sz)
 	args->memattr = VM_MEMATTR_DEVICE;
 }
 
+/**
+ * @brief Validate a resource mapping request
+ *
+ * Translate a device driver's mapping request (@p in) to a struct
+ * resource_map_request using the current structure layout (@p out).
+ * In addition, validate the offset and length from the mapping
+ * request against the bounds of the resource @p r.  If the offset or
+ * length are invalid, fail with EINVAL.  If the offset and length are
+ * valid, the absolute starting address of the requested mapping is
+ * returned in @p startp and the length of the requested mapping is
+ * returned in @p lengthp.
+ */
 int
 resource_validate_map_request(struct resource *r,
     struct resource_map_request *in, struct resource_map_request *out,