uspace/lib/usb/include/usb/port.h

   1 /*
   2  * Copyright (c) 2018 Ondrej Hlavaty
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * - Redistributions of source code must retain the above copyright
  10  *   notice, this list of conditions and the following disclaimer.
  11  * - Redistributions in binary form must reproduce the above copyright
  12  *   notice, this list of conditions and the following disclaimer in the
  13  *   documentation and/or other materials provided with the distribution.
  14  * - The name of the author may not be used to endorse or promote products
  15  *   derived from this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /** @addtogroup libusb
  30  * @{
  31  */
  32 /** @file
  33  * An USB hub port state machine.
  34  *
  35  * This helper structure solves a repeated problem in USB world: management of
  36  * USB ports. A port is an object which receives events (connect, disconnect,
  37  * reset) which are to be handled in an asynchronous way. The tricky part is
  38  * that response to events has to wait for different events - the most notable
  39  * being USB 2 port requiring port reset to be enabled. This problem is solved
  40  * by launching separate fibril for taking the port up.
  41  *
  42  * This subsystem abstracts the rather complicated state machine, and offers
  43  * a simple interface to announce events and leave the fibril management on the
  44  * library.
  45  */
  46
  47 #ifndef LIB_USB_PORT_H
  48 #define LIB_USB_PORT_H
  49
  50 #include <fibril_synch.h>
  51 #include <usb/usb.h>
  52 #include <errno.h>
  53
  54 typedef enum {
  55         PORT_DISABLED,  /* No device connected. Fibril not running. */
  56         PORT_ENUMERATED,/* Device enumerated. Fibril finished succesfully. */
  57         PORT_CONNECTING,/* A connected event received, fibril running. */
  58         PORT_DISCONNECTING,/* A disconnected event received, fibril running. */
  59         PORT_ERROR,     /* An error "in-progress". Fibril still running. */
  60 } usb_port_state_t;
  61
  62 typedef struct usb_port {
  63         /** Guarding all fields. Is locked in the connected op. */
  64         fibril_mutex_t guard;
  65         /** Current state of the port */
  66         usb_port_state_t state;
  67         /** CV signalled on fibril exit. */
  68         fibril_condvar_t finished_cv;
  69         /** CV signalled on enabled event. */
  70         fibril_condvar_t enabled_cv;
  71 } usb_port_t;
  72
  73 /**
  74  * Callback to run the enumeration routine.
  75  * Called in separate fibril with guard locked.
  76  */
  77 typedef int (*usb_port_enumerate_t)(usb_port_t *);
  78
  79 /**
  80  * Callback to run the enumeration routine. Called in the caller fibril,
  81  */
  82 typedef void (*usb_port_remove_t)(usb_port_t *);
  83
  84 /* Following methods are intended to be called "from outside". */
  85 void usb_port_init(usb_port_t *);
  86 int usb_port_connected(usb_port_t *, usb_port_enumerate_t);
  87 void usb_port_enabled(usb_port_t *);
  88 void usb_port_disabled(usb_port_t *, usb_port_remove_t);
  89 void usb_port_fini(usb_port_t *);
  90
  91 /* And these are to be called from the connected handler. */
  92 int usb_port_condvar_wait_timeout(usb_port_t *port, fibril_condvar_t *, usec_t);
  93
  94 /**
  95  * Wait for the enabled event to come.
  96  *
  97  * @return Error code:
  98  *      EINTR if the device was disconnected in the meantime.
  99  *      ETIMEOUT if the enabled event didn't come in 2 seconds
 100  */
 101 static inline int usb_port_wait_for_enabled(usb_port_t *port)
 102 {
 103         return usb_port_condvar_wait_timeout(port, &port->enabled_cv, 2000000);
 104 }
 105
 106 #endif
 107
 108 /**
 109  * @}
 110  */