Regarding API documentation

Kernel
1

taskYield() Api Documentation

Hi , in this link it says ;

Detailed Description

taskYIELD

task. h

taskYIELD() is used to request a context switch to another task. However, if there are no other tasks at a higher or equal priority to the task that calls taskYIELD() then the RTOS scheduler will simply select the task that called taskYIELD() to run again.

If configUSE_PREEMPTION is set to 1 then the RTOS scheduler will always be running the highest priority task that is able to run, so calling taskYIELD() will never result in a switch to a higher priority task.

Should it be “taskYIELD() will never result in a switch to a lower priority task.” ?

2

Yes, I agree with you.
By the way,I hope learning some updateted documents comes from official website.

3

if configUSE_PREEMPTION is true, the the moment the higher priority task became ready it would have been switched to (unless there is a programming error in an ISR). So that means there can’t be a higher priority task ready, so taskYIELD() will never switch to a higher priority task, as if there was one, it would have been switched to when it became ready.

The possible exception is if an ISR writen by the user makes a task ready, but didn’t invoke the scheduler as it is supposed to, the there might be a higher priority task waiting to run.

4

I think the idea that wants to be given here is taskYIELD() will never result in a switch to a lower priority task If [configUSE_PREEMPTION] is set to 1.

Otherwise, when configUSE_PREEMPTION is set to 1, we have already know the scheduler will switch to the higher priority task which is ready without waiting for taskYIELD called by current lower priority task.

5

The first sentence says that yield will never switch to a task with a lower priority, that is absolute, but only to a task of same or higher priority. The possibility of switching to a higher priority task can only exist in a non-preemptive system, as if the system was preemptive, then that task would have started as soon as it became ready to run. The last sentence is basically qualify the first that said it COULD switch to a higher priority task to explain that in some cases it is impossible for a higher priority ready task to exist.

6

With your second message, I definitely understood what you mean. Thank you so much.

7

Another way to state this for those who might still be confused, if we list all possible results of a yield, making a list of every logically possible but exclusive possibility they would be:

  1. We could continue with the task making the call
  2. We could switch to a Higher Priority task
  3. We could switch to a Equal Priority task
  4. We could switch to a Lower Priority task.

It is easy to see that this list is exhaustive and exclusive (it covers every conceivable case, and no cases overlap).

By the rules of the scheduler, case 4 is impossible, and the first sentence is basically saying that if we ignored the current task, and the highest priority remaining task is lower in priority than the current task, we will use case 1 instead of case 4.

The second clause is telling us that case 2 is only possible if configUSE_PREEMPTION is 0 (or we aren’t following the rules in our ISRs), as if configUSE_PREEMPTION is true, then when that higher priority task became ready, we would have switched to it then, so the mere fact that we are running to call yield would be evidence that no higher priority task is ready to run.

There are a few small holes in this, one it is possible for an ISR to have been written, arguably incorrectly, to have made ready that higher priority task and then failed to activate the scheduler to run it, at which point its resumption would get delayed to the next time the scheduler is invoked, like a yield call. Another case would be if during the execution of the yield call, an interrupt occurs that causes a higher priority task to run. While technically true that the switch wasn’t BECAUSE of the call to yield, it did happen with the yield so might appear to a somewhat casual observer to have happened.

That all is a mouthful to say, so it makes sense to not go into that sort of detail, but I believe the sentence is there to help point out that if configUSE_PREEMPTION is true, you don’t need to use a yield to run the higher priority task that became ready, but if configUSE_PREEMPTION is 0, then it IS perhaps needed to put in calls to taskYEILD() to switch to the higher priority task if the code spends a significant period of time doing something that didn’t provide scheduler opportunities.