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
Loading
Loading
Loading
Loading
+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)
{
+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)
{