xTaskNotifyWait(): incorrect documentation of the ulBitsToClearOnEntry parameter (IDFGH-5468)

[alyf80]

Environment

• IDF version: current release/v4.1 HEAD, but 4.2 and 4.3 are also affected

Problem Description

The documentation of the ulBitsToClearOnEntry parameter of xTaskNotifyWait() says:

Bits that are set in ulBitsToClearOnEntry value will be cleared in the calling task’s notification value before the task checks to see if any notifications are pending, and optionally blocks if no notifications are pending.

The underlying code, however, first checks whether there is a pending notification, and then only clears the bits if there are no pending notifications.

I know that the above snippet comes straight from FreeRTOS (so it's really their problem), but this caused me quite a lot of hair pulling, so it would be probably a good idea to update the documentation to reflect reality.

On the FreeRTOS side, things appear to have been fixed in release 10.4.0 (in conjunction with a major overhaul of the task notification API), as the documentation now reads:

Any bits set in ulBitsToClearOnEntry will be cleared in the calling RTOS task's notification value on entry to the xTaskNotifyWait() function (before the task waits for a new notification) provided a notification is not already pending when xTaskNotifyWait() is called.

[projectgus]

Hi @alyf80,

Thanks for pointing this out. We can certainly update the docs from the newer version to match the behaviour (although we won't update FreeRTOS to v10.4 yet, if you're interested then there's some discussion in #7137).

[SoucheSouche]

Hi @alyf80,
The documentation will be updated to match the implementation of xTaskNotifyWait().