What do you want from MCU vendors?

[ataradov]

Still, there seems to be quite some distance between SVD and actual HLL definitions.(For example, Microchip changed EVERYTHING on SAMxxx between pack versions, even though both versions are presumably based on the same root chip description

Well, that's exactly the point of SVD. You can generate your own header files and not rely on erratic behaviour from manufacturers.

I don't like that change, and I will probably start generating my own header files for future projects. I already do that for GigaDevice parts, since their header files are atrocious.

[techman-001]

a CMSIS-SVD file

Hmm.  Does that have any traction outside of ARM?   I guess it could; Atmel had something similar (.ATDF) for their AVRs.Still, there seems to be quite some distance between SVD and actual HLL definitions.(For example, Microchip changed EVERYTHING on SAMxxx between pack versions, even though both versions are presumably based on the same root chip description...  https://community.atmel.com/forum/gratuitous-changes-cmsis-types-and-defines-mplabx )

It does have traction outside of ARM, but not officially.

For instance the Rust folks have made CMSIS-SVD converters for the Ti MSP430 and the tm4c1294, which I use to automatically generate my Forth memmap, bitfield and assembly equ files. It made using these chips *very* easy for me, thanks Rust people!

The Atmel SAMxxx range all have CMSIS-SVD's being ARM based.

I've never seen a PIC CMSIS-SVD converter,  which would be nice as I do have a Forth (Flashforth) for them, but don't wish to have to manually enter memmaps and bitfields as it's far too time consuming and error prone.

I think ARM set the standard with CMSIS-SVD and it would be very handy if the other mfrs would adopt it. Just my 2c.

[westfw]

that's exactly the point of SVD. You can generate your own header files and not rely on erratic behaviour from manufacturers. [/size]

[/size]
[/size]I don’t know.  I want to import other people’s code, buy sw vendors’ code, use code from books, and probably even use code from the chip vendors.  The manufacturers symbols would have to be REALLY awful before I’d prefer a foursome of,different schemes.  And I’d rather not have it all blow up...
[/size]Eventually, standardization is more,impotrant than a particularly elegant mechasm in a tinycorner of the chip

[rhodges]

Going back in time, I seem to remember that Motorola (for example) had a prominent page in the manuals asking for feedback to improve the manual.

Now, when I see a typo or a confusing description, I can't find any email address to contact the editors. How the hell do they expect to correct their datasheets when they hide their contact information?!

[NorthGuy]

Now, when I see a typo or a confusing description, I can't find any email address to contact the editors. How the hell do they expect to correct their datasheets when they hide their contact information?!

The same with the software. There's no way to report bugs. Everything must go through some sort of outsourced tech support. Worse yet, users got accustomed to this, and most don't try at all.

Same with banks. I try to call my local branch, but the phone is redirected to nationwide call center, possibly located somewhere in India.

Companies don't want to hear from customers. Instead they send you surveys with questions that are mostly irrelevant.

[SiliconWizard]

a CMSIS-SVD file

Hmm.  Does that have any traction outside of ARM?   I guess it could; Atmel had something similar (.ATDF) for their AVRs.Still, there seems to be quite some distance between SVD and actual HLL definitions.(For example, Microchip changed EVERYTHING on SAMxxx between pack versions, even though both versions are presumably based on the same root chip description...  https://community.atmel.com/forum/gratuitous-changes-cmsis-types-and-defines-mplabx )

By the very name, CMSIS means "Cortex Microcontroller Software Interface Standard". So CMSIS-SVD files are purely defined for ARM Cortex MCUs.

I don't think I have seen CMSIS-SVD "compliant" files for any other targets than ARM Cortex ones. Some vendors have similar files, but they aren't strictly compatible.

[Bassman59]

I want useful examples that are properly documented. Verbosity in example comments is fine -- tell me WHY you do what you are doing. WHY is this weird library being included.

If a configurator tool is provided, I want all of the examples to have configurations that were generated BY THAT TOOL.

I want examples that get updated with the tools and the SDKs. So if there's a new release of the tools or the SDK, all of the examples need to be refreshed.

Documentation for tools and SDKs must be updated with those tools and SDKs. If a walk-through/"get started" video is provided, make sure it ALWAYS uses the current rev of the tools.

Doxygen is not a substitute for actual user manuals. If your code comments are worthless, so is your doxygen documentation.

Low-level drivers that basically abstract register accesses are fine.

Specifically regarding USB stacks: every vendor has different ideas on how to implement a USB library. Most of them are way overcomplicated. They're ok if you are going to implement the exact device classes for which examples are provided, but to do anything else it's usually a shit-show. All that is really necessary is: a, code that handles reading the device descriptors from one big structure. b, for IN transactions (to the host) provide a WRITE function that takes a buffer and sends it out over the specified endpoint. c, for OUT transactions (from the host) provide a READ function that fires an interrupt or callback when a previously-supplied buffer is filled from a specific endpoint. The Silicon Labs USB library is straightforward and easily extended. The TI Tiva and MSP-432 library is a disaster.

And so on.

[JPortici]

I want useful examples that are properly documented. Verbosity in example comments is fine -- tell me WHY you do what you are doing. WHY is this weird library being included.

If a configurator tool is provided, I want all of the examples to have configurations that were generated BY THAT TOOL.

I want examples that get updated with the tools and the SDKs. So if there's a new release of the tools or the SDK, all of the examples need to be refreshed.

Documentation for tools and SDKs must be updated with those tools and SDKs. If a walk-through/"get started" video is provided, make sure it ALWAYS uses the current rev of the tools.

Doxygen is not a substitute for actual user manuals. If your code comments are worthless, so is your doxygen documentation.

I sense you're not a fan of silicon labs (or at least their ezradios)

[Bassman59]

I want useful examples that are properly documented. Verbosity in example comments is fine -- tell me WHY you do what you are doing. WHY is this weird library being included.

If a configurator tool is provided, I want all of the examples to have configurations that were generated BY THAT TOOL.

I want examples that get updated with the tools and the SDKs. So if there's a new release of the tools or the SDK, all of the examples need to be refreshed.

Documentation for tools and SDKs must be updated with those tools and SDKs. If a walk-through/"get started" video is provided, make sure it ALWAYS uses the current rev of the tools.

Doxygen is not a substitute for actual user manuals. If your code comments are worthless, so is your doxygen documentation.

I sense you're not a fan of silicon labs (or at least their ezradios)

Actually, I am a fan of Silicon Labs. I've used their 8051 parts since they were still Cygnal. Getting a USB device working on EFM8UB2 wasn't difficult at all. The only hiccup was getting them to explain how the USB device interface would handle throttling data from the host. It turns out that it did exactly what it should do. (And the same interface is present on the EFM32 devices with USB, so porting was straightforward.)

The EFM32 parts I've used (TG, GG) were not difficult to get going. The GG11 has a big fail in that the driver for the Ethernet interface is buried in the Micrium OS code and not supported as standalone, so a bare-metal (or other RTOS) design is, uh, not supported. And I wish that they supported High Speed USB, but that seems to be at odds with their low-power IoT push.

I have never used their wireless parts (EZR) so I can't comment.

[JPortici]

ezradios check for every point in that list.
they can be configured only with their WDS application, god forbid they provide the algorythm to calculate the radio parameters

WDS has three output modes:
-Header file with many defines containing all sorts of binary blobs, space separated hex numbers
-Sample project for their IDE which by the way uses SDCC (puke) and assumes you are using a specific 8bitter from them
-Sends the confiuration directly to the demoboard in case one is connected

The communication protocol is not documented. you only know it's SPI, no idea on the mode or how it works so you need to decipher the sample project, which contains only a handful of comments for the useless bits like "now i'm turning on a LED" and the next function is something akin to "SetLedOn(LED1)"
Well, actually one of the datasheets for one of the parts in the ezradio line briefly mention how to communicate with the radio so how to send requests and read data, which i would never figure out in a million years and gives some hints on an initialization sequence, which i couldn't figure out in on my own.

Oh, and the information is scattered across several datasheets, app notes and reference manuals some of which won't be found in the product page nor mentioned in other datasheets with thei identification code code so you know it's the right one.

But then there is this other archive which contains the programming interface in an htm format. doxygen!!!!! but at least formatted a bit to not look like an aftertought and THAT's probably what you need to understand the various commands, what they expect and what the device responds, once you figure out how to communicate

Back to the initialization sequence, only found in the sample project: remember that we have an array of hundreds of space separated hex? how the hell am i supposed to put them in an array? but with a macro of course. containing macros. containing macros. I think four layer of macros unpack the patch because of course there was some formatting to do, every nth bythe is the lenght of the next message, same for the various configuration parameters. It took me a whole day to decypher the macros and port everything to platform independent C because their ancient IDE doesn't do expansion nor symbol navigation and also the funcions, I HATE SDCC with all my heart.

Also, undocumented gotchas to put the radio into sleep, how to achieve low power.

Once you get over all this the radio itself is pretty nice to use.. well would be better if it didn't have an extremely retarded QFN with 4 LGA pads on the corners containing both power and essential signals. why, oh why  but they're still the cheapest radio chips (by a lot!) that fit my requirements

At the time i was tempted to try the radio and bluetooth enabled mcus from them to try and reduce costs but i was put off by the lack of documentation

[up8051]

well would be better if it didn't have an extremely retarded QFN with 4 LGA pads on the corners containing both power and essential signals. why, oh why

Unfortunately, they also use this case for EFM8 series processors

Incomplete datasheets are probably the worst.
As an example I can give: Microchip PIC32MZ USB HS OTG
document 61232A.pdf"Section 51. Hi-Speed USB with On-The-Go (OTG)"
Preliminary sine 2013 
Half of the information is missing, an attempt to get more accurate information from Microchip technical service failed.
The only source of information  is the sample library from the Harmony package.

[NorthGuy]

Incomplete datasheets are probably the worst.
As an example I can give: Microchip PIC32MZ USB HS OTG
The only source of information  is the sample library from the Harmony package.

They bought an USB HS IP from someone, inserted it into their chips. The IP came with the library, which they simply passed to the user without adding/changing much. There may be no single person at Microchip who knows how it works and can produce  better documentation. One of them practically said this on their forum. I'm afraid this is new normal.

[mark03]

ezradios check for every point in that list.
they can be configured only with their WDS application, god forbid they provide the algorythm to calculate the radio parameters

Radios are to MCUs what GPUs are to application processors:  A black box which shall never be publically documented, even if this severely constrains actual end-user applications due to lack of timely driver support.  Marketing doesn't care.  They still get to claim all of the wonderful [theoretical] capabilities on the "data brief."  (Please refer to the unfortunate saga of the Intel Atom processors with Imagination Technologies GPUs, one of which never did get an actual accelerated driver, even on Windows!!  The reason:  Imagination would only allow their contracted driver-dev team to see the documentation, and they never delivered )

Precious IP is the most-cited rationale for these kinds of policies, but it's hard for me to take that seriously.  In the case of radios, an additional fig leaf exists in the form of FCC regulations---they can't risk mere mortals fooling around with the radio hardware, never mind the quality/competence of the devs actually producing the closed-source vendor code...

Anyway, this is pretty much universal in the RF SoC world, so it's probably not fair to criticize one vendor more than their competitors.  At least I know TI (CCxxxx series) is basically the same as you describe.

[Bassman59]

Incomplete datasheets are probably the worst.
As an example I can give: Microchip PIC32MZ USB HS OTG
The only source of information  is the sample library from the Harmony package.

They bought an USB HS IP from someone, inserted it into their chips. The IP came with the library, which they simply passed to the user without adding/changing much. There may be no single person at Microchip who knows how it works and can produce  better documentation. One of them practically said this on their forum. I'm afraid this is new normal.

That's the case with the TI Tiva M4 and MSP-432 devices. The standard user manual has no detail for the USB hardware other than a list of registers. It says that to get access to the manual that has much more detail about how the USB stuff works, you have to fill out an online form and wait to be approved. I did that, the approval was quick (I'm in the US, so I guess it's easier) and there it was.

The same thing applies to the Ethernet in the SiLabs GG11 device. They licensed the core from someone and to "keep that IP confidential" they require you to use the Micrium OS which has the driver.

[wizard69]

I want useful examples that are properly documented. Verbosity in example comments is fine -- tell me WHY you do what you are doing. WHY is this weird library being included.

The "WHY" is so important that I really don't understand why it gets ignored so often

If a configurator tool is provided, I want all of the examples to have configurations that were generated BY THAT TOOL.

I want examples that get updated with the tools and the SDKs. So if there's a new release of the tools or the SDK, all of the examples need to be refreshed.

If they can't update them then with draw them from public view.

Documentation for tools and SDKs must be updated with those tools and SDKs. If a walk-through/"get started" video is provided, make sure it ALWAYS uses the current rev of the tools.

Doxygen is not a substitute for actual user manuals. If your code comments are worthless, so is your doxygen documentation.

The best thing that could happen is if the entire industry relearned how to comment code.    This especially for code designed to be examples of how to use hardware features.

Low-level drivers that basically abstract register accesses are fine.

Specifically regarding USB stacks: every vendor has different ideas on how to implement a USB library. Most of them are way overcomplicated. They're ok if you are going to implement the exact device classes for which examples are provided, but to do anything else it's usually a shit-show. All that is really necessary is: a, code that handles reading the device descriptors from one big structure. b, for IN transactions (to the host) provide a WRITE function that takes a buffer and sends it out over the specified endpoint. c, for OUT transactions (from the host) provide a READ function that fires an interrupt or callback when a previously-supplied buffer is filled from a specific endpoint. The Silicon Labs USB library is straightforward and easily extended. The TI Tiva and MSP-432 library is a disaster.

And so on.

I like your post and have a couple of other things to add.

Support a new language for embedded development that moves away from C/C++.   For compiled languages I see Rust and Swift as the best two examples moving forward.   This probably will upset may a C programmer out there but the idea is to have languages that remove the problems (mistakes) seen in C code.   

Likewise I'd like to see vendors start to support official MicroPython distributions for a range of chips.    I'm basically from the back ground of industrial controls (PLC's) and frankly development times for one off projects is ridiculous.   MicroPython is ideal for one off projects that doesn't need performance or that you can throw chip performance at.   Having an officially supported version from chip vendors would elevate its status.   In a nut shell bridge the development gap between rapid development hardware and hard embedded development.

By the way far better IDE's could go a long ways to making rapid development more feasible.    I'm not convinced that such really exists yet.   However modern desktop computer certainly have the performance to deliver such an IDE.   I know some may prefer the slow way of the command line but that isn't exactly a productivity win.