Which mainstream micros have the worst documentation, buggiest silicon etc.

[SiliconWizard]

Yes, I was mistaken. The code example is not related to toggling the GPIO pins.
However, the example is all over the place in the HAL libraries to make sure that a setting has taken place before the next instruction takes place.
In the HAL, this is done a lot when configuring the peripherals.

I believe you, but would you care to post at least an excerpt of it?

To people complaining about the lack of code examples for STM32, CubeMX is the code example.
Simply create a new project in CubeMX which uses the peripheral or feature you are interested in and let it generate the code which you can
use as an example or to study how to accomplish things.

People complaining about that have probably never cared to take a look at what's inside the HAL directories? There are many examples for almost (but admittedly not quite all) all peripherals and CPU features ('Projects' subdirectory). And then, the full source code of HAL is also there and certainly helps figuring out all the functions available, what they do and their parameters. (Not saying that HAL is perfect, but that's not the point here.)

There's no need to ever use CubeMX IMO - when I started with the STM32 MCUs, I started with the HAL, but I absolutely never installed or used the CubeMX software. The HAL files were certainly enough to get started IMO.

[ajb]

And you tell me QSPI is inherently flawed? I used it in 'register access control' mode and yes, it was a invisible minefield of forbidden internal states which stepping into resulted in a total crash, but ultimately this thing is performing well. What is that "unrelated events occurance"?

Disclaimer: I'm still a bit bitter about the weeks of my life this problem cost me.

If you run the QSPI in memory mapped mode with the low-power timeout enabled (deasserts the CS after a period of inactivity so that an external flash IC can switch to a lower power state), when the timeout expires on the same clock edge as an attempt to read from the QSPI, the peripheral deadlocks and locks up the entire MCU.  Even the debug interface stops working!  Because this requires single-clock-cycle timing, it's sensitive to literally everything, making it really hard to isolate, and in my case I ran into it only after my project was quite far along and long after I'd implemented QSPI.  The system would just lock up seemingly at random, anywhere from four times in an hour to not once in 24hrs, just depending on what changes I made to the code and on communications/interrupt timing.  Attempting to use a debugger would either fail completely or just dump me back to the start of main(), which was a bonus headscratcher until I figured that out.  Oh, and at the time, the hardware defect was not yet documented!  Even now the errata entry is terribly blithe about the magnitude of the defect:

Memory-mapped read operations may fail when timeout counter is
enabled.

Description

In memory-mapped mode with the timeout counter enabled (by setting the TCEN bit of the QUADSPI_CR register), the QUADSPI peripheral may hang and the memory-mapped read
operations fail. This occurs if the timeout flag TOF is set at the same clock edge as a new memory-mapped read request..

"Read operations fail", that's a bit of an understatement   

Fortunately, the fix is as easy as disabling the timeout, which is a bit annoying for battery applications I guess, but manually managing the external flash power state is far better than the alternative.

[brucehoult]

Memory-mapped read operations may fail when timeout counter is
enabled.

Description

In memory-mapped mode with the timeout counter enabled (by setting the TCEN bit of the QUADSPI_CR register), the QUADSPI peripheral may hang and the memory-mapped read
operations fail. This occurs if the timeout flag TOF is set at the same clock edge as a new memory-mapped read request..

"Read operations fail", that's a bit of an understatement   

Fortunately, the fix is as easy as disabling the timeout, which is a bit annoying for battery applications I guess, but manually managing the external flash power state is far better than the alternative.

And if you started the access a cycle later than it's ok and wakes up the device again? That's nasty!

[SiliconWizard]

There are none STM32 chips with GPIOs sitting on a bus slower than the CPU core, are there?

Oops, missed that.

Well, actually yes there are. They implement pretty much the same architecture as most Cortex-based MCUs I've seen (there may be exceptions, but haven't seen them myself), following the AMBA architecture. Peripherals, including GPIOs, are usually connected to one (or more) APB bus. There's one bridge per APB bus connecting to the AHB bus. APB busses are typically clocked with a separate, and often slower clock (programmable on many MCUs.) Some higher-performance MCUs have some of their peripherals (like Ethernet) directly connected to the AHB bus, but most still are just connected to an APB. Some MCUs also have their GPIOs directly connected to AHB instead. I can't tell off the top of my head which STM32 lines have their GPIOs on AHB and which on APB, but I'm pretty sure both approaches have been implemented.

Edit: Took a deeper look to give more precise information. The STM32 series in which the GPIOs are on an APB bus is the famous F1 series (including the very popular F103). On other series, such as the more recent L4, GPIOs are on the AHB2 bus, which can be accessed faster than a typical APB, but AHB2 itself can be clocked at a lower speed than the CPU core. So synchronization issues are still potentially there (but would be due to a silicon bug).

On older ARM-based (non-Cortex) MCUs not implementing this AMBA architecture (which I think dates back to early 2000's), that may have been a problem indeed, but I don't know of any current STM32 that doesn't?

But it's still not completely impossible that some silicon bug in the AHB-APB bridges would require the use of workarounds (ot between the different AHB busses when there are several). I just haven't seen any myself in all STM32 (and most other Cortex-based) MCUs I've run into.

[westfw]

Some MCUs also have their GPIOs directly connected to AHB instead.

Or "in addition to", or even on some side channel.   Atmel SAMx2x for example has GPIO pins available via a single-cycle "IOBUS" that is shown as directly connected to the CPU (at least, in the data sheet block diagrams.)

[warpco]

I've worked with PIC, LPC, STM32, TMS320, and with one ARM-based uC from Analog Devices. Documentation from Microchip always had many useful examples and step-by-step instructions on how to use periphery. I missed this in the other manufacturers' documentation.

Regarding the hardware, I think there are no leaders, they are all more or less okay. For example, uC from Analog Devices had a very flexible and simple clocking scheme. I could set the multipliers/dividers individually for each periphery with just a few commands. But DMA configuration was much easer in one of the STM32 MCUs.

[SiliconWizard]

Some MCUs also have their GPIOs directly connected to AHB instead.

Or "in addition to", or even on some side channel.   Atmel SAMx2x for example has GPIO pins available via a single-cycle "IOBUS" that is shown as directly connected to the CPU (at least, in the data sheet block diagrams.)

I admit I don't know the ATSAM MCUs and have never used them. Out of curiousity, I took a look at the SAMD21 family datasheet. Actually, they implement some kind of hybrid approach (quoting):

The IO Pin Controller (PORT) controls the I/O pins of the device.(...)
The PORT is connected to the high-speed bus matrix through an AHB/APB bridge. The Pin Direction,
Data Output Value and Data Input Value registers may also be accessed using the low-latency CPU local
bus (IOBUS; ARM® single-cycle I/O port).

So the GPIOs are accessible both via this IOBUS bus, or via an APB bus. Later in the DS we can read:

The priority of IOBUS accesses is higher than APB accesses. One clock cycle latency can be observed
on the APB access in case of concurrent PORT accesses.

[Harjit]

Given the discussion on the STM32H7, an alternate part is NXP's iMXRT1064. From reading the specs and the errata, they've done a good job of keeping things clean and orthogonal.

Also, the power consumption is incredibly low. This was a surprise since both the STM32H7 and the iMXRT1064 are implemented in a 40nm process.

[MT]

And you tell me QSPI is inherently flawed? I used it in 'register access control' mode and yes, it was a invisible minefield of forbidden internal states which stepping into resulted in a total crash, but ultimately this thing is performing well. What is that "unrelated events occurance"?

Disclaimer: I'm still a bit bitter about the weeks of my life this problem cost me.

If you run the QSPI in memory mapped mode with the low-power timeout enabled (deasserts the CS after a period of inactivity so that an external flash IC can switch to a lower power state), when the timeout expires on the same clock edge as an attempt to read from the QSPI, the peripheral deadlocks and locks up the entire MCU.  Even the debug interface stops working!  Because this requires single-clock-cycle timing, it's sensitive to literally everything, making it really hard to isolate, and in my case I ran into it only after my project was quite far along and long after I'd implemented QSPI.  The system would just lock up seemingly at random, anywhere from four times in an hour to not once in 24hrs, just depending on what changes I made to the code and on communications/interrupt timing.  Attempting to use a debugger would either fail completely or just dump me back to the start of main(), which was a bonus headscratcher until I figured that out.  Oh, and at the time, the hardware defect was not yet documented!  Even now the errata entry is terribly blithe about the magnitude of the defect:

Memory-mapped read operations may fail when timeout counter is
enabled.

Description

In memory-mapped mode with the timeout counter enabled (by setting the TCEN bit of the QUADSPI_CR register), the QUADSPI peripheral may hang and the memory-mapped read operations fail. This occurs if the timeout flag TOF is set at the same clock edge as a new memory-mapped read request..

"Read operations fail", that's a bit of an understatement   

Fortunately, the fix is as easy as disabling the timeout, which is a bit annoying for battery applications I guess, but manually managing the external flash power state is far better than the alternative.

OK, so this lockup only applies to QSPI when "low-power timeout enabled" else it performs OK for mem mapped mode
in all BNK modes?

STM32 have absolutely absurd pin mappings which always make it a huge pain and a big time sink to find an optimal set of pin assignments, and even so the best solution still often results in ridiculous routing (like QSPI on three or four sides of a QFP, MII lines in the middle of the ADC, etc).  Their QSPI peripheral also has a really nasty hardware defect that will totally lock up the chip if two unrelated events occur on the same clock cycle, which makes it like the worst possible thing to debug.

Does this lockup apply to all ST QSPI enabled devices and all BNK modes? Even H7? ! QSPI BNK2 on F446 and H750 only NSC comes from the opposite side (non ADC) rest is neatly pin by pin on one side.

[ajb]

OK, so this lockup only applies to QSPI when "low-power timeout enabled" else it performs OK for mem mapped mode
in all BNK modes?

That is correct as far as I know.

Does lockup apply to all ST QSPI enabled devices and all BNK modes? Even H7? Nothing mentioned about lockup in 446 errata! QSPI BNK2 on F446 and H750 only NSC comes from the opposite side (non ADC) rest is neatly pin by pin on one side.

Presumably every part that shares the same QSPI peripheral revision.  I've tested it personally on F777 and F746.  It's actually pretty easy to test, you don't even need to have an external flash IC connected:

- Setup the QSPI peripheral in memory mapped mode with the timeout counter enabled
- Create a short spin loop to periodically read from some address in the QSPI range
- Sweep the timeout counter register value

You can twiddle an IO pin and scope it along with the QSPI nCS line to watch the correlation (and know immediately when it locks up)

Here's the minimal test program I threw together to demo the problem.  It's mostly defines used in configuration, the actual demonstration is only a few lines. 

Code: [Select]

/*
 * The following is a minimal demonstration of an apparent problem with
 * the QUADSPI peripheral on STM32F7 parts.  The QUADSPI seems to totally
 * lock up the MCU--even preventing debugging--under the following conditions:
 *  - The QUADSPI is in memory mapped mode
 *  - The QUADSPI's timeout counter is enabled
 *  - The timeout counter expires, releasing the QUADSPI_NCS line, right about
 *  the time that a memory-mapped QUADSPI access is attempted.
 *
 * This program has been run on a Nucleo-F767ZI board and successfully
 * demonstrated the problem.  It does not require that an external IC be
 * connected to the QUADSPI interface.  It should run on similar parts with
 * no modification.
 *
 * Be aware that the nature of this apparent fault makes the program rather
 * delicate with regard to timing.  It has been successful when compiled
 * without optimization.  It would probably be more reliable if the main test
 * loop were written in assembly, but even so the run-time performance
 * optimizations of the Cortex-M7 may introduce sufficient timing variations
 * that it takes several tries to achieve the timing required to cause the
 * fault.
 *
 */


/* Includes */
#include "stm32f7xx.h"



/* ****************************************************************************
 * QUADSPI CONFIG VALUES
 * ****************************************************************************/

#define QUADSPI_DCR_FSIZE_Pos 16
#define QUADSPI_CR_PRESCALER_Pos 24
#define QUADSPI_DCR_CSHT_Pos 8

/* QUADSPI->CCR.FMODE specifies the functional mode */
#define QUADSPI_CCR_FMODE_gp 26
#define QUADSPI_CCR_FMODE_MEMMAP (3<<QUADSPI_CCR_FMODE_gp)

/* QUADSPI->CCR.DMODE specifies the number of IO lines to use for
 * data transfer */
#define QUADSPI_CCR_DMODE_gp 24
#define QUADSPI_CCR_DMODE_SINGLE (1<<QUADSPI_CCR_DMODE_gp)

/* QUADSPI->CCR.DCYC specifies the number of dummy cycles to insert between
 * the address and data phases of the transaction */
#define QUADSPI_CCR_DCYC_gp 18
#define QUADSPI_CCR_DCYC_gm (0x1f<<QUADSPI_CCR_DCYC_gp)
#define QUADSPI_CCR_DCYC_m(num) ((num<<QUADSPI_CCR_DCYC_gp) & QUADSPI_CCR_DCYC_gm)


/* QUADSPI->CCR.ABMODE specifies the number of IO lines to use for
 * alternate byte transfer */
#define QUADSPI_CCR_ABMODE_gp 14
#define QUADSPI_CCR_ABMODE_NONE (0x0<<QUADSPI_CCR_ABMODE_gp)

/* QUADSPI->CCR.ADSIZE specifies the number of address bits to use */
#define QUADSPI_CCR_ADSIZE_gp 12
#define QUADSPI_CCR_ADSIZE_24BIT (0x2<<QUADSPI_CCR_ADSIZE_gp)

/* QUADSPI->CCR.ADMODE specifies the number of IO lines to use for
 * address transfer */
#define QUADSPI_CCR_ADMODE_gp 10
#define QUADSPI_CCR_ADMODE_gm (0x3<<QUADSPI_CCR_ADMODE_gp)
#define QUADSPI_CCR_ADMODE_SINGLE (0x1<<QUADSPI_CCR_ADMODE_gp)


/* QUADSPI->CCR.DMODE specifies the number of IO lines to use for
 * instruction transfer */
#define QUADSPI_CCR_IMODE_gp 8
#define QUADSPI_CCR_IMODE_gm (0x3<<QUADSPI_CCR_IMODE_gp)
#define QUADSPI_CCR_IMODE_SINGLE (0x1<<QUADSPI_CCR_IMODE_gp)


#define QSPI_CCR_MEMMAP_VAL (QUADSPI_CCR_FMODE_MEMMAP |\
QUADSPI_CCR_DMODE_SINGLE |\
QUADSPI_CCR_DCYC_m(0)|\
QUADSPI_CCR_ABMODE_NONE |\
QUADSPI_CCR_ADSIZE_24BIT |\
QUADSPI_CCR_ADMODE_SINGLE |\
QUADSPI_CCR_IMODE_SINGLE |\
EXTFLASH_CMD_READ)

#define EXTFLASH_CMD_READ 0x03

/* ****************************************************************************
 * GPIO CONFIG MACROS
 * ****************************************************************************/

#define IO_OUTSET(...) /* set (port, pin) output */ IO_OUTSET_SUB(__VA_ARGS__)
#define IO_OUTSET_SUB(port, pin) GPIO##port->BSRR = (1<<pin)

#define IO_OUTCLR_SUB(port, pin) GPIO##port->BSRR = ((1<<pin)<<16)
#define IO_OUTCLR(...) /* clear (port, pin) output */ IO_OUTCLR_SUB(__VA_ARGS__)

#define IO_OUTTGL(...) /* toggle (port, pin) output */ IO_OUTTGL_SUB(__VA_ARGS__)
#define IO_OUTTGL_SUB(port, pin) GPIO##port->ODR = (GPIO##port->ODR ^ (1<<pin));

#define IO_DIROUT(...) /* set (port, pin) as output */ IO_DIROUT_SUB(__VA_ARGS__)
#define IO_DIROUT_SUB(port, pin) IO_SET_MODE(port,pin, IO_MODER_OUTPUT_gv)

#define IO_SET_MODE(...) IO_SET_MODE_SUB(__VA_ARGS__)
#define IO_SET_MODE_SUB(gpio, pin, mode_gv) GPIO##gpio->MODER = ((GPIO##gpio->MODER & ~IO_MODER_gm(pin)) | ((mode_gv << (pin*2))&IO_MODER_gm(pin)))

#define IO_MODER_gm(pinNum)         (0x03<<(2*pinNum))
#define IO_MODER_INPUT_gv 0x00
#define IO_MODER_OUTPUT_gv 0x01
#define IO_MODER_ALT_gv 0x02
#define IO_MODER_ANALOG_gv 0x03

#define IO_AF_SEL(...)                        IO_AF_SEL_SUB(__VA_ARGS__)
#define IO_AF_SEL_SUB(gpio, pin, af_gv)   IO_AF_SEL_PIN##pin(gpio, pin, af_gv)

#define IO_AF_SEL_PIN0(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN1(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN2(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN3(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN4(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN5(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN6(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)
#define IO_AF_SEL_PIN7(...) IO_AF_SEL_SUB_LO(__VA_ARGS__)

#define IO_AF_SEL_PIN8(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN9(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN10(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN11(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN12(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN13(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN14(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)
#define IO_AF_SEL_PIN15(...) IO_AF_SEL_SUB_HI(__VA_ARGS__)

#define IO_AF_SEL_SUB_HI(gpio, pin, af_gv)    GPIO##gpio->AFR[1] = ((GPIO##gpio->AFR[1] & ~IO_AFRH_gm(pin)) | ((af_gv << ((pin-8)*4)) & IO_AFRH_gm(pin)));
#define IO_AF_SEL_SUB_LO(gpio, pin, af_gv)    GPIO##gpio->AFR[0] = ((GPIO##gpio->AFR[0] & ~IO_AFRL_gm(pin)) | ((af_gv << (pin*4)) & IO_AFRL_gm(pin)));

#define IO_AFRL_gm(pinNum)                    (0x0f<<(pinNum*4))
#define IO_AFRH_gm(pinNum)                    (0x0f<<((pinNum-8)*4))

/* ****************************************************************************
 * GPIOS IN USE
 * ****************************************************************************/

#define LED1 B,0 //GREEN
#define LED2 B,7 //BLUE
#define LED3 B,14 //RED

#define QUADSPI_CLK F,10
#define QUADSPI_NCS B,6

#define QUADSPI_CLK_AF 9
#define QUADSPI_NCS_AF 10


/* Private macro */
/* Private variables */
/* Private function prototypes */
/* Private functions */

void QSPI_memMapMode(void);
void QSPI_memMapModeDisable(void);

void QSPI_init(void){



IO_SET_MODE(QUADSPI_CLK, IO_MODER_ALT_gv);
IO_SET_MODE(QUADSPI_NCS, IO_MODER_ALT_gv);

IO_AF_SEL(QUADSPI_CLK, QUADSPI_CLK_AF);
IO_AF_SEL(QUADSPI_NCS, QUADSPI_NCS_AF);

RCC->AHB3ENR |= RCC_AHB3ENR_QSPIEN;

// clk = AHB, using bank 1
QUADSPI->CR = 0<<QUADSPI_CR_PRESCALER_Pos | 0;

/** vvvv  This is the problem  vvvv  ******************************************/

QUADSPI->CR |= QUADSPI_CR_TCEN;  // enable timeout in memory mapped mode

/** ^^^^  This is the problem  ^^^^  ******************************************/



QUADSPI->DCR =
( 23 << QUADSPI_DCR_FSIZE_Pos ) | // 23-bit addressing = 8MB
( 7 << QUADSPI_DCR_CSHT_Pos);  // 7 -> 8 clock cycles of nCS high between commands

QUADSPI->CR |= QUADSPI_CR_EN;

QUADSPI->FCR =
QUADSPI_FCR_CTEF |
QUADSPI_FCR_CTCF |
QUADSPI_FCR_CSMF |
QUADSPI_FCR_CTOF;
QUADSPI->DLR = 0;

QUADSPI->LPTR = 0;

//Configure QSPI for memory-mapped mode
QSPI_memMapMode();
}


void QSPI_memMapMode(void){
QUADSPI->CCR = QSPI_CCR_MEMMAP_VAL;
}

void QSPI_memMapModeDisable(void){
QUADSPI->CCR = 0;
QUADSPI->CR |= QUADSPI_CR_ABORT;
while(QUADSPI->CR & QUADSPI_CR_ABORT);
}


uint32_t delay_time=10;
volatile uint8_t dummyval;
volatile uint8_t * exfl = (uint8_t*)(0x90000000);
uint16_t offs=0;
int main(void)
{
RCC->AHB1ENR |= RCC_AHB1ENR_GPIOBEN | RCC_AHB1ENR_GPIOFEN;
IO_DIROUT(LED1);
IO_DIROUT(LED2);
IO_DIROUT(LED3);

/* configure SWO pin (optional -- since the MCU will
* wind up in a state where debugging is impossible,
* the only way to extract the parameters that trigger
* the fault is to capture that data beforehand).
*/
IO_SET_MODE(B,3,IO_MODER_ALT_gv);
IO_AF_SEL(B,3, 0);

QSPI_init();

while (1)
{
for(uint32_t i=0; i<500; i++){
/* many reads are made at each timing step to
* increase the chances of the fault occurring, since
* it is so sensitive to timing.
*/
IO_OUTSET(LED3);
for(uint32_t j=0; j < delay_time; j++);
IO_OUTCLR(LED3);
dummyval = *(exfl+(offs++));
}
IO_OUTSET(LED2);
if( (delay_time % 100) ==0) IO_OUTTGL(LED1);

//delay_time+=1;

QSPI_memMapModeDisable();
/* sweeping the QSPI timeout works better than sweeping
* delay_time because the timer (running at AHB frequency)
* has better granularity than a C spinlopp, therefore the
* chances of the timing lining up to cause the fault are
* much improved.
*/
QUADSPI->LPTR++;
QSPI_memMapMode();
IO_OUTCLR(LED2);
}
}


[MT]

OK, so this lockup only applies to QSPI when "low-power timeout enabled" else it performs OK for mem mapped mode
in all BNK modes?

That is correct as far as I know.

Does lockup apply to all ST QSPI enabled devices and all BNK modes? Even H7? Nothing mentioned about lockup in 446 errata! QSPI BNK2 on F446 and H750 only NSC comes from the opposite side (non ADC) rest is neatly pin by pin on one side.

Presumably every part that shares the same QSPI peripheral revision.  I've tested it personally on F777 and F746.  It's actually pretty easy to test, you don't even need to have an external flash IC connected:

Thanks for the heads up, appreciated , this is a serious issue for batt apps , hope its gone with the H750 rev V thats coming in Januari 2020. Will try your code on the F446 and see whats happens..

[jesuscf]

Some Nuvoton microcontrollers have interesting sections in their documentation.  For example:

http://www.nuvoton.com/resource-files/DS_N76E003_EN_Rev1.06.pdf

"IAP  facilitates  the  updating  flash  contents  in  a  convenient  way;  however, user should  follow  some restricted laws in order that the IAP operates correctly. Without noticing warnings will possible cause undetermined results even serious damages of devices. Furthermore, this paragraph will also support useful suggestions during IAP procedures."

"In  general application,  there  is  a  need  of  data storage,  which  is  non-volatile  so  that  it  remains  its content even after the power is off. Therefore, in general application user can read back or update the data,  which  rules  as  parameters  or  constants for  system  control."

"Note: When register CKDIV value  is not  equal  00H, the  system  clock  frequency  will  be  divided,  if under  this  condition  after  MCU  into  power  down  mode, the  WDT  Reset  will  fail.  So suggest  use  WKT  to wakeup N76E003 when into power down mode."