[cdi-devel] [PATCH v2 6/9] cdi/usb: Add headers

Max Reitz ·

On 18.04.2015 00:35, Kevin Wolf wrote:
> On Thu, Apr 16, 2015 at 12:13:55AM +0200, Max Reitz wrote:
>> + Add headers to be used by USB host controller drivers, the USB bus
>>    driver, and USB device drivers.
>>    These headers are still lacking functions for periodic transactions
>>    (interrupt/isochronous), hotplugging, suspend/resume, etc. pp..
>>
>> Signed-off-by: Max Reitz <max at tyndur.org>
> Lots of documentation texts here. FWIW, I'm okay with leaving the
> USB-specific headers in English only. It just felt out of place in the
> existing bilingual (or even German-only) headers.
>
>> +/**
>> + * This function is provided by the reference USB bus driver, it must only be
>> + * called by the CDI library.
>> + *
>> + * It is called once a host controller driver provides a host controller device
>> + * (returned by its init_device() function) which is passed to this function.
>> + */
>> +void cdi_usb_provide_hc(struct cdi_device* dev);
> Hm, I'm afraid I don't fully understand this function yet.
>
> If this is part of the USB bus driver, why isn't it in struct
> cdi_usb_driver?
>
> Okay, I looked in the tyndur patches, and it seems this is actually
> _not_ provided by the USB bus driver, but part of the CDI USB library
> (and used in the HCD driver process, not the USB one).

Oops, right. The comment is still from when I intended to make the bus 
driver part of the CDI library.

> In other words, since you also say it must only be called by the
> library, isn't this a purely internal implementation detail that isn't
> necessary in the public header files?

Yes, it should be removed from the public interface. It appears to be 
just left over in this header; in the implementation, it's actually 
called cdi_osdep_provide_hc() already.

>> +/**
>> + * Contains information about a communication pipe to a USB device endpoint used
>> + * for USB transactions.
>> + */
>> +struct cdi_usb_hc_ep_info {
>> +    /// Device ID
>> +    int dev;
>> +
>> +    /// Endpoint ID
>> +    int ep;
>> +
>> +    /// Endpoint type
>> +    cdi_usb_endpoint_type_t ep_type;
>> +
>> +    /// Transfer speed
>> +    cdi_usb_speed_t speed;
>> +
>> +    /// Maximum packet size for this endpoint
>> +    int mps;
>> +
>> +    /**
>> +     * For low and full speed devices operated behind a high speed hub: @tt_addr
>> +     * is the USB device address of the translating USB hub (the last high speed
>> +     * hub), @tt_port is the port (0-based index) of that hub where the first
>> +     * non-high-speed device of this device's tree is plugged into.
>> +     */
>> +    int tt_addr, tt_port;
>> +};
> I wonder if all the ints in this struct should be unsigned (and then
> consistently so throughout all the header files).

Well... If you're going that far, dev should be uint8_t, ep should be 
uint4_t (well...), and we can probably just make mps a size_t. tt_addr 
should be uint8_t again, and tt_port... Well, maybe uint8_t, too.

>> +
>> +/**
>> + * Describes a single USB transmission.
>> + */
>> +struct cdi_usb_hc_transmission {
>> +    /// Transaction this transmission is part of
>> +    cdi_usb_hc_transaction_t ta;
>> +
>> +    /// Type of transfer to be performed
>> +    cdi_usb_transfer_token_t token;
>> +
>> +    /// Buffer to be used (may be NULL if @size is 0)
>> +    void* buffer;
>> +
>> +    /// Number of bytes to be transferred (may be 0, and may exceed the MPS)
>> +    size_t size;
> Perhaps this suggests that the right unsigned type for mps is size_t,
> too.
>
>> +    /**
>> +     * Toggle bit to be used for the first packet issued in this transmission.
>> +     * If @size exceeds the MPS and thus multiple packets are transmitted, the
>> +     * toggle bit will be toggled automatically.
>> +     */
>> +    int toggle;
> bool? (Honest question; "bit" just sounds like it, but I don't know how
> this actually works)

Good question, I asked myself the same. For normal data transfers, this 
bit can be only 0 or 1. But for isochronous transfers, I (think I) know 
it can switch between 0, 1, 2, and even something else.

Also, bool wouldn't be the right type even if it can be only 0 or 1. 
It's a bit that's switched for every transfer (so that lost packets can 
be detected, a bit like the TCP sequence number; only you don't need a 
full-fledged sequence number for USB because every (non-isochronous) 
packet is replied to with an ACK, and you're waiting for that ACK before 
sending the next packet), so it's not "false"/"true", but really just an 
integer mod 2.

>> +    /**
>> +     * Result of this transmission. Only valid after wait_transaction() has
>> +     * returned.
>> +     */
>> +    cdi_usb_transmission_result_t* result;
>> +};
> I won't say that this patch is right, but it looks plausible at least. ;-)

That's good enough, I suppose. :-) Thanks!

I'll change the types and remove cdi_usb_provide_hc().

Max