KL25 USB documentation

[__ramon__]

Hi,

Where I can find detailed documentation about KL25 USB with flowcharts, statecharts, etc.?

Because the reference manual is useless.

Thanks in advance.

[paulstoffregen]

I don't think it's fair to say there's no documentation.  The reference manual does indeed document the registers and descriptor table.

If anyone from Freescale reads this, and I am speaking from experience of actually writing a device-only USB stack from scratch, what's really lacking in your reference manual is a solid description of what actual state your controller is maintaining for each endpoint, and how that relates to what must be done with the BDT fields.

It's unreasonable to expect a reference manual to have a tutorial or background material on USB, which can be easily obtained from www.usb.org or Jan Axelson's books.  It's also not reasonable to expect the reference manual to recommend flowcharts for specific algorithms for something as complex as USB.  There are indeed a LOT of very different ways one could structure their USB stack, especially if only a subset of USB functionality is needed.

But the reference manual is sorely lacking in documenting the internal endpoint state.  That truly is unique to Freescale's hardware and not something that can be learned from any other documentation.  I personally spent many long hours trying different approaches while watching with my protocol analyzer to come up with my own mental model of what your internal state machine is really doing.  Even to this day, with many thousands of customers using my USB source code, and a good number now starting to embed it in their own products, I'm *still* not entirely sure my understanding of the internal endpoint state is truly correct.

I know the odds of that chapter ever being improved are probably slim to none, but it'd be really nice if it happened someday.

[__ramon__]

In other words there is no any documentation.

After my whole professional experience with such stupid stuff, I prefer do not work with devices without documentation.
I dislike imagine about internal device activities based only on registers description even if I know how they are should be implemented in RTL.
Several time ago I had close relation to virtual machines. In that context I have developed several virtual USB host controllers and integration with host environment (direct connection with physical devices).

I have looked at Freescale USB stack. It is a kind of mess :smileysad:
Also there is no possibility to validate results without documentation. Yes it can be tested with test suites from usb.org or Microsoft, but...
"Just works" doesn't equal to "Correctly works".

I don't understand. Does it difficult to draw several charts (initialization, interrupt processing, endpoint statechart, transceiver/receiver statecharts, OTG and so on)?
Or maybe RTL was written "from the head" without plans and understandings...

*facepalm*

[mjbcswitzerland]

Hi Roman

No semiconductor manufacturer publishes documents explaining how to completly integrate a USB solution (it is just too huge a topic and has too many factors, such as [possible] OS used for the implementation) - the Freescale documentation concerning the chip is fairly good and adequate for capable engineers.

Semiconductor manufacturer all offer a USB implemention (as example/reference/starting point) and a fair amount of additional documentation (eg. application notes for specific class operation and example of building and testing it).

usb.org maintains the USB specification and there is no need to re-write that as part of semiconductor documentation, just as it also makes no sense in re-writing all the ARM Cortex documentation because the Kinetis is based on it (all details are available for ARM).

Yes, the FSL stack is not the easiest to understand, use and maintain. That is why there are many alternatives that are supported and training available for people/companies who need a reliable project solution and don't want to re-invent the wheel with a several month long development and then several months of further project support until it has matured for production use.

There are also many USB books and articles that aid engineers who want to do some own developments and understand more details. It is also easy to hook up a development board and step a bit fo USB interrupt code to get a good idea in case of any uncertainties.

Freescale is not perfect in this sense but they are also not at all bad - in fact it doesn't get much better and is also adequate, as shown by the fact that in this short thread you already have three links to alternative working solutions that have been developed with the same information, showing that it is possible, and also possible to do well, based on existing information (and a bit of engineering). If you want to do the same there is no reason why you can't do so either. If you think the community would benefit from more diagrams, blogs, application notes etc. then there is nothing stopping you add them during your work to show how it should be done.

Regards

Mark

[__ramon__]

Hi Mark

Yes, I can draw my imaginations in diagrams, but they will still just my imaginations. Also I will spend a lot of my time to do the job that, I believe, has already/should be done by Freescale guys.

Also I can show not perfect but more useful documentation. For example you can just look at USB chapters in FM3 PERIPHERAL MANUAL from Fujitsu and evaluate its coverage.

Product without public or maybe even internal documentation is not a product, it doesn't engineered at all.

[mjbcswitzerland]

Hi Roman

I think the situation in software-engineering terms is quite simple:

if ((Fujfitsu_documentation > Freescale_documentation) && (Fujitsu_speed > Freescale_speed) && (Fujitsu_support > Freescale_support) && (Fujitsu_toolchain_cost < Freescale_toolchain_cost) && (Fujitsu_chip_price < Freescale_chip_price)) {

    fnUseFujitsuChip();

}

else {

    fnUseFreescaleChip();

}

Which branch to take ? ;-)

Regards

Mark

[bobpaddock]

You can find my KL25Z bare metal USB HID here:Attached is USB Generic HID demo for the FRDM-KL25Z Freedom Board

Jan Alxelson's site is a good place for USB related questions and answers (Not Freescale specific): USB

[paulstoffregen]

Freescale's reference manual certainly leaves a lot to be desired, especially in the USB chapter.  There's very little explanation of how the internal state machine works, particularly when it comes to your responsibility in the code to deal with the data toggle bit.  But they do at least document the registers and buffer descriptors pretty well.

Writing a USB stack from the register descriptions is tough.  I know.  I've done it 3 times (2 were earlier stacks for 8 bit non-Freescale chips).  You can find my USB stack for Teensyduino, which runs on a Kinetis K20 chip, here:

https://github.com/PaulStoffregen/cores/blob/master/teensy3/usb_dev.c

You can also find an article written by the one person (as far as I know) who's really looked at my code and other USB code and written a beginner oriented article about how Freescale's USB works:

http://kevincuzner.com/2014/12/12/teensy-3-1-bare-metal-writing-a-usb-driver/

These alone will not be nearly enough.  USB is a complex protocol.  At the very least, you really must read parts of the USB specification.  It can be found for free at www.usb.org.  Their site changes often, and it's buried inside a huge zip file with tons of other docs.  Here's a direct link to just the USB 2.0 spec.

http://www.pjrc.com/teensy/beta/usb20.pdf

If you're not familiar with USB technical details, read chapter 4 and 5 first.

The actual protocol information you need to understand how to use Freescale's USB hardware is mostly in chapter 8.  Once you're able to respond to token and send/receive data with the correct toggle bits, chapter 9 has the info about descriptor data and other details of what you need to do to get a PC or Mac to recognize your device.

The state diagrams and flowchart and other stuff you requested is mostly in those chapter of the USB spec.

As a practical matter, bringing up brand new USB code is a huge challenge, even if you're pretty familiar with USB.  Freescale's poor documentation of their USB's internal state machine, especially how it handles data toggle, will require quite a lot of fiddling and guesswork.  I know, since I've personally done this.

To have any reasonable chance of success, you really must have some sort of USB protocol analyzer, so you can see what's actually happening on the wire as you try things.  There are some software only options, which are more appropriate when working with already-good USB stack code and merely fiddling with descriptor data or the contents of packets.

For bringing up your own stack, you really should get a hardware protocol analyzer.  Another computer is also very useful for viewing the data.  The analyzer I use is the Beagle from Total Phase.

http://www.totalphase.com/protocols/usb/

Again, I want to emphasize the very advanced and difficult nature of writing your own USB code from scratch.  It's not impossible.  I did it.  But I had years of prior experience and very good familiarity with the USB spec, and the Beagle analyzer (and plenty of prior experience using it), but this still took me 1 solid month to really get it working well.

On the plus side, the fact I was able to do so, without any direct contact with anyone inside Freescale for technical questions on their hardware details that are only vaguely explained in the reference manual, shows it can indeed be done.  Specifically to your question, there aren't any easy tutorials with nice, beginner-level documentation that has all the answers or even a useful formula for how to structure your code.  The documents I linked to are probably the best info you'll find to supplement Freescale's terse reference manual and their USB stack source code.

[mjbcswitzerland]

Hi

I agree with Paul's accessment of the situation. If you want to build your first USB class device starting for scratch you need at least one months solid work (assuming you are a professional embedded programmer with say 10 years of experience) and a decent USB analyser (the Beagle is a decent one and they don't cost the world as they used to do - althout $500--$1200 should be budgeted).

Jan Axelsone's USB Complete is one of the books that USB developers often have on their bookshelf which helps decode much of the USB specification that is not very understandable to those who didn't actually write it and so offers good practial advice (a certain amount of knowldge of the way that PC hosts operate with the devie is needed).

After a first class has been written there are many other classes that may need to be added, composite configurations and later host and OTG operation. Depending on how many classes are needed you may need to budget several additional months and lots of testing and debugging as you get the operation validated in productive environments before you can be sure that it is stable enough for industrial use.

Personally I have written drivers for 5 processor families and the Freescale USB controller does require the most handing overhead for controlling toggles etc.(ATMEL controllers, for exmple, do this in the internal state-machine and so the driver code is much simpler) but the Freescale controller are otherwise well balanced, support a good number of endpoints and overall solidly designed. There is a lot of reading-between-lines and practical experimentation needed to actually get all details right.

The problem with the Freescale stack is that it uses many deferred calles that are very difficult to understand and so is a nightmare to study and maintain.It also mixes application, class, driver and HW code so that it has little structure and is not portable. In fact you need a driver/complete example for just about every different part it seems since it won't work on all chips. A good stack will be able to run on all Kinetis and Coldfire parts (with amost the same USB controller) with no application/class code changes above the HAL.

USB is complicated that is for sure. To make it easier I use a Kinetis USB simulation that allows all details to be tested, studied, and new class/applications to be written based on input from reference devices. This means that I no longer work with the user's manual but just step through the simulator to see how the USB interrupts, buffers etc are behaving.

These is also a documents that I can offer: http://www.utasker.com/docs/uTasker/USB_User_Guide.PDF

And KL25 simulation/binaries here: http://www.utasker.com/kinetis/FRDM-KL25Z.html

Note however that all KL and K devices use the same USB controller and can also use the same code with a couple of exceptions such as USB clock settings, cross-bar master access settings and, when on-board, the MPU settings (and USB buffer sizes in case of devices with small SRAM).

Regards

Mark

[Paul_Tian]

Hi, Roman

I suggest you use USB Stack v4.1.1 Freescale bare metal (no OS) USB Stack for your development first. After you installing, you can find more documents in doc folder. Thanks.

The link is USB Stack|Freescale

Best Regards

Paul