I'm making yet another attempt to port a complex project to the MCUX SDK and once again I'm baffled by the (lack of) documentation. Am I missing something? Is the documentation still being worked on? It's completely inadequate in many areas.
I'm using the MK22FN1M0AVLH12 specifically, with SDK version 2.3.1. To give an example of what I'm talking about, let's consider the simplest of the drivers: GPIO. I just want to set and clear some pins.
The GPIO section in the API reference manual (MK22F51212 Rev. 0) has a blank overview section - no description at all. Ok, I know what GPIO is and I've got a good idea of what should be here, that's not a big deal.
There's an FGPIO driver section that says a few MCUs support it. It doesn't say which ones. Seems like if we're going to have different API reference documents generated for every MCU, optional features like this ought to be excluded if they're not present. If all of the documents are the same, why the elaborate SDK builder system?
Moving on to the GPIO driver. This section at least has a one-line description that defines what GPIO stands for. That's a start. No use case or examples, though - it just says to check out the driver examples. If there are multiple boards, this means we've got to dig around and see which ones actually have useful examples. In this case I've got only one board to check, and the GPIO example demonstrates exactly two of the functions - GPIO_PinInit and GPIO_PortToggle.
There's a list of output operations and GPIO_PinWrite includes the brilliant description "Sets the output level of the multiple GPIO pins to the logic 1 or 0." Pretty clear that it works on multiple pins. The description says parameter "pin" is "GPIO pin number", though - number, not mask. There's no further description of the function, so now we've got contradictory hints and no certainty as to what it's expecting. And recall that there is no example given anywhere for GPIO_PinWrite, so we can't even deduce it from that.
How do we resolve this ambiguity? We've got to read the source for GPIO_PinWrite(), where we can see that it's setting PCOR or PSOR and shifting 1 by the pin number - and if you're not already familiar with the hardware registers, you've got to look them up in the reference manual to see that that means.
So it's not a multiple pin write - it does take a single pin number. The one-sentence explanation given for this function is wrong. The API has failed to save the developer one iota of development time, and in fact this discovery process has more steps than just starting with the reference manual and writing one's own code.
Then there's the GPIO_PortSet() function. I've got to jump back to the overview to get a description, which is "Sets the output level of the multiple GPIO pins to the logic 1". The second parameter is named 'mask' and it's defined as "GPIO pin number macro". Ok, where is the pin number macro defined? There's nothing about macros anywhere in this section. But checking the source code reveals that it's not a macro of any sort, it's a mask, and it just sets base->PSOR.
What if I want to read all of the pins for a port at once? There's not an API function for that. Is the expectation that we'll access GPIOn->PDIR directly? Why does PSOR get an API wrapper but PDOR doesn't? Should I be able to use the API and the API documentation alone to interact with the hardware? If not, what's the expected starting point for a developer reading up on how to access registers directly in a way that conforms to the SDK's conventions? Like where would I find the base pointer names for this part?
The language used is also often ambiguous or not quite parsable as English. Take "0: corresponding pin output low-logic level." I challenge you to diagram that sentence/fragment. Is 'pin output' the subject? Is 'output' a verb? Why is "low-logic" hyphenated?
What about metadata for this documentation? How do I tell what version of the SDK it applies to? When was it last revised? For that matter, where are any dates other than the 2016 copyright? It conveniently does provide a link for "the latest version of this and other MCUXpresso SDK documents" (https://mcuxpresso.nxp.com/apidoc/) - and the link is dead.
This isn't documentation - this is what you get when you tell a first-year computer science student they have to document their code for an assignment and they install Doxygen and hand in whatever it automatically generated. For the GPIO section at least, I'd consider that a 'C' grade at best if the information was accurate. Given the errors in the mask and pin number definitions, it's a solid 'F' to me - worse than no documentation.
Yes, a competent programmer can figure all of this out with the combination of the SDK docs, the MCU reference manual, and the SDK source code. It doesn't really save any time, though.
NXP as an organization is not incapable of writing good docs - the sensor fusion user's guide is really quite good. Good luck finding it, though. As far as I can tell the current revision is 2.2 but I can't come up with any Google search or search terms on NXP's site that will actually take you to that document. You have to know to build a custom SDK package for one of the two boards that supports ISSDK, and add the ISSDK option. That's assuming you already knew Sensor Fusion is now part of ISSDK.
That's why I'm asking here. Is there some newer version of the SDK API reference manual that I'm not finding? Or is this really as good as it gets?
Scott
