Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 58caaac1 authored by Stuart Yoder's avatar Stuart Yoder Committed by Greg Kroah-Hartman
Browse files

staging: fsl-mc: improve wording in comments 



improve and clarify miscellaneous comments in the bus driver
and allocator

Signed-off-by: default avatarStuart Yoder <stuart.yoder@nxp.com>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent e3494af5

drivers/staging/fsl-mc/bus/fsl-mc-allocator.c

+33 −35
Original line number Diff line number Diff line 
/*

 * 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
Original line number Diff line number Diff line
@@ -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)

{