diff options
author | Ahmad Fatoum <a.fatoum@pengutronix.de> | 2021-06-22 10:26:15 +0200 |
---|---|---|
committer | Sascha Hauer <s.hauer@pengutronix.de> | 2021-06-25 09:31:03 +0200 |
commit | aa649b826c535810b59a107a67cc90079a0681e5 (patch) | |
tree | 01ab3670f6875f2392eac7220c08c22357a9d18c /Documentation | |
parent | 7ead63d835f70a56ca6b51ee8c15ac48d0ed068b (diff) | |
download | barebox-aa649b826c535810b59a107a67cc90079a0681e5.tar.gz barebox-aa649b826c535810b59a107a67cc90079a0681e5.tar.xz |
Documentation: devel: background-execution: update bthread docs
Using bthreads throughout means we'll need finer grained locking across
the code base, which is too big a commitment for now. Previous commit
limited bthread_reschedule to only happen in command context, like
how it is for workqueues. Adjust the docs appropriately.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
Link: https://lore.barebox.org/20210622082617.18011-7-a.fatoum@pengutronix.de
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/devel/background-execution.rst | 34 |
1 files changed, 11 insertions, 23 deletions
diff --git a/Documentation/devel/background-execution.rst b/Documentation/devel/background-execution.rst index fa4d23e6d2..d379593efb 100644 --- a/Documentation/devel/background-execution.rst +++ b/Documentation/devel/background-execution.rst @@ -10,9 +10,9 @@ Pollers ------- Pollers are a way in barebox to frequently execute code in the background. -barebox is single-threaded, so a poller is not executed as a separate thread, -but instead pollers are executed whenever ``is_timeout()`` is called. This has -a few implications. First of all, pollers are not executed when +They don't run within their own threads, but instead they are executed +whenever ``is_timeout()`` is called. +This has a few implications. First of all, pollers are not executed when ``is_timeout()`` is not called. For this and other reasons, loops polling for hardware events should always use a timeout, which is best implemented with ``is_timeout()``. Another thing to remember is that pollers can be executed @@ -74,31 +74,19 @@ code. Usually a work item is allocated by the poller and then freed either in bthreads -------- -barebox threads are co-operative green threads, which are scheduled whenever -``is_timeout()`` is called. This has a few implications. First of all, -bthreads are not scheduled when ``is_timeout()`` is not called. -For this and other reasons, loops polling for hardware events should always -use a timeout, which is best implemented with ``is_timeout()``. -Another thing to remember is that bthreads can be scheduled anywhere -in the middle of other device accesses whenever ``is_timeout()`` is -called. Care must be taken that a green thread doesn't access the very same device -again itself. See "slices" below on how devices can safely be accessed from -bthreads. +barebox threads are co-operative green threads, which are scheduled for the +same context as workqueues: Before the shell executes the next command. +This means that bthreads can be used to implement workqueues, but not pollers. The bthread interface is declared in ``include/bthread.h``. ``bthread_create()`` is used to allocate a bthread control block along with its stack. ``bthread_wake()`` can be used to add it into the run queue. From this moment on and until the thread terminates, the thread will be -switched to regularly as long as someone calls ``is_timeout()``. -bthreads are allowed to call ``is_timeout()``, which will arrange for -other threads to execute. - -barebox threads are planned to replace previous infrastructure, pollers -and workqueues. Poller like behavior can be easily achieved by looping -and yielding on every iteration. There's ``bthread_should_stop()``, which -can be used as condition for continuing the loop. Workqueues could be -replaced along the same line, but with mutexes protecting underlying device -access. +switched to regularly as long as the shell processes commands. + +bthreads are allowed to call ``is_timeout()``, which will eventually +arrange for other threads to execute. This allowed implementing a Linux-like +completion API on top, which can be useful for porting threaded kernel code. Slices ------ |