Re: [PATCH v3 5/7] PCI: endpoint: Update documentation

[Niklas Cassel <cassel@kernel.org>]

On Fri, Oct 04, 2024 at 02:07:40PM +0900, Damien Le Moal wrote:
> Document the new functions pci_epc_map_align(), pci_epc_mem_map() and
> pci_epc_mem_unmap(). Also add the documentation for the functions
> pci_epc_map_addr() and pci_epc_unmap_addr() that were missing.
> 
> Signed-off-by: Damien Le Moal <dlemoal@kernel.org>
> ---
>  Documentation/PCI/endpoint/pci-endpoint.rst | 33 +++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/Documentation/PCI/endpoint/pci-endpoint.rst b/Documentation/PCI/endpoint/pci-endpoint.rst
> index 21507e3cc238..80061110441d 100644
> --- a/Documentation/PCI/endpoint/pci-endpoint.rst
> +++ b/Documentation/PCI/endpoint/pci-endpoint.rst
> @@ -117,6 +117,39 @@ by the PCI endpoint function driver.
>     The PCI endpoint function driver should use pci_epc_mem_free_addr() to
>     free the memory space allocated using pci_epc_mem_alloc_addr().
>  
> +* pci_epc_map_align()
> +
> +   The PCI endpoint controller may impose constraints on the RC PCI addresses
> +   that can be mapped. The function pci_epc_map_align() allows endpoint drivers
> +   to discover and handle such constraint by providing the size of the memory

Nit: s/constraint/constraints/


> +   that must be allocated with pci_epc_mem_alloc_addr() for successfully mapping
> +   any RC PCI address. This function will also indicate the offset into the
> +   allocated memory to use for accessing the target RC PCI address.

Should probably also mention that it might map less memory than requested.


> +
> +* pci_epc_map_addr()
> +
> +  A PCI endpoint function driver should use pci_epc_map_addr() to map to a RC
> +  PCI address the CPU address of local memory obtained with
> +  pci_epc_mem_alloc_addr().
> +
> +* pci_epc_unmap_addr()
> +
> +  A PCI endpoint function driver should use pci_epc_unmap_addr() to unmap the
> +  CPU address of local memory mapped to a RC address with pci_epc_map_addr().
> +
> +* pci_epc_mem_map()
> +
> +  A PCI endpoint function driver can use pci_epc_mem_map() to allocate and map
> +  a RC PCI address range. This function combines calls to pci_epc_map_align(),
> +  pci_epc_mem_alloc_addr() and pci_epc_mem_alloc_addr() into a single function
> +  to simplify the PCI address mapping handling in endpoitn function drivers.

s/endpoitn/endpoint/


> +
> +* pci_epc_mem_unmap()
> +
> +  A PCI endpoint function driver can use pci_epc_mem_unmap() to unmap and free
> +  memory that was allocated and mapped using pci_epc_mem_map().
> +
> +
>  Other EPC APIs
>  ~~~~~~~~~~~~~~
>  
> -- 
> 2.46.2
> 

I think that it would make more sense if you squashed the doc updates for
each function into the respective commit that add the new function(s).

Sure, you would still need a commit that adds the documentation for the
functions that was missing, but that is expected.


Regardless:
Reviewed-by: Niklas Cassel <cassel@kernel.org>