STM32 USB support

STM32 USB support

[Chris Holgate]

Simon Kallweit wrote:
> Chris Holgate schrieb:
>>
>> It's stable in my application using my own Linux kernel driver (several
>> million bulk and interrupt transactions and counting!).
>>   
> That sound's pretty stable to me :)

OK - I've now done a bit of tidying up which I hope won't have broken
it!  The latest version of the package is here:

http://www.zynaptic.com/ecos/packages/stm32-usb-20090519.epk

There are a couple of minor TODO's which I need to revisit before a
proper release, but nothing significant.

>> However, I've not had much luck getting it working with the standard
>> eCos test framework - although I now suspect thats a Linux usbfs issue
>> rather than my driver.  I also need to sort out some proper
>> documentation!
> 
> Well, I could do some testing too and see where I get.

That would be very helpful, although I think that the standard host-side
tests have only ever been run on a pretty old version of Linux.  I'd
have more confidence in testing against some standard drivers like a
virtual serial port or a 'memory stick' device.

>> There is a significant difference from the other USB drivers which I
>> should probably flag up (and document).  The endpoint configuration is
>> generated dynamically from the USB descriptors.  This gives a lot of
>> flexibility and potentially allows support for multiple configurations
>> (untested!).  However, the downside is that I had to leave out devtab
>> support since the devtab entries need to be set statically.
>>   
> Don't you think it's possible to have both options? I haven't looked at
> the USB subsystem or any drivers, but I think a public driver should
> behave as the subsystem intends. Maybe the subsystem could be extended
> for more dynamic usage though.

The official docs say "To support this the device driver can provide a
devtab entry for each endpoint".  I took that to mean that devtab
support was optional - and the dynamic endpoint configuration is a much
more useful feature IMHO.

Previously supported hardware has had fixed endpoint configurations
which makes the static devtab entries easy to implement.  However, with
dynamic endpoint configuration, the low-level driver doesn't know
a-priori what endpoints to generate devtab entries for - and nor should it!

Copied to the list, since I'm sure there are other people who would like
to comment...

Chris.

Re: STM32 USB support

[Andrew Lunn]

> >> There is a significant difference from the other USB drivers which I
> >> should probably flag up (and document).  The endpoint configuration is
> >> generated dynamically from the USB descriptors.  This gives a lot of
> >> flexibility and potentially allows support for multiple configurations
> >> (untested!).  However, the downside is that I had to leave out devtab
> >> support since the devtab entries need to be set statically.
> >>   
> > Don't you think it's possible to have both options? I haven't looked at
> > the USB subsystem or any drivers, but I think a public driver should
> > behave as the subsystem intends. Maybe the subsystem could be extended
> > for more dynamic usage though.
> 
> The official docs say "To support this the device driver can provide a
> devtab entry for each endpoint".  I took that to mean that devtab
> support was optional - and the dynamic endpoint configuration is a much
> more useful feature IMHO.
> 
> Previously supported hardware has had fixed endpoint configurations
> which makes the static devtab entries easy to implement.  However, with
> dynamic endpoint configuration, the low-level driver doesn't know
> a-priori what endpoints to generate devtab entries for - and nor should it!

The AT91 USB driver has something similar to this. It can configure
the endpoints by looking at the USB descriptors.

I don't remember how it works with respect to devtab entries.

  Andrew

Re: STM32 USB support

[John Dallaway]

Hi Chris

Great to see more USB support for eCos.

Chris Holgate wrote:

> OK - I've now done a bit of tidying up which I hope won't have broken
> it!  The latest version of the package is here:
> 
> http://www.zynaptic.com/ecos/packages/stm32-usb-20090519.epk

I note that you've defined a new eCos target for "STM3210E-EVAL with
USB". This should not be necessary. If you take a look at one of the
other targets with USB support (eg "assabet") there's a CDL option which
controls compilation of the USB hardware driver source code. In the case
of assabet, this is the CYGFUN_DEVS_USB_SA11X0_EP0 option. This option
is controlled by the CYGINT_IO_USB_SLAVE_CLIENTS interface. The
intention is that other packages implement this interface to indicate
that the USB hardware driver is required.

Can you do something similar for your own target to eliminate the need
for an extra target definition in ecos.db? The assabet target is old and
may not offer the best example.

John Dallaway

Re: STM32 USB support

[Simon Kallweit]

Andrew Lunn wrote:
>>>> There is a significant difference from the other USB drivers which I
>>>> should probably flag up (and document).  The endpoint configuration is
>>>> generated dynamically from the USB descriptors.  This gives a lot of
>>>> flexibility and potentially allows support for multiple configurations
>>>> (untested!).  However, the downside is that I had to leave out devtab
>>>> support since the devtab entries need to be set statically.
>>>>   
>>> Don't you think it's possible to have both options? I haven't looked at
>>> the USB subsystem or any drivers, but I think a public driver should
>>> behave as the subsystem intends. Maybe the subsystem could be extended
>>> for more dynamic usage though.
>> The official docs say "To support this the device driver can provide a
>> devtab entry for each endpoint".  I took that to mean that devtab
>> support was optional - and the dynamic endpoint configuration is a much
>> more useful feature IMHO.
>>
>> Previously supported hardware has had fixed endpoint configurations
>> which makes the static devtab entries easy to implement.  However, with
>> dynamic endpoint configuration, the low-level driver doesn't know
>> a-priori what endpoints to generate devtab entries for - and nor should it!
> 
> The AT91 USB driver has something similar to this. It can configure
> the endpoints by looking at the USB descriptors.
> 
> I don't remember how it works with respect to devtab entries.

Chris, do you have any example code using your driver? I was wondering 
if your approach to dynamically set the endpoint configurations should 
be offered as an official alternative to the devtab entries (or we may 
even get rid of the devtab entries). I may be working on USB serial and 
ethernet support. The USB serial driver at least seems to be tailored 
for the AT91 driver right now and cannot be used generically yet. We 
could change that to use dynamic setup of endpoints, which I think would 
be a great idea.

Simon

Re: STM32 USB support

[Chris Holgate]

Andrew Lunn wrote:

> The AT91 USB driver has something similar to this. It can configure
> the endpoints by looking at the USB descriptors.
> 
I've just had a quick look back at the AT91, and while there's a certain
degree of flexibility there, it's still limited to the particular
configuration decreed by Atmel as far as buffer sizes, endpoint number
etc. is concerned.

With the STM32, ST seem to have taken the opposite approach - you have a
chunk of buffer memory and 8 endpoint state machines.  Beyond that
you've got complete flexibility to choose how many endpoints you want -
input or output (or bidirectional[1] if you don't need double
buffering).  You can also choose an arbitrary set of logical (ie visible
to the host) endpoint IDs and buffer sizes.

Given this flexibility, it seemed to be a bit of a waste to define a
fixed standard configuration similar to the Atmel device.  Instead, when
the host sends the configuration select to the STM32 EP0 I intercept it
and scan the descriptor data structures for a corresponding
configuration.  Using the descriptor configuration I can then set up the
buffer memory and endpoint state machines 'on the fly' to correspond
directly to the configuration requested by the host.

All this gives the application specific driver layered on top of the
STM32 driver complete freedom to specify one or more supported endpoint
configurations.

> I don't remember how it works with respect to devtab entries.

Since the Atmel and other USB drivers have fixed endpoint
configurations, it's reasonable to statically allocate and configure the
devtab entries during the device init sequence.  Unfortunately, this has
obvious problems when using the dynamic configuration scheme described
above.

Chris.

[1] I used the bidirectional mode for the control endpoint, but
otherwise decided it was more bother than it was worth!

Re: STM32 USB support

[Chris Holgate]

Simon Kallweit wrote:

> Chris, do you have any example code using your driver?

There's the high-level driver for my application, but that's quite
involved and will probably obscure more than it illuminates...

> I may be working on USB serial and ethernet support. 

Ethernet for the STM32?  I'd considered having a stab at a driver for
one of the SPI based Ethernet chips (either the Micrel or Microchip) but
just don't have the time right now.

> The USB serial driver at least seems to be tailored
> for the AT91 driver right now and cannot be used generically yet. We
> could change that to use dynamic setup of endpoints, which I think would
> be a great idea.

I've just had a look at the code and it shouldn't be too hard.  The key
change is that in order to obtain a handle on the endpoint data
structures you need to wait for endpoint configuration to complete
(which the serial driver does anyway):

//
--------------------------------------------------------------------------
// Block the calling thread until the USB is configured.

void
usbs_serial_wait_until_configured(void)
{
  cyg_mutex_lock(&usbs_serial_lock);
  while (usbs_serial_state != USBS_STATE_CONFIGURED)
    cyg_cond_wait(&usbs_serial_state_cond);
  cyg_mutex_unlock(&usbs_serial_lock);
}

Then you can get a handle on the endpoint data structures by calling one
of the following functions (see the STM32 USB header).

cyg_usbs_cortexm_stm32_tx_endpoint (...)
cyg_usbs_cortexm_stm32_rx_endpoint (...)

This replaces the static way of doing it, where the following lines from
the USB serial driver specify the statically allocated endpoint data
structures:

extern usbs_tx_endpoint         CYGDAT_IO_USB_SLAVE_SERIAL_TX_EP;
extern usbs_rx_endpoint         CYGDAT_IO_USB_SLAVE_SERIAL_RX_EP;

And these are hooked directly into the following static data structure:

usbs_serial usbs_ser0 = {
    tx_ep:      TX_EP,
    rx_ep:      RX_EP,
    tx_result:  0,
    rx_result:  0,
};

Everything else looks fine.  The STM32 driver should automatically parse
the device descriptors so that it looks like the 'standard' serial
device.  If you don't have any luck with it I might have time to play
with it at the weekend.

Chris.

Re: STM32 USB support

[Frank Pagliughi]

Chris Holgate wrote:
> Andrew Lunn wrote:
>
>   
>> The AT91 USB driver has something similar to this. It can configure
>> the endpoints by looking at the USB descriptors.
>>
>>     
> I've just had a quick look back at the AT91, and while there's a certain
> degree of flexibility there, it's still limited to the particular
> configuration decreed by Atmel as far as buffer sizes, endpoint number
> etc. is concerned.
>
> With the STM32, ST seem to have taken the opposite approach - you have a
> chunk of buffer memory and 8 endpoint state machines.  Beyond that
> you've got complete flexibility to choose how many endpoints you want -
> input or output (or bidirectional[1] if you don't need double
> buffering).  You can also choose an arbitrary set of logical (ie visible
> to the host) endpoint IDs and buffer sizes.
>
> Given this flexibility, it seemed to be a bit of a waste to define a
> fixed standard configuration similar to the Atmel device.  Instead, when
> the host sends the configuration select to the STM32 EP0 I intercept it
> and scan the descriptor data structures for a corresponding
> configuration.  Using the descriptor configuration I can then set up the
> buffer memory and endpoint state machines 'on the fly' to correspond
> directly to the configuration requested by the host.
>
> All this gives the application specific driver layered on top of the
> STM32 driver complete freedom to specify one or more supported endpoint
> configurations.
>
>   
>> I don't remember how it works with respect to devtab entries.
>>     
>
> Since the Atmel and other USB drivers have fixed endpoint
> configurations, it's reasonable to statically allocate and configure the
> devtab entries during the device init sequence.  Unfortunately, this has
> obvious problems when using the dynamic configuration scheme described
> above.
>
> Chris.
>
> [1] I used the bidirectional mode for the control endpoint, but
> otherwise decided it was more bother than it was worth!
>
>   
Yeah, the USB subsystem for eCos was written at a time when USB chips 
were quite rigid - endpoints with fixed sizes and functions. Now, most 
chips are more flexible than not, with generic endpoints and 
configurable memory allocation. So the existing eCos infrastructure is 
showing it's age.  So each new driver is hitting this same problem and 
trying to solve it in a new and different way.

A search of this mailing list and 'ecos-devel' will show a couple 
different complaints and suggestions that I and a few other people made 
a while back. I haven't used eCos all year, but am close to jumping back 
in for a bit, and would need to refresh my own memory with the details.

IIRC, at the time I had fairly convinced myself that what was needed was 
an entirely new USB subsystem that would:
- make it much easier to work with the flexible new chips
- handle much more of the device enumeration
- provide a very specific callbacks structure (like read/write an 
endpoint, respond to a bus reset, set the chips' address, etc)
- handle more of the buffering

In general, make it much easier to knock out USB drivers.

Maybe now it's time to start considering this in earnest?  Count me in.

Frank

Re: STM32 USB support

[Simon Kallweit]

Chris Holgate wrote:
> Ethernet for the STM32?  I'd considered having a stab at a driver for
> one of the SPI based Ethernet chips (either the Micrel or Microchip) but
> just don't have the time right now.

We don't have the possibility to add real ethernet to our platform, 
using ethernet over USB could be a nice solution for device 
configuration (http server).

>> The USB serial driver at least seems to be tailored
>> for the AT91 driver right now and cannot be used generically yet. We
>> could change that to use dynamic setup of endpoints, which I think would
>> be a great idea.
> 
> I've just had a look at the code and it shouldn't be too hard.  The key
> change is that in order to obtain a handle on the endpoint data
> structures you need to wait for endpoint configuration to complete
> (which the serial driver does anyway):

I see. Should be easy to get around. I'll see if I can change the serial 
driver in a way so it's still usable with the other slave drivers.

Simon

Re: STM32 USB support

[Chris Holgate]

Frank Pagliughi wrote:
> 
> Yeah, the USB subsystem for eCos was written at a time when USB chips
> were quite rigid - endpoints with fixed sizes and functions. Now, most
> chips are more flexible than not, with generic endpoints and
> configurable memory allocation. So the existing eCos infrastructure is
> showing it's age.  So each new driver is hitting this same problem and
> trying to solve it in a new and different way.

My thoughts are that the current infrastructure is still pretty usable
and that the main limitations are the use of static devtab entries
(which are optional anyway) and the drivers themselves.  More
specifically, there isn't a good example of how to use the
infrastructure to write drivers for these more configurable USB devices.

My main bugbear is the way in which class drivers currently access
device endpoints.  At the moment you need to know which low level driver
is in use and the completely arbitrary names of the exported static
endpoint data structures.  This should really be hidden behind a generic
API which is defined by usbs.h.  I think that this would be an easy
change and would require mimimal additions to the existing drivers.
Existing drivers could add the endpoint 'getter' functions and still
export their static endpoint data structures for legacy class drivers.

> IIRC, at the time I had fairly convinced myself that what was needed was
> an entirely new USB subsystem that would:
> - make it much easier to work with the flexible new chips
> - handle much more of the device enumeration

There's quite a bit of code in the STM32 driver which addresses these
issues within the existing framework.  Maybe the thing to do would be to
factor it out into a device driver utility library which can be used
alongside the existing framework.

> - provide a very specific callbacks structure (like read/write an
> endpoint, respond to a bus reset, set the chips' address, etc)
> - handle more of the buffering

While the existing callback setup may not be the easiest to use, it does
provide all the required information.  As for buffering, this is
something which I think should be a matter for the class driver writer.
 Again, this could all be made easier by better documentation and a
possible class driver utility library.

> In general, make it much easier to knock out USB drivers.

It's never going to be really easy though!

Chris.

Re: STM32 USB support

[Frank Pagliughi]

> My main bugbear is the way in which class drivers currently access
> device endpoints.  At the moment you need to know which low level driver
> is in use and the completely arbitrary names of the exported static
> endpoint data structures.  This should really be hidden behind a generic
> API which is defined by usbs.h.  I think that this would be an easy
> change and would require mimimal additions to the existing drivers.
> Existing drivers could add the endpoint 'getter' functions and still
> export their static endpoint data structures for legacy class drivers.
>   
In addition, it's difficult to specify endpoints which can be used for 
either direction. I believe several drivers specify that all their 
generic endpoints are "rx endpoints" and if you want to use one to 
transmit data you must overlay a "tx endpoint" on top of it. That's not 
a big problem, but it's confusing. In addition, then rx/tx data 
structures lack a few fields to completely (easily) handle a generic 
endpoint, like the endpoint number, and maybe some intermediate buffer 
pointers to handle a single transfer. So each driver has to add this 
functionality in one way or another.


>> IIRC, at the time I had fairly convinced myself that what was needed was
>> an entirely new USB subsystem that would:
>> - make it much easier to work with the flexible new chips
>> - handle much more of the device enumeration
>>     
>
> There's quite a bit of code in the STM32 driver which addresses these
> issues within the existing framework.  Maybe the thing to do would be to
> factor it out into a device driver utility library which can be used
> alongside the existing framework.
>   
Agreed that this is actually more realistic.

And, keep in mind, there are a few additional tricky issues to which the 
driver writer is exposed, which can be delegated out to a common 
package. I don't think any of the drivers properly deal with the state 
change callback - most appear to emit a "current/new state" enumerated 
value (USBS_STATE_xxx) rather than a state change value 
(USBS_STATE_CHANGE_xxx).

 And the way in which transfers for bulk and interrupt endpoints need to 
be ended - in regard to short and zero packets - can get a little messy, 
but is common to all devices. With a more complete, common endpoint 
structure, this decision making could be handed off to a single, common 
set of routines.

>> - provide a very specific callbacks structure (like read/write an
>> endpoint, respond to a bus reset, set the chips' address, etc)
>> - handle more of the buffering
>>     
>
> While the existing callback setup may not be the easiest to use, it does
> provide all the required information.  As for buffering, this is
> something which I think should be a matter for the class driver writer.
>  Again, this could all be made easier by better documentation and a
> possible class driver utility library.
>   

True, though I worry that even the existing drivers have a number of 
bugs and deficiencies, especially since they're left to handle some 
common control messages on their own. And, since each new driver is 
written using an old one as a template, the bugs are perpetuated. But no 
one - my self included - wants to fix the old drivers since they're 
mostly for chips that are obsolete or no longer viable.

Frank

Re: STM32 USB support

[Chris Holgate]

Frank Pagliughi wrote:
> 
>> My main bugbear is the way in which class drivers currently access
>> device endpoints.  At the moment you need to know which low level driver
>> is in use and the completely arbitrary names of the exported static
>> endpoint data structures.  This should really be hidden behind a generic
>> API which is defined by usbs.h.  
>>   
> In addition, it's difficult to specify endpoints which can be used for
> either direction. I believe several drivers specify that all their
> generic endpoints are "rx endpoints" and if you want to use one to
> transmit data you must overlay a "tx endpoint" on top of it. That's not
> a big problem, but it's confusing.

It does make a bit of a mockery of type safety, though.  To the user, Tx
and Rx endpoints are fundamentally different things and it's good to try
and prevent Tx calls to Rx endpoints and vice versa.  If the driver
writer feels they must use the same data structure for each, then this
should be hidden from the user.

With the STM32 driver, it is possible to have Tx and Rx endpoints with
the same logical endpoint ID but they will be implemented on different
physical endpoints[1].  The user doesn't need to know this - they just
tell the tx or rx endpoint getter function the logical endpoint number
they want and the corresponding, correctly typed data structure is returned.

> And the way in which transfers for bulk and interrupt endpoints need to
> be ended - in regard to short and zero packets - can get a little messy,
> but is common to all devices. With a more complete, common endpoint
> structure, this decision making could be handed off to a single, common
> set of routines.

Yeah - that would have saved me from a lot of pain!

Chris.

[1] The distinction being that logical endpoints are the endpoint
numbers seen by the host and physical endpoints are the actual endpoint
state machines on the chip.

Re: STM32 USB support

[Chris Holgate]

Hi John,

Sorry about the delay in getting back - I got distracted by the other
thread of this discussion...

John Dallaway wrote:
> Hi Chris
> 
> Great to see more USB support for eCos.
> 
> Chris Holgate wrote:
> 
>> OK - I've now done a bit of tidying up which I hope won't have broken
>> it!  The latest version of the package is here:
>>
>> http://www.zynaptic.com/ecos/packages/stm32-usb-20090519.epk
> 
> I note that you've defined a new eCos target for "STM3210E-EVAL with
> USB". This should not be necessary. 

That's there because I want the new package to be loadable against the
3.0 release using the package manager and I couldn't see a way of adding
in new hardware packages to a platform without creating a new target.

When we're all happy that the driver is up to scratch for a CVS commit
I'll modify the existing target as you suggested.

However, this raises another question for the maintainers.  I'm now
developing against 3.0 for production purposes and would rather add in
things like this USB driver as stable 3.0 packages rather than pulling a
potentially unstable CVS tree.  Is there an 'official' place where all
such additional 3.0 packages could be located?

Chris.

Re: STM32 USB support

[Frank Pagliughi]

> With the STM32 driver, it is possible to ...

I'll have a look at this new driver as soon as possible. Sounds interesting.

Re: STM32 USB support

[John Dallaway]

Hi Chris

Chris Holgate wrote:

> John Dallaway wrote:
>> 
>> I note that you've defined a new eCos target for "STM3210E-EVAL with
>> USB". This should not be necessary. 
> 
> That's there because I want the new package to be loadable against the
> 3.0 release using the package manager and I couldn't see a way of adding
> in new hardware packages to a platform without creating a new target.

If you provide a new target record in pkgadd.db which matches the name
of an existing target record in ecos.db, the packages listed in the new
target record will be appended to the existing target record by
ecosadmin.tcl. So you could do something like this in your pkgadd.db:

  target stm3210e_eval {
    packages {
      CYGPKG_IO_USB
      CYGPKG_IO_USB_SLAVE
      CYGPKG_DEVS_USB_CORTEXM_STM32
    }
  }

> When we're all happy that the driver is up to scratch for a CVS commit
> I'll modify the existing target as you suggested.

OK, but you _will_ need to provide a mechanism for disabling the
compilation of the driver source code as I outlined in my previous e-mail.

> However, this raises another question for the maintainers.  I'm now
> developing against 3.0 for production purposes and would rather add in
> things like this USB driver as stable 3.0 packages rather than pulling a
> potentially unstable CVS tree.  Is there an 'official' place where all
> such additional 3.0 packages could be located?

We have tended to avoid doing this in the past. If we did this for all
new packages we would end up with quite a number of .epk files over the
lifetime of an eCos release. These files might also require updating if
bugs are found and fixed. The maintainers focus their efforts on the CVS
repository between releases. If developers want the very latest packages
we advise them to use CVS.

John Dallaway

Re: STM32 USB support

[Chris Holgate]

Hi John,

John Dallaway wrote:

> If you provide a new target record in pkgadd.db which matches the name
> of an existing target record in ecos.db, the packages listed in the new
> target record will be appended to the existing target record by
> ecosadmin.tcl. So you could do something like this in your pkgadd.db:
> 
>   target stm3210e_eval {
>     packages {
>       CYGPKG_IO_USB
>       CYGPKG_IO_USB_SLAVE
>       CYGPKG_DEVS_USB_CORTEXM_STM32
>     }
>   }

I tried this and while it works for adding in a new package, I found
that it has the unfortunate side effect of causing the entire STM3210E
target to be removed when removing the USB package.  Subsequently
re-adding the USB package then just adds in this truncated target
definition which results in ecos.db becoming unloadable.

On balance, I think I'll probably stick with adding in a completely new
target for the time being since this seems to be more robust.  The other
changes you suggested have now gone in and should allow the USB driver
to be added to the standard target in CVS.

Chris.

Re: STM32 USB support

[John Dallaway]

Hi Chris

Chris Holgate wrote:

> John Dallaway wrote:
> 
>> If you provide a new target record in pkgadd.db which matches the name
>> of an existing target record in ecos.db, the packages listed in the new
>> target record will be appended to the existing target record by
>> ecosadmin.tcl. So you could do something like this in your pkgadd.db:
>>
>>   target stm3210e_eval {
>>     packages {
>>       CYGPKG_IO_USB
>>       CYGPKG_IO_USB_SLAVE
>>       CYGPKG_DEVS_USB_CORTEXM_STM32
>>     }
>>   }
> 
> I tried this and while it works for adding in a new package, I found
> that it has the unfortunate side effect of causing the entire STM3210E
> target to be removed when removing the USB package.  Subsequently
> re-adding the USB package then just adds in this truncated target
> definition which results in ecos.db becoming unloadable.

The following (undocumented) incantation:

  ./ecosadmin.tcl --keep_targets remove CYGPKG_DEVS_USB_CORTEXM_STM32

should allow you to remove the driver package without deleting the
targets which use it. Perhaps this should become the default behaviour
when removing packages so that people are less likely to remove target
records inadvertently. Anyway, working with ecosadmin.tcl is certainly
more elegant and more scalable than adding a new target just to
accommodate a new driver.

> The other
> changes you suggested have now gone in and should allow the USB driver
> to be added to the standard target in CVS.

That's great.

John Dallaway