Queue documentation references to portYIELD_FROM_ISR with incorrect parameter

Kernel
1

I came across this and wanted to share in case others run in to this. I haven’t submitted an issue yet.

I believe portYIELD_FROM_ISR is supposed to take a parameter (pdTrue or pdFalse), while the previous taskYIELD_FROM_ISR did not. The documentation for queue doesn’t have a parameter, leading to example code unable to be used (compiler complains of missing expression in macro expansion). 3 lines would have to be updated, for example:
FreeRTOS-Kernel/ /include/queue.h#L1264 (I’m a new user, can’t submit links)

As a note, a couple of the port’s portmacro.h have portYIELD_FROM_ISR that does not take a parameter.

2

Hey @maqifrnswa, welcome to the FreeRTOS community! And thank you for creating a post here before raising an issue on GitHub :slight_smile:.

The function/macro portYIELD_FROM_ISR() is a port specific macro, which is why you’re seeing this inconsistency. This is because there are ports that handle the yield from an Interrupt Service Routine in different ways. That’s actually why there’s the comment that explicitly calls out that the actual macro that is used there is port specific in queue.h:1263

 *  // Now the buffer is empty we can switch context if necessary.
 *  if( xHigherPriorityTaskWoken )
 *  {
 *      // Actual macro used here is port specific.
 *      portYIELD_FROM_ISR ();
 *  }
 * }

Additionally, there are many FreeRTOS ports that do not have this macro defined. (Where I noticed this comment is missing on line queue.h:1344, which should be fixed)

Was there a specific port that you were trying to use that failed to build because of this macro missing? If so I’d be happy to try and help with your issue

3

Thanks for the reply! It wasn’t that the macro was missing from the port, it was just that the port required a parameter that the API documentation did not use, so when I tried what the documentation suggested, it wouldn’t build. I had to then look at the port’s source code, notice that it took a parameter, then saw that some documentation took a parameter and others did not.

I was just raising the issue so it’s documented in case someone else ran in to it. It’s more of an issue that the API documentation uses a port specific macro which is defined differently on different ports (and sometimes even missing), and the API’s documentation includes the less common version of the port specific macro.

So everything works, you just have to not follow the API’s documented example on most ports. Maybe there can be a comment in the API’s documentation example that the port specific macro may be missing or have different signature?

4

Hey Scott, sorry for the long delay in getting back to you
I agree with you that the API documentation wasn’t clear in queue.h about how portYIELD_FROM_ISR() is port specific. And I agree that this can be confusing to people trying to follow the documentation.

I’ve raised a PR to change these comments to be more inline with the other places we discuss this function in the header blocks, such as in event_groups.h:587:

 *          // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
 *          // switch should be requested.  The macro used is port specific and
 *          // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
 *          // refer to the documentation page for the port being used.
 *          portYIELD_FROM_ISR( xHigherPriorityTaskWoken );

If you have a moment would you mind letting me know if you think that the changes in this PR help clear up the use of this Port-specific API?