Reschedule points are currently undocumented

[andyross]

Zephyr has never been good about documenting its schedule points, where a call to z_swap() (via the z_reschedule family of internal utilities) can be made and a new thread can be selected to run. This complicates user analysis, especially in the case of cooperative/non-preemptible threads, and can lead to surprising behavior (see for example #20802, where a priority change due to mutex release is not immediately honored by the scheduler).

We should be rigorous about this and document all the circumstances under which each API can reschedule. For example:

• k_sem_take() will swap only on an empty semaphore
• k_sem_give() will always reschedule, even if no other threads were waiting
• k_mutex_unlock() will not swap, even if the priority changes (reschedule not done after mutex unlock #20802)
• k_pipe_put() will not swap, except if an async message is queued

And lots more...

The lack of documentation here is blocking work on existing code, so we really need to get this fixed.

[pabigot]

As I have noted elsewhere this behavior appears to be inconsistent with the described behavior of cooperative threads which appears to specifically disallow a context switch on a mutex release of a blocked higher-priority thread.

The architectural description of cooperative thread behavior must be done before individual API descriptions can be annotated as part of #18970.

Removing assignment and priority so this can be discussed in triage tomorrow.

[carlescufi]

k_sem_give() will always reschedule, even if no other threads were waiting

As @pabigot notes, this seems to be inconsistent with the diagram he links to assuming in the diagram the ISR is using k_sem_give() to make Thread 2 ready. Thoughts @andyross ?

[pabigot]

k_sem_give() will always reschedule, even if no other threads were waiting

As @pabigot notes, this seems to be inconsistent with the diagram he links to

I think it's fine. "reschedule" doesn't mean "force a context switch". See #20919 (comment)

To discuss but I think this issue can be closed as redundant with #18970, unless it turns out we can't define the behavior in terms of standard feature sets, in which case we can address it then.

[pabigot]

API 2020-07-07: Closing as duplicate of #18970 which is the centerpoint of current plans to document API expectations.