[coreboot] New patch to review for coreboot: 812ee4a libpayload: Document USB host controller setup functions

[Nico Huber (nico.huber@secunet.com)]

Nico Huber (nico.huber at secunet.com) just uploaded a new patch set to gerrit, which you can find at http://review.coreboot.org/1848

-gerrit

commit 812ee4ad95b840173e3cacb2d482b0fea44295d7
Author: Nico Huber <nico.huber at secunet.com>
Date:   Mon Nov 12 15:12:35 2012 +0100

    libpayload: Document USB host controller setup functions
    
    The semantics of the controller functions, start(), stop(), reset() and
    shutdown(), are not self-explanatory which let to some confusion. At
    least the reset() functions of the different host controller drivers
    were implemented following different interpretations. Let's make the
    intended behaviour of these functions clear.
    
    The stated inconsistencies will be addressed in following commits.
    
    Change-Id: Id2e300f65c21039218b6ba3f87c0fcd4f0dda0a8
    Signed-off-by: Nico Huber <nico.huber at secunet.com>
---
 payloads/libpayload/include/usb/usb.h | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/payloads/libpayload/include/usb/usb.h b/payloads/libpayload/include/usb/usb.h
index 17eca01..8dd2304 100644
--- a/payloads/libpayload/include/usb/usb.h
+++ b/payloads/libpayload/include/usb/usb.h
@@ -119,10 +119,19 @@ struct usbdev_hc {
 	u32 reg_base;
 	hc_type type;
 	usbdev_t *devices[128];	// dev 0 is root hub, 127 is last addressable
+
+	/* start():     Resume operation. */
 	void (*start) (hci_t *controller);
+	/* stop():      Stop operation but keep controller initialized. */
 	void (*stop) (hci_t *controller);
+	/* reset():     Perform a controller reset. The controller needs to
+	                be (re)initialized afterwards to work (again). */
 	void (*reset) (hci_t *controller);
+	/* shutdown():  Stop operation, detach host controller and shutdown
+	                this driver instance. After calling shutdown() any
+			other usage of this hci_t* is invalid. */
 	void (*shutdown) (hci_t *controller);
+
 	int (*bulk) (endpoint_t *ep, int size, u8 *data, int finalize);
 	int (*control) (usbdev_t *dev, direction_t pid, int dr_length,
 			void *devreq, int data_length, u8 *data);