uspace/lib/usbhost/include/usb/host/endpoint.h

   1 /*
   2  * Copyright (c) 2011 Jan Vesely
   3  * Copyright (c) 2018 Ondrej Hlavaty
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * - Redistributions of source code must retain the above copyright
  11  *   notice, this list of conditions and the following disclaimer.
  12  * - Redistributions in binary form must reproduce the above copyright
  13  *   notice, this list of conditions and the following disclaimer in the
  14  *   documentation and/or other materials provided with the distribution.
  15  * - The name of the author may not be used to endorse or promote products
  16  *   derived from this software without specific prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  19  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  20  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  21  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  23  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  27  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28  */
  29
  30 /** @addtogroup libusbhost
  31  * @{
  32  */
  33 /** @file
  34  *
  35  * Endpoint structure is tightly coupled to the bus. The bus controls the
  36  * life-cycle of endpoint. In order to keep endpoints lightweight, operations
  37  * on endpoints are part of the bus structure.
  38  *
  39  */
  40 #ifndef LIBUSBHOST_HOST_ENDPOINT_H
  41 #define LIBUSBHOST_HOST_ENDPOINT_H
  42
  43 #include <adt/list.h>
  44 #include <fibril_synch.h>
  45 #include <refcount.h>
  46 #include <stdbool.h>
  47 #include <time.h>
  48 #include <usb/usb.h>
  49 #include <usb/host/bus.h>
  50 #include <usbhc_iface.h>
  51
  52 typedef struct bus bus_t;
  53 typedef struct device device_t;
  54 typedef struct transfer_request transfer_request_t;
  55 typedef struct usb_transfer_batch usb_transfer_batch_t;
  56
  57 /**
  58  * Host controller side endpoint structure.
  59  *
  60  * This structure, though reference-counted, is very fragile. It is responsible
  61  * for synchronizing transfer batch scheduling and completion.
  62  *
  63  * To avoid situations, in which two locks must be obtained to schedule/finish
  64  * a transfer, the endpoint inherits a lock from the outside. Because the
  65  * concrete instance of mutex can be unknown at the time of initialization,
  66  * the HC shall pass the right lock at the time of onlining the endpoint.
  67  *
  68  * The fields used for scheduling (online, active_batch) are to be used only
  69  * under that guard and by functions designed for this purpose. The driver can
  70  * also completely avoid using this mechanism, in which case it is on its own in
  71  * question of transfer aborting.
  72  *
  73  * Relevant information can be found in the documentation of HelenOS xHCI
  74  * project.
  75  */
  76 typedef struct endpoint {
  77         /** USB device */
  78         device_t *device;
  79         /** Reference count. */
  80         atomic_refcount_t refcnt;
  81
  82         /** An inherited guard */
  83         fibril_mutex_t *guard;
  84         /** Whether it's allowed to schedule on this endpoint */
  85         bool online;
  86         /** The currently active transfer batch. */
  87         usb_transfer_batch_t *active_batch;
  88         /** Signals change of active status. */
  89         fibril_condvar_t avail;
  90
  91         /** Endpoint number */
  92         usb_endpoint_t endpoint;
  93         /** Communication direction. */
  94         usb_direction_t direction;
  95         /** USB transfer type. */
  96         usb_transfer_type_t transfer_type;
  97         /** Maximum size of one packet */
  98         size_t max_packet_size;
  99
 100         /** Maximum size of one transfer */
 101         size_t max_transfer_size;
 102
 103         /* Policies for transfer buffers */
 104         /** A hint for optimal performance. */
 105         dma_policy_t transfer_buffer_policy;
 106         /** Enforced by the library. */
 107         dma_policy_t required_transfer_buffer_policy;
 108
 109         /**
 110          * Number of packets that can be sent in one service interval
 111          * (not necessarily uframe, despite its name)
 112          */
 113         unsigned packets_per_uframe;
 114
 115         /* This structure is meant to be extended by overriding. */
 116 } endpoint_t;
 117
 118 extern void endpoint_init(endpoint_t *, device_t *,
 119     const usb_endpoint_descriptors_t *);
 120
 121 extern void endpoint_add_ref(endpoint_t *);
 122 extern void endpoint_del_ref(endpoint_t *);
 123
 124 extern void endpoint_set_online(endpoint_t *, fibril_mutex_t *);
 125 extern void endpoint_set_offline_locked(endpoint_t *);
 126
 127 extern void endpoint_wait_timeout_locked(endpoint_t *ep, usec_t);
 128 extern int endpoint_activate_locked(endpoint_t *, usb_transfer_batch_t *);
 129 extern void endpoint_deactivate_locked(endpoint_t *);
 130
 131 int endpoint_send_batch(endpoint_t *, const transfer_request_t *);
 132
 133 static inline bus_t *endpoint_get_bus(endpoint_t *ep)
 134 {
 135         device_t *const device = ep->device;
 136         return device ? device->bus : NULL;
 137 }
 138
 139 #endif
 140
 141 /**
 142  * @}
 143  */