MCU Vendor Documentation

[Sal Ammoniac]

Is it just me, or is vendor documentation for microcontrollers getting worse and worse? 

I remember looking at the Freescale Kinetis family several years ago and was impressed by the quality and completeness of their documentation. It was well-written and covered all of the common and pathological use cases. At the time I decided to go with NXP and ST MCUs, so I haven't looked at Freescale documentation in years.

A week or two ago I decided to give Kinetis another look and bought a development board and downloaded the reference manual from the Freescale site. The board I have uses one of the new Kinetis MCUs and its reference manual really sucks. There are loads of grammatical errors, and, more importantly, it glosses over or omits things you really need to know when you're programming these chips at the bare-metal level (as opposed to using canned libraries). Some things are just outright wrong too.

What happened? Freescale used to have such good documentation. One clue, perhaps, is in some of the screenshots of oscilloscope traces in the documentation. The menus on these scopes are in Chinese, which leads me to think that these manuals were written by people in Freescale's China office. While I think that having people for whom English is a second language write technical documentation in English is a bad idea to begin with, Freescale should have at least had native speakers go over the manuals and correct the obvious errors. To me, this smacks of unprofessionalism.

What do you think? Is vendor-written documentation going to the dogs?

[nctnico]

Try and work out how the Freescale IMX5x or IMX6 application processor work precisely... 

[hamdi.tn]

i usually like nxp datasheets and TI documentation (for all kind of chips) ,st have some nice documentation too ( however my last experience with stm32F1 datasheet not a single word about interrupt priority and how it can be set was a bit shocking to me ). Microchip i only use 8 bit MCU and on their ds you always find what you need to know.

i think most vendors count much about the fact that many developers now just focus on the application level, with some rtos running the chip even in the most stupid product. so developers will be relaying much on the vendors library's for any low level interaction with the hardware itself. so no need to spend much time on every detail regarding the mcu hardware.

[legacy]

The age of motorola CISC, like 6.8k, 68k, and 88k, had better documentation 

[andyturk]

Good doc takes effort to prepare. And with so many new mcu designs being put out into the market, I bet the OEMs aren't putting the same level of effort into each datasheet.

[uncle_bob]

Hi

The doc's really started to go down hill pretty abruptly in the mid 70's ....They have been going down hill ever since.

Bob

[Bruce Abbott]

it glosses over or omits things you really need to know when you're programming these chips at the bare-metal level... What happened?

Nobody does that any more. You're supposed to use the canned libraries.

[Jeroen3]

You cannot create 1 product with a global team, that does not work. So 1 location (europe, usa or asia) runs a project.
The quality of the product is entirely dependent on the location where it was developed. There are significant differences in teamwork and quality.

Slowly all the R&D is shifting for asia. It all comes down to the price/quality factor. You can get enough quality to make profit in asia for the lowest amount of money possible.

( however my last experience with stm32F1 datasheet not a single word about interrupt priority and how it can be set was a bit shocking to me ).

That is because ST bought an ARM core. All the documentation that is in ARM's manuals will not be in ST's manuals.

[uncle_bob]

Hi

It is also the case that English is no longer the first language learned by every MCU designer. Shucks ... That leads to inevitable typos and odd syntax. The same thing happens if I type a bit late into the evening after having a beer (or ..errr .. maybe more than one) with dinner.

The days of a 30 page all inclusive data package died long ago. Take a look at the timing numbers on the original 6800 (no not a typo two zeros) data sheet. Now explain how the system can ever work. Sometimes being brief on the details is not that good an idea. It actually was more than just leaving the details off the sheet, but that's another story.

Any MCU you find today has information on it. It likely spans at least three major documents and possibly six depending on the vendor. Past that each nasty detail has it's own little sub document. At last count I had a few hundred of them in the folder marked "docs". Each part group that comes out has it's own flurry of sub doc's and yes tracking them down is part of the job. In the case of ARM, the real deal stuff is hosted on ARM Ltd.

Lots of Fun.

It's not that the doc's are getting worse as much as the parts are getting a lot more complex. The world now approaches this stuff from a number of different directions. It stopped being a "break out the soldering iron and the assembler" and "code from this card" world for 99% of the development a long time ago. The fragmented docs are an attempt to better address a world where the guy doing this or that chunk may not be on the same contentment as the guy with the soldering iron.

Fine for some, a real pain for others.

Bob

[dannyf]

The path we are on, putting more and more peripherals on a given chip, is not sustainable. I think it is likely that we are going to see more and more software programmable but otherwise generic "cores", like xmos, eusi, or the propellers.

Essentially cpld/FPGA plus a mcu core. Cypress is taking that approach and we will see how successful they are.

[uncle_bob]

The path we are on, putting more and more peripherals on a given chip, is not sustainable. I think it is likely that we are going to see more and more software programmable but otherwise generic "cores", like xmos, eusi, or the propellers.

Essentially cpld/FPGA plus a mcu core. Cypress is taking that approach and we will see how successful they are.

Hi

Cyprus has been trying that for quite a while at various levels of integration. From what I have seen, they get clobbered in the marketplace. The resultant chip is more expensive and (very important these days) much higher power consumption. The Altera and Xylinx guys are coming in the other way, putting ARM cores on FPGA's. It's the same sort of thing. Expensive and lots of power. If you need something strange (gigabit video i/o) the FPGA approach is fine. If you need "normal" peripherals the Cyprus parts don't give you the bang for the buck.

Each tick of Moore's Law means that the minimum sized die has a crap load more devices on it. If that clock keeps ticking (and it may not) we'll be seeing ever more peripherals on dirt cheap little parts.

Bob

[nctnico]

The path we are on, putting more and more peripherals on a given chip, is not sustainable. I think it is likely that we are going to see more and more software programmable but otherwise generic "cores", like xmos, eusi, or the propellers.

Essentially cpld/FPGA plus a mcu core. Cypress is taking that approach and we will see how successful they are.

Interestingly I just put an NXP LPC11U37 in a design. That microcontroller has some kind of undocumented hardware accellerator and a software library to create extra peripherals (DMA, UART, SPI, I2C, etc, etc). From what I see in the user manual this must be some kind of programmable logic block.

[Jeroen3]

Nothing prevents them from putting in an additional non-arm unlicensed cpu block and use it as a peripheral. They often do for testing already.
They even put in an extra CM0's to use as offload, expect to see that more in the future. A quad cortex M0 mcu or something alike when the cpu clocks and memory density in mcu's start to flatten.

[uncle_bob]

The path we are on, putting more and more peripherals on a given chip, is not sustainable. I think it is likely that we are going to see more and more software programmable but otherwise generic "cores", like xmos, eusi, or the propellers.

Essentially cpld/FPGA plus a mcu core. Cypress is taking that approach and we will see how successful they are.

Interestingly I just put an NXP LPC11U37 in a design. That microcontroller has some kind of undocumented hardware accellerator and a software library to create extra peripherals (DMA, UART, SPI, I2C, etc, etc). From what I see in the user manual this must be some kind of programmable logic block.

Hi

On Freescale parts they call that gizmo Flex I/O. It looks really cool right up to the point you run out of resources. That's happened disappointingly soon each time I've used it.

Bob

[nctnico]

The path we are on, putting more and more peripherals on a given chip, is not sustainable. I think it is likely that we are going to see more and more software programmable but otherwise generic "cores", like xmos, eusi, or the propellers.

Essentially cpld/FPGA plus a mcu core. Cypress is taking that approach and we will see how successful they are.

Interestingly I just put an NXP LPC11U37 in a design. That microcontroller has some kind of undocumented hardware accellerator and a software library to create extra peripherals (DMA, UART, SPI, I2C, etc, etc). From what I see in the user manual this must be some kind of programmable logic block.

Hi

On Freescale parts they call that gizmo Flex I/O. It looks really cool right up to the point you run out of resources. That's happened disappointingly soon each time I've used it.

Bob

Fortunately the hardware IO accellerator on the LPC11U37 is just an add-on next to the fixed (normal) peripherals so it is more like an escape route if you need a little bit extra.