+++ /dev/null
-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->Kernel Overview</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE="The eCos Kernel"
-HREF="kernel.html"><LINK
-REL="PREVIOUS"
-TITLE="The eCos Kernel"
-HREF="kernel.html"><LINK
-REL="NEXT"
-TITLE="SMP Support"
-HREF="kernel-smp.html"></HEAD
-><BODY
-CLASS="REFENTRY"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="kernel.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="kernel-smp.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><H1
-><A
-NAME="KERNEL-OVERVIEW">Kernel Overview</H1
-><DIV
-CLASS="REFNAMEDIV"
-><A
-NAME="AEN56"
-></A
-><H2
->Name</H2
->Kernel -- Overview of the eCos Kernel</DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-OVERVIEW-DESCRIPTION"
-></A
-><H2
->Description</H2
-><P
->The kernel is one of the key packages in all of eCos. It provides the
-core functionality needed for developing multi-threaded applications:
- </P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
->The ability to create new threads in the system, either during startup
-or when the system is already running.
- </P
-></LI
-><LI
-><P
->Control over the various threads in the system, for example
-manipulating their priorities.
- </P
-></LI
-><LI
-><P
->A choice of schedulers, determining which thread should currently be
-running.
- </P
-></LI
-><LI
-><P
->A range of synchronization primitives, allowing threads to interact
-and share data safely.
- </P
-></LI
-><LI
-><P
->Integration with the system's support for interrupts and exceptions.
- </P
-></LI
-></OL
-><P
->In some other operating systems the kernel provides additional
-functionality. For example the kernel may also provide memory
-allocation functionality, and device drivers may be part of the kernel
-as well. This is not the case for eCos. Memory allocation is handled
-by a separate package. Similary each device driver will typically be a
-separate package. Various packages are combined and configured using
-the eCos configuration technology to meet the requirements of the
-application.
- </P
-><P
->The eCos kernel package is optional. It is possible to write
-single-threaded applications which do not use any kernel
-functionality, for example RedBoot. Typically such applications are
-based around a central polling loop, continually checking all devices
-and taking appropriate action when I/O occurs. A small amount of
-calculation is possible every iteration, at the cost of an increased
-delay between an I/O event occurring and the polling loop detecting
-the event. When the requirements are straightforward it may well be
-easier to develop the application using a polling loop, avoiding the
-complexities of multiple threads and synchronization between threads.
-As requirements get more complicated a multi-threaded solution becomes
-more appropriate, requiring the use of the kernel. In fact some of the
-more advanced packages in eCos, for example the TCP/IP stack, use
-multi-threading internally. Therefore if the application uses any of
-those packages then the kernel becomes a required package, not an
-optional one.
- </P
-><P
->The kernel functionality can be used in one of two ways. The kernel
-provides its own C API, with functions like
-<TT
-CLASS="FUNCTION"
->cyg_thread_create</TT
-> and
-<TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
->. These can be called directly from
-application code or from other packages. Alternatively there are a
-number of packages which provide compatibility with existing API's,
-for example POSIX threads or µITRON. These allow application
-code to call standard functions such as
-<TT
-CLASS="FUNCTION"
->pthread_create</TT
->, and those functions are
-implemented using the basic functionality provided by the eCos kernel.
-Using compatibility packages in an eCos application can make it much
-easier to reuse code developed in other environments, and to share
-code.
- </P
-><P
->Although the different compatibility packages have similar
-requirements on the underlying kernel, for example the ability to
-create a new thread, there are differences in the exact semantics. For
-example, strict µITRON compliance requires that kernel
-timeslicing is disabled. This is achieved largely through the
-configuration technology. The kernel provides a number of
-configuration options that control the exact semantics that are
-provided, and the various compatibility packages require particular
-settings for those options. This has two important consequences.
-First, it is not usually possible to have two different compatibility
-packages in one eCos configuration because they will have conflicting
-requirements on the underlying kernel. Second, the semantics of the
-kernel's own API are only loosely defined because of the many
-configuration options. For example <TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
->
-will always attempt to lock a mutex, but various configuration options
-determine the behaviour when the mutex is already locked and there is
-a possibility of priority inversion.
- </P
-><P
->The optional nature of the kernel package presents some complications
-for other code, especially device drivers. Wherever possible a device
-driver should work whether or not the kernel is present. However there
-are some parts of the system, especially those related to interrupt
-handling, which should be implemented differently in multi-threaded
-environments containing the eCos kernel and in single-threaded
-environments without the kernel. To cope with both scenarios the
-common HAL package provides a driver API, with functions such as
-<TT
-CLASS="FUNCTION"
->cyg_drv_interrupt_attach</TT
->. When the kernel package
-is present these driver API functions map directly on to the
-equivalent kernel functions such as
-<TT
-CLASS="FUNCTION"
->cyg_interrupt_attach</TT
->, using macros to avoid any
-overheads. When the kernel is absent the common HAL package implements
-the driver API directly, but this implementation is simpler than the
-one in the kernel because it can assume a single-threaded environment.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-OVERVIEW-SCHEDULERS"
-></A
-><H2
->Schedulers</H2
-><P
->When a system involves multiple threads, a scheduler is needed to
-determine which thread should currently be running. The eCos kernel
-can be configured with one of two schedulers, the bitmap scheduler and
-the multi-level queue (MLQ) scheduler. The bitmap scheduler is
-somewhat more efficient, but has a number of limitations. Most systems
-will instead use the MLQ scheduler. Other schedulers may be added in
-the future, either as extensions to the kernel package or in separate
-packages.
- </P
-><P
->Both the bitmap and the MLQ scheduler use a simple numerical priority
-to determine which thread should be running. The number of priority
-levels is configurable via the option
-<TT
-CLASS="VARNAME"
->CYGNUM_KERNEL_SCHED_PRIORITIES</TT
->, but a typical
-system will have up to 32 priority levels. Therefore thread priorities
-will be in the range 0 to 31, with 0 being the highest priority and 31
-the lowest. Usually only the system's idle thread will run at the
-lowest priority. Thread priorities are absolute, so the kernel will
-only run a lower-priority thread if all higher-priority threads are
-currently blocked.
- </P
-><P
->The bitmap scheduler only allows one thread per priority level, so if
-the system is configured with 32 priority levels then it is limited to
-only 32 threads — still enough for many applications. A simple
-bitmap can be used to keep track of which threads are currently
-runnable. Bitmaps can also be used to keep track of threads waiting on
-a mutex or other synchronization primitive. Identifying the
-highest-priority runnable or waiting thread involves a simple
-operation on the bitmap, and an array index operation can then be used
-to get hold of the thread data structure itself. This makes the
-bitmap scheduler fast and totally deterministic.
- </P
-><P
->The MLQ scheduler allows multiple threads to run at the same priority.
-This means that there is no limit on the number of threads in the
-system, other than the amount of memory available. However operations
-such as finding the highest priority runnable thread are a little bit
-more expensive than for the bitmap scheduler.
- </P
-><P
->Optionally the MLQ scheduler supports timeslicing, where the scheduler
-automatically switches from one runnable thread to another when some
-number of clock ticks have occurred. Timeslicing only comes into play
-when there are two runnable threads at the same priority and no higher
-priority runnable threads. If timeslicing is disabled then a thread
-will not be preempted by another thread of the same priority, and will
-continue running until either it explicitly yields the processor or
-until it blocks by, for example, waiting on a synchronization
-primitive. The configuration options
-<TT
-CLASS="VARNAME"
->CYGSEM_KERNEL_SCHED_TIMESLICE</TT
-> and
-<TT
-CLASS="VARNAME"
->CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS</TT
-> control
-timeslicing. The bitmap scheduler does not provide timeslicing
-support. It only allows one thread per priority level, so it is not
-possible to preempt the current thread in favour of another one with
-the same priority.
- </P
-><P
->Another important configuration option that affects the MLQ scheduler
-is <TT
-CLASS="VARNAME"
->CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT
->. This
-determines what happens when a thread blocks, for example by waiting
-on a semaphore which has no pending events. The default behaviour of
-the system is last-in-first-out queuing. For example if several
-threads are waiting on a semaphore and an event is posted, the thread
-that gets woken up is the last one that called
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_wait</TT
->. This allows for a simple and
-fast implementation of both the queue and dequeue operations. However
-if there are several queued threads with different priorities, it may
-not be the highest priority one that gets woken up. In practice this
-is rarely a problem: usually there will be at most one thread waiting
-on a queue, or when there are several threads they will be of the same
-priority. However if the application does require strict priority
-queueing then the option
-<TT
-CLASS="VARNAME"
->CYGIMP_KERNEL_SCHED_SORTED_QUEUES</TT
-> should be
-enabled. There are disadvantages: more work is needed whenever a
-thread is queued, and the scheduler needs to be locked for this
-operation so the system's dispatch latency is worse. If the bitmap
-scheduler is used then priority queueing is automatic and does not
-involve any penalties.
- </P
-><P
->Some kernel functionality is currently only supported with the MLQ
-scheduler, not the bitmap scheduler. This includes support for SMP
-systems, and protection against priority inversion using either mutex
-priority ceilings or priority inheritance.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-OVERVIEW-SYNCH-PRIMITIVES"
-></A
-><H2
->Synchronization Primitives</H2
-><P
->The eCos kernel provides a number of different synchronization
-primitives: <A
-HREF="kernel-mutexes.html"
->mutexes</A
->,
-<A
-HREF="kernel-condition-variables.html"
->condition variables</A
->,
-<A
-HREF="kernel-semaphores.html"
->counting semaphores</A
->,
-<A
-HREF="kernel-mail-boxes.html"
->mail boxes</A
-> and
-<A
-HREF="kernel-flags.html"
->event flags</A
->.
- </P
-><P
->Mutexes serve a very different purpose from the other primitives. A
-mutex allows multiple threads to share a resource safely: a thread
-locks a mutex, manipulates the shared resource, and then unlocks the
-mutex again. The other primitives are used to communicate information
-between threads, or alternatively from a DSR associated with an
-interrupt handler to a thread.
- </P
-><P
->When a thread that has locked a mutex needs to wait for some condition
-to become true, it should use a condition variable. A condition
-variable is essentially just a place for a thread to wait, and which
-another thread, or DSR, can use to wake it up. When a thread waits on
-a condition variable it releases the mutex before waiting, and when it
-wakes up it reacquires it before proceeding. These operations are
-atomic so that synchronization race conditions cannot be introduced.
- </P
-><P
->A counting semaphore is used to indicate that a particular event has
-occurred. A consumer thread can wait for this event to occur, and a
-producer thread or a DSR can post the event. There is a count
-associated with the semaphore so if the event occurs multiple times in
-quick succession this information is not lost, and the appropriate
-number of semaphore wait operations will succeed.
- </P
-><P
->Mail boxes are also used to indicate that a particular event has
-occurred, and allows for one item of data to be exchanged per event.
-Typically this item of data would be a pointer to some data structure.
-Because of the need to store this extra data, mail boxes have a
-finite capacity. If a producer thread generates mail box events
-faster than they can be consumed then, to avoid overflow, it will be
-blocked until space is again available in the mail box. This means
-that mail boxes usually cannot be used by a DSR to wake up a
-thread. Instead mail boxes are typically only used between threads.
- </P
-><P
->Event flags can be used to wait on some number of different events,
-and to signal that one or several of these events have occurred. This
-is achieved by associating bits in a bit mask with the different
-events. Unlike a counting semaphore no attempt is made to keep track
-of the number of events that have occurred, only the fact that an
-event has occurred at least once. Unlike a mail box it is not
-possible to send additional data with the event, but this does mean
-that there is no possibility of an overflow and hence event flags can
-be used between a DSR and a thread as well as between threads.
- </P
-><P
->The eCos common HAL package provides its own device driver API which
-contains some of the above synchronization primitives. These allow
-the DSR for an interrupt handler to signal events to higher-level
-code. If the configuration includes the eCos kernel package then
-the driver API routines map directly on to the equivalent kernel
-routines, allowing interrupt handlers to interact with threads. If the
-kernel package is not included and the application consists of just a
-single thread running in polled mode then the driver API is
-implemented entirely within the common HAL, and with no need to worry
-about multiple threads the implementation can obviously be rather
-simpler.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-OVERVIEW-THREADS-INTERRUPTS"
-></A
-><H2
->Threads and Interrupt Handling</H2
-><P
->During normal operation the processor will be running one of the
-threads in the system. This may be an application thread, a system
-thread running inside say the TCP/IP stack, or the idle thread. From
-time to time a hardware interrupt will occur, causing control to be
-transferred briefly to an interrupt handler. When the interrupt has
-been completed the system's scheduler will decide whether to return
-control to the interrupted thread or to some other runnable thread.
- </P
-><P
->Threads and interrupt handlers must be able to interact. If a thread
-is waiting for some I/O operation to complete, the interrupt handler
-associated with that I/O must be able to inform the thread that the
-operation has completed. This can be achieved in a number of ways. One
-very simple approach is for the interrupt handler to set a volatile
-variable. A thread can then poll continuously until this flag is set,
-possibly sleeping for a clock tick in between. Polling continuously
-means that the cpu time is not available for other activities, which
-may be acceptable for some but not all applications. Polling once
-every clock tick imposes much less overhead, but means that the thread
-may not detect that the I/O event has occurred until an entire clock
-tick has elapsed. In typical systems this could be as long as 10
-milliseconds. Such a delay might be acceptable for some applications,
-but not all.
- </P
-><P
->A better solution would be to use one of the synchronization
-primitives. The interrupt handler could signal a condition variable,
-post to a semaphore, or use one of the other primitives. The thread
-would perform a wait operation on the same primitive. It would not
-consume any cpu cycles until the I/O event had occurred, and when the
-event does occur the thread can start running again immediately
-(subject to any higher priority threads that might also be runnable).
- </P
-><P
->Synchronization primitives constitute shared data, so care must be
-taken to avoid problems with concurrent access. If the thread that was
-interrupted was just performing some calculations then the interrupt
-handler could manipulate the synchronization primitive quite safely.
-However if the interrupted thread happened to be inside some kernel
-call then there is a real possibility that some kernel data structure
-will be corrupted.
- </P
-><P
->One way of avoiding such problems would be for the kernel functions to
-disable interrupts when executing any critical region. On most
-architectures this would be simple to implement and very fast, but it
-would mean that interrupts would be disabled often and for quite a
-long time. For some applications that might not matter, but many
-embedded applications require that the interrupt handler run as soon
-as possible after the hardware interrupt has occurred. If the kernel
-relied on disabling interrupts then it would not be able to support
-such applications.
- </P
-><P
->Instead the kernel uses a two-level approach to interrupt handling.
-Associated with every interrupt vector is an Interrupt Service Routine
-or ISR, which will run as quickly as possible so that it can service
-the hardware. However an ISR can make only a small number of kernel
-calls, mostly related to the interrupt subsystem, and it cannot make
-any call that would cause a thread to wake up. If an ISR detects that
-an I/O operation has completed and hence that a thread should be woken
-up, it can cause the associated Deferred Service Routine or DSR to
-run. A DSR is allowed to make more kernel calls, for example it can
-signal a condition variable or post to a semaphore.
- </P
-><P
->Disabling interrupts prevents ISRs from running, but very few parts of
-the system disable interrupts and then only for short periods of time.
-The main reason for a thread to disable interrupts is to manipulate
-some state that is shared with an ISR. For example if a thread needs
-to add another buffer to a linked list of free buffers and the ISR may
-remove a buffer from this list at any time, the thread would need to
-disable interrupts for the few instructions needed to manipulate the
-list. If the hardware raises an interrupt at this time, it remains
-pending until interrupts are reenabled.
- </P
-><P
->Analogous to interrupts being disabled or enabled, the kernel has a
-scheduler lock. The various kernel functions such as
-<TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
-> and
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_post</TT
-> will claim the scheduler lock,
-manipulate the kernel data structures, and then release the scheduler
-lock. If an interrupt results in a DSR being requested and the
-scheduler is currently locked, the DSR remains pending. When the
-scheduler lock is released any pending DSRs will run. These may post
-events to synchronization primitives, causing other higher priority
-threads to be woken up.
- </P
-><P
->For an example, consider the following scenario. The system has a high
-priority thread A, responsible for processing some data coming from an
-external device. This device will raise an interrupt when data is
-available. There are two other threads B and C which spend their time
-performing calculations and occasionally writing results to a display
-of some sort. This display is a shared resource so a mutex is used to
-control access.
- </P
-><P
->At a particular moment in time thread A is likely to be blocked,
-waiting on a semaphore or another synchronization primitive until data
-is available. Thread B might be running performing some calculations,
-and thread C is runnable waiting for its next timeslice. Interrupts
-are enabled, and the scheduler is unlocked because none of the threads
-are in the middle of a kernel operation. At this point the device
-raises an interrupt. The hardware transfers control to a low-level
-interrupt handler provided by eCos which works out exactly which
-interrupt occurs, and then the corresponding ISR is run. This ISR
-manipulates the hardware as appropriate, determines that there is now
-data available, and wants to wake up thread A by posting to the
-semaphore. However ISR's are not allowed to call
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_post</TT
-> directly, so instead the ISR
-requests that its associated DSR be run and returns. There are no more
-interrupts to be processed, so the kernel next checks for DSR's. One
-DSR is pending and the scheduler is currently unlocked, so the DSR can
-run immediately and post the semaphore. This will have the effect of
-making thread A runnable again, so the scheduler's data structures are
-adjusted accordingly. When the DSR returns thread B is no longer the
-highest priority runnable thread so it will be suspended, and instead
-thread A gains control over the cpu.
- </P
-><P
->In the above example no kernel data structures were being manipulated
-at the exact moment that the interrupt happened. However that cannot
-be assumed. Suppose that thread B had finished its current set of
-calculations and wanted to write the results to the display. It would
-claim the appropriate mutex and manipulate the display. Now suppose
-that thread B was timesliced in favour of thread C, and that thread C
-also finished its calculations and wanted to write the results to the
-display. It would call <TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
->. This
-kernel call locks the scheduler, examines the current state of the
-mutex, discovers that the mutex is already owned by another thread,
-suspends the current thread, and switches control to another runnable
-thread. Another interrupt happens in the middle of this
-<TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
-> call, causing the ISR to run
-immediately. The ISR decides that thread A should be woken up so it
-requests that its DSR be run and returns back to the kernel. At this
-point there is a pending DSR, but the scheduler is still locked by the
-call to <TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
-> so the DSR cannot run
-immediately. Instead the call to <TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
->
-is allowed to continue, which at some point involves unlocking the
-scheduler. The pending DSR can now run, safely post the semaphore, and
-thus wake up thread A.
- </P
-><P
->If the ISR had called <TT
-CLASS="FUNCTION"
->cyg_semaphore_post</TT
-> directly
-rather than leaving it to a DSR, it is likely that there would have
-been some sort of corruption of a kernel data structure. For example
-the kernel might have completely lost track of one of the threads, and
-that thread would never have run again. The two-level approach to
-interrupt handling, ISR's and DSR's, prevents such problems with no
-need to disable interrupts.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-OVERVIEW-CONTEXTS"
-></A
-><H2
->Calling Contexts</H2
-><P
->eCos defines a number of contexts. Only certain calls are allowed from
-inside each context, for example most operations on threads or
-synchronization primitives are not allowed from ISR context. The
-different contexts are initialization, thread, ISR and DSR.
- </P
-><P
->When eCos starts up it goes through a number of phases, including
-setting up the hardware and invoking C++ static constructors. During
-this time interrupts are disabled and the scheduler is locked. When a
-configuration includes the kernel package the final operation is a
-call to <A
-HREF="kernel-schedcontrol.html"
-><TT
-CLASS="FUNCTION"
->cyg_scheduler_start</TT
-></A
->.
-At this point interrupts are enabled, the scheduler is unlocked, and
-control is transferred to the highest priority runnable thread. If the
-configuration also includes the C library package then usually the C
-library startup package will have created a thread which will call the
-application's <TT
-CLASS="FUNCTION"
->main</TT
-> entry point.
- </P
-><P
->Some application code can also run before the scheduler is started,
-and this code runs in initialization context. If the application is
-written partly or completely in C++ then the constructors for any
-static objects will be run. Alternatively application code can define
-a function <TT
-CLASS="FUNCTION"
->cyg_user_start</TT
-> which gets called after
-any C++ static constructors. This allows applications to be written
-entirely in C.
- </P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->void
-cyg_user_start(void)
-{
- /* Perform application-specific initialization here */
-}
- </PRE
-></TD
-></TR
-></TABLE
-><P
->It is not necessary for applications to provide a
-<TT
-CLASS="FUNCTION"
->cyg_user_start</TT
-> function since the system will
-provide a default implementation which does nothing.
- </P
-><P
->Typical operations that are performed from inside static constructors
-or <TT
-CLASS="FUNCTION"
->cyg_user_start</TT
-> include creating threads,
-synchronization primitives, setting up alarms, and registering
-application-specific interrupt handlers. In fact for many applications
-all such creation operations happen at this time, using statically
-allocated data, avoiding any need for dynamic memory allocation or
-other overheads.
- </P
-><P
->Code running in initialization context runs with interrupts disabled
-and the scheduler locked. It is not permitted to reenable interrupts
-or unlock the scheduler because the system is not guaranteed to be in
-a totally consistent state at this point. A consequence is that
-initialization code cannot use synchronization primitives such as
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_wait</TT
-> to wait for an external event.
-It is permitted to lock and unlock a mutex: there are no other threads
-running so it is guaranteed that the mutex is not yet locked, and
-therefore the lock operation will never block; this is useful when
-making library calls that may use a mutex internally.
- </P
-><P
->At the end of the startup sequence the system will call
-<TT
-CLASS="FUNCTION"
->cyg_scheduler_start</TT
-> and the various threads will
-start running. In thread context nearly all of the kernel functions
-are available. There may be some restrictions on interrupt-related
-operations, depending on the target hardware. For example the hardware
-may require that interrupts be acknowledged in the ISR or DSR before
-control returns to thread context, in which case
-<TT
-CLASS="FILENAME"
->cyg_interrupt_acknowledge</TT
-> should not be called
-by a thread.
- </P
-><P
->At any time the processor may receive an external interrupt, causing
-control to be transferred from the current thread. Typically a VSR
-provided by eCos will run and determine exactly which interrupt
-occurred. Then the VSR will switch to the appropriate ISR, which can
-be provided by a HAL package, a device driver, or by the application.
-During this time the system is running at ISR context, and most of the
-kernel function calls are disallowed. This includes the various
-synchronization primitives, so for example an ISR is not allowed to
-post to a semaphore to indicate that an event has happened. Usually
-the only operations that should be performed from inside an ISR are
-ones related to the interrupt subsystem itself, for example masking an
-interrupt or acknowledging that an interrupt has been processed. On
-SMP systems it is also possible to use spinlocks from ISR context.
- </P
-><P
->When an ISR returns it can request that the corresponding DSR be run
-as soon as it is safe to do so, and that will run in DSR context. This
-context is also used for running alarm functions, and threads can
-switch temporarily to DSR context by locking the scheduler. Only
-certain kernel functions can be called from DSR context, although more
-than in ISR context. In particular it is possible to use any
-synchronization primitives which cannot block. These include
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_post</TT
->,
-<TT
-CLASS="FILENAME"
->cyg_cond_signal</TT
->,
-<TT
-CLASS="FUNCTION"
->cyg_cond_broadcast</TT
->,
-<TT
-CLASS="FUNCTION"
->cyg_flag_setbits</TT
->, and
-<TT
-CLASS="FUNCTION"
->cyg_mbox_tryput</TT
->. It is not possible to use any
-primitives that may block such as
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_wait</TT
->,
-<TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
->, or
-<TT
-CLASS="FUNCTION"
->cyg_mbox_put</TT
->. Calling such functions from inside
-a DSR may cause the system to hang.
- </P
-><P
->The specific documentation for the various kernel functions gives more
-details about valid contexts.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-OVERVIEW-ERRORS"
-></A
-><H2
->Error Handling and Assertions</H2
-><P
->In many APIs each function is expected to perform some validation of
-its parameters and possibly of the current state of the system. This
-is supposed to ensure that each function is used correctly, and that
-application code is not attempting to perform a semaphore operation on
-a mutex or anything like that. If an error is detected then a suitable
-error code is returned, for example the POSIX function
-<TT
-CLASS="FUNCTION"
->pthread_mutex_lock</TT
-> can return various error codes
-including <TT
-CLASS="LITERAL"
->EINVAL</TT
-> and <TT
-CLASS="LITERAL"
->EDEADLK</TT
->.
-There are a number of problems with this approach, especially in the
-context of deeply embedded systems:
- </P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
->Performing these checks inside the mutex lock and all the other
-functions requires extra cpu cycles and adds significantly to the code
-size. Even if the application is written correctly and only makes
-system function calls with sensible arguments and under the right
-conditions, these overheads still exist.
- </P
-></LI
-><LI
-><P
->Returning an error code is only useful if the calling code detects
-these error codes and takes appropriate action. In practice the
-calling code will often ignore any errors because the programmer
-<SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->“knows”</I
-></SPAN
-> that the function is being
-used correctly. If the programmer is mistaken then an error condition
-may be detected and reported, but the application continues running
-anyway and is likely to fail some time later in mysterious ways.
- </P
-></LI
-><LI
-><P
->If the calling code does always check for error codes, that adds yet
-more cpu cycles and code size overhead.
- </P
-></LI
-><LI
-><P
->Usually there will be no way to recover from certain errors, so if the
-application code detected an error such as <TT
-CLASS="LITERAL"
->EINVAL</TT
->
-then all it could do is abort the application somehow.
- </P
-></LI
-></OL
-><P
->The approach taken within the eCos kernel is different. Functions such
-as <TT
-CLASS="FUNCTION"
->cyg_mutex_lock</TT
-> will not return an error code.
-Instead they contain various assertions, which can be enabled or
-disabled. During the development process assertions are normally left
-enabled, and the various kernel functions will perform parameter
-checks and other system consistency checks. If a problem is detected
-then an assertion failure will be reported and the application will be
-terminated. In a typical debug session a suitable breakpoint will have
-been installed and the developer can now examine the state of the
-system and work out exactly what is going on. Towards the end of the
-development cycle assertions will be disabled by manipulating
-configuration options within the eCos infrastructure package, and all
-assertions will be eliminated at compile-time. The assumption is that
-by this time the application code has been mostly debugged: the
-initial version of the code might have tried to perform a semaphore
-operation on a mutex, but any problems like that will have been fixed
-some time ago. This approach has a number of advantages:
- </P
-><P
-></P
-><OL
-TYPE="1"
-><LI
-><P
->In the final application there will be no overheads for checking
-parameters and other conditions. All that code will have been
-eliminated at compile-time.
- </P
-></LI
-><LI
-><P
->Because the final application will not suffer any overheads, it is
-reasonable for the system to do more work during the development
-process. In particular the various assertions can test for more error
-conditions and more complicated errors. When an error is detected
-it is possible to give a text message describing the error rather than
-just return an error code.
- </P
-></LI
-><LI
-><P
->There is no need for application programmers to handle error codes
-returned by various kernel function calls. This simplifies the
-application code.
- </P
-></LI
-><LI
-><P
->If an error is detected then an assertion failure will be reported
-immediately and the application will be halted. There is no
-possibility of an error condition being ignored because application
-code did not check for an error code.
- </P
-></LI
-></OL
-><P
->Although none of the kernel functions return an error code, many of
-them do return a status condition. For example the function
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_timed_wait</TT
-> waits until either an
-event has been posted to a semaphore, or until a certain number of
-clock ticks have occurred. Usually the calling code will need to know
-whether the wait operation succeeded or whether a timeout occurred.
-<TT
-CLASS="FUNCTION"
->cyg_semaphore_timed_wait</TT
-> returns a boolean: a
-return value of zero or false indicates a timeout, a non-zero return
-value indicates that the wait succeeded.
- </P
-><P
->In conventional APIs one common error conditions is lack of memory.
-For example the POSIX function <TT
-CLASS="FUNCTION"
->pthread_create</TT
->
-usually has to allocate some memory dynamically for the thread stack
-and other per-thread data. If the target hardware does not have enough
-memory to meet all demands, or more commonly if the application
-contains a memory leak, then there may not be enough memory available
-and the function call would fail. The eCos kernel avoids such problems
-by never performing any dynamic memory allocation. Instead it is the
-responsibility of the application code to provide all the memory
-required for kernel data structures and other needs. In the case of
-<TT
-CLASS="FUNCTION"
->cyg_thread_create</TT
-> this means a
-<SPAN
-CLASS="STRUCTNAME"
->cyg_thread</SPAN
-> data structure to hold the thread
-details, and a <SPAN
-CLASS="TYPE"
->char</SPAN
-> array for the thread stack.
- </P
-><P
->In many applications this approach results in all data structures
-being allocated statically rather than dynamically. This has several
-advantages. If the application is in fact too large for the target
-hardware's memory then there will be an error at link-time rather than
-at run-time, making the problem much easier to diagnose. Static
-allocation does not involve any of the usual overheads associated with
-dynamic allocation, for example there is no need to keep track of the
-various free blocks in the system, and it may be possible to eliminate
-<TT
-CLASS="FUNCTION"
->malloc</TT
-> from the system completely. Problems such
-as fragmentation and memory leaks cannot occur if all data is
-allocated statically. However, some applications are sufficiently
-complicated that dynamic memory allocation is required, and the
-various kernel functions do not distinguish between statically and
-dynamically allocated memory. It still remains the responsibility of
-the calling code to ensure that sufficient memory is available, and
-passing null pointers to the kernel will result in assertions or
-system failure.
- </P
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="kernel.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-ref.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="kernel-smp.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->The eCos Kernel</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="kernel.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->SMP Support</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff