nand-ecoscentric: packages/kernel/current/doc/kernel.sgml annotate

annotate packages/kernel/current/doc/kernel.sgml @ 208:e0c0827131d1 ecos

Merge from eCos master repository on 2002-05-20-20:11:54-BST

author	jlarmour
date	Mon, 20 May 2002 22:19:26 +0000
parents
children	d2c90368aeef

rev	line source
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1 <part ID="kernel">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2 <title>The eCos kernel</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3 <chapter id="ecos-kernel-overview">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	4 <TITLE>eCos kernel overview</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	5 <PARA>This is an overview of the internal workings of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	6 <EMPHASIS>eCos</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	7 <!-- <index></index> -->kernel. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	8 <SECT1 id="kernel-scheduler">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	9 <TITLE><!-- <xref> -->The scheduler</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	10 <PARA>At the core of the kernel is the <!-- <index></index> -->scheduler.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	11 This defines the way in which threads are run, and provides the mechanisms
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	12 by which they may synchronize. It also controls the means by which interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	13 affect thread execution. No single scheduler can cover all possible system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	14 configurations. For different purposes we will need to cover several scheduling
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	15 polices. In this release two schedulers are provided (described
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	16 in more detail in <xref linkend="sched-subdirectory">):</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	17 <ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	18 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	19 <PARA>a <EMPHASIS>bitmap scheduler</EMPHASIS> </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	20 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	21 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	22 <PARA>a <EMPHASIS>multi-level queue scheduler</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	23 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	24 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	25 </ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	26 <PARA>At present the system will only support a single scheduler
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	27 at any one time. Future systems may allow multiple schedulers to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	28 co-exist, but this will be hidden behind the scheduler API in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	29 current release. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	30 <PARA>To make scheduling safe we need a mechanism to protect the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	31 scheduler data structures from concurrent access. The traditional
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	32 approach to this is to disable interrupts during the critical regions.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	33 Unfortunately this increases the maximum interrupt dispatch latency,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	34 which is to be avoided in any real-time system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	35 <PARA>The mechanisms chosen for <EMPHASIS>eCos</EMPHASIS> is to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	36 maintain a counter, <!-- <index></index> --><VARNAME>Scheduler::sched_lock</VARNAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	37 that, if non-zero, prevents any rescheduling. The current thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	38 can claim the lock by calling <!-- <index></index> --><FUNCTION>Scheduler::lock()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	39 This increments the counter and prevents any further scheduling.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	40 The function <!-- <index></index> --><FUNCTION>Scheduler::unlock()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	41 decrements the counter and if it returns to zero, allows scheduling
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	42 to continue. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	43 <PARA>For this to work in the presence of interrupts, it is necessary
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	44 for the <!-- <index></index> -->Interrupt Service Routines (ISR) to defer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	45 any scheduler-oriented operations until the lock is about to go
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	46 zero. We do this by splitting the work of an ISR into two parts,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	47 with the second part, the <!-- <index></index> -->Deferred Service Routine
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	48 (DSR), being queued until the scheduler decides it is safe to run.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	49 This is covered in more detail in <xref linkend="interrupts"> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	50 <xref linkend="interrupt-and-exception-handlers">. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	51 <PARA>On a uni-processor,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	52 <FUNCTION>Scheduler::lock()</FUNCTION> is a simple increment
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	53 of <VARNAME>Scheduler::sched_lock</VARNAME>. It does
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	54 not need to be a read-modify-write cycle since the lock is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	55 strictly nested. The mere fact that the current thread is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	56 running implies that the lock has not been claimed by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	57 another thread, so it is always claimable. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	58 <PARA><FUNCTION>Scheduler::unlock()</FUNCTION> is generic to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	59 all scheduler implementations. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	60 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	61 <SECT1 id="thread-synchronization">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	62 <TITLE>Thread <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	63 synchronization</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	64 <PARA>To allow threads to cooperate and compete for resources,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	65 it is necessary to provide mechanisms for synchronization
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	66 and communication. The classic synchronization mechanisms
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	67 are mutexes/condition variables and semaphores. These
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	68 are provided in the <EMPHASIS>eCos</EMPHASIS> kernel,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	69 together with other synchronization/communication
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	70 mechanisms that are common in real-time systems, such as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	71 event flags and message queues. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	72 <PARA>One of the problems that must be dealt with in any real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	73 systems is <!-- <index></index> -->priority inversion. This is where a high
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	74 priority thread is (wrongly) prevented from continuing by one at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	75 lower priority. The normal example is of a high priority thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	76 waiting at a mutex already held by a low priority thread. If the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	77 low priority thread is preempted by a medium priority thread then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	78 priority inversion has occurred since the high priority thread is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	79 prevented from continuing by an unrelated thread of lower priority.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	80 <PARA>This problem got much attention recently when the Mars Pathfinder
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	81 mission had to reset the computers on the ground exploration robot
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	82 repeatedly because a priority inversion problem would cause it to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	83 hang. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	84 <PARA>There are several solutions to this problem. The simplest
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	85 is to employ a <!-- <index></index> -->priority ceiling protocol where all
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	86 threads that acquire the mutex have their priority boosted to some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	87 predetermined value. This has a number of disadvantages: it requires
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	88 the maximum priority of the threads using the mutex to be known
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	89 in advance; if the ceiling priority is too high it acts as a global
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	90 lock disabling all scheduling and it is pessimistic, taking action
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	91 to prevent the problem even when it does not arise. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	92 <PARA>A better solution is to use <!-- <index></index> -->priority inheritance
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	93 protocol. Here, the priority of the thread that owns the mutex is boosted
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	94 to equal that of the highest priority thread that is waiting for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	95 it. This technique does not require prior knowledge of the priorities
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	96 of the threads that are going to use the mutex, and the priority
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	97 of the owning thread is only boosted when a higher priority thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	98 is waiting. This reduces the effect on the scheduling of other threads,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	99 and is more optimistic than the priority ceiling protocol. A disadvantage
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	100 of this mechanism is that the cost of each synchronization call
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	101 is increased since the inheritance protocol must be obeyed each
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	102 time. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	103 <PARA>A third approach to priority inversion is to recognize that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	104 relative thread priorities have been poorly chosen and thus the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	105 system in which it occurs is faulty. In this case the kernel needs
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	106 the ability to detect when priority inversion has taken place, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	107 to raise an exception when it occurs to aid debugging. Then this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	108 code is removed from the shipping version. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	109 <PARA>The current <EMPHASIS>eCos</EMPHASIS> release provides a relatively
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	110 simple implementation of <!-- <index></index> -->mutex priority inheritance.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	111 This implementation will only work in the multi-level queue scheduler,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	112 and it does not handle the rare case of nested mutexes completely correctly.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	113 However it is both fast and deterministic. Mutex priority inheritance
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	114 can be disabled if the application does not require it. This will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	115 reduce both code size and data space. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	116 <PARA>Future releases will provide alternative implementations of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	117 mutex priority inheritance, and application developers will be able
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	118 to choose the implementation appropriate to their application. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	119 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	120 <SECT1 id="exceptions">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	121 <TITLE>Exceptions</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	122 <PARA>An exception is a synchronous event caused by the execution
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	123 of a thread. These include both the machine exceptions raised by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	124 hardware (such as divide-by-zero, memory fault and illegal instruction)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	125 and machine exceptions raised by software (such as deadline overrun).
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	126 The standard C++ exception mechanism is too expensive
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	127 to use for this, and in any case has the wrong semantics for the exception
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	128 handling in an RTOS. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	129 <PARA>The simplest, and most flexible, mechanism for <!-- <index></index> -->exception
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	130 handling is to call a function. This function needs context in which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	131 to work, so access to some working data is required. The function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	132 may also need to be handed some data about the exception raised:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	133 at least the exception number and some optional parameters. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	134 <PARA>The exception handler receives a data argument which is a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	135 value that was registered with the handler and points to context
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	136 information. It also receives an exception_number which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	137 identifies the exception taken, and an error code which contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	138 any additional information (such as a memory fault address) needed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	139 to handle the exception. Returning from the function will allow
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	140 the thread to continue. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	141 <PARA>Exception handlers may be either global or per-thread, or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	142 both, depending on configuration options. If exceptions are per-thread,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	143 it is necessary to have an exception handler attached to each thread. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	144 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	145 <SECT1 id="interrupts">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	146 <TITLE><!-- <xref> -->Interrupts</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	147 <PARA>Interrupts are asynchronous events caused by external devices.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	148 They may occur at any time and are not associated in any way with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	149 the thread that is currently running. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	150 <PARA>The <!-- <index></index> -->handling of interrupts is one of the more
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	151 complex areas in RTOS design, largely because it is the least well
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	152 defined. The ways in which interrupt vectors are named, how interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	153 are delivered to the software and how interrupts are masked are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	154 all highly architecture- (and in some cases board-) specific. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	155 approach taken in <emphasis>eCos</emphasis> is to provide a generalized mechanism
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	156 with sufficient hooks for system-specific code to be inserted where
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	157 needed. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	158 <PARA>Let us start by considering the issue of interrupt vectors.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	159 Hardware support differs greatly here: from the Intel Architecture
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	160 and the 680X0 having support for vectoring individual interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	161 to their own vectors, to most RISC architectures that only have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	162 a single vector. In the first case it is possible to attach an ISR directly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	163 to the vector and know that it need only concern itself with the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	164 device in question. In the second case it is necessary to determine
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	165 which device is actually interrupting and then vector to the correct
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	166 ISR. Where there is an external interrupt controller, it will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	167 possible to query that and provide what is essentially a software
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	168 implementation of hardware vectoring. Otherwise the actual hardware devices
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	169 must be tested, by calling the ISRs in turn and letting them make
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	170 the determination. Since it is possible for two devices to interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	171 simultaneously, it is necessary to call all ISRs each time an interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	172 occurs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	173 <PARA>Interrupt masking has a similar variety of support. Most processors
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	174 have a simple interrupt mask bit in a status register. The 680X0
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	175 has seven levels of masking. Any board with a interrupt controller
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	176 can be programmed to provide similar multi-level masking. It is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	177 necessary to keep the interrupt masking mechanism simple and efficient,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	178 and use only architectural support. The cost of manipulating an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	179 on-board interrupt controller may be too high. However, individual
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	180 device drivers may want access to their individual mask bits in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	181 the interrupt controller, so support for this must be provided. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	182 <PARA>Most of the infrastructure necessary for a (somewhat) portable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	183 treatment of interrupts is implemented in the <EMPHASIS>eCos</EMPHASIS> Hardware
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	184 Abstraction Layer (HAL), which is documented in <xref linkend="the-ecos-hardware-abstraction-layer">. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	185 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	186 <SECT1 id="counters-clocks-alarms-and-timers">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	187 <TITLE>Counters, clocks, alarms and timers</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	188 <PARA>If the hardware provides a periodic clock or timer, it will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	189 be used to drive timing-related features of the system. Many CPU
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	190 architectures now have built in timer registers that can provide
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	191 a periodic interrupt. This should be used to drive these features
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	192 where possible. Otherwise an external timer/clock chip
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	193 must be used. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	194 <PARA>We draw a distinction between Counters, Clocks, Alarms and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	195 Timers. A <!-- <index></index> -->Counter maintains a monotonically increasing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	196 counter that is driven by some source of ticks. A <!-- <index></index> -->Clock
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	197 is a counter driven by a regular source of ticks (i.e. it counts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	198 time). Clocks have a <FIRSTTERM>resolution</FIRSTTERM> associated with them.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	199 A default system Clock is driven by the periodic interrupt described
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	200 above, and tracks real-time. Other interrupt sources may drive other
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	201 Counters that may or may not track real-time at different resolutions.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	202 Some Counters may be driven by aperiodic events and thus have no relation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	203 to real-time at all. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	204 <PARA>An <!-- <index></index> -->Alarm is attached to a Counter and provides
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	205 a mechanism for generating single-shot or periodic events based
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	206 on the counter's value. A <!-- <index></index> -->Timer is simply
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	207 an Alarm that is attached to a Clock. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	208 <PARA>The system (including the kernel) represents time in units
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	209 of <EMPHASIS>ticks</EMPHASIS>. These are clock-specific time units
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	210 and are usually the period of the timer interrupt, or a multiple
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	211 thereof. Conversion of ticks into conventional time and date units
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	212 should occur only when required via library functions. Equivalence
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	213 between Clock time and real-time can be made with an <!-- <index></index> -->RTC
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	214 (real-time clock), <!-- <index></index> -->NTP (network time protocol) or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	215 user input. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	216 <PARA>The representation of the current tick count needs to be 64
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	217 bit. This requires either compiler support for 64 bit integers,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	218 or assembly code. Even at the extreme of a 1 ns tick (ticks will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	219 typically be >1ms), this gives a 584 year rollover period. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	220 <PARA>The Clock API and configuration options that affect clock,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	221 counter and alarm behavior are described in detail in <xref linkend="counters-clocks-and-alarms">. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	222 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	223 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	224 <CHAPTER id="tour-of-kernel-sources">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	225 <TITLE>A tour of the kernel sources</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	226 <PARA>This description takes the form of a tour around the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	227 sources explaining their structure and describing the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	228 functionality of each component. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	229 <PARA>The kernel is divided into two basic parts, the largely machine
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	230 independent parts in <filename>packages/kernel/&versiondir;</FILENAME>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	231 and the architecture- and platform-specific parts that comprise
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	232 the Hardware Abstraction Layer (HAL) in <filename>packages/hal</filename>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	233 These will be described separately. Also note that the HAL is described
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	234 in great detail in its own chapter (<xref
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	235 linkend="the-ecos-hardware-abstraction-layer">). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	236 <SECT1 id="kernel-headers">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	237 <TITLE><!-- <index></index> -->Kernel headers</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	238 <PARA>Kernel header files (in <FILENAME>packages/kernel/&versiondir;/include</FILENAME>)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	239 provide external interfaces and configuration control for the various
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	240 kernel objects. In general there is an include file for each major
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	241 kernel class. Those header files having to do with configuration
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	242 live in the <FILENAME>pkgconf</FILENAME> subdirectory. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	243 <PARA>The base name of a header file and the source file that implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	244 it are usually the same. So, for example, the member functions defined
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	245 in <FILENAME>sched.hxx</FILENAME> are implemented in <FILENAME>sched.cxx</FILENAME>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	246 For a number of classes there are also header files that define
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	247 inline functions, for example <FILENAME>sched.inl</FILENAME>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	248 <PARA>There are some kernel objects that are implemented using C++ templates
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	249 to allow code re-use in future; it is not intended that these template
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	250 classes be used generally by applications. The appropriate concrete
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	251 kernel classes should be used instead. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	252 <PARA>Now we examine the files one by one for reference: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	253 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	254 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	255 <TERM><FILENAME>include/bitmap.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	256 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	257 <PARA>Bitmap scheduler definition. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	258 <FILENAME>sched/bitmap.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	259 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	260 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	261 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	262 <TERM><FILENAME>include/clock.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	263 <TERM><FILENAME>include/clock.inl</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	264 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	265 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	266 <PARA>Counter, clock and alarm functions. See source
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	267 file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	268 <FILENAME>common/clock.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	269 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	270 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	271 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	272 <TERM><FILENAME>include/diag.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	273 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	274 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	275
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	276 <PARA>Diagnostic routines. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	277 <FILENAME>trace/diag.c</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	278 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	279 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	280 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	281 <TERM><FILENAME>include/errors.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	282 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	283 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	284
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	285 <PARA>Kernel error codes. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	286 <FILENAME>common/except.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	287 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	288 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	289 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	290 <TERM><FILENAME>include/except.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	291 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	292 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	293
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	294 <PARA>Exception handling.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	295 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	296 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	297 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	298 <TERM><FILENAME>include/flag.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	299 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	300 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	301
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	302 <PARA>Flag synchronization objects. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	303 <FILENAME>sync/flag.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	304 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	305 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	306 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	307 <TERM><FILENAME>include/instrmnt.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	308 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	309 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	310
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	311 <PARA>Instrumentation. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	312 <FILENAME>instrmnt/meminst.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	313 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	314 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	315 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	316 <TERM><FILENAME>include/intr.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	317 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	318 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	319
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	320 <PARA>Interrupts. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	321 <FILENAME>intr/intr.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	322 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	323 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	324 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	325 <TERM><FILENAME>include/kapi.h</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	326 <TERM><FILENAME>include/kapidata.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	327 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	328 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	329 <PARA>Native 'C' API to the kernel. See source
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	330 file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	331 <FILENAME>common/kapi.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	332 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	333 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	334 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	335 <TERM><FILENAME>include/ktypes.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	336 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	337 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	338
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	339 <PARA>Kernel types.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	340 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	341 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	342 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	343 <TERM><FILENAME>include/llistt.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	344 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	345 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	346
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	347 <PARA>A simple doubly linked-list template class used elsewhere
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	348 in the kernel.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	349 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	350 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	351 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	352 <TERM><FILENAME>include/lottery.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	353 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	354 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	355
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	356 <PARA>Lottery scheduler implementation. (Not used). See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	357 <FILENAME>sched/lottery.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	358 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	359 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	360 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	361 <TERM><FILENAME>include/mbox.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	362 <TERM><FILENAME>include/mboxt.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	363 <TERM><FILENAME>include/mboxt2.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	364 <TERM><FILENAME>include/mboxt.inl</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	365 <TERM><FILENAME>include/mboxt2.inl</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	366 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	367 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	368
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	369 <PARA>Message boxes. See source file <FILENAME>sync/mbox.cxx</FILENAME>; <FILENAME>mboxt.hxx</FILENAME> and <FILENAME>mboxt2.hxx</FILENAME> and <FILENAME>mboxt.inl</FILENAME> and <FILENAME>mboxt2.inl</FILENAME> implement
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	370 the underlying template function.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	371 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	372 <PARA>The files with a 2 suffix are used by default and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	373 provide precise µITRON semantics.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	374 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	375 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	376 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	377 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	378 <TERM><FILENAME>include/memfixed.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	379 <TERM><FILENAME>include/mempoolt.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	380 <TERM><FILENAME>include/mempolt2.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	381 <TERM><FILENAME>include/mempoolt.inl</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	382 <TERM><FILENAME>include/mempolt2.inl</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	383 <TERM><FILENAME>include/mfiximpl.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	384 <TERM><FILENAME>include/mfiximpl.inl</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	385 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	386 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	387
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	388 <PARA>Fixed-block allocation memory pools. See source file <FILENAME>mem/memfixed.cxx</FILENAME>;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	389 mempoolt[2] and mfiximpl are a thread-safety template
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	390 function and underlying memory manager respectively.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	391 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	392 <PARA>The files with a 2 suffix are used by default and provide
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	393 precise µITRON semantics.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	394 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	395 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	396 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	397 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	398 <TERM><FILENAME>include/memvar.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	399 <TERM><FILENAME>include/mempoolt.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	400 <TERM><FILENAME>include/mempolt2.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	401 <TERM><FILENAME>include/mempoolt.inl</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	402 <TERM><FILENAME>include/mempolt2.inl</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	403 <TERM><FILENAME>include/mvarimpl.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	404 <TERM><FILENAME>include/mvarimpl.inl</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	405 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	406 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	407 <PARA>Variable-block allocation memory pools. See source file <FILENAME>mem/memvar.cxx</FILENAME>;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	408 mempoolt[2] and mvar are a thread-safety template
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	409 function and underlying memory manager respectively.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	410 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	411 <PARA>The files with a 2 suffix are used by default and provide
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	412 precise µITRON semantics.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	413 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	414 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	415 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	416 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	417 <TERM><FILENAME>include/mlqueue.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	418 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	419 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	420
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	421 <PARA>Multi-level queue scheduler. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	422 <FILENAME>sched/mlqueue.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	423 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	424 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	425 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	426 <TERM><FILENAME>include/mutex.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	427 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	428 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	429
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	430 <PARA>Mutexes. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	431 <FILENAME>sync/mutex.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	432 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	433 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	434 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	435 <TERM><FILENAME>include/sched.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	436 <TERM><FILENAME>include/sched.inl</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	437 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	438 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	439 <PARA>General scheduler functions. See source file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	440 <FILENAME>sched/sched.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	441 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	442 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	443 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	444 <TERM><FILENAME>include/sema.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	445 <TERM><FILENAME>include/sema2.hxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	446 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	447 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	448 <PARA>Semaphores. See source files <FILENAME>sync/cnt_sem.cxx</FILENAME> and <FILENAME>sync/bin_sem.cxx</FILENAME> for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	449 counting or binary semaphores respectively.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	450 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	451 <PARA>The file with a 2 suffix is used by default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	452 and provides precise µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	453 semantics.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	454 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	455 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	456 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	457 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	458 <TERM><FILENAME>include/thread.hxx</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	459 <TERM><FILENAME>include/thread.inl</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	460 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	461 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	462 <PARA>Threads, regardless of scheduler. See
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	463 <FILENAME>common/thread.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	464 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	465 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	466 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	467 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	468 <SECT1 id="kernel-source-files">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	469 <TITLE><!-- <index></index> --> Kernel source files</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	470 <PARA>The kernel source directory (<FILENAME>packages/kernel/&versiondir;/src</FILENAME>)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	471 is divided into a number of sub-directories each containing the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	472 source files for a particular kernel subsystem. These sources divide
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	473 into two classes: those that are generic to all configurations,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	474 and those that are specific to a particular configuration. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	475 <SECT2 id="sched-subdirectory">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	476 <TITLE><!-- <index></index> --><!-- <xref> -->Sched subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	477 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	478 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	479 <TERM><FILENAME>sched/sched.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	480 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	481 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	482 <PARA> </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	483 <PARA>This contains the implementation of the base
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	484 scheduler classes. The most important function here
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	485 is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	486 <FUNCTION>Cyg_Scheduler::unlock_inner()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	487 which runs DSRs and performs any rescheduling and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	488 thread switching.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	489 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	490 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	491 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	492 <TERM><FILENAME>sched/bitmap.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	493 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	494 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	495
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	496 <PARA>This contains the bitmap scheduler implementation. It represents
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	497 each runnable thread with a bit in a bitmap. Each thread must have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	498 a unique priority and there is a strict upper limit on the number
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	499 of threads allowed.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	500 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	501 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	502 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	503 <TERM><FILENAME>sched/mlqueue.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	504 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	505 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	506
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	507 <PARA>This contains the multi-level queue scheduler implementation.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	508 It implements a number of thread priorities and is capable of timeslicing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	509 between threads at the same priority. This scheduler can also support
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	510 priority inheritance.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	511 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	512 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	513 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	514 <TERM><FILENAME>sched/lottery.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	515 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	516 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	517
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	518 <PARA>This contains a lottery scheduler implementation. This implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	519 a CPU share scheduler based on threads holding a number of lottery
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	520 tickets. At the start of each time quantum, a random number is generated
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	521 and the thread holding the matching ticket is scheduled. Compensation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	522 tickets and ticket donation allow fair sharing for I/O
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	523 bound threads and an equivalent mechanism to priority
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	524 inheritance.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	525 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	526 <PARA>This scheduler is experimental, and is meant to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	527 test the behavior of other parts of the kernel with a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	528 non-orthodox scheduler. It is not meant to be used for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	529 real applications. It is currently under development and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	530 is incomplete and unusable.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	531 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	532 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	533 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	534 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	535 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	536 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	537 <TITLE><!-- <index></index> --> Common subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	538 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	539 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	540 <TERM><FILENAME>common/thread.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	541 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	542 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	543 <PARA> </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	544 <PARA>This implements the basic thread classes. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	545 functions in this file implement the basic thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	546 controls to sleep and wake threads, change
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	547 priorities and delay and time-out. Also defined here
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	548 is the idle thread that runs when there is nothing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	549 else to do.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	550 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	551 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	552 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	553 <TERM><FILENAME>common/clock.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	554 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	555 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	556
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	557 <PARA>This implements the counter, clock and alarm functions. Also
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	558 defined here is the system real-time clock that is used to drive
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	559 timeslicing, delays and time-outs.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	560 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	561 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	562 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	563 <TERM><FILENAME>common/kapi.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	564 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	565 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	566
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	567 <PARA>This implements a C API to the basic kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	568 functions.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	569 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	570 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	571 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	572 <TERM><FILENAME>common/memcpy.c</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	573 <TERM><FILENAME>common/memset.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	574 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	575 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	576 <PARA>Standard ANSI memcpy and memset operations; these are here
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	577 because the compiler may invoke them for structure operations regardless
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	578 of the presence of a C library.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	579 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	580 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	581 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	582 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	583 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	584 <TITLE><!-- <index></index> --> Interrupt subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	585 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	586 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	587 <TERM><FILENAME>intr/intr.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	588 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	589 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	590
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	591 <PARA>This implements the Interrupt class. Most of this code is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	592 concerned with posting and calling DSRs. The remainder of the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	593 handling code is machine specific and is in <FILENAME>hal_intr.cxx</FILENAME> in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	594 the HAL directory.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	595 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	596 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	597 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	598 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	599 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	600 <TITLE><!-- <index></index> -->Synchronization subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	601 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	602 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	603 <TERM><FILENAME>sync/mutex.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	604 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	605 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	606
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	607 <PARA>This contains the implementation of mutexes and condition
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	608 variables. Mutexes can optionally be configured to use a priority
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	609 inheritance mechanism supplied by the scheduler.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	610 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	611 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	612 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	613 <TERM><FILENAME>sync/cnt_sem.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	614 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	615 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	616
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	617 <PARA>This contains the implementation of counting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	618 semaphores.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	619 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	620 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	621 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	622 <TERM><FILENAME>sync/cnt_sem2.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	623 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	624 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	625
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	626 <PARA>This contains the alternate implementation of counting semaphores
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	627 which implements precise µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	628 semantics.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	629 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	630 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	631 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	632 <TERM><FILENAME>sync/bin_sem.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	633 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	634 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	635
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	636 <PARA>This contains the implementation of binary
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	637 semaphores.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	638 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	639 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	640 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	641 <TERM><FILENAME>sync/mbox.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	642 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	643 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	644
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	645 <PARA>This contains wrapper functions for a message box of (void *)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	646 values. The implementation is the template defined in <FILENAME>include/mboxt.hxx</FILENAME> which <FILENAME>include/mboxt.inl</FILENAME> implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	647 in turn. Message boxes exist in the kernel specifically to support µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	648 compatibility.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	649 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	650 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	651 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	652 <TERM><FILENAME>sync/flag.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	653 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	654 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	655
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	656 <PARA>This contains the implementation of flag objects. Flag objects
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	657 exist in the kernel specifically to support µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	658 compatibility.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	659 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	660 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	661 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	662 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	663 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	664 <TITLE><!-- <index></index> -->Memory management subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	665 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	666 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	667 <TERM><FILENAME>mem/memfixed.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	668 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	669 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	670
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	671 <PARA>This contains the wrapper functions for a fixed-block allocation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	672 memory manager. The actual implementation is in two parts: <FILENAME>include/mfiximpl.hxx</FILENAME> implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	673 the fixed-block memory management algorithms, and template <FILENAME>include/mempoolt.hxx</FILENAME> implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	674 thread safety and waiting for memory management classes. These are combined
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	675 in <FILENAME>memfixed.cxx</FILENAME>. Memory pools exist
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	676 in the kernel specifically to support µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	677 compatibility.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	678 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	679 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	680 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	681 <TERM><FILENAME>mem/memvar.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	682 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	683 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	684
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	685 <PARA>This contains the wrapper functions for a variable-block allocation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	686 memory manager. The actual implementation is in two parts: <FILENAME>include/mvarimpl.hxx</FILENAME> implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	687 the variable-block memory management algorithms, and template <FILENAME>include/mempoolt.hxx</FILENAME> implements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	688 thread safety and waiting for memory management classes. These are combined
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	689 in <FILENAME>memvar.cxx</FILENAME>. Memory pools exist
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	690 in the kernel specifically to support µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	691 compatibility.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	692 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	693 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	694 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	695 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	696 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	697 <TITLE><!-- <index></index> -->Instrumentation subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	698 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	699 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	700 <TERM><FILENAME>instrmnt/meminst.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	701 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	702 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	703
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	704 <PARA>This contains an implementation of the instrumentation mechanism
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	705 that stores instrumentation records in a circular buffer in memory.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	706 The size of this buffer is configurable. The instrumentation flags
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	707 mechanism allows the generation of instrumentation records to be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	708 controlled on a per-record basis. The header file <FILENAME>cyg/kernel/instrmnt.h</FILENAME> contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	709 macros to generate instrumentation records in various places, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	710 may be configured to only generate instrumentation records where
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	711 required.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	712 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	713 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	714 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	715 <TERM><FILENAME>instrmnt/nullinst.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	716 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	717 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	718
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	719 <PARA>This contains an implementation of the instrumentation mechanism
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	720 that does nothing. By substituting its object file <FILENAME>nullinst.o</FILENAME> for <FILENAME>meminst.o</FILENAME> in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	721 a build, the instrumentation mechanism may be disabled without
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	722 recompiling.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	723 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	724 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	725 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	726 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	727 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	728 <TITLE><!-- <index></index> -->Trace subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	729 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	730 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	731 <TERM><FILENAME>trace/simple.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	732 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	733 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	734
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	735 <PARA>This contains an implementation of the trace and assert mechanisms
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	736 that output textual messages via a set of externally defined functions.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	737 These are currently supplied by the code in <FILENAME>trace/diag.c</FILENAME> but
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	738 may be supplied by a device driver in the future.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	739 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	740 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	741 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	742 <TERM><FILENAME>trace/fancy.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	743 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	744 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	745
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	746 <PARA>This contains a (fancier) implementation of the trace and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	747 assert mechanisms that output textual messages via a set of externally
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	748 defined functions. These are currently supplied by the code in <FILENAME>trace/diag.c</FILENAME> but
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	749 may be supplied by a device driver in the future.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	750 <PARA>This more elaborate view was introduced mainly to validate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	751 the trace and assertion macros during development. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	752 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	753 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	754 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	755 <TERM><FILENAME>trace/null.cxx</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	756 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	757 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	758
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	759 <PARA>This contains an implementation of the trace and assert mechanisms
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	760 that do nothing. By substituting its object file <FILENAME>null.o</FILENAME> for <FILENAME>simple.o</FILENAME> in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	761 a build, the trace mechanisms may be disabled without
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	762 recompiling.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	763 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	764 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	765 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	766 <TERM><FILENAME>trace/diag.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	767 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	768 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	769
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	770 <PARA>This contains a number of diagnostic routines that use the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	771 HAL supplied diagnostic output mechanism to format and print strings
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	772 and numbers. There is currently no formatted output.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	773 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	774 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	775 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	776 <TERM><FILENAME>trace/tcdiag.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	777 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	778 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	779
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	780 <PARA>This contains an implementation of the testing internal API
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	781 which uses the kernel's diagnostic routines to perform
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	782 output.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	783 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	784 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	785 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	786 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	787 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	788 <TITLE><!-- <index></index> -->Sload subdirectory</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	789 <PARA>This contains the sources of a simple S-Record loader that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	790 may be used in a ROM for various microprocessor development boards
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	791 to download code via a serial port.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	792 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	793 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	794 <TITLE><!-- <index></index> -->HAL source files</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	795 <PARA>The HAL is divided into architecture- and platform-specific
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	796 files. For each architecture supported, there is an <FILENAME>arch</FILENAME> directory,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	797 containing files generic to that architecture, and a <FILENAME>platform</FILENAME> directory,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	798 containing files specific to each platform supported.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	799 <PARA>Amongst the architectures supported are: the PowerPC, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	800 Tx39 and the MN10300. To find the code corresponding to each architecture,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	801 substitute “powerpc”, “mips” and “mn10300”,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	802 respectively, for “ARCH” in the following file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	803 descriptions. Similarly substitute the appropriate platform name
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	804 representing your development board for “PLATFORM”.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	805 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	806 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	807 <TITLE><!-- <index></index> -->Architecture files</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	808 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	809 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	810 <TERM><FILENAME>ARCH/arch/&versiondir;/include/basetype.h</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	811 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	812
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	813 <PARA>This file is used to define the base architecture configuration
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	814 such as endianness and word size.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	815 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	816 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	817 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	818 <TERM><FILENAME>ARCH/arch/&versiondir;/include/hal_arch.h</FILENAME></TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	819 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	820
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	821 <PARA>This file contains macros that implement various architecture-specific
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	822 functions. The most important macros here are the thread context
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	823 initialization and switch macros that are used to implement
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	824 multithreading.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	825 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	826 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	827 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	828 <TERM><FILENAME>ARCH/arch/&versiondir;/include/hal_intr.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	829 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	830 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	831
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	832 <PARA>This file contains the HAL support for interrupt management
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	833 and clock support.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	834 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	835 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	836 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	837 <TERM><FILENAME>ARCH/arch/&versiondir;/include/hal_io.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	838 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	839 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	840
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	841 <PARA>This file contains the HAL support for accessing hardware
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	842 registers. It provides a portable API that allows more generic device
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	843 drivers to be written.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	844 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	845 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	846 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	847 <TERM><FILENAME>ARCH/arch/&versiondir;/include/hal_cache.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	848 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	849 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	850
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	851 <PARA>This file contains macros to control any caches that may be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	852 present.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	853 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	854 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	855 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	856 <TERM><FILENAME>ARCH/arch/&versiondir;/include/ARCH_stub.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	857 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	858 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	859
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	860 <PARA>This file contains architectural information for a GDB stub,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	861 such as the register layout in a GDB packet.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	862 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	863 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	864 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	865 <TERM><FILENAME>ARCH/arch/&versiondir;/src/vectors.S</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	866 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	867 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	868
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	869 <PARA>This is an assembly code file that contains the code to handle
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	870 interrupt and exception vectors. Since system reset can also be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	871 considered an exception, this is handled here also. Interrupts are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	872 currently handled by placing a stub routine in the hardware vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	873 which calls a Vector Service Routine via an indirection table. There
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	874 is a API to allow user-defined VSRs to be installed. The default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	875 VSR reads the interrupt controller registers and decodes the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	876 source into an offset into a further table of interrupt service
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	877 routines. It also handles interrupt cleanup, which may result in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	878 the execution of deferred service routines (DSRs) and the preemption of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	879 the current thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	880 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	881 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	882 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	883 <TERM><FILENAME>ARCH/arch/&versiondir;/src/context.S</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	884 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	885 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	886
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	887 <PARA>If present, this is an assembly code file that contains the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	888 code to support thread contexts. The routines to switch between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	889 various contexts, as well as initialize a thread context may be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	890 present in this file.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	891 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	892 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	893 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	894 <TERM><FILENAME>ARCH/arch/&versiondir;/src/hal_misc.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	895 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	896 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	897
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	898 <PARA>This file contains the implementation of various miscellaneous
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	899 HAL routines that are needed by the kernel or C++
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	900 runtime.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	901 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	902 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	903 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	904 <TERM><FILENAME>ARCH/arch/&versiondir;/src/ARCH_stub.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	905 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	906 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	907
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	908 <PARA>This file contains the architectural part of a GDB stub. This
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	909 deals with CPU-specific details of the stub, such as the setting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	910 of breakpoints and translating exception data into signals that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	911 GDB understands.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	912 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	913 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	914 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	915 <TERM><FILENAME>ARCH/arch/&versiondir;/src/ARCH.ld</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	916 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	917 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	918
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	919 <PARA>This file is the linker script. During preprocessing it includes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	920 linker script fragments that define the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	921 layout.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	922 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	923 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	924 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	925 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	926 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	927 <TITLE><!-- <index></index> -->Platform files</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	928 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	929 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	930 <TERM><FILENAME>ARCH/PLATFORM/&versiondir;/include/hal_diag.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	931 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	932 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	933
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	934 <PARA>This file contains the definitions of macros that support
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	935 the HAL diagnostic output mechanism.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	936 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	937 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	938 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	939 <TERM><FILENAME>ARCH/PLATFORM/&versiondir;/include/plf_stub.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	940 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	941 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	942
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	943 <PARA>This file contains a set of macros that allow the common GDB
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	944 stub code to access the platform-specific minimal serial driver
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	945 functions.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	946 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	947 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	948 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	949 <TERM><FILENAME>ARCH/PLATFORM/&versiondir;/src/hal_diag.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	950 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	951 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	952
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	953 <PARA>This file contain the implementation of the HAL diagnostic
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	954 output mechanism.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	955 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	956 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	957 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	958 <TERM><FILENAME>ARCH/PLATFORM/&versiondir;/src/plf_stub.c</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	959 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	960 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	961
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	962 <PARA>This file contains a minimal serial driver for the target
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	963 platform that is used by the GDB stub.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	964 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	965 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	966 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	967 <TERM><FILENAME>ARCH/PLATFORM/&versiondir;/src/PLATFORM.S</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	968 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	969 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	970
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	971 <PARA>This is an assembler file that contains any platform-specific
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	972 code. It often contains platform initialization code called from
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	973 vectors.S.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	974 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	975 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	976 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	977 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	978 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	979 </chapter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	980 <CHAPTER id="requirements-for-programs">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	981 <TITLE>Requirements for programs</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	982 <PARA><EMPHASIS>eCos</EMPHASIS> <!-- <index></index> -->programs do not have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	983 to satisfy any unusual requirements, but there are always some differences
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	984 between a program written for a real-time operating system as opposed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	985 to one written for a time sharing, virtual memory system like UNIX
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	986 or Windows NT.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	987 <PARA>This chapter contains checklist of things to remember when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	988 writing <EMPHASIS>eCos</EMPHASIS> programs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	989 <SECT1 id="cyg-user-start">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	990 <TITLE><!-- <index></index> -->cyg_user_start()</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	991 <PARA>The entry point for <EMPHASIS>eCos</EMPHASIS> user programs
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	992 is usually <FUNCTION>cyg_user_start()</FUNCTION> instead
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	993 of <FUNCTION>main()</FUNCTION>, although <FUNCTION>main()</FUNCTION> <EMPHASIS>can</EMPHASIS> be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	994 used if the ISO C library package is selected. Complete detail on
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	995 the start-up sequence is given in <xref linkend="system-start-up">. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	996 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	997 <SECT1 id="necessary-headers">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	998 <TITLE>Necessary headers</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	999 <PARA>Any program which uses <EMPHASIS>eCos</EMPHASIS> system calls
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1000 must have the following line at the top of the file:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1001 <PROGRAMLISTING>#include <cyg/kernel/kapi.h><!-- <index></index> --></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1002 <PARA>and the programmer must make sure that <FILENAME>cyg/kernel/kapi.h</FILENAME> is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1003 available in the compiler include path. This can be done by setting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1004 the <EMPHASIS>C_INCLUDE_PATH</EMPHASIS> environment
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1005 variable or by including the <EMPHASIS>-I </EMPHASIS>flag on the compiler
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1006 command line. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1007 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1008 <SECT1 id="necessary-link-instructions">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1009 <TITLE>Necessary link instructions</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1010 <PARA>The <EMPHASIS>eCos</EMPHASIS> configuration and building process
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1011 (described in <EMPHASIS>Getting Started with </EMPHASIS><PRODUCTNAME>eCos</PRODUCTNAME> and <PRODUCTNAME>eCos</PRODUCTNAME><EMPHASIS> User's
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1012 Guide</EMPHASIS>) builds a single library, <FILENAME>libtarget.a</FILENAME>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1013 which contains the selected <EMPHASIS>eCos</EMPHASIS> components.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1014 The <FILENAME>libtarget.a</FILENAME> library does <EMPHASIS>not</EMPHASIS> contain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1015 any user libraries: If you put some of your source in libraries,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1016 you will have to explicitly include those libraries in the linking instruction. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1017 <PARA>You also need to link to the <EMPHASIS>GNU C Compiler</EMPHASIS> runtime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1018 support library (<FILENAME>libgcc.a</FILENAME>).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1019 <PARA>You should <EMPHASIS>not</EMPHASIS> link to the standard C++ library.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1020 This can be achieved with the <EMPHASIS>-nostdlib</EMPHASIS> option.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1021 <PARA>You should only link to <FILENAME>libtarget.a</FILENAME> and <FILENAME>libgcc.a</FILENAME> using
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1022 the linker script <FILENAME>target.ld</FILENAME> provided
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1023 with <EMPHASIS>eCos</EMPHASIS>. The command line for linking should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1024 look like </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1025 <screen>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1026 gcc [options] [object files] -Ttarget.ld -nostdlib
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1027 </screen>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1028 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1029 <SECT1 ID="INTERRUPT-AND-EXCEPTION-HANDLERS">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1030 <TITLE><!-- <xref> -->Interrupt and exception handlers</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1031 <PARA>In <EMPHASIS>eCos</EMPHASIS> a distinction is made between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1032 <EMPHASIS>exceptions</EMPHASIS> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1033 <EMPHASIS>interrupts</EMPHASIS>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1034 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1035 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1036 <TERM><!-- <index></index> -->exceptions </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1037 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1038
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1039 <PARA>are the result of some action by the currently executing code.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1040 Examples of exceptions are divide by zero, illegal instruction,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1041 bad memory access, etc.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1042 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1043 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1044 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1045 <TERM><!-- <index></index> -->interrupts </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1046 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1047
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1048 <PARA>are the result of a signal source which is conceptually asynchronous
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1049 with the currently executing code. Examples of interrupts sources
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1050 are the real-time clock, external and on chip peripherals and so
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1051 forth. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1052 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1053 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1054 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1055 <PARA>This distinction is made in the <EMPHASIS>eCos</EMPHASIS> hardware
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1056 abstraction layer (HAL) to provide a cleaner and more portable mechanism
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1057 for installing interrupt handlers and exception handlers. Individual hardware
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1058 platforms can have different ways of naming and handling interrupts, which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1059 is why this abstraction layer was chosen. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1060 <PARA>Interrupts and exceptions are both associated with <!-- <index></index> -->vectors,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1061 which are labeled by vector numbers (<xref
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1062 linkend="exception-handling"> and <xref
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1063 linkend="interrupt-handling">).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1064 <PARA>There are distinct spaces for exception and interrupt vectors.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1065 These are called “exception vector numbers” and “interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1066 vector numbers”. System calls which install exception handlers
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1067 use the exception vector number, and the system calls which install
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1068 interrupt handlers use the interrupt vector number to specify which interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1069 or exception should be handled by the handler.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1070 <PARA>The details of the vector layout depend on the microprocessor
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1071 and interrupt controller, and are documented in the relevant API
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1072 sections.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1073 <PARA>Interrupt handlers are actually a <EMPHASIS>pair</EMPHASIS> of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1074 functions, one of which (the <EMPHASIS>interrupt service routine</EMPHASIS>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1075 or ISR) is executed immediately and runs with that interrupt disabled.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1076 Since interrupts are disabled for the duration of the ISR, the ISR
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1077 should be very brief and should not use any system services.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1078 <PARA>After the ISR exits, but before the kernel scheduler is invoked
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1079 again, a <EMPHASIS>delayed service routine</EMPHASIS> (DSR) will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1080 be invoked. It executes with scheduling disabled, but with interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1081 enabled, so that further invocations of the same DSR can be queued.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1082 The DSR can use some producer-side system calls, but it should be carefully
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1083 crafted to avoid using any call that might put its thread to sleep.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1084 One of the few examples of safe calls is <!-- <index></index> --><FUNCTION>cyg_semaphore_post()</FUNCTION>;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1085 the non-blocking versions of some system calls are also safe. A
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1086 call that is unsafe is <!-- <index></index> --><FUNCTION>cyg_mutex_lock()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1087 since it will block if the mutex is already locked by another thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1088 <PARA>Finally, <EMPHASIS>eCos</EMPHASIS> has a formalism for installing <EMPHASIS>low
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1089 level handlers</EMPHASIS> which bypass the kernel mechanisms described
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1090 above. A program can install a <!-- <index></index> --><FIRSTTERM>vector service routine</firstterm> (VSR)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1091 which will be invoked instead of the kernel's usual exception
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1092 or interrupt handling. The VSR will typically be written in assembly language. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1093 <PARA>VSRs are associated with vector numbers in the exception space,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1094 just like exception handlers (although there are some variations — architectures
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1095 in which there are no exceptions in the <EMPHASIS>eCos</EMPHASIS> sense).
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1096 The main difference between VSRs and exception handlers is that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1097 VSRs bypass the kernel's usual mechanisms. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1098 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1099 <SECT1 id="memory-allocation">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1100 <TITLE><!-- <index></index> -->Memory allocation</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1101 <PARA>Most <EMPHASIS>eCos</EMPHASIS> system calls expect you to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1102 pass the address of pre-allocated memory for the objects created
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1103 in that system call. This is frequently the preferred way of doing things
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1104 for embedded applications, where programmers want to allocate all
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1105 memory statically and have fine control over that resource.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1106 <PARA>In contrast, some <EMPHASIS>eCos</EMPHASIS> system calls also
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1107 allow a NULL pointer to be passed. In such a case the kernel will allocate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1108 the memory or select default size. This feature is not supported
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1109 in the current release, and a warning flag is placed in the documentation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1110 for those routines (like
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1111 <FUNCTION>cyg_thread_create()</FUNCTION>). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1112 <PARA><EMPHASIS>eCos</EMPHASIS> provides dynamic memory allocation,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1113 based on <EMPHASIS>memory pools</EMPHASIS>, a useful and flexible
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1114 approach to memory management inspired by the µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1115 compatibility layer. These are described in <xref linkend="memory-pools">.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1116 <PARA>If you configure your system to use the Standard C Library
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1117 you can also use the standard <FUNCTION>malloc()</FUNCTION> library
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1118 call. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1119 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1120 <SECT1 id="assertions-and-bad-param-handling">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1121 <TITLE>Assertions and bad parameter handling</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1122 <PARA>This section describes how the <EMPHASIS>eCos</EMPHASIS> kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1123 and basic packages behave when system calls are invoked with bad parameters.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1124 <PARA>In <EMPHASIS>eCos</EMPHASIS>, the basic kernel assertion behavior
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1125 is configuration-dependent.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1126 <PARA>By default, <!-- <index></index> -->assertions are turned off in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1127 kernel. If the kernel is configured to turn them <EMPHASIS>on</EMPHASIS>, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1128 kernel will make basic assertions, such as checking for invalid
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1129 parameters when system calls are invoked. If an assertion fails,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1130 the kernel will print a message to the diagnostic output channel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1131 and stop executing.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1132 <PARA>If the kernel is configured with assertions disabled (usually
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1133 when the application has been thoroughly debugged), it will not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1134 do any checking. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1135 <PARA>The configuration sections referenced above also describe
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1136 the use of preconditions, postconditions and loop invariants. These
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1137 are no different from ordinary assertions, but they are used in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1138 specialized circumstances, and the programmer would wish to select
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1139 their presence individually. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1140 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1141 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1142 <CHAPTER id="system-start-up">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1143 <TITLE><!-- <xref> -->System start-up</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1144 <PARA>We describe here the steps performed by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1145 <EMPHASIS>eCos</EMPHASIS> upon start-up, mentioning how a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1146 programmer can introduce custom start-up routines. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1147 <SECT1 id="system-startup-hal">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1148 <TITLE>System start-up — the HAL</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1149 <PARA>The HAL (Hardware Abstraction Layer, see <xref linkend="the-ecos-hardware-abstraction-layer">)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1150 is the <EMPHASIS>eCos</EMPHASIS> package which contains all <!-- <index></index> -->start-up
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1151 code. Its start-up procedure is outlined in detail in <xref linkend="hal-startup">, but the main steps
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1152 can be summarized here:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1153 <ORDEREDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1154 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1155 <PARA> The HAL initializes the hardware, coordinates with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1156 the ROM monitor, and performs diagnostics.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1157 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1158 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1159 <PARA>The HAL invokes all static and global
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1160 C++ constructors. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1161 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1162 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1163 <PARA>The HAL jumps to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1164 <FUNCTION>cyg_start()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1165 which has the following prototype:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1166 <PROGRAMLISTING>void cyg_start( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1167 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1168 </ORDEREDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1169 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1170 <SECT1 id="system-startup-cyg-start">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1171 <TITLE>System start-up — cyg_start()</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1172 <PARA><!-- <index></index> --><FUNCTION>cyg_start()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1173 is the core
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1174 of the <!-- <index></index> -->start-up mechanism. The default definition
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1175 is in <FILENAME>infra/current/src/startup.cxx</FILENAME></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1176 <PARA>It calls, in turn, </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1177 <PROGRAMLISTING>cyg_prestart()
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1178 cyg_package_start()
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1179 cyg_user_start()</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1180 <PARA>and then starts the <EMPHASIS>eCos</EMPHASIS> scheduler if
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1181 the system has been configured to have a kernel and scheduler.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1182 <PARA>You can override the default <FUNCTION>cyg_start()</FUNCTION> routine
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1183 by providing your own function by the same name with the following prototype: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1184 <PROGRAMLISTING>void cyg_start( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1185 <WARNING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1186 <PARA>Overriding <FUNCTION>cyg_start()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1187 should rarely, if ever, be done. The functions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1188 <FUNCTION>cyg_prestart()</FUNCTION> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1189 <FUNCTION>cyg_user_start()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1190 described just below allow enough flexibility for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1191 installing user initialization code safely for almost all
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1192 applications.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1193 </WARNING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1194 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1195 <PARA> If you are supplying your own definition of this function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1196 from a C++ file, make sure it has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1197 “C” linkage.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1198 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1199 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1200 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1201 <SECT1 id="system-startup-cyg-prestart">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1202 <TITLE>System startup — cyg_prestart()</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1203 <PARA>The default <!-- <index></index>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1204 --><FUNCTION>cyg_prestart()</FUNCTION> function does
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1205 not do anything; it is meant to be overwritten if the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1206 programmer needs to do any initialization
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1207 <EMPHASIS>before</EMPHASIS> other system level
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1208 initialization.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1209 <PARA>You can override the default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1210 <FUNCTION>cyg_prestart()</FUNCTION> routine by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1211 providing your own function by the same name with the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1212 following prototype: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1213 <PROGRAMLISTING>void cyg_prestart( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1214 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1215 <PARA> If you are supplying your own definition of this function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1216 from a C++ file, make sure it has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1217 “C” linkage.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1218 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1219 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1220 <SECT1 id="system-startup-cyg-package-start">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1221 <TITLE>System startup — cyg_package_start()</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1222 <PARA>The <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1223 <FUNCTION>cyg_package_start()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1224 allows individual packages to do their initialization before
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1225 the main user program is invoked.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1226 <PARA>Two of the packages shipped with this release of <EMPHASIS>eCos</EMPHASIS> have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1227 code in the default <FUNCTION>cyg_package_start()</FUNCTION>;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1228 the µITRON and the ISO standard C
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1229 library compatibility packages (<xref linkend="compat-uitron-microitron-api"> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1230 <xref linkend="c-and-math-library-overview">). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1231 <PARA>The infrastructure package has configuration options CYGSEM_START_UITRON_COMPATIBILITY
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1232 and CYGSEM_START_ISO_C_COMPATIBILITY
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1233 which control specialized initialization.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1234 <PARA>You can override the default <FUNCTION>cyg_package_start()</FUNCTION> routine
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1235 by providing your own function by the same name with the following prototype: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1236 <PROGRAMLISTING>void cyg_package_start( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1237 <PARA>but you should be careful to initialize the default packages
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1238 (if you are using them). An example user-supplied function might
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1239 look like:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1240 <PROGRAMLISTING> void cyg_package_start(void)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1241 {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1242 #ifdef CYGSEM_START_UITRON_COMPATABILITY
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1243 cyg_uitron_start(); /* keep the µITRON initialization */
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1244 #endif
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1245 my_package_start(); /* make sure I initialize my package */
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1246 }</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1247 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1248 <PARA>If you are supplying your own definition of this function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1249 from a C++ file, make sure it has “C” linkage.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1250 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1251 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1252 <SECT1 id="system-startup-cyg-user-start">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1253 <TITLE>System startup — cyg_user_start()</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1254 <PARA>This is the normal entry point for your code. Although a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1255 default empty version is provided by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1256 <EMPHASIS>eCos</EMPHASIS>, this is a good place to set up
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1257 your threads (<xref linkend="thread-operations">).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1258 <PARA>If you are not including the ISO standard C library
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1259 package then there will not be a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1260 <FUNCTION>main()</FUNCTION> function, so it becomes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1261 mandatory to provide this function (<xref linkend="c-library-startup">).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1262 <PARA>To set up your own <!-- <index></index> --><FUNCTION>cyg_user_start()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1263 function, create a function by that name with the following prototype:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1264 <PROGRAMLISTING>void cyg_user_start( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1265 <PARA>When you return control from
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1266 <FUNCTION>cyg_user_start()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1267 <FUNCTION>cyg_start()</FUNCTION> will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1268 then invoke the scheduler, and any threads you created and resumed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1269 in <FUNCTION>cyg_user_start()</FUNCTION> will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1270 be executed. The preferred approach is to allow the scheduler to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1271 be started automatically, rather than to start it explicitly in <FUNCTION>cyg_user_start()</FUNCTION>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1272 <CAUTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1273 <PARA>Remember that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1274 <FUNCTION>cyg_user_start()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1275 is invoked before the scheduler (and frequently the scheduler is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1276 invoked as the last step in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1277 <FUNCTION>cyg_user_start()</FUNCTION>), so it should not use any
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1278 kernel services that require the scheduler.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1279 </CAUTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1280 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1281 <PARA> If you are supplying your own definition of this function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1282 from a C++ file, make sure it has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1283 “C” linkage.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1284 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1285 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1286 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1287 <CHAPTER id="native-kernel-c-language-api">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1288 <TITLE>Native kernel C language API</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1289 <PARA>The <EMPHASIS>eCos</EMPHASIS> kernel, like many other
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1290 real-time kernels, is a library to which the programmer links
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1291 an application. System calls resemble library API calls, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1292 there is no trap mechanism to switch from user to system mode.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1293 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1294 <PARA>We present here the <EMPHASIS>eCos</EMPHASIS> <!-- <index></index> -->kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1295 API and the APIs for other kernels provided as compatibility layers
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1296 on top of eC<EMPHASIS>os</EMPHASIS>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1297 <PARA>Since this API sits on top of a configurable system, the semantics
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1298 are only weakly defined. The exact semantics and even the API itself
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1299 depend on the configuration. For example if returned error codes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1300 were supported this would change the prototype of the functions.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1301 The semantics given in this chapter describe the default configuration.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1302 <PARA>As mentioned above, all source files which use the kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1303 C API should have the following <computeroutput>#include</computeroutput> statement:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1304 <PROGRAMLISTING>#include <cyg/kernel/kapi.h></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1305 <PARA>at the head of the file. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1306 <SECT1 id="kapi-types">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1307 <TITLE>Types used in programming eCos</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1308 <PARA>We now describe the types defined for use with <EMPHASIS>eCos</EMPHASIS>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1309 These are available to programs that include <filename>kapi.h</filename>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1310 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1311 <PARA>Most of these types are meant to be <EMPHASIS>opaque</EMPHASIS> — in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1312 other words, programmers do not need to know (and probably should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1313 not know) how they are defined. But the types that are numeric are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1314 marked, since it can be useful to use comparison operators.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1315 <PARA>The definitions for these types can be found in the installed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1316 tree, in the file <filename>include/cyg/kernel/kapi.h</filename>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1317 <PARA>The <EMPHASIS>eCos</EMPHASIS> kernel uses the following naming
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1318 convention for types: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1319 <ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1320 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1321 <PARA>Types that can be treated as completely opaque usually
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1322 have _t suffix.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1323 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1324 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1325 <PARA>Types for which it is necessary to know the implementation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1326 do not have a _t suffix.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1327 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1328 </ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1329 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1330 <TITLE><!-- <index></index> -->cyg_addrword_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1331 <PARA>A type which is large enough to store the larger of an address
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1332 and a machine word. This is used for convenience when a function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1333 is passed data which could be either a pointer to a block of data
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1334 or a single word. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1335 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1336 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1337 <TITLE><!-- <index></index> -->cyg_handle_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1338 <PARA>A <EMPHASIS>handle</EMPHASIS> is a variable used to refer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1339 to <EMPHASIS>eCos</EMPHASIS> system objects (such as a thread or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1340 an alarm). Most <EMPHASIS>eCos</EMPHASIS> system calls that create
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1341 system objects will return a handle that is used to access that
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1342 object from then on.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1343 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1344 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1345 <TITLE><!-- <index></index> -->cyg_priority_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1346 <PARA>A numeric type used to represent the priority of a thread,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1347 or the priority of an interrupt level. A lower number means a higher
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1348 (i.e. more important) priority thread. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1349 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1350 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1351 <TITLE><!-- <index></index> -->cyg_code_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1352 <PARA>A numeric type used for various error or status codes, such
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1353 as exception numbers.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1354 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1355 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1356 <TITLE><!-- <index></index> -->cyg_vector_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1357 <PARA>A numeric type used to identify an interrupt vector. Its value
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1358 is called the interrupt vector <EMPHASIS>id</EMPHASIS>. This type
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1359 is used for both ISR vector ids and VSR vector ids.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1360 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1361 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1362 <TITLE><!-- <index></index> -->cyg_tick_count_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1363 <PARA>A numeric type used to count counter ticks. The resolution
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1364 and other details regarding tick quantities depend on the configuration,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1365 but this is a 64 bit type, and no matter what configuration is chosen
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1366 it should still last for centuries before it overflows.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1367 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1368 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1369 <TITLE><!-- <index></index> -->cyg_bool_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1370 <PARA>A boolean type whose values can be false (0) or true (1).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1371 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1372 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1373 <TITLE><!-- <index></index> -->cyg_thread_entry_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1374 <PARA>A function type for functions that are entry points for threads.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1375 It is used in the thread creation call <FUNCTION>cyg_thread_create()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1376 <PARA>To help write thread entry point functions, here is how cyg_thread_entry_t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1377 is defined:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1378 <PROGRAMLISTING>typedef void cyg_thread_entry_t(void *);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1379 <PARA>Examples of thread functions can be found in the programming
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1380 tutorial in <EMPHASIS>Getting Started with </EMPHASIS><PRODUCTNAME>eCos</PRODUCTNAME>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1381 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1382 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1383 <TITLE><!-- <index></index> -->cyg_exception_handler_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1384 <PARA>A function type used for installing exception handlers. It
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1385 is defined as: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1386 <PROGRAMLISTING>typedef void cyg_exception_handler_t(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1387 cyg_addrword_t data,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1388 cyg_code_t exception_number,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1389 cyg_addrword_t info
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1390 );</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1391 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1392 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1393 <TITLE><!-- <index></index> -->cyg_thread, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1394 cyg_interrupt, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1395 cyg_counter, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1396 cyg_clock, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1397 cyg_alarm, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1398 cyg_mbox, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1399 cyg_mempool_var, and <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1400 cyg_mempool_fix</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1401 <PARA>These types are of the appropriate size to contain the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1402 used by the respective kernel objects. These types are only used
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1403 in the corresponding create call where the programmer allocates
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1404 the memory for the object and passes the address to the kernel.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1405 After creation the provided handle is used to reference the object.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1406 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1407 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1408 <TITLE><!-- <index></index> -->cyg_mempool_info</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1409 <PARA>Contains information about a memory pool. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1410 <PROGRAMLISTING>typedef struct {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1411 cyg_int32 totalmem;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1412 cyg_int32 freemem;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1413 void *base;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1414 cyg_int32 size;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1415 cyg_int32 blocksize;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1416 cyg_int32 maxfree; // The largest free block
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1417 } cyg_mempool_info;</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1418 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1419 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1420 <TITLE><!-- <index></index> -->cyg_sem_t, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1421 cyg_mutex_t, and <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1422 cyg_cond_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1423 <PARA>These types are of the appropriate size to contain the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1424 used by their respective kernel objects. These objects are always
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1425 referred to by a pointer to an object of this type.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1426 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1427 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1428 <TITLE><!-- <index></index> -->cyg_VSR_t, <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1429 cyg_ISR_t, and <!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1430 cyg_DSR_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1431 <PARA>These are function types used when vector, interrupt and delayed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1432 service routines are installed. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1433 <PROGRAMLISTING>typedef void cyg_VSR_t();
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1434 typedef cyg_uint32 cyg_ISR_t(cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1435 cyg_addrword_t data);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1436 typedef void cyg_DSR_t(cyg_uint32 vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1437 cyg_ucount32 count,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1438 cyg_addrword_t data);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1439 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1440 <SECT2 id="cyg-resolution-t">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1441 <TITLE><!-- <index></index> --><!-- <xref> -->cyg_resolution_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1442 <PARA>Stores the resolution of a clock. The resolution is defined
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1443 to be (dividend/divisor) nanoseconds per tick. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1444 <PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1445 typedef struct { cyg_uint32 dividend; cyg_uint32 divisor; }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1446 cyg_resolution_t;</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1447 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1448 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1449 <TITLE><!-- <index></index> -->cyg_alarm_t</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1450 <PARA>The function type used for alarm handlers. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1451 <PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1452 typedef void cyg_alarm_t(cyg_handle_t alarm,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1453 cyg_addrword_t data);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1454 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1455 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1456 <SECT1 id="thread-operations">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1457 <TITLE><!-- <index></index> --><!-- <xref> -->Thread operations</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1458 <PROGRAMLISTING>void cyg_scheduler_start( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1459 <PARA>Starts the scheduler with the threads that have been created.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1460 It never returns. The scheduler has been chosen at configuration
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1461 time. <EMPHASIS>eCos</EMPHASIS> currently ships with three schedulers:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1462 a bitmap scheduler, a multi-level scheduler (selected by default),
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1463 and an experimental “lottery” scheduler which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1464 is currently incomplete and unusable.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1465 <PARA>The configuration tool can be used to select between schedulers.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1466 The configuration options are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1467 CYGSEM_SCHED_BITMAP, CYGSEM_SCHED_MLQUEUE
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1468 and CYGSEM_SCHED_LOTTERY.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1469 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1470 <PARA> Interrupts are not enabled until the scheduler has been
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1471 started with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1472 <FUNCTION>cyg_scheduler_start()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1473 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1474 <PROGRAMLISTING>void cyg_scheduler_lock( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1475 <PARA>Locks the scheduler so that a context switch cannot occur.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1476 This can be used to protect data shared between a thread and a DSR,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1477 or between multiple threads, by surrounding the critical region
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1478 with <FUNCTION>cyg_scheduler_lock()</FUNCTION> and <FUNCTION>cyg_scheduler_unlock()</FUNCTION>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1479 <PROGRAMLISTING>void cyg_scheduler_unlock( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1480 <PARA>Unlocks the scheduler so that context switching can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1481 occur again.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1482 <PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1483 void <!-- <index></index> -->cyg_thread_create(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1484 cyg_addrword_t sched_info,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1485 cyg_thread_entry_t *entry,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1486 cyg_addrword_t entry_data,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1487 char *name,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1488 void *stack_base,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1489 cyg_ucount32 stack_size,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1490 cyg_handle_t *handle,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1491 cyg_thread *thread )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1492 <PARA>Creates a thread in a suspended state. The thread will not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1493 run until it has been resumed with <FUNCTION>cyg_thread_resume()</FUNCTION> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1494 the scheduler has been started with <FUNCTION>cyg_scheduler_start()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1495 <PARA>Here is a description of the parameters of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1496 <FUNCTION>cyg_thread_create()</FUNCTION>:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1497 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1498 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1499 <TERM>sched_info</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1500 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1501
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1502 <PARA>Information to be passed to the scheduler. For almost all
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1503 schedulers this is a simple priority value, and you can simply pass
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1504 a non-negative integer when you create the thread. Even when this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1505 holds, some schedulers may have restrictions on how priorities can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1506 be used. For example, the bitmap scheduler can onlyhave one thread at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1507 each priority, so if an already-occupied priority slot is quoted,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1508 the next free slot of lower priority is chosen.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1509 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1510 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1511 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1512 <TERM>entry </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1513 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1514
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1515 <PARA>A user-supplied function: it is a routine that begins execution
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1516 of the new thread. This function takes a single argument of type
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1517 cyg_addrword_t, which is usually a pointer to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1518 a block of data, which allows <FUNCTION>cyg_scheduler_start()</FUNCTION> to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1519 pass data to this particular thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1520 <PARA>Here is a typedef for the entry function: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1521 <PROGRAMLISTING>typedef void cyg_thread_entry_t(cyg_addrword_t);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1522 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1523 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1524 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1525 <TERM>entry_data </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1526 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1527
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1528 <PARA>A data value passed to the entry function. This may be either
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1529 a machine word datum or the address of a block of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1530 data.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1531 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1532 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1533 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1534 <TERM>name </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1535 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1536
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1537 <PARA>A C string with the name of this thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1538 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1539 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1540 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1541 <TERM>stack_base </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1542 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1543
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1544 <PARA>The address of the stack base. If this value is NULL then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1545 <FUNCTION>cyg_thread_create()</FUNCTION> will choose a stack
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1546 base.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1547 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1548 <PARA>Passing a stack base of NULL is not supported in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1549 this release. You must pass a real address for the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1550 stack base.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1551 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1552 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1553 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1554 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1555 <TERM>stack_size</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1556 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1557
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1558 <PARA>The size of the stack for this thread. If this is 0, the default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1559 stack size will be used for this thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1560 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1561 <PARA>Passing a stack size of 0 is not supported in this release.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1562 You must pass a real stack size.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1563 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1564 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1565 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1566 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1567 <TERM>handle </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1568 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1569
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1570 <PARA><FUNCTION>cyg_thread_create()</FUNCTION> returns
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1571 the thread handle in this location.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1572 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1573 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1574 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1575 <TERM>thread </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1576 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1577
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1578 <PARA>The thread housekeeping information is placed in the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1579 pointed to by this parameter. If this pointer is NULL then the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1580 will be allocated. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1581 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1582 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1583 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1584 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1585 <PARA>Passing a NULL value for the thread data structure
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1586 address is not supported in this release. You must pass a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1587 valid address. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1588 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1589 <PROGRAMLISTING>void cyg_thread_exit( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1590 <PARA>Exits the current thread. At present this simply puts the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1591 thread into suspended state.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1592 <PROGRAMLISTING>void cyg_thread_suspend ( cyg_handle_t thread )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1593 <PARA>Suspends the thread. A thread may be suspended multiple times,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1594 in which case it will need to be resumed the same number of times
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1595 before it will run. A thread can suspend itself; the effect will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1596 be that the call does not return until some other thread has resumed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1597 it. Obviously this can only be done once!</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1598 <PARA>It is OK for a thread to suspend other threads with the scheduler
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1599 locked; it will continue to run until the scheduler is unlocked.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1600 However, a thread suspending itself with the scheduler locked is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1601 in danger of causing problems within the system because a suspended
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1602 thread has been removed from its run-queue, even if it continues
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1603 to execute! The problematic situation cannot be detected because
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1604 it is OK for a DSR (ie. alarm function for example) to suspend
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1605 a thread - possibly the current thread if that is what happened
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1606 to be running, and DSRs run with the scheduler locked.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1607 <PARA>If you see an assert referring to something like "Queue map
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1608 bit not set for pri" it is likely that this means a thread has suspended
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1609 itself with the scheduler locked. The simplest workaround is: never
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1610 let a thread suspend itself; look for that behaviour in your code. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1611 <PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1612 void cyg_thread_resume ( cyg_handle_t thread )
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1613 </PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1614 <PARA>Resumes <emphasis>thread</emphasis>. If a thread has been suspended multiple times
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1615 it will need to be resumed the same number of times before it will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1616 run. Threads are created in a suspended state and must be resumed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1617 before they will run.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1618 <PROGRAMLISTING>void cyg_thread_yield ( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1619 <PARA>Yields control to the next runnable thread of equal
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1620 priority. If no such thread exists, then this function has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1621 no effect.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1622 <PROGRAMLISTING>void cyg_thread_kill ( cyg_handle_t thread )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1623 <PARA>Kills <emphasis>thread</emphasis>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1624 <PROGRAMLISTING>cyg_bool_t cyg_thread_delete( cyg_handle_t thread)</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1625 <PARA>Kills <EMPHASIS>thread</EMPHASIS> and deletes it from the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1626 scheduler. If necessary, it will kill <EMPHASIS>thread</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1627 first using <FUNCTION>cyg_thread_kill( thread )</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1628 If <EMPHASIS>thread</EMPHASIS> does not terminate in response to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1629 the kill message, this function returns false, indicating failure.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1630 <PARA>This function differs from <FUNCTION>cyg_thread_kill()</FUNCTION> (or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1631 calling <FUNCTION>cyg_thread_exit()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1632 for the current thread) by deregistering the thread from the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1633 scheduler. As a result, the thread handle, thread stack and space
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1634 passed for the thread housekeeping information can then be reused.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1635 This is not the case if just <FUNCTION>cyg_thread_kill()</FUNCTION> or <FUNCTION>cyg_thread_exit()</FUNCTION> is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1636 invoked for the thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1637 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1638 <PARA><FUNCTION>cyg_thread_delete()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1639 only deregisters the thread from the scheduler, it does not free
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1640 up any resources that had been allocated by the thread such as dynamic
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1641 memory, nor does it unlock any synchronization objects owned by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1642 the thread. This is the responsibility of the programmer. Additionally,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1643 unlike
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1644 <FUNCTION>cyg_thread_kill()</FUNCTION>, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1645 <FUNCTION>cyg_thread_delete()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1646 function cannot be self-referencing.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1647 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1648 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1649 <PROGRAMLISTING>// Delete another thread. This must be done in a loop, waiting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1650 // for the call to return true. If it returns false, go to sleep
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1651 // for a while, so that the killed thread gets a chance to run
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1652 // and complete its business.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1653 while (!cyg_thread_delete(<thread_handle>) {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1654 cyg_thread_delay(1);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1655 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1656 <PROGRAMLISTING> cyg_handle_t cyg_thread_self( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1657 <PARA>Returns the handle of the current thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1658 <PROGRAMLISTING>void cyg_thread_release ( cyg_handle_t thread )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1659 <PARA>Break the thread out of any wait it is currently in.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1660 Exactly how the thread returns from the wait operation, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1661 how, if at all, the break is indicated, depends on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1662 synchronization object it was waiting on.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1663 <PROGRAMLISTING>cyg_ucount32 cyg_thread_new_data_index ( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1664 <PARA>Allocates a new per-thread data index from those still
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1665 available. If no more indexes are available, and assertions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1666 are enabled, an assertion will be raised.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1667 <PROGRAMLISTING>void cyg_thread_free_data_index ( cyg_ucount32 index )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1668 <PARA>Return the per-thread data index to the pool.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1669 <PROGRAMLISTING>CYG_ADDRWORD cyg_thread_get_data( cyg_ucount32 index )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1670 <PARA>Retrieve the per-thread data at the given index for the current
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1671 thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1672 <PROGRAMLISTING>CYG_ADDRWORD *cyg_thread_get_data_ptr( cyg_ucount32 index )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1673 <PARA>Return a pointer to the per-thread data at the given index
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1674 for the current thread. This should be used with some care since
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1675 in some future implementation the per-thread data may be managed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1676 by a dynamic mechanism that might invalidate this pointer at any
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1677 time. This pointer should only be considered valid until the next call
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1678 to the per-thread data functions.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1679 <PROGRAMLISTING>void cyg_thread_set_data( cyg_ucount32 index, CYG_ADDRWORD data )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1680 <PARA>Store the data in the per-thread data for the current thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1681 at the given index.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1682 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1683 <SECT1 id="priority-manipulation">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1684 <TITLE><!-- <index></index> -->Priority manipulation</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1685 <PROGRAMLISTING>void cyg_thread_set_priority( cyg_handle_t thread, cyg_priority_t priority )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1686 <PARA>Sets the priority of the given thread to the given value.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1687 The smaller the value, the higher the priority of the thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1688 <PARA>Allowed priorities range between 1 and 64. The values of these
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1689 parameters are configuration-dependent because they depend on which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1690 scheduler has been selected, and what value has been configured
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1691 for the CYGNUM_KERNEL_SCHED_PRIORITIES
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1692 configuration parameter (<xref linkend="thread-operations">).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1693 <PARA>There is always an idle thread, owned by the kernel, running
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1694 at CYG_THREAD_MIN_PRIORITY. Because of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1695 this, ordinary threads should never be run at the lowest priority. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1696 <PROGRAMLISTING>cyg_priority_t cyg_thread_get_priority( cyg_handle_t thread )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1697 <PARA>Returns the priority of the given thread.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1698 <PROGRAMLISTING>void cyg_thread_delay( cyg_tick_count_t delay )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1699 <PARA>Puts the current thread to sleep for <emphasis>delay</emphasis> ticks. In a default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1700 configuration there are approximately 100 ticks a second. The actual
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1701 length of the ticks is given by the resolution of the real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1702 clock. <xref linkend="counters-clocks-and-alarms"> for more
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1703 information on counter resolution. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1704 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1705 <SECT1 id="exception-handling">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1706 <TITLE><!-- <index></index> --><!-- <xref> -->Exception handling</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1707 <PARA>Exception handlers can be installed to deal with various system-level
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1708 exceptions, such as alignment errors, resets, timers and so forth.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1709 Exception handling is a configurable feature of <EMPHASIS>eCos</EMPHASIS> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1710 is enabled by default.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1711 <PARA>The range of values for the exception_number parameter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1712 in the functions below is hardware-dependent, as are the individual
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1713 exceptions. See <filename>hal/ARCH/arch/&versiondir;/include/hal_intr</filename> for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1714 the exception vector definitions specific to a given architecture. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1715 <PARA>The exception handler is a function of the following type: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1716 <PROGRAMLISTING>typedef void cyg_exception_handler_t(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1717 cyg_addrword_t data,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1718 cyg_code_t exception_number,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1719 cyg_addrword_t info
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1720 );</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1721 <PARA>cyg_exception_handler_t is the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1722 type used for functions which are called as a result of an exception.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1723 It is used in the function <FUNCTION>cyg_exception_set_handler()</FUNCTION>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1724 <PROGRAMLISTING>void cyg_exception_set_handler(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1725 cyg_code_t exception_number,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1726 cyg_exception_handler_t *new_handler,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1727 cyg_addrword_t new_data, cyg_exception_handler_t **old_handler,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1728 void **old_data
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1729 )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1730 <PARA>Replace current exception handler. This may apply to either
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1731 the thread, or to a global exception handler, according to how exception
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1732 handling was configured (global or per-thread). The exception may
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1733 be ignored, or used to specify a particular handler.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1734 <PROGRAMLISTING>void cyg_exception_call_handler (
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1735 cyg_handle_t thread,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1736 cyg_code_t exception_number,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1737 cyg_addrword_t exception_info
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1738 )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1739 <PARA>Invoke exception handler for the given exception number. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1740 exception handler will be invoked with <emphasis>exception_info</emphasis> as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1741 its third argument.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1742 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1743 <SECT1 id="interrupt-handling">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1744 <TITLE><!-- <index></index> --><!-- <xref> -->Interrupt handling</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1745 <PARA>Interrupt handling is by nature machine-specific. The <EMPHASIS>eCos</EMPHASIS> kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1746 aims to provide efficiency and flexibility in this area, while maintaining
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1747 a very low interrupt latency. To allow the programmer direct access
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1748 to hardware, the semantics and the interface can vary from one architecture
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1749 to another.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1750 <PARA>The interrupt vectors for a given architecture are defined
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1751 in <filename>hal/ARCH/arch/&versiondir;/include/hal_intr.h</filename> where
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1752 also special semantics and caveats of the interrupt capabilities
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1753 would be described.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1754 <PROGRAMLISTING>typedef void cyg_VSR_t();
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1755 typedef cyg_uint32 cyg_ISR_t(cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1756 cyg_addrword_t data);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1757 typedef void cyg_DSR_t(cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1758 cyg_ucount32 count,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1759 cyg_addrword_t data);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1760
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1761 enum cyg_ISR_results
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1762 {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1763 CYG_ISR_HANDLED = 1, /* Interrupt was handled */
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1764 CYG_ISR_CALL_DSR = 2 /* Schedule DSR */
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1765 }; </PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1766 <PROGRAMLISTING>void cyg_interrupt_create(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1767 cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1768 cyg_priority_t priority,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1769 cyg_addrword_t data,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1770 cyg_ISR_t *isr,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1771 cyg_DSR_t *dsr,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1772 cyg_handle_t *handle,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1773 cyg_interrupt *intr
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1774 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1775 <PARA>Creates an interrupt object and returns a handle to it. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1776 object contains information about which interrupt vector to use
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1777 and the ISR and DSR that will be called after the interrupt object
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1778 is attached. The interrupt object will be allocated in the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1779 passed in the <emphasis>intr</emphasis> parameter. The interrupt object is not immediately attached;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1780 it must be attached with the <FUNCTION>cyg_interrupt_attach()</FUNCTION> call.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1781 <PROGRAMLISTING>void cyg_interrupt_delete(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1782 cyg_handle_t interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1783 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1784 <PARA>Detaches the <emphasis>interrupt</emphasis> from the vector and frees the corresponding
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1785 memory.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1786 <PROGRAMLISTING>void cyg_interrupt_attach(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1787 cyg_handle_t interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1788 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1789 <PARA>Attaches <emphasis>interrupt</emphasis>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1790 <PROGRAMLISTING>void cyg_interrupt_detach(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1791 cyg_handle_t interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1792 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1793 <PARA>Detaches <emphasis>interrupt</emphasis>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1794 <PROGRAMLISTING>void cyg_interrupt_get_vsr(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1795 cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1796 cyg_VSR_t **vsr
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1797 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1798 <PARA>Returns a pointer to the VSR currently installed on <emphasis>vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1799 </emphasis>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1800 <PROGRAMLISTING>void cyg_interrupt_set_vsr(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1801 cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1802 cyg_VSR_t *vsr
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1803 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1804 <PARA>Sets the current VSR on <emphasis>vector</emphasis>. A VSR directly attaches to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1805 the hardware interrupt vector and needs to be written in assembler.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1806 <PROGRAMLISTING>void cyg_interrupt_disable( void )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1807 <PARA>Disables all interrupts.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1808 <PROGRAMLISTING>void cyg_interrupt_enable( void )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1809 <PARA>Enables all interrupts.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1810 <PROGRAMLISTING>void cyg_interrupt_mask(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1811 cyg_vector_t vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1812 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1813 <PARA>Programs the interrupt controller to stop delivery of interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1814 on <emphasis>vector</emphasis>. On some architectures this will also disable all lower
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1815 priority interrupts while on others they remain enabled. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1816 <PROGRAMLISTING>void cyg_interrupt_mask_intunsafe(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1817 cyg_vector_t vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1818 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1819 <PARA>Programs the interrupt controller to stop delivery of interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1820 on <emphasis>vector</emphasis>. On some architectures this will also disable all lower
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1821 priority interrupts while on others they remain enabled.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1822 This version differs from cyg_drv_interrupt_unmask in not being interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1823 safe.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1824 <PROGRAMLISTING>void cyg_interrupt_unmask(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1825 cyg_vector_t vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1826 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1827 <PARA>Programs the interrupt controller to allow delivery of interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1828 on the given interrupt vector. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1829 <PROGRAMLISTING>void cyg_interrupt_unmask_intunsafe(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1830 cyg_vector_t vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1831 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1832 <PARA>Programs the interrupt controller to allow delivery of interrupts
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1833 on the given interrupt vector.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1834 This version differs from cyg_drv_interrupt_unmask in not being interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1835 safe. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1836 <PROGRAMLISTING>void cyg_interrupt_acknowledge(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1837 cyg_vector_t vector
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1838 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1839 <PARA>Should be used from inside an ISR to acknowledge receipt of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1840 the interrupt. The interrupt must be acknowledged. If an interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1841 is not acknowledged, the interrupt may trigger immediately after
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1842 the ISR returns, causing the ISR to be called again in a loop. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1843 <PROGRAMLISTING>void cyg_interrupt_configure(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1844 cyg_vector_t vector,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1845 cyg_bool_t level,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1846 cyg_bool_t up )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1847 <PARA>On some interrupt controllers the way an interrupt is detected
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1848 may be configured. The <emphasis>level</emphasis> parameter chooses between level- or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1849 edge-triggered interrupts. The <emphasis>up</emphasis> parameter chooses between high
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1850 and low level for level triggered interrupts or rising and falling
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1851 edges for edge triggered interrupts. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1852 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1853 <SECT1 id="counters-clocks-and-alarms">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1854 <TITLE><!-- <xref> -->Counters, clocks and alarms</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1855 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1856 <TITLE><!-- <index></index> -->Counters</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1857 <PARA>The counter objects provided by the kernel provide an abstraction
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1858 of the clock facility that is generally provided. Application code
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1859 can associate alarms with counters, where an alarm is identified
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1860 by the number of ticks until it triggers, the action to be taken
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1861 on triggering, and whether or not the alarm should be repeated. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1862 <PARA>There are two different implementations of the counter objects.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1863 The first stores all alarms in a single linked list. The alternative
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1864 implementation uses a table of linked lists, with the size of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1865 table being a separate configurable option. A single list is more
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1866 efficient in terms of memory usage and is generally adequate when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1867 the application only makes use of a small number of alarms. For
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1868 more complicated operations it is better to have a table of lists
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1869 since this reduces the amount of computation whenever the timer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1870 goes off. Assuming a table size of 8 (the default value) on average
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1871 the timer code will only need to check 1/8 of the pending
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1872 alarms instead of all of them.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1873 <PARA>The configuration options which select the counter implementation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1874 are CYGIMP_KERNEL_COUNTERS_MULTI_LIST
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1875 (“Option: Implement counters using a table of lists”)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1876 and CYGIMP_KERNEL_COUNTERS_SINGLE_LIST
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1877 (“Option: Implement counters using a single list”). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1878 <PARA>The following functions can be used to create and manipulate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1879 counters:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1880 <PROGRAMLISTING>void cyg_counter_create(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1881 cyg_handle_t *counter,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1882 cyg_counter *the_counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1883 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1884 <PARA>Creates a new counter and places it in the space pointed to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1885 by <emphasis>counter</emphasis>. A counter stores a value that is incremented by <FUNCTION>cyg_counter_tick()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1886 Alarms may be attached to counters, and the alarms will trigger
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1887 when the counter reaches a specified value.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1888 <PROGRAMLISTING>void cyg_counter_delete(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1889 cyg_handle_t counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1890 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1891 <PARA>Deletes the given counter and frees the corresponding memory.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1892 <PROGRAMLISTING>cyg_tick_count_t cyg_counter_current_value(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1893 cyg_handle_t counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1894 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1895 <PARA>Returns the current value of the given counter.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1896 <PROGRAMLISTING>void cyg_counter_set_value(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1897 cyg_handle_t counter,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1898 cyg_tick_count_t new_value
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1899 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1900 <PARA>Sets the counter's value to new_value.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1901 <PROGRAMLISTING>void cyg_counter_tick(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1902 cyg_handle_t counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1903 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1904 <PARA>Advances the counter by one tick.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1905 <PROGRAMLISTING>void cyg_counter_multi_tick(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1906 cyg_handle_t counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1907 cyg_tick_count_t ticks
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1908 )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1909 <PARA>Advances the counter by multiple ticks.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1910 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1911 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1912 <TITLE>Clocks</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1913 <PARA>Clocks are counters which are associated with a stream
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1914 of ticks that represent time periods. Clocks have a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1915 resolution associated with them, whereas counters do not.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1916 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1917 <PARA>The most frequently used clock is the <EMPHASIS>real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1918 clock</EMPHASIS> which serves two special purposes. First, it is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1919 necessary to support clock and alarm related functions such as <FUNCTION>cyg_thread_delay()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1920 Second, it is needed to implement timeslicing in the mlqueue and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1921 lottery schedulers. If the application does not require either of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1922 these facilities, then it is possible to disable the real-time clock
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1923 support completely. It is also possible to disable just timeslicing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1924 with the configuration option CYGSEM_KERNEL_SCHED_TIMESLICE,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1925 or just the clock and alarm functions, using the option CYGFUN_KERNEL_THREADS_TIMER..</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1926 <PARA>The real-time clock is available if the configuration option CYGVAR_KERNEL_COUNTERS_CLOCK
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1927 is defined. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1928 <PARA>Clock resolution is stored in variables of type cyg_resolution_t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1929 (<xref linkend="cyg-resolution-t">).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1930 <PROGRAMLISTING>void <FUNCTION>cyg_clock_create</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1931 cyg_resolution_t resolution,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1932 cyg_handle_t *handle,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1933 cyg_clock *clock )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1934 <PARA>Creates a clock object with the given <emphasis>resolution</emphasis> and places
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1935 it in the space pointed to by <emphasis>clock</emphasis>. A clock is a counter driven
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1936 by a regular source of ticks. For example the system real-time clock
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1937 is driven by a clock interrupt.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1938 <PROGRAMLISTING>void <FUNCTION>cyg_clock_delete</FUNCTION>( cyg_handle_t clock )</programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1939 <PARA>Deletes a clock object and frees the associated memory.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1940 <PROGRAMLISTING>void <FUNCTION>cyg_clock_to_counter</FUNCTION>( </PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1941 <PROGRAMLISTING>cyg_handle_t clock,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1942 cyg_handle_t *counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1943 )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1944 <PARA>Converts a clock handle to a counter handle. The counter functions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1945 can then be used with the counter handle.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1946 <PROGRAMLISTING>void <FUNCTION>cyg_clock_set_resolution</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1947 cyg_handle_t clock,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1948 cyg_resolution_t resolution
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1949 )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1950 <PARA>Changes the resolution of a given clock object.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1951 <PROGRAMLISTING>cyg_resolution_t <FUNCTION>cyg_clock_get_resolution</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1952 cyg_handle_t clock )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1953 <PARA>Returns the resolution of clock. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1954 <PROGRAMLISTING>cyg_handle <FUNCTION>cyg_real_time_clock</FUNCTION>( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1955 <PARA>Returns a handle to the system-supplied real-time clock.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1956 <PROGRAMLISTING>cyg_tick_count_t <FUNCTION>cyg_current_time</FUNCTION>( void )</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1957 <PARA>Returns the real-time clock's counter. This is equivalent
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1958 to executing the code:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1959 <PROGRAMLISTING> cyg_clock_to_counter(cyg_real_time_clock(), &h),
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1960 cyg_counter_current_value(h); </PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1961 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1962 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1963 <TITLE><!-- <index></index> -->Alarms</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1964 <PROGRAMLISTING>typedef void cyg_alarm_t(cyg_handle_t alarm, cyg_addrword_t data);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1965 <PARA>cyg_alarm_t is the type used for functions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1966 which are used to handle alarm events. It is used in the function <FUNCTION>cyg_alarm_create()</FUNCTION>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1967 <PROGRAMLISTING>void <FUNCTION>cyg_alarm_create</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1968 cyg_handle_t <EMPHASIS>counter,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1969 cyg_alarm_t *<EMPHASIS>alarm_fn,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1970 cyg_addrword_t <EMPHASIS>data,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1971 cyg_handle_t *<EMPHASIS>handle,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1972 cyg_alarm *<EMPHASIS>alarm )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1973 <PARA>Creates an alarm object. The alarm is attached to the <parameter>counter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1974 </parameter> and is created in the memory pointed to by <parameter>alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1975 </parameter>. When the alarm triggers, the handler function <parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1976 alarmfn</parameter> is called and is passed <parameter>data</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1977 as a parameter. The alarm handler executes in the context of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1978 function that incremented the counter and thus triggered the alarm.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1979 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1980 <PARA>If the alarm is associated with the real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1981 clock, the alarm handler <parameter>alarmfn</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1982 will be invoked by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1983 delayed service routine (DSR) that services the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1984 real-time clock. This means that real-time clock alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1985 handlers (which are possibly the most frequently used)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1986 must follow the rules of behavior for DSRs. These rules
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1987 are outlined in <XREF LINKEND="INTERRUPT-AND-EXCEPTION-HANDLERS">.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1988 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1989 <PROGRAMLISTING>void <FUNCTION>cyg_alarm_delete</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1990 cyg_handle_t <EMPHASIS>alarm )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1991 <PARA>Disables the alarm, detaches from the counter, invalidates
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1992 handles, and frees memory if it was dynamically allocated by <FUNCTION>cyg_alarm_create()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1993 <PROGRAMLISTING>void <FUNCTION>cyg_alarm_initialize</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1994 cyg_handle_t <EMPHASIS>alarm,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1995 cyg_tick_count_t <EMPHASIS>trigger,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1996 cyg_tick_count_t <EMPHASIS>interval
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1997 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1998 <PARA>Initialize an alarm. This sets it to trigger at the tick with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	1999 value <parameter>trigger</parameter>. When an alarm triggers, this event is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2000 dealt with by calling the <parameter>alarmfn</parameter> parameter which was
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2001 passed when the alarm was created using <FUNCTION>cyg_alarm_create()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2002 If <parameter>interval</parameter> is non-zero, then after the alarm has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2003 triggered it will set itself to trigger again after <parameter>interval
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2004 </parameter> ticks. Otherwise, if <parameter>interval</parameter> is zero, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2005 alarm will be disabled automatically once it has triggered. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2006 <PROGRAMLISTING>void <FUNCTION>cyg_alarm_get_times</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2007 cyg_handle_t <EMPHASIS>alarm,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2008 cyg_tick_count_t *<EMPHASIS>trigger,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2009 cyg_tick_count_t *<EMPHASIS>interval
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2010 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2011 <PARA>Returns the trigger and interval parameters of the alarm.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2012 <PROGRAMLISTING>void <FUNCTION>cyg_alarm_enable</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2013 cyg_handle_t <EMPHASIS>alarm )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2014 <PARA>Enables an alarm that has been disabled by calling <FUNCTION>cyg_alarm_disable()</FUNCTION>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2015 <PROGRAMLISTING>void <FUNCTION>cyg_alarm_disable</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2016 cyg_handle_t <EMPHASIS>alarm )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2017 <PARA>Disables an alarm. After an alarm is disabled it will not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2018 be triggered unless it is subsequently re-enabled by calling <FUNCTION>cyg_alarm_enable()</FUNCTION> or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2019 is reinitialized by calling <FUNCTION>cyg_alarm_initialize()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2020 <PARA>Note, though, that if a periodic alarm that has been disabled
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2021 is re-enabled without reinitializing it will be in phase with the <EMPHASIS>original</EMPHASIS> sequence
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2022 of alarms. If it is <EMPHASIS>reinitialized</EMPHASIS>, the new
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2023 sequence of alarms will be in phase with the moment in which <FUNCTION>cyg_alarm_initialize()</FUNCTION> was
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2024 called. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2025 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2026 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2027 <SECT1 id="synchronization">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2028 <TITLE>Synchronization</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2029 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2030 <TITLE>Semaphores</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2031 <PARA>The <!-- <index></index> -->semaphores defined by the type cyg_sem_t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2032 are counting semaphores. These objects are not referred to by handles,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2033 but rather by the pointer to the variable in which the semaphore
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2034 is created.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2035 <PROGRAMLISTING>void <FUNCTION>cyg_semaphore_init</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2036 cyg_sem_t *<EMPHASIS>sem,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2037 cyg_ucount32 <EMPHASIS>val )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2038 <PARA>Initializes a semaphore. The initial semaphore count is set
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2039 to <parameter>val</parameter>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2040 <PROGRAMLISTING>void <FUNCTION>cyg_semaphore_destroy</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2041 cyg_sem_t *<EMPHASIS>sem
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2042 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2043 <PARA>Destroys a semaphore. This must not be done while there are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2044 any threads waiting on it. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2045 <PROGRAMLISTING>void <FUNCTION>cyg_semaphore_wait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2046 cyg_sem_t *<EMPHASIS>sem
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2047 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2048 <PARA>If the semaphore count is zero, the current thread will wait
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2049 on the semaphore. If the count is non-zero, it will be decremented
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2050 and the thread will continue running. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2051 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_semaphore_trywait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2052 cyg_sem_t *<EMPHASIS>sem
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2053 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2054 <PARA>A non-blocking version of <FUNCTION>cyg_semaphore_wait()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2055 This attempts to decrement the semaphore count. If the count is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2056 positive, then the semaphore is decremented and <constant>true</constant>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2057 is returned. If the count is zero then the semaphore remains unchanged, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2058 <constant>false</constant> is returned, but the current thread continues to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2059 run. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2060 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_semaphore_timed_wait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2061 cyg_sem_t *<EMPHASIS>sem,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2062 cyg_tick_count_t <EMPHASIS>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2063 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2064 <PARA>A time-out version of <FUNCTION>cyg_semaphore_wait()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2065 This attempts to decrement the semaphore count. If the count is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2066 positive, then the semaphore is decremented and <constant>true</constant> is returned.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2067 If the count is zero, it will wait for the semaphore to increment.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2068 If however the <parameter>abstime</parameter> time-out is reached first, it will return
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2069 <constant>false</constant> without changing state, and the current thread will continue
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2070 to run.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2071 <PARA>The <parameter>cyg_tick_count_t</parameter> parameter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2072 is an absolute time. If a relative time is required, you should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2073 use <FUNCTION>cyg_current_time</FUNCTION> with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2074 an offset. For example, to time out 200 ticks from the present you
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2075 would use:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2076 <PROGRAMLISTING>cyg_semaphore_timed_wait(&sem, cyg_current_time() + 200);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2077 <PARA><FUNCTION>cyg_semaphore_timed_wait()</FUNCTION> is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2078 only available if the configuration option CYGFUN_KERNEL_THREADS_TIMER
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2079 is set. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2080 <PROGRAMLISTING>void <FUNCTION>cyg_semaphore_post</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2081 cyg_sem_t *<EMPHASIS>sem
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2082 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2083 <PARA>If there are threads waiting on this semaphore this will wake
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2084 exactly one of them. Otherwise it simply increments the semaphore
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2085 count.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2086 <PROGRAMLISTING>void <FUNCTION>cyg_semaphore_peek</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2087 cyg_sem_t *<EMPHASIS>sem,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2088 cyg_count32 *<EMPHASIS>val )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2089 <PARA>Returns the current semaphore count in the variable pointed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2090 to by <parameter>val</parameter>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2091 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2092 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2093 <TITLE><!-- <xref> -->Mutexes</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2094 <PARA><!-- <index></index> -->Mutexes (mutual exclusion locks) are used in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2095 a similar way to semaphores. A mutex only has two states, locked
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2096 and unlocked. Mutexes are used to protect accesses to shared data
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2097 or resources. When a thread locks a mutex it becomes the owner.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2098 Only the mutex's owner may unlock it. While a mutex remains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2099 locked, the owner should not lock it again, as the behavior is undefined
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2100 and probably dangerous. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2101 <PARA>If non-owners try to lock the mutex, they will be suspended
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2102 until the mutex is available again, at which point they will own
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2103 the mutex. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2104 <PROGRAMLISTING>void <FUNCTION>cyg_mutex_init</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2105 cyg_mutex_t *<EMPHASIS>mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2106 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2107 <PARA>Initializes a mutex. It is initialized in the unlocked state. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2108 <PROGRAMLISTING>void <FUNCTION>cyg_mutex_destroy</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2109 cyg_mutex_t *<EMPHASIS>mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2110 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2111 <PARA>Destroys a mutex. A mutex should not be destroyed in the locked
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2112 state, as the behavior is undefined. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2113 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mutex_lock</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2114 cyg_mutex_t *<EMPHASIS>mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2115 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2116 <PARA>Changes the nutex from the unlocked state to the locked state.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2117 When this happens the mutex becomes owned by the current thread.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2118 If the mutex is locked, the current thread will wait until the mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2119 becomes unlocked before performing this operation. The result of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2120 this function will be TRUE if the mutex has been locked, or FALSE
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2121 if it has not. A FALSE result can result if the thread has been
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2122 released from its wait by a call to <FUNCTION>cyg_thread_release()</FUNCTION> or <FUNCTION>cyg_mutex_release()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2123 <PROGRAMLISTING>void <FUNCTION>cyg_mutex_unlock</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2124 cyg_mutex_t *<EMPHASIS>mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2125 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2126 <PARA>Changes the mutex from the locked state to the unlocked state.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2127 This function may only be called by the thread which locked the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2128 mutex, and should not be called on an unlocked mutex. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2129 <PROGRAMLISTING>void <FUNCTION>cyg_mutex_release</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2130 cyg_mutex_t *<EMPHASIS>mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2131 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2132 <PARA>Release all threads waiting on the mutex pointed to by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2133 mutex argument. These threads will return from cyg_mutex_lock()
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2134 with a FALSE result and will not have claimed the mutex. This function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2135 has no effect on any thread that may have the mutex claimed.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2136 <PROGRAMLISTING>void cyg_mutex_set_protocol(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2137 cyg_mutex_t *<parameter>mutex</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2138 enum cyg_mutex_protocol <parameter>protocol</parameter>)</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2139 <PARA>As described in the Thread Synchronization section, eCos's
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2140 mutex can use a number of schemes when dealing with priority inversion.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2141 This function is used to set the protocol for the mutex. <parameter>protocol
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2142 </parameter> may take one of 3 values: CYG_MUTEX_NONE, CYG_MUTEX_INHERIT,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2143 CYG_MUTEX_CEILING. The first indicates no inversion
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2144 protocol will be used. The second uses the SIMPLE inversion protocol,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2145 and the last uses the ceiling protocol.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2146 <PROGRAMLISTING>void cyg_mutex_set_ceiling(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2147 cyg_mutex_t *<parameter>mutex</parameter>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2148 cyg_priority_t <parameter>priority</parameter>)</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2149 <PARA>When using the ceiling inversion protocol, this function allows
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2150 the ceiling thread priority of an obtained mutex to be set. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2151 <PROGRAMLISTING>cyg_priority_t cyg_thread_get_current_priority(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2152 cyg_handle_t <parameter>thread</parameter>)</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2153 <PARA>Returns the current thread priority. If the thread is running
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2154 at a higher priority than normal due to priority inversion, this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2155 functions returns the inverted priority, whereas
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2156 <function>cyg_thread_get_priority()</function> returns
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2157 the normal priority.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2158 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2159 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2160 <TITLE><!-- <xref> -->Condition Variables</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2161 <PARA><!-- <index></index> -->Condition variables are a synchronization mechanism
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2162 which (used with a mutex) grants several threads mutually exclusive
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2163 access to shared data and to broadcast availability of that data
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2164 to all the other threads.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2165 <PARA>A typical example of the use of condition variables is when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2166 one thread (the producer) is producing data and several other (consumer)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2167 threads are waiting for that data to be ready. The consumers will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2168 wait by invoking <FUNCTION>cyg_cond_wait()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2169 The producer will lock access to the data with a mutex, and when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2170 it has generated enough data for the other processes to consume,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2171 it will invoke <FUNCTION>cyg_cond_broadcast()</FUNCTION> to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2172 wake up the consumers. The <EMPHASIS>Getting Started with </EMPHASIS><PRODUCTNAME>eCos</PRODUCTNAME> book
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2173 has example programs which use condition variables to implement
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2174 a simple message passing system between threads. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2175 <PROGRAMLISTING>void <FUNCTION>cyg_cond_init</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2176 cyg_cond_t *<EMPHASIS>cond,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2177 cyg_mutex_t *<EMPHASIS>mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2178 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2179 <PARA>Initializes the condition variable. A condition variable is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2180 attached to a specific mutex. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2181 <PROGRAMLISTING>void <FUNCTION>cyg_cond_destroy</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2182 cyg_cond_t *<EMPHASIS>cond
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2183 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2184 <PARA>Destroys the condition variable <parameter>cond</parameter>. This must not be done
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2185 on a condition variable which is in use. After it has been destroyed,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2186 it may be subsequently reinitialized. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2187 <PROGRAMLISTING>void <FUNCTION>cyg_cond_wait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2188 cyg_cond_t *<EMPHASIS>cond
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2189 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2190 <PARA>Causes the current thread to wait on the condition variable,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2191 while simultaneously unlocking the corresponding mutex. <FUNCTION>cyg_cond_wait()</FUNCTION> may
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2192 be called by a thread which has the corresponding mutex locked.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2193 <PARA>The thread can only be awakened by a call to <FUNCTION>cyg_cond_signal()</FUNCTION> or <FUNCTION>cyg_cond_broadcast()</FUNCTION> on
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2194 the same condition variable. When the thread is awakened, the mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2195 will be reclaimed before this function proceeds. Since it may have
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2196 to wait for this, <FUNCTION>cyg_cond_wait()</FUNCTION> should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2197 only be used in a loop since the condition may become false in the meantime.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2198 This is shown in the following example: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2199 <PROGRAMLISTING>extern cyg_mutex_t mutex;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2200 extern cyg_cond_t cond;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2201
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2202 cyg_mutex_lock( &mutex );
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2203 ...
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2204
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2205 while( condition_not_true )
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2206 {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2207 cyg_cond_wait( &cond );
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2208 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2209
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2210 ...
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2211
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2212 cyg_mutex_unlock( &mutex );
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2213 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2214 <programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2215 cyg_bool_t <FUNCTION>cyg_cond_timed_wait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2216 cyg_cond_t *<EMPHASIS>cond,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2217 cyg_tick_count_t <EMPHASIS>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2218 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2219 <PARA>A time-out version of <FUNCTION>cyg_cond_wait()</FUNCTION> which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2220 waits for a signal or broadcast. If a signal or broadcast is received
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2221 it returns <constant>true</constant>, but if one is not received by
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2222 <parameter>abstime</parameter>, it returns <constant>false</constant>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2223 <PARA>The <parameter>cyg_tick_count_t</parameter> parameter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2224 is an absolute time. If a relative time is required, you should
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2225 use <FUNCTION>cyg_current_time</FUNCTION> with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2226 an offset. For example, to time out 200 ticks from the present you
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2227 would use:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2228 <PROGRAMLISTING>cyg_cond_timed_wait(&sem, cyg_current_time() + 200);</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2229 <PARA><FUNCTION>cyg_cond_timed_wait()</FUNCTION> is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2230 only available if the configuration option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2231 is set. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2232 <PROGRAMLISTING>void <FUNCTION>cyg_cond_signal</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2233 cyg_cond_t *<EMPHASIS>cond
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2234 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2235 <PARA>Wakes up at least one thread which is waiting on the condition
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2236 variable. When a thread is awakened it will become the owner of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2237 the mutex. <FUNCTION>cyg_cond_signal()</FUNCTION> may
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2238 be called by the thread which currently owns the mutex to which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2239 the condition variable is attached. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2240 <PROGRAMLISTING>void <FUNCTION>cyg_cond_broadcast</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2241 cyg_cond_t *<EMPHASIS>cond
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2242 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2243 <PARA>Wakes <EMPHASIS>all</EMPHASIS> the threads waiting on the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2244 condition variable. Each time a thread is awakened it will become
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2245 the current owner of the mutex. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2246 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2247 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2248 <SECT1 id="memory-pools">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2249 <TITLE><!-- <xref> -->Memory pools</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2250 <PARA>There are two sorts of <!-- <index></index> -->memory pools. A variable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2251 size memory pool is for allocating blocks of any size. A fixed size
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2252 memory pool, has the block size specified when the pool is created
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2253 and only provides blocks of that size.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2254 <PARA>Blocking, non-blocking and “blocking with time-out” versions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2255 of these calls are provided. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2256 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_var_create</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2257 void *<EMPHASIS>base,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2258 cyg_int32 <EMPHASIS>size,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2259 cyg_handle_t *<EMPHASIS>handle,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2260 cyg_mempool_var *<EMPHASIS>var
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2261 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2262 <PARA>Creates a variable size memory pool. The parameters are:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2263 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2264 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2265 <TERM>base </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2266 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2267
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2268 <PARA>base of memory to use for pool</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2269 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2270 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2271 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2272 <TERM>size </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2273 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2274
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2275 <PARA>size of memory pool in bytes</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2276 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2277 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2278 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2279 <TERM>handle </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2280 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2281
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2282 <PARA>returned handle of memory pool</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2283 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2284 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2285 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2286 <TERM>var </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2287 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2288
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2289 <PARA>space to put pool structure in</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2290 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2291 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2292 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2293 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_var_delete</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2294 cyg_handle_t <EMPHASIS>varpool
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2295 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2296 <PARA>Deletes the variable size memory pool <parameter>varpool</parameter>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2297 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2298 <PROGRAMLISTING>void *<FUNCTION>cyg_mempool_var_alloc</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2299 cyg_handle_t <EMPHASIS>varpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2300 cyg_int32 <EMPHASIS>size )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2301 <PARA>Allocates a block of length <parameter>size</parameter>. This will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2302 block until the memory becomes available.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2303 <PROGRAMLISTING>void *<FUNCTION>cyg_mempool_var_timed_alloc</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2304 cyg_handle_t <EMPHASIS>varpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2305 cyg_int32 <EMPHASIS>size,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2306 cyg_tick_count_t <EMPHASIS>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2307 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2308 <PARA>Allocates a block of length <parameter>size</parameter>. If the requested
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2309 amount of memory is not available, it will wait until <parameter>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2310 </parameter> before giving up and returning <constant>NULL</constant>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2311 <PROGRAMLISTING>void *<FUNCTION>cyg_mempool_var_try_alloc</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2312 cyg_handle_t <EMPHASIS>varpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2313 cyg_int32 <EMPHASIS>size )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2314 <PARA>Allocates a block of length <parameter>size</parameter>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2315 <constant>NULL</constant> is returned if not enough is available.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2316 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_var_free</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2317 cyg_handle_t <EMPHASIS>varpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2318 void *<EMPHASIS>p )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2319 <PARA>Frees memory back into variable size pool <parameter>varpool</parameter>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2320 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2321 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mempool_var_waiting</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2322 cyg_handle_t <EMPHASIS>varpool
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2323 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2324 <PARA>Returns true if any threads are waiting for memory in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2325 <parameter>varpool</parameter>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2326 <PROGRAMLISTING>typedef struct {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2327 cyg_int32 totalmem;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2328 cyg_int32 freemem;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2329 void *base;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2330 cyg_int32 size;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2331 cyg_int32 blocksize;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2332 cyg_int32 maxfree; // The largest free block
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2333 } cyg_mempool_info;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2334 </programlisting><programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2335 void <FUNCTION>cyg_mempool_var_get_info</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2336 cyg_handle_t <EMPHASIS>varpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2337 cyg_mempool_info *<EMPHASIS>info
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2338 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2339 <PARA>Puts information about a variable memory pool into the structure
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2340 provided.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2341 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_fix_create</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2342 void *<EMPHASIS>base,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2343 cyg_int32 <EMPHASIS>size,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2344 cyg_int32 <EMPHASIS>blocksize,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2345 cyg_handle_t *<EMPHASIS>handle,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2346 cyg_mempool_fix *<EMPHASIS>fix
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2347 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2348 <PARA>Create a fixed size memory pool. This function takes the following
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2349 parameters:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2350 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2351 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2352 <TERM>base </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2353 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2354
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2355 <PARA>base of memory to use for pool</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2356 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2357 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2358 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2359 <TERM>size </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2360 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2361
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2362 <PARA>size of total space requested</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2363 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2364 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2365 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2366 <TERM>blocksize </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2367 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2368
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2369 <PARA>size of individual elements</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2370 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2371 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2372 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2373 <TERM>handle </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2374 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2375
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2376 <PARA>returned handle of memory pool</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2377 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2378 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2379 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2380 <TERM>fix </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2381 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2382
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2383 <PARA>space to put pool structure in</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2384 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2385 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2386 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2387 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_fix_delete</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2388 cyg_handle_t <EMPHASIS>fixpool
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2389 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2390 <PARA>Deletes the given fixed size memory pool.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2391 <PROGRAMLISTING>void *<FUNCTION>cyg_mempool_fix_alloc</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2392 cyg_handle_t <EMPHASIS>fixpool
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2393 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2394 <PARA>Allocates a block. If the memory is not available immediately,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2395 this blocks until the memory becomes available.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2396 <PROGRAMLISTING>void *<FUNCTION>cyg_mempool_fix_timed_alloc</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2397 cyg_handle_t <EMPHASIS>fixpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2398 cyg_tick_count_t <EMPHASIS>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2399 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2400 <PARA>Allocates a block. If the memory is not already available,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2401 it will try until <parameter>abstim</parameter>e before giving up and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2402 returning a <constant>NULL</constant>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2403 <PROGRAMLISTING>void *<FUNCTION>cyg_mempool_fix_try_alloc</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2404 cyg_handle_t <EMPHASIS>fixpool
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2405 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2406 <PARA>Allocates a block. NULL is returned if no memory is available.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2407 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_fix_free</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2408 cyg_handle_t <EMPHASIS>fixpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2409 void *<EMPHASIS>p )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2410 <PARA>Frees memory back into fixed size pool.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2411 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mempool_fix_waiting</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2412 cyg_handle_t <EMPHASIS>fixpool
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2413 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2414 <PARA>Returns true if there are any threads waiting for memory in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2415 the given memory pool.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2416 <PROGRAMLISTING>void <FUNCTION>cyg_mempool_fix_get_info</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2417 cyg_handle_t <EMPHASIS>fixpool,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2418 cyg_mempool_info *<EMPHASIS>info
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2419 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2420 <PARA>Puts information about a variable memory pool into the structure
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2421 provided.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2422 <PARA>The fixed size memory pool simply returns blocks of memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2423 of exactly the blocksize requested. If the pool is being used to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2424 allocate memory for a type that has alignment constraints (such
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2425 as 4-byte alignment), then it is up to the user to align the memory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2426 appropriately for the type in question. Alternatively, choose a blocksize
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2427 that is an exact multiple of the required alignment.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2428 <PARA>The memory available from the memory pools will not be the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2429 same size as the memory supplied to it. Some of the memory is used
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2430 for internal data structures of the allocator. <function>cyg_mempool_fix_get_info()</function> and <function>cyg_mempool_var_get_info()</function> may
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2431 be used to determine the available memory.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2432 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2433 <SECT1 id="message-boxes">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2434 <TITLE><!-- <index></index> -->Message boxes</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2435 <PARA>Message boxes are a primitive mechanism for exchanging messages
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2436 between threads, inspired by the µITRON
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2437 specification. A message box can be created with <FUNCTION>cyg_mbox_create()</FUNCTION> before
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2438 the scheduler is started, and two threads in a typical producer/consumer relationship
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2439 can access it. One thread, the producer, will use <FUNCTION>cyg_mbox_put()</FUNCTION> to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2440 make data available to the consumer thread which uses <FUNCTION>cyg_mbox_get()</FUNCTION> to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2441 access the data. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2442 <PARA>The size of the internal message queue is configured by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2443 “Message box queue size” ( CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE )
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2444 configuration option. The default value is 10. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2445 <PARA>Blocking, non-blocking and “blocking with time-out” versions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2446 of these calls are provided. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2447 <PROGRAMLISTING>void <FUNCTION>cyg_mbox_create</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2448 cyg_handle_t *<EMPHASIS>handle,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2449 cyg_mbox *<EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2450 <PARA>Creates a message box using the space provided in the mbox
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2451 parameter, and returns a handle for future access to that message
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2452 box.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2453 <PROGRAMLISTING>void <FUNCTION>cyg_mbox_delete</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2454 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2455 <PARA>Deletes the given message box. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2456 <PROGRAMLISTING>void *<FUNCTION>cyg_mbox_get</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2457 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2458 <PARA>Waits for a message to be available, then retrieves it and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2459 returns the address of the data. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2460 <PROGRAMLISTING>void *<FUNCTION>cyg_mbox_timed_get</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2461 cyg_handle_t <EMPHASIS>mbox,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2462 cyg_tick_count_t <EMPHASIS>timeout
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2463 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2464 <PARA>Waits for a message to be available, but times out if <parameter>timeout
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2465 </parameter>time passes. This version of the function is only available if the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2466 configuration option CYGFUN_KERNEL_THREADS_TIMER
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2467 is turned on. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2468 <PROGRAMLISTING>void *<FUNCTION>cyg_mbox_tryget</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2469 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2470 <PARA>Checks to see if a message is ready. If no message is available
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2471 it returns immediately with a return value of <constant>NULL</constant>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2472 If a message is available it retrieves it and returns the address of the data.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2473 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2474 <PROGRAMLISTING>void *<FUNCTION>cyg_mbox_peek_item</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2475 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2476 <PARA>Checks to see if a message is ready, and if one is available
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2477 returns the address of the data <EMPHASIS>without</EMPHASIS> removing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2478 the message from the queue. If no message is available it returns
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2479 <constant>NULL</constant>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2480 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mbox_put</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2481 cyg_handle_t <EMPHASIS>mbox,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2482 void *<EMPHASIS>item )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2483 <PARA>Places a message in the given message box. If the queue is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2484 full it will block until the message can be sent. It returns <constant>true
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2485 </constant>if the message was successfully sent, and <constant>false</constant>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2486 if the message was not sent and its sleep was awakened by the kernel before
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2487 the message could be sent. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2488 <PARA>The <FUNCTION>cyg_mbox_put()</FUNCTION> function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2489 is only available if the CYGMTH_MBOXT_PUT_CAN_WAIT configuration
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2490 has been selected. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2491 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mbox_timed_put</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2492 cyg_handle_t <EMPHASIS>mbox,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2493 void *<EMPHASIS>item,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2494 cyg_tick_count_t <EMPHASIS>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2495 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2496 <PARA>A time-out version of <FUNCTION>cyg_mbox_put()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2497 This will try to place the message in the given message box. If
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2498 the queue is full, it will wait until <parameter>abstime</parameter> before
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2499 giving up and returning <constant>false</constant>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2500 <PARA>The <FUNCTION>cyg_mbox_timed_put()</FUNCTION> function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2501 is only available if the both the CYGMFN_KERNEL_SYNCH_MBOXT_PUT_CAN_WAIT
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2502 and CYGFUN_KERNEL_THREADS_TIMER configuration
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2503 have been selected. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2504 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mbox_tryput</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2505 cyg_handle_t <EMPHASIS>mbox,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2506 void *<EMPHASIS>item )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2507 <PARA>Tries to place a message in the given message box. It returns
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2508 <constant>true</constant> if the message was successfully sent, and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2509 <constant>false</constant> if the message
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2510 could not be sent immediately, usually because the queue was full. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2511 <PROGRAMLISTING>cyg_count32 <FUNCTION>cyg_mbox_peek</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2512 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2513 <PARA>Takes a peek at the queue and returns the number of messages
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2514 waiting in it. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2515 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mbox_waiting_to_get</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2516 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2517 <PARA>Queries the kernel to see if other processes are waiting to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2518 receive a message in the given message box. Returns <constant>true</constant>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2519 if other processes are waiting, <constant>false</constant> otherwise. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2520 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_mbox_waiting_to_put</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2521 cyg_handle_t <EMPHASIS>mbox )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2522 <PARA>Queries the kernel to see if <EMPHASIS>other</EMPHASIS> processes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2523 are waiting to send a message in the given message box. Returns
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2524 <constant>true</constant> if other processes are waiting, <constant>false
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2525 </constant> otherwise. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2526 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2527 <SECT1 id="flags">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2528 <TITLE>Flags</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2529 <PARA>Flags are a <!-- <index></index> -->synchronization mechanism which
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2530 allow a thread to wait for a single condition or a combination of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2531 conditions. The conditions are represented by bits in a 32 bit word. Flags
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2532 are inspired by the <!-- <index></index> -->µITRON specification.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2533 <PARA>Flags are of type cyg_flag_t, which are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2534 32 bit words, and routines are provided to set or mask some bits
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2535 in the flag value. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2536 <PARA>A “consumer side” thread can wait for a “producer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2537 side” thread to set the entire collection of bits, or any
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2538 subset of them.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2539 <PARA>When a thread sets some bits in a flag, all threads whose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2540 requirements are now satisfied are woken up; thus flags have broadcast
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2541 semantics. A variation on the wait call can specify that the flag
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2542 value be cleared when the wait call is satisfied, in which case
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2543 the setting of bits would not be a broadcast. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2544 <PARA>Blocking, non-blocking, and “blocking with time-out” versions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2545 of the wait calls are provided. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2546 <PROGRAMLISTING>void <FUNCTION>cyg_flag_init</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2547 cyg_flag_t *<EMPHASIS>flag
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2548 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2549 <PARA>Initializes a flag variable.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2550 <PROGRAMLISTING>void <FUNCTION>cyg_flag_destroy</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2551 cyg_flag_t *<EMPHASIS>flag
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2552 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2553 <PARA>Destroys a flag variable.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2554 <PROGRAMLISTING>void <FUNCTION>cyg_flag_setbits</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2555 cyg_flag_t *<EMPHASIS>flag,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2556 cyg_flag_value_t <EMPHASIS>value
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2557 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2558 <PARA>Sets the bits in <parameter>flag</parameter> which are set in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2559 <parameter>value</parameter>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2560 <PARA>A side effect of <FUNCTION>cyg_flag_setbits()</FUNCTION> is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2561 that the kernel wakes up any waiting threads whose requirements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2562 are now satisfied. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2563 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2564 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2565 <TERM>flag </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2566 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2567
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2568 <PARA>A pointer to the flag whose bits are being set. The new setting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2569 of <parameter>flag</parameter> will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2570 <literal>flag -> (flag \| value)</literal>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2571 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2572 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2573 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2574 <TERM>value </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2575 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2576
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2577 <PARA>A word whose 1 bits will also be set in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2578 *<parameter>flag</parameter>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2579 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2580 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2581 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2582 <PROGRAMLISTING>void <FUNCTION>cyg_flag_maskbits</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2583 cyg_flag_t *<EMPHASIS>flag,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2584 cyg_flag_value_t <EMPHASIS>value</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2585 )
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2586 </PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2587 <PARA>Clear the bits in the given <parameter>flag</parameter> which are zero
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2588 in the <parameter>value</parameter>. This cannot result in new threads being
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2589 eligible for awakening.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2590 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2591 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2592 <TERM>flag </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2593 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2594
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2595 <PARA>A pointer to the flag whose bits are being cleared. The new
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2596 setting of <parameter>flag</parameter> will be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2597 <literal>flag -> (flag & value)</literal>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2598 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2599 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2600 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2601 <TERM>value </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2602 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2603
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2604 <PARA>A word whose 0 bits will also be cleared in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2605 *<parameter>flag</parameter>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2606 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2607 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2608 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2609 <PARA>We now describe the <FUNCTION>cyg_flag_wait()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2610 which frequently uses the following macros: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2611 <PROGRAMLISTING> #define CYG_FLAG_WAITMODE_AND ((cyg_flag_mode_t)0)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2612 #define CYG_FLAG_WAITMODE_OR ((cyg_flag_mode_t)2)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2613 #define CYG_FLAG_WAITMODE_CLR ((cyg_flag_mode_t)1)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2614 </programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2615 <programlisting>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2616 cyg_flag_value_t <FUNCTION>cyg_flag_wait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2617 cyg_flag_t *<EMPHASIS>flag,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2618 cyg_flag_value_t <EMPHASIS>pattern,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2619 cyg_flag_mode_t <EMPHASIS>mode
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2620 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2621 <PARA>Wait for all the bits which are one in <parameter>pattern</parameter> to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2622 be set in the <parameter>flag</parameter> value (if <parameter>mode</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2623 is <constant>CYG_FLAG_WAITMODE_AND</constant>)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2624 or for any of the bits which are one in <parameter>pattern</parameter> to be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2625 set in the <parameter>flag</parameter> value (if mode is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2626 <constant>CYG_FLAG_WAITMODE_OR</constant>).</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2627 <PARA>When <FUNCTION>cyg_flag_wait()</FUNCTION> returns,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2628 meaning that the condition is met, the flag value which succeeded
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2629 is returned from the call; in other circumstances (such as a bad
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2630 value for <parameter>mode</parameter> or <parameter>pattern</parameter>), zero
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2631 is returned to indicate the error.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2632 <PARA>If the mode is one of those above plus <constant>CYG_FLAG_WAITMODE_CLR
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2633 </constant>, the whole of the flag value is cleared to zero when the condition
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2634 is met. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2635 <PARA><FUNCTION>cyg_flag_wait()</FUNCTION> takes
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2636 the following parameters: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2637 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2638 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2639 <TERM>flag </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2640 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2641
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2642 <PARA>The value of the flag (set by the thread that called <FUNCTION>cyg_flag_setbits()</FUNCTION> or <FUNCTION>cyg_flag_maskbits()</FUNCTION>)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2643 is placed in here.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2644 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2645 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2646 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2647 <TERM>pattern </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2648 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2649
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2650 <PARA>The set of bits which, if set, will cause the calling thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2651 to be woken up. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2652 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2653 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2654 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2655 <TERM>mode </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2656 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2657
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2658 <PARA>A parameter which modifies the conditions for wake-up. It
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2659 can take the following values: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2660 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2661 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2662 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2663 <TERM>CYG_FLAG_WAITMODE_AND </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2664 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2665
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2666 <PARA>Only wake up if <EMPHASIS>all</EMPHASIS> the bits in <parameter>mask
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2667 </parameter>are set in the flag.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2668 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2669 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2670 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2671 <TERM>CYG_FLAG_WAITMODE_OR </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2672 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2673
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2674 <PARA>Wake up if <EMPHASIS>any</EMPHASIS> of the bits in <parameter>mask
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2675 </parameter> are set in the flag. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2676 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2677 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2678 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2679 <TERM>CYG_FLAG_WAITMODE_AND +
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2680 CYG_FLAG_WAITMODE_CLR </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2681 <TERM>CYG_FLAG_WAITMODE_OR + CYG_FLAG_WAITMODE_CLR
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2682 </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2683 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2684 <PARA> Like CYG_FLAG_WAITMODE_AND and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2685 CYG_FLAG_WAITMODE_OR, but the entire
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2686 flag is cleared to zero when the condition is met, whereas normally
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2687 the value of the flag is unchanged. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2688 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2689 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2690 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2691 <PARA>Waiting threads are queued depending on the semantics of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2692 underlying scheduler. In release &version;, this means that, if
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2693 the multi-level queue scheduler is selected, queueing is in FIFO
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2694 ordering, while the bitmap scheduler supports thread priority ordered
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2695 queueing. When some flag value bits become signalled by a call to <FUNCTION>cyg_flag_setbits()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2696 the queue is scanned in order, and each waiting thread in turn is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2697 awoken or re-queued depending on its request. When a thread is awoken,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2698 if it made the wait call with CYG_FLAG_WAITMODE_CLR,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2699 the flag value is cleared to zero, and the scan of queued threads
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2700 is terminated. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2701 <PROGRAMLISTING>cyg_flag_value_t <FUNCTION>cyg_flag_timed_wait</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2702 cyg_flag_t *<EMPHASIS>flag,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2703 cyg_flag_value_t <EMPHASIS>pattern,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2704 cyg_flag_mode_t <EMPHASIS>mode,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2705 cyg_tick_count_t <EMPHASIS>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2706 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2707 <PARA>A time-out version of <FUNCTION>cyg_flag_wait()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2708 This waits for the condition required by <parameter>pattern</parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2709 and <parameter>mode</parameter> to be met, or until the <parameter>abstime
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2710 </parameter> time-out is reached, whichever is first.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2711 If the time-out is reached first, zero is returned. This call is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2712 only available if the configuration option <constant>CYGFUN_KERNEL_THREADS_TIMER
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2713 </constant> is enabled. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2714 <PROGRAMLISTING>cyg_flag_value_t <FUNCTION>cyg_flag_poll</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2715 cyg_flag_t *<EMPHASIS>flag,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2716 cyg_flag_value_t <EMPHASIS>pattern,</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2717 cyg_flag_mode_t <EMPHASIS>mode
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2718 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2719 <PARA>A non-blocking version of <FUNCTION>cyg_flag_wait()</FUNCTION>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2720 If the condition required by <parameter>pattern</parameter> and <parameter>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2721 mode</parameter> is met, the flag value
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2722 is returned, otherwise zero is returned. The flag value may be cleared
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2723 in the event of success by specifying CYG_FLAG_WAITMODE_CLR
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2724 in the <parameter>mode</parameter>, as usual. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2725 <PROGRAMLISTING>cyg_flag_value_t <FUNCTION>cyg_flag_peek</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2726 cyg_flag_t *<EMPHASIS>flag
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2727 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2728 <PARA>Returns the current flag value.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2729 <PROGRAMLISTING>cyg_bool_t <FUNCTION>cyg_flag_waiting</FUNCTION>(
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2730 cyg_flag_t *<EMPHASIS>flag
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2731 )</EMPHASIS></PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2732 <PARA>Returns true if there are threads waiting on this flag.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2733 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2734 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2735 <CHAPTER id="ecos-interrupt-model">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2736 <TITLE>eCos <!-- <index></index> -->Interrupt Model</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2737 <PARA>This chapter describes the <EMPHASIS>eCos</EMPHASIS>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2738 interrupt model in detail. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2739 <PARA>Interrupt handling is an important part of most real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2740 systems. Timely handling of interrupt sources is important.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2741 This can be severely impacted by certain activities that must
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2742 be considered atomic (i.e. uninterruptible). Typically these
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2743 activities are executed with interrupts disabled. In order to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2744 keep such activities to a minimum and allow for the smallest
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2745 possible interrupt latencies, <EMPHASIS>eCos</EMPHASIS> uses a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2746 split interrupt handling scheme. In this scheme, interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2747 handling is separated into two parts. The first part is known
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2748 as the <!-- <index></index> -->Interrupt Service Routine or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2749 ISR. The second part is the <!-- <index></index> -->Deferred
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2750 Service Routine or DSR. This separation explicitly allows for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2751 the DSRs to be run with interrupts enabled, thus allowing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2752 other potentially higher priority interrupts to occur and be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2753 processed while processing a lower priority interrupt. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2754 <PARA>In order for this model to work, the ISR should run
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2755 quickly. If the service requirements for the interrupt are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2756 small, the interrupt can be completely handled by the ISR and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2757 no DSR is required. However, if servicing the interrupt is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2758 more complex, a DSR should be used. The DSR will be run at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2759 some later time, at the point when thread scheduling is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2760 allowed. Postponing the execution of DSRs until this time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2761 allows for simple synchronization methods to be used by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2762 kernel. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2763 <PARA>Further, this controlled calling — when thread scheduling
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2764 is allowed — means that DSRs can interact with the kernel,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2765 for example by signalling that an asynchronous operation has completed. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2766 <PARA>In order to allow DSRs to run with interrupts enabled, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2767 ISR for a particular interrupt source (or the hardware) must arrange
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2768 that that interrupt will not recur until the DSR has completed.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2769 In some cases, this is how the hardware works. Once an interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2770 is delivered another interrupt will not occur until re-enabled.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2771 In the general case, however, it is up to the ISR to enforce this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2772 behavior. Typically the ISR will "mask" the interrupt source, thus
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2773 preventing its recurrence. The DSR will then unmask the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2774 when it has been serviced thus allowing new occurrences of the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2775 to be delivered when they happen. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2776 <PARA>Alternatively, if an ISR is doing very little per interrupt,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2777 for example transferring one byte from memory to an IO device, it
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2778 may only be necessary to interact with the rest of the system when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2779 a "transfer" is complete. In such a case an ISR could execute many
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2780 times and only when it reaches the end of a buffer does it need
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2781 to request execution of its DSR. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2782 <PARA>If the interrupt source is "bursty", it may be OK for several
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2783 interrupts and calls to the ISR to occur before a requested DSR
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2784 has been executed; the kernel maintains counts for posted DSRs,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2785 and in such a case the DSR will eventually be called with a parameter
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2786 that tells it how many ISRs requested that the DSR be called. Care
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2787 is needed to get the interrupt code right for such a situation,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2788 for one call to the DSR is required to do the work of several. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2789 <PARA>As mentioned above, the DSR will execute at some later time.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2790 Depending on the state of the system, it may be executed at a much
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2791 later time. There are periods during certain kernel operations where
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2792 thread scheduling is disabled, and hence DSRs are not allowed to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2793 operate. These periods have been purposefully made as limited as
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2794 possible in the <EMPHASIS>eCos</EMPHASIS> kernel, but they still
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2795 exist. In addition, user threads have the ability to suspend scheduling
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2796 as well, thus affecting the possible DSR execution latency. If a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2797 DSR cannot be executed sufficiently quickly, the interrupt source
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2798 may actually overrun. This would be considered a system failure. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2799 <PARA>One of the problems system designers face is how much stack
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2800 space to allow each thread in the system. <EMPHASIS>eCos</EMPHASIS> does
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2801 not dictate the size of thread stacks, it is left to the user when
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2802 the thread is created. The size of the stack depends on the thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2803 requirements as well as some fixed overhead required by the system.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2804 In this case, the overhead is enough stack space to hold a complete
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2805 thread state (the actual amount depends on the CPU architecture).
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2806 Guidelines for the minimum stack requirements are provided by the HAL
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2807 using the symbol <literal>CYGNUM_HAL_STACK_SIZE_MINIMUM</literal>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2808 <PARA>A potential problem with this scheme is with nested interrupts.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2809 Since interrupts are reenabled during the DSR portion of servicing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2810 an interrupt, there is the possibility of a new interrupt (hopefully
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2811 from a separate source) arriving while this processing takes place.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2812 When this new interrupt is serviced some state information about
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2813 the interrupted processing will be saved on the stack. The amount
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2814 of this information again depends on the CPU architecture and in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2815 some cases it is substantial. This implies that any given stack
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2816 would need enough space to potentially hold "N" interrupt frames.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2817 In a realtime system with many threads this is an untenable situation.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2818 To solve this problem, <EMPHASIS>eCos</EMPHASIS> allows for a separate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2819 interrupt stack to be used while processing interrupts. This stack
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2820 needs to be large enough to support "N" nested interrupts, but each
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2821 individual thread stack only needs the overhead of a single interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2822 state. This is because the thread state is kept on the thread's
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2823 own stack, including information about any interrupt that caused
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2824 the thread to be scheduled. This is a much better situation in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2825 end, however, since only the interrupt stack need be large enough
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2826 to handle the potential interrupt servicing needs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2827 <PARA><EMPHASIS>eCos</EMPHASIS> allows for the use of the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2828 stack to be totally configurable. The user can elect to not use
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2829 a separate interrupt stack. This requires making all thread stacks large
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2830 enough but does reduce the overhead of switching stacks while processing interrupts.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2831 On the other hand, if memory is tight, then choosing a separate
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2832 interrupt stack would be warranted at the cost of a few machine
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2833 cycles during the processing of each interrupt. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2834 <PARA>Not all target HALs support this feature from day one anyway;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2835 however common configuration features such as this may still be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2836 presented in the config tool, and present in include files, even
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2837 if the actual target selected does not support the feature at this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2838 time. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2839 <PARA>The following problem with the interrupt system has been observed.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2840 On the mn10300 simulator, interrupts were occurring immediately
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2841 after they were re-enabled in the DSR. This should really be considered
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2842 a case of interrupt overrun since there is no possibility of useful [or
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2843 any] processing between the time an interrupt has been
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2844 serviced and an subsequent interrupt occurs, hence the system is totally
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2845 saturated. The problem came about because the stack was overflowing.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2846 It was a user [thread] stack that overflowed because
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2847 DSR processing was taking place on the thread stack. Analysis of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2848 this problem led to a rework of how interrupts are processed, in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2849 particular the use of a separate interrupt stack during interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2850 processing (both ISR and DSR parts). The overflow can still happen,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2851 but now it is restricted to only the interrupt stack. The system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2852 designer can make accommodations for this by making a suitably large
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2853 interrupt stack if it is known that the "overrun" is finite, e.g.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2854 in the case of a serial device, this could be the depth of some
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2855 FIFO. In any case, overrun should be avoided, but having only a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2856 single stack that needs to suffer multiple interrupt frames allows
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2857 for this failure to be detected simply. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2858 <PARA>Of course, it is only worthwhile having a separate interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2859 stack if you are using an <EMPHASIS>eCos</EMPHASIS> configuration
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2860 that has a scheduler and multiple threads. If there is no kernel,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2861 then the C library arranges to call <FUNCTION>main()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2862 or your application may be entered from <FUNCTION>cyg_user_start()</FUNCTION>,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2863 on the startup stack. It runs on the only stack there is in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2864 system. Depending on the design of the particular HAL for your target
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2865 platform, it is natural to re-use the startup stack as the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2866 stack as soon as the scheduler is running. Since this is only sensible
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2867 if there is a kernel, HALs typically only implement the separate interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2868 stack if the kernel is present. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2869 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2870 <CHAPTER id="real-time-characterization">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2871 <TITLE><!-- <index></index> -->Real-time Characterization</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2872 <PARA>When building a real-time system, care must be taken to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2873 ensure that the system will be able to perform properly within
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2874 the constraints of that system. One of these constraints may
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2875 be how fast certain operations can be performed. Another might
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2876 be how deterministic the overall behavior of the system is.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2877 Lastly the memory footprint (size) and unit cost may be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2878 important. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2879 <PARA>One of the major problems encountered while evaluating a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2880 system will be how to compare it with possible alternatives.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2881 Most manufacturers of real-time systems publish performance
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2882 numbers, ostensibly so that users can compare the different
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2883 offerings. However, what these numbers mean and how they were
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2884 gathered is often not clear. The values are typically measured
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2885 on a particular piece of hardware, so in order to truly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2886 compare, one must obtain measurements for exactly the same set
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2887 of hardware that were gathered in a similar fashion. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2888 <PARA>Two major items need to be present in any given set of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2889 measurements. First, the raw values for the various
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2890 operations; these are typically quite easy to measure and will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2891 be available for most systems. Second, the determinacy of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2892 numbers; in other words how much the value might change
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2893 depending on other factors within the system. This value is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2894 affected by a number of factors: how long interrupts might be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2895 masked, whether or not the function can be interrupted, even
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2896 very hardware-specific effects such as cache locality and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2897 pipeline usage. It is very difficult to measure the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2898 determinacy of any given operation, but that determinacy is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2899 fundamentally important to proper overall characterization of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2900 a system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2901 <PARA>In the discussion and numbers that follow, three key measurements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2902 are provided. The first measurement is an estimate of the interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2903 latency: this is the length of time from when a hardware interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2904 occurs until its <!-- <index></index> -->Interrupt Service Routine (ISR)
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2905 is called. The second measurement is an estimate of overall interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2906 overhead: this is the length of time average interrupt processing takes,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2907 as measured by the real-time clock interrupt (other interrupt sources
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2908 will certainly take a different amount of time, but this data cannot
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2909 be easily gathered). The third measurement consists of the timings
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2910 for the various kernel primitives. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2911 <SECT1 id="real-time-char-methodology"><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2912 <TITLE>Methodology</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2913 <PARA>Key operations in the kernel were measured by using a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2914 simple test program which exercises the various kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2915 primitive operations. A hardware timer, normally the one
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2916 used to drive the real-time clock, was used for these
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2917 measurements. In most cases this timer can be read with
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2918 quite high resolution, typically in the range of a few
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2919 microseconds. For each measurement, the operation was
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2920 repeated a number of times. Time stamps were obtained
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2921 directly before and after the operation was performed. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2922 data gathered for the entire set of operations was then
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2923 analyzed, generating average (mean), maximum and minimum
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2924 values. The sample variance (a measure of how close most
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2925 samples are to the mean) was also calculated. The cost of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2926 obtaining the real-time clock timer values was also
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2927 measured, and was subtracted from all other times. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2928 <PARA>Most <!-- <index></index> -->kernel functions can be measured separately.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2929 In each case, a reasonable number of iterations are performed. Where
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2930 the test case involves a kernel object, for example creating a task,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2931 each iteration is performed on a different object. There is also
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2932 a set of tests which measures the interactions between multiple
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2933 tasks and certain kernel primitives. Most functions are tested in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2934 such a way as to determine the variations introduced by varying
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2935 numbers of objects in the system. For example, the mailbox tests
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2936 measure the cost of a 'peek' operation when the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2937 mailbox is empty, has a single item, and has multiple items present.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2938 In this way, any effects of the state of the object or how many
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2939 items it contains can be determined. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2940 <PARA>There are a few things to consider about these measurements.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2941 Firstly, they are quite micro in scale and only measure the operation
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2942 in question. These measurements do not adequately describe how the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2943 timings would be perturbed in a real system with multiple interrupting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2944 sources. Secondly, the possible aberration incurred by the real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2945 clock (system heartbeat tick) is explicitly avoided. Virtually all
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2946 kernel functions have been designed to be interruptible. Thus the times
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2947 presented are typical, but best case, since any particular function
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2948 may be interrupted by the clock tick processing. This number is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2949 explicitly calculated so that the value may be included in any deadline
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2950 calculations required by the end user. Lastly, the reported measurements
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2951 were obtained from a system built with all options at their default
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2952 values. Kernel instrumentation and asserts are also disabled for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2953 these measurements. Any number of configuration options can change
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2954 the measured results, sometimes quite dramatically. For example,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2955 mutexes are using priority inheritance in these measurements. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2956 numbers will change if the system is built with priority inheritance
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2957 on mutex variables turned off. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2958 <PARA>The final value that is measured is an estimate of interrupt
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2959 latency. This particular value is not explicitly calculated in the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2960 test program used, but rather by instrumenting the kernel itself.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2961 The raw number of timer ticks that elapse between the time the timer
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2962 generates an interrupt and the start of the timer ISR is kept in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2963 the kernel. These values are printed by the test program after all
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2964 other operations have been tested. Thus this should be a reasonable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2965 estimate of the interrupt latency over time. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2966 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2967 <SECT1 id="real-time-char-using-measurements">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2968 <TITLE>Using these Measurements</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2969 <PARA>These measurements can be used in a number of ways. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2970 most typical use will be to compare different real-time
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2971 kernel offerings on similar hardware, another will be to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2972 estimate the cost of implementing a task using eCos
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2973 (applications can be examined to see what effect the kernel
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2974 operations will have on the total execution time). Another
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2975 use would be to observe how the tuning of the kernel affects
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2976 overall operation. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2977 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2978 <SECT1 id="real-time-char-influences-on-performance">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2979 <TITLE>Influences on Performance</TITLE><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2980 <PARA>A number of factors can affect real-time performance in
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2981 a system. One of the most common factors, yet most difficult
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2982 to characterize, is the effect of device drivers and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2983 interrupts on system timings. Different device drivers will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2984 have differing requirements as to how long interrupts are
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2985 suppressed, for example. The eCos system has been designed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2986 with this in mind, by separating the management of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2987 interrupts (ISR handlers) and the processing required by the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2988 interrupt (<!-- <index></index> -->DSR—Deferred
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2989 Service Routine— handlers). However, since there is so
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2990 much variability here, and indeed most device drivers will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2991 come from the end users themselves, these effects cannot be
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2992 reliably measured. Attempts have been made to measure the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2993 overhead of the single interrupt that eCos relies on, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2994 real-time clock timer. This should give you a reasonable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2995 idea of the cost of executing interrupt handling for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2996 devices. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2997 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2998 <SECT1 id="real-time-char-measured-items">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	2999 <TITLE>Measured Items</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3000 <PARA>This section describes the various <!-- <index></index>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3001 -->tests and the numbers presented. All tests use the C
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3002 kernel API (available by way of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3003 <FILENAME>cyg/kernel/kapi.h</FILENAME>). There is a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3004 single main thread in the system that performs the various
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3005 tests. Additional threads may be created as part of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3006 testing, but these are short lived and are destroyed between
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3007 tests unless otherwise noted. The terminology “lower
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3008 priority” means a priority that is less important, not
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3009 necessarily lower in numerical value. A higher priority
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3010 thread will run in preference to a lower priority thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3011 even though the priority value of the higher priority thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3012 may be numerically less than that of the lower priority
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3013 thread. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3014 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3015 <TITLE>Thread Primitives</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3016 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3017 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3018 <TERM>Create thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3019 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3020 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3021 <FUNCTION>cyg_thread_create()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3022 call. Each call creates a totally new thread. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3023 set of threads created by this test will be reused
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3024 in the subsequent thread primitive tests. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3025 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3026 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3027 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3028 <TERM>Yield thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3029 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3030 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3031 <FUNCTION>cyg_thread_yield()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3032 call. For this test, there are no other runnable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3033 threads, thus the test should just measure the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3034 overhead of trying to give up the CPU. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3035 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3036 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3037 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3038 <TERM>Suspend [suspended] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3039 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3040 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3041 <FUNCTION>cyg_thread_suspend()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3042 call. A thread may be suspended multiple times; each
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3043 thread is already suspended from its initial
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3044 creation, and is suspended again. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3045 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3046 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3047 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3048 <TERM>Resume thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3049 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3050 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3051 <FUNCTION>cyg_thread_resume()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3052 call. All of the threads have a suspend count of 2,
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3053 thus this call does not make them runnable. This
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3054 test just measures the overhead of resuming a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3055 thread. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3056 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3057 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3058 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3059 <TERM>Set priority</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3060 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3061 <PARA> This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3062 <FUNCTION>cyg_thread_set_priority()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3063 call. Each thread, currently suspended, has its
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3064 priority set to a new value. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3065 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3066 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3067 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3068 <TERM>Get priority</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3069 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3070 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3071 <FUNCTION>cyg_thread_get_priority()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3072 call. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3073 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3074 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3075 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3076 <TERM>Kill [suspended] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3077 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3078 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3079 <FUNCTION>cyg_thread_kill()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3080 call. Each thread in the set is killed. All threads
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3081 are known to be suspended before being killed.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3082 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3083 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3084 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3085 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3086 <TERM>Yield [no other] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3087 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3088 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3089 <FUNCTION>cyg_thread_yield()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3090 call again. This is to demonstrate that the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3091 <FUNCTION>cyg_thread_yield()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3092 call has a fixed overhead, regardless of whether
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3093 there are other threads in the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3094 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3095 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3096 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3097 <TERM>Resume [suspended low priority] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3098 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3099 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3100 <FUNCTION>cyg_thread_resume()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3101 call again. In this case, the thread being resumed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3102 is lower priority than the main thread, thus it will
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3103 simply become ready to run but not be granted the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3104 CPU. This test measures the cost of making a thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3105 ready to run. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3106 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3107 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3108 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3109 <TERM>Resume [runnable low priority] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3110 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3111 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3112 <FUNCTION>cyg_thread_resume()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3113 call again. In this case, the thread being resumed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3114 is lower priority than the main thread and has
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3115 already been made runnable, so in fact the resume
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3116 call has no effect. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3117 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3118 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3119 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3120 <TERM>Suspend [runnable] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3121 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3122 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3123 <FUNCTION>cyg_thread_suspend()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3124 call again. In this case, each thread has already
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3125 been made runnable (by previous tests). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3126 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3127 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3128 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3129 <TERM>Yield [only low priority] thread </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3130 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3131 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3132 <FUNCTION>cyg_thread_yield()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3133 call. In this case, there are many other runnable
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3134 threads, but they are all lower priority than the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3135 main thread, thus no thread switches will take
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3136 place. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3137 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3138 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3139 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3140 <TERM>Suspend [runnable->not runnable] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3141 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3142 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3143 <FUNCTION>cyg_thread_suspend()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3144 call again. The thread being suspended will become
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3145 non-runnable by this action. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3146 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3147 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3148 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3149 <TERM>Kill [runnable] thread</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3150 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3151 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3152 <FUNCTION>cyg_thread_kill()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3153 call again. In this case, the thread being killed
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3154 is currently runnable, but lower priority than the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3155 main thread. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3156 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3157 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3158 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3159 <TERM>Resume [high priority] thread </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3160 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3161 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3162 <FUNCTION>cyg_thread_resume()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3163 call. The thread being resumed is higher priority
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3164 than the main thread, thus a thread switch will take
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3165 place on each call. In fact there will be two thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3166 switches; one to the new higher priority thread and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3167 a second back to the test thread. The test thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3168 exits immediately. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3169 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3170 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3171 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3172 <TERM>Thread switch</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3173 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3174 <PARA>This test attempts to measure the cost of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3175 switching from one thread to another. Two equal
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3176 priority threads are started and they will each
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3177 yield to the other for a number of iterations. A
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3178 time stamp is gathered in one thread before the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3179 <FUNCTION>cyg_thread_yield()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3180 call and after the call in the other thread. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3181 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3182 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3183 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3184 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3185 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3186 <TITLE>Scheduler Primitives</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3187 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3188 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3189 <TERM>Scheduler lock</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3190 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3191 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3192 <FUNCTION>cyg_scheduler_lock()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3193 call. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3194 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3195 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3196 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3197 <TERM>Scheduler unlock [0 threads] </TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3198 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3199 <PARA>This test measures the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3200 <FUNCTION>cyg_scheduler_unlock()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3201 call. There are no other threads in the system and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3202 the unlock happens immediately after a lock so there
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3203 will be no pending DSR’s to run. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3204 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3205 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3206 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3207 <TERM>Scheduler unlock [1 suspended thread]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3208 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3209 <PARA>This test measures the <FUNCTION>cyg_scheduler_unlock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3210 There is one other thread in the system which is currently suspended. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3211 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3212 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3213 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3214 <TERM>Scheduler unlock [many suspended threads]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3215 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3216 <PARA>This test measures the <FUNCTION>cyg_scheduler_unlock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3217 There are many other threads in the system which are currently suspended. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3218 purpose of this test is to determine the cost of having additional
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3219 threads in the system when the scheduler is activated by way of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3220 <FUNCTION>cyg_scheduler_unlock()</FUNCTION>. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3221 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3222 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3223 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3224 <TERM>Scheduler unlock [many low priority threads]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3225 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3226 <PARA>This test measures the <FUNCTION>cyg_scheduler_unlock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3227 There are many other threads in the system which are runnable but
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3228 are lower priority than the main thread. The purpose of this test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3229 is to determine the cost of having additional threads in the system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3230 when the scheduler is activated by way of <FUNCTION>cyg_scheduler_unlock()</FUNCTION>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3231 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3232 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3233 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3234 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3235 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3236 <TITLE>Mutex Primitives</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3237 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3238 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3239 <TERM>Init mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3240 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3241 <PARA>This test measures the <FUNCTION>cyg_mutex_init()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3242 A number of separate mutex variables are created. The purpose of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3243 this test is to measure the cost of creating a new mutex and introducing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3244 it to the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3245 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3246 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3247 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3248 <TERM>Lock [unlocked] mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3249 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3250 <PARA>This test measures the <FUNCTION>cyg_mutex_lock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3251 The purpose of this test is to measure the cost of locking a mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3252 which is currently unlocked. There are no other threads executing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3253 in the system while this test runs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3254 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3255 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3256 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3257 <TERM>Unlock [locked] mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3258 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3259 <PARA>This test measures the <FUNCTION>cyg_mutex_unlock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3260 The purpose of this test is to measure the cost of unlocking a mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3261 which is currently locked. There are no other threads executing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3262 in the system while this test runs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3263 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3264 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3265 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3266 <TERM>Trylock [unlocked] mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3267 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3268 <PARA>This test measures the <FUNCTION>cyg_mutex_trylock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3269 The purpose of this test is to measure the cost of locking a mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3270 which is currently unlocked. There are no other threads executing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3271 in the system while this test runs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3272 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3273 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3274 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3275 <TERM>Trylock [locked] mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3276 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3277 <PARA>This test measures the <FUNCTION>cyg_mutex_trylock()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3278 The purpose of this test is to measure the cost of locking a mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3279 which is currently locked. There are no other threads executing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3280 in the system while this test runs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3281 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3282 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3283 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3284 <TERM>Destroy mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3285 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3286 <PARA>This test measures the <FUNCTION>cyg_mutex_destroy()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3287 The purpose of this test is to measure the cost of deleting a mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3288 from the system. There are no other threads executing in the system
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3289 while this test runs. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3290 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3291 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3292 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3293 <TERM>Unlock/Lock mutex</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3294 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3295 <PARA>This test attempts to measure the cost of unlocking a mutex
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3296 for which there is another higher priority thread waiting. When
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3297 the mutex is unlocked, the higher priority waiting thread will immediately
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3298 take the lock. The time from when the unlock is issued until after
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3299 the lock succeeds in the second thread is measured, thus giving
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3300 the round-trip or circuit time for this type of synchronizer. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3301 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3302 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3303 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3304 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3305 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3306 <TITLE>Mailbox Primitives</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3307 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3308 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3309 <TERM>Create mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3310 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3311 <PARA>This test measures the <FUNCTION>cyg_mbox_create()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3312 A number of separate mailboxes is created. The purpose of this test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3313 is to measure the cost of creating a new mailbox and introducing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3314 it to the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3315 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3316 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3317 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3318 <TERM>Peek [empty] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3319 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3320 <PARA>This test measures the <FUNCTION>cyg_mbox_peek()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3321 An attempt is made to peek the value in each mailbox, which is currently empty.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3322 The purpose of this test is to measure the cost of checking a mailbox
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3323 for a value without blocking. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3324 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3325 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3326 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3327 <TERM>Put [first] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3328 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3329 <PARA>This test measures the <FUNCTION>cyg_mbox_put()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3330 One item is added to a currently empty mailbox. The purpose of this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3331 test is to measure the cost of adding an item to a mailbox. There
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3332 are no other threads currently waiting for mailbox items to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3333 arrive. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3334 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3335 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3336 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3337 <TERM>Peek [1 msg] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3338 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3339 <PARA>This test measures the <FUNCTION>cyg_mbox_peek()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3340 An attempt is made to peek the value in each mailbox, which contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3341 a single item. The purpose of this test is to measure the cost of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3342 checking a mailbox which has data to deliver. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3343 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3344 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3345 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3346 <TERM>Put [second] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3347 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3348 <PARA>This test measures the <FUNCTION>cyg_mbox_put()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3349 A second item is added to a mailbox. The purpose of this test is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3350 to measure the cost of adding an additional item to a mailbox. There
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3351 are no other threads currently waiting for mailbox items to
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3352 arrive. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3353 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3354 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3355 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3356 <TERM>Peek [2 msgs] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3357 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3358 <PARA>This test measures the <FUNCTION>cyg_mbox_peek()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3359 An attempt is made to peek the value in each mailbox, which contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3360 two items. The purpose of this test is to measure the cost of checking
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3361 a mailbox which has data to deliver. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3362 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3363 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3364 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3365 <TERM>Get [first] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3366 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3367 <PARA>This test measures the <FUNCTION>cyg_mbox_get()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3368 The first item is removed from a mailbox that currently contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3369 two items. The purpose of this test is to measure the cost of obtaining
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3370 an item from a mailbox without blocking. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3371 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3372 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3373 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3374 <TERM>Get [second] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3375 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3376 <PARA>This test measures the <FUNCTION>cyg_mbox_get()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3377 The last item is removed from a mailbox that currently contains
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3378 one item. The purpose of this test is to measure the cost of obtaining
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3379 an item from a mailbox without blocking. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3380 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3381 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3382 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3383 <TERM>Tryput [first] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3384 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3385 <PARA>This test measures the <FUNCTION>cyg_mbox_tryput()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3386 A single item is added to a currently empty mailbox. The purpose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3387 of this test is to measure the cost of adding an item to a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3388 mailbox. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3389 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3390 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3391 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3392 <TERM>Peek item [non-empty] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3393 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3394 <PARA>This test measures the <FUNCTION>cyg_mbox_peek_item()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3395 A single item is fetched from a mailbox that contains a single item.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3396 The purpose of this test is to measure the cost of obtaining an
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3397 item without disturbing the mailbox. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3398 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3399 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3400 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3401 <TERM>Tryget [non-empty] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3402 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3403 <PARA>This test measures the <FUNCTION>cyg_mbox_tryget()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3404 A single item is removed from a mailbox that contains exactly one
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3405 item. The purpose of this test is to measure the cost of obtaining
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3406 one item from a non-empty mailbox. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3407 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3408 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3409 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3410 <TERM>Peek item [empty] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3411 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3412 <PARA>This test measures the <FUNCTION>cyg_mbox_peek_item()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3413 An attempt is made to fetch an item from a mailbox that is empty.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3414 The purpose of this test is to measure the cost of trying to obtain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3415 an item when the mailbox is empty. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3416 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3417 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3418 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3419 <TERM>Tryget [empty] mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3420 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3421 <PARA>This test measures the <FUNCTION>cyg_mbox_tryget()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3422 An attempt is made to fetch an item from a mailbox that is empty.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3423 The purpose of this test is to measure the cost of trying to obtain
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3424 an item when the mailbox is empty. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3425 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3426 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3427 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3428 <TERM>Waiting to get mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3429 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3430 <PARA>This test measures the <FUNCTION>cyg_mbox_waiting_to_get()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3431 The purpose of this test is to measure the cost of determining how
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3432 many threads are waiting to obtain a message from this
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3433 mailbox. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3434 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3435 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3436 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3437 <TERM>Waiting to put mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3438 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3439 <PARA>This test measures the <FUNCTION>cyg_mbox_waiting_to_put()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3440 The purpose of this test is to measure the cost of determining how
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3441 many threads are waiting to put a message into this mailbox. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3442 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3443 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3444 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3445 <TERM>Delete mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3446 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3447 <PARA>This test measures the <FUNCTION>cyg_mbox_delete()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3448 The purpose of this test is to measure the cost of destroying a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3449 mailbox and removing it from the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3450 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3451 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3452 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3453 <TERM>Put/Get mbox</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3454 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3455 <PARA>In this round-trip test, one thread is sending data to a mailbox
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3456 that is being consumed by another thread. The time from when the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3457 data is put into the mailbox until it has been delivered to the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3458 waiting thread is measured. Note that this time will contain a thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3459 switch. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3460 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3461 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3462 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3463 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3464 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3465 <TITLE>Semaphore Primitives</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3466 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3467 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3468 <TERM>Init semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3469 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3470 <PARA>This test measures the <FUNCTION>cyg_semaphore_init()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3471 A number of separate semaphore objects are created and introduced
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3472 to the system. The purpose of this test is to measure the cost of
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3473 creating a new semaphore. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3474 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3475 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3476 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3477 <TERM>Post [0] semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3478 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3479 <PARA>This test measures the <FUNCTION>cyg_semaphore_post()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3480 Each semaphore currently has a value of 0 and there are no other
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3481 threads in the system. The purpose of this test is to measure the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3482 overhead cost of posting to a semaphore. This cost will differ if
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3483 there is a thread waiting for the semaphore. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3484 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3485 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3486 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3487 <TERM>Wait [1] semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3488 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3489 <PARA>This test measures the <FUNCTION>cyg_semaphore_wait()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3490 The semaphore has a current value of 1 so the call is non-blocking.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3491 The purpose of the test is to measure the overhead of “taking” a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3492 semaphore. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3493 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3494 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3495 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3496 <TERM>Trywait [0] semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3497 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3498 <PARA>This test measures the <FUNCTION>cyg_semaphore_trywait()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3499 The semaphore has a value of 0 when the call is made. The purpose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3500 of this test is to measure the cost of seeing if a semaphore can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3501 be “taken” without blocking. In this case, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3502 answer would be no. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3503 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3504 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3505 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3506 <TERM>Trywait [1] semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3507 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3508 <PARA>This test measures the <FUNCTION>cyg_semaphore_trywait()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3509 The semaphore has a value of 1 when the call is made. The purpose
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3510 of this test is to measure the cost of seeing if a semaphore can
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3511 be “taken” without blocking. In this case, the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3512 answer would be yes. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3513 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3514 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3515 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3516 <TERM>Peek semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3517 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3518 <PARA>This test measures the <FUNCTION>cyg_semaphore_peek()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3519 The purpose of this test is to measure the cost of obtaining the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3520 current semaphore count value. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3521 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3522 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3523 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3524 <TERM>Destroy semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3525 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3526 <PARA>This test measures the <FUNCTION>cyg_semaphore_destroy()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3527 The purpose of this test is to measure the cost of deleting a semaphore
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3528 from the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3529 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3530 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3531 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3532 <TERM>Post/Wait semaphore</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3533 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3534 <PARA>In this round-trip test, two threads are passing control back
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3535 and forth by using a semaphore. The time from when one thread calls <FUNCTION>cyg_semaphore_post()</FUNCTION> until
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3536 the other thread completes its <FUNCTION>cyg_semaphore_wait()</FUNCTION> is
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3537 measured. Note that each iteration of this test will involve a thread
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3538 switch. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3539 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3540 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3541 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3542 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3543 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3544 <TITLE>Counters</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3545 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3546 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3547 <TERM>Create counter</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3548 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3549 <PARA>This test measures the <FUNCTION>cyg_counter_create()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3550 A number of separate counters are created. The purpose of this test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3551 is to measure the cost of creating a new counter and introducing
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3552 it to the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3553 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3554 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3555 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3556 <TERM>Get counter value</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3557 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3558 <PARA>This test measures the <FUNCTION>cyg_counter_current_value()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3559 The current value of each counter is obtained. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3560 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3561 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3562 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3563 <TERM>Set counter value</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3564 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3565 <PARA>This test measures the <FUNCTION>cyg_counter_set_value()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3566 Each counter is set to a new value. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3567 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3568 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3569 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3570 <TERM>Tick counter</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3571 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3572 <PARA>This test measures the <FUNCTION>cyg_counter_tick()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3573 Each counter is “ticked” once. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3574 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3575 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3576 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3577 <TERM>Delete counter</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3578 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3579 <PARA>This test measures the <FUNCTION>cyg_counter_delete()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3580 Each counter is deleted from the system. The purpose of this test
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3581 is to measure the cost of deleting a counter object.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3582 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3583 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3584 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3585 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3586 <SECT2><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3587 <TITLE>Alarms</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3588 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3589 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3590 <TERM>Create alarm</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3591 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3592 <PARA>This test measures the <FUNCTION>cyg_alarm_create()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3593 A number of separate alarms are created, all attached to the same
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3594 counter object. The purpose of this test is to measure the cost
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3595 of creating a new counter and introducing it to the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3596 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3597 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3598 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3599 <TERM>Initialize alarm</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3600 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3601 <PARA>This test measures the <FUNCTION>cyg_alarm_initialize()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3602 Each alarm is initialized to a small value. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3603 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3604 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3605 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3606 <TERM>Disable alarm</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3607 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3608 <PARA>This test measures the <FUNCTION>cyg_alarm_disable()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3609 Each alarm is explicitly disabled. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3610 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3611 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3612 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3613 <TERM>Enable alarm</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3614 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3615 <PARA>This test measures the <FUNCTION>cyg_alarm_enable()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3616 Each alarm is explicitly enabled. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3617 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3618 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3619 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3620 <TERM>Delete alarm</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3621 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3622 <PARA>This test measures the <FUNCTION>cyg_alarm_delete()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3623 Each alarm is destroyed. The purpose of this test is to measure
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3624 the cost of deleting an alarm and removing it from the system. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3625 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3626 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3627 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3628 <TERM>Tick counter [1 alarm]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3629 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3630 <PARA>This test measures the <FUNCTION>cyg_counter_tick()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3631 A counter is created that has a single alarm attached to it. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3632 purpose of this test is to measure the cost of “ticking” a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3633 counter when it has a single attached alarm. In this test, the alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3634 is not activated (fired). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3635 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3636 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3637 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3638 <TERM>Tick counter [many alarms]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3639 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3640 <PARA>This test measures the <FUNCTION>cyg_counter_tick()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3641 A counter is created that has multiple alarms attached to it. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3642 purpose of this test is to measure the cost of “ticking” a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3643 counter when it has many attached alarms. In this test, the alarms
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3644 are not activated (fired). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3645 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3646 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3647 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3648 <TERM>Tick & fire counter [1 alarm]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3649 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3650 <PARA>This test measures the <FUNCTION>cyg_counter_tick()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3651 A counter is created that has a single alarm attached to it. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3652 purpose of this test is to measure the cost of “ticking” a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3653 counter when it has a single attached alarm. In this test, the alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3654 is activated (fired). Thus the measured time will include the overhead
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3655 of calling the alarm callback function. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3656 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3657 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3658 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3659 <TERM>Tick & fire counter [many alarms]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3660 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3661 <PARA>This test measures the <FUNCTION>cyg_counter_tick()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3662 A counter is created that has multiple alarms attached to it. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3663 purpose of this test is to measure the cost of “ticking” a
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3664 counter when it has many attached alarms. In this test, the alarms
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3665 are activated (fired). Thus the measured time will include the overhead
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3666 of calling the alarm callback function. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3667 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3668 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3669 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3670 <TERM>Alarm latency [0 threads]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3671 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3672 <PARA>This test attempts to measure the latency in calling an alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3673 callback function. The time from the clock interrupt until the alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3674 function is called is measured. In this test, there are no threads
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3675 that can be run, other than the system idle thread, when the clock
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3676 interrupt occurs (all threads are suspended). </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3677 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3678 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3679 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3680 <TERM>Alarm latency [2 threads]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3681 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3682 <PARA>This test attempts to measure the latency in calling an alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3683 callback function. The time from the clock interrupt until the alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3684 function is called is measured. In this test, there are exactly
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3685 two threads which are running when the clock interrupt occurs. They
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3686 are simply passing back and forth by way of the <FUNCTION>cyg_thread_yield()</FUNCTION> call.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3687 The purpose of this test is to measure the variations in the latency
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3688 when there are executing threads. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3689 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3690 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3691 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3692 <TERM>Alarm latency [many threads]</TERM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3693 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3694 <PARA>This test attempts to measure the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3695 latency in calling an alarm callback function. The
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3696 time from the clock interrupt until the alarm
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3697 function is called is measured. In this test, there
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3698 are a number of threads which are running when the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3699 clock interrupt occurs. They are simply passing back
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3700 and forth by way of the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3701 <FUNCTION>cyg_thread_yield()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3702 call. The purpose of this test is to measure the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3703 variations in the latency when there are many
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3704 executing threads. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3705 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3706 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3707 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3708 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3709 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3710 <SECT1 id="real-time-char-sample-numbers"><!-- <index></index> -->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3711 <TITLE>Sample Numbers</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3712 <PARA>For sample results, see Appendix 1 of <EMPHASIS>Getting
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3713 Started with eCos</EMPHASIS></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3714 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3715 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	3716 </part>

Mercurial > nand-ecoscentric

annotate packages/kernel/current/doc/kernel.sgml @ 208:e0c0827131d1 ecos