OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-semaphores.html] - Diff between revs 28 and 174

Only display areas with differences | Details | Blame | View Log

Rev 28 Rev 174
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
<!-- This material may be distributed only subject to the terms      -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- http://www.opencontent.org/openpub/).                           -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission is obtained from the copyright holder.               -->
<!-- permission is obtained from the copyright holder.               -->
<HTML
<HTML
><HEAD
><HEAD
><TITLE
><TITLE
>Semaphores</TITLE
>Semaphores</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
<META
NAME="GENERATOR"
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
"><LINK
REL="HOME"
REL="HOME"
TITLE="eCos Reference Manual"
TITLE="eCos Reference Manual"
HREF="ecos-ref.html"><LINK
HREF="ecos-ref.html"><LINK
REL="UP"
REL="UP"
TITLE="The eCos Kernel"
TITLE="The eCos Kernel"
HREF="kernel.html"><LINK
HREF="kernel.html"><LINK
REL="PREVIOUS"
REL="PREVIOUS"
TITLE="Condition Variables"
TITLE="Condition Variables"
HREF="kernel-condition-variables.html"><LINK
HREF="kernel-condition-variables.html"><LINK
REL="NEXT"
REL="NEXT"
TITLE="Mail boxes"
TITLE="Mail boxes"
HREF="kernel-mail-boxes.html"></HEAD
HREF="kernel-mail-boxes.html"></HEAD
><BODY
><BODY
CLASS="REFENTRY"
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
BGCOLOR="#FFFFFF"
TEXT="#000000"
TEXT="#000000"
LINK="#0000FF"
LINK="#0000FF"
VLINK="#840084"
VLINK="#840084"
ALINK="#0000FF"
ALINK="#0000FF"
><DIV
><DIV
CLASS="NAVHEADER"
CLASS="NAVHEADER"
><TABLE
><TABLE
SUMMARY="Header navigation table"
SUMMARY="Header navigation table"
WIDTH="100%"
WIDTH="100%"
BORDER="0"
BORDER="0"
CELLPADDING="0"
CELLPADDING="0"
CELLSPACING="0"
CELLSPACING="0"
><TR
><TR
><TH
><TH
COLSPAN="3"
COLSPAN="3"
ALIGN="center"
ALIGN="center"
>eCos Reference Manual</TH
>eCos Reference Manual</TH
></TR
></TR
><TR
><TR
><TD
><TD
WIDTH="10%"
WIDTH="10%"
ALIGN="left"
ALIGN="left"
VALIGN="bottom"
VALIGN="bottom"
><A
><A
HREF="kernel-condition-variables.html"
HREF="kernel-condition-variables.html"
ACCESSKEY="P"
ACCESSKEY="P"
>Prev</A
>Prev</A
></TD
></TD
><TD
><TD
WIDTH="80%"
WIDTH="80%"
ALIGN="center"
ALIGN="center"
VALIGN="bottom"
VALIGN="bottom"
></TD
></TD
><TD
><TD
WIDTH="10%"
WIDTH="10%"
ALIGN="right"
ALIGN="right"
VALIGN="bottom"
VALIGN="bottom"
><A
><A
HREF="kernel-mail-boxes.html"
HREF="kernel-mail-boxes.html"
ACCESSKEY="N"
ACCESSKEY="N"
>Next</A
>Next</A
></TD
></TD
></TR
></TR
></TABLE
></TABLE
><HR
><HR
ALIGN="LEFT"
ALIGN="LEFT"
WIDTH="100%"></DIV
WIDTH="100%"></DIV
><H1
><H1
><A
><A
NAME="KERNEL-SEMAPHORES">Semaphores</H1
NAME="KERNEL-SEMAPHORES">Semaphores</H1
><DIV
><DIV
CLASS="REFNAMEDIV"
CLASS="REFNAMEDIV"
><A
><A
NAME="AEN1330"
NAME="AEN1330"
></A
></A
><H2
><H2
>Name</H2
>Name</H2
>cyg_semaphore_init, cyg_semaphore_destroy, cyg_semaphore_wait, cyg_semaphore_timed_wait, cyg_semaphore_post, cyg_semaphore_peek&nbsp;--&nbsp;Synchronization primitive</DIV
>cyg_semaphore_init, cyg_semaphore_destroy, cyg_semaphore_wait, cyg_semaphore_timed_wait, cyg_semaphore_post, cyg_semaphore_peek&nbsp;--&nbsp;Synchronization primitive</DIV
><DIV
><DIV
CLASS="REFSYNOPSISDIV"
CLASS="REFSYNOPSISDIV"
><A
><A
NAME="AEN1338"><H2
NAME="AEN1338"><H2
>Synopsis</H2
>Synopsis</H2
><DIV
><DIV
CLASS="FUNCSYNOPSIS"
CLASS="FUNCSYNOPSIS"
><A
><A
NAME="AEN1339"><P
NAME="AEN1339"><P
></P
></P
><TABLE
><TABLE
BORDER="5"
BORDER="5"
BGCOLOR="#E0E0F0"
BGCOLOR="#E0E0F0"
WIDTH="70%"
WIDTH="70%"
><TR
><TR
><TD
><TD
><PRE
><PRE
CLASS="FUNCSYNOPSISINFO"
CLASS="FUNCSYNOPSISINFO"
>#include &lt;cyg/kernel/kapi.h&gt;
>#include &lt;cyg/kernel/kapi.h&gt;
        </PRE
        </PRE
></TD
></TD
></TR
></TR
></TABLE
></TABLE
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>void cyg_semaphore_init</CODE
>void cyg_semaphore_init</CODE
>(cyg_sem_t* sem, cyg_count32 val);</CODE
>(cyg_sem_t* sem, cyg_count32 val);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>void cyg_semaphore_destroy</CODE
>void cyg_semaphore_destroy</CODE
>(cyg_sem_t* sem);</CODE
>(cyg_sem_t* sem);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>cyg_bool_t cyg_semaphore_wait</CODE
>cyg_bool_t cyg_semaphore_wait</CODE
>(cyg_sem_t* sem);</CODE
>(cyg_sem_t* sem);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>cyg_bool_t cyg_semaphore_timed_wait</CODE
>cyg_bool_t cyg_semaphore_timed_wait</CODE
>(cyg_sem_t* sem, cyg_tick_count_t abstime);</CODE
>(cyg_sem_t* sem, cyg_tick_count_t abstime);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>cyg_bool_t cyg_semaphore_trywait</CODE
>cyg_bool_t cyg_semaphore_trywait</CODE
>(cyg_sem_t* sem);</CODE
>(cyg_sem_t* sem);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>void cyg_semaphore_post</CODE
>void cyg_semaphore_post</CODE
>(cyg_sem_t* sem);</CODE
>(cyg_sem_t* sem);</CODE
></P
></P
><P
><P
><CODE
><CODE
><CODE
><CODE
CLASS="FUNCDEF"
CLASS="FUNCDEF"
>void cyg_semaphore_peek</CODE
>void cyg_semaphore_peek</CODE
>(cyg_sem_t* sem, cyg_count32* val);</CODE
>(cyg_sem_t* sem, cyg_count32* val);</CODE
></P
></P
><P
><P
></P
></P
></DIV
></DIV
></DIV
></DIV
><DIV
><DIV
CLASS="REFSECT1"
CLASS="REFSECT1"
><A
><A
NAME="KERNEL-SEMAPHORES-DESCRIPTION"
NAME="KERNEL-SEMAPHORES-DESCRIPTION"
></A
></A
><H2
><H2
>Description</H2
>Description</H2
><P
><P
>Counting semaphores are a <A
>Counting semaphores are a <A
HREF="kernel-overview.html#KERNEL-OVERVIEW-SYNCH-PRIMITIVES"
HREF="kernel-overview.html#KERNEL-OVERVIEW-SYNCH-PRIMITIVES"
>synchronization
>synchronization
primitive</A
primitive</A
> that allow threads to wait until an event has
> that allow threads to wait until an event has
occurred. The event may be generated by a producer thread, or by a DSR
occurred. The event may be generated by a producer thread, or by a DSR
in response to a hardware interrupt. Associated with each semaphore is
in response to a hardware interrupt. Associated with each semaphore is
an integer counter that keeps track of the number of events that have
an integer counter that keeps track of the number of events that have
not yet been processed. If this counter is zero, an attempt by a
not yet been processed. If this counter is zero, an attempt by a
consumer thread to wait on the semaphore will block until some other
consumer thread to wait on the semaphore will block until some other
thread or a DSR posts a new event to the semaphore. If the counter is
thread or a DSR posts a new event to the semaphore. If the counter is
greater than zero then an attempt to wait on the semaphore will
greater than zero then an attempt to wait on the semaphore will
consume one event, in other words decrement the counter, and return
consume one event, in other words decrement the counter, and return
immediately. Posting to a semaphore will wake up the first thread that
immediately. Posting to a semaphore will wake up the first thread that
is currently waiting, which will then resume inside the semaphore wait
is currently waiting, which will then resume inside the semaphore wait
operation and decrement the counter again.
operation and decrement the counter again.
      </P
      </P
><P
><P
>Another use of semaphores is for certain forms of resource management.
>Another use of semaphores is for certain forms of resource management.
The counter would correspond to how many of a certain type of resource
The counter would correspond to how many of a certain type of resource
are currently available, with threads waiting on the semaphore to
are currently available, with threads waiting on the semaphore to
claim a resource and posting to release the resource again. In
claim a resource and posting to release the resource again. In
practice <A
practice <A
HREF="kernel-condition-variables.html"
HREF="kernel-condition-variables.html"
>condition
>condition
variables</A
variables</A
> are usually much better suited for operations like
> are usually much better suited for operations like
this.
this.
      </P
      </P
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_init</TT
>cyg_semaphore_init</TT
> is used to initialize a
> is used to initialize a
semaphore. It takes two arguments, a pointer to a
semaphore. It takes two arguments, a pointer to a
<SPAN
<SPAN
CLASS="STRUCTNAME"
CLASS="STRUCTNAME"
>cyg_sem_t</SPAN
>cyg_sem_t</SPAN
> structure and an initial value for
> structure and an initial value for
the counter. Note that semaphore operations, unlike some other parts
the counter. Note that semaphore operations, unlike some other parts
of the kernel API, use pointers to data structures rather than
of the kernel API, use pointers to data structures rather than
handles. This makes it easier to embed semaphores in a larger data
handles. This makes it easier to embed semaphores in a larger data
structure. The initial counter value can be any number, zero, positive
structure. The initial counter value can be any number, zero, positive
or negative, but typically a value of zero is used to indicate that no
or negative, but typically a value of zero is used to indicate that no
events have occurred yet.
events have occurred yet.
      </P
      </P
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
> is used by a consumer thread
> is used by a consumer thread
to wait for an event. If the current counter is greater than 0, in
to wait for an event. If the current counter is greater than 0, in
other words if the event has already occurred in the past, then the
other words if the event has already occurred in the past, then the
counter will be decremented and the call will return immediately.
counter will be decremented and the call will return immediately.
Otherwise the current thread will be blocked until there is a
Otherwise the current thread will be blocked until there is a
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_post</TT
>cyg_semaphore_post</TT
> call.
> call.
      </P
      </P
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_post</TT
>cyg_semaphore_post</TT
> is called when an event has
> is called when an event has
occurs. This increments the counter and wakes up the first thread
occurs. This increments the counter and wakes up the first thread
waiting on the semaphore (if any). Usually that thread will then
waiting on the semaphore (if any). Usually that thread will then
continue running inside <TT
continue running inside <TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
> and
> and
decrement the counter again. However other scenarioes are possible.
decrement the counter again. However other scenarioes are possible.
For example the thread calling <TT
For example the thread calling <TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_post</TT
>cyg_semaphore_post</TT
>
>
may be running at high priority, some other thread running at medium
may be running at high priority, some other thread running at medium
priority may be about to call <TT
priority may be about to call <TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
>
>
when it next gets a chance to run, and a low priority thread may be
when it next gets a chance to run, and a low priority thread may be
waiting on the semaphore. What will happen is that the current high
waiting on the semaphore. What will happen is that the current high
priority thread continues running until it is descheduled for some
priority thread continues running until it is descheduled for some
reason, then the medium priority thread runs and its call to
reason, then the medium priority thread runs and its call to
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
> succeeds immediately, and
> succeeds immediately, and
later on the low priority thread runs again, discovers a counter value
later on the low priority thread runs again, discovers a counter value
of 0, and blocks until another event is posted. If there are multiple
of 0, and blocks until another event is posted. If there are multiple
threads blocked on a semaphore then the configuration option
threads blocked on a semaphore then the configuration option
<TT
<TT
CLASS="VARNAME"
CLASS="VARNAME"
>CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT
>CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT
> determines which
> determines which
one will be woken up by a post operation.
one will be woken up by a post operation.
      </P
      </P
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
> returns a boolean. Normally it
> returns a boolean. Normally it
will block until it has successfully decremented the counter, retrying
will block until it has successfully decremented the counter, retrying
as necessary, and return success. However the wait operation may be
as necessary, and return success. However the wait operation may be
aborted by a call to <A
aborted by a call to <A
HREF="kernel-thread-control.html"
HREF="kernel-thread-control.html"
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_thread_release</TT
>cyg_thread_release</TT
></A
></A
>,
>,
and <TT
and <TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
> will then return false.
> will then return false.
      </P
      </P
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_timed_wait</TT
>cyg_semaphore_timed_wait</TT
> is a variant of
> is a variant of
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
>. It can be used to wait until
>. It can be used to wait until
either an event has occurred or a number of clock ticks have happened.
either an event has occurred or a number of clock ticks have happened.
The function returns success if the semaphore wait operation
The function returns success if the semaphore wait operation
succeeded, or false if the operation timed out or was aborted by
succeeded, or false if the operation timed out or was aborted by
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_thread_release</TT
>cyg_thread_release</TT
>. If support for the real-time
>. If support for the real-time
clock has been removed from the current configuration then this
clock has been removed from the current configuration then this
function will not be available.
function will not be available.
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_trywait</TT
>cyg_semaphore_trywait</TT
> is another variant which
> is another variant which
will always return immediately rather than block, again returning
will always return immediately rather than block, again returning
success or failure.
success or failure.
      </P
      </P
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_peek</TT
>cyg_semaphore_peek</TT
> can be used to get hold of the
> can be used to get hold of the
current counter value. This function is rarely useful except for
current counter value. This function is rarely useful except for
debugging purposes since the counter value may change at any time if
debugging purposes since the counter value may change at any time if
some other thread or a DSR performs a semaphore operation.
some other thread or a DSR performs a semaphore operation.
      </P
      </P
></DIV
></DIV
><DIV
><DIV
CLASS="REFSECT1"
CLASS="REFSECT1"
><A
><A
NAME="KERNEL-SEMAPHORES-CONTEXT"
NAME="KERNEL-SEMAPHORES-CONTEXT"
></A
></A
><H2
><H2
>Valid contexts</H2
>Valid contexts</H2
><P
><P
><TT
><TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_init</TT
>cyg_semaphore_init</TT
> is normally called during
> is normally called during
initialization but may also be called from thread context.
initialization but may also be called from thread context.
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_wait</TT
>cyg_semaphore_wait</TT
> and
> and
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_timed_wait</TT
>cyg_semaphore_timed_wait</TT
> may only be called from
> may only be called from
thread context because these operations may block.
thread context because these operations may block.
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_trywait</TT
>cyg_semaphore_trywait</TT
>,
>,
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_post</TT
>cyg_semaphore_post</TT
> and
> and
<TT
<TT
CLASS="FUNCTION"
CLASS="FUNCTION"
>cyg_semaphore_peek</TT
>cyg_semaphore_peek</TT
> may be called from thread or
> may be called from thread or
DSR context.
DSR context.
      </P
      </P
></DIV
></DIV
><DIV
><DIV
CLASS="NAVFOOTER"
CLASS="NAVFOOTER"
><HR
><HR
ALIGN="LEFT"
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
SUMMARY="Footer navigation table"
WIDTH="100%"
WIDTH="100%"
BORDER="0"
BORDER="0"
CELLPADDING="0"
CELLPADDING="0"
CELLSPACING="0"
CELLSPACING="0"
><TR
><TR
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="left"
ALIGN="left"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="kernel-condition-variables.html"
HREF="kernel-condition-variables.html"
ACCESSKEY="P"
ACCESSKEY="P"
>Prev</A
>Prev</A
></TD
></TD
><TD
><TD
WIDTH="34%"
WIDTH="34%"
ALIGN="center"
ALIGN="center"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="ecos-ref.html"
HREF="ecos-ref.html"
ACCESSKEY="H"
ACCESSKEY="H"
>Home</A
>Home</A
></TD
></TD
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="right"
ALIGN="right"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="kernel-mail-boxes.html"
HREF="kernel-mail-boxes.html"
ACCESSKEY="N"
ACCESSKEY="N"
>Next</A
>Next</A
></TD
></TD
></TR
></TR
><TR
><TR
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="left"
ALIGN="left"
VALIGN="top"
VALIGN="top"
>Condition Variables</TD
>Condition Variables</TD
><TD
><TD
WIDTH="34%"
WIDTH="34%"
ALIGN="center"
ALIGN="center"
VALIGN="top"
VALIGN="top"
><A
><A
HREF="kernel.html"
HREF="kernel.html"
ACCESSKEY="U"
ACCESSKEY="U"
>Up</A
>Up</A
></TD
></TD
><TD
><TD
WIDTH="33%"
WIDTH="33%"
ALIGN="right"
ALIGN="right"
VALIGN="top"
VALIGN="top"
>Mail boxes</TD
>Mail boxes</TD
></TR
></TR
></TABLE
></TABLE
></DIV
></DIV
></BODY
></BODY
></HTML
></HTML
 
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.