Commit 3591538a authored by Alastair D'Silva's avatar Alastair D'Silva Committed by Michael Ellerman
Browse files

ocxl: Address kernel doc errors & warnings 



This patch addresses warnings and errors from the kernel doc scripts for
the OpenCAPI driver.

It also makes minor tweaks to make the docs more consistent.

Signed-off-by: default avatarAlastair D'Silva <alastair@d-silva.org>
Acked-by: default avatarAndrew Donnellan <ajd@linux.ibm.com>
Signed-off-by: default avatarMichael Ellerman <mpe@ellerman.id.au>
Link: https://lore.kernel.org/r/20200415012343.919255-3-alastair@d-silva.org
parent c75d42e4

drivers/misc/ocxl/config.c

+12 −12
Original line number Diff line number Diff line
@@ -344,11 +344,11 @@ static int read_afu_info(struct pci_dev *dev, struct ocxl_fn_config *fn, 
}



/**

 * Read the template version from the AFU

 * dev: the device for the AFU

 * fn: the AFU offsets

 * len: outputs the template length

 * version: outputs the major<<8,minor version

 * read_template_version() - Read the template version from the AFU

 * @dev: the device for the AFU

 * @fn: the AFU offsets

 * @len: outputs the template length

 * @version: outputs the major<<8,minor version

 *

 * Returns 0 on success, negative on failure

 */
@@ -547,10 +547,10 @@ static int validate_afu(struct pci_dev *dev, struct ocxl_afu_config *afu) 
}



/**

 * Populate AFU metadata regarding LPC memory

 * dev: the device for the AFU

 * fn: the AFU offsets

 * afu: the AFU struct to populate the LPC metadata into

 * read_afu_lpc_memory_info() - Populate AFU metadata regarding LPC memory

 * @dev: the device for the AFU

 * @fn: the AFU offsets

 * @afu: the AFU struct to populate the LPC metadata into

 *

 * Returns 0 on success, negative on failure

 */

drivers/misc/ocxl/ocxl_internal.h

+5 −4
Original line number Diff line number Diff line
@@ -128,11 +128,12 @@ int ocxl_config_check_afu_index(struct pci_dev *dev, 
				struct ocxl_fn_config *fn, int afu_idx);



/**

 * Update values within a Process Element

 * ocxl_link_update_pe() - Update values within a Process Element

 * @link_handle: the link handle associated with the process element

 * @pasid: the PASID for the AFU context

 * @tid: the new thread id for the process element

 *

 * link_handle: the link handle associated with the process element

 * pasid: the PASID for the AFU context

 * tid: the new thread id for the process element

 * Returns 0 on success

 */

int ocxl_link_update_pe(void *link_handle, int pasid, __u16 tid);

include/misc/ocxl.h

+38 −58
Original line number Diff line number Diff line
@@ -62,8 +62,7 @@ struct ocxl_context; 
// Device detection & initialisation



/**

 * Open an OpenCAPI function on an OpenCAPI device

 *

 * ocxl_function_open() - Open an OpenCAPI function on an OpenCAPI device

 * @dev: The PCI device that contains the function

 *

 * Returns an opaque pointer to the function, or an error pointer (check with IS_ERR)
@@ -71,8 +70,7 @@ struct ocxl_context; 
struct ocxl_fn *ocxl_function_open(struct pci_dev *dev);



/**

 * Get the list of AFUs associated with a PCI function device

 *

 * ocxl_function_afu_list() - Get the list of AFUs associated with a PCI function device

 * Returns a list of struct ocxl_afu *

 *

 * @fn: The OpenCAPI function containing the AFUs
@@ -80,8 +78,7 @@ struct ocxl_fn *ocxl_function_open(struct pci_dev *dev); 
struct list_head *ocxl_function_afu_list(struct ocxl_fn *fn);



/**

 * Fetch an AFU instance from an OpenCAPI function

 *

 * ocxl_function_fetch_afu() - Fetch an AFU instance from an OpenCAPI function

 * @fn: The OpenCAPI function to get the AFU from

 * @afu_idx: The index of the AFU to get

 *
@@ -92,23 +89,20 @@ struct list_head *ocxl_function_afu_list(struct ocxl_fn *fn); 
struct ocxl_afu *ocxl_function_fetch_afu(struct ocxl_fn *fn, u8 afu_idx);



/**

 * Take a reference to an AFU

 *

 * ocxl_afu_get() - Take a reference to an AFU

 * @afu: The AFU to increment the reference count on

 */

void ocxl_afu_get(struct ocxl_afu *afu);



/**

 * Release a reference to an AFU

 *

 * ocxl_afu_put() - Release a reference to an AFU

 * @afu: The AFU to decrement the reference count on

 */

void ocxl_afu_put(struct ocxl_afu *afu);





/**

 * Get the configuration information for an OpenCAPI function

 *

 * ocxl_function_config() - Get the configuration information for an OpenCAPI function

 * @fn: The OpenCAPI function to get the config for

 *

 * Returns the function config, or NULL on error
@@ -116,8 +110,7 @@ void ocxl_afu_put(struct ocxl_afu *afu); 
const struct ocxl_fn_config *ocxl_function_config(struct ocxl_fn *fn);



/**

 * Close an OpenCAPI function

 *

 * ocxl_function_close() - Close an OpenCAPI function

 * This will free any AFUs previously retrieved from the function, and

 * detach and associated contexts. The contexts must by freed by the caller.

 *
@@ -129,8 +122,7 @@ void ocxl_function_close(struct ocxl_fn *fn); 
// Context allocation



/**

 * Allocate an OpenCAPI context

 *

 * ocxl_context_alloc() - Allocate an OpenCAPI context

 * @context: The OpenCAPI context to allocate, must be freed with ocxl_context_free

 * @afu: The AFU the context belongs to

 * @mapping: The mapping to unmap when the context is closed (may be NULL)
@@ -139,14 +131,13 @@ int ocxl_context_alloc(struct ocxl_context **context, struct ocxl_afu *afu, 
			struct address_space *mapping);



/**

 * Free an OpenCAPI context

 *

 * ocxl_context_free() - Free an OpenCAPI context

 * @ctx: The OpenCAPI context to free

 */

void ocxl_context_free(struct ocxl_context *ctx);



/**

 * Grant access to an MM to an OpenCAPI context

 * ocxl_context_attach() - Grant access to an MM to an OpenCAPI context

 * @ctx: The OpenCAPI context to attach

 * @amr: The value of the AMR register to restrict access

 * @mm: The mm to attach to the context
@@ -157,7 +148,7 @@ int ocxl_context_attach(struct ocxl_context *ctx, u64 amr, 
				struct mm_struct *mm);



/**

 * Detach an MM from an OpenCAPI context

 * ocxl_context_detach() - Detach an MM from an OpenCAPI context

 * @ctx: The OpenCAPI context to attach

 *

 * Returns 0 on success, negative on failure
@@ -167,7 +158,7 @@ int ocxl_context_detach(struct ocxl_context *ctx); 
// AFU IRQs



/**

 * Allocate an IRQ associated with an AFU context

 * ocxl_afu_irq_alloc() - Allocate an IRQ associated with an AFU context

 * @ctx: the AFU context

 * @irq_id: out, the IRQ ID

 *
@@ -176,7 +167,7 @@ int ocxl_context_detach(struct ocxl_context *ctx); 
int ocxl_afu_irq_alloc(struct ocxl_context *ctx, int *irq_id);



/**

 * Frees an IRQ associated with an AFU context

 * ocxl_afu_irq_free() - Frees an IRQ associated with an AFU context

 * @ctx: the AFU context

 * @irq_id: the IRQ ID

 *
@@ -185,7 +176,7 @@ int ocxl_afu_irq_alloc(struct ocxl_context *ctx, int *irq_id); 
int ocxl_afu_irq_free(struct ocxl_context *ctx, int irq_id);



/**

 * Gets the address of the trigger page for an IRQ

 * ocxl_afu_irq_get_addr() - Gets the address of the trigger page for an IRQ

 * This can then be provided to an AFU which will write to that

 * page to trigger the IRQ.

 * @ctx: The AFU context that the IRQ is associated with
@@ -196,7 +187,7 @@ int ocxl_afu_irq_free(struct ocxl_context *ctx, int irq_id); 
u64 ocxl_afu_irq_get_addr(struct ocxl_context *ctx, int irq_id);



/**

 * Provide a callback to be called when an IRQ is triggered

 * ocxl_irq_set_handler() - Provide a callback to be called when an IRQ is triggered

 * @ctx: The AFU context that the IRQ is associated with

 * @irq_id: The IRQ ID

 * @handler: the callback to be called when the IRQ is triggered
@@ -213,8 +204,7 @@ int ocxl_irq_set_handler(struct ocxl_context *ctx, int irq_id, 
// AFU Metadata



/**

 * Get a pointer to the config for an AFU

 *

 * ocxl_afu_config() - Get a pointer to the config for an AFU

 * @afu: a pointer to the AFU to get the config for

 *

 * Returns a pointer to the AFU config
@@ -222,27 +212,24 @@ int ocxl_irq_set_handler(struct ocxl_context *ctx, int irq_id, 
struct ocxl_afu_config *ocxl_afu_config(struct ocxl_afu *afu);



/**

 * Assign opaque hardware specific information to an OpenCAPI AFU.

 *

 * @dev: The PCI device associated with the OpenCAPI device

 * ocxl_afu_set_private() - Assign opaque hardware specific information to an OpenCAPI AFU.

 * @afu: The OpenCAPI AFU

 * @private: the opaque hardware specific information to assign to the driver

 */

void ocxl_afu_set_private(struct ocxl_afu *afu, void *private);



/**

 * Fetch the hardware specific information associated with an external OpenCAPI

 * AFU. This may be consumed by an external OpenCAPI driver.

 *

 * @afu: The AFU

 * ocxl_afu_get_private() - Fetch the hardware specific information associated with

 * an external OpenCAPI AFU. This may be consumed by an external OpenCAPI driver.

 * @afu: The OpenCAPI AFU

 *

 * Returns the opaque pointer associated with the device, or NULL if not set

 */

void *ocxl_afu_get_private(struct ocxl_afu *dev);

void *ocxl_afu_get_private(struct ocxl_afu *afu);



// Global MMIO

/**

 * Read a 32 bit value from global MMIO

 *

 * ocxl_global_mmio_read32() - Read a 32 bit value from global MMIO

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -254,8 +241,7 @@ int ocxl_global_mmio_read32(struct ocxl_afu *afu, size_t offset, 
			    enum ocxl_endian endian, u32 *val);



/**

 * Read a 64 bit value from global MMIO

 *

 * ocxl_global_mmio_read64() - Read a 64 bit value from global MMIO

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -267,8 +253,7 @@ int ocxl_global_mmio_read64(struct ocxl_afu *afu, size_t offset, 
			    enum ocxl_endian endian, u64 *val);



/**

 * Write a 32 bit value to global MMIO

 *

 * ocxl_global_mmio_write32() - Write a 32 bit value to global MMIO

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -280,8 +265,7 @@ int ocxl_global_mmio_write32(struct ocxl_afu *afu, size_t offset, 
			     enum ocxl_endian endian, u32 val);



/**

 * Write a 64 bit value to global MMIO

 *

 * ocxl_global_mmio_write64() - Write a 64 bit value to global MMIO

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -293,8 +277,7 @@ int ocxl_global_mmio_write64(struct ocxl_afu *afu, size_t offset, 
			     enum ocxl_endian endian, u64 val);



/**

 * Set bits in a 32 bit global MMIO register

 *

 * ocxl_global_mmio_set32() - Set bits in a 32 bit global MMIO register

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -306,8 +289,7 @@ int ocxl_global_mmio_set32(struct ocxl_afu *afu, size_t offset, 
			   enum ocxl_endian endian, u32 mask);



/**

 * Set bits in a 64 bit global MMIO register

 *

 * ocxl_global_mmio_set64() - Set bits in a 64 bit global MMIO register

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -319,8 +301,7 @@ int ocxl_global_mmio_set64(struct ocxl_afu *afu, size_t offset, 
			   enum ocxl_endian endian, u64 mask);



/**

 * Set bits in a 32 bit global MMIO register

 *

 * ocxl_global_mmio_clear32() - Set bits in a 32 bit global MMIO register

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in
@@ -332,8 +313,7 @@ int ocxl_global_mmio_clear32(struct ocxl_afu *afu, size_t offset, 
			     enum ocxl_endian endian, u32 mask);



/**

 * Set bits in a 64 bit global MMIO register

 *

 * ocxl_global_mmio_clear64() - Set bits in a 64 bit global MMIO register

 * @afu: The AFU

 * @offset: The Offset from the start of MMIO

 * @endian: the endianness that the MMIO data is in

CRA Git | Maintained and supported by SUSTech CRA and CCSE