From 58caaac1f50331dd687ab39d8b3f90f7eabdb1b5 Mon Sep 17 00:00:00 2001 From: Stuart Yoder Date: Wed, 26 Oct 2016 11:20:32 -0500 Subject: [PATCH] staging: fsl-mc: improve wording in comments improve and clarify miscellaneous comments in the bus driver and allocator Signed-off-by: Stuart Yoder Signed-off-by: Greg Kroah-Hartman --- drivers/staging/fsl-mc/bus/fsl-mc-allocator.c | 68 +++++++++---------- drivers/staging/fsl-mc/bus/fsl-mc-bus.c | 18 ++--- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/drivers/staging/fsl-mc/bus/fsl-mc-allocator.c b/drivers/staging/fsl-mc/bus/fsl-mc-allocator.c index e92c7804daab..4a7ac976f3fa 100644 --- a/drivers/staging/fsl-mc/bus/fsl-mc-allocator.c +++ b/drivers/staging/fsl-mc/bus/fsl-mc-allocator.c @@ -1,5 +1,5 @@ /* - * Freescale MC object device allocator driver + * fsl-mc object allocator driver * * Copyright (C) 2013 Freescale Semiconductor, Inc. * @@ -23,15 +23,12 @@ strcmp(_obj_type, "dpcon") == 0) /** - * fsl_mc_resource_pool_add_device - add allocatable device to a resource - * pool of a given MC bus + * fsl_mc_resource_pool_add_device - add allocatable object to a resource + * pool of a given fsl-mc bus * - * @mc_bus: pointer to the MC bus - * @pool_type: MC bus pool type - * @mc_dev: Pointer to allocatable MC object device - * - * It adds an allocatable MC object device to a container's resource pool of - * the given resource type + * @mc_bus: pointer to the fsl-mc bus + * @pool_type: pool type + * @mc_dev: pointer to allocatable fsl-mc device */ static int __must_check fsl_mc_resource_pool_add_device(struct fsl_mc_bus *mc_bus, @@ -95,10 +92,10 @@ static int __must_check fsl_mc_resource_pool_add_device(struct fsl_mc_bus * fsl_mc_resource_pool_remove_device - remove an allocatable device from a * resource pool * - * @mc_dev: Pointer to allocatable MC object device + * @mc_dev: pointer to allocatable fsl-mc device * - * It permanently removes an allocatable MC object device from the resource - * pool, the device is currently in, as long as it is in the pool's free list. + * It permanently removes an allocatable fsl-mc device from the resource + * pool. It's an error if the device is in use. */ static int __must_check fsl_mc_resource_pool_remove_device(struct fsl_mc_device *mc_dev) @@ -255,17 +252,18 @@ void fsl_mc_resource_free(struct fsl_mc_resource *resource) EXPORT_SYMBOL_GPL(fsl_mc_resource_free); /** - * fsl_mc_object_allocate - Allocates a MC object device of the given - * pool type from a given MC bus + * fsl_mc_object_allocate - Allocates an fsl-mc object of the given + * pool type from a given fsl-mc bus instance * - * @mc_dev: MC device for which the MC object device is to be allocated - * @pool_type: MC bus resource pool type - * @new_mc_dev: Pointer to area where the pointer to the allocated - * MC object device is to be returned + * @mc_dev: fsl-mc device which is used in conjunction with the + * allocated object + * @pool_type: pool type + * @new_mc_dev: pointer to area where the pointer to the allocated device + * is to be returned * - * This function allocates a MC object device from the device's parent DPRC, - * from the corresponding MC bus' pool of allocatable MC object devices of - * the given resource type. mc_dev cannot be a DPRC itself. + * Allocatable objects are always used in conjunction with some functional + * device. This function allocates an object of the specified type from + * the DPRC containing the functional device. * * NOTE: pool_type must be different from FSL_MC_POOL_MCP, since MC * portals are allocated using fsl_mc_portal_allocate(), instead of @@ -312,10 +310,9 @@ int __must_check fsl_mc_object_allocate(struct fsl_mc_device *mc_dev, EXPORT_SYMBOL_GPL(fsl_mc_object_allocate); /** - * fsl_mc_object_free - Returns an allocatable MC object device to the - * corresponding resource pool of a given MC bus. - * - * @mc_adev: Pointer to the MC object device + * fsl_mc_object_free - Returns an fsl-mc object to the resource + * pool where it came from. + * @mc_adev: Pointer to the fsl-mc device */ void fsl_mc_object_free(struct fsl_mc_device *mc_adev) { @@ -332,8 +329,14 @@ void fsl_mc_object_free(struct fsl_mc_device *mc_adev) EXPORT_SYMBOL_GPL(fsl_mc_object_free); /* - * Initialize the interrupt pool associated with a MC bus. - * It allocates a block of IRQs from the GIC-ITS + * A DPRC and the devices in the DPRC all share the same GIC-ITS device + * ID. A block of IRQs is pre-allocated and maintained in a pool + * from which devices can allocate them when needed. + */ + +/* + * Initialize the interrupt pool associated with an fsl-mc bus. + * It allocates a block of IRQs from the GIC-ITS. */ int fsl_mc_populate_irq_pool(struct fsl_mc_bus *mc_bus, unsigned int irq_count) @@ -395,7 +398,7 @@ int fsl_mc_populate_irq_pool(struct fsl_mc_bus *mc_bus, EXPORT_SYMBOL_GPL(fsl_mc_populate_irq_pool); /** - * Teardown the interrupt pool associated with an MC bus. + * Teardown the interrupt pool associated with an fsl-mc bus. * It frees the IRQs that were allocated to the pool, back to the GIC-ITS. */ void fsl_mc_cleanup_irq_pool(struct fsl_mc_bus *mc_bus) @@ -422,11 +425,7 @@ void fsl_mc_cleanup_irq_pool(struct fsl_mc_bus *mc_bus) EXPORT_SYMBOL_GPL(fsl_mc_cleanup_irq_pool); /** - * It allocates the IRQs required by a given MC object device. The - * IRQs are allocated from the interrupt pool associated with the - * MC bus that contains the device, if the device is not a DPRC device. - * Otherwise, the IRQs are allocated from the interrupt pool associated - * with the MC bus that represents the DPRC device itself. + * Allocate the IRQs required by a given fsl-mc device. */ int __must_check fsl_mc_allocate_irqs(struct fsl_mc_device *mc_dev) { @@ -495,8 +494,7 @@ int __must_check fsl_mc_allocate_irqs(struct fsl_mc_device *mc_dev) EXPORT_SYMBOL_GPL(fsl_mc_allocate_irqs); /* - * It frees the IRQs that were allocated for a MC object device, by - * returning them to the corresponding interrupt pool. + * Frees the IRQs that were allocated for an fsl-mc device. */ void fsl_mc_free_irqs(struct fsl_mc_device *mc_dev) { diff --git a/drivers/staging/fsl-mc/bus/fsl-mc-bus.c b/drivers/staging/fsl-mc/bus/fsl-mc-bus.c index fb062d39503f..6f148b2cd504 100644 --- a/drivers/staging/fsl-mc/bus/fsl-mc-bus.c +++ b/drivers/staging/fsl-mc/bus/fsl-mc-bus.c @@ -36,7 +36,7 @@ static struct kmem_cache *mc_dev_cache; /** * struct fsl_mc - Private data of a "fsl,qoriq-mc" platform device - * @root_mc_bus_dev: MC object device representing the root DPRC + * @root_mc_bus_dev: fsl-mc device representing the root DPRC * @num_translation_ranges: number of entries in addr_translation_ranges * @translation_ranges: array of bus to system address translation ranges */ @@ -64,8 +64,8 @@ struct fsl_mc_addr_translation_range { /** * fsl_mc_bus_match - device to driver matching callback - * @dev: the MC object device structure to match against - * @drv: the device driver to search for matching MC object device id + * @dev: the fsl-mc device to match against + * @drv: the device driver to search for matching fsl-mc object type * structures * * Returns 1 on success, 0 otherwise. @@ -93,7 +93,7 @@ static int fsl_mc_bus_match(struct device *dev, struct device_driver *drv) /* * Traverse the match_id table of the given driver, trying to find - * a matching for the given MC object device. + * a matching for the given device. */ for (id = mc_drv->match_id_table; id->vendor != 0x0; id++) { if (id->vendor == mc_dev->obj_desc.vendor && @@ -450,7 +450,7 @@ bool fsl_mc_is_root_dprc(struct device *dev) } /** - * Add a newly discovered MC object device to be visible in Linux + * Add a newly discovered fsl-mc device to be visible in Linux */ int fsl_mc_device_add(struct dprc_obj_desc *obj_desc, struct fsl_mc_io *mc_io, @@ -531,8 +531,8 @@ int fsl_mc_device_add(struct dprc_obj_desc *obj_desc, goto error_cleanup_dev; } else { /* - * A non-DPRC MC object device has to be a child of another - * MC object (specifically a DPRC object) + * A non-DPRC object has to be a child of a DPRC, use the + * parent's ICID and interrupt domain. */ mc_dev->icid = parent_mc_dev->icid; mc_dev->dma_mask = FSL_MC_DEFAULT_DMA_MASK; @@ -587,10 +587,10 @@ int fsl_mc_device_add(struct dprc_obj_desc *obj_desc, EXPORT_SYMBOL_GPL(fsl_mc_device_add); /** - * fsl_mc_device_remove - Remove a MC object device from being visible to + * fsl_mc_device_remove - Remove an fsl-mc device from being visible to * Linux * - * @mc_dev: Pointer to a MC object device object + * @mc_dev: Pointer to an fsl-mc device */ void fsl_mc_device_remove(struct fsl_mc_device *mc_dev) { -- 2.45.2