@@ -119,11 +119,13 @@ EXPORT_SYMBOL_GPL(xenbus_strstate);
119119 * @callback: callback to register
120120 *
121121 * Register a @watch on the given path, using the given xenbus_watch structure
122- * for storage, and the given @callback function as the callback. Return 0 on
123- * success, or -errno on error. On success, the given @path will be saved as
124- * @watch->node, and remains the caller's to free. On error, @watch->node will
122+ * for storage, and the given @callback function as the callback. On success,
123+ * the given @path will be saved as @watch->node, and remains the
124+ * caller's to free. On error, @watch->node will
125125 * be NULL, the device will switch to %XenbusStateClosing, and the error will
126126 * be saved in the store.
127+ *
128+ * Returns: %0 on success or -errno on error
127129 */
128130int xenbus_watch_path (struct xenbus_device * dev , const char * path ,
129131 struct xenbus_watch * watch ,
@@ -160,12 +162,14 @@ EXPORT_SYMBOL_GPL(xenbus_watch_path);
160162 * @pathfmt: format of path to watch
161163 *
162164 * Register a watch on the given @path, using the given xenbus_watch
163- * structure for storage, and the given @callback function as the callback.
164- * Return 0 on success, or -errno on error . On success, the watched path
165- * (@path/@path2) will be saved as @watch->node, and becomes the caller's to
166- * kfree(). On error, watch->node will be NULL, so the caller has nothing to
165+ * structure for storage, and the given @callback function as the
166+ * callback . On success, the watched path (@path/@path2) will be saved
167+ * as @watch->node, and becomes the caller's to kfree().
168+ * On error, watch->node will be NULL, so the caller has nothing to
167169 * free, the device will switch to %XenbusStateClosing, and the error will be
168170 * saved in the store.
171+ *
172+ * Returns: %0 on success or -errno on error
169173 */
170174int xenbus_watch_pathfmt (struct xenbus_device * dev ,
171175 struct xenbus_watch * watch ,
@@ -255,13 +259,15 @@ __xenbus_switch_state(struct xenbus_device *dev,
255259}
256260
257261/**
258- * xenbus_switch_state
262+ * xenbus_switch_state - save the new state of a driver
259263 * @dev: xenbus device
260264 * @state: new state
261265 *
262266 * Advertise in the store a change of the given driver to the given new_state.
263- * Return 0 on success, or -errno on error. On error, the device will switch
264- * to XenbusStateClosing, and the error will be saved in the store.
267+ * On error, the device will switch to XenbusStateClosing, and the error
268+ * will be saved in the store.
269+ *
270+ * Returns: %0 on success or -errno on error
265271 */
266272int xenbus_switch_state (struct xenbus_device * dev , enum xenbus_state state )
267273{
@@ -305,7 +311,7 @@ static void xenbus_va_dev_error(struct xenbus_device *dev, int err,
305311}
306312
307313/**
308- * xenbus_dev_error
314+ * xenbus_dev_error - place an error message into the store
309315 * @dev: xenbus device
310316 * @err: error to report
311317 * @fmt: error message format
@@ -324,7 +330,7 @@ void xenbus_dev_error(struct xenbus_device *dev, int err, const char *fmt, ...)
324330EXPORT_SYMBOL_GPL (xenbus_dev_error );
325331
326332/**
327- * xenbus_dev_fatal
333+ * xenbus_dev_fatal - put an error messages into the store and then shutdown
328334 * @dev: xenbus device
329335 * @err: error to report
330336 * @fmt: error message format
@@ -346,7 +352,7 @@ void xenbus_dev_fatal(struct xenbus_device *dev, int err, const char *fmt, ...)
346352}
347353EXPORT_SYMBOL_GPL (xenbus_dev_fatal );
348354
349- /**
355+ /*
350356 * Equivalent to xenbus_dev_fatal(dev, err, fmt, args), but helps
351357 * avoiding recursion within xenbus_switch_state.
352358 */
@@ -453,7 +459,7 @@ void xenbus_teardown_ring(void **vaddr, unsigned int nr_pages,
453459}
454460EXPORT_SYMBOL_GPL (xenbus_teardown_ring );
455461
456- /**
462+ /*
457463 * Allocate an event channel for the given xenbus_device, assigning the newly
458464 * created local port to *port. Return 0 on success, or -errno on error. On
459465 * error, the device will switch to XenbusStateClosing, and the error will be
@@ -479,7 +485,7 @@ int xenbus_alloc_evtchn(struct xenbus_device *dev, evtchn_port_t *port)
479485EXPORT_SYMBOL_GPL (xenbus_alloc_evtchn );
480486
481487
482- /**
488+ /*
483489 * Free an existing event channel. Returns 0 on success or -errno on error.
484490 */
485491int xenbus_free_evtchn (struct xenbus_device * dev , evtchn_port_t port )
@@ -499,18 +505,19 @@ EXPORT_SYMBOL_GPL(xenbus_free_evtchn);
499505
500506
501507/**
502- * xenbus_map_ring_valloc
508+ * xenbus_map_ring_valloc - allocate & map pages of VA space
503509 * @dev: xenbus device
504510 * @gnt_refs: grant reference array
505511 * @nr_grefs: number of grant references
506512 * @vaddr: pointer to address to be filled out by mapping
507513 *
508514 * Map @nr_grefs pages of memory into this domain from another
509515 * domain's grant table. xenbus_map_ring_valloc allocates @nr_grefs
510- * pages of virtual address space, maps the pages to that address, and
511- * sets *vaddr to that address. Returns 0 on success, and -errno on
512- * error. If an error is returned, device will switch to
516+ * pages of virtual address space, maps the pages to that address, and sets
517+ * *vaddr to that address. If an error is returned, device will switch to
513518 * XenbusStateClosing and the error message will be saved in XenStore.
519+ *
520+ * Returns: %0 on success or -errno on error
514521 */
515522int xenbus_map_ring_valloc (struct xenbus_device * dev , grant_ref_t * gnt_refs ,
516523 unsigned int nr_grefs , void * * vaddr )
@@ -599,14 +606,15 @@ static int __xenbus_map_ring(struct xenbus_device *dev,
599606}
600607
601608/**
602- * xenbus_unmap_ring
609+ * xenbus_unmap_ring - unmap memory from another domain
603610 * @dev: xenbus device
604611 * @handles: grant handle array
605612 * @nr_handles: number of handles in the array
606613 * @vaddrs: addresses to unmap
607614 *
608615 * Unmap memory in this domain that was imported from another domain.
609- * Returns 0 on success and returns GNTST_* on error
616+ *
617+ * Returns: %0 on success or GNTST_* on error
610618 * (see xen/include/interface/grant_table.h).
611619 */
612620static int xenbus_unmap_ring (struct xenbus_device * dev , grant_handle_t * handles ,
@@ -712,15 +720,16 @@ static int xenbus_map_ring_hvm(struct xenbus_device *dev,
712720}
713721
714722/**
715- * xenbus_unmap_ring_vfree
723+ * xenbus_unmap_ring_vfree - unmap a page of memory from another domain
716724 * @dev: xenbus device
717725 * @vaddr: addr to unmap
718726 *
719727 * Based on Rusty Russell's skeleton driver's unmap_page.
720728 * Unmap a page of memory in this domain that was imported from another domain.
721729 * Use xenbus_unmap_ring_vfree if you mapped in your memory with
722730 * xenbus_map_ring_valloc (it will free the virtual address space).
723- * Returns 0 on success and returns GNTST_* on error
731+ *
732+ * Returns: %0 on success or GNTST_* on error
724733 * (see xen/include/interface/grant_table.h).
725734 */
726735int xenbus_unmap_ring_vfree (struct xenbus_device * dev , void * vaddr )
@@ -916,10 +925,10 @@ static int xenbus_unmap_ring_hvm(struct xenbus_device *dev, void *vaddr)
916925}
917926
918927/**
919- * xenbus_read_driver_state
928+ * xenbus_read_driver_state - read state from a store path
920929 * @path: path for driver
921930 *
922- * Return the state of the driver rooted at the given store path, or
931+ * Returns: the state of the driver rooted at the given store path, or
923932 * XenbusStateUnknown if no state can be read.
924933 */
925934enum xenbus_state xenbus_read_driver_state (const char * path )
0 commit comments