Mercurial > ecos

annotate packages/kernel/current/doc/kernel.sgml @ 3243:fa4455042d3c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add requirement for WRITETHRU data cache startup mode when eDMA is in use. Sync with change in eDMA driver [ Bugzilla 1001838 ]
author vae
date Sun, 02 Jun 2013 16:39:24 +0000
parents f89e0743ba67
children
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 <!-- =============================================================== -->
2729
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
10 <!-- ####ECOSDOCCOPYRIGHTBEGIN#### -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
11 <!-- =============================================================== -->
2940
f89e0743ba67 * packages/kernel/current/doc/kernel.sgml: Indicate that cyg_alarm_initialize()
jld
parents: 2911
diff changeset
12 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2009, 2010 Free Software Foundation, Inc. -->
2729
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
13 <!-- This material may be distributed only subject to the terms -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
14 <!-- and conditions set forth in the Open Publication License, v1.0 -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
15 <!-- or later (the latest version is presently available at -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
16 <!-- http://www.opencontent.org/openpub/) -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
17 <!-- Distribution of the work or derivative of the work in any -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
18 <!-- standard (paper) book form is prohibited unless prior -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
19 <!-- permission obtained from the copyright holder -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
20 <!-- =============================================================== -->
74dbf4c3f2e1 Update all copyright banners to reflect FSF ownership; fix and improve licence text.
jlarmour
parents: 2273
diff changeset
21 <!-- ####ECOSDOCCOPYRIGHTEND#### -->
210
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 <!-- #####DESCRIPTIONBEGIN#### -->
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 <!-- Author(s): nickg, bartv, markg -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
26 <!-- Contributors: eCos team -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
27 <!-- Date: 2002/02/13 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
28 <!-- Version: 0.02 -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
29 <!-- -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
30 <!-- ####DESCRIPTIONEND#### -->
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
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 <part id="kernel">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
36 <title>The eCos Kernel</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
37
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
38 <!-- {{{ Overview -->
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 <refentry id="kernel-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 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
43 <refentrytitle>Kernel Overview</refentrytitle>
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
46 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
47 <refname>Kernel</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
48 <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
49 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
50
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
51 <!-- {{{ Description -->
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 <refsect1 id="kernel-overview-description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
54 <title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
55 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
56 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
57 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
58 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
59 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
60 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
61 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
62 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
63 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
64 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
65 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
66 manipulating their priorities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
67 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
68 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
69 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
70 running.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
71 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
72 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
73 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
74 and share data safely.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
75 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
76 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
77 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
78 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
79 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
80 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
81 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
82 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
83 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
84 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
85 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
86 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
87 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
88 application.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
89 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
90 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
91 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
92 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
93 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
94 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
95 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
96 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
97 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
98 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
99 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
100 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
101 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
102 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
103 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
104 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
105 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
106 optional one.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
107 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
108 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
109 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
110 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
111 <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
112 <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
113 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
114 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
115 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
116 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
117 <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
118 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
119 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
120 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
121 code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
122 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
123 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
124 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
125 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
126 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
127 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
128 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
129 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
130 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
131 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
132 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
133 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
134 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
135 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
136 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
137 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
138 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
139 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
140 a possibility of priority inversion.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
141 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
142 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
143 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
144 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
145 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
146 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
147 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
148 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
149 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
150 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
151 <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
152 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
153 equivalent kernel functions such as
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
154 <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
155 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
156 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
157 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
158 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
159 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
160
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
161 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
162 <!-- {{{ Schedulers -->
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 <refsect1 id="kernel-overview-schedulers">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
165 <title>Schedulers</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
166 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
167 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
168 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
169 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
170 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
171 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
172 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
173 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
174 packages.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
175 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
176 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
177 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
178 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
179 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
180 <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
181 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
182 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
183 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
184 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
185 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
186 currently blocked.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
187 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
188 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
189 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
190 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
191 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
192 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
193 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
194 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
195 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
196 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
197 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
198 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
199 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
200 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
201 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
202 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
203 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
204 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
205 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
206 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
207 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
208 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
209 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
210 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
211 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
212 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
213 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
214 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
215 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
216 primitive. The configuration options
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
217 <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
218 <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
219 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
220 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
221 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
222 the same priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
223 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
224 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
225 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
226 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
227 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
228 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
229 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
230 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
231 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
232 <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
233 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
234 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
235 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
236 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
237 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
238 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
239 queueing then the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
240 <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
241 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
242 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
243 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
244 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
245 involve any penalties.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
246 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
247 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
248 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
249 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
250 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
251 priority ceilings or priority inheritance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
252 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
253 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
254
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
255 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
256 <!-- {{{ Synch primitives -->
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 <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
259 <title>Synchronization Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
260 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
261 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
262 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
263 <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
264 <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
265 <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
266 <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
267 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
268 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
269 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
270 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
271 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
272 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
273 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
274 interrupt handler to a thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
275 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
276 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
277 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
278 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
279 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
280 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
281 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
282 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
283 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
284 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
285 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
286 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
287 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
288 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
289 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
290 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
291 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
292 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
293 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
294 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
295 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
296 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
297 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
298 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
299 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
300 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
301 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
302 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
303 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
304 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
305 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
306 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
307 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
308 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
309 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
310 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
311 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
312 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
313 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
314 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
315 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
316 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
317 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
318 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
319 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
320 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
321 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
322 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
323 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
324 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
325 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
326 simpler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
327 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
328 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
329
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
330 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
331 <!-- {{{ Threads and interrupts -->
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 <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
334 <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
335 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
336 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
337 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
338 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
339 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
340 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
341 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
342 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
343 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
344 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
345 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
346 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
347 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
348 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
349 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
350 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
351 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
352 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
353 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
354 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
355 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
356 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
357 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
358 but not all.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
359 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
360 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
361 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
362 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
363 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
364 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
365 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
366 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
367 (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
368 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
369 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
370 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
371 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
372 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
373 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
374 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
375 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
376 will be corrupted.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
377 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
378 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
379 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
380 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
381 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
382 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
383 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
384 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
385 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
386 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
387 such applications.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
388 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
389 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
390 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
391 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
392 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
393 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
394 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
395 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
396 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
397 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
398 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
399 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
400 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
401 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
402 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
403 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
404 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
405 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
406 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
407 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
408 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
409 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
410 pending until interrupts are reenabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
411 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
412 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
413 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
414 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
415 <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
416 <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
417 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
418 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
419 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
420 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
421 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
422 threads to be woken up.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
423 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
424 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
425 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
426 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
427 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
428 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
429 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
430 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
431 control access.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
432 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
433 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
434 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
435 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
436 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
437 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
438 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
439 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
440 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
441 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
442 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
443 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
444 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
445 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
446 <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
447 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
448 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
449 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
450 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
451 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
452 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
453 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
454 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
455 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
456 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
457 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
458 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
459 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
460 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
461 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
462 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
463 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
464 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
465 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
466 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
467 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
468 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
469 <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
470 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
471 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
472 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
473 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
474 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
475 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
476 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
477 thus wake up thread A.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
478 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
479 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
480 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
481 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
482 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
483 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
484 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
485 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
486 need to disable interrupts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
487 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
488 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
489
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
490 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
491 <!-- {{{ Calling contexts -->
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 <refsect1 id="kernel-overview-contexts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
494 <title>Calling Contexts</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
495 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
496 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
497 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
498 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
499 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
500 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
501 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
502 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
503 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
504 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
505 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
506 call to <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
507 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
508 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
509 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
510 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
511 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
512 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
513 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
514 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
515 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
516 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
517 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
518 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
519 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
520 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
521 entirely in C.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
522 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
523 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
524 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
525 cyg_user_start(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
526 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
527 /* Perform application-specific initialization here */
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
530 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
531 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
532 <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
533 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
534 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
535 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
536 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
537 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
538 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
539 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
540 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
541 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
542 other overheads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
543 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
544 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
545 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
546 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
547 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
548 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
549 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
550 <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
551 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
552 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
553 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
554 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
555 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
556 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
557 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
558 <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
559 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
560 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
561 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
562 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
563 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
564 <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
565 by a thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
566 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
567 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
568 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
569 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
570 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
571 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
572 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
573 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
574 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
575 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
576 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
577 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
578 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
579 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
580 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
581 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
582 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
583 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
584 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
585 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
586 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
587 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
588 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
589 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
590 <function>cyg_semaphore_post</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
591 <filename>cyg_cond_signal</filename>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
592 <function>cyg_cond_broadcast</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
593 <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
594 <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
595 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
596 <function>cyg_semaphore_wait</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
597 <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
598 <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
599 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
600 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
601 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
602 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
603 details about valid contexts.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
604 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
605 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
606
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
607 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
608 <!-- {{{ Error handling -->
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 <refsect1 id="kernel-overview-errors">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
611 <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
612 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
613 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
614 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
615 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
616 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
617 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
618 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
619 <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
620 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
621 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
622 context of deeply embedded systems:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
623 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
624 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
625 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
626 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
627 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
628 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
629 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
630 conditions, these overheads still exist.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
631 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
632 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
633 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
634 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
635 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
636 <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
637 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
638 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
639 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
640 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
641 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
642 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
643 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
644 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
645 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
646 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
647 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
648 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
649 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
650 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
651 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
652 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
653 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
654 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
655 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
656 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
657 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
658 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
659 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
660 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
661 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
662 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
663 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
664 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
665 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
666 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
667 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
668 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
669 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
670 <orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
671 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
672 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
673 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
674 eliminated at compile-time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
675 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
676 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
677 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
678 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
679 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
680 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
681 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
682 just return an error code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
683 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
684 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
685 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
686 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
687 application code.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
688 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
689 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
690 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
691 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
692 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
693 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
694 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
695 </orderedlist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
696 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
697 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
698 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
699 <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
700 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
701 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
702 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
703 <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
704 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
705 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
706 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
707 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
708 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
709 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
710 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
711 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
712 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
713 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
714 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
715 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
716 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
717 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
718 <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
719 <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
720 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
721 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
722 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
723 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
724 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
725 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
726 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
727 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
728 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
729 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
730 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
731 <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
732 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
733 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
734 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
735 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
736 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
737 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
738 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
739 system failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
740 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
741 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
742
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
743 <!-- }}} -->
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 </refentry>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
748 <!-- {{{ SMP -->
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 <refentry id="kernel-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 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
753 <refentrytitle>SMP Support</refentrytitle>
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
756 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
757 <refname>SMP</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
758 <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
759 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
760
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
761 <refsect1 id="kernel-smp-description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
762 <title>Description</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
763 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
764 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
765 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
766 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
767 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
768 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
769
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 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
772 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
773 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
774 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
775
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
776 <refsect1 id="kernel-smp-startup">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
777 <title>System Startup</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
778 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
779 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
780 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
781 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
782 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
783 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
784 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
785 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
786 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
787 <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
788 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
789 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
790 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
791 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
792 <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
793 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
794 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
795 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
796 <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
797 for the primary CPU.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
798 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
799 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
800 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
801 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
802 <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
803 scheduler lock and calls
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
804 <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
805 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
806 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
807 <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
808 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
809 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
810 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
811 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
812 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
813 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
814 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
815 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
816 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
817 delivery is concerned.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
818 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
819 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
820
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
821 <refsect1 id="kernel-smp-scheduling">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
822 <title>Scheduling</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
823 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
824 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
825 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
826 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
827 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
828 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
829 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
830 other CPUs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
831 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
832 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
833 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
834 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
835 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
836 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
837 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
838 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
839 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
840 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
841 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
842 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
843 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
844 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
845 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
846 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
847 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
848 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
849 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
850 original counter.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
851 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
852 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
853 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
854 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
855 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
856 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
857 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
858 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
859 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
860 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
861 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
862 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
863 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
864 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
865 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
866 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
867 latency.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
868 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
869 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
870 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
871 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
872 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
873 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
874 flag and the timeslice counter.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
875 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
876 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
877 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
878 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
879 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
880 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
881 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
882 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
883 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
884 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
885 system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
886 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
887 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
888 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
889 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
890 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
891 <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
892 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
893 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
894 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
895 (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
896 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
897 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
898 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
899 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
900 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
901 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
902 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
903 interrupt.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
904 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
905 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
906 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
907 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
908 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
909 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
910 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
911 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
912 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
913 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
914 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
915 needed when a timeslice occurs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
916 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
917 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
918 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
919 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
920 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
921 <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
922 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
923 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
924
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
925 <refsect1 id="kernel-smp-interrupts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
926 <title>SMP Interrupt Handling</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
927 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
928 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
929 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
930 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
931 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
932 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
933 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
934 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
935 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
936 kernel package.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
937 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
938 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
939 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
940 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
941 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
942 <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
943 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
944 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
945 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
946 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
947 CPU, where relevant.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
948 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
949
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 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
952 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
953 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
954 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
955
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
956 </refentry>
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 <!-- }}} -->
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 <!-- {{{ cyg_thread_create() -->
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 <refentry id="kernel-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 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
965 <refentrytitle>Thread creation</refentrytitle>
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
968 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
969 <refname>cyg_thread_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
970 <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
971 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
972
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
973 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
974 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
975 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
976 #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
977 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
978 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
979 <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
980 <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
981 <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
982 <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
983 <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
984 <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
985 <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
986 <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
987 <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
988 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
989 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
990 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
991
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
992 <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
993 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
994 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
995 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
996 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
997 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
998 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
999 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
1000 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
1001 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
1002 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
1003 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1004 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1005 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
1006 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
1007 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
1008 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
1009 <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
1010 this name is actually used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1011 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1012 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1013 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
1014 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
1015 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
1016 this thread including the required
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1017 <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
1018 identify the thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1019 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1020 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1021 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
1022 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
1023 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
1024 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
1025 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
1026 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
1027 provides this space.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1028 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1029 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1030
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1031 <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
1032 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1033 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
1034 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1035 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1036 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1037 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
1038 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1039 &hellip;
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 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1042 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1043 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
1044 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
1045 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
1046 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
1047 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
1048 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
1049 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1050 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1051 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
1052 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
1053 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
1054 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
1055 <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
1056 <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
1057 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1058 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1059
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1060 <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
1061 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1062 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
1063 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
1064 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
1065 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
1066 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
1067 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
1068 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
1069 <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
1070 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1071 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1072 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
1073 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
1074 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
1075 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
1076 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
1077 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1078 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1079 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
1080 <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
1081 <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
1082 manipulate a thread's priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1083 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1084 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1085
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1086 <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
1087 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1088 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
1089 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
1090 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
1091 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
1092 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
1093 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
1094 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
1095 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
1096 determine the starting location.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1097 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1098 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1099 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
1100 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
1101 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
1102 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
1103 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
1104 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
1105 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
1106 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
1107 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
1108 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
1109 <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
1110 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
1111 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1112 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1113 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
1114 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
1115 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
1116 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
1117 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
1118 <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
1119 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
1120 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
1121 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
1122 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
1123 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
1124 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
1125 the stack.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1126 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1127 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1128 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
1129 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
1130 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
1131 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
1132 <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
1133 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
1134 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
1135 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
1136 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
1137 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
1138 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
1139 <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
1140 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
1141 <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
1142 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
1143 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
1144 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
1145 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1146 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1147
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1148 <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
1149 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1150 <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
1151 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
1152 from inside a DSR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1153 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1154 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1155
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1156 <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
1157 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1158 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
1159 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
1160 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
1161 <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
1162 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
1163 <function>main</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1164 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1165 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1166 #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
1167 #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
1168
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1169 // 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
1170 #define NUMBER_OF_WORKERS 4
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1171 #define PRODUCER_PRIORITY 10
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1172 #define WORKER_PRIORITY 11
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1173 #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
1174 #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
1175
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1176 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
1177 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
1178 static cyg_handle_t producer_handle, worker_handles[NUMBER_OF_WORKERS];
1187
62fcf59de75c Minor documentation fix
bartv
parents: 1091
diff changeset
1179 static cyg_thread producer_thread, worker_threads[NUMBER_OF_WORKERS];
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1180
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1181 static void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1182 producer(cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1183 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1184 &hellip;
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1187 static void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1188 worker(cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1189 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1190 &hellip;
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1193 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1194 cyg_user_start(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1195 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1196 int i;
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 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
1199 producer_stack, PRODUCER_STACKSIZE,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1200 &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
1201 cyg_thread_resume(producer_handle);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1202 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
1203 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
1204 worker_stacks[i], WORKER_STACKSIZE,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1205 &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
1206 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
1207 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1208 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1209 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1210 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1211
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1212
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1213 <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
1214 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1215 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
1216 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
1217 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
1218 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
1219 <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
1220 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
1221 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
1222 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1223 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1224 class fred {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1225 public:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1226 void thread_function();
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1227 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
1228 };
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1229
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1230 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1231 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
1232 {
2911
7a3b9a2f019b * doc/kernel.sgml: Use "reinterpret_cast" throughout the C++ thread
jld
parents: 2729
diff changeset
1233 fred* object = reinterpret_cast&lt;fred*&gt;(objptr);
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1234 object-&gt;thread_function();
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1235 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1236
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1237 static fred instance;
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 extern "C" void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1240 cyg_start( void )
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1241 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1242 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1243 cyg_thread_create( &hellip;,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1244 &amp;fred::static_thread_aux,
2273
4a81fad4d2b4 * doc/kernel.sgml: Use reinterpret_cast, not static cast
jlarmour
parents: 2181
diff changeset
1245 reinterpret_cast&lt;cyg_addrword_t&gt;(&amp;instance),
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1246 &hellip;);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1247 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1248 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1249 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1250 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1251 Effectively this uses the <parameter
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1252 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
1253 <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
1254 <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
1255 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
1256 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
1257 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1258 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1259
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1260 </refentry>
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 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1263 <!-- {{{ Thread info -->
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 <refentry id="kernel-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 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1268 <refentrytitle>Thread information</refentrytitle>
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1271 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1272 <refname>cyg_thread_self</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1273 <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
1274 <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
1275 <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
1276 <refname>cyg_thread_measure_stack_usage</refname>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1277 <refname>cyg_thread_get_next</refname>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1278 <refname>cyg_thread_get_info</refname>
1436
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1279 <refname>cyg_thread_get_id</refname>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1280 <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
1281 <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
1282 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1283
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1284 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1285 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1286 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1287 #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
1288 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1289 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1290 <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
1291 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1292 </funcprototype>
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 <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
1295 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1296 </funcprototype>
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 <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
1299 <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
1300 </funcprototype>
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 <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
1303 <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
1304 </funcprototype>
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 <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
1307 <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
1308 </funcprototype>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1309 <funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1310 <funcdef>cyg_bool <function>cyg_thread_get_next</function></funcdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1311 <paramdef>cyg_handle_t *<parameter>thread</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1312 <paramdef>cyg_uint16 *<parameter>id</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1313 </funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1314 <funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1315 <funcdef>cyg_bool <function>cyg_thread_get_info</function></funcdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1316 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1317 <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1318 <paramdef>cyg_thread_info *<parameter>info</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1319 </funcprototype>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1320 <funcprototype>
1436
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1321 <funcdef>cyg_uint16 <function>cyg_thread_get_id</function></funcdef>
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1322 <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1323 </funcprototype>
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1324 <funcprototype>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1325 <funcdef>cyg_handle_t <function>cyg_thread_find</function></funcdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1326 <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1327 </funcprototype>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1328 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1329 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1330
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1331 <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
1332 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1333 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
1334 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
1335 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
1336 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1337 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1338 <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
1339 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
1340 <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
1341 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
1342 <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
1343 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1344 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1345 <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
1346 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
1347 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
1348 this information.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1349 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1350 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1351 <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
1352 <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
1353 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
1354 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
1355 thread was created.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1356 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1357 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1358 <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
1359 if the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1360 <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
1361 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
1362 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
1363 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
1364 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
1365 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
1366 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
1367 </para>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1368 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1369 <function>cyg_thread_get_next</function> is used to enumerate all the
526
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1370 current threads in the system. It should be called initially with the
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1371 locations pointed to by <parameter>thread</parameter> and
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1372 <parameter>id</parameter> set to zero. On return these will be set to
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1373 the handle and ID of the first thread. On subsequent calls, these
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1374 parameters should be left set to the values returned by the previous
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1375 call. The handle and ID of the next thread in the system will be
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1376 installed each time, until a <literal>false</literal> return value
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1377 indicates the end of the list.
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1378 </para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1379 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1380 <function>cyg_thread_get_info</function> fills in the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1381 <type>cyg_thread_info</type> structure with information about the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1382 thread described by the <parameter>thread</parameter> and
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1383 <parameter>id</parameter> arguments. The information returned includes
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1384 the thread's handle and id, its state and name, priorities and stack
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1385 parameters. If the thread does not exist the function returns
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1386 <literal>false</literal>.
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1387 </para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1388 <para>
526
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1389 The <type>cyg_thread_info</type> structure is defined as follows by
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1390 &lt;<filename class=headerfile>cyg/kernel/kapi.h</filename>&gt;, but may
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1391 be extended in future with additional members, and so its size should
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1392 not be relied upon:
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1393 <programlisting>
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1394 typedef struct
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1395 {
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1396 <type>cyg_handle_t</type> <structfield>handle</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1397 <type>cyg_uint16</type> <structfield>id</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1398 <type>cyg_uint32</type> <structfield>state</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1399 <type>char</type> <structfield>*name</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1400 <type>cyg_priority_t</type> <structfield>set_pri</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1401 <type>cyg_priority_t</type> <structfield>cur_pri</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1402 <type>cyg_addrword_t</type> <structfield>stack_base</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1403 <type>cyg_uint32</type> <structfield>stack_size</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1404 <type>cyg_uint32</type> <structfield>stack_used</structfield>;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1405 } cyg_thread_info;
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1406 </programlisting>
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1407 </para>
1061ceceb720 * doc/kernel.sgml: Document cyg_thread_info type.
jlarmour
parents: 460
diff changeset
1408 <para>
1436
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1409 <function>cyg_thread_get_id</function> returns the unique thread ID for
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1410 the thread identified by <parameter>thread</parameter>.
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1411 </para>
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1412 <para>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1413 <function>cyg_thread_find</function> returns a handle for the thread
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1414 whose ID is <parameter>id</parameter>. If no such thread exists, a
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1415 zero handle is returned.
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1416 </para>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1417 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1418
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1419 <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
1420 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1421 <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
1422 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
1423 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
1424 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
1425 <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
1426 <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
1427 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
1428 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
1429 so this should normally only be done from thread context.
1436
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1430 <function>cyg_thread_get_id</function> may be called from any context
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1431 as long as the caller can guarantee that the supplied thread handle
1b465c781382 New API for cyg_thread_get_id() - from Dan Jakubiec
gthomas
parents: 1187
diff changeset
1432 remains valid.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1433 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1434 </refsect1>
460
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1435
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1436 <refsect1 id="kernel-thread-info-examples"><title>Examples</title>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1437 <para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1438 A simple example of the use of the
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1439 <function>cyg_thread_get_next</function> and
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1440 <function>cyg_thread_get_info</function> follows:
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1441 </para>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1442 <programlisting width=72>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1443
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1444 #include &lt;cyg/kernel/kapi.h&gt;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1445 #include &lt;stdio.h&gt;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1446
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1447 void show_threads(void)
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1448 {
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1449 cyg_handle_t thread = 0;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1450 cyg_uint16 id = 0;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1451
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1452 while( cyg_thread_get_next( &amp;thread, &amp;id ) )
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1453 {
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1454 cyg_thread_info info;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1455
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1456 if( !cyg_thread_get_info( thread, id, &amp;info ) )
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1457 break;
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1458
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1459 printf("ID: %04x name: %10s pri: %d\n",
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1460 info.id, info.name?info.name:"----", info.set_pri );
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1461 }
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1462 }
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1463
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1464 </programlisting>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1465 </refsect1>
a65a4055f146 * src/common/kapi.cxx:
nickg
parents: 356
diff changeset
1466
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1467 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1468
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1469 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1470 <!-- {{{ Thread control -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1471
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1472 <refentry id="kernel-thread-control">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1473
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1474 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1475 <refentrytitle>Thread control</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1476 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1477
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1478 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1479 <refname>cyg_thread_yield</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1480 <refname>cyg_thread_delay</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1481 <refname>cyg_thread_suspend</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1482 <refname>cyg_thread_resume</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1483 <refname>cyg_thread_release</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1484 <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
1485 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1486
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1487 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1488 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1489 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1490 #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
1491 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1492 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1493 <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
1494 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1495 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1496 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1497 <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
1498 <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
1499 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1500 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1501 <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
1502 <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
1503 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1504 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1505 <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
1506 <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
1507 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1508 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1509 <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
1510 <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
1511 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1512 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1513 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1514
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1515 <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
1516 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1517 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
1518 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
1519 <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
1520 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
1521 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
1522 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1523 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1524
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1525 <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
1526 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1527 <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
1528 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
1529 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
1530 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
1531 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
1532 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
1533 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
1534 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
1535 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
1536 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
1537 <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
1538 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1539 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1540 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
1541 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
1542 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
1543 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
1544 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
1545 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
1546 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
1547 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
1548 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1549 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1550
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1551 <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
1552 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1553 <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
1554 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
1555 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
1556 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
1557 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
1558 controlled by the configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1559 <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
1560 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1561 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1562 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
1563 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
1564 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
1565 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
1566 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
1567 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
1568 <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
1569 system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1570 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1571 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1572
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1573 <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
1574 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1575 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
1576 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
1577 <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
1578 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
1579 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
1580 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
1581 been resumed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1582 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1583 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1584 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
1585 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
1586 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
1587 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
1588 configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1589 <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
1590 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
1591 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
1592 on infrastructure assertions being enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1593 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1594 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1595
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1596 <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
1597 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1598 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
1599 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
1600 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
1601 <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
1602 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
1603 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
1604 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
1605 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
1606 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
1607 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
1608 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
1609 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
1610 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
1611 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
1612 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
1613 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
1614 actually own.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1615 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1616 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1617 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
1618 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
1619 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
1620 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1621 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1622
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1623 <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
1624 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1625 <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
1626 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
1627 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
1628 <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
1629 <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
1630 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1631 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1632 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1633
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1634 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1635
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1636 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1637 <!-- {{{ Thread termination -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1638
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1639 <refentry id="kernel-thread-termination">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1640
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1641 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1642 <refentrytitle>Thread termination</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1643 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1644
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1645 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1646 <refname>cyg_thread_exit</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1647 <refname>cyg_thread_kill</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1648 <refname>cyg_thread_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1649 <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
1650 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1651
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1652 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1653 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1654 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1655 #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
1656 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1657 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1658 <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
1659 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1660 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1661 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1662 <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
1663 <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
1664 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1665 <funcprototype>
1529
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1666 <funcdef>cyg_bool_t <function>cyg_thread_delete</function></funcdef>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1667 <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
1668 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1669 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1670 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1671
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1672 <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
1673 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1674 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
1675 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
1676 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
1677 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
1678 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
1679 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
1680 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
1681 <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
1682 <function>cyg_thread_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1683 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1684 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1685 <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
1686 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
1687 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
1688 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
1689 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
1690 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
1691 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
1692 <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
1693 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
1694 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
1695 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
1696 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
1697 <function>cyg_thread_delete</function>.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1700 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
1701 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
1702 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
1703 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
1704 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
1705 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
1706 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
1707 <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
1708 <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
1709 kill itself.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1710 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1711 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1712 <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
1713 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
1714 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
1715 <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
1716 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
1717 invoked on a thread that is still running then there is an implicit
1529
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1718 call to <function>cyg_thread_kill</function>. This function returns
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1719 <literal>true</literal> if the delete was successful, and
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1720 <literal>false</literal> if the delete did not happen. The delete
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1721 may not happen for example if the thread being destroyed is a lower
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1722 priority thread than the running thread, and will thus not wake up
382e69fac9e0 * doc/kernel.sgml: Document cyg_thread_delete return value.
jlarmour
parents: 1436
diff changeset
1723 in order to exit until it is rescheduled.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1724 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1725 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1726
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1727 <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
1728 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1729 <function>cyg_thread_exit</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1730 <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
1731 <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
1732 context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1733 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1734 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1735
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1736 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1737
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 <!-- {{{ Thread priorities -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1740
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1741 <refentry id="kernel-thread-priorities">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1742
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1743 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1744 <refentrytitle>Thread priorities</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1745 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1746
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1747 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1748 <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
1749 <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
1750 <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
1751 <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
1752 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1753 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1754 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1755 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1756 #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
1757 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1758 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1759 <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
1760 <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
1761 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1762 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1763 <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
1764 <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
1765 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1766 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1767 <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
1768 <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
1769 <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
1770 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1771 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1772 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1773
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1774 <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
1775 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1776 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
1777 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
1778 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
1779 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
1780 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
1781 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
1782 configuration, typically the option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1783 <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
1784 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1785 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1786 <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
1787 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
1788 <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
1789 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
1790 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
1791 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
1792 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
1793 have been boosted temporarily.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1794 <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
1795 current priority.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1796 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1797 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1798 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
1799 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
1800 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
1801 <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
1802 functionality.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1803 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1804 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1805
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1806 <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
1807 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1808 <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
1809 <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
1810 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
1811 <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
1812 called from thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1813 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1814 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1815 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1816
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1817 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1818 <!-- {{{ Per-thread data -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1819
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1820 <refentry id="kernel-thread-data">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1821
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1822 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1823 <refentrytitle>Per-thread data</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1824 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1825
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1826 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1827 <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
1828 <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
1829 <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
1830 <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
1831 <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
1832 <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
1833 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1834 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1835 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1836 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1837 #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
1838 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1839 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1840 <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
1841 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1842 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1843 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1844 <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
1845 <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
1846 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1847 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1848 <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
1849 <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
1850 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1851 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1852 <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
1853 <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
1854 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1855 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1856 <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
1857 <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
1858 <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
1859 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1860 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1861 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1862
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1863 <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
1864 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1865 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
1866 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
1867 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
1868 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
1869 <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
1870 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
1871 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
1872 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
1873 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
1874 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
1875 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
1876 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
1877 instance.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1878 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1879 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1880 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
1881 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
1882 <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
1883 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
1884 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
1885 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
1886 </para>
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 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
1889 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
1890 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
1891 <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
1892 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
1893 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
1894 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
1895 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
1896 <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
1897 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1898 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1899 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
1900 <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
1901 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
1902 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
1903 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
1904 <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
1905 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
1906 <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
1907 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
1908 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
1909 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1910 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1911 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
1912 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
1913 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
1914 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
1915 <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
1916 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
1917 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
1918 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
1919 <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
1920 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
1921 application's requirements ever change.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1922 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1923 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1924
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1925 <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
1926 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1927 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
1928 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
1929 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
1930 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
1931 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
1932 <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
1933 <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
1934 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
1935 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1936 </refsect1>
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 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1939
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1940 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1941 <!-- {{{ Thread destructors -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1942
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1943 <refentry id="kernel-thread-destructors">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1944
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1945 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1946 <refentrytitle>Thread destructors</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1947 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1948
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1949 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1950 <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
1951 <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
1952 <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
1953 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1954 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1955 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1956 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1957 #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
1958 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
1959 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1960 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1961 <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
1962 <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
1963 <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
1964 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1965 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1966 <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
1967 <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
1968 <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
1969 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1970 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1971 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1972
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1973 <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
1974 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1975 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
1976 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
1977 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
1978 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1979 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1980 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
1981 <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
1982 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
1983 <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
1984 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
1985 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
1986 <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
1987 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
1988 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
1989 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
1990 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
1991 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
1992 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
1993 <literal>false</literal> on failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1994 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1995 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
1996 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
1997 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
1998 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
1999 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
2000 <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
2001 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
2002 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
2003 threads have the same destructors.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2004 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2005 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2006 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
2007 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
2008 <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
2009 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
2010 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
2011 <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
2012 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
2013 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
2014 will return <literal>false</literal>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2015 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2016 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2017
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2018 <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
2019 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2020 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
2021 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
2022 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
2023 <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
2024 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
2025 or at initialization time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2026 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2027 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2028
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2029 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2030
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2031 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2032 <!-- {{{ Exceptions -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2033
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2034 <refentry id="kernel-exceptions">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2035
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2036 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2037 <refentrytitle>Exception handling</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2038 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2039
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2040 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2041 <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
2042 <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
2043 <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
2044 <refpurpose>Handle processor exceptions</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2045 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2046 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2047 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2048 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2049 #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
2050 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2051 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2052 <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
2053 <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
2054 <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
2055 <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
2056 <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
2057 <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
2058 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2059 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2060 <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
2061 <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
2062 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2063 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2064 <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
2065 <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
2066 <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
2067 <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
2068 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2069 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2070 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2071
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2072 <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
2073 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2074 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
2075 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
2076 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
2077 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
2078 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
2079 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
2080 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2081 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2082 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
2083 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
2084 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
2085 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
2086 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
2087 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
2088 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
2089 hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2090 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2091 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2092 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
2093 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
2094 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
2095 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
2096 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
2097 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
2098 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
2099 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
2100 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
2101 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
2102 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
2103 <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
2104 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2105 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2106 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
2107 <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
2108 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
2109 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
2110 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
2111 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
2112 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
2113 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
2114 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2115 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2116 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2117 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
2118 {
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2119 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2120 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2121 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2122 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2123 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
2124 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
2125 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
2126 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
2127 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
2128 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2129 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2130 <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
2131 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
2132 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
2133 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
2134 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2135 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2136 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
2137 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
2138 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
2139 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
2140 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
2141 <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
2142 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
2143 <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
2144 <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
2145 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
2146 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2147
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2148 <caution><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2149 In the current implementation
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2150 <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
2151 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
2152 another thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2153 </para></caution>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2154 <note><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2155 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
2156 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
2157 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
2158 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
2159 <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
2160 </para></note>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2161
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2162 </refsect1>
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 <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
2165 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2166 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
2167 handlers then
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2168 <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
2169 <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
2170 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
2171 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
2172 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
2173 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
2174 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
2175 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
2176 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2177 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2178
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2179 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2180
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2181 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2182 <!-- {{{ Counters -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2183
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2184 <refentry id="kernel-counters">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2185
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2186 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2187 <refentrytitle>Counters</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2188 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2189
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2190 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2191 <refname>cyg_counter_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2192 <refname>cyg_counter_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2193 <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
2194 <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
2195 <refname>cyg_counter_tick</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2196 <refpurpose>Count event occurrences</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2197 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2198
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2199 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2200 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2201 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2202 #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
2203 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2204 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2205 <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
2206 <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
2207 <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
2208 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2209 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2210 <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
2211 <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
2212 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2213 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2214 <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
2215 <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
2216 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2217 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2218 <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
2219 <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
2220 <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
2221 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2222 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2223 <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
2224 <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
2225 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2226 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2227 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2228
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2229 <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
2230 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2231 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
2232 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
2233 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
2234 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
2235 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
2236 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
2237 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
2238 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2239 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2240 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
2241 <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
2242 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
2243 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
2244 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
2245 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
2246 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
2247 <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
2248 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
2249 structure to be re-used.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2250 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2251 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2252 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
2253 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
2254 <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
2255 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
2256 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
2257 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
2258 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
2259 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
2260 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
2261 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
2262 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
2263 value of 0.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2264 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2265 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2266 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
2267 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
2268 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
2269 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
2270 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
2271 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
2272 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
2273 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
2274 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
2275 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
2276 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
2277 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
2278 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
2279 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
2280 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
2281 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
2282 appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2283 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2284 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2285
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2286 <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
2287 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2288 <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
2289 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
2290 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
2291 initialization or in thread context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2292 <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
2293 <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
2294 <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
2295 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
2296 <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
2297 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
2298 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2299 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2300
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2301 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2302
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2303 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2304 <!-- {{{ Clocks -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2305
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2306 <refentry id="kernel-clocks">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2307
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2308 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2309 <refentrytitle>Clocks</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2310 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2311
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2312 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2313 <refname>cyg_clock_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2314 <refname>cyg_clock_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2315 <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
2316 <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
2317 <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
2318 <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
2319 <refname>cyg_current_time</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2320 <refpurpose>Provide system clocks</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2321 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2322
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2323 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2324 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2325 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2326 #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
2327 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2328 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2329 <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
2330 <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
2331 <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
2332 <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
2333 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2334 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2335 <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
2336 <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
2337 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2338 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2339 <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
2340 <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
2341 <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
2342 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2343 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2344 <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
2345 <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
2346 <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
2347 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2348 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2349 <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
2350 <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
2351 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2352 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2353 <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
2354 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2355 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2356 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2357 <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
2358 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2359 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2360 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2361 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2362
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2363 <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
2364 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2365 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
2366 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
2367 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
2368 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
2369 source.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2370 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2371 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2372 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
2373 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
2374 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
2375 <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
2376 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
2377 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
2378 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
2379 <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
2380 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
2381 <function>cyg_current_time</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2382 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2383 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2384 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
2385 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
2386 <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
2387 <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
2388 <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
2389 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
2390 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
2391 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
2392 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
2393 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
2394 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
2395 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
2396 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
2397 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
2398 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2399 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2400
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2401 <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
2402 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2403 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
2404 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
2405 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
2406 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
2407 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
2408 ticks.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2409 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2410 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2411 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
2412 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
2413 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
2414 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
2415 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
2416 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
2417 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
2418 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
2419 <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
2420 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
2421 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
2422 <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
2423 not actually provided.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2424 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2425 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2426 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
2427 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
2428 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
2429 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
2430 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2431 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2432 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
2433 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
2434 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
2435 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
2436 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
2437 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
2438 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
2439 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
2440 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
2441 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
2442 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
2443 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
2444 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
2445 ((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
2446 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
2447 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
2448 <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
2449 hardware with unusual clock frequencies.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2450 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2451 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2452 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
2453 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
2454 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
2455 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
2456 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
2457 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
2458 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
2459 <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
2460 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
2461 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
2462 <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
2463 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
2464 the timer hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2465 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2466 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2467
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2468 <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
2469 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2470 <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
2471 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
2472 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
2473 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
2474 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
2475 there is no locking between
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2476 <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
2477 <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
2478 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
2479 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2480 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2481
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2482 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2483
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2484 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2485 <!-- {{{ Alarms -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2486
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2487 <refentry id="kernel-alarms">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2488
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2489 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2490 <refentrytitle>Alarms</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2491 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2492
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2493 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2494 <refname>cyg_alarm_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2495 <refname>cyg_alarm_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2496 <refname>cyg_alarm_initialize</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2497 <refname>cyg_alarm_enable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2498 <refname>cyg_alarm_disable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2499 <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
2500 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2501
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2502 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2503 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2504 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2505 #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
2506 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2507 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2508 <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
2509 <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
2510 <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
2511 <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
2512 <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
2513 <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
2514 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2515 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2516 <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
2517 <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
2518 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2519 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2520 <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
2521 <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
2522 <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
2523 <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
2524 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2525 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2526 <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
2527 <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
2528 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2529 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2530 <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
2531 <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
2532 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2533 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2534 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2535
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2536 <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
2537 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2538 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
2539 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
2540 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
2541 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
2542 a certain period of time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2543 </para>
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 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
2546 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
2547 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
2548 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
2549 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
2550 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
2551 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
2552 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
2553 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
2554 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2555 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2556 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2557 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
2558 {
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2559 &hellip;
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2560 }
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2561 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2562 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2563 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
2564 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
2565 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
2566 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
2567 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
2568 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
2569 </para>
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 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
2572 <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
2573 The first argument specifies the alarm. The second argument indicates
2940
f89e0743ba67 * packages/kernel/current/doc/kernel.sgml: Indicate that cyg_alarm_initialize()
jld
parents: 2911
diff changeset
2574 the absolute value of the attached counter which will result in the
f89e0743ba67 * packages/kernel/current/doc/kernel.sgml: Indicate that cyg_alarm_initialize()
jld
parents: 2911
diff changeset
2575 alarm being triggered. If the third argument is 0 then the alarm
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2576 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
2577 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
2578 events.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2579 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2580 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2581 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
2582 <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
2583 <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
2584 <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
2585 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
2586 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
2587 <function>cyg_alarm_delete</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2588 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2589 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2590 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
2591 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
2592 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
2593 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
2594 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
2595 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
2596 counter is updated.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2597 </para>
356
b77e86276ec3 * src/common/clock.cxx (add_alarm): Tweak last change to allow
jlarmour
parents: 334
diff changeset
2598 <para>
b77e86276ec3 * src/common/clock.cxx (add_alarm): Tweak last change to allow
jlarmour
parents: 334
diff changeset
2599 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
2600 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
2601 </para>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2602 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2603
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2604 <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
2605 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2606 <function>cyg_alarm_create</function>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2607 <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
2608 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
2609 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
2610 <function>cyg_alarm_initialize</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2611 <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
2612 <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
2613 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
2614 <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
2615 <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
2616 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
2617 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2618 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2619
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2620 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2621
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2622 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2623 <!-- {{{ Mutexes -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2624
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2625 <refentry id="kernel-mutexes">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2626
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2627 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2628 <refentrytitle>Mutexes</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2629 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2630
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2631 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2632 <refname>cyg_mutex_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2633 <refname>cyg_mutex_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2634 <refname>cyg_mutex_lock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2635 <refname>cyg_mutex_trylock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2636 <refname>cyg_mutex_unlock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2637 <refname>cyg_mutex_release</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2638 <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
2639 <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
2640 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2641 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2642
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2643 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2644 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2645 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2646 #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
2647 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2648 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2649 <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
2650 <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
2651 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2652 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2653 <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
2654 <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
2655 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2656 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2657 <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
2658 <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
2659 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2660 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2661 <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
2662 <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
2663 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2664 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2665 <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
2666 <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
2667 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2668 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2669 <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
2670 <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
2671 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2672 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2673 <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
2674 <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
2675 <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
2676 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2677 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2678 <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
2679 <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
2680 <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
2681 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2682 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2683 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2684
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2685 <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
2686 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2687 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
2688 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
2689 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
2690 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
2691 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
2692 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
2693 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
2694 consider:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2695 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2696 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2697 static volatile int counter = 0;
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 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2700 process_event(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2701 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2702 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2703
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2704 counter++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2705 }
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
2706 </programlisting>
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2707 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2708 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
2709 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
2710 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
2711 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
2712 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
2713 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
2714 <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
2715 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
2716 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
2717 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
2718 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
2719 prove disastrous.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2720 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2721 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2722 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
2723 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
2724 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
2725 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
2726 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2727 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2728 static volatile int counter = 0;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2729 static cyg_mutex_t lock;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2730
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2731 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2732 process_event(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2733 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2734 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2735
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2736 cyg_mutex_lock(&amp;lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2737 counter++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2738 cyg_mutex_unlock(&amp;lock);
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2739 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2740 </programlisting>
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 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
2743 <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
2744 <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
2745 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
2746 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
2747 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
2748 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2749 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2750 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
2751 <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
2752 <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
2753 <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
2754 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
2755 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
2756 <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
2757 <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
2758 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
2759 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
2760 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
2761 owner, not by another thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2762 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2763 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2764 <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
2765 <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
2766 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
2767 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
2768 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
2769 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
2770 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
2771 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
2772 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
2773 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
2774 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
2775 </para>
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 <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
2778 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
2779 <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
2780 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
2781 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2782 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2783
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2784 <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
2785 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2786 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
2787 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
2788 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
2789 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
2790 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
2791 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
2792 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
2793 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
2794 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
2795 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
2796 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
2797 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
2798 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
2799 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
2800 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2801 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2802 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
2803 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
2804 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
2805 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
2806 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
2807 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
2808 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
2809 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
2810 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
2811 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2812 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2813 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
2814 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
2815 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
2816 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
2817 <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
2818 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
2819 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
2820 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
2821 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
2822 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
2823 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
2824 <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
2825 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
2826 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
2827 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
2828 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2829 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2830 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
2831 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
2832 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
2833 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
2834 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
2835 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
2836 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
2837 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
2838 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
2839 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
2840 configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2841 <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
2842 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
2843 which may prove sufficient.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2846 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
2847 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
2848 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
2849 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
2850 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
2851 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
2852 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
2853 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
2854 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
2855 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
2856 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
2857 ceilings.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2860 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
2861 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
2862 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
2863 <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
2864 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
2865 of either
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2866 <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
2867 or
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2868 <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
2869 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
2870 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
2871 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
2872 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
2873 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
2874 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
2875 <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
2876 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
2877 <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
2878 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2879 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2880 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
2881 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
2882 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
2883 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
2884 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
2885 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
2886 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
2887 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
2888 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
2889 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
2890 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
2891 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
2892 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
2893 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2894 <warning><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2895 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
2896 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
2897 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
2898 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
2899 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
2900 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
2901 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
2902 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
2903 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
2904 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
2905 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
2906 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
2907 </para></warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2908 <warning><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2909 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
2910 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
2911 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
2912 bitmap scheduler.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2913 </para></warning>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2914 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2915
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2916 <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
2917 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2918 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
2919 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
2920 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
2921 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
2922 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
2923 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
2924 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
2925 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2926 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2927 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
2928 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
2929 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
2930 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
2931 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
2932 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
2933 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
2934 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
2935 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
2936 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
2937 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2938 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2939 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
2940 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
2941 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
2942 (<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
2943 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
2944 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
2945 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
2946 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
2947 <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
2948 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
2949 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
2950 work on SMP systems.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2951 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2952 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2953
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2954 <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
2955 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2956 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
2957 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
2958 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
2959 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
2960 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
2961 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
2962 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
2963 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
2964 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
2965 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
2966 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
2967 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
2968 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
2969 purpose of using mutexes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2970 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2971 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2972
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2973 <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
2974 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2975 <function>cyg_mutex_init</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2976 <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
2977 <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
2978 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
2979 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
2980 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
2981 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
2982 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
2983 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
2984 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
2985 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
2986 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
2987 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
2988 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
2989 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2990 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2991
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2992 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2993
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2994 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2995 <!-- {{{ Condition variables -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2996
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2997 <refentry id="kernel-condition-variables">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2998
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
2999 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3000 <refentrytitle>Condition Variables</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3001 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3002
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3003 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3004 <refname>cyg_cond_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3005 <refname>cyg_cond_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3006 <refname>cyg_cond_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3007 <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
3008 <refname>cyg_cond_signal</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3009 <refname>cyg_cond_broadcast</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3010 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3011 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3012
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3013 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3014 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3015 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3016 #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
3017 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3018 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3019 <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
3020 <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
3021 <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
3022 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3023 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3024 <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
3025 <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
3026 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3027 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3028 <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
3029 <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
3030 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3031 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3032 <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
3033 <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
3034 <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
3035 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3036 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3037 <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
3038 <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
3039 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3040 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3041 <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
3042 <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
3043 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3044 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3045 </refsynopsisdiv>
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 <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
3048
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3049 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3050 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
3051 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
3052 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
3053 resources:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3054 </para>
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3057
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3058 cyg_mutex_t res_lock;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3059 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
3060 int res_count = RES_MAX;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3061
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3062 void res_init(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3063 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3064 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
3065 &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
3066 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3067
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3068 res_t res_allocate(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3069 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3070 res_t res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3071
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3072 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
3073
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3074 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
3075 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
3076 else
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 res_count--; // allocate a resources
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3079 res = res_pool[res_count];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3080 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3081
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3082 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
3083
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3084 return res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3085 }
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 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
3088 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3089 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
3090
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3091 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
3092 res_count++;
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 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
3095 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3096 </programlisting>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3099 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
3100 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
3101 <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
3102 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
3103 actions.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3104 </para>
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3107 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
3108 <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
3109 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
3110 can be used:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3111 </para>
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 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3114
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3115 cyg_mutex_t res_lock;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3116 cyg_cond_t res_wait;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3117 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
3118 int res_count = RES_MAX;
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 void res_init(void)
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 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
3123 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
3124 &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
3125 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3126
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3127 res_t res_allocate(void)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3128 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3129 res_t res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3130
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3131 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
3132
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3133 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
3134 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
3135
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3136 res_count--; // allocate a resource
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3137 res = res_pool[res_count];
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3138
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3139 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
3140
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3141 return res;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3142 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3143
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3144 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
3145 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3146 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
3147
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3148 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
3149 res_count++;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3150
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3151 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
3152
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3153 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
3154 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3155 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3156
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3157 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3158 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
3159 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
3160 <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
3161 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
3162 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
3163 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
3164 <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
3165 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
3166 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
3167 <function>cyg_cond_wait</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3168 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3169
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 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
3172 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
3173 <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
3174 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
3175 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
3176 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
3177 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
3178 resources available.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3179 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3180
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3181 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3182 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
3183 <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
3184 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
3185 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
3186 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
3187 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
3188 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
3189 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
3190 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
3191 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
3192 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
3193 waiting.
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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3196 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3197 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
3198 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
3199 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
3200 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
3201 <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
3202 <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
3203 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
3204 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
3205 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3206 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3207 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
3208 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
3209 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
3210 <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
3211 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
3212 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
3213 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
3214 again, allowing it to examine global state and determine whether or
1091
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3215 not the condition is now satisfied.
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3216 </para>
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3217 <para>
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3218 The kernel supplies a variant of this function,
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3219 <function>cyg_cond_timed_wait</function>, which can be used to wait on
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3220 the condition variable or until some number of clock ticks have
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3221 occurred. The number of ticks is specified as an absolute, not
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3222 relative tick count, and so in order to wait for a relative number of
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3223 ticks, the return value of the <function>cyg_current_time()</function>
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3224 function should be added to determine the absolute number of ticks.
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3225 The mutex will always be reclaimed before
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3226 <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
3227 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
3228 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3229 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3230 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
3231 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
3232 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
3233 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
3234 condition variable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3235 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3236 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3237 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
3238 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
3239 <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
3240 <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
3241 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
3242 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
3243 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
3244 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
3245 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
3246 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
3247 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
3248 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
3249 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
3250 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
3251 threads to proceed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3252 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3253 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3254
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3255 <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
3256 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3257 <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
3258 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
3259 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
3260 <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
3261 <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
3262 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
3263 <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
3264 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3265 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3266 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3267
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3268 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3269
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3270 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3271 <!-- {{{ Semaphores -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3272
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3273 <refentry id="kernel-semaphores">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3274
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3275 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3276 <refentrytitle>Semaphores</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3277 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3278
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3279 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3280 <refname>cyg_semaphore_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3281 <refname>cyg_semaphore_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3282 <refname>cyg_semaphore_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3283 <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
3284 <refname>cyg_semaphore_post</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3285 <refname>cyg_semaphore_peek</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3286 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3287 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3288
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3289 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3290 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3291 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3292 #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
3293 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3294 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3295 <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
3296 <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
3297 <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
3298 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3299 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3300 <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
3301 <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
3302 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3303 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3304 <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
3305 <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
3306 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3307 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3308 <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
3309 <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
3310 <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
3311 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3312 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3313 <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
3314 <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
3315 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3316 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3317 <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
3318 <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
3319 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3320 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3321 <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
3322 <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
3323 <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
3324 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3325 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3326 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3327
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3328 <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
3329 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3330 Counting semaphores are a <link
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3331 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
3332 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
3333 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
3334 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
3335 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
3336 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
3337 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
3338 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
3339 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
3340 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
3341 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
3342 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
3343 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
3344 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3345 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3346 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
3347 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
3348 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
3349 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
3350 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
3351 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
3352 this.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3353 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3354 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3355 <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
3356 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
3357 <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
3358 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
3359 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
3360 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
3361 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
3362 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
3363 events have occurred yet.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3364 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3365 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3366 <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
3367 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
3368 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
3369 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
3370 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
3371 <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
3372 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3373 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3374 <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
3375 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
3376 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
3377 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
3378 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
3379 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
3380 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
3381 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
3382 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
3383 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
3384 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
3385 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
3386 <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
3387 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
3388 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
3389 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
3390 <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
3391 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
3392 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3393 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3394 <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
3395 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
3396 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
3397 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
3398 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
3399 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
3400 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3401 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3402 <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
3403 <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
3404 either an event has occurred or a number of clock ticks have happened.
1091
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3405 The number of ticks is specified as an absolute, not relative tick
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3406 count, and so in order to wait for a relative number of ticks, the
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3407 return value of the <function>cyg_current_time()</function> function
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3408 should be added to determine the absolute number of ticks. The
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3409 function returns success if the semaphore wait operation succeeded, or
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3410 false if the operation timed out or was aborted by
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3411 <function>cyg_thread_release</function>.
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3412 If support for the real-time
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3413 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
3414 function will not be available.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3415 <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
3416 will always return immediately rather than block, again returning
1091
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3417 success or failure. If <function>cyg_semaphore_timedwait</function>
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3418 is given a timeout in the past, it operates like
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3419 <function>cyg_semaphore_trywait</function>.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3420 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3421 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3422 <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
3423 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
3424 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
3425 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
3426 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3427 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3428
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3429 <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
3430 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3431 <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
3432 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
3433 <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
3434 <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
3435 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
3436 <function>cyg_semaphore_trywait</function>,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3437 <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
3438 <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
3439 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3440 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3441 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3442
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3443 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3444
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3445 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3446 <!-- {{{ Mail boxes -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3447
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3448 <refentry id="kernel-mail-boxes">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3449
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3450 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3451 <refentrytitle>Mail boxes</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3452 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3453
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3454 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3455 <refname>cyg_mbox_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3456 <refname>cyg_mbox_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3457 <refname>cyg_mbox_get</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3458 <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
3459 <refname>cyg_mbox_tryget</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3460 <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
3461 <refname>cyg_mbox_put</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3462 <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
3463 <refname>cyg_mbox_tryput</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3464 <refname>cyg_mbox_peek</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3465 <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
3466 <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
3467 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3468 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3469
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3470 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3471 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3472 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3473 #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
3474 </funcsynopsisinfo>
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 <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
3477 <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
3478 <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
3479 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3480 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3481 <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
3482 <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
3483 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3484 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3485 <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
3486 <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
3487 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3488 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3489 <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
3490 <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
3491 <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
3492 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3493 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3494 <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
3495 <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
3496 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3497 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3498 <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
3499 <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
3500 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3501 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3502 <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
3503 <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
3504 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3505 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3506 <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
3507 <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
3508 <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
3509 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3510 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3511 <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
3512 <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
3513 <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
3514 <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
3515 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3516 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3517 <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
3518 <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
3519 <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
3520 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3521 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3522 <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
3523 <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
3524 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3525 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3526 <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
3527 <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
3528 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3529 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3530 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3531
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3532 <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
3533 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3534 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
3535 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
3536 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
3537 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
3538 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
3539 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
3540 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
3541 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
3542 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
3543 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
3544 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
3545 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
3546 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
3547 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
3548 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3549 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3550 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
3551 <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
3552 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
3553 be used for subsequent operations.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3554 <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
3555 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
3556 <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
3557 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
3558 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
3559 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3560 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3561 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
3562 <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
3563 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
3564 <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
3565 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
3566 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
3567 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
3568 <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
3569 <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
3570 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
3571 <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
3572 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
3573 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
3574 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
3575 with different priorities.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3576 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3577 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3578 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
3579 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
3580 a message is available or until a number of clock ticks have occurred.
1091
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3581 The number of ticks is specified as an absolute, not relative tick
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3582 count, and so in order to wait for a relative number of ticks, the
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3583 return value of the <function>cyg_current_time()</function> function
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3584 should be added to determine the absolute number of ticks. If no
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3585 message is posted within the timeout then a null pointer will be
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3586 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
3587 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
3588 null pointer.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3589 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3590 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3591 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
3592 <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
3593 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
3594 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
3595 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
3596 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
3597 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
3598 <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
3599 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
3600 <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
3601 on the put operation, returning false if the operation cannot be
1091
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3602 completed within the specified number of clock ticks and as for
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3603 <function>cyg_mbox_timed_get</function> this is an absolute tick
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3604 count. The <function>cyg_mbox_tryput</function> variant is
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3605 non-blocking, returning false if there are no free slots available and
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3606 the message cannot be posted without blocking.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3607 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3608 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3609 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
3610 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
3611 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
3612 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
3613 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
3614 <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
3615 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
3616 <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
3617 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
3618 <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
3619 <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
3620 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
3621 given mail box.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3622 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3623 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3624 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
3625 configuration option
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3626 <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
3627 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
3628 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3629 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3630
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3631 <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
3632 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3633 <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
3634 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
3635 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
3636 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
3637 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
3638 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
3639 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
3640 <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
3641 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
3642 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3643 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3644
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3645 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3646
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3647 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3648 <!-- {{{ Flags -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3649
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3650 <refentry id="kernel-flags">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3651
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3652 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3653 <refentrytitle>Event Flags</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3654 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3655
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3656 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3657 <refname>cyg_flag_init</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3658 <refname>cyg_flag_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3659 <refname>cyg_flag_setbits</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3660 <refname>cyg_flag_maskbits</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3661 <refname>cyg_flag_wait</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3662 <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
3663 <refname>cyg_flag_poll</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3664 <refname>cyg_flag_peek</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3665 <refname>cyg_flag_waiting</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3666 <refpurpose>Synchronization primitive</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3667 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3668
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3669 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3670 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3671 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3672 #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
3673 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3674 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3675 <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
3676 <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
3677 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3678 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3679 <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
3680 <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
3681 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3682 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3683 <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
3684 <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
3685 <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
3686 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3687 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3688 <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
3689 <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
3690 <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
3691 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3692 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3693 <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
3694 <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
3695 <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
3696 <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
3697 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3698 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3699 <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
3700 <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
3701 <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
3702 <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
3703 <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
3704 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3705 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3706 <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
3707 <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
3708 <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
3709 <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
3710 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3711 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3712 <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
3713 <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
3714 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3715 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3716 <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
3717 <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
3718 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3719 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3720 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3721
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3722 <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
3723 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3724 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
3725 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
3726 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
3727 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
3728 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
3729 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
3730 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
3731 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
3732 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
3733 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
3734 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3735 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3736 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
3737 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
3738 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
3739 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
3740 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
3741 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
3742 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
3743 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
3744 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3745 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3746 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
3747 <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
3748 <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
3749 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
3750 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
3751 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
3752 <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
3753 <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
3754 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3755 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3756 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
3757 <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
3758 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
3759 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
3760 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
3761 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3762 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3763 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3764 <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
3765 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3766 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
3767 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
3768 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
3769 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3770 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3771 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3772 <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
3773 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3774 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
3775 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
3776 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3777 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3778 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3779 <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
3780 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3781 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
3782 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
3783 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
3784 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
3785 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
3786 event flag.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3787 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3788 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3789 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3790 <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
3791 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3792 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
3793 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
3794 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3795 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3796 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3797 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3798 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
3799 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
3800 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
3801 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
3802 <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
3803 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
3804 <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
3805 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3806 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3807 <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
3808 <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
3809 operation must succeed within the specified number of ticks, or it
1091
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3810 will fail with a return value of 0. The number of ticks is specified
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3811 as an absolute, not relative tick count, and so in order to wait for a
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3812 relative number of ticks, the return value of the
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3813 <function>cyg_current_time()</function> function should be added to
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3814 determine the absolute number of ticks.
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3815 <function>cyg_flag_poll</function> is a non-blocking variant: if the
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3816 wait operation can succeed immediately it acts like
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3817 <function>cyg_flag_wait</function>, otherwise it returns immediately
111911c5ca9e * doc/kernel.sgml: Document that timeouts for timed functions are
jlarmour
parents: 526
diff changeset
3818 with a value of 0.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3819 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3820 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3821 <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
3822 or from inside a DSR when an event occurs. The specified bits are or'd
1585
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3823 into the current event flag value. This may cause one or more waiting
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3824 threads to be woken up, if their conditions are now satisfied. How many
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3825 threads are awoken depends on the use of <literal>CYG_FLAG_WAITMODE_CLR
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3826 </literal>. The queue of threads waiting on the flag is walked to find
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3827 threads which now have their wake condition fulfilled. If the awoken thread
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3828 has passed <literal>CYG_FLAG_WAITMODE_CLR</literal> the walking of the queue
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3829 is terminated, otherwise the walk continues. Thus if no threads have passed
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3830 <literal>CYG_FLAG_WAITMORE_CLR</literal> all threads with fulfilled
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3831 conditions will be awoken. If <literal>CYG_FLAG_WAITMODE_CLR</literal> is
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3832 passed by threads with fulfilled conditions, the number of awoken threads
eead27d1aa2f * doc/kernel.sgml: Expanded the documentation about the use of
asl
parents: 1529
diff changeset
3833 will depend on the order the threads are in the queue.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3834 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3835 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3836 <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
3837 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
3838 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
3839 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
3840 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
3841 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
3842 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
3843 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
3844 <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
3845 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
3846 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
3847 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3848 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3849 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
3850 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
3851 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
3852 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
3853 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
3854 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
3855 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3856 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3857
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3858 <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
3859 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3860 <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
3861 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
3862 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
3863 <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
3864 <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
3865 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
3866 DSR context.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3867 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3868 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3869
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3870 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3871
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3872 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3873 <!-- {{{ Spinlocks -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3874
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3875 <refentry id="kernel-spinlocks">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3876
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3877 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3878 <refentrytitle>Spinlocks</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3879 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3880
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3881 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3882 <refname>cyg_spinlock_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3883 <refname>cyg_spinlock_destroy</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3884 <refname>cyg_spinlock_spin</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3885 <refname>cyg_spinlock_clear</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3886 <refname>cyg_spinlock_test</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3887 <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
3888 <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
3889 <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
3890 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3891
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3892 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3893 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3894 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3895 #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
3896 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3897 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3898 <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
3899 <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
3900 <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
3901 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3902 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3903 <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
3904 <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
3905 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3906 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3907 <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
3908 <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
3909 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3910 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3911 <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
3912 <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
3913 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3914 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3915 <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
3916 <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
3917 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3918 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3919 <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
3920 <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
3921 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3922 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3923 <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
3924 <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
3925 <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
3926 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3927 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3928 <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
3929 <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
3930 <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
3931 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3932 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3933 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3934
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3935 <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
3936 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3937 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
3938 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
3939 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
3940 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
3941 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
3942 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
3943 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
3944 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3945 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3946 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
3947 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
3948 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
3949 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
3950 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
3951 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
3952 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
3953 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
3954 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
3955 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
3956 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
3957 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
3958 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
3959 not acceptable.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3960 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3961 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3962 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
3963 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
3964 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
3965 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
3966 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
3967 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
3968 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
3969 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
3970 processor, and the function
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3971 <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
3972 facilitate this.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3975 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
3976 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
3977 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
3978 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
3979 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
3980 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
3981 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
3982 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
3983 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
3984 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
3985 running on a different processor.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3986 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3987 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3988 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
3989 <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
3990 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
3991 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
3992 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
3993 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
3994 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3995 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
3996 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
3997 <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
3998 <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
3999 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
4000 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
4001 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
4002 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
4003 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
4004 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
4005 <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
4006 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4007 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4008 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
4009 <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
4010 <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
4011 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
4012 <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
4013 <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
4014 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4015 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4016 There are two additional routines.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4017 <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
4018 <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
4019 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
4020 will return immediately with failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4021 <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
4022 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
4023 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
4024 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
4025 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4026 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4027 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
4028 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
4029 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
4030 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
4031 inheritance do not apply.
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 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4034
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4035 <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
4036 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4037 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
4038 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
4039 <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
4040 initialization.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4041 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4042 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4043
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4044 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4045
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4046 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4047 <!-- {{{ Scheduler control -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4048
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4049 <refentry id="kernel-schedcontrol">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4050
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4051 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4052 <refentrytitle>Scheduler Control</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4053 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4054
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4055 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4056 <refname>cyg_scheduler_start</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4057 <refname>cyg_scheduler_lock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4058 <refname>cyg_scheduler_unlock</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4059 <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
4060 <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
4061 <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
4062 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4063
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4064 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4065 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4066 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4067 #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
4068 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4069 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4070 <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
4071 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4072 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4073 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4074 <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
4075 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4076 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4077 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4078 <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
4079 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4080 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4081 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4082 <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
4083 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4084 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4085 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4086 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4087
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4088 <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
4089 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4090 <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
4091 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
4092 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
4093 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
4094 <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
4095 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
4096 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
4097 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
4098 will never return.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4099 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4100 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4101 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
4102 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
4103 <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
4104 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
4105 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
4106 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
4107 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
4108 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
4109 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
4110 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
4111 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
4112 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
4113 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4114 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4115 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
4116 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
4117 <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
4118 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
4119 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
4120 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
4121 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
4122 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
4123 of kernel data structures.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4124 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4125 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4126 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
4127 <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
4128 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
4129 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
4130 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
4131 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
4132 <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
4133 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
4134 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
4135 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
4136 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4137 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4138 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
4139 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
4140 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
4141 <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
4142 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
4143 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
4144 assertion failure.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4145 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4146 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4147 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
4148 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
4149 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
4150 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
4151 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
4152 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
4153 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
4154 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
4155 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
4156 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
4157 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
4158 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
4159 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
4160 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
4161 former is more efficient.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4162 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4163 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4164
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4165 <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
4166 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4167 <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
4168 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
4169 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
4170 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
4171 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
4172 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
4173 code and DSRs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4174 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4175 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4176
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4177 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4178
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4179 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4180 <!-- {{{ Interrupt handling -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4181
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4182 <refentry id="kernel-interrupts">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4183
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4184 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4185 <refentrytitle>Interrupt Handling</refentrytitle>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4186 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4187
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4188 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4189 <refname>cyg_interrupt_create</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4190 <refname>cyg_interrupt_delete</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4191 <refname>cyg_interrupt_attach</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4192 <refname>cyg_interrupt_detach</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4193 <refname>cyg_interrupt_configure</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4194 <refname>cyg_interrupt_acknowledge</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4195 <refname>cyg_interrupt_enable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4196 <refname>cyg_interrupt_disable</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4197 <refname>cyg_interrupt_mask</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4198 <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
4199 <refname>cyg_interrupt_unmask</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4200 <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
4201 <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
4202 <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
4203 <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
4204 <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
4205 <refpurpose>Manage interrupt handlers</refpurpose>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4206 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4207
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4208 <refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4209 <funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4210 <funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4211 #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
4212 </funcsynopsisinfo>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4213 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4214 <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
4215 <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
4216 <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
4217 <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
4218 <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
4219 <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
4220 <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
4221 <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
4222 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4223 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4224 <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
4225 <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
4226 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4227 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4228 <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
4229 <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
4230 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4231 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4232 <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
4233 <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
4234 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4235 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4236 <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
4237 <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
4238 <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
4239 <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
4240 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4241 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4242 <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
4243 <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
4244 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4245 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4246 <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
4247 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4248 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4249 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4250 <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
4251 <void>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4252 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4253 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4254 <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
4255 <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
4256 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4257 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4258 <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
4259 <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
4260 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4261 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4262 <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
4263 <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
4264 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4265 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4266 <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
4267 <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
4268 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4269 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4270 <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
4271 <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
4272 <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
4273 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4274 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4275 <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
4276 <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
4277 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4278 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4279 <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
4280 <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
4281 <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
4282 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4283 <funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4284 <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
4285 <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
4286 <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
4287 </funcprototype>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4288 </funcsynopsis>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4289 </refsynopsisdiv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4290
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4291 <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
4292 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4293 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
4294 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
4295 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
4296 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
4297 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
4298 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
4299 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
4300 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
4301 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
4302 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
4303 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
4304 <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
4305 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
4306 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
4307 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
4308 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4309 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4310 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
4311 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
4312 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
4313 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
4314 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
4315 masking specific interrupts then calling
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4316 <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
4317 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
4318 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
4319 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
4320 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
4321 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
4322 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
4323 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
4324 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
4325 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4326 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4327
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4328 <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
4329 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4330 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
4331 <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
4332 arguments:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4333 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4334 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4335 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4336 <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
4337 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4338 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
4339 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
4340 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
4341 which device.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4342 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4343 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4344 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4345 <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
4346 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4347 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
4348 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
4349 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
4350 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
4351 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4352 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4353 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4354 <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
4355 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4356 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
4357 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
4358 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
4359 <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
4360 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
4361 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4362 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4363 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4364 <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
4365 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4366 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
4367 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
4368 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
4369 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
4370 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
4371 takes the following form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4372 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4373 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4374 cyg_uint32
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4375 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
4376 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4377 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
4378
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4379 &hellip;
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4380
2181
d9e9cf8adc85 * doc/kernel.sgml: Fix typo
asl
parents: 2104
diff changeset
4381 return dsr_required ?
d9e9cf8adc85 * doc/kernel.sgml: Fix typo
asl
parents: 2104
diff changeset
4382 (CYG_ISR_CALL_DSR | CYG_ISR_HANDLED) :
2104
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4383 CYG_ISR_HANDLED;
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4384 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4385 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4386 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4387 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
4388 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
4389 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
4390 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
4391 <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
4392 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
4393 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
4394 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
4395 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
4396 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
4397 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
4398 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
4399 interrupt happened.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4400 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4401 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4402 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
4403 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
4404 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
4405 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
4406 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
4407 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
4408 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
4409 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
4410 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4411 <para>
2104
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4412 The return value of an ISR is normally a bit mask containing zero, one
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4413 or both of the following bits: <literal>CYG_ISR_CALL_DSR</literal> or
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4414 <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
4415 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
4416 will be run as soon as possible. The latter indicates that the
2104
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4417 interrupt was handled by this ISR so there is no need to call other
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4418 interrupt handlers which might be chained on this interrupt vector. If
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4419 this ISR did not handle the interrupt it should not set the
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4420 CYG_ISR_HANDLED bit so that other chained interrupt handlers may
84bb9baeb0e1 * doc/kernel.sgml: Fix description of CYG_ISR_CALL_DSR and
asl
parents: 1585
diff changeset
4421 handle the interrupt.
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4422 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4423 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4424 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
4425 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
4426 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
4427 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
4428 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
4429 improves interrupt latency.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4430 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4431 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4432 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4433 <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
4434 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4435 If an interrupt has occurred and the ISR has returned a value
2181
d9e9cf8adc85 * doc/kernel.sgml: Fix typo
asl
parents: 2104
diff changeset
4436 with <literal>CYG_ISR_CALL_DSR</literal> bit being set, the system
d9e9cf8adc85 * doc/kernel.sgml: Fix typo
asl
parents: 2104
diff changeset
4437 will call the DSR associated with this interrupt
210
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4438 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
4439 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
4440 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
4441 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
4442 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
4443 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
4444 which takes the following form:
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4445 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4446 <programlisting width=72>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4447 void
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4448 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
4449 cyg_ucount32 count,
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4450 cyg_addrword_t data)
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4451 {
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4452 }
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4453 </programlisting>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4454 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4455 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
4456 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
4457 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
4458 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
4459 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
4460 <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
4461 <function>cyg_interrupt_create</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4462 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4463 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4464 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4465 <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
4466 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4467 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
4468 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
4469 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
4470 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4471 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4472 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4473 <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
4474 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4475 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
4476 interrupt handler and associated data.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4477 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4478 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4479 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4480 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4481 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
4482 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
4483 <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
4484 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
4485 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
4486 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
4487 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
4488 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
4489 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
4490 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
4491 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4492 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4493 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
4494 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
4495 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
4496 <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
4497 <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
4498 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
4499 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
4500 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4501 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4502 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
4503 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
4504 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
4505 <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
4506 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
4507 is installed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4508 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4509 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4510
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4511 <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
4512 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4513 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
4514 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
4515 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
4516 <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
4517 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
4518 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
4519 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
4520 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
4521 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
4522 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
4523 on all hardware.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4524 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4525 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4526 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
4527 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
4528 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
4529 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
4530 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
4531 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
4532 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
4533 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
4534 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
4535 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
4536 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
4537 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
4538 by that device.
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 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4541 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
4542 <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
4543 <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
4544 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
4545 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
4546 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
4547 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
4548 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
4549 <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
4550 instead. There are matching functions
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4551 <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
4552 <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
4553 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4554 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4555
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4556 <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
4557 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4558 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
4559 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
4560 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
4561 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
4562 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
4563 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
4564 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
4565 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
4566 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
4567 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4568 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4569
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4570 <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
4571 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4572 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
4573 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
4574 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
4575 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
4576 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
4577 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
4578 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
4579 environment suitable for this ISR.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4580 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4581 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4582 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
4583 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
4584 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
4585 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
4586 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
4587 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
4588 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
4589 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
4590 <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
4591 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
4592 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
4593 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4594 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4595
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4596 <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
4597 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4598 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
4599 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
4600 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
4601 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
4602 <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
4603 <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
4604 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
4605 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
4606 <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
4607 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4608 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4609 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
4610 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
4611 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
4612 these functions is appropriate.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4613 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4614 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4615
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4616 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4617
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4618 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4619 <!-- {{{ tm_basic -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4620
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4621 <refentry id="kernel-characterization">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4622
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4623 <refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4624 <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
4625 </refmeta>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4626 <refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4627 <refname>tm_basic</refname>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4628 <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
4629 </refnamediv>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4630
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4631 <refsect1 id="kernel-characterization-description">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4632 <title>Description</title>
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 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
4635 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
4636 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
4637 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
4638 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
4639 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
4640 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4641 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4642 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
4643 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
4644 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
4645 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
4646 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
4647 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
4648 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
4649 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
4650 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4651 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4652 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
4653 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
4654 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
4655 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
4656 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
4657 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
4658 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
4659 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
4660 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
4661 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
4662 overall characterization of a system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4663 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4664 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4665 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
4666 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
4667 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
4668 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
4669 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
4670 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
4671 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
4672 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
4673 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
4674 primitives.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4675 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4676 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4677 <refsect1 id="kernel-characterization-methodology">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4678 <title>Methodology</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 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
4681 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
4682 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
4683 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
4684 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
4685 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
4686 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
4687 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
4688 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
4689 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
4690 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
4691 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
4692 from all other times.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4693 </para>
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 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
4696 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
4697 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
4698 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
4699 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
4700 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
4701 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
4702 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
4703 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
4704 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
4705 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
4706 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4707 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4708 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
4709 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
4710 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
4711 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
4712 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
4713 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
4714 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
4715 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
4716 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
4717 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
4718 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
4719 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
4720 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
4721 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
4722 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
4723 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
4724 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
4725 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
4726 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4727 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4728 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
4729 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
4730 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
4731 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
4732 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
4733 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
4734 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
4735 interrupt latency over time.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4736 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4737 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4738
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4739 <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
4740 <title>Using these Measurements</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4741 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4742 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
4743 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
4744 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
4745 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
4746 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
4747 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
4748 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4749 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4750
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4751 <refsect1 id="kernel-characterization-influences">
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4752 <title>Influences on Performance</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4753 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4754 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
4755 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
4756 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
4757 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
4758 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
4759 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
4760 (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
4761 (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
4762 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
4763 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
4764 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
4765 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
4766 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
4767 handling for devices.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4768 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4769 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4770
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4771 <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
4772 <title>Measured Items</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4773 <para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4774 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
4775 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
4776 <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
4777 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
4778 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
4779 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
4780 &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
4781 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
4782 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
4783 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
4784 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
4785 </para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4786
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4787 <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
4788 <title>Thread Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4789 <variablelist>
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 <term>Create thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4792 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4793 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
4794 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
4795 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
4796 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4797 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4798 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4799 <term>Yield thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4800 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4801 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
4802 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
4803 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
4804 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4805 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4806 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4807 <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
4808 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4809 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
4810 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
4811 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
4812 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4813 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4814 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4815 <term>Resume thread</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4816 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4817 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
4818 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
4819 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
4820 thread.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4821 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4822 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4823 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4824 <term>Set priority</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4825 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4826 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
4827 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
4828 value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4829 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4830 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4831 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4832 <term>Get priority</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4833 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4834 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
4835 call.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4836 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4837 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4838 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4839 <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
4840 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4841 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
4842 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
4843 suspended before being killed.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4844 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4845 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4846 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4847 <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
4848 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4849 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
4850 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
4851 <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
4852 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
4853 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4854 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4855 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4856 <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
4857 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4858 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
4859 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
4860 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
4861 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
4862 to run.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4863 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4864 </varlistentry>
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 <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
4867 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4868 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
4869 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
4870 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
4871 resume call has no effect.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4872 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4873 </varlistentry>
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 <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
4876 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4877 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
4878 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
4879 previous tests).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4880 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4881 </varlistentry>
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 <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
4884 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4885 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
4886 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
4887 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
4888 place.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4889 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4890 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4891 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4892 <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
4893 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4894 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
4895 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
4896 action.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4897 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4898 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4899 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4900 <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
4901 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4902 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
4903 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
4904 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
4905 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4906 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4907 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4908 <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
4909 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4910 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
4911 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
4912 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
4913 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
4914 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
4915 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4916 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4917 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4918 <term>Thread switch</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4919 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4920 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
4921 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
4922 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
4923 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
4924 <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
4925 other thread.
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 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4929 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4930
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4931 <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
4932 <title>Scheduler Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4933 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4934 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4935 <term>Scheduler lock</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4936 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4937 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
4938 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4939 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4940 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4941 <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
4942 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4943 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
4944 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
4945 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
4946 run.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4947 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4948 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4949 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4950 <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
4951 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4952 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
4953 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
4954 suspended.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4955 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4956 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4957 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4958 <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
4959 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4960 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
4961 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
4962 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
4963 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
4964 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
4965 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4966 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4967 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4968 <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
4969 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4970 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
4971 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
4972 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
4973 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
4974 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
4975 <function>cyg_scheduler_unlock()</function>.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4976 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4977 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4978 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4979 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4980
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4981 <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
4982 <title>Mutex Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4983 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4984 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4985 <term>Init mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4986 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4987 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
4988 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
4989 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
4990 to the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4991 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4992 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4993 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4994 <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
4995 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
4996 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
4997 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
4998 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
4999 system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5000 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5001 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5002 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5003 <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
5004 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5005 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
5006 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
5007 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
5008 system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5009 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5010 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5011 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5012 <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
5013 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5014 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
5015 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
5016 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
5017 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
5018 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5019 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5020 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5021 <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
5022 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5023 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
5024 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
5025 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
5026 system while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5027 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5028 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5029 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5030 <term>Destroy mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5031 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5032 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
5033 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
5034 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
5035 while this test runs.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5036 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5037 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5038 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5039 <term>Unlock/Lock mutex</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5040 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5041 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
5042 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
5043 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
5044 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
5045 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
5046 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
5047 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5048 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5049 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5050 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5051
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5052 <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
5053 <title>Mailbox Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5054 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5055 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5056 <term>Create mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5057 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5058 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
5059 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
5060 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
5061 the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5062 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5063 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5064 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5065 <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
5066 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5067 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
5068 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
5069 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
5070 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
5071 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5072 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5073 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5074 <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
5075 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5076 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
5077 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
5078 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
5079 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
5080 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5081 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5082 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5083 <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
5084 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5085 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
5086 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
5087 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
5088 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
5089 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5090 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5091 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5092 <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
5093 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5094 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
5095 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
5096 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
5097 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
5098 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5099 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5100 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5101 <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
5102 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5103 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
5104 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
5105 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
5106 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
5107 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5108 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5109 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5110 <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
5111 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5112 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
5113 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
5114 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
5115 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
5116 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5117 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5118 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5119 <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
5120 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5121 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
5122 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
5123 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
5124 from a mailbox without blocking.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5125 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5126 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5127 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5128 <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
5129 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5130 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
5131 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
5132 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
5133 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5134 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5135 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5136 <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
5137 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5138 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
5139 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
5140 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
5141 without disturbing the mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5142 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5143 </varlistentry>
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 <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
5146 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5147 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
5148 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
5149 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
5150 from a non-empty mailbox.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5151 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5152 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5153 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5154 <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
5155 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5156 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
5157 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
5158 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
5159 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
5160 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5161 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5162 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5163 <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
5164 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5165 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
5166 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
5167 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
5168 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
5169 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5170 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5171 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5172 <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
5173 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5174 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
5175 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
5176 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
5177 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5178 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5179 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5180 <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
5181 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5182 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
5183 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
5184 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
5185 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5186 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5187 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5188 <term>Delete mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5189 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5190 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
5191 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
5192 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
5193 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5194 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5195 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5196 <term>Put/Get mbox</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5197 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5198 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
5199 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
5200 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
5201 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
5202 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5203 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5204 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5205 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5206
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5207 <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
5208 <title>Semaphore Primitives</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5209 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5210 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5211 <term>Init semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5212 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5213 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
5214 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
5215 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
5216 creating a new semaphore.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5217 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5218 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5219 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5220 <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
5221 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5222 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
5223 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
5224 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
5225 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
5226 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
5227 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5228 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5229 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5230 <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
5231 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5232 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
5233 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
5234 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
5235 &ldquo;taking&rdquo; a semaphore.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5236 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5237 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5238 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5239 <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
5240 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5241 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
5242 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
5243 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
5244 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
5245 would be no.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5246 </para></listitem>
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5249 <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
5250 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5251 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
5252 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
5253 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
5254 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
5255 would be yes.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5256 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5257 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5258 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5259 <term>Peek semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5260 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5261 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
5262 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
5263 current semaphore count value.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5264 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5265 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5266 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5267 <term>Destroy semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5268 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5269 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
5270 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
5271 semaphore from the system.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5272 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5273 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5274 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5275 <term>Post/Wait semaphore</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5276 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5277 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
5278 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
5279 <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
5280 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
5281 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
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 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5285 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5286
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5287 <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
5288 <title>Counters</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5289 <variablelist>
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 <term>Create counter</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5292 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5293 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
5294 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
5295 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
5296 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>Get counter value</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
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5303 <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
5304 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
5305 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5306 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5307 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5308 <term>Set counter value</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5309 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5310 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
5311 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
5312 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5313 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5314 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5315 <term>Tick counter</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5316 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5317 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
5318 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
5319 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5320 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5321 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5322 <term>Delete counter</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5323 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5324 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
5325 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
5326 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
5327 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5328 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5329 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5330 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5331
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5332 <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
5333 <title>Alarms</title>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5334 <variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5335 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5336 <term>Create alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5337 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5338 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
5339 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
5340 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
5341 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
5342 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5343 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5344 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5345 <term>Initialize alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5346 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5347 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
5348 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
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>Disable alarm</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 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
5355 Each alarm is explicitly disabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5356 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5357 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5358 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5359 <term>Enable alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5360 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5361 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
5362 Each alarm is explicitly enabled.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5363 </para></listitem>
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 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5366 <term>Delete alarm</term>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5367 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5368 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
5369 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
5370 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
5371 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5372 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5373 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5374 <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
5375 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5376 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
5377 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
5378 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
5379 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
5380 activated (fired).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5381 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5382 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5383 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5384 <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
5385 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5386 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
5387 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
5388 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
5389 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
5390 not activated (fired).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5391 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5392 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5393 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5394 <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
5395 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5396 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
5397 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
5398 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
5399 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
5400 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
5401 calling the alarm callback function.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5402 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5403 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5404 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5405 <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
5406 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5407 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
5408 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
5409 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
5410 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
5411 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
5412 calling the alarm callback function.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5413 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5414 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5415 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5416 <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
5417 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5418 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
5419 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
5420 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
5421 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
5422 occurs (all threads are suspended).
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5423 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5424 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5425 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5426 <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
5427 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5428 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
5429 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
5430 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
5431 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
5432 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
5433 <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
5434 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
5435 threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5436 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5437 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5438 <varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5439 <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
5440 <listitem><para>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5441 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
5442 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
5443 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
5444 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
5445 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
5446 <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
5447 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
5448 executing threads.
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5449 </para></listitem>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5450 </varlistentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5451 </variablelist>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5452 </refsect2>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5453
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5454 </refsect1>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5455
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5456 </refentry>
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5457
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5458 <!-- }}} -->
d2c90368aeef Merge from eCos master repository on 2002-05-23-21:39:14-BST
jlarmour
parents: 208
diff changeset
5459
208
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST
jlarmour
parents:
diff changeset
5460 </part>