-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->More Features — Clocks and Alarm
-Handlers</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos User Guide"
-HREF="ecos-user-guide.html"><LINK
-REL="UP"
-TITLE="Programming With eCos"
-HREF="user-guide-programming.html"><LINK
-REL="PREVIOUS"
-TITLE="A Sample Program with Two Threads"
-HREF="sample-twothreads.html"><LINK
-REL="NEXT"
-TITLE="The eCos Configuration Tool"
-HREF="the-ecos-configuration-tool.html"></HEAD
-><BODY
-CLASS="CHAPTER"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos User Guide</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="sample-twothreads.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="the-ecos-configuration-tool.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><DIV
-CLASS="CHAPTER"
-><H1
-><A
-NAME="CLOCKS-AND-ALARM-HANDLERS">Chapter 14. More Features — Clocks and Alarm
-Handlers</H1
-><P
->If a program wanted to execute a task at a given time, or
-periodically, it could do it in an inefficient way by sitting in a
-loop and checking the real-time clock to see if the proper amount of
-time has elapsed. But operating systems usually provide system calls
-which allow the program to be informed at the desired time.</P
-><P
-><SPAN
-CLASS="PRODUCTNAME"
->eCos</SPAN
-> provides a rich timekeeping formalism, involving
-<SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->counters</I
-></SPAN
->, <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->clocks</I
-></SPAN
->,
-<SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->alarms</I
-></SPAN
->, and <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->timers</I
-></SPAN
->. The
-precise definition, relationship, and motivation of these features is
-beyond the scope of this tutorial, but these examples illustrate how
-to set up basic periodic tasks.</P
-><P
->Alarms are events that happen at
-a given time, either once or periodically. A thread associates an
-alarm handling function with the alarm, so that the function will
-be invoked every time the alarm “goes off”.</P
-><DIV
-CLASS="SECT1"
-><H1
-CLASS="SECT1"
-><A
-NAME="SAMPLE-ALARMS">A Sample Program with Alarms</H1
-><P
-><TT
-CLASS="FILENAME"
->simple-alarm.c</TT
-> (in
-the examples directory) is a short program that creates a thread that
-creates an alarm. The alarm is handled by the function
-<TT
-CLASS="FUNCTION"
->test_alarm_func()</TT
->, which sets a global
-variable. When the main thread of execution sees that the variable has
-changed, it prints a message.</P
-><DIV
-CLASS="EXAMPLE"
-><A
-NAME="AEN910"><P
-><B
->Example 14-1. A sample program that creates an alarm</B
-></P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->/* this is a very simple program meant to demonstrate
- a basic use of time, alarms and alarm-handling functions in eCos */
-
-#include <cyg/kernel/kapi.h>
-
-#include <stdio.h>
-
-#define NTHREADS 1
-#define STACKSIZE 4096
-
-static cyg_handle_t thread[NTHREADS];
-
-static cyg_thread thread_obj[NTHREADS];
-static char stack[NTHREADS][STACKSIZE];
-
-static void alarm_prog( cyg_addrword_t data );
-
-/* we install our own startup routine which sets up
- threads and starts the scheduler */
-void cyg_user_start(void)
-{
- cyg_thread_create(4, alarm_prog, (cyg_addrword_t) 0,
- "alarm_thread", (void *) stack[0],
- STACKSIZE, &thread[0], &thread_obj[0]);
- cyg_thread_resume(thread[0]);
-}
-
-/* we need to declare the alarm handling function (which is
- defined below), so that we can pass it to cyg_alarm_initialize() */
-cyg_alarm_t test_alarm_func;
-
-/* alarm_prog() is a thread which sets up an alarm which is then
- handled by test_alarm_func() */
-static void alarm_prog(cyg_addrword_t data)
-{
- cyg_handle_t test_counterH, system_clockH, test_alarmH;
- cyg_tick_count_t ticks;
- cyg_alarm test_alarm;
- unsigned how_many_alarms = 0, prev_alarms = 0, tmp_how_many;
-
- system_clockH = cyg_real_time_clock();
- cyg_clock_to_counter(system_clockH, &test_counterH);
- cyg_alarm_create(test_counterH, test_alarm_func,
- (cyg_addrword_t) &how_many_alarms,
- &test_alarmH, &test_alarm);
- cyg_alarm_initialize(test_alarmH, cyg_current_time()+200, 200);
-
- /* get in a loop in which we read the current time and
- print it out, just to have something scrolling by */
- for (;;) {
- ticks = cyg_current_time();
- printf("Time is %llu\n", ticks);
- /* note that we must lock access to how_many_alarms, since the
- alarm handler might change it. this involves using the
- annoying temporary variable tmp_how_many so that I can keep the
- critical region short */
- cyg_scheduler_lock();
- tmp_how_many = how_many_alarms;
- cyg_scheduler_unlock();
- if (prev_alarms != tmp_how_many) {
- printf(" --- alarm calls so far: %u\n", tmp_how_many);
- prev_alarms = tmp_how_many;
- }
- cyg_thread_delay(30);
- }
-}
-
-/* test_alarm_func() is invoked as an alarm handler, so
- it should be quick and simple. in this case it increments
- the data that is passed to it. */
-void test_alarm_func(cyg_handle_t alarmH, cyg_addrword_t data)
-{
- ++*((unsigned *) data);
-}</PRE
-></TD
-></TR
-></TABLE
-></DIV
-><P
->When you run this program (by typing <B
-CLASS="COMMAND"
->continue</B
-> at
-the (<SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->gdb</I
-></SPAN
->) prompt) the output should look like
-this:</P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="SCREEN"
->Starting program: <TT
-CLASS="REPLACEABLE"
-><I
->BASE_DIR</I
-></TT
->/examples/simple-alarm.exe
-Time is 0
-Time is 30
-Time is 60
-Time is 90
-Time is 120
-Time is 150
-Time is 180
-Time is 210
- --- alarm calls so far: 1
-Time is 240
-Time is 270
-Time is 300
-Time is 330
-Time is 360
-Time is 390
-Time is 420
- --- alarm calls so far: 2
-Time is 450
-Time is 480</PRE
-></TD
-></TR
-></TABLE
-><DIV
-CLASS="NOTE"
-><BLOCKQUOTE
-CLASS="NOTE"
-><P
-><B
->Note: </B
->When running in a simulator the delays
-might be quite long. On a hardware board (where the clock speed is 100
-ticks/second) the delays should average to about 0.3 seconds (and 2
-seconds between alarms). In simulation, the delay will depend on the
-speed of the host processor and will almost always be much slower than
-the actual board. You might want to reduce the delay parameter when
-running in simulation.</P
-></BLOCKQUOTE
-></DIV
-><P
->Here are a few things you might notice about this program:</P
-><P
-></P
-><UL
-><LI
-><P
->It used the <TT
-CLASS="FUNCTION"
->cyg_real_time_clock()</TT
-> function;
-this always returns a handle to the default system real-time clock. </P
-></LI
-><LI
-><P
->Clocks are based on counters, so the function <TT
-CLASS="FUNCTION"
->cyg_alarm_create()</TT
->
-uses a counter handle. The program used the function
-<TT
-CLASS="FUNCTION"
->cyg_clock_to_counter()</TT
-> to strip the clock handle
-to the underlying counter handle. </P
-></LI
-><LI
-><P
->Once the alarm is created it is
-initialized with <TT
-CLASS="FUNCTION"
->cyg_alarm_initialize()</TT
->, which
-sets the time at which the alarm should go off, as well as the period
-for repeating alarms. It is set to go off at the current time and
-then to repeat every 200 ticks. </P
-></LI
-><LI
-><P
->The alarm handler function
-<TT
-CLASS="FUNCTION"
->test_alarm_func()</TT
-> conforms to the guidelines for
-writing alarm handlers and other delayed service routines: it does not invoke any
-functions which might lock the scheduler. This is discussed in detail
-in the <I
-CLASS="CITETITLE"
-><SPAN
-CLASS="PRODUCTNAME"
->eCos</SPAN
-> Reference Manual</I
->, in the chapter
-<I
-CLASS="CITETITLE"
->The <SPAN
-CLASS="PRODUCTNAME"
->eCos</SPAN
-> Kernel</I
->.</P
-></LI
-><LI
-><P
->There is a <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->critical region</I
-></SPAN
-> in this program:
-the variable <TT
-CLASS="LITERAL"
->how_many_alarms</TT
-> is accessed in the
-main thread of control and is also modified in the alarm handler. To
-prevent a possible (though unlikely) race condition on this variable,
-access to <TT
-CLASS="LITERAL"
->how_many_alarms</TT
-> in the principal thread
-is protected by calls to <TT
-CLASS="FUNCTION"
->cyg_scheduler_lock()</TT
-> and
-<TT
-CLASS="FUNCTION"
->cyg_scheduler_unlock()</TT
->. When the scheduler is
-locked, the alarm handler will not be invoked, so the problem is
-averted. </P
-></LI
-></UL
-></DIV
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="sample-twothreads.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-user-guide.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="the-ecos-configuration-tool.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->A Sample Program with Two Threads</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="user-guide-programming.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->The eCos Configuration Tool</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff