Will there ever be proper documentation for KSDK / MCUXpresso SDK?

[scottm]

I'm going to try my best to keep this constructive and minimize the ranting.

KSDK 2.0 seems to be the only supported framework for current Kinetis devices.  I know this is a period of transition with the merger and changes in development tools, but I'd like to know if we can expect to see real, complete documentation or if the current state of affairs is likely to persist indefinitely.

Doxygen is a tool for documenting code, not a substitute for documenting code.  Everything I can find on KSDK - the PDFs and the HTML version - seems to be primarily generated by Doxygen or a similar tool directly from the comments in the code.  That's great, if the programmers put some effort into doing it well.  It'll never look as good as professionally typeset documentation, but I can live with ugly formatting.  I'm OK with spelling errors, too, if they're limited to comments.  (The USB BM stack 5.0 code spells 'function' wrong most places, 'successful' wrong in all instances I think, and 'composite' is misspelled in a typedef name.)

Factual errors are more troubling.  Another example from the USB stack (which I realize is now abandoned):

* @param controller_id : Controller ID
* @param composite_callback_ptr : Pointer to app callback

...

***************************************************
*This function De-initializes the Composite layer
*****************************************************************************/
usb_status USB_Composite_DeInit(
comosite_handle_t handle /* [IN] Controller ID */

This clearly identifies the function as taking two parameters, which it doesn't.  The one parameter it does take is marked 'Controller ID' in the comment right next to it.  The only valid controller ID on this device is 0, and the first thing the code does is exit if the value passed to it is 0.  Because it's not looking for a controller ID, it's looking for a handle.  The documentation here is worse than useless - the only way to get the right answer is to read the code, and if it had been missing comments entirely it would have taken less time to figure out.

Many sections lack any kind of description.  SDCARD, for example.  The overview section is blank. There's also an MMCCARD section and "Secure Digital Card/Embedded MultiMedia Card (CARD)", with no explanation as to their relationship.  The latter contains the following gem:

Function groups

This function group implements the SD card functional API.

This function group implements the MMC card functional API.

So... both?  Maybe it's the component that uses the other two?  No way to tell from the description.

The example code in the docs can't be trusted.  Some of it won't even compile, like this bit from the UART example:

uint8_t sendData[] = ['H', 'e', 'l', 'l', 'o'];

I tasked an employee with a simple KSDK project so he could get a feel for the tools and this is what he ran into.  There's a functional error in the code, too, that I'd have to go look up.  We were told to ignore the example code in the docs and stick to the board examples.  The bad code remains in the docs, though.

Finding the documentation is also an adventure.  Let's follow the most obvious route to look for API docs:

www.nxp.com -> Kinetis MCUs -> Developer Resources -> MCUXpresso SDK -> Documentation

Nothing here but a couple of fact sheets.  If we back up and follow the Kinetis SDK link and go to the documentation section, now we get two fact sheets, a transition guide, and inexplicably a datasheet for the Kinetis KE1xF, app notes for IRDA and PWM pulse counting, and the KE1xZ sub-family reference manual - but it does at least have the SDK API reference.

From the SDK dashboard, you can get the docs but you have to click on 'download' to see the link to the online documentation.  This takes you to a (presumably) customized version of the API docs for that device, with a device number in the URL.  This is not, however, anything in that document to tell you what device's documentation you're looking at.  A Google search for "mcuxpresso sdk api reference manual" returns device 116 as the first result, and one might believe they're looking at the whole thing since there's nothing there to suggest otherwise.

The second hit is the KSDK reference.  I haven't even been able to figure out where this is linked from within NXP's site - I've only gotten there through Google.

Having documents specific to a particular part would be a great idea if it added any information specific to that part.  I'm looking at the UART_Init() function for the MK22FN1M0 and it says the srcClock_Hz parameter is the UART clock source frequency in Hz.  Ok, so what's that?  The docs don't say, so we go back to the reference manual and look at the UART docs.  The baud rate generation section just mentions the module clock with no explanation as to where it comes from.  So we go up to the clock distribution section and it tells us that UART0 and UART1 operate from the core clock and the others from the bus clock.

That gets us the value to plug in to UART_Init(), but if we're smart we'll also leave a note not to change the UART assignment without also changing the clock source, because there's nothing in this chip-specific API that captures that.  This is in contrast to Processor Expert, where you'd create a component, plug in a baud rate, and it'd just work.  If you changed from UART0 to UART2, it'd still work.  If you changed the clock configuration, it'd readjust or it'd warn that it couldn't match the baud rate.

For a simple peripheral initialization, the SDK is now almost worse than nothing.  With no documentation to say how it interacts with the hardware, we're spending just as much time poring through reference manuals and we've got to read the SDK source code to figure out what it's doing.  Maybe it's not intended to simplify things as much as PEx, but it wouldn't hurt to add a line that says "Check the Chip Configuration section in your part's reference manual for UART clock sources.  Note that UARTs in the same part may have different clock sources."

I think the voluminous Doxygen-generated references don't accomplish much other than to give management the impression that the API is in fact documented.  I am in fact a fan of Doxygen myself and use it in all of my projects, but the bulk of the SDK is documented at the bare minimum level I would use as a reminder to myself for code I never expected anyone else to have to read and understand.  I really hope some real documentation is on the way.  Or at the very least, that the SDK and reference manual material might get combined to reduce the need to constantly move back and forth between the two.

[danielchen]

Hi Scott:

Thank you very much for your sincere feedback. Your input is very important for us to improve KSDK quality.  I will forward your comments to the doc team. Just a information that old SDK1.x is not maintained any more. Latest SDK version is SDK2.3 REL7, which is available on on https://mcuxpresso.nxp.com/ web page.

Regards

Daniel