source: mainline/uspace/lib/usbdev/src/devpoll.c@ c24b0dcb

/*
 * Copyright (c) 2011 Vojtech Horky
 * Copyright (c) 2017 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 libusbdev
 * @{
 */
/** @file
 * USB device driver framework - automatic interrupt polling.
 */

#include <usb/dev/device.h>
#include <usb/dev/pipes.h>
#include <usb/dev/poll.h>
#include <usb/dev/request.h>
#include <usb/classes/classes.h>
#include <usb/debug.h>
#include <usb/descriptor.h>
#include <usb/usb.h>

#include <assert.h>
#include <async.h>
#include <errno.h>
#include <fibril.h>
#include <fibril_synch.h>
#include <stdbool.h>
#include <stdlib.h>
#include <str_error.h>
#include <stddef.h>
#include <stdint.h>

/** Initialize the polling data structure, its internals and configuration
 *  with default values.
 *
 * @param polling Valid polling data structure.
 * @return Error code.
 * @retval EOK Polling data structure is ready to be used.
 */
int usb_polling_init(usb_polling_t *polling)
{
        if (!polling)
                return EBADMEM;

        /* Zero out everything */
        memset(polling, 0, sizeof(usb_polling_t));

        /* Internal initializers. */
        fibril_mutex_initialize(&polling->guard);
        fibril_condvar_initialize(&polling->cv);

        /* Default configuration. */
        polling->auto_clear_halt = true;
        polling->delay = -1;
        polling->max_failures = 3;

        return EOK;
}

/** Destroy the polling data structure.
 *  This function does nothing but a safety check whether the polling
 *  was joined successfully.
 *
 * @param polling Polling data structure.
 */
void usb_polling_fini(usb_polling_t *polling)
{
        /* Nothing done at the moment. */
        assert(polling);
        assert(!polling->running);
}

/** Polling fibril.
 *
 * @param arg Pointer to usb_polling_t.
 * @return Always EOK.
 */
static errno_t polling_fibril(void *arg)
{
        assert(arg);
        usb_polling_t *polling = arg;

        fibril_mutex_lock(&polling->guard);
        polling->running = true;
        fibril_mutex_unlock(&polling->guard);

        usb_pipe_t *pipe = &polling->ep_mapping->pipe;

        if (polling->debug > 0) {
                const usb_endpoint_mapping_t *mapping =
                    polling->ep_mapping;
                usb_log_debug("Poll (%p): started polling of `%s' - "
                    "interface %d (%s,%d,%d), %zuB/%zu.\n",
                    polling, usb_device_get_name(polling->device),
                    (int) mapping->interface->interface_number,
                    usb_str_class(mapping->interface->interface_class),
                    (int) mapping->interface->interface_subclass,
                    (int) mapping->interface->interface_protocol,
                    polling->request_size, pipe->desc.max_transfer_size);
        }

        size_t failed_attempts = 0;
        while (failed_attempts <= polling->max_failures) {
                size_t actual_size;
                const errno_t rc = usb_pipe_read(pipe, polling->buffer,
                    polling->request_size, &actual_size);

                if (rc == EOK) {
                        if (polling->debug > 1) {
                                usb_log_debug(
                                    "Poll%p: received: '%s' (%zuB).\n",
                                    polling,
                                    usb_debug_str_buffer(polling->buffer,
                                    actual_size, 16),
                                    actual_size);
                        }
                } else {
                        usb_log_debug(
                            "Poll%p: polling failed: %s.\n",
                            polling, str_error(rc));
                }

                /* If the pipe stalled, we can try to reset the stall. */
                if (rc == ESTALL && polling->auto_clear_halt) {
                        /*
                         * We ignore error here as this is usually a futile
                         * attempt anyway.
                         */
                        usb_pipe_clear_halt(
                            usb_device_get_default_pipe(polling->device), pipe);
                }

                if (rc != EOK) {
                        ++failed_attempts;
                        const bool carry_on = !polling->on_error ? true :
                            polling->on_error(polling->device, rc, polling->arg);

                        if (!carry_on || polling->joining) {
                                /* This is user requested abort, erases failures. */
                                failed_attempts = 0;
                                break;
                        }
                        continue;
                }

                /* We have the data, execute the callback now. */
                assert(polling->on_data);
                const bool carry_on = polling->on_data(polling->device,
                    polling->buffer, actual_size, polling->arg);

                if (!carry_on) {
                        /* This is user requested abort, erases failures. */
                        failed_attempts = 0;
                        break;
                }

                /* Reset as something might be only a temporary problem. */
                failed_attempts = 0;

                /* Take a rest before next request. */

                // FIXME TODO: This is broken, the time is in ms not us.
                // but first we need to fix drivers to actually stop using this,
                // since polling delay should be implemented in HC schedule
                fibril_usleep(polling->delay);
        }

        const bool failed = failed_attempts > 0;

        if (polling->on_polling_end)
                polling->on_polling_end(polling->device, failed, polling->arg);

        if (polling->debug > 0) {
                if (failed) {
                        usb_log_error("Polling of device `%s' terminated: "
                            "recurring failures.\n",
                            usb_device_get_name(polling->device));
                } else {
                        usb_log_debug("Polling of device `%s' terminated: "
                            "driver request.\n",
                            usb_device_get_name(polling->device));
                }
        }

        fibril_mutex_lock(&polling->guard);
        polling->running = false;
        fibril_mutex_unlock(&polling->guard);

        /* Notify joiners, if any. */
        fibril_condvar_broadcast(&polling->cv);
        return EOK;
}

/** Start automatic device polling over interrupt in pipe.
 *
 * The polling settings is copied thus it is okay to destroy the structure
 * after this function returns.
 *
 * @warning There is no guarantee when the request to the device
 * will be sent for the first time (it is possible that this
 * first request would be executed prior to return from this function).
 *
 * @param polling Polling data structure.
 * @return Error code.
 * @retval EOK New fibril polling the device was already started.
 */
errno_t usb_polling_start(usb_polling_t *polling)
{
        if (!polling || !polling->device || !polling->ep_mapping || !polling->on_data)
                return EBADMEM;

        if (!polling->request_size)
                return EINVAL;

        if (!polling->ep_mapping || (polling->ep_mapping->pipe.desc.transfer_type != USB_TRANSFER_INTERRUPT) ||
            (polling->ep_mapping->pipe.desc.direction != USB_DIRECTION_IN))
                return EINVAL;

        /* Negative value means use descriptor provided value. */
        if (polling->delay < 0)
                polling->delay = polling->ep_mapping->descriptor->poll_interval;

        polling->fibril = fibril_create(polling_fibril, polling);
        if (!polling->fibril)
                return ENOMEM;

        fibril_add_ready(polling->fibril);

        /* Fibril launched. That fibril will free the allocated data. */
        return EOK;
}

/** Close the polling pipe permanently and synchronously wait
 *  until the automatic polling fibril terminates.
 *
 *  It is safe to deallocate the polling data structure (and its
 *  data buffer) only after a successful call to this function.
 *
 *  @warning Call to this function will trigger execution of the
 *  on_error() callback with EINTR error code.
 *
 *  @parram polling Polling data structure.
 *  @return Error code.
 *  @retval EOK Polling fibril has been successfully terminated.
 */
errno_t usb_polling_join(usb_polling_t *polling)
{
        errno_t rc;
        if (!polling)
                return EBADMEM;

        /* Check if the fibril already terminated. */
        if (!polling->running)
                return EOK;

        /* Set the flag */
        polling->joining = true;

        /* Unregister the pipe. */
        rc = usb_device_unmap_ep(polling->ep_mapping);
        if (rc != EOK && rc != ENOENT && rc != EHANGUP)
                return rc;

        /* Wait for the fibril to terminate. */
        fibril_mutex_lock(&polling->guard);
        while (polling->running)
                fibril_condvar_wait(&polling->cv, &polling->guard);
        fibril_mutex_unlock(&polling->guard);

        return EOK;
}

/**
 * @}
 */