--- /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
+>Semaphores</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="Condition Variables"
+HREF="kernel-condition-variables.html"><LINK
+REL="NEXT"
+TITLE="Mail boxes"
+HREF="kernel-mail-boxes.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-condition-variables.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+></TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="kernel-mail-boxes.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><H1
+><A
+NAME="KERNEL-SEMAPHORES">Semaphores</H1
+><DIV
+CLASS="REFNAMEDIV"
+><A
+NAME="AEN1330"
+></A
+><H2
+>Name</H2
+>cyg_semaphore_init, cyg_semaphore_destroy, cyg_semaphore_wait, cyg_semaphore_timed_wait, cyg_semaphore_post, cyg_semaphore_peek -- Synchronization primitive</DIV
+><DIV
+CLASS="REFSYNOPSISDIV"
+><A
+NAME="AEN1338"><H2
+>Synopsis</H2
+><DIV
+CLASS="FUNCSYNOPSIS"
+><A
+NAME="AEN1339"><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_semaphore_init</CODE
+>(cyg_sem_t* sem, cyg_count32 val);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_semaphore_destroy</CODE
+>(cyg_sem_t* sem);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>cyg_bool_t cyg_semaphore_wait</CODE
+>(cyg_sem_t* sem);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>cyg_bool_t cyg_semaphore_timed_wait</CODE
+>(cyg_sem_t* sem, cyg_tick_count_t abstime);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>cyg_bool_t cyg_semaphore_trywait</CODE
+>(cyg_sem_t* sem);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_semaphore_post</CODE
+>(cyg_sem_t* sem);</CODE
+></P
+><P
+><CODE
+><CODE
+CLASS="FUNCDEF"
+>void cyg_semaphore_peek</CODE
+>(cyg_sem_t* sem, cyg_count32* val);</CODE
+></P
+><P
+></P
+></DIV
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-SEMAPHORES-DESCRIPTION"
+></A
+><H2
+>Description</H2
+><P
+>Counting semaphores are a <A
+HREF="kernel-overview.html#KERNEL-OVERVIEW-SYNCH-PRIMITIVES"
+>synchronization
+primitive</A
+> that allow threads to wait until an event has
+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
+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
+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
+greater than zero then an attempt to wait on the semaphore will
+consume one event, in other words decrement the counter, and return
+immediately. Posting to a semaphore will wake up the first thread that
+is currently waiting, which will then resume inside the semaphore wait
+operation and decrement the counter again.
+ </P
+><P
+>Another use of semaphores is for certain forms of resource management.
+The counter would correspond to how many of a certain type of resource
+are currently available, with threads waiting on the semaphore to
+claim a resource and posting to release the resource again. In
+practice <A
+HREF="kernel-condition-variables.html"
+>condition
+variables</A
+> are usually much better suited for operations like
+this.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_init</TT
+> is used to initialize a
+semaphore. It takes two arguments, a pointer to a
+<SPAN
+CLASS="STRUCTNAME"
+>cyg_sem_t</SPAN
+> structure and an initial value for
+the counter. Note that semaphore operations, unlike some other parts
+of the kernel API, use pointers to data structures rather than
+handles. This makes it easier to embed semaphores in a larger data
+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
+events have occurred yet.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+> is used by a consumer thread
+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
+counter will be decremented and the call will return immediately.
+Otherwise the current thread will be blocked until there is a
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_post</TT
+> call.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_post</TT
+> is called when an event has
+occurs. This increments the counter and wakes up the first thread
+waiting on the semaphore (if any). Usually that thread will then
+continue running inside <TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+> and
+decrement the counter again. However other scenarioes are possible.
+For example the thread calling <TT
+CLASS="FUNCTION"
+>cyg_semaphore_post</TT
+>
+may be running at high priority, some other thread running at medium
+priority may be about to call <TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+>
+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
+priority thread continues running until it is descheduled for some
+reason, then the medium priority thread runs and its call to
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+> succeeds immediately, and
+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
+threads blocked on a semaphore then the configuration option
+<TT
+CLASS="VARNAME"
+>CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT
+> determines which
+one will be woken up by a post operation.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+> returns a boolean. Normally it
+will block until it has successfully decremented the counter, retrying
+as necessary, and return success. However the wait operation may be
+aborted by a call to <A
+HREF="kernel-thread-control.html"
+><TT
+CLASS="FUNCTION"
+>cyg_thread_release</TT
+></A
+>,
+and <TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+> will then return false.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_timed_wait</TT
+> is a variant of
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+>. It can be used to wait until
+either an event has occurred or a number of clock ticks have happened.
+The function returns success if the semaphore wait operation
+succeeded, or false if the operation timed out or was aborted by
+<TT
+CLASS="FUNCTION"
+>cyg_thread_release</TT
+>. If support for the real-time
+clock has been removed from the current configuration then this
+function will not be available.
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_trywait</TT
+> is another variant which
+will always return immediately rather than block, again returning
+success or failure.
+ </P
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_peek</TT
+> can be used to get hold of the
+current counter value. This function is rarely useful except for
+debugging purposes since the counter value may change at any time if
+some other thread or a DSR performs a semaphore operation.
+ </P
+></DIV
+><DIV
+CLASS="REFSECT1"
+><A
+NAME="KERNEL-SEMAPHORES-CONTEXT"
+></A
+><H2
+>Valid contexts</H2
+><P
+><TT
+CLASS="FUNCTION"
+>cyg_semaphore_init</TT
+> is normally called during
+initialization but may also be called from thread context.
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_wait</TT
+> and
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_timed_wait</TT
+> may only be called from
+thread context because these operations may block.
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_trywait</TT
+>,
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_post</TT
+> and
+<TT
+CLASS="FUNCTION"
+>cyg_semaphore_peek</TT
+> may be called from thread or
+DSR context.
+ </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-condition-variables.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-mail-boxes.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Condition Variables</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="kernel.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Mail boxes</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff