--- /dev/null
+<!-- Copyright (C) 2003 Red Hat, Inc. -->
+<!-- This material may be distributed only subject to the terms -->
+<!-- and conditions set forth in the Open Publication License, v1.0 -->
+<!-- or later (the latest version is presently available at -->
+<!-- http://www.opencontent.org/openpub/). -->
+<!-- Distribution of the work or derivative of the work in any -->
+<!-- standard (paper) book form is prohibited unless prior -->
+<!-- permission is obtained from the copyright holder. -->
+<HTML
+><HEAD
+><TITLE
+>Mutexes</TITLE
+><meta name="MSSmartTagsPreventParsing" content="TRUE">
+<META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
+REL="HOME"
+TITLE="eCos Reference Manual"
+HREF="ecos-ref.html"><LINK
+REL="UP"
+TITLE="The eCos Kernel"
+HREF="kernel.html"><LINK
+REL="PREVIOUS"
+TITLE="Alarms"
+HREF="kernel-alarms.html"><LINK
+REL="NEXT"
+TITLE="Condition Variables"
+HREF="kernel-condition-variables.html"></HEAD
+><BODY
+CLASS="REFENTRY"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>eCos Reference Manual</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="kernel-alarms.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="kernel-condition-variables.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><H1
+><A
+NAME="KERNEL-MUTEXES">Mutexes</H1
+><DIV
+CLASS="REFNAMEDIV"
+><A
+NAME="AEN1098"
+></A
+><H2
+>Name</H2
+>cyg_mutex_init, cyg_mutex_destroy, cyg_mutex_lock, cyg_mutex_trylock, cyg_mutex_unlock, cyg_mutex_release, cyg_mutex_set_ceiling, cyg_mutex_set_protocol -- Synchronization primitive</DIV
+><DIV
+CLASS="REFSYNOPSISDIV"
+><A
+NAME="AEN1108"><H2
+>Synopsis</H2
+><DIV
+CLASS="FUNCSYNOPSIS"
+><A
+NAME="AEN1109"><P
+></P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="FUNCSYNOPSISINFO"
+>#include <cyg/kernel/kapi.h>
+ </PRE
+></TD
+></TR
+></TABLE
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_mutex_init</CODE
+>(cyg_mutex_t* mutex);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_mutex_destroy</CODE
+>(cyg_mutex_t* mutex);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>cyg_bool_t cyg_mutex_lock</CODE
+>(cyg_mutex_t* mutex);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>cyg_bool_t cyg_mutex_trylock</CODE
+>(cyg_mutex_t* mutex);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_mutex_unlock</CODE
+>(cyg_mutex_t* mutex);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_mutex_release</CODE
+>(cyg_mutex_t* mutex);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_mutex_set_ceiling</CODE
+>(cyg_mutex_t* mutex, cyg_priority_t priority);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_mutex_set_protocol</CODE
+>(cyg_mutex_t* mutex, enum cyg_mutex_protocol protocol/);</CODE
+></P
+><P
+></P
+></DIV
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-MUTEXES-DESCRIPTION"
+></A
+><H2
+>Description</H2
+><P
+>The purpose of mutexes is to let threads share resources safely. If
+two or more threads attempt to manipulate a data structure with no
+locking between them then the system may run for quite some time
+without apparent problems, but sooner or later the data structure will
+become inconsistent and the application will start behaving strangely
+and is quite likely to crash. The same can apply even when
+manipulating a single variable or some other resource. For example,
+consider:
+ </P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>static volatile int counter = 0;
+
+void
+process_event(void)
+{
+ …
+
+ counter++;
+}</PRE
+></TD
+></TR
+></TABLE
+><P
+>Assume that after a certain period of time <TT
+CLASS="VARNAME"
+>counter</TT
+>
+has a value of 42, and two threads A and B running at the same
+priority call <TT
+CLASS="FUNCTION"
+>process_event</TT
+>. Typically thread A
+will read the value of <TT
+CLASS="VARNAME"
+>counter</TT
+> into a register,
+increment this register to 43, and write this updated value back to
+memory. Thread B will do the same, so usually
+<TT
+CLASS="VARNAME"
+>counter</TT
+> will end up with a value of 44. However if
+thread A is timesliced after reading the old value 42 but before
+writing back 43, thread B will still read back the old value and will
+also write back 43. The net result is that the counter only gets
+incremented once, not twice, which depending on the application may
+prove disastrous.
+ </P
+><P
+>Sections of code like the above which involve manipulating shared data
+are generally known as critical regions. Code should claim a lock
+before entering a critical region and release the lock when leaving.
+Mutexes provide an appropriate synchronization primitive for this.
+ </P
+><TABLE
+BORDER="5"
+BGCOLOR="#E0E0F0"
+WIDTH="70%"
+><TR
+><TD
+><PRE
+CLASS="PROGRAMLISTING"
+>static volatile int counter = 0;
+static cyg_mutex_t lock;
+
+void
+process_event(void)
+{
+ …
+
+ cyg_mutex_lock(&lock);
+ counter++;
+ cyg_mutex_unlock(&lock);
+}
+ </PRE
+></TD
+></TR
+></TABLE
+><P
+>A mutex must be initialized before it can be used, by calling
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_init</TT
+>. This takes a pointer to a
+<SPAN
+CLASS="STRUCTNAME"
+>cyg_mutex_t</SPAN
+> data structure which is typically
+statically allocated, and may be part of a larger data structure. If a
+mutex is no longer required and there are no threads waiting on it
+then <TT
+CLASS="FUNCTION"
+>cyg_mutex_destroy</TT
+> can be used.
+ </P
+><P
+>The main functions for using a mutex are
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> and
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_unlock</TT
+>. In normal operation
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> will return success after claiming
+the mutex lock, blocking if another thread currently owns the mutex.
+However the lock operation may fail if other code calls
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_release</TT
+> or
+<TT
+CLASS="FUNCTION"
+>cyg_thread_release</TT
+>, so if these functions may get
+used then it is important to check the return value. The current owner
+of a mutex should call <TT
+CLASS="FUNCTION"
+>cyg_mutex_unlock</TT
+> when a
+lock is no longer required. This operation must be performed by the
+owner, not by another thread.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_mutex_trylock</TT
+> is a variant of
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> that will always return
+immediately, returning success or failure as appropriate. This
+function is rarely useful. Typical code locks a mutex just before
+entering a critical region, so if the lock cannot be claimed then
+there may be nothing else for the current thread to do. Use of this
+function may also cause a form of priority inversion if the owner
+owner runs at a lower priority, because the priority inheritance code
+will not be triggered. Instead the current thread continues running,
+preventing the owner from getting any cpu time, completing the
+critical region, and releasing the mutex.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_mutex_release</TT
+> can be used to wake up all
+threads that are currently blocked inside a call to
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> for a specific mutex. These lock
+calls will return failure. The current mutex owner is not affected.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-MUTEXES-PRIORITY-INVERSION"
+></A
+><H2
+>Priority Inversion</H2
+><P
+>The use of mutexes gives rise to a problem known as priority
+inversion. In a typical scenario this requires three threads A, B, and
+C, running at high, medium and low priority respectively. Thread A and
+thread B are temporarily blocked waiting for some event, so thread C
+gets a chance to run, needs to enter a critical region, and locks
+a mutex. At this point threads A and B are woken up - the exact order
+does not matter. Thread A needs to claim the same mutex but has to
+wait until C has left the critical region and can release the mutex.
+Meanwhile thread B works on something completely different and can
+continue running without problems. Because thread C is running a lower
+priority than B it will not get a chance to run until B blocks for
+some reason, and hence thread A cannot run either. The overall effect
+is that a high-priority thread A cannot proceed because of a lower
+priority thread B, and priority inversion has occurred.
+ </P
+><P
+>In simple applications it may be possible to arrange the code such
+that priority inversion cannot occur, for example by ensuring that a
+given mutex is never shared by threads running at different priority
+levels. However this may not always be possible even at the
+application level. In addition mutexes may be used internally by
+underlying code, for example the memory allocation package, so careful
+analysis of the whole system would be needed to be sure that priority
+inversion cannot occur. Instead it is common practice to use one of
+two techniques: priority ceilings and priority inheritance.
+ </P
+><P
+>Priority ceilings involve associating a priority with each mutex.
+Usually this will match the highest priority thread that will ever
+lock the mutex. When a thread running at a lower priority makes a
+successful call to <TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> or
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_trylock</TT
+> its priority will be boosted to
+that of the mutex. For example, given the previous example the
+priority associated with the mutex would be that of thread A, so for
+as long as it owns the mutex thread C will run in preference to thread
+B. When C releases the mutex its priority drops to the normal value
+again, allowing A to run and claim the mutex. Setting the
+priority for a mutex involves a call to
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_set_ceiling</TT
+>, which is typically called
+during initialization. It is possible to change the ceiling
+dynamically but this will only affect subsequent lock operations, not
+the current owner of the mutex.
+ </P
+><P
+>Priority ceilings are very suitable for simple applications, where for
+every thread in the system it is possible to work out which mutexes
+will be accessed. For more complicated applications this may prove
+difficult, especially if thread priorities change at run-time. An
+additional problem occurs for any mutexes outside the application, for
+example used internally within eCos packages. A typical eCos package
+will be unaware of the details of the various threads in the system,
+so it will have no way of setting suitable ceilings for its internal
+mutexes. If those mutexes are not exported to application code then
+using priority ceilings may not be viable. The kernel does provide a
+configuration option
+<TT
+CLASS="VARNAME"
+>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_DEFAULT_PRIORITY</TT
+>
+that can be used to set the default priority ceiling for all mutexes,
+which may prove sufficient.
+ </P
+><P
+>The alternative approach is to use priority inheritance: if a thread
+calls <TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> for a mutex that it
+currently owned by a lower-priority thread, then the owner will have
+its priority raised to that of the current thread. Often this is more
+efficient than priority ceilings because priority boosting only
+happens when necessary, not for every lock operation, and the required
+priority is determined at run-time rather than by static analysis.
+However there are complications when multiple threads running at
+different priorities try to lock a single mutex, or when the current
+owner of a mutex then tries to lock additional mutexes, and this makes
+the implementation significantly more complicated than priority
+ceilings.
+ </P
+><P
+>There are a number of configuration options associated with priority
+inversion. First, if after careful analysis it is known that priority
+inversion cannot arise then the component
+<TT
+CLASS="FUNCTION"
+>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL</TT
+>
+can be disabled. More commonly this component will be enabled, and one
+of either
+<TT
+CLASS="VARNAME"
+>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_INHERIT</TT
+>
+or
+<TT
+CLASS="VARNAME"
+>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_CEILING</TT
+>
+will be selected, so that one of the two protocols is available for
+all mutexes. It is possible to select multiple protocols, so that some
+mutexes can have priority ceilings while others use priority
+inheritance or no priority inversion protection at all. Obviously this
+flexibility will add to the code size and to the cost of mutex
+operations. The default for all mutexes will be controlled by
+<TT
+CLASS="VARNAME"
+>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_DEFAULT</TT
+>,
+and can be changed at run-time using
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_set_protocol</TT
+>.
+ </P
+><P
+>Priority inversion problems can also occur with other synchronization
+primitives such as semaphores. For example there could be a situation
+where a high-priority thread A is waiting on a semaphore, a
+low-priority thread C needs to do just a little bit more work before
+posting the semaphore, but a medium priority thread B is running and
+preventing C from making progress. However a semaphore does not have
+the concept of an owner, so there is no way for the system to know
+that it is thread C which would next post to the semaphore. Hence
+there is no way for the system to boost the priority of C
+automatically and prevent the priority inversion. Instead situations
+like this have to be detected by application developers and
+appropriate precautions have to be taken, for example making sure that
+all the threads run at suitable priorities at all times.
+ </P
+><DIV
+CLASS="WARNING"
+><P
+></P
+><TABLE
+CLASS="WARNING"
+BORDER="1"
+WIDTH="100%"
+><TR
+><TD
+ALIGN="CENTER"
+><B
+>Warning</B
+></TD
+></TR
+><TR
+><TD
+ALIGN="LEFT"
+><P
+>The current implementation of priority inheritance within the eCos
+kernel does not handle certain exceptional circumstances completely
+correctly. Problems will only arise if a thread owns one mutex,
+then attempts to claim another mutex, and there are other threads
+attempting to lock these same mutexes. Although the system will
+continue running, the current owners of the various mutexes involved
+may not run at the priority they should. This situation never arises
+in typical code because a mutex will only be locked for a small
+critical region, and there is no need to manipulate other shared resources
+inside this region. A more complicated implementation of priority
+inheritance is possible but would add significant overhead and certain
+operations would no longer be deterministic.
+ </P
+></TD
+></TR
+></TABLE
+></DIV
+><DIV
+CLASS="WARNING"
+><P
+></P
+><TABLE
+CLASS="WARNING"
+BORDER="1"
+WIDTH="100%"
+><TR
+><TD
+ALIGN="CENTER"
+><B
+>Warning</B
+></TD
+></TR
+><TR
+><TD
+ALIGN="LEFT"
+><P
+>Support for priority ceilings and priority inheritance is not
+implemented for all schedulers. In particular neither priority
+ceilings nor priority inheritance are currently available for the
+bitmap scheduler.
+ </P
+></TD
+></TR
+></TABLE
+></DIV
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-MUTEXES-ALTERNATIVES"
+></A
+><H2
+>Alternatives</H2
+><P
+>In nearly all circumstances, if two or more threads need to share some
+data then protecting this data with a mutex is the correct thing to
+do. Mutexes are the only primitive that combine a locking mechanism
+and protection against priority inversion problems. However this
+functionality is achieved at a cost, and in exceptional circumstances
+such as an application's most critical inner loop it may be desirable
+to use some other means of locking.
+ </P
+><P
+>When a critical region is very very small it is possible to lock the
+scheduler, thus ensuring that no other thread can run until the
+scheduler is unlocked again. This is achieved with calls to <A
+HREF="kernel-schedcontrol.html"
+><TT
+CLASS="FUNCTION"
+>cyg_scheduler_lock</TT
+></A
+>
+and <TT
+CLASS="FUNCTION"
+>cyg_scheduler_unlock</TT
+>. If the critical region
+is sufficiently small then this can actually improve both performance
+and dispatch latency because <TT
+CLASS="FUNCTION"
+>cyg_mutex_lock</TT
+> also
+locks the scheduler for a brief period of time. This approach will not
+work on SMP systems because another thread may already be running on a
+different processor and accessing the critical region.
+ </P
+><P
+>Another way of avoiding the use of mutexes is to make sure that all
+threads that access a particular critical region run at the same
+priority and configure the system with timeslicing disabled
+(<TT
+CLASS="VARNAME"
+>CYGSEM_KERNEL_SCHED_TIMESLICE</TT
+>). Without
+timeslicing a thread can only be preempted by a higher-priority one,
+or if it performs some operation that can block. This approach
+requires that none of the operations in the critical region can block,
+so for example it is not legal to call
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+>. It is also vulnerable to
+any changes in the configuration or to the various thread priorities:
+any such changes may now have unexpected side effects. It will not
+work on SMP systems.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-MUTEXES-RECURSIVE"
+></A
+><H2
+>Recursive Mutexes</H2
+><P
+>The implementation of mutexes within the eCos kernel does not support
+recursive locks. If a thread has locked a mutex and then attempts to
+lock the mutex again, typically as a result of some recursive call in
+a complicated call graph, then either an assertion failure will be
+reported or the thread will deadlock. This behaviour is deliberate.
+When a thread has just locked a mutex associated with some data
+structure, it can assume that that data structure is in a consistent
+state. Before unlocking the mutex again it must ensure that the data
+structure is again in a consistent state. Recursive mutexes allow a
+thread to make arbitrary changes to a data structure, then in a
+recursive call lock the mutex again while the data structure is still
+inconsistent. The net result is that code can no longer make any
+assumptions about data structure consistency, which defeats the
+purpose of using mutexes.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-MUTEXES-CONTEXT"
+></A
+><H2
+>Valid contexts</H2
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_mutex_init</TT
+>,
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_set_ceiling</TT
+> and
+<TT
+CLASS="FUNCTION"
+>cyg_mutex_set_protocol</TT
+> are normally called during
+initialization but may also be called from thread context. The
+remaining functions should only be called from thread context. Mutexes
+serve as a mutual exclusion mechanism between threads, and cannot be
+used to synchronize between threads and the interrupt handling
+subsystem. If a critical region is shared between a thread and a DSR
+then it must be protected using <A
+HREF="kernel-schedcontrol.html"
+><TT
+CLASS="FUNCTION"
+>cyg_scheduler_lock</TT
+></A
+>
+and <TT
+CLASS="FUNCTION"
+>cyg_scheduler_unlock</TT
+>. If a critical region is
+shared between a thread and an ISR, it must be protected by disabling
+or masking interrupts. Obviously these operations must be used with
+care because they can affect dispatch and interrupt latencies.
+ </P
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="kernel-alarms.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="ecos-ref.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="kernel-condition-variables.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Alarms</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="kernel.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Condition Variables</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff