staging: fsl-mc: improve comment wording
PATCH 12/14 staging: fsl-mc: improve comment wording
improve and clarify miscellaneous comments
-when referring to the bus call it "fsl-mc"
-reduce the verbosity of some comments for clarity -improve wording of the slightly confusing term "MC object device"
Signed-off-by Stuart Yoder <[email protected]>
--- 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(-)
drivers/staging/fsl-mc/bus/fsl-mc-allocator.c +33 -35
@@ -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) {
drivers/staging/fsl-mc/bus/fsl-mc-bus.c +9 -9
@@ -34,7 +34,7 @@/** * 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 */
@@ -62,8 +62,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.
@@ -91,7 +91,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 &&
@@ -448,7 +448,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,
@@ -529,8 +529,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 ;
@@ -585,10 +585,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) {
Signature · 1 line
1.9.0