A microSD Active Object with QP/C and USDHC1 — and the Card-Detect Line That Lied

I needed a microSD card on a Control Unit board running QP/C active objects over FreeRTOS. The architecture rule on that project is absolute: no blocking calls inside an AO’s dispatch handler. The SDMMC middleware does not care about my rules — SD_CardInit() blocks on an OSA semaphore no matter what the Kconfig says.

That was the easy problem. The hard one showed up later: card detection worked for a while, then broke unpredictably after a few insert/remove cycles, and once an init failed it never recovered. On removal, the debugger showed the card-detect callback firing twice — false, then immediately true.

The board was reporting a card that was not there, and it was doing it to itself.

In this article I show how the SdCard AO is wired — schematic to pin mux to worker task to state machine — and then how the detection was actually fixed, because the first version was architecturally correct and still unreliable.

The routing table that matters. Note CD_B and RESET_B are on dedicated USDHC1 alt-functions, not GPIO — that single fact shapes the whole design.

Step 1 — Read the schematic before believing the pin mux

Hardware: microSD socket on USDHC1.

Pull direction was checked against NXP’s own evkbmimxrt1060/sdmmc_examples reference pin_mux.c before any driver code was written — the SD spec requires pull-ups, not pull-downs, on CMD/DATA/CD for the open-drain identification phase. The field-by-field reasoning is in the companion article on pin config: pull/keeper, drive strength and slew rate.

Step 2 — Middleware setup, and one build-breaking export

In MCUXpresso Config Tools → Component Configuration → Middleware → sdmmc:

• SD card (middleware.sdmmc.sd)
• uSDHC host controller (middleware.sdmmc.host.usdhc) — not SDHC or SDIF, those are for other NXP families
• Transfer mode: non-blocking
• OSA selection: confirm it resolved to FreeRTOS (component.osa_free_rtos), not bare-metal

error: MCUX_COMPONENT_middleware.sdmmc.common ... is assigned in a
configuration file, but is not directly user-configurable (has no prompt)

What survives in prj.conf:

CONFIG_MCUX_COMPONENT_middleware.sdmmc.sd=y
CONFIG_MCUX_COMPONENT_middleware.sdmmc.host.usdhc=y
CONFIG_MCUX_COMPONENT_middleware.sdmmc.host.usdhc.non_blocking=y

Step 3 — Board SDMMC config

There was no sdmmc_config.h in this repo yet. The SDK’s middleware.sdmmc.usdhc.template component ships only a generic stub at middleware/sdmmc/template/usdhc/sdmmc_config.h, which has to be copied in and filled with board values — the same way pin_mux.c is generated once and then hand-edited.

#define BOARD_SDMMC_SD_HOST_BASEADDR USDHC1
#define BOARD_SDMMC_SD_HOST_IRQ      USDHC1_IRQn
#define BOARD_SDMMC_SD_CD_TYPE       kSD_DetectCardByHostCD   /* hardware CD_B */
#define BOARD_SDMMC_SD_POWER_RESET_ACTIVE_HIGH (1)            /* RESET_B HIGH = power ON */

BOARD_SD_Config() wires the card descriptor’s usrParam.pwr callback to a function calling USDHC_AssertHardwareReset(USDHC1, enable). That is what actually switches the transistor pair and powers the card, since GPIO writes do nothing on a pin muxed to a peripheral alt-function.

The build system picks up a project-provided sdmmc_config.c and says so during CMake configure:

-- Will use custom config file .../bsp/app/sdmmc_config.c from project

Step 4 — The blocking-API problem, and the worker-task pattern

That conflicts directly with “no blocking calls inside AO event handlers”. The resolution is to never call these APIs from the AO’s dispatch function at all. bsp_sdcard.c owns a dedicated FreeRTOS worker task that:

1. Calls BOARD_SD_Config() and SD_HostInit() once at startup.
2. Waits on a binary semaphore, given by the hardware CD_B interrupt callback. That callback is ISR-safe by construction — it does xSemaphoreGiveFromISR and nothing else.
3. On card insertion, power-cycles via SD_SetCardPower off/on, then calls the blocking SD_CardInit().
4. Posts a plain QACTIVE_POST() — task context, not _FROM_ISR — back to the SdCard AO with the result.

The AO’s state machine never touches a blocking call. It only reacts to posted result signals.

Step 5 — The active object

SdCard is a singleton AO. The state machine is deliberately small:

stateTop
  stateDisabled                 <- waits for SM_SDCARD_ENABLE_SIG
    -> BSP_SdCard_Init(ao, initOkSig, initFailSig, removedSig)
  stateEnabled
    stateNoCard                 <- initial substate
      HW_SD_CARD_INIT_OK_SIG    -> publish SD_CARD_MOUNTED_SIG,   -> stateMounted
      HW_SD_CARD_INIT_FAIL_SIG  -> publish SD_CARD_ERROR_SIG,     stay in stateNoCard
    stateMounted
      HW_SD_CARD_REMOVED_SIG    -> publish SD_CARD_UNMOUNTED_SIG, -> stateNoCard
    SM_SDCARD_DISABLE_SIG       -> BSP_SdCard_Deinit(),           -> stateDisabled

Other AOs subscribe to SD_CARD_MOUNTED_SIG, SD_CARD_UNMOUNTED_SIG and SD_CARD_ERROR_SIG. They never talk to the BSP or the worker task directly — no shared data between AOs.

A SystemManager_stateConfigureAndEnableSdCard state slots into the boot chain between Io and Rte, publishing SM_SDCARD_ENABLE_SIG. No separate configure phase is needed because init is already non-blocking from the AO’s point of view.

On priority: I first placed the AO at Io+1, then deliberately lowered it to Blinky+1. Its dispatch is trivial — few events, no blocking — and the real work lives on a separate low-priority worker task. There is no reason for it to out-rank I/O-critical AOs like Io, I2CBusController or TouchController. Size AO priority to actual urgency, not to habit.

Step 6 — Where it went wrong

Everything above is architecturally correct, and it was not reliable in practice. It took an extended debugging session to find out why, and the answer is worth writing down because the lesson generalises.

Symptoms

• Detection worked for a while, then broke unpredictably after a few insert/remove cycles.
• After an SD_CardInit() failure, detection corrupted and never recovered.
• The HMI display went black while touch kept working — the SD path was starving the FlexIO-eDMA display.
• In the debugger, the CD callback fired twice on removal: false, then immediately true.

Root causes, stacked

1. SD_HostDoReset() on removal disabled all USDHC interrupt signals, and nothing re-armed them. Detection silently died.
2. Boot-with-card gap in the SDK. If a card is already inserted at power-on, the SDK arms no CD interrupt at all.
3. RESET_B ↔ CD_B coupling, in hardware. The card power switch sits next to the card-detect line. Toggling it dumps a transient onto CD_B. With a card inserted, the card mechanically holds CD_B low and is immune. With the card removed, CD_B floats on just its 10 kΩ pull-up and the transient flips it — a fake insertion immediately after a real removal.
4. Trusting the ISR-reported state. Acting on the value the CD interrupt reported, on a line this noisy, propagated every glitch straight into the state machine.
5. Retry livelock. A persistent init failure, retried on every wake, power-cycled the card each time. Each power-cycle self-glitched another CD interrupt. The resulting SD_CardInit/DMA/interrupt churn is what starved the display.

The fix — four measures, and you need all four

Defense in depth: never trust a single signal on a coupled, bouncing line. The CD interrupt becomes a “something changed, go check” trigger. The live hardware pin is the source of truth.

1. Arm the removal interrupt once at boot if a card is already present, closing the SDK’s boot-with-card gap. One write, during single-threaded init — never in the steady-state loop.
2. Debounce and re-read the hardware on every edge. On a reported change, wait ~50 ms, then read the actual pin with SDMMCHOST_CardDetectStatus(), not the ISR flag. If it matches the last acted-on state, it was a false trigger: drain the semaphore and ignore it.
3. Power-cycle on insertion, then re-sync and drain. After SD_CardInit(), re-read the live pin, reset the tracked state to it, and drain pending semaphore gives — absorbing the fake CD interrupts the power-cycle itself induces through RESET_B coupling.
4. Never power off on removal. The card is already gone; toggling RESET_B only glitches the now-floating CD line. The next insertion power-cycles cleanly anyway. This also matches the SDK examples, which only power-cycle on insertion.

The retry livelock disappears as a consequence. Acting only on a debounced, hardware-confirmed change of state means a persistent init failure is reported once and then waits for a genuine remove and re-insert. No churn, no display starvation.

Step 7 — Verifying it

• Host unit tests (CppUTest) cover the full lifecycle: disabled → enabled, mount, unmount, error paths, disable-while-mounted, re-enable, plus two Q_ASSERT tests for BSP init and deinit failure. The BSP is mocked, so the worker task and hardware are never touched in host tests.
• Firmware build gates: both the flexspi_nor_sdram_debug_qspy and flexspi_nor_sdram_debug_trace presets must build clean.
• On hardware, via QSpy: open QView, set the current object and AO object to l_SdCard, filter for the matching AO IDs, and enable the global SM group (all) plus QS_QF_PUBLISH. Add BSP_logMsgWithUint() calls at each blocking-call boundary in the worker task — the trace then shows driver status codes rather than just “it failed”.

Cheat sheet — a new SDMMC-backed AO on this platform

Summary

What works now: the SdCard AO mounts and unmounts reliably across repeated insert/remove cycles, a failed init is reported once instead of livelocking, and the display no longer starves. What is still open: the 100 nF cap on the card-detect net is a schematic change for the next board spin, not something software can do.

Three things I would carry to any board:

1. The interrupt tells you when to look, not what is true. On a coupled or bouncing line, debounce and re-read the hardware.
2. A self-induced action can generate its own spurious interrupts. Power-cycling the card glitched the very line that reports the card. Re-sync and drain afterwards.
3. Match the SDK structure, but not blindly. The SDK examples do not debounce because their reference boards do not have this RESET_B-to-CD_B coupling. Board-specific hardware realities need board-specific software on top of the SDK pattern.

And the one that cost the most time: fix all the root causes at once. Each of the four measures addresses a different failure. Removing any one of them brought a symptom back.

Related

• i.MX RT1062 pin config: pull/keeper, drive strength and slew rate — why CMD/DATA/CD need pull-ups
• FlexSPI + QSPI NOR on the i.MX RT1062 — the other storage path on this board

💬 Questions, corrections, or your own war story with card detect? Leave a comment below — I read and answer all of them.