Ignore:
Timestamp:
2018-01-14T21:16:03Z (6 years ago)
Author:
Petr Manek <petr.manek@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
17c1d9db
Parents:
edc51615
git-author:
Petr Manek <petr.manek@…> (2018-01-14 21:16:00)
git-committer:
Petr Manek <petr.manek@…> (2018-01-14 21:16:03)
Message:

usbdev: refactor polling more

For clarity, the opaque usb_device_polling_t and its complementary
configuration data structure usb_device_polling_config_t have been
merged into usb_polling_t. All related methods have dropped the
"device" from their prefix as well.

The usage semantics have transitioned to malloc-free model, where the
user is entirely responsible for (de)allocation of the polling structure
and its data buffer, and (de)initialization happens in designated
functions during its lifetime in the system.

In addition, the distinction between mandatory / optional / internal
parameters has been documented. Optional parameters now have default
values, which are set to sensible constants in order to allow dropping
some lines in USB driver implementations.

The drivers usbhid and usbhub were refactored to match the API
changes.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/usbdev/include/usb/dev/poll.h

    redc51615 r8b71f3e  
    4343#include <stddef.h>
    4444#include <stdint.h>
     45#include <fibril_synch.h>
    4546
    46 /** Automated polling instance. */
    47 typedef struct usb_device_polling usb_device_polling_t;
    4847
    49 /** Parameters and callbacks for automated polling. */
    50 typedef struct usb_device_polling_config {
    51         /** Level of debugging messages from auto polling.
    52          * 0 - nothing
    53          * 1 - inform about errors and polling start/end
    54          * 2 - also dump every retrieved buffer
    55          */
    56         int debug;
     48/** USB automated polling. */
     49typedef struct usb_polling {
     50        /** Mandatory parameters - user is expected to configure these. */
    5751
    58         /** Maximum number of consecutive errors before polling termination. */
    59         size_t max_failures;
     52        /** USB device to poll. */
     53        usb_device_t *device;
    6054
    61         /** Delay between poll requests in milliseconds.
    62          * Set to negative value to use value from endpoint descriptor.
    63          */
    64         int delay;
     55        /** Device enpoint mapping to use for polling. */
     56        usb_endpoint_mapping_t *ep_mapping;
    6557
    66         /** Whether to automatically try to clear the HALT feature after
    67          * the endpoint stalls.
    68          */
    69         bool auto_clear_halt;
     58        /** Size of the recieved data. */
     59        size_t request_size;
     60
     61        /** Data buffer of at least `request_size`. User is responsible for its allocation. */
     62        uint8_t *buffer;
    7063
    7164        /** Callback when data arrives.
    … …  
    7972        bool (*on_data)(usb_device_t *dev, uint8_t *data, size_t data_size,
    8073            void *arg);
     74
     75
     76        /** Optional parameters - user can customize them, but they are defaulted to
     77         *  some reasonable values.
     78         */
     79
     80        /** Level of debugging messages from auto polling.
     81         * 0 - nothing (default)
     82         * 1 - inform about errors and polling start/end
     83         * 2 - also dump every retrieved buffer
     84         */
     85        int debug;
     86
     87        /** Maximum number of consecutive errors before polling termination (default 3). */
     88        size_t max_failures;
     89
     90        /** Delay between poll requests in milliseconds.
     91         * By default, value from endpoint descriptor used.
     92         */
     93        int delay;
     94
     95        /** Whether to automatically try to clear the HALT feature after
     96         * the endpoint stalls (true by default).
     97         */
     98        bool auto_clear_halt;
     99
     100        /** Argument to pass to callbacks (default NULL). */
     101        void *arg;
    81102
    82103        /** Callback when polling is terminated.
    … …  
    98119        bool (*on_error)(usb_device_t *dev, int err_code, void *arg);
    99120
    100         /** Argument to pass to callbacks. */
    101         void *arg;
    102 } usb_device_polling_config_t;
    103121
    104 int usb_device_poll(usb_device_t *, usb_endpoint_mapping_t *,
    105     const usb_device_polling_config_t *, size_t, usb_device_polling_t **);
     122        /** Internal parameters - user is not expected to set them. Messing with them
     123         *  can result in unexpected behavior if you do not know what you are doing.
     124         */
    106125
    107 int usb_device_poll_join(usb_device_polling_t *);
     126        /** Fibril used for polling. */
     127        fid_t fibril;
     128
     129        /** True if polling is currently in operation. */
     130        volatile bool running;
     131
     132        /** True if polling should terminate as soon as possible. */
     133        volatile bool joining;
     134
     135        /** Synchronization primitives for joining polling end. */
     136        fibril_mutex_t guard;
     137        fibril_condvar_t cv;
     138} usb_polling_t;
     139
     140int usb_polling_init(usb_polling_t *);
     141void usb_polling_fini(usb_polling_t *);
     142
     143int usb_polling_start(usb_polling_t *);
     144int usb_polling_join(usb_polling_t *);
    108145
    109146#endif
Note: See TracChangeset for help on using the changeset viewer.