hartmannathan commented on code in PR #20625: URL: https://github.com/apache/nuttx/pull/20625#discussion_r4252988056
########## Documentation/os/scheduling/index.rst: ########## @@ -2,22 +2,106 @@ Scheduling ========== -NuttX decides which thread runs, and when. This page describes that -decision: the states a thread moves through, the policies that order threads -of equal priority, and the interface an application uses to choose between -them. - -The code lives under ``sched/``. +The *scheduler* is the part of the operating system that decides which +thread runs on the CPU. Every time the running thread leaves the CPU, +the scheduler picks the next one. A thread leaves the CPU when it +waits for something, ends, gives up its turn, or when a thread of +higher priority becomes ready. With some policies, such as round +robin, the scheduler also limits how long each thread runs. + +Why does someone have to decide this? Because a CPU runs one thing at a +time. Only one. Think of someone reading several books at the same +time. In fact nobody reads two books at once: you read one for a while, +put the bookmark in, take another, and later come back to the first one +exactly at the page where you stopped. From outside, it looks like all +the books are "being read". And someone has to decide which book to +take now and, sometimes, for how long. That someone is the scheduler. + +Now the same characters with their technical names: + +- **The book is the thread:** a sequence of instructions in execution, + with its own stack. +- **The bookmark is the task control block (TCB).** The kernel keeps + one TCB per thread, with everything needed to resume it: the thread's + priority, its state, and the place where its CPU registers are saved + while it is not running. +- **Changing books is the context switch:** saving the registers of the + thread that stops and loading those of the thread that starts. Each + architecture does this in its own way. + +How does the NuttX scheduler choose? The first rule is priority: a +ready thread of higher priority runs before one of lower priority. And +when two threads have the same priority? Then the *scheduling policy* +decides. NuttX has three: ``SCHED_FIFO``, ``SCHED_RR`` and +``SCHED_SPORADIC``. Each one breaks the tie in its own way, and the +last two have to be enabled in the configuration. + +When NuttX is built with ``CONFIG_SMP`` (SMP stands for *symmetric +multiprocessing*) on a chip with several CPUs, each CPU runs its own +thread, and then several threads really do run at the same time. +Priority still decides, but with more than one CPU there are cases where +a lower-priority thread runs while a higher-priority one waits; the next +section explains them. + +Interrupts are a different story. When a peripheral asks for attention +(the timer, a UART, the end of a DMA transfer) and interrupts are +enabled, the hardware sends the CPU to the handler of that interrupt, +without going through the scheduler and without looking at the +priority of any thread. The handler is not a thread: the scheduler +does not choose when it runs. It can make a thread ready, for example +by posting a semaphore, or the timer can mark the end of the current +thread's turn. In both cases the switch to another thread happens only +when the interrupt returns. A driver can also hand part of its work to +a thread (``irq_attach_thread()``) or to a work queue +(``irq_attach_wqueue()``), and that part competes for the CPU by +priority, like any thread. + +In NuttX a thread can be a *task*, a *pthread* or a *kernel thread*. +The differences are in :doc:`tasks_vs_threads` and +:doc:`kernel_threads_vs_pthreads`. + +This page explains: + +- the states a thread goes through, from creation to the end; +- the three policies, and when to use each one; +- how an application chooses the policy and the priority of a thread. + +The scheduler itself is in ``sched/sched/``. Threads are created, and +get their first priority and policy, in ``sched/task/`` and +``sched/pthread/``. The thread states and the TCB are defined in +``include/nuttx/sched.h``, and each architecture does the context switch +under ``arch/``. Priority comes first ==================== -NuttX is a **strict priority** scheduler. The thread that runs is always -the ready-to-run thread with the highest priority. A lower-priority thread -runs only while no higher-priority thread is ready; the moment a -higher-priority one becomes ready, it takes the CPU. NuttX is fully -pre-emptible, so that happens immediately, including from inside an -interrupt handler. +NuttX uses a **strict priority** scheduler. On a single CPU (without +``CONFIG_SMP``), the thread that runs is the ready-to-run thread with the +highest priority. A lower-priority thread runs only while no +higher-priority thread is ready; the moment a higher-priority one becomes +ready, it takes the CPU, unless preemption is locked with +``sched_lock()`` (see below). When an interrupt handler makes it ready, +the switch happens as the interrupt returns. + +Under ``CONFIG_SMP``, each CPU runs its own thread, so a lower-priority +thread can run on one CPU while a higher-priority thread runs on +another. When a thread becomes ready, the scheduler looks for a CPU in +its affinity mask: an idle one first, otherwise the one running the +lowest-priority thread. A CPU skips a ready thread whose mask does not +include it, so a lower-priority thread can also run while a +higher-priority thread is ready and waits for a CPU in its mask. By +default the mask holds every CPU, so NuttX chooses the CPU; an +application narrows the mask with ``sched_setaffinity()`` (see below). + +Priorities go from ``SCHED_PRIORITY_MIN`` (1) to ``SCHED_PRIORITY_MAX`` Review Comment: On a single-CPU system, if there are two threads, one at priority `SCHED_PRIORITY_MIN` and one at `SCHED_PRIORITY_MAX`, which one will run? This is probably a good place to document whether a higher number (like `SCHED_PRIORITY_MAX`) means a higher priority, or whether a lower number (like `SCHED_PRIORITY_MIN`) means a higher priority. ########## Documentation/os/scheduling/index.rst: ########## @@ -2,22 +2,106 @@ Scheduling ========== -NuttX decides which thread runs, and when. This page describes that -decision: the states a thread moves through, the policies that order threads -of equal priority, and the interface an application uses to choose between -them. - -The code lives under ``sched/``. +The *scheduler* is the part of the operating system that decides which +thread runs on the CPU. Every time the running thread leaves the CPU, +the scheduler picks the next one. A thread leaves the CPU when it +waits for something, ends, gives up its turn, or when a thread of +higher priority becomes ready. With some policies, such as round +robin, the scheduler also limits how long each thread runs. + +Why does someone have to decide this? Because a CPU runs one thing at a +time. Only one. Think of someone reading several books at the same +time. In fact nobody reads two books at once: you read one for a while, +put the bookmark in, take another, and later come back to the first one +exactly at the page where you stopped. From outside, it looks like all +the books are "being read". And someone has to decide which book to +take now and, sometimes, for how long. That someone is the scheduler. + +Now the same characters with their technical names: + +- **The book is the thread:** a sequence of instructions in execution, + with its own stack. +- **The bookmark is the task control block (TCB).** The kernel keeps + one TCB per thread, with everything needed to resume it: the thread's + priority, its state, and the place where its CPU registers are saved + while it is not running. +- **Changing books is the context switch:** saving the registers of the + thread that stops and loading those of the thread that starts. Each + architecture does this in its own way. + +How does the NuttX scheduler choose? The first rule is priority: a +ready thread of higher priority runs before one of lower priority. And +when two threads have the same priority? Then the *scheduling policy* +decides. NuttX has three: ``SCHED_FIFO``, ``SCHED_RR`` and +``SCHED_SPORADIC``. Each one breaks the tie in its own way, and the +last two have to be enabled in the configuration. Review Comment: "have to be enabled" implies that you have to enable them. Perhaps you mean "may be enabled"? ```suggestion last two may be enabled in the configuration. ``` ########## Documentation/os/scheduling/index.rst: ########## @@ -2,22 +2,106 @@ Scheduling ========== -NuttX decides which thread runs, and when. This page describes that -decision: the states a thread moves through, the policies that order threads -of equal priority, and the interface an application uses to choose between -them. - -The code lives under ``sched/``. +The *scheduler* is the part of the operating system that decides which +thread runs on the CPU. Every time the running thread leaves the CPU, +the scheduler picks the next one. A thread leaves the CPU when it +waits for something, ends, gives up its turn, or when a thread of +higher priority becomes ready. With some policies, such as round +robin, the scheduler also limits how long each thread runs. + +Why does someone have to decide this? Because a CPU runs one thing at a +time. Only one. Think of someone reading several books at the same +time. In fact nobody reads two books at once: you read one for a while, +put the bookmark in, take another, and later come back to the first one +exactly at the page where you stopped. From outside, it looks like all +the books are "being read". And someone has to decide which book to +take now and, sometimes, for how long. That someone is the scheduler. + +Now the same characters with their technical names: + +- **The book is the thread:** a sequence of instructions in execution, + with its own stack. +- **The bookmark is the task control block (TCB).** The kernel keeps Review Comment: For consistency with the other two bullet points, I suggest: ```suggestion - **The bookmark is the task control block (TCB):** the kernel keeps ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
