This commit affects comments (and in one case, whitespace) only.
Throughout the IPA code, return statements are documented using
"@Return:", whereas they should use "Return:" instead. Fix these
mistakes.
In function definitions, some parameters are missing their comment
to describe them. And in structure definitions, some fields are
missing their comment to describe them. Add these missing
descriptions.
Some arguments changed name and type along the way, but their
descriptions were not updated (an endpoint pointer is now used in
many places that previously used an endpoint ID). Fix these
incorrect parameter descriptions.
In the description for the ipa_clock structure, one field had a
semicolon instead of a colon in its description. Fix this.
Add a missing function description for ipa_gsi_endpoint_data_empty().
All of these issues were identified when building with "W=1".
Signed-off-by: Alex Elder <elder@linaro.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
* gsi_channel_poll_one() - Return a single completed transaction on a channel
* @channel: Channel to be polled
*
- * @Return: Transaction pointer, or null if none are available
+ * Return: Transaction pointer, or null if none are available
*
* This function returns the first entry on a channel's completed transaction
* list. If that list is empty, the hardware is consulted to determine
* gsi_channel_poll() - NAPI poll function for a channel
* @napi: NAPI structure for the channel
* @budget: Budget supplied by NAPI core
-
- * @Return: Number of items polled (<= budget)
+ *
+ * Return: Number of items polled (<= budget)
*
* Single transactions completed by hardware are polled until either
* the budget is exhausted, or there are no more. Each transaction
* @gsi: Address of GSI structure embedded in an IPA structure
* @legacy: Set up for legacy hardware
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*
* Performs initialization that must wait until the GSI hardware is
* ready (including firmware loaded).
* @gsi: GSI pointer
* @channel_id: Channel whose limit is to be returned
*
- * @Return: The maximum number of TREs oustanding on the channel
+ * Return: The maximum number of TREs oustanding on the channel
*/
u32 gsi_channel_tre_max(struct gsi *gsi, u32 channel_id);
* @gsi: GSI pointer
* @channel_id: Channel whose limit is to be returned
*
- * @Return: The maximum TRE count per transaction on the channel
+ * Return: The maximum TRE count per transaction on the channel
*/
u32 gsi_channel_trans_tre_max(struct gsi *gsi, u32 channel_id);
* @gsi: GSI pointer
* @channel_id: Channel to start
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
int gsi_channel_start(struct gsi *gsi, u32 channel_id);
* @gsi: GSI pointer returned by gsi_setup()
* @channel_id: Channel to stop
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
int gsi_channel_stop(struct gsi *gsi, u32 channel_id);
* @gsi: Address of GSI structure embedded in an IPA structure
* @pdev: IPA platform device
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*
* Early stage initialization of the GSI subsystem, performing tasks
* that can be done before the GSI hardware is ready to use.
* @channel: Channel associated with the transaction
* @index: Index of the TRE having a transaction
*
- * @Return: The GSI transaction pointer associated with the TRE index
+ * Return: The GSI transaction pointer associated with the TRE index
*/
struct gsi_trans *gsi_channel_trans_mapped(struct gsi_channel *channel,
u32 index);
* gsi_channel_trans_complete() - Return a channel's next completed transaction
* @channel: Channel whose next transaction is to be returned
*
- * @Return: The next completed transaction, or NULL if nothing new
+ * Return: The next completed transaction, or NULL if nothing new
*/
struct gsi_trans *gsi_channel_trans_complete(struct gsi_channel *channel);
* @gsi: GSI pointer
* @channel_id: Channel number
*
- * @Return: 0 if successful, or -ENOMEM on allocation failure
+ * Return: 0 if successful, or -ENOMEM on allocation failure
*
* Creates and sets up information for managing transactions on a channel
*/
* @count: Minimum number of elements in the pool
* @max_alloc: Maximum number of elements allocated at a time from pool
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
int gsi_trans_pool_init(struct gsi_trans_pool *pool, size_t size, u32 count,
u32 max_alloc);
* @pool: Pool pointer
* @count: Number of elements to allocate from the pool
*
- * @Return: Virtual address of element(s) allocated from the pool
+ * Return: Virtual address of element(s) allocated from the pool
*/
void *gsi_trans_pool_alloc(struct gsi_trans_pool *pool, u32 count);
* @count: Minimum number of elements in the pool
* @max_alloc: Maximum number of elements allocated at a time from pool
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*
* Structures in this pool reside in DMA-coherent memory.
*/
* @pool: DMA pool pointer
* @addr: DMA address "handle" associated with the allocation
*
- * @Return: Virtual address of element allocated from the pool
+ * Return: Virtual address of element allocated from the pool
*
* Only one element at a time may be allocated from a DMA pool.
*/
* @tre_count: Number of elements in the transaction
* @direction: DMA direction for entire SGL (or DMA_NONE)
*
- * @Return: A GSI transaction structure, or a null pointer if all
+ * Return: A GSI transaction structure, or a null pointer if all
* available transactions are in use
*/
struct gsi_trans *gsi_channel_trans_alloc(struct gsi *gsi, u32 channel_id,
* @trans: Transaction
* @skb: Socket buffer for transfer (outbound)
*
- * @Return: 0, or -EMSGSIZE if socket data won't fit in transaction.
+ * Return: 0, or -EMSGSIZE if socket data won't fit in transaction.
*/
int gsi_trans_skb_add(struct gsi_trans *trans, struct sk_buff *skb);
/**
* struct ipa_clock - IPA clocking information
* @count: Clocking reference count
- * @mutex; Protects clock enable/disable
+ * @mutex: Protects clock enable/disable
* @core: IPA core clock
* @memory_path: Memory interconnect
* @imem_path: Internal memory interconnect
* ipa_clock_init() - Initialize IPA clocking
* @dev: IPA device
*
- * @Return: A pointer to an ipa_clock structure, or a pointer-coded error
+ * Return: A pointer to an ipa_clock structure, or a pointer-coded error
*/
struct ipa_clock *ipa_clock_init(struct device *dev);
* @ipv6: - Whether the table is for IPv6 or IPv4
* @hashed: - Whether the table is hashed or non-hashed
*
- * @Return: true if region is valid, false otherwise
+ * Return: true if region is valid, false otherwise
*/
bool ipa_cmd_table_valid(struct ipa *ipa, const struct ipa_mem *mem,
bool route, bool ipv6, bool hashed);
* ipa_cmd_data_valid() - Validate command-realted configuration is valid
* @ipa: - IPA pointer
*
- * @Return: true if assumptions required for command are valid
+ * Return: true if assumptions required for command are valid
*/
bool ipa_cmd_data_valid(struct ipa *ipa);
* @channel: AP->IPA command TX GSI channel pointer
* @tre_count: Number of pool elements to allocate
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
int ipa_cmd_pool_init(struct gsi_channel *gsi_channel, u32 tre_count);
/**
* ipa_cmd_tag_process_add_count() - Number of commands in a tag process
*
- * @Return: The number of elements to allocate in a transaction
+ * Return: The number of elements to allocate in a transaction
* to hold tag process commands
*/
u32 ipa_cmd_tag_process_count(void);
* @ipa: IPA pointer
* @tre_count: Number of elements in the transaction
*
- * @Return: A GSI transaction structure, or a null pointer if all
+ * Return: A GSI transaction structure, or a null pointer if all
* available transactions are in use
*/
struct gsi_trans *ipa_cmd_trans_alloc(struct ipa *ipa, u32 tre_count);
/**
* ipa_endpoint_suspend_aggr() - Emulate suspend interrupt
- * @endpoint_id: Endpoint on which to emulate a suspend
+ * @endpoint: Endpoint on which to emulate a suspend
*
* Emulate suspend IPA interrupt to unsuspend an endpoint suspended
* with an open aggregation frame. This is to work around a hardware
}
/**
+ * ipa_endpoint_init_hdr() - Initialize HDR endpoint configuration register
+ * @endpoint: Endpoint pointer
+ *
* We program QMAP endpoints so each packet received is preceded by a QMAP
* header structure. The QMAP header contains a 1-byte mux_id and 2-byte
* packet size field, and we have the IPA hardware populate both for each
/**
* ipa_endpoint_replenish() - Replenish the Rx packets cache.
+ * @endpoint: Endpoint to be replenished
+ * @count: Number of buffers to send to hardware
*
* Allocate RX packet wrapper structures with maximal socket buffers
* for an endpoint. These are supplied to the hardware, which fills
* on its underlying GSI channel, a special sequence of actions must be
* taken to ensure the IPA pipeline is properly cleared.
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
static int ipa_endpoint_reset_rx_aggr(struct ipa_endpoint *endpoint)
{
*/
void ipa_gsi_channel_tx_queued(struct gsi *gsi, u32 channel_id, u32 count,
u32 byte_count);
+
/**
- * ipa_gsi_trans_complete() - GSI transaction completion callback
-ipa_gsi_channel_tx_completed()
+ * ipa_gsi_channel_tx_completed() - GSI transaction completion callback
* @gsi: GSI pointer
* @channel_id: Channel number
* @count: Number of transactions completed since last report
void ipa_gsi_channel_tx_completed(struct gsi *gsi, u32 channel_id, u32 count,
u32 byte_count);
+/* ipa_gsi_endpoint_data_empty() - Empty endpoint config data test
+ * @data: endpoint configuration data
+ *
+ * Determines whether an endpoint configuration data entry is empty,
+ * meaning it contains no valid configuration information and should
+ * be ignored.
+ *
+ * Return: true if empty; false otherwise
+ */
bool ipa_gsi_endpoint_data_empty(const struct ipa_gsi_endpoint_data *data);
#endif /* _IPA_GSI_TRANS_H_ */
* ipa_interrupt_setup() - Set up the IPA interrupt framework
* @ipa: IPA pointer
*
- * @Return: Pointer to IPA SMP2P info, or a pointer-coded error
+ * Return: Pointer to IPA SMP2P info, or a pointer-coded error
*/
struct ipa_interrupt *ipa_interrupt_setup(struct ipa *ipa);
/**
* ipa_hardware_dcd_config() - Enable dynamic clock division on IPA
+ * @ipa: IPA pointer
*
* Configures when the IPA signals it is idle to the global clock
* controller, which can respond by scalling down the clock to
/**
* ipa_config() - Configure IPA hardware
* @ipa: IPA pointer
+ * @data: IPA configuration data
*
* Perform initialization requiring IPA clock to be enabled.
*/
* ipa_probe() - IPA platform driver probe function
* @pdev: Platform device pointer
*
- * @Return: 0 if successful, or a negative error code (possibly
+ * Return: 0 if successful, or a negative error code (possibly
* EPROBE_DEFER)
*
* This is the main entry point for the IPA driver. Initialization proceeds
* ipa_suspend() - Power management system suspend callback
* @dev: IPA device structure
*
- * @Return: Zero
+ * Return: Always returns zero
*
* Called by the PM framework when a system suspend operation is invoked.
*/
* ipa_resume() - Power management system resume callback
* @dev: IPA device structure
*
- * @Return: Always returns 0
+ * Return: Always returns 0
*
* Called by the PM framework when a system resume operation is invoked.
*/
/**
* ipa_mem_setup() - Set up IPA AP and modem shared memory areas
+ * @ipa: IPA pointer
*
* Set up the shared memory regions in IPA local memory. This involves
* zero-filling memory regions, and in the case of header memory, telling
* The AP informs the modem where its portions of memory are located
* in a QMI exchange that occurs at modem startup.
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
int ipa_mem_setup(struct ipa *ipa)
{
/**
* ipa_mem_config() - Configure IPA shared memory
+ * @ipa: IPA pointer
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*/
int ipa_mem_config(struct ipa *ipa)
{
/**
* ipa_mem_zero_modem() - Zero IPA-local memory regions owned by the modem
+ * @ipa: IPA pointer
*
* Zero regions of IPA-local memory used by the modem. These are configured
* (and initially zeroed) by ipa_mem_setup(), but if the modem crashes and
* @ipa: IPA pointer
* @modem_init: Whether the modem is responsible for GSI initialization
*
- * @Return: 0 if successful, or a negative error code
+ * Return: 0 if successful, or a negative error code
*
*/
int ipa_smp2p_init(struct ipa *ipa, bool modem_init);
/**
* ipa_filter_tuple_zero() - Zero an endpoint's hashed filter tuple
- * @endpoint_id: Endpoint whose filter hash tuple should be zeroed
+ * @endpoint: Endpoint whose filter hash tuple should be zeroed
*
* Endpoint must be for the AP (not modem) and support filtering. Updates
* the filter hash values without changing route ones.
/**
* ipa_route_tuple_zero() - Zero a hashed route table entry tuple
+ * @ipa: IPA pointer
* @route_id: Route table entry whose hash tuple should be zeroed
*
* Updates the route hash values without changing filter ones.
* ipa_table_valid() - Validate route and filter table memory regions
* @ipa: IPA pointer
- * @Return: true if all regions are valid, false otherwise
+ * Return: true if all regions are valid, false otherwise
*/
bool ipa_table_valid(struct ipa *ipa);
* ipa_filter_map_valid() - Validate a filter table endpoint bitmap
* @ipa: IPA pointer
*
- * @Return: true if all regions are valid, false otherwise
+ * Return: true if all regions are valid, false otherwise
*/
bool ipa_filter_map_valid(struct ipa *ipa, u32 filter_mask);
/**
* struct ipa_uc_mem_area - AP/microcontroller shared memory area
* @command: command code (AP->microcontroller)
+ * @reserved0: reserved bytes; avoid reading or writing
* @command_param: low 32 bits of command parameter (AP->microcontroller)
* @command_param_hi: high 32 bits of command parameter (AP->microcontroller)
*
* @response: response code (microcontroller->AP)
+ * @reserved1: reserved bytes; avoid reading or writing
* @response_param: response parameter (microcontroller->AP)
*
* @event: event code (microcontroller->AP)
+ * @reserved2: reserved bytes; avoid reading or writing
* @event_param: event parameter (microcontroller->AP)
*
* @first_error_address: address of first error-source on SNOC
* @hw_state: state of hardware (including error type information)
* @warning_counter: counter of non-fatal hardware errors
+ * @reserved3: reserved bytes; avoid reading or writing
* @interface_version: hardware-reported interface version
+ * @reserved4: reserved bytes; avoid reading or writing
*
* A shared memory area at the base of IPA resident memory is used for
* communication with the microcontroller. The region is 128 bytes in
projects / linux.git / commitdiff