firewire: core: fix fw_send_request kerneldoc comment

The present inline documentation of the fw_send_request() in-kernel API refers to userland code that is not applicable to kernel drivers at all. Reported-by: Ben Gamari <bgamari.foss@gmail.com> While we are at fixing the whole documentation of fw_send_request(), also improve the rest of firewire-core's kerneldoc comments: - Add a bit of text concerning fw_run_transaction()'s call parameters. - Append () to function names and tab-align parameter descriptions as suggested by the example in Documentation/kernel-doc-nano-HOWTO.txt. - Remove kerneldoc markers from comments on static functions. - Remove outdated parameter descriptions at build_tree(). Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>

firewire: core: fix fw_send_request kerneldoc comment
The present inline documentation of the fw_send_request() in-kernel API refers to userland code that is not applicable to kernel drivers at all. Reported-by: Ben Gamari <bgamari.foss@gmail.com> While we are at fixing the whole documentation of fw_send_request(), also improve the rest of firewire-core's kerneldoc comments: - Add a bit of text concerning fw_run_transaction()'s call parameters. - Append () to function names and tab-align parameter descriptions as suggested by the example in Documentation/kernel-doc-nano-HOWTO.txt. - Remove kerneldoc markers from comments on static functions. - Remove outdated parameter descriptions at build_tree(). Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
Stefan Richter
1 parent a8e93f3dcc
Showing 4 changed files with 57 additions and 55 deletions Side-by-side Diff
drivers/firewire/core-device.c
drivers/firewire/core-iso.c
drivers/firewire/core-topology.c
drivers/firewire/core-transaction.c
@@ -107,11 +107,11 @@
 }
  
 /**
- * fw_csr_string - reads a string from the configuration ROM
- * @directory: e.g. root directory or unit directory
- * @key: the key of the preceding directory entry
- * @buf: where to put the string
- * @size: size of @buf, in bytes
+ * fw_csr_string() - reads a string from the configuration ROM
+ * @directory:	e.g. root directory or unit directory
+ * @key:	the key of the preceding directory entry
+ * @buf:	where to put the string
+ * @size:	size of @buf, in bytes
  *
  * The string is taken from a minimal ASCII text descriptor leaf after
  * the immediate entry with @key.  The string is zero-terminated.
@@ -272,7 +272,7 @@
 }
  
 /**
- * fw_iso_resource_manage - Allocate or deallocate a channel and/or bandwidth
+ * fw_iso_resource_manage() - Allocate or deallocate a channel and/or bandwidth
  *
  * In parameters: card, generation, channels_mask, bandwidth, allocate
  * Out parameters: channel, bandwidth
@@ -174,12 +174,7 @@
 	return list_entry(l, struct fw_node, link);
 }
  
-/**
- * build_tree - Build the tree representation of the topology
- * @self_ids: array of self IDs to create the tree from
- * @self_id_count: the length of the self_ids array
- * @local_id: the node ID of the local node
- *
+/*
  * This function builds the tree representation of the topology given
  * by the self IDs from the latest bus reset.  During the construction
  * of the tree, the function checks that the self IDs are valid and
@@ -420,11 +415,10 @@
 	}
 }
  
-/**
- * update_tree - compare the old topology tree for card with the new
- * one specified by root.  Queue the nodes and mark them as either
- * found, lost or updated.  Update the nodes in the card topology tree
- * as we go.
+/*
+ * Compare the old topology tree for card with the new one specified by root.
+ * Queue the nodes and mark them as either found, lost or updated.
+ * Update the nodes in the card topology tree as we go.
  */
 static void update_tree(struct fw_card *card, struct fw_node *root)
 {
@@ -273,43 +273,49 @@
 }
  
 /**
- * This function provides low-level access to the IEEE1394 transaction
- * logic.  Most C programs would use either fw_read(), fw_write() or
- * fw_lock() instead - those function are convenience wrappers for
- * this function.  The fw_send_request() function is primarily
- * provided as a flexible, one-stop entry point for languages bindings
- * and protocol bindings.
+ * fw_send_request() - submit a request packet for transmission
+ * @card:		interface to send the request at
+ * @t:			transaction instance to which the request belongs
+ * @tcode:		transaction code
+ * @destination_id:	destination node ID, consisting of bus_ID and phy_ID
+ * @generation:		bus generation in which request and response are valid
+ * @speed:		transmission speed
+ * @offset:		48bit wide offset into destination's address space
+ * @payload:		data payload for the request subaction
+ * @length:		length of the payload, in bytes
+ * @callback:		function to be called when the transaction is completed
+ * @callback_data:	data to be passed to the transaction completion callback
  *
- * FIXME: Document this function further, in particular the possible
- * values for rcode in the callback.  In short, we map ACK_COMPLETE to
- * RCODE_COMPLETE, internal errors set errno and set rcode to
- * RCODE_SEND_ERROR (which is out of range for standard ieee1394
- * rcodes).  All other rcodes are forwarded unchanged.  For all
- * errors, payload is NULL, length is 0.
+ * Submit a request packet into the asynchronous request transmission queue.
+ * Can be called from atomic context.  If you prefer a blocking API, use
+ * fw_run_transaction() in a context that can sleep.
  *
- * Can not expect the callback to be called before the function
- * returns, though this does happen in some cases (ACK_COMPLETE and
- * errors).
+ * In case of lock requests, specify one of the firewire-core specific %TCODE_
+ * constants instead of %TCODE_LOCK_REQUEST in @tcode.
  *
- * The payload is only used for write requests and must not be freed
- * until the callback has been called.
+ * Make sure that the value in @destination_id is not older than the one in
+ * @generation.  Otherwise the request is in danger to be sent to a wrong node.
  *
- * @param card the card from which to send the request
- * @param tcode the tcode for this transaction.  Do not use
- *   TCODE_LOCK_REQUEST directly, instead use TCODE_LOCK_MASK_SWAP
- *   etc. to specify tcode and ext_tcode.
- * @param node_id the destination node ID (bus ID and PHY ID concatenated)
- * @param generation the generation for which node_id is valid
- * @param speed the speed to use for sending the request
- * @param offset the 48 bit offset on the destination node
- * @param payload the data payload for the request subaction
- * @param length the length in bytes of the data to read
- * @param callback function to be called when the transaction is completed
- * @param callback_data pointer to arbitrary data, which will be
- *   passed to the callback
- *
- * In case of asynchronous stream packets i.e. TCODE_STREAM_DATA, the caller
+ * In case of asynchronous stream packets i.e. %TCODE_STREAM_DATA, the caller
  * needs to synthesize @destination_id with fw_stream_packet_destination_id().
+ * It will contain tag, channel, and sy data instead of a node ID then.
+ *
+ * The payload buffer at @data is going to be DMA-mapped except in case of
+ * quadlet-sized payload or of local (loopback) requests.  Hence make sure that
+ * the buffer complies with the restrictions for DMA-mapped memory.  The
+ * @payload must not be freed before the @callback is called.
+ *
+ * In case of request types without payload, @data is NULL and @length is 0.
+ *
+ * After the transaction is completed successfully or unsuccessfully, the
+ * @callback will be called.  Among its parameters is the response code which
+ * is either one of the rcodes per IEEE 1394 or, in case of internal errors,
+ * the firewire-core specific %RCODE_SEND_ERROR.
+ *
+ * Note some timing corner cases:  fw_send_request() may complete much earlier
+ * than when the request packet actually hits the wire.  On the other hand,
+ * transaction completion and hence execution of @callback may happen even
+ * before fw_send_request() returns.
  */
 void fw_send_request(struct fw_card *card, struct fw_transaction *t, int tcode,
 		     int destination_id, int generation, int speed,
  
@@ -375,9 +381,11 @@
 }
  
 /**
- * fw_run_transaction - send request and sleep until transaction is completed
+ * fw_run_transaction() - send request and sleep until transaction is completed
  *
- * Returns the RCODE.
+ * Returns the RCODE.  See fw_send_request() for parameter documentation.
+ * Unlike fw_send_request(), @data points to the payload of the request or/and
+ * to the payload of the response.
  */
 int fw_run_transaction(struct fw_card *card, int tcode, int destination_id,
 		       int generation, int speed, unsigned long long offset,
@@ -495,9 +503,9 @@
 }
  
 /**
- * fw_core_add_address_handler - register for incoming requests
- * @handler: callback
- * @region: region in the IEEE 1212 node space address range
+ * fw_core_add_address_handler() - register for incoming requests
+ * @handler:	callback
+ * @region:	region in the IEEE 1212 node space address range
  *
  * region->start, ->end, and handler->length have to be quadlet-aligned.
  *
@@ -552,7 +560,7 @@
 EXPORT_SYMBOL(fw_core_add_address_handler);
  
 /**
- * fw_core_remove_address_handler - unregister an address handler
+ * fw_core_remove_address_handler() - unregister an address handler
  */
 void fw_core_remove_address_handler(struct fw_address_handler *handler)
 {
...	...	@@ -107,11 +107,11 @@
107	107	}
108	108
109	109	/**
110		- * fw_csr_string - reads a string from the configuration ROM
111		- * @directory: e.g. root directory or unit directory
112		- * @key: the key of the preceding directory entry
113		- * @buf: where to put the string
114		- * @size: size of @buf, in bytes
	110	+ * fw_csr_string() - reads a string from the configuration ROM
	111	+ * @directory: e.g. root directory or unit directory
	112	+ * @key: the key of the preceding directory entry
	113	+ * @buf: where to put the string
	114	+ * @size: size of @buf, in bytes
115	115	*
116	116	* The string is taken from a minimal ASCII text descriptor leaf after
117	117	* the immediate entry with @key. The string is zero-terminated.
...	...	@@ -272,7 +272,7 @@
272	272	}
273	273
274	274	/**
275		- * fw_iso_resource_manage - Allocate or deallocate a channel and/or bandwidth
	275	+ * fw_iso_resource_manage() - Allocate or deallocate a channel and/or bandwidth
276	276	*
277	277	* In parameters: card, generation, channels_mask, bandwidth, allocate
278	278	* Out parameters: channel, bandwidth
...	...	@@ -174,12 +174,7 @@
174	174	return list_entry(l, struct fw_node, link);
175	175	}
176	176
177		-/**
178		- * build_tree - Build the tree representation of the topology
179		- * @self_ids: array of self IDs to create the tree from
180		- * @self_id_count: the length of the self_ids array
181		- * @local_id: the node ID of the local node
182		- *
	177	+/*
183	178	* This function builds the tree representation of the topology given
184	179	* by the self IDs from the latest bus reset. During the construction
185	180	* of the tree, the function checks that the self IDs are valid and
...	...	@@ -420,11 +415,10 @@
420	415	}
421	416	}
422	417
423		-/**
424		- * update_tree - compare the old topology tree for card with the new
425		- * one specified by root. Queue the nodes and mark them as either
426		- * found, lost or updated. Update the nodes in the card topology tree
427		- * as we go.
	418	+/*
	419	+ * Compare the old topology tree for card with the new one specified by root.
	420	+ * Queue the nodes and mark them as either found, lost or updated.
	421	+ * Update the nodes in the card topology tree as we go.
428	422	*/
429	423	static void update_tree(struct fw_card card, struct fw_node root)
430	424	{
...	...	@@ -273,43 +273,49 @@
273	273	}
274	274
275	275	/**
276		- * This function provides low-level access to the IEEE1394 transaction
277		- * logic. Most C programs would use either fw_read(), fw_write() or
278		- * fw_lock() instead - those function are convenience wrappers for
279		- * this function. The fw_send_request() function is primarily
280		- * provided as a flexible, one-stop entry point for languages bindings
281		- * and protocol bindings.
	276	+ * fw_send_request() - submit a request packet for transmission
	277	+ * @card: interface to send the request at
	278	+ * @t: transaction instance to which the request belongs
	279	+ * @tcode: transaction code
	280	+ * @destination_id: destination node ID, consisting of bus_ID and phy_ID
	281	+ * @generation: bus generation in which request and response are valid
	282	+ * @speed: transmission speed
	283	+ * @offset: 48bit wide offset into destination's address space
	284	+ * @payload: data payload for the request subaction
	285	+ * @length: length of the payload, in bytes
	286	+ * @callback: function to be called when the transaction is completed
	287	+ * @callback_data: data to be passed to the transaction completion callback
282	288	*
283		- * FIXME: Document this function further, in particular the possible
284		- * values for rcode in the callback. In short, we map ACK_COMPLETE to
285		- * RCODE_COMPLETE, internal errors set errno and set rcode to
286		- * RCODE_SEND_ERROR (which is out of range for standard ieee1394
287		- * rcodes). All other rcodes are forwarded unchanged. For all
288		- * errors, payload is NULL, length is 0.
	289	+ * Submit a request packet into the asynchronous request transmission queue.
	290	+ * Can be called from atomic context. If you prefer a blocking API, use
	291	+ * fw_run_transaction() in a context that can sleep.
289	292	*
290		- * Can not expect the callback to be called before the function
291		- * returns, though this does happen in some cases (ACK_COMPLETE and
292		- * errors).
	293	+ * In case of lock requests, specify one of the firewire-core specific %TCODE_
	294	+ * constants instead of %TCODE_LOCK_REQUEST in @tcode.
293	295	*
294		- * The payload is only used for write requests and must not be freed
295		- * until the callback has been called.
	296	+ * Make sure that the value in @destination_id is not older than the one in
	297	+ * @generation. Otherwise the request is in danger to be sent to a wrong node.
296	298	*
297		- * @param card the card from which to send the request
298		- * @param tcode the tcode for this transaction. Do not use
299		- * TCODE_LOCK_REQUEST directly, instead use TCODE_LOCK_MASK_SWAP
300		- * etc. to specify tcode and ext_tcode.
301		- * @param node_id the destination node ID (bus ID and PHY ID concatenated)
302		- * @param generation the generation for which node_id is valid
303		- * @param speed the speed to use for sending the request
304		- * @param offset the 48 bit offset on the destination node
305		- * @param payload the data payload for the request subaction
306		- * @param length the length in bytes of the data to read
307		- * @param callback function to be called when the transaction is completed
308		- * @param callback_data pointer to arbitrary data, which will be
309		- * passed to the callback
310		- *
311		- * In case of asynchronous stream packets i.e. TCODE_STREAM_DATA, the caller
	299	+ * In case of asynchronous stream packets i.e. %TCODE_STREAM_DATA, the caller
312	300	* needs to synthesize @destination_id with fw_stream_packet_destination_id().
	301	+ * It will contain tag, channel, and sy data instead of a node ID then.
	302	+ *
	303	+ * The payload buffer at @data is going to be DMA-mapped except in case of
	304	+ * quadlet-sized payload or of local (loopback) requests. Hence make sure that
	305	+ * the buffer complies with the restrictions for DMA-mapped memory. The
	306	+ * @payload must not be freed before the @callback is called.
	307	+ *
	308	+ * In case of request types without payload, @data is NULL and @length is 0.
	309	+ *
	310	+ * After the transaction is completed successfully or unsuccessfully, the
	311	+ * @callback will be called. Among its parameters is the response code which
	312	+ * is either one of the rcodes per IEEE 1394 or, in case of internal errors,
	313	+ * the firewire-core specific %RCODE_SEND_ERROR.
	314	+ *
	315	+ * Note some timing corner cases: fw_send_request() may complete much earlier
	316	+ * than when the request packet actually hits the wire. On the other hand,
	317	+ * transaction completion and hence execution of @callback may happen even
	318	+ * before fw_send_request() returns.
313	319	*/
314	320	void fw_send_request(struct fw_card card, struct fw_transaction t, int tcode,
315	321	int destination_id, int generation, int speed,
316	322
...	...	@@ -375,9 +381,11 @@
375	381	}
376	382
377	383	/**
378		- * fw_run_transaction - send request and sleep until transaction is completed
	384	+ * fw_run_transaction() - send request and sleep until transaction is completed
379	385	*
380		- * Returns the RCODE.
	386	+ * Returns the RCODE. See fw_send_request() for parameter documentation.
	387	+ * Unlike fw_send_request(), @data points to the payload of the request or/and
	388	+ * to the payload of the response.
381	389	*/
382	390	int fw_run_transaction(struct fw_card *card, int tcode, int destination_id,
383	391	int generation, int speed, unsigned long long offset,
...	...	@@ -495,9 +503,9 @@
495	503	}
496	504
497	505	/**
498		- * fw_core_add_address_handler - register for incoming requests
499		- * @handler: callback
500		- * @region: region in the IEEE 1212 node space address range
	506	+ * fw_core_add_address_handler() - register for incoming requests
	507	+ * @handler: callback
	508	+ * @region: region in the IEEE 1212 node space address range
501	509	*
502	510	* region->start, ->end, and handler->length have to be quadlet-aligned.
503	511	*
...	...	@@ -552,7 +560,7 @@
552	560	EXPORT_SYMBOL(fw_core_add_address_handler);
553	561
554	562	/**
555		- * fw_core_remove_address_handler - unregister an address handler
	563	+ * fw_core_remove_address_handler() - unregister an address handler
556	564	*/
557	565	void fw_core_remove_address_handler(struct fw_address_handler *handler)
558	566	{