Mercurial > flash_v2

annotate packages/kernel/current/doc/kernel.sgml @ 460:a65a4055f146

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* src/common/kapi.cxx: * include/kapi.h: Added function cyg_thread_get_next(), cyg_thread_find() and cyg_thread_get_info() to allow the current set of threads to be enumerated, and per-thread information to be retrieved safely. * doc/kernel.sgml: Documented new KAPI calls. * src/common/thread.cxx: Zero unique_id in thread destructor so that a stale thread pointer can be checked for validity. * include/instrmnt.h: Added cyg_instrument_state() to report the current state of an instrumentation flag. Moved ifdef for CYGDBG_KERNEL_INSTRUMENT_MSGS out of within FLAGS ifdef. We can have messages without flags. * src/instrmnt/meminst.cxx: Added cyg_instrument_state() to report the current state of an instrumentation flag. Modified cyg_instrument_msg() in line with header and table changes. * host/instr/dump_instr.c: * host/instr/instrument.sh: * include/instrument_desc.h: Added a final NULL element to the generated table in instrument_desc.h to mark its end. Otherwise code that does not have access to the table definition cannot find its end. Also added ifdefs to allow instrument_desc.h to be used to acquire the structure definition and table pointer.
author nickg
date Thu, 12 Dec 2002 18:31:34 +0000
parents b77e86276ec3
children 1061ceceb720
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1 <!-- {{{ Banner -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5 <!-- kernel.sgml -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
6 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
7 <!-- eCos kernel documentation. -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
8 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
9 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
10 <!-- ####COPYRIGHTBEGIN#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
11 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
12 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
14 <!-- This material may be distributed only subject to the terms -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
16 <!-- or later (the latest version is presently available at -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
17 <!-- http://www.opencontent.org/openpub/) -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
18 <!-- Distribution of the work or derivative of the work in any -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
19 <!-- standard (paper) book form is prohibited unless prior -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
20 <!-- permission obtained from the copyright holder -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
21 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
22 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
23 <!-- ####COPYRIGHTEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
24 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
25 <!-- #####DESCRIPTIONBEGIN#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
26 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
27 <!-- Author(s): nickg, bartv, markg -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
28 <!-- Contributors: eCos team -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
29 <!-- Date: 2002/02/13 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
30 <!-- Version: 0.02 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
31 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
32 <!-- ####DESCRIPTIONEND#### -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
33 <!-- =============================================================== -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
34
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
35 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
36
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
37 <part id="kernel">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
38 <title>The eCos Kernel</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
39
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
40 <!-- {{{ Overview -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
41
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
42 <refentry id="kernel-overview">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
43
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
44 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
45 <refentrytitle>Kernel Overview</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
46 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
47
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
48 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
49 <refname>Kernel</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
50 <refpurpose>Overview of the eCos Kernel</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
51 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
52
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
53 <!-- {{{ Description -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
54
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
55 <refsect1 id="kernel-overview-description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
56 <title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
57 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
58 The kernel is one of the key packages in all of eCos. It provides the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
59 core functionality needed for developing multi-threaded applications:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
60 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
61 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
62 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
63 The ability to create new threads in the system, either during startup
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
64 or when the system is already running.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
65 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
66 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
67 Control over the various threads in the system, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
68 manipulating their priorities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
69 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
70 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
71 A choice of schedulers, determining which thread should currently be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
72 running.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
73 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
74 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
75 A range of synchronization primitives, allowing threads to interact
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
76 and share data safely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
77 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
78 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
79 Integration with the system's support for interrupts and exceptions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
80 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
81 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
82 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
83 In some other operating systems the kernel provides additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
84 functionality. For example the kernel may also provide memory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
85 allocation functionality, and device drivers may be part of the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
86 as well. This is not the case for eCos. Memory allocation is handled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
87 by a separate package. Similary each device driver will typically be a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
88 separate package. Various packages are combined and configured using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
89 the eCos configuration technology to meet the requirements of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
90 application.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
91 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
92 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
93 The eCos kernel package is optional. It is possible to write
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
94 single-threaded applications which do not use any kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
95 functionality, for example RedBoot. Typically such applications are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
96 based around a central polling loop, continually checking all devices
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
97 and taking appropriate action when I/O occurs. A small amount of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
98 calculation is possible every iteration, at the cost of an increased
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
99 delay between an I/O event occurring and the polling loop detecting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
100 the event. When the requirements are straightforward it may well be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
101 easier to develop the application using a polling loop, avoiding the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
102 complexities of multiple threads and synchronization between threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
103 As requirements get more complicated a multi-threaded solution becomes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
104 more appropriate, requiring the use of the kernel. In fact some of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
105 more advanced packages in eCos, for example the TCP/IP stack, use
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
106 multi-threading internally. Therefore if the application uses any of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
107 those packages then the kernel becomes a required package, not an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
108 optional one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
109 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
110 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
111 The kernel functionality can be used in one of two ways. The kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
112 provides its own C API, with functions like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
113 <function>cyg_thread_create</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
114 <function>cyg_mutex_lock</function>. These can be called directly from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
115 application code or from other packages. Alternatively there are a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
116 number of packages which provide compatibility with existing API's,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
117 for example POSIX threads or &micro;ITRON. These allow application
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
118 code to call standard functions such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
119 <function>pthread_create</function>, and those functions are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
120 implemented using the basic functionality provided by the eCos kernel.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
121 Using compatibility packages in an eCos application can make it much
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
122 easier to reuse code developed in other environments, and to share
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
123 code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
124 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
125 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
126 Although the different compatibility packages have similar
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
127 requirements on the underlying kernel, for example the ability to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
128 create a new thread, there are differences in the exact semantics. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
129 example, strict &micro;ITRON compliance requires that kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
130 timeslicing is disabled. This is achieved largely through the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
131 configuration technology. The kernel provides a number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
132 configuration options that control the exact semantics that are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
133 provided, and the various compatibility packages require particular
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
134 settings for those options. This has two important consequences.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
135 First, it is not usually possible to have two different compatibility
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
136 packages in one eCos configuration because they will have conflicting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
137 requirements on the underlying kernel. Second, the semantics of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
138 kernel's own API are only loosely defined because of the many
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
139 configuration options. For example <function>cyg_mutex_lock</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
140 will always attempt to lock a mutex, but various configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
141 determine the behaviour when the mutex is already locked and there is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
142 a possibility of priority inversion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
143 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
144 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
145 The optional nature of the kernel package presents some complications
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
146 for other code, especially device drivers. Wherever possible a device
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
147 driver should work whether or not the kernel is present. However there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
148 are some parts of the system, especially those related to interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
149 handling, which should be implemented differently in multi-threaded
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
150 environments containing the eCos kernel and in single-threaded
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
151 environments without the kernel. To cope with both scenarios the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
152 common HAL package provides a driver API, with functions such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
153 <function>cyg_drv_interrupt_attach</function>. When the kernel package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
154 is present these driver API functions map directly on to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
155 equivalent kernel functions such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
156 <function>cyg_interrupt_attach</function>, using macros to avoid any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
157 overheads. When the kernel is absent the common HAL package implements
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
158 the driver API directly, but this implementation is simpler than the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
159 one in the kernel because it can assume a single-threaded environment.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
160 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
161 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
162
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
163 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
164 <!-- {{{ Schedulers -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
165
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
166 <refsect1 id="kernel-overview-schedulers">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
167 <title>Schedulers</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
168 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
169 When a system involves multiple threads, a scheduler is needed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
170 determine which thread should currently be running. The eCos kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
171 can be configured with one of two schedulers, the bitmap scheduler and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
172 the multi-level queue (MLQ) scheduler. The bitmap scheduler is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
173 somewhat more efficient, but has a number of limitations. Most systems
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
174 will instead use the MLQ scheduler. Other schedulers may be added in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
175 the future, either as extensions to the kernel package or in separate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
176 packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
177 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
178 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
179 Both the bitmap and the MLQ scheduler use a simple numerical priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
180 to determine which thread should be running. The number of priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
181 levels is configurable via the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
182 <varname>CYGNUM_KERNEL_SCHED_PRIORITIES</varname>, but a typical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
183 system will have up to 32 priority levels. Therefore thread priorities
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
184 will be in the range 0 to 31, with 0 being the highest priority and 31
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
185 the lowest. Usually only the system's idle thread will run at the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
186 lowest priority. Thread priorities are absolute, so the kernel will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
187 only run a lower-priority thread if all higher-priority threads are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
188 currently blocked.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
189 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
190 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
191 The bitmap scheduler only allows one thread per priority level, so if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
192 the system is configured with 32 priority levels then it is limited to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
193 only 32 threads &mdash; still enough for many applications. A simple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
194 bitmap can be used to keep track of which threads are currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
195 runnable. Bitmaps can also be used to keep track of threads waiting on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
196 a mutex or other synchronization primitive. Identifying the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
197 highest-priority runnable or waiting thread involves a simple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
198 operation on the bitmap, and an array index operation can then be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
199 to get hold of the thread data structure itself. This makes the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
200 bitmap scheduler fast and totally deterministic.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
201 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
202 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
203 The MLQ scheduler allows multiple threads to run at the same priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
204 This means that there is no limit on the number of threads in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
205 system, other than the amount of memory available. However operations
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
206 such as finding the highest priority runnable thread are a little bit
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
207 more expensive than for the bitmap scheduler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
208 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
209 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
210 Optionally the MLQ scheduler supports timeslicing, where the scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
211 automatically switches from one runnable thread to another when some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
212 number of clock ticks have occurred. Timeslicing only comes into play
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
213 when there are two runnable threads at the same priority and no higher
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
214 priority runnable threads. If timeslicing is disabled then a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
215 will not be preempted by another thread of the same priority, and will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
216 continue running until either it explicitly yields the processor or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
217 until it blocks by, for example, waiting on a synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
218 primitive. The configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
219 <varname>CYGSEM_KERNEL_SCHED_TIMESLICE</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
220 <varname>CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS</varname> control
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
221 timeslicing. The bitmap scheduler does not provide timeslicing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
222 support. It only allows one thread per priority level, so it is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
223 possible to preempt the current thread in favour of another one with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
224 the same priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
225 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
226 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
227 Another important configuration option that affects the MLQ scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
228 is <varname>CYGIMP_KERNEL_SCHED_SORTED_QUEUES</varname>. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
229 determines what happens when a thread blocks, for example by waiting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
230 on a semaphore which has no pending events. The default behaviour of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
231 the system is last-in-first-out queuing. For example if several
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
232 threads are waiting on a semaphore and an event is posted, the thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
233 that gets woken up is the last one that called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
234 <function>cyg_semaphore_wait</function>. This allows for a simple and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
235 fast implementation of both the queue and dequeue operations. However
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
236 if there are several queued threads with different priorities, it may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
237 not be the highest priority one that gets woken up. In practice this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
238 is rarely a problem: usually there will be at most one thread waiting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
239 on a queue, or when there are several threads they will be of the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
240 priority. However if the application does require strict priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
241 queueing then the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
242 <varname>CYGIMP_KERNEL_SCHED_SORTED_QUEUES</varname> should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
243 enabled. There are disadvantages: more work is needed whenever a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
244 thread is queued, and the scheduler needs to be locked for this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
245 operation so the system's dispatch latency is worse. If the bitmap
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
246 scheduler is used then priority queueing is automatic and does not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
247 involve any penalties.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
248 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
249 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
250 Some kernel functionality is currently only supported with the MLQ
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
251 scheduler, not the bitmap scheduler. This includes support for SMP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
252 systems, and protection against priority inversion using either mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
253 priority ceilings or priority inheritance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
254 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
255 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
256
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
257 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
258 <!-- {{{ Synch primitives -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
259
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
260 <refsect1 id="kernel-overview-synch-primitives">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
261 <title>Synchronization Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
262 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
263 The eCos kernel provides a number of different synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
264 primitives: <link linkend="kernel-mutexes">mutexes</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
265 <link linkend="kernel-condition-variables">condition variables</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
266 <link linkend="kernel-semaphores">counting semaphores</link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
267 <link linkend="kernel-mail-boxes">mail boxes</link> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
268 <link linkend="kernel-flags">event flags</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
269 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
270 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
271 Mutexes serve a very different purpose from the other primitives. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
272 mutex allows multiple threads to share a resource safely: a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
273 locks a mutex, manipulates the shared resource, and then unlocks the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
274 mutex again. The other primitives are used to communicate information
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
275 between threads, or alternatively from a DSR associated with an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
276 interrupt handler to a thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
277 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
278 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
279 When a thread that has locked a mutex needs to wait for some condition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
280 to become true, it should use a condition variable. A condition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
281 variable is essentially just a place for a thread to wait, and which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
282 another thread, or DSR, can use to wake it up. When a thread waits on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
283 a condition variable it releases the mutex before waiting, and when it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
284 wakes up it reacquires it before proceeding. These operations are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
285 atomic so that synchronization race conditions cannot be introduced.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
286 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
287 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
288 A counting semaphore is used to indicate that a particular event has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
289 occurred. A consumer thread can wait for this event to occur, and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
290 producer thread or a DSR can post the event. There is a count
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
291 associated with the semaphore so if the event occurs multiple times in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
292 quick succession this information is not lost, and the appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
293 number of semaphore wait operations will succeed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
294 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
295 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
296 Mail boxes are also used to indicate that a particular event has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
297 occurred, and allows for one item of data to be exchanged per event.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
298 Typically this item of data would be a pointer to some data structure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
299 Because of the need to store this extra data, mail boxes have a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
300 finite capacity. If a producer thread generates mail box events
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
301 faster than they can be consumed then, to avoid overflow, it will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
302 blocked until space is again available in the mail box. This means
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
303 that mail boxes usually cannot be used by a DSR to wake up a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
304 thread. Instead mail boxes are typically only used between threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
305 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
306 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
307 Event flags can be used to wait on some number of different events,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
308 and to signal that one or several of these events have occurred. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
309 is achieved by associating bits in a bit mask with the different
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
310 events. Unlike a counting semaphore no attempt is made to keep track
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
311 of the number of events that have occurred, only the fact that an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
312 event has occurred at least once. Unlike a mail box it is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
313 possible to send additional data with the event, but this does mean
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
314 that there is no possibility of an overflow and hence event flags can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
315 be used between a DSR and a thread as well as between threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
316 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
317 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
318 The eCos common HAL package provides its own device driver API which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
319 contains some of the above synchronization primitives. These allow
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
320 the DSR for an interrupt handler to signal events to higher-level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
321 code. If the configuration includes the eCos kernel package then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
322 the driver API routines map directly on to the equivalent kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
323 routines, allowing interrupt handlers to interact with threads. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
324 kernel package is not included and the application consists of just a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
325 single thread running in polled mode then the driver API is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
326 implemented entirely within the common HAL, and with no need to worry
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
327 about multiple threads the implementation can obviously be rather
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
328 simpler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
329 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
330 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
331
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
332 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
333 <!-- {{{ Threads and interrupts -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
334
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
335 <refsect1 id="kernel-overview-threads-interrupts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
336 <title>Threads and Interrupt Handling</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
337 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
338 During normal operation the processor will be running one of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
339 threads in the system. This may be an application thread, a system
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
340 thread running inside say the TCP/IP stack, or the idle thread. From
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
341 time to time a hardware interrupt will occur, causing control to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
342 transferred briefly to an interrupt handler. When the interrupt has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
343 been completed the system's scheduler will decide whether to return
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
344 control to the interrupted thread or to some other runnable thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
345 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
346 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
347 Threads and interrupt handlers must be able to interact. If a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
348 is waiting for some I/O operation to complete, the interrupt handler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
349 associated with that I/O must be able to inform the thread that the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
350 operation has completed. This can be achieved in a number of ways. One
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
351 very simple approach is for the interrupt handler to set a volatile
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
352 variable. A thread can then poll continuously until this flag is set,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
353 possibly sleeping for a clock tick in between. Polling continuously
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
354 means that the cpu time is not available for other activities, which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
355 may be acceptable for some but not all applications. Polling once
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
356 every clock tick imposes much less overhead, but means that the thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
357 may not detect that the I/O event has occurred until an entire clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
358 tick has elapsed. In typical systems this could be as long as 10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
359 milliseconds. Such a delay might be acceptable for some applications,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
360 but not all.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
361 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
362 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
363 A better solution would be to use one of the synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
364 primitives. The interrupt handler could signal a condition variable,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
365 post to a semaphore, or use one of the other primitives. The thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
366 would perform a wait operation on the same primitive. It would not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
367 consume any cpu cycles until the I/O event had occurred, and when the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
368 event does occur the thread can start running again immediately
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
369 (subject to any higher priority threads that might also be runnable).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
370 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
371 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
372 Synchronization primitives constitute shared data, so care must be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
373 taken to avoid problems with concurrent access. If the thread that was
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
374 interrupted was just performing some calculations then the interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
375 handler could manipulate the synchronization primitive quite safely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
376 However if the interrupted thread happened to be inside some kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
377 call then there is a real possibility that some kernel data structure
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
378 will be corrupted.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
379 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
380 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
381 One way of avoiding such problems would be for the kernel functions to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
382 disable interrupts when executing any critical region. On most
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
383 architectures this would be simple to implement and very fast, but it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
384 would mean that interrupts would be disabled often and for quite a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
385 long time. For some applications that might not matter, but many
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
386 embedded applications require that the interrupt handler run as soon
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
387 as possible after the hardware interrupt has occurred. If the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
388 relied on disabling interrupts then it would not be able to support
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
389 such applications.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
390 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
391 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
392 Instead the kernel uses a two-level approach to interrupt handling.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
393 Associated with every interrupt vector is an Interrupt Service Routine
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
394 or ISR, which will run as quickly as possible so that it can service
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
395 the hardware. However an ISR can make only a small number of kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
396 calls, mostly related to the interrupt subsystem, and it cannot make
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
397 any call that would cause a thread to wake up. If an ISR detects that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
398 an I/O operation has completed and hence that a thread should be woken
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
399 up, it can cause the associated Deferred Service Routine or DSR to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
400 run. A DSR is allowed to make more kernel calls, for example it can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
401 signal a condition variable or post to a semaphore.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
402 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
403 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
404 Disabling interrupts prevents ISRs from running, but very few parts of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
405 the system disable interrupts and then only for short periods of time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
406 The main reason for a thread to disable interrupts is to manipulate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
407 some state that is shared with an ISR. For example if a thread needs
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
408 to add another buffer to a linked list of free buffers and the ISR may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
409 remove a buffer from this list at any time, the thread would need to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
410 disable interrupts for the few instructions needed to manipulate the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
411 list. If the hardware raises an interrupt at this time, it remains
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
412 pending until interrupts are reenabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
413 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
414 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
415 Analogous to interrupts being disabled or enabled, the kernel has a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
416 scheduler lock. The various kernel functions such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
417 <function>cyg_mutex_lock</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
418 <function>cyg_semaphore_post</function> will claim the scheduler lock,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
419 manipulate the kernel data structures, and then release the scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
420 lock. If an interrupt results in a DSR being requested and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
421 scheduler is currently locked, the DSR remains pending. When the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
422 scheduler lock is released any pending DSRs will run. These may post
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
423 events to synchronization primitives, causing other higher priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
424 threads to be woken up.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
425 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
426 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
427 For an example, consider the following scenario. The system has a high
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
428 priority thread A, responsible for processing some data coming from an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
429 external device. This device will raise an interrupt when data is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
430 available. There are two other threads B and C which spend their time
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
431 performing calculations and occasionally writing results to a display
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
432 of some sort. This display is a shared resource so a mutex is used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
433 control access.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
434 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
435 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
436 At a particular moment in time thread A is likely to be blocked,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
437 waiting on a semaphore or another synchronization primitive until data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
438 is available. Thread B might be running performing some calculations,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
439 and thread C is runnable waiting for its next timeslice. Interrupts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
440 are enabled, and the scheduler is unlocked because none of the threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
441 are in the middle of a kernel operation. At this point the device
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
442 raises an interrupt. The hardware transfers control to a low-level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
443 interrupt handler provided by eCos which works out exactly which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
444 interrupt occurs, and then the corresponding ISR is run. This ISR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
445 manipulates the hardware as appropriate, determines that there is now
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
446 data available, and wants to wake up thread A by posting to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
447 semaphore. However ISR's are not allowed to call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
448 <function>cyg_semaphore_post</function> directly, so instead the ISR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
449 requests that its associated DSR be run and returns. There are no more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
450 interrupts to be processed, so the kernel next checks for DSR's. One
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
451 DSR is pending and the scheduler is currently unlocked, so the DSR can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
452 run immediately and post the semaphore. This will have the effect of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
453 making thread A runnable again, so the scheduler's data structures are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
454 adjusted accordingly. When the DSR returns thread B is no longer the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
455 highest priority runnable thread so it will be suspended, and instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
456 thread A gains control over the cpu.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
457 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
458 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
459 In the above example no kernel data structures were being manipulated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
460 at the exact moment that the interrupt happened. However that cannot
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
461 be assumed. Suppose that thread B had finished its current set of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
462 calculations and wanted to write the results to the display. It would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
463 claim the appropriate mutex and manipulate the display. Now suppose
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
464 that thread B was timesliced in favour of thread C, and that thread C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
465 also finished its calculations and wanted to write the results to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
466 display. It would call <function>cyg_mutex_lock</function>. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
467 kernel call locks the scheduler, examines the current state of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
468 mutex, discovers that the mutex is already owned by another thread,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
469 suspends the current thread, and switches control to another runnable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
470 thread. Another interrupt happens in the middle of this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
471 <function>cyg_mutex_lock</function> call, causing the ISR to run
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
472 immediately. The ISR decides that thread A should be woken up so it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
473 requests that its DSR be run and returns back to the kernel. At this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
474 point there is a pending DSR, but the scheduler is still locked by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
475 call to <function>cyg_mutex_lock</function> so the DSR cannot run
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
476 immediately. Instead the call to <function>cyg_mutex_lock</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
477 is allowed to continue, which at some point involves unlocking the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
478 scheduler. The pending DSR can now run, safely post the semaphore, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
479 thus wake up thread A.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
480 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
481 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
482 If the ISR had called <function>cyg_semaphore_post</function> directly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
483 rather than leaving it to a DSR, it is likely that there would have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
484 been some sort of corruption of a kernel data structure. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
485 the kernel might have completely lost track of one of the threads, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
486 that thread would never have run again. The two-level approach to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
487 interrupt handling, ISR's and DSR's, prevents such problems with no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
488 need to disable interrupts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
489 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
490 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
491
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
492 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
493 <!-- {{{ Calling contexts -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
494
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
495 <refsect1 id="kernel-overview-contexts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
496 <title>Calling Contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
497 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
498 eCos defines a number of contexts. Only certain calls are allowed from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
499 inside each context, for example most operations on threads or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
500 synchronization primitives are not allowed from ISR context. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
501 different contexts are initialization, thread, ISR and DSR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
502 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
503 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
504 When eCos starts up it goes through a number of phases, including
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
505 setting up the hardware and invoking C++ static constructors. During
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
506 this time interrupts are disabled and the scheduler is locked. When a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
507 configuration includes the kernel package the final operation is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
508 call to <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
509 linkend="kernel-schedcontrol"><function>cyg_scheduler_start</function></link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
510 At this point interrupts are enabled, the scheduler is unlocked, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
511 control is transferred to the highest priority runnable thread. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
512 configuration also includes the C library package then usually the C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
513 library startup package will have created a thread which will call the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
514 application's <function>main</function> entry point.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
515 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
516 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
517 Some application code can also run before the scheduler is started,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
518 and this code runs in initialization context. If the application is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
519 written partly or completely in C++ then the constructors for any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
520 static objects will be run. Alternatively application code can define
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
521 a function <function>cyg_user_start</function> which gets called after
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
522 any C++ static constructors. This allows applications to be written
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
523 entirely in C.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
524 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
525 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
526 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
527 cyg_user_start(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
528 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
529 /* Perform application-specific initialization here */
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
530 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
531 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
532 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
533 It is not necessary for applications to provide a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
534 <function>cyg_user_start</function> function since the system will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
535 provide a default implementation which does nothing.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
536 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
537 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
538 Typical operations that are performed from inside static constructors
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
539 or <function>cyg_user_start</function> include creating threads,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
540 synchronization primitives, setting up alarms, and registering
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
541 application-specific interrupt handlers. In fact for many applications
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
542 all such creation operations happen at this time, using statically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
543 allocated data, avoiding any need for dynamic memory allocation or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
544 other overheads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
545 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
546 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
547 Code running in initialization context runs with interrupts disabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
548 and the scheduler locked. It is not permitted to reenable interrupts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
549 or unlock the scheduler because the system is not guaranteed to be in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
550 a totally consistent state at this point. A consequence is that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
551 initialization code cannot use synchronization primitives such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
552 <function>cyg_semaphore_wait</function> to wait for an external event.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
553 It is permitted to lock and unlock a mutex: there are no other threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
554 running so it is guaranteed that the mutex is not yet locked, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
555 therefore the lock operation will never block; this is useful when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
556 making library calls that may use a mutex internally.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
557 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
558 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
559 At the end of the startup sequence the system will call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
560 <function>cyg_scheduler_start</function> and the various threads will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
561 start running. In thread context nearly all of the kernel functions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
562 are available. There may be some restrictions on interrupt-related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
563 operations, depending on the target hardware. For example the hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
564 may require that interrupts be acknowledged in the ISR or DSR before
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
565 control returns to thread context, in which case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
566 <filename>cyg_interrupt_acknowledge</filename> should not be called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
567 by a thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
568 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
569 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
570 At any time the processor may receive an external interrupt, causing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
571 control to be transferred from the current thread. Typically a VSR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
572 provided by eCos will run and determine exactly which interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
573 occurred. Then the VSR will switch to the appropriate ISR, which can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
574 be provided by a HAL package, a device driver, or by the application.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
575 During this time the system is running at ISR context, and most of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
576 kernel function calls are disallowed. This includes the various
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
577 synchronization primitives, so for example an ISR is not allowed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
578 post to a semaphore to indicate that an event has happened. Usually
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
579 the only operations that should be performed from inside an ISR are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
580 ones related to the interrupt subsystem itself, for example masking an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
581 interrupt or acknowledging that an interrupt has been processed. On
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
582 SMP systems it is also possible to use spinlocks from ISR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
583 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
584 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
585 When an ISR returns it can request that the corresponding DSR be run
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
586 as soon as it is safe to do so, and that will run in DSR context. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
587 context is also used for running alarm functions, and threads can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
588 switch temporarily to DSR context by locking the scheduler. Only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
589 certain kernel functions can be called from DSR context, although more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
590 than in ISR context. In particular it is possible to use any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
591 synchronization primitives which cannot block. These include
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
592 <function>cyg_semaphore_post</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
593 <filename>cyg_cond_signal</filename>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
594 <function>cyg_cond_broadcast</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
595 <function>cyg_flag_setbits</function>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
596 <function>cyg_mbox_tryput</function>. It is not possible to use any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
597 primitives that may block such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
598 <function>cyg_semaphore_wait</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
599 <function>cyg_mutex_lock</function>, or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
600 <function>cyg_mbox_put</function>. Calling such functions from inside
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
601 a DSR may cause the system to hang.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
602 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
603 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
604 The specific documentation for the various kernel functions gives more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
605 details about valid contexts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
606 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
607 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
608
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
609 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
610 <!-- {{{ Error handling -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
611
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
612 <refsect1 id="kernel-overview-errors">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
613 <title>Error Handling and Assertions</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
614 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
615 In many APIs each function is expected to perform some validation of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
616 its parameters and possibly of the current state of the system. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
617 is supposed to ensure that each function is used correctly, and that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
618 application code is not attempting to perform a semaphore operation on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
619 a mutex or anything like that. If an error is detected then a suitable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
620 error code is returned, for example the POSIX function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
621 <function>pthread_mutex_lock</function> can return various error codes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
622 including <literal>EINVAL</literal> and <literal>EDEADLK</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
623 There are a number of problems with this approach, especially in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
624 context of deeply embedded systems:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
625 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
626 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
627 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
628 Performing these checks inside the mutex lock and all the other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
629 functions requires extra cpu cycles and adds significantly to the code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
630 size. Even if the application is written correctly and only makes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
631 system function calls with sensible arguments and under the right
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
632 conditions, these overheads still exist.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
633 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
634 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
635 Returning an error code is only useful if the calling code detects
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
636 these error codes and takes appropriate action. In practice the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
637 calling code will often ignore any errors because the programmer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
638 <emphasis>&ldquo;knows&rdquo;</emphasis> that the function is being
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
639 used correctly. If the programmer is mistaken then an error condition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
640 may be detected and reported, but the application continues running
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
641 anyway and is likely to fail some time later in mysterious ways.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
642 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
643 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
644 If the calling code does always check for error codes, that adds yet
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
645 more cpu cycles and code size overhead.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
646 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
647 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
648 Usually there will be no way to recover from certain errors, so if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
649 application code detected an error such as <literal>EINVAL</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
650 then all it could do is abort the application somehow.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
651 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
652 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
653 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
654 The approach taken within the eCos kernel is different. Functions such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
655 as <function>cyg_mutex_lock</function> will not return an error code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
656 Instead they contain various assertions, which can be enabled or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
657 disabled. During the development process assertions are normally left
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
658 enabled, and the various kernel functions will perform parameter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
659 checks and other system consistency checks. If a problem is detected
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
660 then an assertion failure will be reported and the application will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
661 terminated. In a typical debug session a suitable breakpoint will have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
662 been installed and the developer can now examine the state of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
663 system and work out exactly what is going on. Towards the end of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
664 development cycle assertions will be disabled by manipulating
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
665 configuration options within the eCos infrastructure package, and all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
666 assertions will be eliminated at compile-time. The assumption is that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
667 by this time the application code has been mostly debugged: the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
668 initial version of the code might have tried to perform a semaphore
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
669 operation on a mutex, but any problems like that will have been fixed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
670 some time ago. This approach has a number of advantages:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
671 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
672 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
673 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
674 In the final application there will be no overheads for checking
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
675 parameters and other conditions. All that code will have been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
676 eliminated at compile-time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
677 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
678 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
679 Because the final application will not suffer any overheads, it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
680 reasonable for the system to do more work during the development
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
681 process. In particular the various assertions can test for more error
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
682 conditions and more complicated errors. When an error is detected
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
683 it is possible to give a text message describing the error rather than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
684 just return an error code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
685 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
686 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
687 There is no need for application programmers to handle error codes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
688 returned by various kernel function calls. This simplifies the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
689 application code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
690 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
691 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
692 If an error is detected then an assertion failure will be reported
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
693 immediately and the application will be halted. There is no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
694 possibility of an error condition being ignored because application
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
695 code did not check for an error code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
696 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
697 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
698 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
699 Although none of the kernel functions return an error code, many of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
700 them do return a status condition. For example the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
701 <function>cyg_semaphore_timed_wait</function> waits until either an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
702 event has been posted to a semaphore, or until a certain number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
703 clock ticks have occurred. Usually the calling code will need to know
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
704 whether the wait operation succeeded or whether a timeout occurred.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
705 <function>cyg_semaphore_timed_wait</function> returns a boolean: a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
706 return value of zero or false indicates a timeout, a non-zero return
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
707 value indicates that the wait succeeded.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
708 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
709 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
710 In conventional APIs one common error conditions is lack of memory.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
711 For example the POSIX function <function>pthread_create</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
712 usually has to allocate some memory dynamically for the thread stack
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
713 and other per-thread data. If the target hardware does not have enough
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
714 memory to meet all demands, or more commonly if the application
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
715 contains a memory leak, then there may not be enough memory available
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
716 and the function call would fail. The eCos kernel avoids such problems
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
717 by never performing any dynamic memory allocation. Instead it is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
718 responsibility of the application code to provide all the memory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
719 required for kernel data structures and other needs. In the case of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
720 <function>cyg_thread_create</function> this means a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
721 <structname>cyg_thread</structname> data structure to hold the thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
722 details, and a <type>char</type> array for the thread stack.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
723 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
724 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
725 In many applications this approach results in all data structures
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
726 being allocated statically rather than dynamically. This has several
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
727 advantages. If the application is in fact too large for the target
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
728 hardware's memory then there will be an error at link-time rather than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
729 at run-time, making the problem much easier to diagnose. Static
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
730 allocation does not involve any of the usual overheads associated with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
731 dynamic allocation, for example there is no need to keep track of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
732 various free blocks in the system, and it may be possible to eliminate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
733 <function>malloc</function> from the system completely. Problems such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
734 as fragmentation and memory leaks cannot occur if all data is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
735 allocated statically. However, some applications are sufficiently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
736 complicated that dynamic memory allocation is required, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
737 various kernel functions do not distinguish between statically and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
738 dynamically allocated memory. It still remains the responsibility of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
739 the calling code to ensure that sufficient memory is available, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
740 passing null pointers to the kernel will result in assertions or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
741 system failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
742 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
743 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
744
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
745 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
746
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
747 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
748
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
749 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
750 <!-- {{{ SMP -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
751
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
752 <refentry id="kernel-SMP">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
753
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
754 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
755 <refentrytitle>SMP Support</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
756 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
757
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
758 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
759 <refname>SMP</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
760 <refpurpose>Support Symmetric Multiprocessing Systems</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
761 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
762
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
763 <refsect1 id="kernel-smp-description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
764 <title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
765 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
766 eCos contains support for limited Symmetric Multi-Processing (SMP).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
767 This is only available on selected architectures and platforms.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
768 The implementation has a number of restrictions on the kind of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
769 hardware supported. These are described in <xref linkend="hal-smp-support">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
770 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
771
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
772 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
773 The following sections describe the changes that have been made to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
774 eCos kernel to support SMP operation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
775 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
776 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
777
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
778 <refsect1 id="kernel-smp-startup">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
779 <title>System Startup</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
780 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
781 The system startup sequence needs to be somewhat different on an SMP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
782 system, although this is largely transparent to application code. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
783 main startup takes place on only one CPU, called the primary CPU. All
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
784 other CPUs, the secondary CPUs, are either placed in suspended state
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
785 at reset, or are captured by the HAL and put into a spin as they start
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
786 up. The primary CPU is responsible for copying the DATA segment and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
787 zeroing the BSS (if required), calling HAL variant and platform
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
788 initialization routines and invoking constructors. It then calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
789 <function>cyg_start</function> to enter the application. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
790 application may then create extra threads and other objects.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
791 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
792 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
793 It is only when the application calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
794 <function>cyg_scheduler_start</function> that the secondary CPUs are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
795 initialized. This routine scans the list of available secondary CPUs
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
796 and invokes <function>HAL_SMP_CPU_START</function> to start each
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
797 CPU. Finally it calls an internal function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
798 <function>Cyg_Scheduler::start_cpu</function> to enter the scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
799 for the primary CPU.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
800 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
801 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
802 Each secondary CPU starts in the HAL, where it completes any per-CPU
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
803 initialization before calling into the kernel at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
804 <function>cyg_kernel_cpu_startup</function>. Here it claims the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
805 scheduler lock and calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
806 <function>Cyg_Scheduler::start_cpu</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
807 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
808 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
809 <function>Cyg_Scheduler::start_cpu</function> is common to both the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
810 primary and secondary CPUs. The first thing this code does is to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
811 install an interrupt object for this CPU's inter-CPU interrupt. From
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
812 this point on the code is the same as for the single CPU case: an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
813 initial thread is chosen and entered.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
814 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
815 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
816 From this point on the CPUs are all equal, eCos makes no further
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
817 distinction between the primary and secondary CPUs. However, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
818 hardware may still distinguish between them as far as interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
819 delivery is concerned.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
820 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
821 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
822
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
823 <refsect1 id="kernel-smp-scheduling">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
824 <title>Scheduling</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
825 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
826 To function correctly an operating system kernel must protect its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
827 vital data structures, such as the run queues, from concurrent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
828 access. In a single CPU system the only concurrent activities to worry
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
829 about are asynchronous interrupts. The kernel can easily guard its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
830 data structures against these by disabling interrupts. However, in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
831 multi-CPU system, this is inadequate since it does not block access by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
832 other CPUs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
833 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
834 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
835 The eCos kernel protects its vital data structures using the scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
836 lock. In single CPU systems this is a simple counter that is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
837 atomically incremented to acquire the lock and decremented to release
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
838 it. If the lock is decremented to zero then the scheduler may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
839 invoked to choose a different thread to run. Because interrupts may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
840 continue to be serviced while the scheduler lock is claimed, ISRs are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
841 not allowed to access kernel data structures, or call kernel routines
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
842 that can. Instead all such operations are deferred to an associated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
843 DSR routine that is run during the lock release operation, when the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
844 data structures are in a consistent state.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
845 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
846 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
847 By choosing a kernel locking mechanism that does not rely on interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
848 manipulation to protect data structures, it is easier to convert eCos
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
849 to SMP than would otherwise be the case. The principal change needed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
850 make eCos SMP-safe is to convert the scheduler lock into a nestable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
851 spin lock. This is done by adding a spinlock and a CPU id to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
852 original counter.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
853 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
854 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
855 The algorithm for acquiring the scheduler lock is very simple. If the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
856 scheduler lock's CPU id matches the current CPU then it can just increment
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
857 the counter and continue. If it does not match, the CPU must spin on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
858 the spinlock, after which it may increment the counter and store its
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
859 own identity in the CPU id.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
860 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
861 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
862 To release the lock, the counter is decremented. If it goes to zero
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
863 the CPU id value must be set to NONE and the spinlock cleared.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
864 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
865 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
866 To protect these sequences against interrupts, they must be performed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
867 with interrupts disabled. However, since these are very short code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
868 sequences, they will not have an adverse effect on the interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
869 latency.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
870 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
871 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
872 Beyond converting the scheduler lock, further preparing the kernel for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
873 SMP is a relatively minor matter. The main changes are to convert
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
874 various scalar housekeeping variables into arrays indexed by CPU
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
875 id. These include the current thread pointer, the need_reschedule
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
876 flag and the timeslice counter.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
877 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
878 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
879 At present only the Multi-Level Queue (MLQ) scheduler is capable of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
880 supporting SMP configurations. The main change made to this scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
881 is to cope with having several threads in execution at the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
882 time. Running threads are marked with the CPU that they are executing on.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
883 When scheduling a thread, the scheduler skips past any running threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
884 until it finds a thread that is pending. While not a constant-time
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
885 algorithm, as in the single CPU case, this is still deterministic,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
886 since the worst case time is bounded by the number of CPUs in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
887 system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
888 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
889 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
890 A second change to the scheduler is in the code used to decide when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
891 the scheduler should be called to choose a new thread. The scheduler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
892 attempts to keep the <property>n</property> CPUs running the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
893 <property>n</property> highest priority threads. Since an event or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
894 interrupt on one CPU may require a reschedule on another CPU, there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
895 must be a mechanism for deciding this. The algorithm currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
896 implemented is very simple. Given a thread that has just been awakened
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
897 (or had its priority changed), the scheduler scans the CPUs, starting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
898 with the one it is currently running on, for a current thread that is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
899 of lower priority than the new one. If one is found then a reschedule
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
900 interrupt is sent to that CPU and the scan continues, but now using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
901 the current thread of the rescheduled CPU as the candidate thread. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
902 this way the new thread gets to run as quickly as possible, hopefully
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
903 on the current CPU, and the remaining CPUs will pick up the remaining
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
904 highest priority threads as a consequence of processing the reschedule
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
905 interrupt.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
906 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
907 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
908 The final change to the scheduler is in the handling of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
909 timeslicing. Only one CPU receives timer interrupts, although all CPUs
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
910 must handle timeslicing. To make this work, the CPU that receives the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
911 timer interrupt decrements the timeslice counter for all CPUs, not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
912 just its own. If the counter for a CPU reaches zero, then it sends a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
913 timeslice interrupt to that CPU. On receiving the interrupt the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
914 destination CPU enters the scheduler and looks for another thread at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
915 the same priority to run. This is somewhat more efficient than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
916 distributing clock ticks to all CPUs, since the interrupt is only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
917 needed when a timeslice occurs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
918 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
919 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
920 All existing synchronization mechanisms work as before in an SMP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
921 system. Additional synchronization mechanisms have been added to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
922 provide explicit synchronization for SMP, in the form of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
923 <link linkend="kernel-spinlocks">spinlocks</link>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
924 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
925 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
926
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
927 <refsect1 id="kernel-smp-interrupts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
928 <title>SMP Interrupt Handling</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
929 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
930 The main area where the SMP nature of a system requires special
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
931 attention is in device drivers and especially interrupt handling. It
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
932 is quite possible for the ISR, DSR and thread components of a device
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
933 driver to execute on different CPUs. For this reason it is much more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
934 important that SMP-capable device drivers use the interrupt-related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
935 functions correctly. Typically a device driver would use the driver
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
936 API rather than call the kernel directly, but it is unlikely that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
937 anybody would attempt to use a multiprocessor system without the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
938 kernel package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
939 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
940 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
941 Two new functions have been added to the Kernel API
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
942 to do <link linkend="kernel-interrupts-smp">interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
943 routing</link>: <function>cyg_interrupt_set_cpu</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
944 <function>cyg_interrupt_get_cpu</function>. Although not currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
945 supported, special values for the cpu argument may be used in future
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
946 to indicate that the interrupt is being routed dynamically or is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
947 CPU-local. Once a vector has been routed to a new CPU, all other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
948 interrupt masking and configuration operations are relative to that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
949 CPU, where relevant.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
950 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
951
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
952 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
953 There are more details of how interrupts should be handled in SMP
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
954 systems in <xref linkend="devapi-smp-support">.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
955 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
956 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
957
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
958 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
959
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
960 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
961
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
962 <!-- {{{ cyg_thread_create() -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
963
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
964 <refentry id="kernel-thread-create">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
965
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
966 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
967 <refentrytitle>Thread creation</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
968 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
969
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
970 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
971 <refname>cyg_thread_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
972 <refpurpose>Create a new thread</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
973 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
974
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
975 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
976 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
977 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
978 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
979 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
980 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
981 <funcdef>void <function>cyg_thread_create</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
982 <paramdef>cyg_addrword_t <parameter>sched_info</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
983 <paramdef>cyg_thread_entry_t* <parameter>entry</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
984 <paramdef>cyg_addrword_t <parameter>entry_data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
985 <paramdef>char* <parameter>name</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
986 <paramdef>void* <parameter>stack_base</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
987 <paramdef>cyg_ucount32 <parameter>stack_size</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
988 <paramdef>cyg_handle_t* <parameter>handle</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
989 <paramdef>cyg_thread* <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
990 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
991 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
992 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
993
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
994 <refsect1 id="kernel-thread-create-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
995 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
996 The <function>cyg_thread_create</function> function allows application
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
997 code and eCos packages to create new threads. In many applications
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
998 this only happens during system initialization and all required data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
999 is allocated statically. However additional threads can be created at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1000 any time, if necessary. A newly created thread is always in suspended
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1001 state and will not start running until it has been resumed via a call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1002 to <function>cyg_thread_resume</function>. Also, if threads are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1003 created during system initialization then they will not start running
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1004 until the eCos scheduler has been started.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1005 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1006 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1007 The <parameter class="function">name</parameter> argument is used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1008 primarily for debugging purposes, making it easier to keep track of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1009 which <structname>cyg_thread</structname> structure is associated with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1010 which application-level thread. The kernel configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1011 <varname>CYGVAR_KERNEL_THREADS_NAME</varname> controls whether or not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1012 this name is actually used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1013 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1014 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1015 On creation each thread is assigned a unique handle, and this will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1016 stored in the location pointed at by the <parameter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1017 class="function">handle</parameter> argument. Subsequent operations on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1018 this thread including the required
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1019 <function>cyg_thread_resume</function> should use this handle to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1020 identify the thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1021 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1022 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1023 The kernel requires a small amount of space for each thread, in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1024 form of a <structname>cyg_thread</structname> data structure, to hold
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1025 information such as the current state of that thread. To avoid any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1026 need for dynamic memory allocation within the kernel this space has to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1027 be provided by higher-level code, typically in the form of a static
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1028 variable. The <parameter class="function">thread</parameter> argument
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1029 provides this space.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1030 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1031 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1032
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1033 <refsect1 id="kernel-thread-create-entry"><title>Thread Entry Point</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1034 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1035 The entry point for a thread takes the form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1036 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1037 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1038 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1039 thread_entry_function(cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1040 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1041 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1042 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1043 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1044 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1045 The second argument to <function>cyg_thread_create</function> is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1046 pointer to such a function. The third argument <parameter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1047 class="function">entry_data</parameter> is used to pass additional
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1048 data to the function. Typically this takes the form of a pointer to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1049 some static data, or a small integer, or <literal>0</literal> if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1050 thread does not require any additional data.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1051 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1052 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1053 If the thread entry function ever returns then this is equivalent to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1054 the thread calling <function>cyg_thread_exit</function>. Even though
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1055 the thread will no longer run again, it remains registered with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1056 scheduler. If the application needs to re-use the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1057 <structname>cyg_thread</structname> data structure then a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1058 <function>cyg_thread_delete</function> is required first.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1059 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1060 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1061
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1062 <refsect1 id="kernel-thread-create-priorities"><title>Thread Priorities</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1063 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1064 The <parameter class="function">sched_info</parameter> argument
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1065 provides additional information to the scheduler. The exact details
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1066 depend on the scheduler being used. For the bitmap and mlqueue
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1067 schedulers it is a small integer, typically in the range 0 to 31, with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1068 0 being the highest priority. The lowest priority is normally used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1069 only by the system's idle thread. The exact number of priorities is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1070 controlled by the kernel configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1071 <varname>CYGNUM_KERNEL_SCHED_PRIORITIES</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1072 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1073 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1074 It is the responsibility of the application developer to be aware of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1075 the various threads in the system, including those created by eCos
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1076 packages, and to ensure that all threads run at suitable priorities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1077 For threads created by other packages the documentation provided by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1078 those packages should indicate any requirements.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1079 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1080 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1081 The functions <function>cyg_thread_set_priority</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1082 <function>cyg_thread_get_priority</function>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1083 <function>cyg_thread_get_current_priority</function> can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1084 manipulate a thread's priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1085 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1086 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1087
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1088 <refsect1 id="kernel-thread-create-stack"><title>Stacks and Stack Sizes</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1089 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1090 Each thread needs its own stack for local variables and to keep track
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1091 of function calls and returns. Again it is expected that this stack is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1092 provided by the calling code, usually in the form of static data, so
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1093 that the kernel does not need any dynamic memory allocation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1094 facilities. <function>cyg_thread_create</function> takes two arguments
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1095 related to the stack, a pointer to the base of the stack and the total
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1096 size of this stack. On many processors stacks actually descend from the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1097 top down, so the kernel will add the stack size to the base address to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1098 determine the starting location.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1099 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1100 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1101 The exact stack size requirements for any given thread depend on a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1102 number of factors. The most important is of course the code that will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1103 be executed in the context of this code: if this involves significant
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1104 nesting of function calls, recursion, or large local arrays, then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1105 stack size needs to be set to a suitably high value. There are some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1106 architectural issues, for example the number of cpu registers and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1107 calling conventions will have some effect on stack usage. Also,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1108 depending on the configuration, it is possible that some other code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1109 such as interrupt handlers will occasionally run on the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1110 thread's stack. This depends in part on configuration options such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1111 <varname>CYGIMP_HAL_COMMON_INTERRUPTS_USE_INTERRUPT_STACK</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1112 and <varname>CYGSEM_HAL_COMMON_INTERRUPTS_ALLOW_NESTING</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1113 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1114 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1115 Determining an application's actual stack size requirements is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1116 responsibility of the application developer, since the kernel cannot
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1117 know in advance what code a given thread will run. However, the system
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1118 does provide some hints about reasonable stack sizes in the form of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1119 two constants: <varname>CYGNUM_HAL_STACK_SIZE_MINIMUM</varname> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1120 <varname>CYGNUM_HAL_STACK_SIZE_TYPICAL</varname>. These are defined by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1121 the appropriate HAL package. The <varname>MINIMUM</varname> value is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1122 appropriate for a thread that just runs a single function and makes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1123 very simple system calls. Trying to create a thread with a smaller
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1124 stack than this is illegal. The <varname>TYPICAL</varname> value is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1125 appropriate for applications where application calls are nested no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1126 more than half a dozen or so levels, and there are no large arrays on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1127 the stack.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1128 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1129 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1130 If the stack sizes are not estimated correctly and a stack overflow
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1131 occurs, the probably result is some form of memory corruption. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1132 can be very hard to track down. The kernel does contain some code to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1133 help detect stack overflows, controlled by the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1134 <varname>CYGFUN_KERNEL_THREADS_STACK_CHECKING</varname>: a small
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1135 amount of space is reserved at the stack limit and filled with a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1136 special signature: every time a thread context switch occurs this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1137 signature is checked, and if invalid that is a good indication (but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1138 not absolute proof) that a stack overflow has occurred. This form of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1139 stack checking is enabled by default when the system is built with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1140 debugging enabled. A related configuration option is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1141 <varname>CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</varname>: enabling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1142 this option means that a thread can call the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1143 <function>cyg_thread_measure_stack_usage</function> to find out the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1144 maximum stack usage to date. Note that this is not necessarily the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1145 true maximum because, for example, it is possible that in the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1146 run no interrupt occurred at the worst possible moment.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1147 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1148 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1149
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1150 <refsect1 id="kernel-thread-create-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1151 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1152 <function>cyg_thread_create</function> may be called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1153 initialization and from within thread context. It may not be called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1154 from inside a DSR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1155 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1156 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1157
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1158 <refsect1 id="kernel-thread-create-example"><title>Example</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1159 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1160 A simple example of thread creation is shown below. This involves
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1161 creating five threads, one producer and four consumers or workers. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1162 threads are created in the system's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1163 <function>cyg_user_start</function>: depending on the configuration it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1164 might be more appropriate to do this elsewhere, for example inside
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1165 <function>main</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1166 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1167 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1168 #include &lt;cyg/hal/hal_arch.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1169 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1170
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1171 // These numbers depend entirely on your application
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1172 #define NUMBER_OF_WORKERS 4
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1173 #define PRODUCER_PRIORITY 10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1174 #define WORKER_PRIORITY 11
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1175 #define PRODUCER_STACKSIZE CYGNUM_HAL_STACK_SIZE_TYPICAL
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1176 #define WORKER_STACKSIZE (CYGNUM_HAL_STACK_SIZE_MINIMUM + 1024)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1177
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1178 static unsigned char producer_stack[PRODUCER_STACKSIZE];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1179 static unsigned char worker_stacks[NUMBER_OF_WORKERS][WORKER_STACKSIZE];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1180 static cyg_handle_t producer_handle, worker_handles[NUMBER_OF_WORKERS];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1181 static cyg_thread_t producer_thread, worker_threads[NUMBER_OF_WORKERS];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1182
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1183 static void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1184 producer(cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1185 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1186 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1187 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1188
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1189 static void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1190 worker(cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1191 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1192 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1193 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1194
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1195 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1196 cyg_user_start(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1197 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1198 int i;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1199
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1200 cyg_thread_create(PRODUCER_PRIORITY, &amp;producer, 0, "producer",
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1201 producer_stack, PRODUCER_STACKSIZE,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1202 &amp;producer_handle, &amp;producer_thread);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1203 cyg_thread_resume(producer_handle);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1204 for (i = 0; i < NUMBER_OF_WORKERS; i++) {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1205 cyg_thread_create(WORKER_PRIORITY, &amp;worker, i, "worker",
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1206 worker_stacks[i], WORKER_STACKSIZE,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1207 &amp;(worker_handles[i]), &amp;(worker_threads[i]));
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1208 cyg_thread_resume(worker_handles[i]);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1209 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1210 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1211 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1212 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1213
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1214
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1215 <refsect1 id="kernel-thread-create-cxx"><title>Thread Entry Points and C++</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1216 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1217 For code written in C++ the thread entry function must be either a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1218 static member function of a class or an ordinary function outside any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1219 class. It cannot be a normal member function of a class because such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1220 member functions take an implicit additional argument
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1221 <varname>this</varname>, and the kernel has no way of knowing what
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1222 value to use for this argument. One way around this problem is to make
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1223 use of a special static member function, for example:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1224 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1225 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1226 class fred {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1227 public:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1228 void thread_function();
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1229 static void static_thread_aux(cyg_addrword_t);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1230 };
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1231
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1232 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1233 fred::static_thread_aux(cyg_addrword_t objptr)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1234 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1235 fred* object = static_cast&lt;fred*&gt;(objptr);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1236 object-&gt;thread_function();
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1237 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1238
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1239 static fred instance;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1240
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1241 extern "C" void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1242 cyg_start( void )
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1243 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1244 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1245 cyg_thread_create( &hellip;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1246 &amp;fred::static_thread_aux,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1247 static_cast&lt;cyg_addrword_t&gt;(&amp;instance),
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1248 &hellip;);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1249 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1250 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1251 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1252 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1253 Effectively this uses the <parameter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1254 class="function">entry_data</parameter> argument to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1255 <function>cyg_thread_create</function> to hold the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1256 <varname>this</varname> pointer. Unfortunately this approach does
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1257 require the use of some C++ casts, so some of the type safety that can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1258 be achieved when programming in C++ is lost.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1259 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1260 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1261
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1262 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1263
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1264 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1265 <!-- {{{ Thread info -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1266
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1267 <refentry id="kernel-thread-info">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1268
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1269 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1270 <refentrytitle>Thread information</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1271 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1272
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1273 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1274 <refname>cyg_thread_self</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1275 <refname>cyg_thread_idle_thread</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1276 <refname>cyg_thread_get_stack_base</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1277 <refname>cyg_thread_get_stack_size</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1278 <refname>cyg_thread_measure_stack_usage</refname>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1279 <refname>cyg_thread_get_next</refname>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1280 <refname>cyg_thread_get_info</refname>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1281 <refname>cyg_thread_find</refname>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1282 <refpurpose>Get basic thread information</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1283 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1284
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1285 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1286 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1287 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1288 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1289 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1290 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1291 <funcdef>cyg_handle_t <function>cyg_thread_self</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1292 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1293 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1294 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1295 <funcdef>cyg_handle_t <function>cyg_thread_idle_thread</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1296 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1297 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1298 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1299 <funcdef>cyg_addrword_t <function>cyg_thread_get_stack_base</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1300 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1301 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1302 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1303 <funcdef>cyg_uint32 <function>cyg_thread_get_stack_size</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1304 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1305 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1306 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1307 <funcdef>cyg_uint32 <function>cyg_thread_measure_stack_usage</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1308 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1309 </funcprototype>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1310 <funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1311 <funcdef>cyg_bool <function>cyg_thread_get_next</function></funcdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1312 <paramdef>cyg_handle_t *<parameter>thread</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1313 <paramdef>cyg_uint16 *<parameter>id</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1314 </funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1315 <funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1316 <funcdef>cyg_bool <function>cyg_thread_get_info</function></funcdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1317 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1318 <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1319 <paramdef>cyg_thread_info *<parameter>info</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1320 </funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1321 <funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1322 <funcdef>cyg_handle_t <function>cyg_thread_find</function></funcdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1323 <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1324 </funcprototype>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1325 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1326 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1327
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1328 <refsect1 id="kernel-thread-info-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1329 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1330 These functions can be used to obtain some basic information about
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1331 various threads in the system. Typically they serve little or no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1332 purpose in real applications, but they can be useful during debugging.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1333 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1334 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1335 <function>cyg_thread_self</function> returns a handle corresponding
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1336 to the current thread. It will be the same as the value filled in by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1337 <function>cyg_thread_create</function> when the current thread was
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1338 created. This handle can then be passed to other functions such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1339 <function>cyg_thread_get_priority</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1340 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1341 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1342 <function>cyg_thread_idle_thread</function> returns the handle
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1343 corresponding to the idle thread. This thread is created automatically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1344 by the kernel, so application-code has no other way of getting hold of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1345 this information.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1346 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1347 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1348 <function>cyg_thread_get_stack_base</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1349 <function>cyg_thread_get_stack_size</function> return information
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1350 about a specific thread's stack. The values returned will match the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1351 values passed to <function>cyg_thread_create</function> when this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1352 thread was created.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1353 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1354 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1355 <function>cyg_thread_measure_stack_usage</function> is only available
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1356 if the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1357 <varname>CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</varname> is enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1358 The return value is the maximum number of bytes of stack space used so
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1359 far by the specified thread. Note that this should not be considered a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1360 true upper bound, for example it is possible that in the current test
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1361 run the specified thread has not yet been interrupted at the deepest
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1362 point in the function call graph. Never the less the value returned
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1363 can give some useful indication of the thread's stack requirements.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1364 </para>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1365 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1366 <function>cyg_thread_get_next</function> is used to enumerate all the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1367 current threads in the system. It should be called intially with the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1368 locations pointed to by <parameter>thread</parameter> and
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1369 <parameter>id</parameter> set to zero. On return these will be set to
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1370 the handle and ID of the first thread. On subsequent calls, these
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1371 parameters should be left set to the values returned by the previous
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1372 call. The handle and ID of the next thread in the system will be
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1373 installed each time, until a <literal>false</literal> return value
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1374 indicates the end of the list.
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1375 </para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1376 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1377 <function>cyg_thread_get_info</function> fills in the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1378 <type>cyg_thread_info</type> structure with information about the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1379 thread described by the <parameter>thread</parameter> and
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1380 <parameter>id</parameter> arguments. The information returned includes
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1381 the thread's handle and id, its state and name, priorities and stack
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1382 parameters. If the thread does not exist the function returns
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1383 <literal>false</literal>.
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1384 </para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1385 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1386 <function>cyg_thread_find</function> returns a handle for the thread
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1387 whose ID is <parameter>id</parameter>. If no such thread exists, a
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1388 zero handle is returned.
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1389 </para>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1390 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1391
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1392 <refsect1 id="kernel-thread-info-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1393 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1394 <function>cyg_thread_self</function> may only be called from thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1395 context. <function>cyg_thread_idle_thread</function> may be called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1396 from thread or DSR context, but only after the system has been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1397 initialized. <function>cyg_thread_get_stack_base</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1398 <function>cyg_thread_get_stack_size</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1399 <function>cyg_thread_measure_stack_usage</function> may be called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1400 any time after the specified thread has been created, but measuring
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1401 stack usage involves looping over at least part of the thread's stack
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1402 so this should normally only be done from thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1403 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1404 </refsect1>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1405
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1406 <refsect1 id="kernel-thread-info-examples"><title>Examples</title>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1407 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1408 A simple example of the use of the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1409 <function>cyg_thread_get_next</function> and
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1410 <function>cyg_thread_get_info</function> follows:
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1411 </para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1412 <programlisting width=72>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1413
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1414 #include &lt;cyg/kernel/kapi.h&gt;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1415 #include &lt;stdio.h&gt;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1416
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1417 void show_threads(void)
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1418 {
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1419 cyg_handle_t thread = 0;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1420 cyg_uint16 id = 0;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1421
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1422 while( cyg_thread_get_next( &amp;thread, &amp;id ) )
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1423 {
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1424 cyg_thread_info info;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1425
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1426 if( !cyg_thread_get_info( thread, id, &amp;info ) )
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1427 break;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1428
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1429 printf("ID: %04x name: %10s pri: %d\n",
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1430 info.id, info.name?info.name:"----", info.set_pri );
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1431 }
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1432 }
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1433
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1434 </programlisting>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1435 </refsect1>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1436
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1437 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1438
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1439 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1440 <!-- {{{ Thread control -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1441
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1442 <refentry id="kernel-thread-control">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1443
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1444 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1445 <refentrytitle>Thread control</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1446 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1447
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1448 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1449 <refname>cyg_thread_yield</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1450 <refname>cyg_thread_delay</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1451 <refname>cyg_thread_suspend</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1452 <refname>cyg_thread_resume</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1453 <refname>cyg_thread_release</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1454 <refpurpose>Control whether or not a thread is running</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1455 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1456
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1457 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1458 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1459 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1460 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1461 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1462 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1463 <funcdef>void <function>cyg_thread_yield</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1464 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1465 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1466 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1467 <funcdef>void <function>cyg_thread_delay</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1468 <paramdef>cyg_tick_count_t <parameter>delay</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1469 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1470 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1471 <funcdef>void <function>cyg_thread_suspend</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1472 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1473 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1474 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1475 <funcdef>void <function>cyg_thread_resume</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1476 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1477 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1478 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1479 <funcdef>void <function>cyg_thread_release</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1480 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1481 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1482 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1483 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1484
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1485 <refsect1><title id="kernel-thread-control-description">Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1486 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1487 These functions provide some control over whether or not a particular
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1488 thread can run. Apart from the required use of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1489 <function>cyg_thread_resume</function> to start a newly-created
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1490 thread, application code should normally use proper synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1491 primitives such as condition variables or mail boxes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1492 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1493 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1494
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1495 <refsect1><title id="kernel-thread-control-yield">Yield</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1496 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1497 <function>cyg_thread_yield</function> allows a thread to relinquish
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1498 control of the processor to some other runnable thread which has the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1499 same priority. This can have no effect on any higher-priority thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1500 since, if such a thread were runnable, the current thread would have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1501 been preempted in its favour. Similarly it can have no effect on any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1502 lower-priority thread because the current thread will always be run in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1503 preference to those. As a consequence this function is only useful
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1504 in configurations with a scheduler that allows multiple threads to run
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1505 at the same priority, for example the mlqueue scheduler. If instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1506 the bitmap scheduler was being used then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1507 <function>cyg_thread_yield()</function> would serve no purpose.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1508 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1509 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1510 Even if a suitable scheduler such as the mlqueue scheduler has been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1511 configured, <function>cyg_thread_yield</function> will still rarely
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1512 prove useful: instead timeslicing will be used to ensure that all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1513 threads of a given priority get a fair slice of the available
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1514 processor time. However it is possible to disable timeslicing via the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1515 configuration option <varname>CYGSEM_KERNEL_SCHED_TIMESLICE</varname>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1516 in which case <function>cyg_thread_yield</function> can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1517 implement a form of cooperative multitasking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1518 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1519 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1520
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1521 <refsect1><title id="kernel-thread-control-delay">Delay</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1522 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1523 <function>cyg_thread_delay</function> allows a thread to suspend until
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1524 the specified number of clock ticks have occurred. For example, if a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1525 value of 1 is used and the system clock runs at a frequency of 100Hz
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1526 then the thread will sleep for up to 10 milliseconds. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1527 functionality depends on the presence of a real-time system clock, as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1528 controlled by the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1529 <varname>CYGVAR_KERNEL_COUNTERS_CLOCK</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1530 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1531 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1532 If the application requires delays measured in milliseconds or similar
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1533 units rather than in clock ticks, some calculations are needed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1534 convert between these units as described in <xref
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1535 linkend="kernel-clocks">. Usually these calculations can be done by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1536 the application developer, or at compile-time. Performing such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1537 calculations prior to every call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1538 <function>cyg_thread_delay</function> adds unnecessary overhead to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1539 system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1540 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1541 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1542
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1543 <refsect1><title id="kernel-thread-control-suspend">Suspend and Resume</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1544 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1545 Associated with each thread is a suspend counter. When a thread is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1546 first created this counter is initialized to 1.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1547 <function>cyg_thread_suspend</function> can be used to increment the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1548 suspend counter, and <function>cyg_thread_resume</function> decrements
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1549 it. The scheduler will never run a thread with a non-zero suspend
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1550 counter. Therefore a newly created thread will not run until it has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1551 been resumed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1552 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1553 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1554 An occasional problem with the use of suspend and resume functionality
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1555 is that a thread gets suspended more times than it is resumed and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1556 hence never becomes runnable again. This can lead to very confusing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1557 behaviour. To help with debugging such problems the kernel provides a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1558 configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1559 <varname>CYGNUM_KERNEL_MAX_SUSPEND_COUNT_ASSERT</varname> which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1560 imposes an upper bound on the number of suspend calls without matching
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1561 resumes, with a reasonable default value. This functionality depends
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1562 on infrastructure assertions being enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1563 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1564 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1565
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1566 <refsect1><title id="kernel-thread-control-release">Releasing a Blocked Thread</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1567 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1568 When a thread is blocked on a synchronization primitive such as a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1569 semaphore or a mutex, or when it is waiting for an alarm to trigger,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1570 it can be forcibly woken up using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1571 <function>cyg_thread_release</function>. Typically this will call the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1572 affected synchronization primitive to return false, indicating that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1573 the operation was not completed successfully. This function has to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1574 used with great care, and in particular it should only be used on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1575 threads that have been designed appropriately and check all return
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1576 codes. If instead it were to be used on, say, an arbitrary thread that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1577 is attempting to claim a mutex then that thread might not bother to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1578 check the result of the mutex lock operation - usually there would be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1579 no reason to do so. Therefore the thread will now continue running in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1580 the false belief that it has successfully claimed a mutex lock, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1581 the resulting behaviour is undefined. If the system has been built
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1582 with assertions enabled then it is possible that an assertion will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1583 trigger when the thread tries to release the mutex it does not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1584 actually own.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1585 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1586 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1587 The main use of <function>cyg_thread_release</function> is in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1588 POSIX compatibility layer, where it is used in the implementation of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1589 per-thread signals and cancellation handlers.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1590 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1591 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1592
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1593 <refsect1 id="kernel-thread-control-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1594 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1595 <function>cyg_thread_yield</function> can only be called from thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1596 context, A DSR must always run to completion and cannot yield the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1597 processor to some thread. <function>cyg_thread_suspend</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1598 <function>cyg_thread_resume</function>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1599 <function>cyg_thread_release</function> may be called from thread or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1600 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1601 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1602 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1603
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1604 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1605
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1606 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1607 <!-- {{{ Thread termination -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1608
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1609 <refentry id="kernel-thread-termination">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1610
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1611 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1612 <refentrytitle>Thread termination</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1613 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1614
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1615 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1616 <refname>cyg_thread_exit</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1617 <refname>cyg_thread_kill</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1618 <refname>cyg_thread_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1619 <refpurpose>Allow threads to terminate</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1620 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1621
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1622 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1623 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1624 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1625 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1626 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1627 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1628 <funcdef>void <function>cyg_thread_exit</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1629 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1630 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1631 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1632 <funcdef>void <function>cyg_thread_kill</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1633 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1634 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1635 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1636 <funcdef>void <function>cyg_thread_delete</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1637 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1638 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1639 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1640 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1641
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1642 <refsect1><title id="kernel-thread-termination-description">Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1643 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1644 In many embedded systems the various threads are allocated statically,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1645 created during initialization, and never need to terminate. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1646 avoids any need for dynamic memory allocation or other resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1647 management facilities. However if a given application does have a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1648 requirement that some threads be created dynamically, must terminate,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1649 and their resources such as the stack be reclaimed, then the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1650 provides the functions <function>cyg_thread_exit</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1651 <function>cyg_thread_kill</function>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1652 <function>cyg_thread_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1653 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1654 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1655 <function>cyg_thread_exit</function> allows a thread to terminate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1656 itself, thus ensuring that it will not be run again by the scheduler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1657 However the <structname>cyg_thread</structname> data structure passed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1658 to <function>cyg_thread_create</function> remains in use, and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1659 handle returned by <function>cyg_thread_create</function> remains
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1660 valid. This allows other threads to perform certain operations on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1661 terminated thread, for example to determine its stack usage via
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1662 <function>cyg_thread_measure_stack_usage</function>. When the handle
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1663 and <structname>cyg_thread</structname> structure are no longer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1664 required, <function>cyg_thread_delete</function> should be called to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1665 release these resources. If the stack was dynamically allocated then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1666 this should not be freed until after the call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1667 <function>cyg_thread_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1668 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1669 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1670 Alternatively, one thread may use <function>cyg_thread_kill</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1671 on another This has much the same effect as the affected thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1672 calling <function>cyg_thread_exit</function>. However killing a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1673 is generally rather dangerous because no attempt is made to unlock any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1674 synchronization primitives currently owned by that thread or release
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1675 any other resources that thread may have claimed. Therefore use of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1676 this function should be avoided, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1677 <function>cyg_thread_exit</function> is preferred.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1678 <function>cyg_thread_kill</function> cannot be used by a thread to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1679 kill itself.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1680 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1681 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1682 <function>cyg_thread_delete</function> should be used on a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1683 after it has exited and is no longer required. After this call the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1684 thread handle is no longer valid, and both the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1685 <structname>cyg_thread</structname> structure and the thread stack can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1686 be re-used or freed. If <function>cyg_thread_delete</function> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1687 invoked on a thread that is still running then there is an implicit
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1688 call to <function>cyg_thread_kill</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1689 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1690 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1691
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1692 <refsect1 id="kernel-thread-termination-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1693 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1694 <function>cyg_thread_exit</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1695 <function>cyg_thread_kill</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1696 <function>cyg_thread_delete</function> can only be called from thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1697 context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1698 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1699 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1700
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1701 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1702
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1703 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1704 <!-- {{{ Thread priorities -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1705
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1706 <refentry id="kernel-thread-priorities">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1707
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1708 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1709 <refentrytitle>Thread priorities</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1710 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1711
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1712 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1713 <refname>cyg_thread_get_priority</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1714 <refname>cyg_thread_get_current_priority</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1715 <refname>cyg_thread_set_priority</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1716 <refpurpose>Examine and manipulate thread priorities</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1717 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1718 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1719 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1720 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1721 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1722 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1723 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1724 <funcdef>cyg_priority_t <function>cyg_thread_get_priority</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1725 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1726 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1727 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1728 <funcdef>cyg_priority_t <function>cyg_thread_get_current_priority</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1729 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1730 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1731 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1732 <funcdef>void <function>cyg_thread_set_priority</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1733 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1734 <paramdef>cyg_priority_t <parameter>priority</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1735 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1736 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1737 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1738
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1739 <refsect1><title id="kernel-thread-priorities-description">Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1740 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1741 Typical schedulers use the concept of a thread priority to determine
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1742 which thread should run next. Exactly what this priority consists of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1743 will depend on the scheduler, but a typical implementation would be a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1744 small integer in the range 0 to 31, with 0 being the highest priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1745 Usually only the idle thread will run at the lowest priority. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1746 exact number of priority levels available depends on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1747 configuration, typically the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1748 <varname>CYGNUM_KERNEL_SCHED_PRIORITIES</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1749 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1750 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1751 <function>cyg_thread_get_priority</function> can be used to determine
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1752 the priority of a thread, or more correctly the value last used in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1753 <function>cyg_thread_set_priority</function> call or when the thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1754 was first created. In some circumstances it is possible that the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1755 thread is actually running at a higher priority. For example, if it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1756 owns a mutex and priority ceilings or inheritance is being used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1757 prevent priority inversion problems, then the thread's priority may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1758 have been boosted temporarily.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1759 <function>cyg_thread_get_current_priority</function> returns the real
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1760 current priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1761 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1762 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1763 In many applications appropriate thread priorities can be determined
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1764 and allocated statically. However, if it is necessary for a thread's
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1765 priority to change at run-time then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1766 <function>cyg_thread_set_priority</function> function provides this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1767 functionality.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1768 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1769 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1770
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1771 <refsect1 id="kernel-thread-priorities-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1772 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1773 <function>cyg_thread_get_priority</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1774 <function>cyg_thread_get_current_priority</function> can be called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1775 from thread or DSR context, although the latter is rarely useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1776 <function>cyg_thread_set_priority</function> should also only be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1777 called from thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1778 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1779 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1780 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1781
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1782 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1783 <!-- {{{ Per-thread data -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1784
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1785 <refentry id="kernel-thread-data">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1786
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1787 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1788 <refentrytitle>Per-thread data</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1789 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1790
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1791 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1792 <refname>cyg_thread_new_data_index</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1793 <refname>cyg_thread_free_data_index</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1794 <refname>cyg_thread_get_data</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1795 <refname>cyg_thread_get_data_ptr</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1796 <refname>cyg_thread_set_data</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1797 <refpurpose>Manipulate per-thread data</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1798 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1799 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1800 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1801 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1802 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1803 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1804 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1805 <funcdef>cyg_ucount32 <function>cyg_thread_new_data_index</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1806 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1807 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1808 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1809 <funcdef>void <function>cyg_thread_free_data_index</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1810 <paramdef>cyg_ucount32 <parameter>index</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1811 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1812 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1813 <funcdef>cyg_addrword_t <function>cyg_thread_get_data</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1814 <paramdef>cyg_ucount32 <parameter>index</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1815 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1816 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1817 <funcdef>cyg_addrword_t* <function>cyg_thread_get_data_ptr</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1818 <paramdef>cyg_ucount32 <parameter>index</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1819 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1820 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1821 <funcdef>void <function>cyg_thread_set_data</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1822 <paramdef>cyg_ucount32 <parameter>index</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1823 <paramdef>cyg_addrword_t <parameter>data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1824 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1825 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1826 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1827
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1828 <refsect1><title id="kernel-thread-data-description">Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1829 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1830 In some applications and libraries it is useful to have some data that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1831 is specific to each thread. For example, many of the functions in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1832 POSIX compatibility package return -1 to indicate an error and store
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1833 additional information in what appears to be a global variable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1834 <varname>errno</varname>. However, if multiple threads make concurrent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1835 calls into the POSIX library and if <varname>errno</varname> were
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1836 really a global variable then a thread would have no way of knowing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1837 whether the current <varname>errno</varname> value really corresponded
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1838 to the last POSIX call it made, or whether some other thread had run
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1839 in the meantime and made a different POSIX call which updated the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1840 variable. To avoid such confusion <varname>errno</varname> is instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1841 implemented as a per-thread variable, and each thread has its own
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1842 instance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1843 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1844 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1845 The support for per-thread data can be disabled via the configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1846 option <varname>CYGVAR_KERNEL_THREADS_DATA</varname>. If enabled, each
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1847 <structname>cyg_thread</structname> data structure holds a small array
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1848 of words. The size of this array is determined by the configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1849 option <varname>CYGNUM_KERNEL_THREADS_DATA_MAX</varname>. When a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1850 thread is created the array is filled with zeroes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1851 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1852 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1853 If an application needs to use per-thread data then it needs an index
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1854 into this array which has not yet been allocated to other code. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1855 index can be obtained by calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1856 <function>cyg_thread_new_data_index</function>, and then used in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1857 subsequent calls to <function>cyg_thread_get_data</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1858 Typically indices are allocated during system initialization and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1859 stored in static variables. If for some reason a slot in the array is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1860 no longer required and can be re-used then it can be released by calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1861 <function>cyg_thread_free_data_index</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1862 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1863 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1864 The current per-thread data in a given slot can be obtained using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1865 <function>cyg_thread_get_data</function>. This implicitly operates on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1866 the current thread, and its single argument should be an index as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1867 returned by <function>cyg_thread_new_data_index</function>. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1868 per-thread data can be updated using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1869 <function>cyg_thread_set_data</function>. If a particular item of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1870 per-thread data is needed repeatedly then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1871 <function>cyg_thread_get_data_ptr</function> can be used to obtain the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1872 address of the data, and indirecting through this pointer allows the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1873 data to be examined and updated efficiently.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1874 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1875 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1876 Some packages, for example the error and POSIX packages, have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1877 pre-allocated slots in the array of per-thread data. These slots
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1878 should not normally be used by application code, and instead slots
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1879 should be allocated during initialization by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1880 <function>cyg_thread_new_data_index</function>. If it is known that,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1881 for example, the configuration will never include the POSIX
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1882 compatibility package then application code may instead decide to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1883 re-use the slot allocated to that package,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1884 <varname>CYGNUM_KERNEL_THREADS_DATA_POSIX</varname>, but obviously
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1885 this does involve a risk of strange and subtle bugs if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1886 application's requirements ever change.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1887 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1888 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1889
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1890 <refsect1 id="kernel-thread-data-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1891 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1892 Typically <function>cyg_thread_new_data_index</function> is only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1893 called during initialization, but may also be called at any time in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1894 thread context. <function>cyg_thread_free_data_index</function>, if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1895 used at all, can also be called during initialization or from thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1896 context. <function>cyg_thread_get_data</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1897 <function>cyg_thread_get_data_ptr</function>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1898 <function>cyg_thread_set_data</function> may only be called from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1899 thread context because they implicitly operate on the current thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1900 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1901 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1902
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1903 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1904
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1905 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1906 <!-- {{{ Thread destructors -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1907
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1908 <refentry id="kernel-thread-destructors">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1909
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1910 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1911 <refentrytitle>Thread destructors</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1912 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1913
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1914 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1915 <refname>cyg_thread_add_destructor</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1916 <refname>cyg_thread_rem_destructor</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1917 <refpurpose>Call functions on thread termination</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1918 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1919 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1920 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1921 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1922 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1923 typedef void (*<type>cyg_thread_destructor_fn</type>)(<type>cyg_addrword_t</type>);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1924 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1925 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1926 <funcdef>cyg_bool_t <function>cyg_thread_add_destructor</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1927 <paramdef>cyg_thread_destructor_fn <parameter>fn</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1928 <paramdef>cyg_addrword_t <parameter>data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1929 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1930 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1931 <funcdef>cyg_bool_t <function>cyg_thread_rem_destructor</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1932 <paramdef>cyg_thread_destructor_fn <parameter>fn</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1933 <paramdef>cyg_addrword_t <parameter>data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1934 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1935 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1936 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1937
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1938 <refsect1><title id="kernel-thread-destructors-description">Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1939 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1940 These functions are provided for cases when an application requires a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1941 function to be automatically called when a thread exits. This is often
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1942 useful when, for example, freeing up resources allocated by the thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1943 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1944 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1945 This support must be enabled with the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1946 <varname>CYGPKG_KERNEL_THREADS_DESTRUCTORS</varname>. When enabled,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1947 you may register a function of type
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1948 <type>cyg_thread_destructor_fn</type> to be called on thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1949 termination using <function>cyg_thread_add_destructor</function>. You
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1950 may also provide it with a piece of arbitrary information in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1951 <parameter>data</parameter> argument which will be passed to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1952 destructor function <parameter>fn</parameter> when the thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1953 terminates. If you no longer wish to call a function previous
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1954 registered with <function>cyg_thread_add_destructor</function>, you
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1955 may call <function>cyg_thread_rem_destructor</function> with the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1956 parameters used to register the destructor function. Both these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1957 functions return <literal>true</literal> on success and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1958 <literal>false</literal> on failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1959 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1960 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1961 By default, thread destructors are per-thread, which means that registering
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1962 a destructor function only registers that function for the current thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1963 In other words, each thread has its own list of destructors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1964 Alternatively you may disable the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1965 <varname>CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</varname> in which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1966 case any registered destructors will be run when <emphasis>any</emphasis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1967 threads exit. In other words, the thread destructor list is global and all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1968 threads have the same destructors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1969 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1970 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1971 There is a limit to the number of destructors which may be registered,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1972 which can be controlled with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1973 <varname>CYGNUM_KERNEL_THREADS_DESTRUCTORS</varname> configuration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1974 option. Increasing this value will very slightly increase the amount
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1975 of memory in use, and when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1976 <varname>CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</varname> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1977 enabled, the amount of memory used per thread will increase. When the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1978 limit has been reached, <function>cyg_thread_add_destructor</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1979 will return <literal>false</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1980 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1981 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1982
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1983 <refsect1 id="kernel-thread-destructors-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1984 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1985 When <varname>CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1986 is enabled, these functions must only be called from a thread context
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1987 as they implicitly operate on the current thread. When
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1988 <varname>CYGSEM_KERNEL_THREADS_DESTRUCTORS_PER_THREAD</varname> is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1989 disabled, these functions may be called from thread or DSR context,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1990 or at initialization time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1991 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1992 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1993
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1994 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1995
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1996 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1997 <!-- {{{ Exceptions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1998
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1999 <refentry id="kernel-exceptions">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2000
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2001 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2002 <refentrytitle>Exception handling</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2003 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2004
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2005 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2006 <refname>cyg_exception_set_handler</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2007 <refname>cyg_exception_clear_handler</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2008 <refname>cyg_exception_call_handler</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2009 <refpurpose>Handle processor exceptions</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2010 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2011 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2012 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2013 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2014 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2015 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2016 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2017 <funcdef>void <function>cyg_exception_set_handler</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2018 <paramdef>cyg_code_t <parameter>exception_number</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2019 <paramdef>cyg_exception_handler_t* <parameter>new_handler</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2020 <paramdef>cyg_addrword_t <parameter>new_data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2021 <paramdef>cyg_exception_handler_t** <parameter>old_handler</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2022 <paramdef>cyg_addrword_t* <parameter>old_data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2023 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2024 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2025 <funcdef>void <function>cyg_exception_clear_handler</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2026 <paramdef>cyg_code_t <parameter>exception_number</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2027 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2028 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2029 <funcdef>void <function>cyg_exception_call_handler</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2030 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2031 <paramdef>cyg_code_t <parameter>exception_number</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2032 <paramdef>cyg_addrword_t <parameter>exception_info</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2033 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2034 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2035 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2036
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2037 <refsect1><title id="kernel-exceptions-description">Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2038 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2039 Sometimes code attempts operations that are not legal on the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2040 hardware, for example dividing by zero, or accessing data through a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2041 pointer that is not properly aligned. When this happens the hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2042 will raise an exception. This is very similar to an interrupt, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2043 happens synchronously with code execution rather than asynchronously
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2044 and hence can be tied to the thread that is currently running.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2045 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2046 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2047 The exceptions that can be raised depend very much on the hardware,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2048 especially the processor. The corresponding documentation should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2049 consulted for more details. Alternatively the architectural HAL header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2050 file <filename class="headerfile">hal_intr.h</filename>, or one of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2051 variant or platform header files it includes, will contain appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2052 definitions. The details of how to handle exceptions, including
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2053 whether or not it is possible to recover from them, also depend on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2054 hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2055 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2056 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2057 Exception handling is optional, and can be disabled through the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2058 configuration option <varname>CYGPKG_KERNEL_EXCEPTIONS</varname>. If
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2059 an application has been exhaustively tested and is trusted never to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2060 raise a hardware exception then this option can be disabled and code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2061 and data sizes will be reduced somewhat. If exceptions are left
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2062 enabled then the system will provide default handlers for the various
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2063 exceptions, but these do nothing. Even the specific type of exception
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2064 is ignored, so there is no point in attempting to decode this and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2065 distinguish between say a divide-by-zero and an unaligned access.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2066 If the application installs its own handlers and wants details of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2067 specific exception being raised then the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2068 <varname>CYGSEM_KERNEL_EXCEPTIONS_DECODE</varname> has to be enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2069 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2070 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2071 An alternative handler can be installed using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2072 <function>cyg_exception_set_handler</function>. This requires a code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2073 for the exception, a function pointer for the new exception handler,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2074 and a parameter to be passed to this handler. Details of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2075 previously installed exception handler will be returned via the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2076 remaining two arguments, allowing that handler to be reinstated, or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2077 null pointers can be used if this information is of no interest. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2078 exception handling function should take the following form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2079 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2080 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2081 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2082 my_exception_handler(cyg_addrword_t data, cyg_code_t exception, cyg_addrword_t info)
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2083 {
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2084 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2085 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2086 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2087 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2088 The data argument corresponds to the <parameter class="function">new_data</parameter>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2089 parameter supplied to <function>cyg_exception_set_handler</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2090 The exception code is provided as well, in case a single handler is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2091 expected to support multiple exceptions. The <parameter class="function">info</parameter>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2092 argument will depend on the hardware and on the specific exception.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2093 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2094 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2095 <function>cyg_exception_clear_handler</function> can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2096 restore the default handler, if desired. It is also possible for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2097 software to raise an exception and cause the current handler to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2098 invoked, but generally this is useful only for testing.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2099 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2100 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2101 By default the system maintains a single set of global exception
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2102 handlers. However, since exceptions occur synchronously it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2103 sometimes useful to handle them on a per-thread basis, and have a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2104 different set of handlers for each thread. This behaviour can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2105 obtained by disabling the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2106 <varname>CYGSEM_KERNEL_EXCEPTIONS_GLOBAL</varname>. If per-thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2107 exception handlers are being used then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2108 <function>cyg_exception_set_handler</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2109 <function>cyg_exception_clear_handler</function> apply to the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2110 thread. Otherwise they apply to the global set of handlers.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2111 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2112
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2113 <caution><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2114 In the current implementation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2115 <function>cyg_exception_call_handler</function> can only be used on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2116 the current thread. There is no support for delivering an exception to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2117 another thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2118 </para></caution>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2119 <note><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2120 Exceptions at the eCos kernel level refer specifically to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2121 hardware-related events such as unaligned accesses to memory or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2122 division by zero. There is no relation with other concepts that are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2123 also known as exceptions, for example the <literal>throw</literal> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2124 <literal>catch</literal> facilities associated with C++.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2125 </para></note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2126
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2127 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2128
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2129 <refsect1 id="kernel-exceptions-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2130 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2131 If the system is configured with a single set of global exception
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2132 handlers then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2133 <function>cyg_exception_set_handler</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2134 <function>cyg_exception_clear_handler</function> may be called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2135 initialization or from thread context. If instead per-thread exception
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2136 handlers are being used then it is not possible to install new
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2137 handlers during initialization because the functions operate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2138 implicitly on the current thread, so they can only be called from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2139 thread context. <function>cyg_exception_call_handler</function> should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2140 only be called from thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2141 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2142 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2143
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2144 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2145
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2146 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2147 <!-- {{{ Counters -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2148
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2149 <refentry id="kernel-counters">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2150
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2151 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2152 <refentrytitle>Counters</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2153 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2154
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2155 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2156 <refname>cyg_counter_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2157 <refname>cyg_counter_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2158 <refname>cyg_counter_current_value</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2159 <refname>cyg_counter_set_value</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2160 <refname>cyg_counter_tick</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2161 <refpurpose>Count event occurrences</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2162 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2163
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2164 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2165 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2166 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2167 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2168 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2169 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2170 <funcdef>void <function>cyg_counter_create</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2171 <paramdef>cyg_handle_t* <parameter>handle</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2172 <paramdef>cyg_counter* <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2173 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2174 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2175 <funcdef>void <function>cyg_counter_delete</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2176 <paramdef>cyg_handle_t <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2177 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2178 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2179 <funcdef>cyg_tick_count_t <function>cyg_counter_current_value</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2180 <paramdef>cyg_handle_t <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2181 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2182 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2183 <funcdef>void <function>cyg_counter_set_value</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2184 <paramdef>cyg_handle_t <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2185 <paramdef>cyg_tick_count_t <parameter>new_value</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2186 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2187 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2188 <funcdef>void <function>cyg_counter_tick</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2189 <paramdef>cyg_handle_t <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2190 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2191 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2192 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2193
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2194 <refsect1 id="kernel-counters-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2195 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2196 Kernel counters can be used to keep track of how many times a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2197 particular event has occurred. Usually this event is an external
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2198 signal of some sort. The most common use of counters is in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2199 implementation of clocks, but they can be useful with other event
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2200 sources as well. Application code can attach <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2201 linkend="kernel-alarms">alarms</link> to counters, causing a function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2202 to be called when some number of events have occurred.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2203 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2204 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2205 A new counter is initialized by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2206 <function>cyg_counter_create</function>. The first argument is used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2207 return a handle to the new counter which can be used for subsequent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2208 operations. The second argument allows the application to provide the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2209 memory needed for the object, thus eliminating any need for dynamic
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2210 memory allocation within the kernel. If a counter is no longer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2211 required and does not have any alarms attached then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2212 <function>cyg_counter_delete</function> can be used to release the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2213 resources, allowing the <structname>cyg_counter</structname> data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2214 structure to be re-used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2215 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2216 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2217 Initializing a counter does not automatically attach it to any source
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2218 of events. Instead some other code needs to call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2219 <function>cyg_counter_tick</function> whenever a suitable event
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2220 occurs, which will cause the counter to be incremented and may cause
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2221 alarms to trigger. The current value associated with the counter can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2222 be retrieved using <function>cyg_counter_current_value</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2223 modified with <function>cyg_counter_set_value</function>. Typically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2224 the latter function is only used during initialization, for example to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2225 set a clock to wallclock time, but it can be used to reset a counter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2226 if necessary. However <function>cyg_counter_set_value</function> will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2227 never trigger any alarms. A newly initialized counter has a starting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2228 value of 0.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2229 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2230 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2231 The kernel provides two different implementations of counters. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2232 default is <varname>CYGIMP_KERNEL_COUNTERS_SINGLE_LIST</varname> which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2233 stores all alarms attached to the counter on a single list. This is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2234 simple and usually efficient. However when a tick occurs the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2235 code has to traverse this list, typically at DSR level, so if there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2236 are a significant number of alarms attached to a single counter this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2237 will affect the system's dispatch latency. The alternative
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2238 implementation, <varname>CYGIMP_KERNEL_COUNTERS_MULTI_LIST</varname>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2239 stores each alarm in one of an array of lists such that at most one of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2240 the lists needs to be searched per clock tick. This involves extra
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2241 code and data, but can improve real-time responsiveness in some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2242 circumstances. Another configuration option that is relevant here
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2243 is <varname>CYGIMP_KERNEL_COUNTERS_SORT_LIST</varname>, which is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2244 disabled by default. This provides a trade off between doing work
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2245 whenever a new alarm is added to a counter and doing work whenever a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2246 tick occurs. It is application-dependent which of these is more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2247 appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2248 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2249 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2250
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2251 <refsect1 id="kernel-counters-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2252 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2253 <function>cyg_counter_create</function> is typically called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2254 system initialization but may also be called in thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2255 Similarly <function>cyg_counter_delete</function> may be called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2256 initialization or in thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2257 <function>cyg_counter_current_value</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2258 <function>cyg_counter_set_value</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2259 <function>cyg_counter_tick</function> may be called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2260 initialization or from thread or DSR context. In fact,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2261 <function>cyg_counter_tick</function> is usually called from inside a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2262 DSR in response to an external event of some sort.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2263 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2264 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2265
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2266 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2267
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2268 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2269 <!-- {{{ Clocks -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2270
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2271 <refentry id="kernel-clocks">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2272
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2273 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2274 <refentrytitle>Clocks</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2275 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2276
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2277 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2278 <refname>cyg_clock_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2279 <refname>cyg_clock_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2280 <refname>cyg_clock_to_counter</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2281 <refname>cyg_clock_set_resolution</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2282 <refname>cyg_clock_get_resolution</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2283 <refname>cyg_real_time_clock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2284 <refname>cyg_current_time</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2285 <refpurpose>Provide system clocks</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2286 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2287
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2288 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2289 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2290 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2291 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2292 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2293 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2294 <funcdef>void <function>cyg_clock_create</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2295 <paramdef>cyg_resolution_t <parameter>resolution</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2296 <paramdef>cyg_handle_t* <parameter>handle</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2297 <paramdef>cyg_clock* <parameter>clock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2298 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2299 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2300 <funcdef>void <function>cyg_clock_delete</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2301 <paramdef>cyg_handle_t <parameter>clock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2302 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2303 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2304 <funcdef>void <function>cyg_clock_to_counter</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2305 <paramdef>cyg_handle_t <parameter>clock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2306 <paramdef>cyg_handle_t* <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2307 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2308 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2309 <funcdef>void <function>cyg_clock_set_resolution</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2310 <paramdef>cyg_handle_t <parameter>clock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2311 <paramdef>cyg_resolution_t <parameter>resolution</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2312 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2313 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2314 <funcdef>cyg_resolution_t <function>cyg_clock_get_resolution</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2315 <paramdef>cyg_handle_t <parameter>clock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2316 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2317 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2318 <funcdef>cyg_handle_t <function>cyg_real_time_clock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2319 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2320 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2321 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2322 <funcdef>cyg_tick_count_t <function>cyg_current_time</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2323 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2324 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2325 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2326 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2327
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2328 <refsect1 id="kernel-clocks-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2329 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2330 In the eCos kernel clock objects are a special form of <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2331 linkend="kernel-counters">counter</link> objects. They are attached to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2332 a specific type of hardware, clocks that generate ticks at very
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2333 specific time intervals, whereas counters can be used with any event
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2334 source.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2335 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2336 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2337 In a default configuration the kernel provides a single clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2338 instance, the real-time clock. This gets used for timeslicing and for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2339 operations that involve a timeout, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2340 <function>cyg_semaphore_timed_wait</function>. If this functionality
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2341 is not required it can be removed from the system using the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2342 configuration option <varname>CYGVAR_KERNEL_COUNTERS_CLOCK</varname>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2343 Otherwise the real-time clock can be accessed by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2344 <function>cyg_real_time_clock</function>, allowing applications to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2345 attach alarms, and the current counter value can be obtained using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2346 <function>cyg_current_time</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2347 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2348 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2349 Applications can create and destroy additional clocks if desired,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2350 using <function>cyg_clock_create</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2351 <function>cyg_clock_delete</function>. The first argument to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2352 <function>cyg_clock_create</function> specifies the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2353 <link linkend="kernel-clocks-resolution">resolution</link> this clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2354 will run at. The second argument is used to return a handle for this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2355 clock object, and the third argument provides the kernel with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2356 memory needed to hold this object. This clock will not actually tick
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2357 by itself. Instead it is the responsibility of application code to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2358 initialize a suitable hardware timer to generate interrupts at the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2359 appropriate frequency, install an interrupt handler for this, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2360 call <function>cyg_counter_tick</function> from inside the DSR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2361 Associated with each clock is a kernel counter, a handle for which can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2362 be obtained using <function>cyg_clock_to_counter</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2363 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2364 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2365
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2366 <refsect1 id="kernel-clocks-resolution"><title>Clock Resolutions and Ticks</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2367 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2368 At the kernel level all clock-related operations including delays,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2369 timeouts and alarms work in units of clock ticks, rather than in units
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2370 of seconds or milliseconds. If the calling code, whether the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2371 application or some other package, needs to operate using units such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2372 as milliseconds then it has to convert from these units to clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2373 ticks.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2374 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2375 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2376 The main reason for this is that it accurately reflects the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2377 hardware: calling something like <function>nanosleep</function> with a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2378 delay of ten nanoseconds will not work as intended on any real
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2379 hardware because timer interrupts simply will not happen that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2380 frequently; instead calling <function>cyg_thread_delay</function> with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2381 the equivalent delay of 0 ticks gives a much clearer indication that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2382 the application is attempting something inappropriate for the target
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2383 hardware. Similarly, passing a delay of five ticks to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2384 <function>cyg_thread_delay</function> makes it fairly obvious that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2385 the current thread will be suspended for somewhere between four and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2386 five clock periods, as opposed to passing 50000000 to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2387 <function>nanosleep</function> which suggests a granularity that is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2388 not actually provided.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2389 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2390 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2391 A secondary reason is that conversion between clock ticks and units
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2392 such as milliseconds can be somewhat expensive, and whenever possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2393 should be done at compile-time or by the application developer rather
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2394 than at run-time. This saves code size and cpu cycles.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2395 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2396 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2397 The information needed to perform these conversions is the clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2398 resolution. This is a structure with two fields, a dividend and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2399 divisor, and specifies the number of nanoseconds between clock ticks.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2400 For example a clock that runs at 100Hz will have 10 milliseconds
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2401 between clock ticks, or 10000000 nanoseconds. The ratio between the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2402 resolution's dividend and divisor will therefore be 10000000 to 1, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2403 typical values for these might be 1000000000 and 100. If the clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2404 runs at a different frequency, say 60Hz, the numbers could be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2405 1000000000 and 60 respectively. Given a delay in nanoseconds, this can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2406 be converted to clock ticks by multiplying with the the divisor and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2407 then dividing by the dividend. For example a delay of 50 milliseconds
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2408 corresponds to 50000000 nanoseconds, and with a clock frequency of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2409 100Hz this can be converted to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2410 ((50000000&nbsp;*&nbsp;100)&nbsp;/&nbsp;1000000000)&nbsp;=&nbsp;5
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2411 clock ticks. Given the large numbers involved this arithmetic normally
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2412 has to be done using 64-bit precision and the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2413 <type>long&nbsp;long</type> data type, but allows code to run on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2414 hardware with unusual clock frequencies.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2415 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2416 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2417 The default frequency for the real-time clock on any platform is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2418 usually about 100Hz, but platform-specific documentation should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2419 consulted for this information. Usually it is possible to override
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2420 this default by configuration options, but again this depends on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2421 capabilities of the underlying hardware. The resolution for any clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2422 can be obtained using <function>cyg_clock_get_resolution</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2423 For clocks created by application code, there is also a function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2424 <function>cyg_clock_set_resolution</function>. This does not affect
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2425 the underlying hardware timer in any way, it merely updates the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2426 information that will be returned in subsequent calls to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2427 <function>cyg_clock_get_resolution</function>: changing the actual
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2428 underlying clock frequency will require appropriate manipulation of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2429 the timer hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2430 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2431 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2432
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2433 <refsect1 id="kernel-clocks-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2434 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2435 <function>cyg_clock_create</function> is usually only called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2436 system initialization (if at all), but may also be called from thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2437 context. The same applies to <function>cyg_clock_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2438 The remaining functions may be called during initialization, from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2439 thread context, or from DSR context, although it should be noted that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2440 there is no locking between
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2441 <function>cyg_clock_get_resolution</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2442 <function>cyg_clock_set_resolution</function> so theoretically it is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2443 possible that the former returns an inconsistent data structure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2444 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2445 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2446
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2447 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2448
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2449 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2450 <!-- {{{ Alarms -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2451
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2452 <refentry id="kernel-alarms">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2453
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2454 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2455 <refentrytitle>Alarms</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2456 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2457
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2458 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2459 <refname>cyg_alarm_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2460 <refname>cyg_alarm_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2461 <refname>cyg_alarm_initialize</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2462 <refname>cyg_alarm_enable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2463 <refname>cyg_alarm_disable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2464 <refpurpose>Run an alarm function when a number of events have occurred</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2465 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2466
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2467 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2468 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2469 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2470 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2471 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2472 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2473 <funcdef>void <function>cyg_alarm_create</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2474 <paramdef>cyg_handle_t <parameter>counter</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2475 <paramdef>cyg_alarm_t* <parameter>alarmfn</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2476 <paramdef>cyg_addrword_t <parameter>data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2477 <paramdef>cyg_handle_t* <parameter>handle</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2478 <paramdef>cyg_alarm* <parameter>alarm</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2479 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2480 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2481 <funcdef>void <function>cyg_alarm_delete</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2482 <paramdef>cyg_handle_t <parameter>alarm</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2483 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2484 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2485 <funcdef>void <function>cyg_alarm_initialize</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2486 <paramdef>cyg_handle_t <parameter>alarm</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2487 <paramdef>cyg_tick_count_t <parameter>trigger</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2488 <paramdef>cyg_tick_count_t <parameter>interval</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2489 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2490 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2491 <funcdef>void <function>cyg_alarm_enable</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2492 <paramdef>cyg_handle_t <parameter>alarm</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2493 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2494 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2495 <funcdef>void <function>cyg_alarm_disable</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2496 <paramdef>cyg_handle_t <parameter>alarm</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2497 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2498 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2499 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2500
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2501 <refsect1 id="kernel-alarms-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2502 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2503 Kernel alarms are used together with counters and allow for action to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2504 be taken when a certain number of events have occurred. If the counter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2505 is associated with a clock then the alarm action happens when the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2506 appropriate number of clock ticks have occurred, in other words after
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2507 a certain period of time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2508 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2509 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2510 Setting up an alarm involves a two-step process. First the alarm must
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2511 be created with a call to <function>cyg_alarm_create</function>. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2512 takes five arguments. The first identifies the counter to which the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2513 alarm should be attached. If the alarm should be attached to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2514 system's real-time clock then <function>cyg_real_time_clock</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2515 and <function>cyg_clock_to_counter</function> can be used to get hold
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2516 of the appropriate handle. The next two arguments specify the action
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2517 to be taken when the alarm is triggered, in the form of a function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2518 pointer and some data. This function should take the form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2519 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2520 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2521 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2522 alarm_handler(cyg_handle_t alarm, cyg_addrword_t data)
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2523 {
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2524 &hellip;
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2525 }
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2526 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2527 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2528 The data argument passed to the alarm function corresponds to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2529 third argument passed to <function>cyg_alarm_create</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2530 The fourth argument to <function>cyg_alarm_create</function> is used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2531 to return a handle to the newly-created alarm object, and the final
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2532 argument provides the memory needed for the alarm object and thus
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2533 avoids any need for dynamic memory allocation within the kernel.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2534 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2535 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2536 Once an alarm has been created a further call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2537 <function>cyg_alarm_initialize</function> is needed to activate it.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2538 The first argument specifies the alarm. The second argument indicates
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2539 the number of events, for example clock ticks, that need to occur
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2540 before the alarm triggers. If the third argument is 0 then the alarm
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2541 will only trigger once. A non-zero value specifies that the alarm
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2542 should trigger repeatedly, with an interval of the specified number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2543 events.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2544 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2545 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2546 Alarms can be temporarily disabled and reenabled using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2547 <function>cyg_alarm_disable</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2548 <function>cyg_alarm_enable</function>. Alternatively another call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2549 <function>cyg_alarm_initialize</function> can be used to modify the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2550 behaviour of an existing alarm. If an alarm is no longer required then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2551 the associated resources can be released using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2552 <function>cyg_alarm_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2553 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2554 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2555 The alarm function is invoked when a counter tick occurs, in other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2556 words when there is a call to <function>cyg_counter_tick</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2557 and will happen in the same context. If the alarm is associated with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2558 the system's real-time clock then this will be DSR context, following
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2559 a clock interrupt. If the alarm is associated with some other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2560 application-specific counter then the details will depend on how that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2561 counter is updated.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2562 </para>
356
b77e86276ec3 * src/common/clock.cxx (add_alarm): Tweak last change to allow
jlarmour
parents: 334
diff changeset
2563 <para>
b77e86276ec3 * src/common/clock.cxx (add_alarm): Tweak last change to allow
jlarmour
parents: 334
diff changeset
2564 If two or more alarms are registered for precisely the same counter tick,
b77e86276ec3 * src/common/clock.cxx (add_alarm): Tweak last change to allow
jlarmour
parents: 334
diff changeset
2565 the order of execution of the alarm functions is unspecified.
b77e86276ec3 * src/common/clock.cxx (add_alarm): Tweak last change to allow
jlarmour
parents: 334
diff changeset
2566 </para>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2567 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2568
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2569 <refsect1 id="kernel-alarms-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2570 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2571 <function>cyg_alarm_create</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2572 <function>cyg_alarm_initialize</function> is typically called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2573 system initialization but may also be called in thread context. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2574 same applies to <function>cyg_alarm_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2575 <function>cyg_alarm_initialize</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2576 <function>cyg_alarm_disable</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2577 <function>cyg_alarm_enable</function> may be called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2578 initialization or from thread or DSR context, but
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2579 <function>cyg_alarm_enable</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2580 <function>cyg_alarm_initialize</function> may be expensive operations
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2581 and should only be called when necessary.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2582 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2583 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2584
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2585 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2586
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2587 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2588 <!-- {{{ Mutexes -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2589
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2590 <refentry id="kernel-mutexes">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2591
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2592 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2593 <refentrytitle>Mutexes</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2594 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2595
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2596 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2597 <refname>cyg_mutex_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2598 <refname>cyg_mutex_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2599 <refname>cyg_mutex_lock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2600 <refname>cyg_mutex_trylock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2601 <refname>cyg_mutex_unlock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2602 <refname>cyg_mutex_release</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2603 <refname>cyg_mutex_set_ceiling</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2604 <refname>cyg_mutex_set_protocol</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2605 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2606 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2607
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2608 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2609 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2610 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2611 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2612 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2613 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2614 <funcdef>void <function>cyg_mutex_init</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2615 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2616 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2617 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2618 <funcdef>void <function>cyg_mutex_destroy</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2619 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2620 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2621 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2622 <funcdef>cyg_bool_t <function>cyg_mutex_lock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2623 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2624 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2625 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2626 <funcdef>cyg_bool_t <function>cyg_mutex_trylock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2627 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2628 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2629 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2630 <funcdef>void <function>cyg_mutex_unlock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2631 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2632 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2633 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2634 <funcdef>void <function>cyg_mutex_release</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2635 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2636 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2637 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2638 <funcdef>void <function>cyg_mutex_set_ceiling</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2639 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2640 <paramdef>cyg_priority_t <parameter>priority</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2641 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2642 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2643 <funcdef>void <function>cyg_mutex_set_protocol</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2644 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2645 <paramdef>enum cyg_mutex_protocol <parameter>protocol/</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2646 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2647 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2648 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2649
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2650 <refsect1 id="kernel-mutexes-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2651 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2652 The purpose of mutexes is to let threads share resources safely. If
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2653 two or more threads attempt to manipulate a data structure with no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2654 locking between them then the system may run for quite some time
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2655 without apparent problems, but sooner or later the data structure will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2656 become inconsistent and the application will start behaving strangely
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2657 and is quite likely to crash. The same can apply even when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2658 manipulating a single variable or some other resource. For example,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2659 consider:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2660 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2661 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2662 static volatile int counter = 0;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2663
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2664 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2665 process_event(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2666 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2667 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2668
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2669 counter++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2670 }
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2671 </programlisting>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2672 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2673 Assume that after a certain period of time <varname>counter</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2674 has a value of 42, and two threads A and B running at the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2675 priority call <function>process_event</function>. Typically thread A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2676 will read the value of <varname>counter</varname> into a register,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2677 increment this register to 43, and write this updated value back to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2678 memory. Thread B will do the same, so usually
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2679 <varname>counter</varname> will end up with a value of 44. However if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2680 thread A is timesliced after reading the old value 42 but before
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2681 writing back 43, thread B will still read back the old value and will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2682 also write back 43. The net result is that the counter only gets
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2683 incremented once, not twice, which depending on the application may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2684 prove disastrous.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2685 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2686 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2687 Sections of code like the above which involve manipulating shared data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2688 are generally known as critical regions. Code should claim a lock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2689 before entering a critical region and release the lock when leaving.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2690 Mutexes provide an appropriate synchronization primitive for this.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2691 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2692 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2693 static volatile int counter = 0;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2694 static cyg_mutex_t lock;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2695
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2696 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2697 process_event(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2698 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2699 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2700
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2701 cyg_mutex_lock(&amp;lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2702 counter++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2703 cyg_mutex_unlock(&amp;lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2704 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2705 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2706 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2707 A mutex must be initialized before it can be used, by calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2708 <function>cyg_mutex_init</function>. This takes a pointer to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2709 <structname>cyg_mutex_t</structname> data structure which is typically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2710 statically allocated, and may be part of a larger data structure. If a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2711 mutex is no longer required and there are no threads waiting on it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2712 then <function>cyg_mutex_destroy</function> can be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2713 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2714 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2715 The main functions for using a mutex are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2716 <function>cyg_mutex_lock</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2717 <function>cyg_mutex_unlock</function>. In normal operation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2718 <function>cyg_mutex_lock</function> will return success after claiming
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2719 the mutex lock, blocking if another thread currently owns the mutex.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2720 However the lock operation may fail if other code calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2721 <function>cyg_mutex_release</function> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2722 <function>cyg_thread_release</function>, so if these functions may get
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2723 used then it is important to check the return value. The current owner
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2724 of a mutex should call <function>cyg_mutex_unlock</function> when a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2725 lock is no longer required. This operation must be performed by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2726 owner, not by another thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2727 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2728 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2729 <function>cyg_mutex_trylock</function> is a variant of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2730 <function>cyg_mutex_lock</function> that will always return
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2731 immediately, returning success or failure as appropriate. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2732 function is rarely useful. Typical code locks a mutex just before
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2733 entering a critical region, so if the lock cannot be claimed then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2734 there may be nothing else for the current thread to do. Use of this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2735 function may also cause a form of priority inversion if the owner
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2736 owner runs at a lower priority, because the priority inheritance code
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2737 will not be triggered. Instead the current thread continues running,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2738 preventing the owner from getting any cpu time, completing the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2739 critical region, and releasing the mutex.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2740 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2741 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2742 <function>cyg_mutex_release</function> can be used to wake up all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2743 threads that are currently blocked inside a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2744 <function>cyg_mutex_lock</function> for a specific mutex. These lock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2745 calls will return failure. The current mutex owner is not affected.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2746 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2747 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2748
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2749 <refsect1 id="kernel-mutexes-priority-inversion"><title>Priority Inversion</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2750 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2751 The use of mutexes gives rise to a problem known as priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2752 inversion. In a typical scenario this requires three threads A, B, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2753 C, running at high, medium and low priority respectively. Thread A and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2754 thread B are temporarily blocked waiting for some event, so thread C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2755 gets a chance to run, needs to enter a critical region, and locks
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2756 a mutex. At this point threads A and B are woken up - the exact order
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2757 does not matter. Thread A needs to claim the same mutex but has to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2758 wait until C has left the critical region and can release the mutex.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2759 Meanwhile thread B works on something completely different and can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2760 continue running without problems. Because thread C is running a lower
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2761 priority than B it will not get a chance to run until B blocks for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2762 some reason, and hence thread A cannot run either. The overall effect
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2763 is that a high-priority thread A cannot proceed because of a lower
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2764 priority thread B, and priority inversion has occurred.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2765 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2766 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2767 In simple applications it may be possible to arrange the code such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2768 that priority inversion cannot occur, for example by ensuring that a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2769 given mutex is never shared by threads running at different priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2770 levels. However this may not always be possible even at the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2771 application level. In addition mutexes may be used internally by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2772 underlying code, for example the memory allocation package, so careful
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2773 analysis of the whole system would be needed to be sure that priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2774 inversion cannot occur. Instead it is common practice to use one of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2775 two techniques: priority ceilings and priority inheritance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2776 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2777 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2778 Priority ceilings involve associating a priority with each mutex.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2779 Usually this will match the highest priority thread that will ever
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2780 lock the mutex. When a thread running at a lower priority makes a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2781 successful call to <function>cyg_mutex_lock</function> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2782 <function>cyg_mutex_trylock</function> its priority will be boosted to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2783 that of the mutex. For example, given the previous example the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2784 priority associated with the mutex would be that of thread A, so for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2785 as long as it owns the mutex thread C will run in preference to thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2786 B. When C releases the mutex its priority drops to the normal value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2787 again, allowing A to run and claim the mutex. Setting the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2788 priority for a mutex involves a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2789 <function>cyg_mutex_set_ceiling</function>, which is typically called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2790 during initialization. It is possible to change the ceiling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2791 dynamically but this will only affect subsequent lock operations, not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2792 the current owner of the mutex.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2793 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2794 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2795 Priority ceilings are very suitable for simple applications, where for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2796 every thread in the system it is possible to work out which mutexes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2797 will be accessed. For more complicated applications this may prove
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2798 difficult, especially if thread priorities change at run-time. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2799 additional problem occurs for any mutexes outside the application, for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2800 example used internally within eCos packages. A typical eCos package
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2801 will be unaware of the details of the various threads in the system,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2802 so it will have no way of setting suitable ceilings for its internal
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2803 mutexes. If those mutexes are not exported to application code then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2804 using priority ceilings may not be viable. The kernel does provide a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2805 configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2806 <varname>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_DEFAULT_PRIORITY</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2807 that can be used to set the default priority ceiling for all mutexes,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2808 which may prove sufficient.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2809 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2810 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2811 The alternative approach is to use priority inheritance: if a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2812 calls <function>cyg_mutex_lock</function> for a mutex that it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2813 currently owned by a lower-priority thread, then the owner will have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2814 its priority raised to that of the current thread. Often this is more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2815 efficient than priority ceilings because priority boosting only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2816 happens when necessary, not for every lock operation, and the required
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2817 priority is determined at run-time rather than by static analysis.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2818 However there are complications when multiple threads running at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2819 different priorities try to lock a single mutex, or when the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2820 owner of a mutex then tries to lock additional mutexes, and this makes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2821 the implementation significantly more complicated than priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2822 ceilings.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2823 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2824 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2825 There are a number of configuration options associated with priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2826 inversion. First, if after careful analysis it is known that priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2827 inversion cannot arise then the component
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2828 <function>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2829 can be disabled. More commonly this component will be enabled, and one
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2830 of either
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2831 <varname>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_INHERIT</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2832 or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2833 <varname>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_CEILING</varname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2834 will be selected, so that one of the two protocols is available for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2835 all mutexes. It is possible to select multiple protocols, so that some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2836 mutexes can have priority ceilings while others use priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2837 inheritance or no priority inversion protection at all. Obviously this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2838 flexibility will add to the code size and to the cost of mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2839 operations. The default for all mutexes will be controlled by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2840 <varname>CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_DEFAULT</varname>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2841 and can be changed at run-time using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2842 <function>cyg_mutex_set_protocol</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2843 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2844 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2845 Priority inversion problems can also occur with other synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2846 primitives such as semaphores. For example there could be a situation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2847 where a high-priority thread A is waiting on a semaphore, a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2848 low-priority thread C needs to do just a little bit more work before
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2849 posting the semaphore, but a medium priority thread B is running and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2850 preventing C from making progress. However a semaphore does not have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2851 the concept of an owner, so there is no way for the system to know
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2852 that it is thread C which would next post to the semaphore. Hence
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2853 there is no way for the system to boost the priority of C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2854 automatically and prevent the priority inversion. Instead situations
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2855 like this have to be detected by application developers and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2856 appropriate precautions have to be taken, for example making sure that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2857 all the threads run at suitable priorities at all times.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2858 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2859 <warning><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2860 The current implementation of priority inheritance within the eCos
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2861 kernel does not handle certain exceptional circumstances completely
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2862 correctly. Problems will only arise if a thread owns one mutex,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2863 then attempts to claim another mutex, and there are other threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2864 attempting to lock these same mutexes. Although the system will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2865 continue running, the current owners of the various mutexes involved
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2866 may not run at the priority they should. This situation never arises
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2867 in typical code because a mutex will only be locked for a small
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2868 critical region, and there is no need to manipulate other shared resources
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2869 inside this region. A more complicated implementation of priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2870 inheritance is possible but would add significant overhead and certain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2871 operations would no longer be deterministic.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2872 </para></warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2873 <warning><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2874 Support for priority ceilings and priority inheritance is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2875 implemented for all schedulers. In particular neither priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2876 ceilings nor priority inheritance are currently available for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2877 bitmap scheduler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2878 </para></warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2879 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2880
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2881 <refsect1 id="kernel-mutexes-alternatives"><title>Alternatives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2882 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2883 In nearly all circumstances, if two or more threads need to share some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2884 data then protecting this data with a mutex is the correct thing to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2885 do. Mutexes are the only primitive that combine a locking mechanism
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2886 and protection against priority inversion problems. However this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2887 functionality is achieved at a cost, and in exceptional circumstances
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2888 such as an application's most critical inner loop it may be desirable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2889 to use some other means of locking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2890 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2891 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2892 When a critical region is very very small it is possible to lock the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2893 scheduler, thus ensuring that no other thread can run until the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2894 scheduler is unlocked again. This is achieved with calls to <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2895 linkend="kernel-schedcontrol"><function>cyg_scheduler_lock</function></link>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2896 and <function>cyg_scheduler_unlock</function>. If the critical region
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2897 is sufficiently small then this can actually improve both performance
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2898 and dispatch latency because <function>cyg_mutex_lock</function> also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2899 locks the scheduler for a brief period of time. This approach will not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2900 work on SMP systems because another thread may already be running on a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2901 different processor and accessing the critical region.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2902 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2903 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2904 Another way of avoiding the use of mutexes is to make sure that all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2905 threads that access a particular critical region run at the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2906 priority and configure the system with timeslicing disabled
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2907 (<varname>CYGSEM_KERNEL_SCHED_TIMESLICE</varname>). Without
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2908 timeslicing a thread can only be preempted by a higher-priority one,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2909 or if it performs some operation that can block. This approach
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2910 requires that none of the operations in the critical region can block,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2911 so for example it is not legal to call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2912 <function>cyg_semaphore_wait</function>. It is also vulnerable to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2913 any changes in the configuration or to the various thread priorities:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2914 any such changes may now have unexpected side effects. It will not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2915 work on SMP systems.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2916 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2917 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2918
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2919 <refsect1 id="kernel-mutexes-recursive"><title>Recursive Mutexes</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2920 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2921 The implementation of mutexes within the eCos kernel does not support
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2922 recursive locks. If a thread has locked a mutex and then attempts to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2923 lock the mutex again, typically as a result of some recursive call in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2924 a complicated call graph, then either an assertion failure will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2925 reported or the thread will deadlock. This behaviour is deliberate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2926 When a thread has just locked a mutex associated with some data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2927 structure, it can assume that that data structure is in a consistent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2928 state. Before unlocking the mutex again it must ensure that the data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2929 structure is again in a consistent state. Recursive mutexes allow a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2930 thread to make arbitrary changes to a data structure, then in a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2931 recursive call lock the mutex again while the data structure is still
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2932 inconsistent. The net result is that code can no longer make any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2933 assumptions about data structure consistency, which defeats the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2934 purpose of using mutexes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2935 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2936 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2937
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2938 <refsect1 id="kernel-mutexes-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2939 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2940 <function>cyg_mutex_init</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2941 <function>cyg_mutex_set_ceiling</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2942 <function>cyg_mutex_set_protocol</function> are normally called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2943 initialization but may also be called from thread context. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2944 remaining functions should only be called from thread context. Mutexes
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2945 serve as a mutual exclusion mechanism between threads, and cannot be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2946 used to synchronize between threads and the interrupt handling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2947 subsystem. If a critical region is shared between a thread and a DSR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2948 then it must be protected using <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2949 linkend="kernel-schedcontrol"><function>cyg_scheduler_lock</function></link>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2950 and <function>cyg_scheduler_unlock</function>. If a critical region is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2951 shared between a thread and an ISR, it must be protected by disabling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2952 or masking interrupts. Obviously these operations must be used with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2953 care because they can affect dispatch and interrupt latencies.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2954 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2955 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2956
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2957 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2958
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2959 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2960 <!-- {{{ Condition variables -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2961
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2962 <refentry id="kernel-condition-variables">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2963
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2964 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2965 <refentrytitle>Condition Variables</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2966 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2967
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2968 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2969 <refname>cyg_cond_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2970 <refname>cyg_cond_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2971 <refname>cyg_cond_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2972 <refname>cyg_cond_timed_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2973 <refname>cyg_cond_signal</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2974 <refname>cyg_cond_broadcast</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2975 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2976 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2977
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2978 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2979 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2980 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2981 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2982 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2983 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2984 <funcdef>void <function>cyg_cond_init</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2985 <paramdef>cyg_cond_t* <parameter>cond</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2986 <paramdef>cyg_mutex_t* <parameter>mutex</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2987 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2988 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2989 <funcdef>void <function>cyg_cond_destroy</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2990 <paramdef>cyg_cond_t* <parameter>cond</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2991 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2992 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2993 <funcdef>cyg_bool_t <function>cyg_cond_wait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2994 <paramdef>cyg_cond_t* <parameter>cond</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2995 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2996 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2997 <funcdef>cyg_bool_t <function>cyg_cond_timed_wait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2998 <paramdef>cyg_cond_t* <parameter>cond</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2999 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3000 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3001 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3002 <funcdef>void <function>cyg_cond_signal</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3003 <paramdef>cyg_cond_t* <parameter>cond</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3004 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3005 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3006 <funcdef>void <function>cyg_cond_broadcast</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3007 <paramdef>cyg_cond_t* <parameter>cond</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3008 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3009 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3010 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3011
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3012 <refsect1 id="kernel-condition-variables-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3013
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3014 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3015 Condition variables are used in conjunction with mutexes to implement
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3016 long-term waits for some condition to become true. For example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3017 consider a set of functions that control access to a pool of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3018 resources:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3019 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3020
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3021 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3022
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3023 cyg_mutex_t res_lock;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3024 res_t res_pool[RES_MAX];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3025 int res_count = RES_MAX;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3026
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3027 void res_init(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3028 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3029 cyg_mutex_init(&amp;res_lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3030 &lt;fill pool with resources&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3031 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3032
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3033 res_t res_allocate(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3034 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3035 res_t res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3036
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3037 cyg_mutex_lock(&amp;res_lock); // lock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3038
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3039 if( res_count == 0 ) // check for free resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3040 res = RES_NONE; // return RES_NONE if none
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3041 else
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3042 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3043 res_count--; // allocate a resources
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3044 res = res_pool[res_count];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3045 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3046
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3047 cyg_mutex_unlock(&amp;res_lock); // unlock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3048
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3049 return res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3050 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3051
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3052 void res_free(res_t res)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3053 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3054 cyg_mutex_lock(&amp;res_lock); // lock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3055
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3056 res_pool[res_count] = res; // free the resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3057 res_count++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3058
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3059 cyg_mutex_unlock(&amp;res_lock); // unlock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3060 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3061 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3062
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3063 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3064 These routines use the variable <varname>res_count</varname> to keep
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3065 track of the resources available. If there are none then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3066 <function>res_allocate</function> returns <literal>RES_NONE</literal>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3067 which the caller must check for and take appropriate error handling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3068 actions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3069 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3070
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3071 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3072 Now suppose that we do not want to return
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3073 <literal>RES_NONE</literal> when there are no resources, but want to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3074 wait for one to become available. This is where a condition variable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3075 can be used:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3076 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3077
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3078 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3079
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3080 cyg_mutex_t res_lock;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3081 cyg_cond_t res_wait;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3082 res_t res_pool[RES_MAX];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3083 int res_count = RES_MAX;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3084
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3085 void res_init(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3086 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3087 cyg_mutex_init(&amp;res_lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3088 cyg_cond_init(&amp;res_wait, &amp;res_lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3089 &lt;fill pool with resources&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3090 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3091
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3092 res_t res_allocate(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3093 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3094 res_t res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3095
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3096 cyg_mutex_lock(&amp;res_lock); // lock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3097
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3098 while( res_count == 0 ) // wait for a resources
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3099 cyg_cond_wait(&amp;res_wait);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3100
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3101 res_count--; // allocate a resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3102 res = res_pool[res_count];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3103
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3104 cyg_mutex_unlock(&amp;res_lock); // unlock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3105
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3106 return res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3107 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3108
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3109 void res_free(res_t res)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3110 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3111 cyg_mutex_lock(&amp;res_lock); // lock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3112
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3113 res_pool[res_count] = res; // free the resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3114 res_count++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3115
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3116 cyg_cond_signal(&amp;res_wait); // wake up any waiting allocators
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3117
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3118 cyg_mutex_unlock(&amp;res_lock); // unlock the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3119 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3120 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3121
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3122 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3123 In this version of the code, when <function>res_allocate</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3124 detects that there are no resources it calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3125 <function>cyg_cond_wait</function>. This does two things: it unlocks
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3126 the mutex, and puts the calling thread to sleep on the condition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3127 variable. When <function>res_free</function> is eventually called, it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3128 puts a resource back into the pool and calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3129 <function>cyg_cond_signal</function> to wake up any thread waiting on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3130 the condition variable. When the waiting thread eventually gets to run again,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3131 it will re-lock the mutex before returning from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3132 <function>cyg_cond_wait</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3133 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3134
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3135 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3136 There are two important things to note about the way in which this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3137 code works. The first is that the mutex unlock and wait in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3138 <function>cyg_cond_wait</function> are atomic: no other thread can run
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3139 between the unlock and the wait. If this were not the case then a call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3140 to <function>res_free</function> by that thread would release the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3141 resource but the call to <function>cyg_cond_signal</function> would be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3142 lost, and the first thread would end up waiting when there were
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3143 resources available.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3144 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3145
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3146 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3147 The second feature is that the call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3148 <function>cyg_cond_wait</function> is in a <literal>while</literal>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3149 loop and not a simple <literal>if</literal> statement. This is because
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3150 of the need to re-lock the mutex in <function>cyg_cond_wait</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3151 when the signalled thread reawakens. If there are other threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3152 already queued to claim the lock then this thread must wait. Depending
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3153 on the scheduler and the queue order, many other threads may have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3154 entered the critical section before this one gets to run. So the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3155 condition that it was waiting for may have been rendered false. Using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3156 a loop around all condition variable wait operations is the only way
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3157 to guarantee that the condition being waited for is still true after
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3158 waiting.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3159 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3160
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3161 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3162 Before a condition variable can be used it must be initialized with a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3163 call to <function>cyg_cond_init</function>. This requires two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3164 arguments, memory for the data structure and a pointer to an existing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3165 mutex. This mutex will not be initialized by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3166 <function>cyg_cond_init</function>, instead a separate call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3167 <function>cyg_mutex_init</function> is required. If a condition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3168 variable is no longer required and there are no threads waiting on it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3169 then <function>cyg_cond_destroy</function> can be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3170 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3171 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3172 When a thread needs to wait for a condition to be satisfied it can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3173 call <function>cyg_cond_wait</function>. The thread must have already
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3174 locked the mutex that was specified in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3175 <function>cyg_cond_init</function> call. This mutex will be unlocked
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3176 and the current thread will be suspended in an atomic operation. When
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3177 some other thread performs a signal or broadcast operation the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3178 thread will be woken up and automatically reclaim ownership of the mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3179 again, allowing it to examine global state and determine whether or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3180 not the condition is now satisfied. The kernel supplies a variant of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3181 this function, <function>cyg_cond_timed_wait</function>, which can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3182 used to wait on the condition variable or until some number of clock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3183 ticks have occurred. The mutex will always be reclaimed before
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3184 <function>cyg_cond_timed_wait</function> returns, regardless of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3185 whether it was a result of a signal operation or a timeout.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3186 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3187 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3188 There is no <function>cyg_cond_trywait</function> function because
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3189 this would not serve any purpose. If a thread has locked the mutex and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3190 determined that the condition is satisfied, it can just release the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3191 mutex and return. There is no need to perform any operation on the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3192 condition variable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3193 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3194 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3195 When a thread changes shared state that may affect some other thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3196 blocked on a condition variable, it should call either
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3197 <function>cyg_cond_signal</function> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3198 <function>cyg_cond_broadcast</function>. These calls do not require
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3199 ownership of the mutex, but usually the mutex will have been claimed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3200 before updating the shared state. A signal operation only wakes up the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3201 first thread that is waiting on the condition variable, while a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3202 broadcast wakes up all the threads. If there are no threads waiting on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3203 the condition variable at the time, then the signal or broadcast will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3204 have no effect: past signals are not counted up or remembered in any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3205 way. Typically a signal should be used when all threads will check the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3206 same condition and at most one thread can continue running. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3207 broadcast should be used if threads check slightly different
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3208 conditions, or if the change to the global state might allow multiple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3209 threads to proceed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3210 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3211 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3212
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3213 <refsect1 id="kernel-condition-variables-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3214 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3215 <function>cyg_cond_init</function> is typically called during system
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3216 initialization but may also be called in thread context. The same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3217 applies to <function>cyg_cond_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3218 <function>cyg_cond_wait</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3219 <function>cyg_cond_timedwait</function> may only be called from thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3220 context since they may block. <function>cyg_cond_signal</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3221 <function>cyg_cond_broadcast</function> may be called from thread or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3222 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3223 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3224 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3225
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3226 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3227
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3228 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3229 <!-- {{{ Semaphores -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3230
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3231 <refentry id="kernel-semaphores">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3232
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3233 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3234 <refentrytitle>Semaphores</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3235 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3236
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3237 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3238 <refname>cyg_semaphore_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3239 <refname>cyg_semaphore_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3240 <refname>cyg_semaphore_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3241 <refname>cyg_semaphore_timed_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3242 <refname>cyg_semaphore_post</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3243 <refname>cyg_semaphore_peek</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3244 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3245 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3246
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3247 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3248 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3249 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3250 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3251 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3252 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3253 <funcdef>void <function>cyg_semaphore_init</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3254 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3255 <paramdef>cyg_count32 <parameter>val</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3256 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3257 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3258 <funcdef>void <function>cyg_semaphore_destroy</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3259 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3260 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3261 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3262 <funcdef>cyg_bool_t <function>cyg_semaphore_wait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3263 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3264 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3265 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3266 <funcdef>cyg_bool_t <function>cyg_semaphore_timed_wait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3267 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3268 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3269 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3270 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3271 <funcdef>cyg_bool_t <function>cyg_semaphore_trywait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3272 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3273 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3274 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3275 <funcdef>void <function>cyg_semaphore_post</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3276 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3277 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3278 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3279 <funcdef>void <function>cyg_semaphore_peek</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3280 <paramdef>cyg_sem_t* <parameter>sem</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3281 <paramdef>cyg_count32* <parameter>val</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3282 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3283 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3284 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3285
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3286 <refsect1 id="kernel-semaphores-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3287 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3288 Counting semaphores are a <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3289 linkend="kernel-overview-synch-primitives">synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3290 primitive</link> that allow threads to wait until an event has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3291 occurred. The event may be generated by a producer thread, or by a DSR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3292 in response to a hardware interrupt. Associated with each semaphore is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3293 an integer counter that keeps track of the number of events that have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3294 not yet been processed. If this counter is zero, an attempt by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3295 consumer thread to wait on the semaphore will block until some other
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3296 thread or a DSR posts a new event to the semaphore. If the counter is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3297 greater than zero then an attempt to wait on the semaphore will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3298 consume one event, in other words decrement the counter, and return
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3299 immediately. Posting to a semaphore will wake up the first thread that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3300 is currently waiting, which will then resume inside the semaphore wait
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3301 operation and decrement the counter again.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3302 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3303 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3304 Another use of semaphores is for certain forms of resource management.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3305 The counter would correspond to how many of a certain type of resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3306 are currently available, with threads waiting on the semaphore to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3307 claim a resource and posting to release the resource again. In
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3308 practice <link linkend="kernel-condition-variables">condition
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3309 variables</link> are usually much better suited for operations like
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3310 this.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3311 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3312 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3313 <function>cyg_semaphore_init</function> is used to initialize a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3314 semaphore. It takes two arguments, a pointer to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3315 <structname>cyg_sem_t</structname> structure and an initial value for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3316 the counter. Note that semaphore operations, unlike some other parts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3317 of the kernel API, use pointers to data structures rather than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3318 handles. This makes it easier to embed semaphores in a larger data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3319 structure. The initial counter value can be any number, zero, positive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3320 or negative, but typically a value of zero is used to indicate that no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3321 events have occurred yet.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3322 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3323 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3324 <function>cyg_semaphore_wait</function> is used by a consumer thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3325 to wait for an event. If the current counter is greater than 0, in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3326 other words if the event has already occurred in the past, then the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3327 counter will be decremented and the call will return immediately.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3328 Otherwise the current thread will be blocked until there is a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3329 <function>cyg_semaphore_post</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3330 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3331 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3332 <function>cyg_semaphore_post</function> is called when an event has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3333 occurs. This increments the counter and wakes up the first thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3334 waiting on the semaphore (if any). Usually that thread will then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3335 continue running inside <function>cyg_semaphore_wait</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3336 decrement the counter again. However other scenarioes are possible.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3337 For example the thread calling <function>cyg_semaphore_post</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3338 may be running at high priority, some other thread running at medium
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3339 priority may be about to call <function>cyg_semaphore_wait</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3340 when it next gets a chance to run, and a low priority thread may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3341 waiting on the semaphore. What will happen is that the current high
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3342 priority thread continues running until it is descheduled for some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3343 reason, then the medium priority thread runs and its call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3344 <function>cyg_semaphore_wait</function> succeeds immediately, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3345 later on the low priority thread runs again, discovers a counter value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3346 of 0, and blocks until another event is posted. If there are multiple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3347 threads blocked on a semaphore then the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3348 <varname>CYGIMP_KERNEL_SCHED_SORTED_QUEUES</varname> determines which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3349 one will be woken up by a post operation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3350 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3351 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3352 <function>cyg_semaphore_wait</function> returns a boolean. Normally it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3353 will block until it has successfully decremented the counter, retrying
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3354 as necessary, and return success. However the wait operation may be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3355 aborted by a call to <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3356 linkend="kernel-thread-control"><function>cyg_thread_release</function></link>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3357 and <function>cyg_semaphore_wait</function> will then return false.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3358 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3359 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3360 <function>cyg_semaphore_timed_wait</function> is a variant of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3361 <function>cyg_semaphore_wait</function>. It can be used to wait until
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3362 either an event has occurred or a number of clock ticks have happened.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3363 The function returns success if the semaphore wait operation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3364 succeeded, or false if the operation timed out or was aborted by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3365 <function>cyg_thread_release</function>. If support for the real-time
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3366 clock has been removed from the current configuration then this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3367 function will not be available.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3368 <function>cyg_semaphore_trywait</function> is another variant which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3369 will always return immediately rather than block, again returning
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3370 success or failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3371 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3372 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3373 <function>cyg_semaphore_peek</function> can be used to get hold of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3374 current counter value. This function is rarely useful except for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3375 debugging purposes since the counter value may change at any time if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3376 some other thread or a DSR performs a semaphore operation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3377 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3378 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3379
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3380 <refsect1 id="kernel-semaphores-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3381 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3382 <function>cyg_semaphore_init</function> is normally called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3383 initialization but may also be called from thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3384 <function>cyg_semaphore_wait</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3385 <function>cyg_semaphore_timed_wait</function> may only be called from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3386 thread context because these operations may block.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3387 <function>cyg_semaphore_trywait</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3388 <function>cyg_semaphore_post</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3389 <function>cyg_semaphore_peek</function> may be called from thread or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3390 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3391 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3392 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3393
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3394 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3395
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3396 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3397 <!-- {{{ Mail boxes -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3398
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3399 <refentry id="kernel-mail-boxes">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3400
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3401 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3402 <refentrytitle>Mail boxes</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3403 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3404
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3405 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3406 <refname>cyg_mbox_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3407 <refname>cyg_mbox_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3408 <refname>cyg_mbox_get</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3409 <refname>cyg_mbox_timed_get</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3410 <refname>cyg_mbox_tryget</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3411 <refname>cyg_mbox_peek_item</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3412 <refname>cyg_mbox_put</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3413 <refname>cyg_mbox_timed_put</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3414 <refname>cyg_mbox_tryput</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3415 <refname>cyg_mbox_peek</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3416 <refname>cyg_mbox_waiting_to_get</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3417 <refname>cyg_mbox_waiting_to_put</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3418 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3419 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3420
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3421 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3422 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3423 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3424 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3425 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3426 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3427 <funcdef>void <function>cyg_mbox_create</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3428 <paramdef>cyg_handle_t* <parameter>handle</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3429 <paramdef>cyg_mbox* <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3430 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3431 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3432 <funcdef>void <function>cyg_mbox_delete</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3433 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3434 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3435 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3436 <funcdef>void* <function>cyg_mbox_get</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3437 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3438 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3439 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3440 <funcdef>void* <function>cyg_mbox_timed_get</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3441 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3442 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3443 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3444 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3445 <funcdef>void* <function>cyg_mbox_tryget</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3446 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3447 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3448 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3449 <funcdef>cyg_count32 <function>cyg_mbox_peek</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3450 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3451 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3452 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3453 <funcdef>void* <function>cyg_mbox_peek_item</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3454 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3455 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3456 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3457 <funcdef>cyg_bool_t <function>cyg_mbox_put</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3458 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3459 <paramdef>void* <parameter>item</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3460 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3461 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3462 <funcdef>cyg_bool_t <function>cyg_mbox_timed_put</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3463 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3464 <paramdef>void* <parameter>item</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3465 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3466 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3467 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3468 <funcdef>cyg_bool_t <function>cyg_mbox_tryput</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3469 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3470 <paramdef>void* <parameter>item</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3471 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3472 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3473 <funcdef>cyg_bool_t <function>cyg_mbox_waiting_to_get</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3474 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3475 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3476 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3477 <funcdef>cyg_bool_t <function>cyg_mbox_waiting_to_put</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3478 <paramdef>cyg_handle_t <parameter>mbox</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3479 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3480 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3481 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3482
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3483 <refsect1 id="kernel-mail-boxes-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3484 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3485 Mail boxes are a synchronization primitive. Like semaphores they
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3486 can be used by a consumer thread to wait until a certain event has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3487 occurred, but the producer also has the ability to transmit some data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3488 along with each event. This data, the message, is normally a pointer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3489 to some data structure. It is stored in the mail box itself, so the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3490 producer thread that generates the event and provides the data usually
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3491 does not have to block until some consumer thread is ready to receive
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3492 the event. However a mail box will only have a finite capacity,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3493 typically ten slots. Even if the system is balanced and events are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3494 typically consumed at least as fast as they are generated, a burst of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3495 events can cause the mail box to fill up and the generating thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3496 will block until space is available again. This behaviour is very
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3497 different from semaphores, where it is only necessary to maintain a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3498 counter and hence an overflow is unlikely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3499 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3500 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3501 Before a mail box can be used it must be created with a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3502 <function>cyg_mbox_create</function>. Each mail box has a unique
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3503 handle which will be returned via the first argument and which should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3504 be used for subsequent operations.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3505 <function>cyg_mbox_create</function> also requires an area of memory
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3506 for the kernel structure, which is provided by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3507 <structname>cyg_mbox</structname> second argument. If a mail box is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3508 no longer required then <function>cyg_mbox_delete</function> can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3509 used. This will simply discard any messages that remain posted.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3510 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3511 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3512 The main function for waiting on a mail box is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3513 <function>cyg_mbox_get</function>. If there is a pending message
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3514 because of a call to <function>cyg_mbox_put</function> then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3515 <function>cyg_mbox_get</function> will return immediately with the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3516 message that was put into the mail box. Otherwise this function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3517 will block until there is a put operation. Exceptionally the thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3518 can instead be unblocked by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3519 <function>cyg_thread_release</function>, in which case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3520 <function>cyg_mbox_get</function> will return a null pointer. It is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3521 assumed that there will never be a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3522 <function>cyg_mbox_put</function> with a null pointer, because it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3523 would not be possible to distinguish between that and a release
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3524 operation. Messages are always retrieved in the order in which they
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3525 were put into the mail box, and there is no support for messages
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3526 with different priorities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3527 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3528 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3529 There are two variants of <function>cyg_mbox_get</function>. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3530 first, <function>cyg_mbox_timed_get</function> will wait until either
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3531 a message is available or until a number of clock ticks have occurred.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3532 If no message is posted within the timeout then a null pointer will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3533 returned. <function>cyg_mbox_tryget</function> is a non-blocking
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3534 operation which will either return a message if one is available or a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3535 null pointer.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3536 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3537 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3538 New messages are placed in the mail box by calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3539 <function>cyg_mbox_put</function> or one of its variants. The main put
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3540 function takes two arguments, a handle to the mail box and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3541 pointer for the message itself. If there is a spare slot in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3542 mail box then the new message can be placed there immediately, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3543 if there is a waiting thread it will be woken up so that it can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3544 receive the message. If the mail box is currently full then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3545 <function>cyg_mbox_put</function> will block until there has been a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3546 get operation and a slot is available. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3547 <function>cyg_mbox_timed_put</function> variant imposes a time limit
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3548 on the put operation, returning false if the operation cannot be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3549 completed within the specified number of clock ticks. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3550 <function>cyg_mbox_tryput</function> variant is non-blocking,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3551 returning false if there are no free slots available and the message
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3552 cannot be posted without blocking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3553 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3554 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3555 There are a further four functions available for examining the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3556 state of a mailbox. The results of these functions must be used with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3557 care because usually the state can change at any time as a result of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3558 activity within other threads, but they may prove occasionally useful
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3559 during debugging or in special situations.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3560 <function>cyg_mbox_peek</function> returns a count of the number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3561 messages currently stored in the mail box.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3562 <function>cyg_mbox_peek_item</function> retrieves the first message,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3563 but it remains in the mail box until a get operation is performed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3564 <function>cyg_mbox_waiting_to_get</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3565 <function>cyg_mbox_waiting_to_put</function> indicate whether or not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3566 there are currently threads blocked in a get or a put operation on a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3567 given mail box.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3568 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3569 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3570 The number of slots in each mail box is controlled by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3571 configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3572 <varname>CYGNUM_KERNEL_SYNCH_MBOX_QUEUE_SIZE</varname>, with a default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3573 value of 10. All mail boxes are the same size.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3574 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3575 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3576
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3577 <refsect1 id="kernel-mail-boxes-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3578 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3579 <function>cyg_mbox_create</function> is typically called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3580 system initialization but may also be called in thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3581 The remaining functions are normally called only during thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3582 context. Of special note is <function>cyg_mbox_put</function> which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3583 can be a blocking operation when the mail box is full, and which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3584 therefore must never be called from DSR context. It is permitted to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3585 call <function>cyg_mbox_tryput</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3586 <function>cyg_mbox_tryget</function>, and the information functions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3587 from DSR context but this is rarely useful.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3588 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3589 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3590
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3591 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3592
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3593 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3594 <!-- {{{ Flags -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3595
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3596 <refentry id="kernel-flags">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3597
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3598 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3599 <refentrytitle>Event Flags</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3600 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3601
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3602 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3603 <refname>cyg_flag_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3604 <refname>cyg_flag_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3605 <refname>cyg_flag_setbits</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3606 <refname>cyg_flag_maskbits</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3607 <refname>cyg_flag_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3608 <refname>cyg_flag_timed_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3609 <refname>cyg_flag_poll</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3610 <refname>cyg_flag_peek</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3611 <refname>cyg_flag_waiting</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3612 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3613 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3614
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3615 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3616 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3617 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3618 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3619 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3620 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3621 <funcdef>void <function>cyg_flag_init</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3622 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3623 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3624 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3625 <funcdef>void <function>cyg_flag_destroy</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3626 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3627 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3628 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3629 <funcdef>void <function>cyg_flag_setbits</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3630 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3631 <paramdef>cyg_flag_value_t <parameter>value</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3632 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3633 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3634 <funcdef>void <function>cyg_flag_maskbits</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3635 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3636 <paramdef>cyg_flag_value_t <parameter>value</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3637 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3638 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3639 <funcdef>cyg_flag_value_t <function>cyg_flag_wait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3640 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3641 <paramdef>cyg_flag_value_t <parameter>pattern</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3642 <paramdef>cyg_flag_mode_t <parameter>mode</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3643 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3644 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3645 <funcdef>cyg_flag_value_t <function>cyg_flag_timed_wait</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3646 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3647 <paramdef>cyg_flag_value_t <parameter>pattern</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3648 <paramdef>cyg_flag_mode_t <parameter>mode</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3649 <paramdef>cyg_tick_count_t <parameter>abstime</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3650 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3651 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3652 <funcdef>cyg_flag_value_t <function>cyg_flag_poll</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3653 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3654 <paramdef>cyg_flag_value_t <parameter>pattern</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3655 <paramdef>cyg_flag_mode_t <parameter>mode</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3656 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3657 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3658 <funcdef>cyg_flag_value_t <function>cyg_flag_peek</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3659 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3660 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3661 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3662 <funcdef>cyg_bool_t <function>cyg_flag_waiting</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3663 <paramdef>cyg_flag_t* <parameter>flag</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3664 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3665 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3666 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3667
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3668 <refsect1 id="kernel-flags-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3669 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3670 Event flags allow a consumer thread to wait for one of several
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3671 different types of event to occur. Alternatively it is possible to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3672 wait for some combination of events. The implementation is relatively
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3673 straightforward. Each event flag contains a 32-bit integer.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3674 Application code associates these bits with specific events, so for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3675 example bit 0 could indicate that an I/O operation has completed and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3676 data is available, while bit 1 could indicate that the user has
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3677 pressed a start button. A producer thread or a DSR can cause one or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3678 more of the bits to be set, and a consumer thread currently waiting
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3679 for these bits will be woken up.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3680 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3681 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3682 Unlike semaphores no attempt is made to keep track of event counts. It
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3683 does not matter whether a given event occurs once or multiple times
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3684 before being consumed, the corresponding bit in the event flag will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3685 change only once. However semaphores cannot easily be used to handle
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3686 multiple event sources. Event flags can often be used as an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3687 alternative to condition variables, although they cannot be used for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3688 completely arbitrary conditions and they only support the equivalent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3689 of condition variable broadcasts, not signals.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3690 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3691 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3692 Before an event flag can be used it must be initialized by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3693 <function>cyg_flag_init</function>. This takes a pointer to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3694 <structname>cyg_flag_t</structname> data structure, which can be part of a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3695 larger structure. All 32 bits in the event flag will be set to 0,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3696 indicating that no events have yet occurred. If an event flag is no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3697 longer required it can be cleaned up with a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3698 <function>cyg_flag_destroy</function>, allowing the memory for the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3699 <structfield>cyg_flag_t</structfield> structure to be re-used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3700 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3701 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3702 A consumer thread can wait for one or more events by calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3703 <function>cyg_flag_wait</function>. This takes three arguments. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3704 first identifies a particular event flag. The second is some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3705 combination of bits, indicating which events are of interest. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3706 final argument should be one of the following:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3707 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3708 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3709 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3710 <term><literal>CYG_FLAG_WAITMODE_AND</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3711 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3712 The call to <function>cyg_flag_wait</function> will block until all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3713 the specified event bits are set. The event flag is not cleared when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3714 the wait succeeds, in other words all the bits remain set.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3715 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3716 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3717 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3718 <term><literal>CYG_FLAG_WAITMODE_OR</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3719 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3720 The call will block until at least one of the specified event bits is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3721 set. The event flag is not cleared on return.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3722 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3723 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3724 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3725 <term><literal>CYG_FLAG_WAITMODE_AND | CYG_FLAG_WAITMODE_CLR</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3726 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3727 The call will block until all the specified event bits are set, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3728 the entire event flag is cleared when the call succeeds. Note that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3729 if this mode of operation is used then a single event flag cannot be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3730 used to store disjoint sets of events, even though enough bits might
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3731 be available. Instead each disjoint set of events requires its own
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3732 event flag.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3733 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3734 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3735 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3736 <term><literal>CYG_FLAG_WAITMODE_OR | CYG_FLAG_WAITMODE_CLR</literal></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3737 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3738 The call will block until at least one of the specified event bits is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3739 set, and the entire flag is cleared when the call succeeds.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3740 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3741 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3742 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3743 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3744 A call to <function>cyg_flag_wait</function> normally blocks until the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3745 required condition is satisfied. It will return the value of the event
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3746 flag at the point that the operation succeeded, which may be a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3747 superset of the requested events. If
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3748 <function>cyg_thread_release</function> is used to unblock a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3749 that is currently in a wait operation, the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3750 <function>cyg_flag_wait</function> call will instead return 0.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3751 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3752 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3753 <function>cyg_flag_timed_wait</function> is a variant of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3754 <function>cyg_flag_wait</function> which adds a timeout: the wait
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3755 operation must succeed within the specified number of ticks, or it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3756 will fail with a return value of 0. <function>cyg_flag_poll</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3757 is a non-blocking variant: if the wait operation can succeed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3758 immediately it acts like <function>cyg_flag_wait</function>, otherwise
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3759 it returns immediately with a value of 0.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3760 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3761 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3762 <function>cyg_flag_setbits</function> is called by a producer thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3763 or from inside a DSR when an event occurs. The specified bits are or'd
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3764 into the current event flag value. This may cause a waiting thread to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3765 be woken up, if its condition is now satisfied.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3766 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3767 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3768 <function>cyg_flag_maskbits</function> can be used to clear one or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3769 more bits in the event flag. This can be called from a producer when a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3770 particular condition is no longer satisfied, for example when the user
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3771 is no longer pressing a particular button. It can also be used by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3772 consumer thread if <literal>CYG_FLAG_WAITMODE_CLR</literal> was not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3773 used as part of the wait operation, to indicate that some but not all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3774 of the active events have been consumed. If there are multiple
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3775 consumer threads performing wait operations without using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3776 <function>CYG_FLAG_WAITMODE_CLR</function> then typically some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3777 additional synchronization such as a mutex is needed to prevent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3778 multiple threads consuming the same event.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3779 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3780 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3781 Two additional functions are provided to query the current state of an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3782 event flag. <function>cyg_flag_peek</function> returns the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3783 value of the event flag, and <function>cyg_flag_waiting</function> can
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3784 be used to find out whether or not there are any threads currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3785 blocked on the event flag. Both of these functions must be used with
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3786 care because other threads may be operating on the event flag.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3787 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3788 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3789
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3790 <refsect1 id="kernel-flags-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3791 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3792 <function>cyg_flag_init</function> is typically called during system
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3793 initialization but may also be called in thread context. The same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3794 applies to <function>cyg_flag_destroy</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3795 <function>cyg_flag_wait</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3796 <function>cyg_flag_timed_wait</function> may only be called from
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3797 thread context. The remaining functions may be called from thread or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3798 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3799 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3800 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3801
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3802 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3803
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3804 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3805 <!-- {{{ Spinlocks -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3806
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3807 <refentry id="kernel-spinlocks">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3808
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3809 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3810 <refentrytitle>Spinlocks</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3811 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3812
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3813 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3814 <refname>cyg_spinlock_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3815 <refname>cyg_spinlock_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3816 <refname>cyg_spinlock_spin</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3817 <refname>cyg_spinlock_clear</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3818 <refname>cyg_spinlock_test</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3819 <refname>cyg_spinlock_spin_intsave</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3820 <refname>cyg_spinlock_clear_intsave</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3821 <refpurpose>Low-level Synchronization Primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3822 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3823
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3824 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3825 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3826 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3827 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3828 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3829 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3830 <funcdef>void <function>cyg_spinlock_init</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3831 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3832 <paramdef>cyg_bool_t <parameter>locked</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3833 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3834 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3835 <funcdef>void <function>cyg_spinlock_destroy</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3836 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3837 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3838 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3839 <funcdef>void <function>cyg_spinlock_spin</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3840 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3841 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3842 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3843 <funcdef>void <function>cyg_spinlock_clear</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3844 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3845 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3846 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3847 <funcdef>cyg_bool_t <function>cyg_spinlock_try</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3848 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3849 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3850 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3851 <funcdef>cyg_bool_t <function>cyg_spinlock_test</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3852 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3853 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3854 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3855 <funcdef>void <function>cyg_spinlock_spin_intsave</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3856 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3857 <paramdef>cyg_addrword_t* <parameter>istate</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3858 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3859 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3860 <funcdef>void <function>cyg_spinlock_clear_intsave</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3861 <paramdef>cyg_spinlock_t* <parameter>lock</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3862 <paramdef>cyg_addrword_t <parameter>istate</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3863 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3864 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3865 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3866
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3867 <refsect1 id="kernel-spinlocks-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3868 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3869 Spinlocks provide an additional synchronization primitive for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3870 applications running on SMP systems. They operate at a lower level
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3871 than the other primitives such as mutexes, and for most purposes the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3872 higher-level primitives should be preferred. However there are some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3873 circumstances where a spinlock is appropriate, especially when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3874 interrupt handlers and threads need to share access to hardware, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3875 on SMP systems the kernel implementation itself depends on spinlocks.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3876 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3877 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3878 Essentially a spinlock is just a simple flag. When code tries to claim
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3879 a spinlock it checks whether or not the flag is already set. If not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3880 then the flag is set and the operation succeeds immediately. The exact
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3881 implementation of this is hardware-specific, for example it may use a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3882 test-and-set instruction to guarantee the desired behaviour even if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3883 several processors try to access the spinlock at the exact same time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3884 If it is not possible to claim a spinlock then the current thead spins
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3885 in a tight loop, repeatedly checking the flag until it is clear. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3886 behaviour is very different from other synchronization primitives such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3887 as mutexes, where contention would cause a thread to be suspended. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3888 assumption is that a spinlock will only be held for a very short time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3889 If claiming a spinlock could cause the current thread to be suspended
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3890 then spinlocks could not be used inside interrupt handlers, which is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3891 not acceptable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3892 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3893 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3894 This does impose a constraint on any code which uses spinlocks.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3895 Specifically it is important that spinlocks are held only for a short
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3896 period of time, typically just some dozens of instructions. Otherwise
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3897 another processor could be blocked on the spinlock for a long time,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3898 unable to do any useful work. It is also important that a thread which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3899 owns a spinlock does not get preempted because that might cause
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3900 another processor to spin for a whole timeslice period, or longer. One
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3901 way of achieving this is to disable interrupts on the current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3902 processor, and the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3903 <function>cyg_spinlock_spin_intsave</function> is provided to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3904 facilitate this.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3905 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3906 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3907 Spinlocks should not be used on single-processor systems. Consider a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3908 high priority thread which attempts to claim a spinlock already held
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3909 by a lower priority thread: it will just loop forever and the lower
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3910 priority thread will never get another chance to run and release the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3911 spinlock. Even if the two threads were running at the same priority,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3912 the one attempting to claim the spinlock would spin until it was
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3913 timesliced and a lot of cpu time would be wasted. If an interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3914 handler tried to claim a spinlock owned by a thread, the interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3915 handler would loop forever. Therefore spinlocks are only appropriate
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3916 for SMP systems where the current owner of a spinlock can continue
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3917 running on a different processor.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3918 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3919 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3920 Before a spinlock can be used it must be initialized by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3921 <function>cyg_spinlock_init</function>. This takes two arguments, a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3922 pointer to a <function>cyg_spinlock_t</function> data structure, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3923 a flag to specify whether the spinlock starts off locked or unlocked.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3924 If a spinlock is no longer required then it can be destroyed by a call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3925 to <function>cyg_spinlock_destroy</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3926 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3927 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3928 There are two routines for claiming a spinlock:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3929 <function>cyg_spinlock_spin</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3930 <function>cyg_spinlock_spin_intsave</function>. The former can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3931 when it is known the current code will not be preempted, for example
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3932 because it is running in an interrupt handler or because interrupts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3933 are disabled. The latter will disable interrupts in addition to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3934 claiming the spinlock, so is safe to use in all circumstances. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3935 previous interrupt state is returned via the second argument, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3936 should be used in a subsequent call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3937 <function>cyg_spinlock_clear_intsave</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3938 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3939 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3940 Similarly there are two routines for releasing a spinlock:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3941 <function>cyg_spinlock_clear</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3942 <function>cyg_spinlock_clear_intsave</function>. Typically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3943 the former will be used if the spinlock was claimed by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3944 <function>cyg_spinlock_spin</function>, and the latter when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3945 <function>cyg_spinlock_intsave</function> was used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3946 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3947 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3948 There are two additional routines.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3949 <function>cyg_spinlock_try</function> is a non-blocking version of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3950 <function>cyg_spinlock_spin</function>: if possible the lock will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3951 claimed and the function will return <literal>true</literal>; otherwise the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3952 will return immediately with failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3953 <function>cyg_spinlock_test</function> can be used to find out whether
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3954 or not the spinlock is currently locked. This function must be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3955 with care because, especially on a multiprocessor system, the state of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3956 the spinlock can change at any time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3957 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3958 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3959 Spinlocks should only be held for a short period of time, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3960 attempting to claim a spinlock will never cause a thread to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3961 suspended. This means that there is no need to worry about priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3962 inversion problems, and concepts such as priority ceilings and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3963 inheritance do not apply.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3964 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3965 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3966
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3967 <refsect1 id="kernel-spinlocks-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3968 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3969 All of the spinlock functions can be called from any context,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3970 including ISR and DSR context. Typically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3971 <function>cyg_spinlock_init</function> is only called during system
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3972 initialization.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3973 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3974 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3975
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3976 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3977
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3978 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3979 <!-- {{{ Scheduler control -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3980
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3981 <refentry id="kernel-schedcontrol">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3982
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3983 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3984 <refentrytitle>Scheduler Control</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3985 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3986
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3987 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3988 <refname>cyg_scheduler_start</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3989 <refname>cyg_scheduler_lock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3990 <refname>cyg_scheduler_unlock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3991 <refname>cyg_scheduler_safe_lock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3992 <refname>cyg_scheduler_read_lock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3993 <refpurpose>Control the state of the scheduler</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3994 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3995
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3996 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3997 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3998 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3999 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4000 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4001 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4002 <funcdef>void <function>cyg_scheduler_start</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4003 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4004 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4005 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4006 <funcdef>void <function>cyg_scheduler_lock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4007 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4008 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4009 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4010 <funcdef>void <function>cyg_scheduler_unlock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4011 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4012 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4013 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4014 <funcdef>cyg_ucount32 <function>cyg_scheduler_read_lock</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4015 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4016 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4017 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4018 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4019
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4020 <refsect1 id="kernel-schedcontrol-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4021 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4022 <function>cyg_scheduler_start</function> should only be called once,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4023 to mark the end of system initialization. In typical configurations it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4024 is called automatically by the system startup, but some applications
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4025 may bypass the standard startup in which case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4026 <function>cyg_scheduler_start</function> will have to be called
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4027 explicitly. The call will enable system interrupts, allowing I/O
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4028 operations to commence. Then the scheduler will be invoked and control
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4029 will be transferred to the highest priority runnable thread. The call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4030 will never return.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4031 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4032 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4033 The various data structures inside the eCos kernel must be protected
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4034 against concurrent updates. Consider a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4035 <function>cyg_semaphore_post</function> which causes a thread to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4036 woken up: the semaphore data structure must be updated to remove the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4037 thread from its queue; the scheduler data structure must also be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4038 updated to mark the thread as runnable; it is possible that the newly
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4039 runnable thread has a higher priority than the current one, in which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4040 case preemption is required. If in the middle of the semaphore post
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4041 call an interrupt occurred and the interrupt handler tried to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4042 manipulate the same data structures, for example by making another
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4043 thread runnable, then it is likely that the structures will be left in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4044 an inconsistent state and the system will fail.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4045 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4046 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4047 To prevent such problems the kernel contains a special lock known as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4048 the scheduler lock. A typical kernel function such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4049 <function>cyg_semaphore_post</function> will claim the scheduler lock,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4050 do all its manipulation of kernel data structures, and then release
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4051 the scheduler lock. The current thread cannot be preempted while it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4052 holds the scheduler lock. If an interrupt occurs and a DSR is supposed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4053 to run to signal that some event has occurred, that DSR is postponed
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4054 until the scheduler unlock operation. This prevents concurrent updates
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4055 of kernel data structures.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4056 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4057 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4058 The kernel exports three routines for manipulating the scheduler lock.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4059 <function>cyg_scheduler_lock</function> can be called to claim the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4060 lock. On return it is guaranteed that the current thread will not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4061 preempted, and that no other code is manipulating any kernel data
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4062 structures. <function>cyg_scheduler_unlock</function> can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4063 release the lock, which may cause the current thread to be preempted.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4064 <function>cyg_scheduler_read_lock</function> can be used to query the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4065 current state of the scheduler lock. This function should never be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4066 needed because well-written code should always know whether or not the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4067 scheduler is currently locked, but may prove useful during debugging.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4068 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4069 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4070 The implementation of the scheduler lock involves a simple counter.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4071 Code can call <function>cyg_scheduler_lock</function> multiple times,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4072 causing the counter to be incremented each time, as long as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4073 <function>cyg_scheduler_unlock</function> is called the same number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4074 times. This behaviour is different from mutexes where an attempt by a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4075 thread to lock a mutex multiple times will result in deadlock or an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4076 assertion failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4077 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4078 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4079 Typical application code should not use the scheduler lock. Instead
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4080 other synchronization primitives such as mutexes and semaphores should
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4081 be used. While the scheduler is locked the current thread cannot be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4082 preempted, so any higher priority threads will not be able to run.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4083 Also no DSRs can run, so device drivers may not be able to service
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4084 I/O requests. However there is one situation where locking the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4085 scheduler is appropriate: if some data structure needs to be shared
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4086 between an application thread and a DSR associated with some interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4087 source, the thread can use the scheduler lock to prevent concurrent
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4088 invocations of the DSR and then safely manipulate the structure. It is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4089 desirable that the scheduler lock is held for only a short period of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4090 time, typically some tens of instructions. In exceptional cases there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4091 may also be some performance-critical code where it is more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4092 appropriate to use the scheduler lock rather than a mutex, because the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4093 former is more efficient.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4094 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4095 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4096
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4097 <refsect1 id="kernel-schedcontrol-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4098 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4099 <function>cyg_scheduler_start</function> can only be called during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4100 system initialization, since it marks the end of that phase. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4101 remaining functions may be called from thread or DSR context. Locking
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4102 the scheduler from inside the DSR has no practical effect because the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4103 lock is claimed automatically by the interrupt subsystem before
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4104 running DSRs, but allows functions to be shared between normal thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4105 code and DSRs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4106 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4107 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4108
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4109 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4110
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4111 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4112 <!-- {{{ Interrupt handling -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4113
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4114 <refentry id="kernel-interrupts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4115
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4116 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4117 <refentrytitle>Interrupt Handling</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4118 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4119
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4120 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4121 <refname>cyg_interrupt_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4122 <refname>cyg_interrupt_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4123 <refname>cyg_interrupt_attach</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4124 <refname>cyg_interrupt_detach</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4125 <refname>cyg_interrupt_configure</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4126 <refname>cyg_interrupt_acknowledge</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4127 <refname>cyg_interrupt_enable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4128 <refname>cyg_interrupt_disable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4129 <refname>cyg_interrupt_mask</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4130 <refname>cyg_interrupt_mask_intunsafe</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4131 <refname>cyg_interrupt_unmask</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4132 <refname>cyg_interrupt_unmask_intunsafe</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4133 <refname>cyg_interrupt_set_cpu</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4134 <refname>cyg_interrupt_get_cpu</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4135 <refname>cyg_interrupt_get_vsr</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4136 <refname>cyg_interrupt_set_vsr</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4137 <refpurpose>Manage interrupt handlers</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4138 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4139
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4140 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4141 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4142 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4143 #include &lt;cyg/kernel/kapi.h&gt;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4144 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4145 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4146 <funcdef>void <function>cyg_interrupt_create</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4147 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4148 <paramdef>cyg_priority_t <parameter>priority</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4149 <paramdef>cyg_addrword_t <parameter>data</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4150 <paramdef>cyg_ISR_t* <parameter>isr</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4151 <paramdef>cyg_DSR_t* <parameter>dsr</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4152 <paramdef>cyg_handle_t* <parameter>handle</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4153 <paramdef>cyg_interrupt* <parameter>intr</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4154 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4155 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4156 <funcdef>void <function>cyg_interrupt_delete</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4157 <paramdef>cyg_handle_t <parameter>interrupt</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4158 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4159 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4160 <funcdef>void <function>cyg_interrupt_attach</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4161 <paramdef>cyg_handle_t <parameter>interrupt</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4162 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4163 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4164 <funcdef>void <function>cyg_interrupt_detach</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4165 <paramdef>cyg_handle_t <parameter>interrupt</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4166 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4167 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4168 <funcdef>void <function>cyg_interrupt_configure</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4169 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4170 <paramdef>cyg_bool_t <parameter>level</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4171 <paramdef>cyg_bool_t <parameter>up</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4172 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4173 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4174 <funcdef>void <function>cyg_interrupt_acknowledge</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4175 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4176 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4177 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4178 <funcdef>void <function>cyg_interrupt_disable</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4179 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4180 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4181 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4182 <funcdef>void <function>cyg_interrupt_enable</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4183 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4184 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4185 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4186 <funcdef>void <function>cyg_interrupt_mask</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4187 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4188 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4189 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4190 <funcdef>void <function>cyg_interrupt_mask_intunsafe</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4191 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4192 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4193 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4194 <funcdef>void <function>cyg_interrupt_unmask</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4195 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4196 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4197 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4198 <funcdef>void <function>cyg_interrupt_unmask_intunsafe</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4199 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4200 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4201 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4202 <funcdef>void <function>cyg_interrupt_set_cpu</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4203 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4204 <paramdef>cyg_cpu_t <parameter>cpu</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4205 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4206 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4207 <funcdef>cyg_cpu_t <function>cyg_interrupt_get_cpu</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4208 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4209 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4210 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4211 <funcdef>void <function>cyg_interrupt_get_vsr</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4212 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4213 <paramdef>cyg_VSR_t** <parameter>vsr</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4214 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4215 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4216 <funcdef>void <function>cyg_interrupt_set_vsr</function></funcdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4217 <paramdef>cyg_vector_t <parameter>vector</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4218 <paramdef>cyg_VSR_t* <parameter>vsr</parameter></paramdef>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4219 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4220 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4221 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4222
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4223 <refsect1 id="kernel-interrupts-description"><title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4224 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4225 The kernel provides an interface for installing interrupt handlers and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4226 controlling when interrupts occur. This functionality is used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4227 primarily by eCos device drivers and by any application code that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4228 interacts directly with hardware. However in most cases it is better
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4229 to avoid using this kernel functionality directly, and instead the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4230 device driver API provided by the common HAL package should be used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4231 Use of the kernel package is optional, and some applications such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4232 RedBoot work with no need for multiple threads or synchronization
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4233 primitives. Any code which calls the kernel directly rather than the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4234 device driver API will not function in such a configuration. When the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4235 kernel package is present the device driver API is implemented as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4236 <literal>#define</literal>'s to the equivalent kernel calls, otherwise
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4237 it is implemented inside the common HAL package. The latter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4238 implementation can be simpler than the kernel one because there is no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4239 need to consider thread preemption and similar issues.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4240 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4241 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4242 The exact details of interrupt handling vary widely between
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4243 architectures. The functionality provided by the kernel abstracts away
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4244 from many of the details of the underlying hardware, thus simplifying
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4245 application development. However this is not always successful. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4246 example, if some hardware does not provide any support at all for
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4247 masking specific interrupts then calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4248 <function>cyg_interrupt_mask</function> may not behave as intended:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4249 instead of masking just the one interrupt source it might disable all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4250 interrupts, because that is as close to the desired behaviour as is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4251 possible given the hardware restrictions. Another possibility is that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4252 masking a given interrupt source also affects all lower-priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4253 interrupts, but still allows higher-priority ones. The documentation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4254 for the appropriate HAL packages should be consulted for more
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4255 information about exactly how interrupts are handled on any given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4256 hardware. The HAL header files will also contain useful information.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4257 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4258 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4259
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4260 <refsect1 id="kernel-interrupts-handlers"><title>Interrupt Handlers</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4261 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4262 Interrupt handlers are created by a call to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4263 <function>cyg_interrupt_create</function>. This takes the following
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4264 arguments:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4265 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4266 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4267 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4268 <term>cyg_vector_t <parameter>vector</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4269 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4270 The interrupt vector, a small integer, identifies the specific
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4271 interrupt source. The appropriate hardware documentation or HAL header
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4272 files should be consulted for details of which vector corresponds to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4273 which device.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4274 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4275 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4276 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4277 <term>cyg_priority_t <parameter>priority</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4278 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4279 Some hardware may support interrupt priorities, where a low priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4280 interrupt handler can in turn be interrupted by a higher priority one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4281 Again hardware-specific documentation should be consulted for details
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4282 about what the valid interrupt priority levels are.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4283 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4284 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4285 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4286 <term>cyg_addrword_t <parameter>data</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4287 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4288 When an interrupt occurs eCos will first call the associated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4289 interrupt service routine or ISR, then optionally a deferred service
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4290 routine or DSR. The <parameter>data</parameter> argument to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4291 <function>cyg_interrupt_create</function> will be passed to both these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4292 functions. Typically it will be a pointer to some data structure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4293 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4294 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4295 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4296 <term>cyg_ISR_t <parameter>isr</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4297 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4298 When an interrupt occurs the hardware will transfer control to the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4299 appropriate vector service routine or VSR, which is usually provided
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4300 by eCos. This performs any appropriate processing, for example to work
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4301 out exactly which interrupt occurred, and then as quickly as possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4302 transfers control the installed ISR. An ISR is a C function which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4303 takes the following form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4304 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4305 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4306 cyg_uint32
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4307 isr_function(cyg_vector_t vector, cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4308 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4309 cyg_bool_t dsr_required = 0;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4310
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4311 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4312
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4313 return dsr_required ? CYG_ISR_CALL_DSR : CYG_ISR_HANDLED;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4314 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4315 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4316 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4317 The first argument identifies the particular interrupt source,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4318 especially useful if there multiple instances of a given device and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4319 single ISR can be used for several different interrupt vectors. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4320 second argument is the <parameter>data</parameter> field passed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4321 <function>cyg_interrupt_create</function>, usually a pointer to some
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4322 data structure. The exact conditions under which an ISR runs will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4323 depend partly on the hardware and partly on configuration options.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4324 Interrupts may currently be disabled globally, especially if the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4325 hardware does not support interrupt priorities. Alternatively
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4326 interrupts may be enabled such that higher priority interrupts are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4327 allowed through. The ISR may be running on a separate interrupt stack,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4328 or on the stack of whichever thread was running at the time the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4329 interrupt happened.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4330 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4331 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4332 A typical ISR will do as little work as possible, just enough to meet
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4333 the needs of the hardware and then acknowledge the interrupt by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4334 calling <function>cyg_interrupt_acknowledge</function>. This ensures
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4335 that interrupts will be quickly reenabled, so higher priority devices
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4336 can be serviced. For some applications there may be one device which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4337 is especially important and whose ISR can take much longer than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4338 normal. However eCos device drivers usually will not assume that they
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4339 are especially important, so their ISRs will be as short as possible.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4340 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4341 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4342 The return value of an ISR is normally one of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4343 <literal>CYG_ISR_CALL_DSR</literal> or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4344 <literal>CYG_ISR_HANDLED</literal>. The former indicates that further
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4345 processing is required at DSR level, and the interrupt handler's DSR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4346 will be run as soon as possible. The latter indicates that the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4347 interrupt has been fully handled and no further effort is required.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4348 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4349 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4350 An ISR is allowed to make very few kernel calls. It can manipulate the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4351 interrupt mask, and on SMP systems it can use spinlocks. However an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4352 ISR must not make higher-level kernel calls such as posting to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4353 semaphore, instead any such calls must be made from the DSR. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4354 avoids having to disable interrupts throughout the kernel and thus
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4355 improves interrupt latency.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4356 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4357 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4358 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4359 <term>cyg_DSR_t <parameter>dsr</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4360 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4361 If an interrupt has occurred and the ISR has returned a value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4362 <literal>CYG_ISR_CALL_DSR</literal>, the system will call the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4363 deferred service routine or DSR associated with this interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4364 handler. If the scheduler is not currently locked then the DSR will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4365 run immediately. However if the interrupted thread was in the middle
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4366 of a kernel call and had locked the scheduler, then the DSR will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4367 deferred until the scheduler is again unlocked. This allows the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4368 DSR to make certain kernel calls safely, for example posting to a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4369 semaphore or signalling a condition variable. A DSR is a C function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4370 which takes the following form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4371 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4372 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4373 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4374 dsr_function(cyg_vector_t vector,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4375 cyg_ucount32 count,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4376 cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4377 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4378 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4379 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4380 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4381 The first argument identifies the specific interrupt that has caused
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4382 the DSR to run. The second argument indicates the number of these
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4383 interrupts that have occurred and for which the ISR requested a DSR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4384 Usually this will be <literal>1</literal>, unless the system is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4385 suffering from a very heavy load. The third argument is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4386 <parameter>data</parameter> field passed to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4387 <function>cyg_interrupt_create</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4388 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4389 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4390 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4391 <term>cyg_handle_t* <parameter>handle</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4392 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4393 The kernel will return a handle to the newly created interrupt handler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4394 via this argument. Subsequent operations on the interrupt handler such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4395 as attaching it to the interrupt source will use this handle.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4396 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4397 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4398 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4399 <term>cyg_interrupt* <parameter>intr</parameter></term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4400 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4401 This provides the kernel with an area of memory for holding this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4402 interrupt handler and associated data.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4403 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4404 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4405 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4406 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4407 The call to <function>cyg_interrupt_create</function> simply fills in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4408 a kernel data structure. A typical next step is to call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4409 <function>cyg_interrupt_attach</function> using the handle returned by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4410 the create operation. This makes it possible to have several different
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4411 interrupt handlers for a given vector, attaching whichever one is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4412 currently appropriate. Replacing an interrupt handler requires a call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4413 to <function>cyg_interrupt_detach</function>, followed by another call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4414 to <function>cyg_interrupt_attach</function> for the replacement
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4415 handler. <function>cyg_interrupt_delete</function> can be used if an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4416 interrupt handler is no longer required.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4417 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4418 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4419 Some hardware may allow for further control over specific interrupts,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4420 for example whether an interrupt is level or edge triggered. Any such
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4421 hardware functionality can be accessed using
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4422 <function>cyg_interrupt_configure</function>: the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4423 <parameter>level</parameter> argument selects between level versus
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4424 edge triggered; the <parameter>up</parameter> argument selects between
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4425 high and low level, or between rising and falling edges.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4426 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4427 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4428 Usually interrupt handlers are created, attached and configured during
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4429 system initialization, while global interrupts are still disabled. On
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4430 most hardware it will also be necessary to call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4431 <function>cyg_interrupt_unmask</function>, since the sensible default
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4432 for interrupt masking is to ignore any interrupts for which no handler
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4433 is installed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4434 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4435 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4436
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4437 <refsect1 id="kernel-interrupts-enable"><title>Controlling Interrupts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4438 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4439 eCos provides two ways of controlling whether or not interrupts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4440 happen. It is possible to disable and reenable all interrupts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4441 globally, using <function>cyg_interrupt_disable</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4442 <function>cyg_interrupt_enable</function>. Typically this works by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4443 manipulating state inside the cpu itself, for example setting a flag
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4444 in a status register or executing special instructions. Alternatively
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4445 it may be possible to mask a specific interrupt source by writing to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4446 one or to several interrupt mask registers. Hardware-specific
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4447 documentation should be consulted for the exact details of how
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4448 interrupt masking works, because a full implementation is not possible
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4449 on all hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4450 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4451 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4452 The primary use for these functions is to allow data to be shared
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4453 between ISRs and other code such as DSRs or threads. If both a thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4454 and an ISR need to manipulate either a data structure or the hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4455 itself, there is a possible conflict if an interrupt happens just when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4456 the thread is doing such manipulation. Problems can be avoided by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4457 thread either disabling or masking interrupts during the critical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4458 region. If this critical region requires only a few instructions then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4459 usually it is more efficient to disable interrupts. For larger
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4460 critical regions it may be more appropriate to use interrupt masking,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4461 allowing other interrupts to occur. There are other uses for interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4462 masking. For example if a device is not currently being used by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4463 application then it may be desirable to mask all interrupts generated
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4464 by that device.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4465 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4466 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4467 There are two functions for masking a specific interrupt source,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4468 <function>cyg_interrupt_mask</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4469 <function>cyg_interrupt_mask_intunsafe</function>. On typical hardware
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4470 masking an interrupt is not an atomic operation, so if two threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4471 were to perform interrupt masking operations at the same time there
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4472 could be problems. <function>cyg_interrupt_mask</function> disables
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4473 all interrupts while it manipulates the interrupt mask. In situations
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4474 where interrupts are already know to be disabled,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4475 <function>cyg_interrupt_mask_intunsafe</function> can be used
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4476 instead. There are matching functions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4477 <function>cyg_interrupt_unmask</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4478 <function>cyg_interrupt_unmask_intsafe</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4479 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4480 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4481
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4482 <refsect1 id="kernel-interrupts-smp"><title>SMP Support</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4483 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4484 On SMP systems the kernel provides an additional two functions related
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4485 to interrupt handling. <function>cyg_interrupt_set_cpu</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4486 specifies that a particular hardware interrupt should always be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4487 handled on one specific processor in the system. In other words when
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4488 the interrupt triggers it is only that processor which detects it, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4489 it is only on that processor that the VSR and ISR will run. If a DSR
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4490 is requested then it will also run on the same CPU. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4491 function <function>cyg_interrupt_get_cpu</function> can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4492 find out which interrupts are handled on which processor.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4493 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4494 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4495
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4496 <refsect1 id="kernel-interrupts-vsr"><title>VSR Support</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4497 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4498 When an interrupt occurs the hardware will transfer control to a piece
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4499 of code known as the VSR, or Vector Service Routine. By default this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4500 code is provided by eCos. Usually it is written in assembler, but on
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4501 some architectures it may be possible to implement VSRs in C by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4502 specifying an interrupt attribute. Compiler documentation should be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4503 consulted for more information on this. The default eCos VSR will work
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4504 out which ISR function should process the interrupt, and set up a C
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4505 environment suitable for this ISR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4506 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4507 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4508 For some applications it may be desirable to replace the default eCos
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4509 VSR and handle some interrupts directly. This minimizes interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4510 latency, but it requires application developers to program at a lower
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4511 level. Usually the best way to write a custom VSR is to copy the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4512 existing one supplied by eCos and then make appropriate modifications.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4513 The function <function>cyg_interrupt_get_vsr</function> can be used to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4514 get hold of the current VSR for a given interrupt vector, allowing it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4515 to be restored if the custom VSR is no longer required.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4516 <function>cyg_interrupt_set_vsr</function> can be used to install a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4517 replacement VSR. Usually the <parameter>vsr</parameter> argument will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4518 correspond to an exported label in an assembler source file.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4519 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4520 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4521
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4522 <refsect1 id="kernel-interrupts-context"><title>Valid contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4523 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4524 In a typical configuration interrupt handlers are created and attached
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4525 during system initialization, and never detached or deleted. However
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4526 it is possible to perform these operations at thread level, if
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4527 desired. Similarly <function>cyg_interrupt_configure</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4528 <function>cyg_interrupt_set_vsr</function>, and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4529 <function>cyg_interrupt_set_cpu</function> are usually called only
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4530 during system initialization, but on typical hardware may be called at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4531 any time. <function>cyg_interrupt_get_vsr</function> and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4532 <function>cyg_interrupt_get_cpu</function> may be called at any time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4533 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4534 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4535 The functions for enabling, disabling, masking and unmasking
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4536 interrupts can be called in any context, when appropriate. It is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4537 responsibility of application developers to determine when the use of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4538 these functions is appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4539 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4540 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4541
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4542 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4543
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4544 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4545 <!-- {{{ tm_basic -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4546
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4547 <refentry id="kernel-characterization">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4548
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4549 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4550 <refentrytitle>Kernel Real-time Characterization</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4551 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4552 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4553 <refname>tm_basic</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4554 <refpurpose>Measure the performance of the eCos kernel</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4555 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4556
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4557 <refsect1 id="kernel-characterization-description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4558 <title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4559 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4560 When building a real-time system, care must be taken to ensure that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4561 the system will be able to perform properly within the constraints of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4562 that system. One of these constraints may be how fast certain
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4563 operations can be performed. Another might be how deterministic the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4564 overall behavior of the system is. Lastly the memory footprint (size)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4565 and unit cost may be important.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4566 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4567 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4568 One of the major problems encountered while evaluating a system will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4569 be how to compare it with possible alternatives. Most manufacturers of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4570 real-time systems publish performance numbers, ostensibly so that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4571 users can compare the different offerings. However, what these numbers
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4572 mean and how they were gathered is often not clear. The values are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4573 typically measured on a particular piece of hardware, so in order to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4574 truly compare, one must obtain measurements for exactly the same set
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4575 of hardware that were gathered in a similar fashion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4576 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4577 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4578 Two major items need to be present in any given set of measurements.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4579 First, the raw values for the various operations; these are typically
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4580 quite easy to measure and will be available for most systems. Second,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4581 the determinacy of the numbers; in other words how much the value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4582 might change depending on other factors within the system. This value
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4583 is affected by a number of factors: how long interrupts might be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4584 masked, whether or not the function can be interrupted, even very
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4585 hardware-specific effects such as cache locality and pipeline usage.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4586 It is very difficult to measure the determinacy of any given
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4587 operation, but that determinacy is fundamentally important to proper
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4588 overall characterization of a system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4589 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4590 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4591 In the discussion and numbers that follow, three key measurements are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4592 provided. The first measurement is an estimate of the interrupt
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4593 latency: this is the length of time from when a hardware interrupt
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4594 occurs until its Interrupt Service Routine (ISR) is called. The second
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4595 measurement is an estimate of overall interrupt overhead: this is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4596 length of time average interrupt processing takes, as measured by the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4597 real-time clock interrupt (other interrupt sources will certainly take
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4598 a different amount of time, but this data cannot be easily gathered).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4599 The third measurement consists of the timings for the various kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4600 primitives.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4601 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4602 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4603 <refsect1 id="kernel-characterization-methodology">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4604 <title>Methodology</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4605 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4606 Key operations in the kernel were measured by using a simple test
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4607 program which exercises the various kernel primitive operations. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4608 hardware timer, normally the one used to drive the real-time clock,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4609 was used for these measurements. In most cases this timer can be read
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4610 with quite high resolution, typically in the range of a few
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4611 microseconds. For each measurement, the operation was repeated a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4612 number of times. Time stamps were obtained directly before and after
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4613 the operation was performed. The data gathered for the entire set of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4614 operations was then analyzed, generating average (mean), maximum and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4615 minimum values. The sample variance (a measure of how close most
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4616 samples are to the mean) was also calculated. The cost of obtaining
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4617 the real-time clock timer values was also measured, and was subtracted
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4618 from all other times.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4619 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4620 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4621 Most kernel functions can be measured separately. In each case, a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4622 reasonable number of iterations are performed. Where the test case
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4623 involves a kernel object, for example creating a task, each iteration
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4624 is performed on a different object. There is also a set of tests which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4625 measures the interactions between multiple tasks and certain kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4626 primitives. Most functions are tested in such a way as to determine
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4627 the variations introduced by varying numbers of objects in the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4628 For example, the mailbox tests measure the cost of a 'peek' operation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4629 when the mailbox is empty, has a single item, and has multiple items
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4630 present. In this way, any effects of the state of the object or how
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4631 many items it contains can be determined.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4632 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4633 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4634 There are a few things to consider about these measurements. Firstly,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4635 they are quite micro in scale and only measure the operation in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4636 question. These measurements do not adequately describe how the
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4637 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
4638 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
4639 clock (system heartbeat tick) is explicitly avoided. Virtually all
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4640 kernel functions have been designed to be interruptible. Thus the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4641 times presented are typical, but best case, since any particular
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4642 function may be interrupted by the clock tick processing. This number
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4643 is explicitly calculated so that the value may be included in any
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4644 deadline calculations required by the end user. Lastly, the reported
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4645 measurements were obtained from a system built with all options at
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4646 their default values. Kernel instrumentation and asserts are also
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4647 disabled for these measurements. Any number of configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4648 can change the measured results, sometimes quite dramatically. For
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4649 example, mutexes are using priority inheritance in these measurements.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4650 The numbers will change if the system is built with priority
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4651 inheritance on mutex variables turned off.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4652 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4653 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4654 The final value that is measured is an estimate of interrupt latency.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4655 This particular value is not explicitly calculated in the test program
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4656 used, but rather by instrumenting the kernel itself. The raw number of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4657 timer ticks that elapse between the time the timer generates an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4658 interrupt and the start of the timer ISR is kept in the kernel. These
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4659 values are printed by the test program after all other operations have
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4660 been tested. Thus this should be a reasonable estimate of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4661 interrupt latency over time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4662 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4663 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4664
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4665 <refsect1 id="kernel-characterization-using-measurements">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4666 <title>Using these Measurements</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4667 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4668 These measurements can be used in a number of ways. The most typical
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4669 use will be to compare different real-time kernel offerings on similar
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4670 hardware, another will be to estimate the cost of implementing a task
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4671 using eCos (applications can be examined to see what effect the kernel
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4672 operations will have on the total execution time). Another use would
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4673 be to observe how the tuning of the kernel affects overall operation.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4674 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4675 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4676
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4677 <refsect1 id="kernel-characterization-influences">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4678 <title>Influences on Performance</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4679 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4680 A number of factors can affect real-time performance in a system. One
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4681 of the most common factors, yet most difficult to characterize, is the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4682 effect of device drivers and interrupts on system timings. Different
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4683 device drivers will have differing requirements as to how long
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4684 interrupts are suppressed, for example. The eCos system has been
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4685 designed with this in mind, by separating the management of interrupts
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4686 (ISR handlers) and the processing required by the interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4687 (DSR&mdash;Deferred Service Routine&mdash; handlers). However, since
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4688 there is so much variability here, and indeed most device drivers will
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4689 come from the end users themselves, these effects cannot be reliably
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4690 measured. Attempts have been made to measure the overhead of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4691 single interrupt that eCos relies on, the real-time clock timer. This
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4692 should give you a reasonable idea of the cost of executing interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4693 handling for devices.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4694 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4695 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4696
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4697 <refsect1 id="kernel-characterization-measured-items">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4698 <title>Measured Items</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4699 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4700 This section describes the various tests and the numbers presented.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4701 All tests use the C kernel API (available by way of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4702 <filename>cyg/kernel/kapi.h</filename>). There is a single main thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4703 in the system that performs the various tests. Additional threads may
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4704 be created as part of the testing, but these are short lived and are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4705 destroyed between tests unless otherwise noted. The terminology
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4706 &ldquo;lower priority&rdquo; means a priority that is less important,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4707 not necessarily lower in numerical value. A higher priority thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4708 will run in preference to a lower priority thread even though the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4709 priority value of the higher priority thread may be numerically less
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4710 than that of the lower priority thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4711 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4712
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4713 <refsect2 id="kernel-characterization-measure-threads">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4714 <title>Thread Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4715 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4716 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4717 <term>Create thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4718 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4719 This test measures the <function>cyg_thread_create()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4720 Each call creates a totally new thread. The set of threads created by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4721 this test will be reused in the subsequent thread primitive tests.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4722 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4723 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4724 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4725 <term>Yield thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4726 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4727 This test measures the <function>cyg_thread_yield()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4728 For this test, there are no other runnable threads, thus the test
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4729 should just measure the overhead of trying to give up the CPU.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4730 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4731 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4732 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4733 <term>Suspend &lsqb;suspended&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4734 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4735 This test measures the <function>cyg_thread_suspend()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4736 A thread may be suspended multiple times; each thread is already
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4737 suspended from its initial creation, and is suspended again.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4738 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4739 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4740 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4741 <term>Resume thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4742 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4743 This test measures the <function>cyg_thread_resume()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4744 All of the threads have a suspend count of 2, thus this call does not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4745 make them runnable. This test just measures the overhead of resuming a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4746 thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4747 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4748 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4749 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4750 <term>Set priority</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4751 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4752 This test measures the <function>cyg_thread_set_priority()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4753 call. Each thread, currently suspended, has its priority set to a new
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4754 value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4755 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4756 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4757 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4758 <term>Get priority</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4759 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4760 This test measures the <function>cyg_thread_get_priority()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4761 call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4762 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4763 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4764 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4765 <term>Kill &lsqb;suspended&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4766 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4767 This test measures the <function>cyg_thread_kill()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4768 Each thread in the set is killed. All threads are known to be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4769 suspended before being killed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4770 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4771 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4772 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4773 <term>Yield &lsqb;no other&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4774 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4775 This test measures the <function>cyg_thread_yield()</function> call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4776 again. This is to demonstrate that the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4777 <function>cyg_thread_yield()</function> call has a fixed overhead,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4778 regardless of whether there are other threads in the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4779 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4780 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4781 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4782 <term>Resume &lsqb;suspended low priority&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4783 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4784 This test measures the <function>cyg_thread_resume()</function> call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4785 again. In this case, the thread being resumed is lower priority than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4786 the main thread, thus it will simply become ready to run but not be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4787 granted the CPU. This test measures the cost of making a thread ready
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4788 to run.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4789 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4790 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4791 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4792 <term>Resume &lsqb;runnable low priority&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4793 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4794 This test measures the <function>cyg_thread_resume()</function> call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4795 again. In this case, the thread being resumed is lower priority than
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4796 the main thread and has already been made runnable, so in fact the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4797 resume call has no effect.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4798 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4799 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4800 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4801 <term>Suspend &lsqb;runnable&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4802 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4803 This test measures the <function>cyg_thread_suspend()</function> call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4804 again. In this case, each thread has already been made runnable (by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4805 previous tests).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4806 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4807 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4808 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4809 <term>Yield &lsqb;only low priority&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4810 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4811 This test measures the <function>cyg_thread_yield()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4812 In this case, there are many other runnable threads, but they are all
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4813 lower priority than the main thread, thus no thread switches will take
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4814 place.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4815 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4816 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4817 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4818 <term>Suspend &lsqb;runnable-&gt;not runnable&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4819 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4820 This test measures the <function>cyg_thread_suspend()</function> call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4821 again. The thread being suspended will become non-runnable by this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4822 action.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4823 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4824 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4825 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4826 <term>Kill &lsqb;runnable&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4827 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4828 This test measures the <function>cyg_thread_kill()</function> call
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4829 again. In this case, the thread being killed is currently runnable,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4830 but lower priority than the main thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4831 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4832 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4833 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4834 <term>Resume &lsqb;high priority&rsqb; thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4835 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4836 This test measures the <function>cyg_thread_resume()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4837 The thread being resumed is higher priority than the main thread, thus
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4838 a thread switch will take place on each call. In fact there will be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4839 two thread switches; one to the new higher priority thread and a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4840 second back to the test thread. The test thread exits immediately.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4841 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4842 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4843 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4844 <term>Thread switch</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4845 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4846 This test attempts to measure the cost of switching from one thread to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4847 another. Two equal priority threads are started and they will each
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4848 yield to the other for a number of iterations. A time stamp is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4849 gathered in one thread before the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4850 <function>cyg_thread_yield()</function> call and after the call in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4851 other thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4852 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4853 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4854 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4855 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4856
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4857 <refsect2 id="kernel-characterization-measure-scheduler"
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4858 <title>Scheduler Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4859 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4860 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4861 <term>Scheduler lock</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4862 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4863 This test measures the <function>cyg_scheduler_lock()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4864 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4865 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4866 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4867 <term>Scheduler unlock &lsqb;0 threads&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4868 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4869 This test measures the <function>cyg_scheduler_unlock()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4870 call. There are no other threads in the system and the unlock happens
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4871 immediately after a lock so there will be no pending DSR&rsquo;s to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4872 run.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4873 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4874 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4875 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4876 <term>Scheduler unlock &lsqb;1 suspended thread&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4877 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4878 This test measures the <function>cyg_scheduler_unlock()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4879 call. There is one other thread in the system which is currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4880 suspended.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4881 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4882 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4883 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4884 <term>Scheduler unlock &lsqb;many suspended threads&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4885 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4886 This test measures the <function>cyg_scheduler_unlock()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4887 call. There are many other threads in the system which are currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4888 suspended. The purpose of this test is to determine the cost of having
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4889 additional threads in the system when the scheduler is activated by
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4890 way of <function>cyg_scheduler_unlock()</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4891 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4892 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4893 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4894 <term>Scheduler unlock &lsqb;many low priority threads&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4895 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4896 This test measures the <function>cyg_scheduler_unlock()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4897 call. There are many other threads in the system which are runnable
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4898 but are lower priority than the main thread. The purpose of this test
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4899 is to determine the cost of having additional threads in the system
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4900 when the scheduler is activated by way of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4901 <function>cyg_scheduler_unlock()</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4902 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4903 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4904 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4905 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4906
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4907 <refsect2 id="kernel-characterization-measure-mutex">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4908 <title>Mutex Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4909 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4910 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4911 <term>Init mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4912 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4913 This test measures the <function>cyg_mutex_init()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4914 number of separate mutex variables are created. The purpose of this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4915 test is to measure the cost of creating a new mutex and introducing it
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4916 to the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4917 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4918 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4919 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4920 <term>Lock &lsqb;unlocked&rsqb; mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4921 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4922 This test measures the <function>cyg_mutex_lock()</function> call. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4923 purpose of this test is to measure the cost of locking a mutex which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4924 is currently unlocked. There are no other threads executing in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4925 system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4926 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4927 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4928 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4929 <term>Unlock &lsqb;locked&rsqb; mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4930 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4931 This test measures the <function>cyg_mutex_unlock()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4932 The purpose of this test is to measure the cost of unlocking a mutex
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4933 which is currently locked. There are no other threads executing in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4934 system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4935 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4936 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4937 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4938 <term>Trylock &lsqb;unlocked&rsqb; mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4939 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4940 This test measures the <function>cyg_mutex_trylock()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4941 The purpose of this test is to measure the cost of locking a mutex
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4942 which is currently unlocked. There are no other threads executing in
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4943 the system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4944 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4945 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4946 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4947 <term>Trylock &lsqb;locked&rsqb; mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4948 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4949 This test measures the <function>cyg_mutex_trylock()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4950 The purpose of this test is to measure the cost of locking a mutex
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4951 which is currently locked. There are no other threads executing in the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4952 system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4953 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4954 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4955 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4956 <term>Destroy mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4957 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4958 This test measures the <function>cyg_mutex_destroy()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
4959 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
4960 from the system. There are no other threads executing in the system
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4961 while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4962 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4963 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4964 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4965 <term>Unlock/Lock mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4966 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4967 This test attempts to measure the cost of unlocking a mutex for which
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4968 there is another higher priority thread waiting. When the mutex is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4969 unlocked, the higher priority waiting thread will immediately take the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4970 lock. The time from when the unlock is issued until after the lock
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4971 succeeds in the second thread is measured, thus giving the round-trip
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4972 or circuit time for this type of synchronizer.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4973 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4974 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4975 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4976 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4977
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4978 <refsect2 id="kernel-characterization-measure-mailbox">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4979 <title>Mailbox Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4980 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4981 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4982 <term>Create mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4983 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4984 This test measures the <function>cyg_mbox_create()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4985 number of separate mailboxes is created. The purpose of this test is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4986 to measure the cost of creating a new mailbox and introducing it to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4987 the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4988 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4989 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4990 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4991 <term>Peek &lsqb;empty&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4992 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4993 This test measures the <function>cyg_mbox_peek()</function> call. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4994 attempt is made to peek the value in each mailbox, which is currently
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4995 empty. The purpose of this test is to measure the cost of checking a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4996 mailbox for a value without blocking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4997 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4998 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4999 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5000 <term>Put &lsqb;first&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5001 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5002 This test measures the <function>cyg_mbox_put()</function> call. One
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5003 item is added to a currently empty mailbox. The purpose of this test
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5004 is to measure the cost of adding an item to a mailbox. There are no
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5005 other threads currently waiting for mailbox items to arrive.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5006 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5007 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5008 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5009 <term>Peek &lsqb;1 msg&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5010 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5011 This test measures the <function>cyg_mbox_peek()</function> call. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5012 attempt is made to peek the value in each mailbox, which contains a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5013 single item. The purpose of this test is to measure the cost of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5014 checking a mailbox which has data to deliver.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5015 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5016 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5017 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5018 <term>Put &lsqb;second&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5019 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5020 This test measures the <function>cyg_mbox_put()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5021 second item is added to a mailbox. The purpose of this test is to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5022 measure the cost of adding an additional item to a mailbox. There are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5023 no other threads currently waiting for mailbox items to arrive.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5024 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5025 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5026 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5027 <term>Peek &lsqb;2 msgs&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5028 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5029 This test measures the <function>cyg_mbox_peek()</function> call. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5030 attempt is made to peek the value in each mailbox, which contains two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5031 items. The purpose of this test is to measure the cost of checking a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5032 mailbox which has data to deliver.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5033 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5034 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5035 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5036 <term>Get &lsqb;first&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5037 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5038 This test measures the <function>cyg_mbox_get()</function> call. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5039 first item is removed from a mailbox that currently contains two
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5040 items. The purpose of this test is to measure the cost of obtaining an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5041 item from a mailbox without blocking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5042 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5043 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5044 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5045 <term>Get &lsqb;second&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5046 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5047 This test measures the <function>cyg_mbox_get()</function> call. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5048 last item is removed from a mailbox that currently contains one item.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5049 The purpose of this test is to measure the cost of obtaining an item
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5050 from a mailbox without blocking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5051 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5052 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5053 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5054 <term>Tryput &lsqb;first&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5055 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5056 This test measures the <function>cyg_mbox_tryput()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5057 single item is added to a currently empty mailbox. The purpose of this
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5058 test is to measure the cost of adding an item to a mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5059 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5060 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5061 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5062 <term>Peek item &lsqb;non-empty&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5063 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5064 This test measures the <function>cyg_mbox_peek_item()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5065 A single item is fetched from a mailbox that contains a single item.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5066 The purpose of this test is to measure the cost of obtaining an item
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5067 without disturbing the mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5068 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5069 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5070 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5071 <term>Tryget &lsqb;non-empty&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5072 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5073 This test measures the <function>cyg_mbox_tryget()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5074 single item is removed from a mailbox that contains exactly one item.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5075 The purpose of this test is to measure the cost of obtaining one item
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5076 from a non-empty mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5077 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5078 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5079 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5080 <term>Peek item &lsqb;empty&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5081 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5082 This test measures the <function>cyg_mbox_peek_item()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5083 An attempt is made to fetch an item from a mailbox that is empty. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5084 purpose of this test is to measure the cost of trying to obtain an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5085 item when the mailbox is empty.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5086 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5087 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5088 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5089 <term>Tryget &lsqb;empty&rsqb; mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5090 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5091 This test measures the <function>cyg_mbox_tryget()</function> call. An
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5092 attempt is made to fetch an item from a mailbox that is empty. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5093 purpose of this test is to measure the cost of trying to obtain an
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5094 item when the mailbox is empty.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5095 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5096 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5097 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5098 <term>Waiting to get mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5099 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5100 This test measures the <function>cyg_mbox_waiting_to_get()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5101 call. The purpose of this test is to measure the cost of determining
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5102 how many threads are waiting to obtain a message from this mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5103 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5104 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5105 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5106 <term>Waiting to put mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5107 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5108 This test measures the <function>cyg_mbox_waiting_to_put()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5109 call. The purpose of this test is to measure the cost of determining
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5110 how many threads are waiting to put a message into this mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5111 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5112 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5113 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5114 <term>Delete mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5115 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5116 This test measures the <function>cyg_mbox_delete()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5117 The purpose of this test is to measure the cost of destroying a
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5118 mailbox and removing it from the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5119 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5120 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5121 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5122 <term>Put/Get mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5123 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5124 In this round-trip test, one thread is sending data to a mailbox that
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5125 is being consumed by another thread. The time from when the data is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5126 put into the mailbox until it has been delivered to the waiting thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5127 is measured. Note that this time will contain a thread switch.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5128 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5129 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5130 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5131 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5132
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5133 <refsect2 id="kernel-characterization-measure-semaphore">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5134 <title>Semaphore Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5135 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5136 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5137 <term>Init semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5138 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5139 This test measures the <function>cyg_semaphore_init()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5140 A number of separate semaphore objects are created and introduced to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5141 the system. The purpose of this test is to measure the cost of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5142 creating a new semaphore.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5143 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5144 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5145 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5146 <term>Post &lsqb;0&rsqb; semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5147 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5148 This test measures the <function>cyg_semaphore_post()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5149 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
5150 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
5151 overhead cost of posting to a semaphore. This cost will differ if
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5152 there is a thread waiting for the semaphore.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5153 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5154 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5155 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5156 <term>Wait &lsqb;1&rsqb; semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5157 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5158 This test measures the <function>cyg_semaphore_wait()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5159 The semaphore has a current value of 1 so the call is non-blocking.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5160 The purpose of the test is to measure the overhead of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5161 &ldquo;taking&rdquo; a semaphore.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5162 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5163 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5164 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5165 <term>Trywait &lsqb;0&rsqb; semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5166 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5167 This test measures the <function>cyg_semaphore_trywait()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5168 call. The semaphore has a value of 0 when the call is made. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5169 purpose of this test is to measure the cost of seeing if a semaphore
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5170 can be &ldquo;taken&rdquo; without blocking. In this case, the answer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5171 would be no.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5172 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5173 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5174 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5175 <term>Trywait &lsqb;1&rsqb; semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5176 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5177 This test measures the <function>cyg_semaphore_trywait()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5178 call. The semaphore has a value of 1 when the call is made. The
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5179 purpose of this test is to measure the cost of seeing if a semaphore
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5180 can be &ldquo;taken&rdquo; without blocking. In this case, the answer
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5181 would be yes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5182 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5183 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5184 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5185 <term>Peek semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5186 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5187 This test measures the <function>cyg_semaphore_peek()</function> call.
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5188 The purpose of this test is to measure the cost of obtaining the
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5189 current semaphore count value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5190 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5191 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5192 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5193 <term>Destroy semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5194 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5195 This test measures the <function>cyg_semaphore_destroy()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5196 call. The purpose of this test is to measure the cost of deleting a
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5197 semaphore from the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5198 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5199 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5200 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5201 <term>Post/Wait semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5202 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5203 In this round-trip test, two threads are passing control back and
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5204 forth by using a semaphore. The time from when one thread calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5205 <function>cyg_semaphore_post()</function> until the other thread
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5206 completes its <function>cyg_semaphore_wait()</function> is measured.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5207 Note that each iteration of this test will involve a thread switch.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5208 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5209 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5210 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5211 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5212
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5213 <refsect2 id="kernel-characterization-measure-counters">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5214 <title>Counters</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5215 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5216 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5217 <term>Create counter</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5218 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5219 This test measures the <function>cyg_counter_create()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5220 A number of separate counters are created. The purpose of this test is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5221 to measure the cost of creating a new counter and introducing it to
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5222 the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5223 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5224 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5225 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5226 <term>Get counter value</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5227 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5228 This test measures the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5229 <function>cyg_counter_current_value()</function> call. The current
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5230 value of each counter is obtained.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5231 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5232 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5233 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5234 <term>Set counter value</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5235 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5236 This test measures the <function>cyg_counter_set_value()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5237 call. Each counter is set to a new value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5238 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5239 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5240 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5241 <term>Tick counter</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5242 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5243 This test measures the <function>cyg_counter_tick()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5244 Each counter is &ldquo;ticked&rdquo; once.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5245 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5246 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5247 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5248 <term>Delete counter</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5249 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5250 This test measures the <function>cyg_counter_delete()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5251 Each counter is deleted from the system. The purpose of this test is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5252 to measure the cost of deleting a counter object.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5253 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5254 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5255 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5256 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5257
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5258 <refsect2 id="kernel-characterization-measure-alarms">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5259 <title>Alarms</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5260 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5261 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5262 <term>Create alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5263 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5264 This test measures the <function>cyg_alarm_create()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5265 number of separate alarms are created, all attached to the same
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5266 counter object. The purpose of this test is to measure the cost of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5267 creating a new counter and introducing it to the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5268 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5269 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5270 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5271 <term>Initialize alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5272 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5273 This test measures the <function>cyg_alarm_initialize()</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5274 call. Each alarm is initialized to a small value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5275 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5276 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5277 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5278 <term>Disable alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5279 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5280 This test measures the <function>cyg_alarm_disable()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5281 Each alarm is explicitly disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5282 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5283 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5284 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5285 <term>Enable alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5286 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5287 This test measures the <function>cyg_alarm_enable()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5288 Each alarm is explicitly enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5289 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5290 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5291 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5292 <term>Delete alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5293 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5294 This test measures the <function>cyg_alarm_delete()</function> call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5295 Each alarm is destroyed. The purpose of this test is to measure the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5296 cost of deleting an alarm and removing it from the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5297 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5298 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5299 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5300 <term>Tick counter &lsqb;1 alarm&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5301 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5302 This test measures the <function>cyg_counter_tick()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5303 counter is created that has a single alarm attached to it. The purpose
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5304 of this test is to measure the cost of &ldquo;ticking&rdquo; a counter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5305 when it has a single attached alarm. In this test, the alarm is not
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5306 activated (fired).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5307 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5308 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5309 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5310 <term>Tick counter &lsqb;many alarms&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5311 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5312 This test measures the <function>cyg_counter_tick()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5313 counter is created that has multiple alarms attached to it. The
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5314 purpose of this test is to measure the cost of &ldquo;ticking&rdquo; a
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5315 counter when it has many attached alarms. In this test, the alarms are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5316 not activated (fired).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5317 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5318 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5319 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5320 <term>Tick &amp; fire counter &lsqb;1 alarm&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5321 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5322 This test measures the <function>cyg_counter_tick()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5323 counter is created that has a single alarm attached to it. The purpose
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5324 of this test is to measure the cost of &ldquo;ticking&rdquo; a counter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5325 when it has a single attached alarm. In this test, the alarm is
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5326 activated (fired). Thus the measured time will include the overhead of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5327 calling the alarm callback function.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5328 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5329 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5330 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5331 <term>Tick &amp; fire counter &lsqb;many alarms&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5332 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5333 This test measures the <function>cyg_counter_tick()</function> call. A
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5334 counter is created that has multiple alarms attached to it. The
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5335 purpose of this test is to measure the cost of &ldquo;ticking&rdquo; a
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5336 counter when it has many attached alarms. In this test, the alarms are
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5337 activated (fired). Thus the measured time will include the overhead of
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5338 calling the alarm callback function.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5339 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5340 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5341 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5342 <term>Alarm latency &lsqb;0 threads&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5343 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5344 This test attempts to measure the latency in calling an alarm callback
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5345 function. The time from the clock interrupt until the alarm function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5346 is called is measured. In this test, there are no threads that can be
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5347 run, other than the system idle thread, when the clock interrupt
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5348 occurs (all threads are suspended).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5349 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5350 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5351 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5352 <term>Alarm latency &lsqb;2 threads&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5353 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5354 This test attempts to measure the latency in calling an alarm callback
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5355 function. The time from the clock interrupt until the alarm function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5356 is called is measured. In this test, there are exactly two threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5357 which are running when the clock interrupt occurs. They are simply
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5358 passing back and forth by way of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5359 <function>cyg_thread_yield()</function> call. The purpose of this test
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5360 is to measure the variations in the latency when there are executing
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5361 threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5362 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5363 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5364 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5365 <term>Alarm latency &lsqb;many threads&rsqb;</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5366 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5367 This test attempts to measure the latency in calling an alarm callback
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5368 function. The time from the clock interrupt until the alarm function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5369 is called is measured. In this test, there are a number of threads
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5370 which are running when the clock interrupt occurs. They are simply
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5371 passing back and forth by way of the
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5372 <function>cyg_thread_yield()</function> call. The purpose of this test
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5373 is to measure the variations in the latency when there are many
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5374 executing threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5375 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5376 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5377 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5378 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5379
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5380 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5381
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5382 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5383
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5384 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5385
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5386 </part>