/*
* Copyright (c) 2018 Ondrej Hlavaty, Petr Manek
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* - The name of the author may not be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/** @addtogroup libusbhost
* @{
*/
/** @file
* Virtual base for usb bus implementations.
*
* The purpose of this structure is to keep information about connected devices
* and endpoints, manage available bandwidth and the toggle bit flipping.
*
* The generic implementation is provided for USB 1 and 2 in usb2_bus.c. Some
* details in [OUE]HCI are solved through overriding some functions. XHCI does
* not need the bookkeeping functionality, because addresses are managed by HC
* itself.
*/
#ifndef LIBUSBHOST_HOST_BUS_H
#define LIBUSBHOST_HOST_BUS_H
#include <assert.h>
#include <fibril_synch.h>
#include <stdbool.h>
#include <usb/host/hcd.h>
#include <usb/request.h>
#include <usb/usb.h>
#include <usbhc_iface.h>
typedef struct hcd hcd_t;
typedef struct endpoint endpoint_t;
typedef struct bus bus_t;
typedef struct ddf_fun ddf_fun_t;
typedef struct usb_transfer_batch usb_transfer_batch_t;
typedef struct device {
/* Device tree keeping */
link_t link;
list_t devices;
fibril_mutex_t guard;
/* Associated DDF function, if any */
ddf_fun_t *fun;
/* Invalid for the roothub device */
unsigned port;
/** Hub under which this device is connected */
struct device *hub;
/** USB Tier of the device */
uint8_t tier;
/* Transaction translator */
struct {
device_t *dev;
unsigned port;
} tt;
/* The following are not set by the library */
usb_speed_t speed;
usb_address_t address;
endpoint_t *endpoints [USB_ENDPOINT_COUNT];
/* Managing bus */
bus_t *bus;
/** True if the device can add new endpoints and schedule transfers. */
volatile bool online;
/* This structure is meant to be extended by overriding. */
} device_t;
typedef struct bus_ops bus_ops_t;
/**
* Operations structure serving as an interface of hc driver for the library
* (and the rest of the system).
*/
struct bus_ops {
/* Global operations on the bus */
void (*interrupt)(bus_t *, uint32_t);
int (*status)(bus_t *, uint32_t *);
/* Operations on device */
int (*device_enumerate)(device_t *);
void (*device_gone)(device_t *);
int (*device_online)(device_t *); /**< Optional */
void (*device_offline)(device_t *); /**< Optional */
endpoint_t *(*endpoint_create)(device_t *,
const usb_endpoint_descriptors_t *);
/* Operations on endpoint */
int (*endpoint_register)(endpoint_t *);
void (*endpoint_unregister)(endpoint_t *);
void (*endpoint_destroy)(endpoint_t *); /**< Optional */
usb_transfer_batch_t *(*batch_create)(endpoint_t *); /**< Optional */
/* Operations on batch */
int (*batch_schedule)(usb_transfer_batch_t *);
void (*batch_destroy)(usb_transfer_batch_t *); /**< Optional */
};
/** Endpoint management structure */
typedef struct bus {
/* Synchronization of ops */
fibril_mutex_t guard;
/* Size of the device_t extended structure */
size_t device_size;
/* Do not call directly, ops are synchronized. */
const bus_ops_t *ops;
/* Reserving default address */
device_t *default_address_owner;
fibril_condvar_t default_address_cv;
/* This structure is meant to be extended by overriding. */
} bus_t;
void bus_init(bus_t *, size_t);
int bus_device_init(device_t *, bus_t *);
int bus_device_set_default_name(device_t *);
int bus_device_enumerate(device_t *);
void bus_device_gone(device_t *);
int bus_device_online(device_t *);
int bus_device_offline(device_t *);
/**
* A proforma to USB transfer batch. As opposed to transfer batch, which is
* supposed to be a dynamic structrure, this one is static and descriptive only.
* Its fields are copied to the final batch.
*/
typedef struct transfer_request {
usb_target_t target;
usb_direction_t dir;
dma_buffer_t buffer;
size_t offset, size;
uint64_t setup;
usbhc_iface_transfer_callback_t on_complete;
void *arg;
const char *name;
} transfer_request_t;
int bus_issue_transfer(device_t *, const transfer_request_t *);
errno_t bus_device_send_batch_sync(device_t *, usb_target_t,
usb_direction_t direction, char *, size_t, uint64_t,
const char *, size_t *);
int bus_endpoint_add(device_t *, const usb_endpoint_descriptors_t *, endpoint_t **);
endpoint_t *bus_find_endpoint(device_t *, usb_endpoint_t, usb_direction_t);
int bus_endpoint_remove(endpoint_t *);
int bus_reserve_default_address(bus_t *, device_t *);
void bus_release_default_address(bus_t *, device_t *);
#endif
/**
* @}
*/