source: mainline/uspace/lib/usbhost/include/usb/host/bus.h

/*
 * 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
/**
 * @}
 */