diff options
Diffstat (limited to 'doc/user')
31 files changed, 13201 insertions, 0 deletions
diff --git a/doc/user/Makefile b/doc/user/Makefile new file mode 100644 index 0000000000..4830a70879 --- /dev/null +++ b/doc/user/Makefile @@ -0,0 +1,59 @@ +# +# COPYRIGHT (c) 1996. +# On-Line Applications Research Corporation (OAR). +# All rights reserved. +# + +include ../Make.config + +PROJECT=c_user + +all: + +COMMON_FILES=../common/cpright.texi +FILES= bsp.texi c_user.texi clock.texi concepts.texi conf.texi \ +dirstat.texi dpmem.texi event.texi example.texi fatal.texi \ +glossary.texi init.texi intr.texi io.texi mp.texi msg.texi overview.texi \ +part.texi preface.texi region.texi rtmon.texi schedule.texi sem.texi \ +signal.texi task.texi timer.texi userext.texi $(COMMON_FILES) + +all: + +INFOFILES=$(wildcard $(PROJECT) $(PROJECT)-*) + +info: c_user + cp $(PROJECT) $(PROJECT)-* $(INFO_INSTALL) + +c_user: $(FILES) + $(MAKEINFO) $(PROJECT).texi + +vinfo: info + $(INFO) -f $(PROJECT) + +dvi: $(PROJECT).dvi +ps: $(PROJECT).ps + +$(PROJECT).ps: $(PROJECT).dvi + dvips -o $(PROJECT).ps $(PROJECT).dvi + cp $(PROJECT).ps $(PS_INSTALL) + +dv: dvi + $(XDVI) $(PROJECT).dvi + +view: ps + $(GHOSTVIEW) $(PROJECT).ps + +$(PROJECT).dvi: $(FILES) + $(TEXI2DVI) $(PROJECT).texi + +html: + -mkdir $(WWW_INSTALL)/c_user + cp rtemsarc.gif rtemspie.gif states.gif $(WWW_INSTALL)/c_user + $(TEXI2WWW) $(TEXI2WWW_ARGS) -dir $(WWW_INSTALL)/$(PROJECT) \ + $(PROJECT).texi + +clean: + rm -f *.o $(PROG) *.txt core *.html + rm -f *.dvi *.ps *.log *.aux *.cp *.fn *.ky *.pg *.toc *.tp *.vr $(BASE) + rm -f c_user c_user-* _* + diff --git a/doc/user/bsp.t b/doc/user/bsp.t new file mode 100644 index 0000000000..85b87f1078 --- /dev/null +++ b/doc/user/bsp.t @@ -0,0 +1,377 @@ +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Board Support Packages, Board Support Packages Introduction, RATE_MONOTONIC_GET_STATUS - Obtain status information on period, Top +@end ifinfo +@chapter Board Support Packages +@ifinfo +@menu +* Board Support Packages Introduction:: +* Board Support Packages Reset and Initialization:: +* Board Support Packages Device Drivers:: +* Board Support Packages User Extensions:: +* Board Support Packages Multiprocessor Communications Interface (MPCI):: +@end menu +@end ifinfo + +@ifinfo +@node Board Support Packages Introduction, Board Support Packages Reset and Initialization, Board Support Packages, Board Support Packages +@end ifinfo +@section Introduction + +A board support package (BSP) is a collection of +user-provided facilities which interface RTEMS and an +application with a specific hardware platform. These facilities +may include hardware initialization, device drivers, user +extensions, and a Multiprocessor Communications Interface +(MPCI). However, a minimal BSP need only support processor +reset and initialization and, if needed, a clock tick. + +@ifinfo +@node Board Support Packages Reset and Initialization, Interrupt Stack Requirements, Board Support Packages Introduction, Board Support Packages +@end ifinfo +@section Reset and Initialization +@ifinfo +@menu +* Interrupt Stack Requirements:: +* Processors with a Separate Interrupt Stack:: +* Processors without a Separate Interrupt Stack:: +@end menu +@end ifinfo + +An RTEMS based application is initiated or +re-initiated when the processor is reset. This initialization +code is responsible for preparing the target platform for the +RTEMS application. Although the exact actions performed by the +initialization code are highly processor and target dependent, +the logical functionality of these actions are similar across a +variety of processors and target platforms. + +Normally, the application's initialization is +performed at two separate times: before the call to +initialize_executive (reset application initialization) and +after initialize_executive in the user's initialization tasks +(local and global application initialization). The order of the +startup procedure is as follows: + +@enumerate +@item Reset application initialization. +@item Call to initialize_executive +@item Local and global application initialization. +@end enumerate + +The reset application initialization code is executed +first when the processor is reset. All of the hardware must be +initialized to a quiescent state by this software before +initializing RTEMS. When in quiescent state, devices do not +generate any interrupts or require any servicing by the +application. Some of the hardware components may be initialized +in this code as well as any application initialization that does +not involve calls to RTEMS directives. + +The processor's Interrupt Vector Table which will be +used by the application may need to be set to the required value +by the reset application initialization code. Because +interrupts are enabled automatically by RTEMS as part of the +initialize_executive directive, the Interrupt Vector Table MUST +be set before this directive is invoked to insure correct +interrupt vectoring. The processor's Interrupt Vector Table +must be accessible by RTEMS as it will be modified by the +interrupt_catch directive. On some CPUs, RTEMS installs it's +own Interrupt Vector Table as part of initialization and thus +these requirements are met automatically. The reset code which +is executed before the call to initialize_executive has the +following requirements: + +@itemize @bullet +@item Must not make any RTEMS directive calls. + +@item If the processor supports multiple privilege levels, +must leave the processor in the most privileged, or supervisory, +state. + +@item Must allocate a stack of at least MINIMUM_STACK_SIZE +bytes and initialize the stack pointer for the +initialize_executive directive. + +@item Must initialize the processor's Interrupt Vector Table. + +@item Must disable all maskable interrupts. + +@item If the processor supports a separate interrupt stack, +must allocate the interrupt stack and initialize the interrupt +stack pointer. +@end itemize + +The initialize_executive directive does not return to +the initialization code, but causes the highest priority +initialization task to begin execution. Initialization tasks +are used to perform both local and global application +initialization which is dependent on RTEMS facilities. The user +initialization task facility is typically used to create the +application's set of tasks. + +@ifinfo +@node Interrupt Stack Requirements, Processors with a Separate Interrupt Stack, Board Support Packages Reset and Initialization, Board Support Packages Reset and Initialization +@end ifinfo +@subsection Interrupt Stack Requirements + +The worst-case stack usage by interrupt service +routines must be taken into account when designing an +application. If the processor supports interrupt nesting, the +stack usage must include the deepest nest level. The worst-case +stack usage must account for the following requirements: + +@itemize @bullet +@item Processor's interrupt stack frame + +@item Processor's subroutine call stack frame + +@item RTEMS system calls + +@item Registers saved on stack + +@item Application subroutine calls +@end itemize + +The size of the interrupt stack must be greater than +or equal to the constant MINIMUM_STACK_SIZE. + +@ifinfo +@node Processors with a Separate Interrupt Stack, Processors without a Separate Interrupt Stack, Interrupt Stack Requirements, Board Support Packages Reset and Initialization +@end ifinfo +@subsection Processors with a Separate Interrupt Stack + +Some processors support a separate stack for +interrupts. When an interrupt is vectored and the interrupt is +not nested, the processor will automatically switch from the +current stack to the interrupt stack. The size of this stack is +based solely on the worst-case stack usage by interrupt service +routines. + +The dedicated interrupt stack for the entire +application is supplied and initialized by the reset and +initialization code of the user's board support package. Since +all ISRs use this stack, the stack size must take into account +the worst case stack usage by any combination of nested ISRs. + +@ifinfo +@node Processors without a Separate Interrupt Stack, Board Support Packages Device Drivers, Processors with a Separate Interrupt Stack, Board Support Packages Reset and Initialization +@end ifinfo +@subsection Processors without a Separate Interrupt Stack + +Some processors do not support a separate stack for +interrupts. In this case, without special assistance every +task's stack must include enough space to handle the task's +worst-case stack usage as well as the worst-case interrupt stack +usage. This is necessary because the worst-case interrupt +nesting could occur while any task is executing. + +On many processors without dedicated hardware managed +interrupt stacks, RTEMS manages a dedicated interrupt stack in +software. If this capability is supported on a CPU, then it is +logically equivalent to the processor supporting a separate +interrupt stack in hardware. + +@ifinfo +@node Board Support Packages Device Drivers, Clock Tick Device Driver, Processors without a Separate Interrupt Stack, Board Support Packages +@end ifinfo +@section Device Drivers +@ifinfo +@menu +* Clock Tick Device Driver:: +@end menu +@end ifinfo + +Device drivers consist of control software for +special peripheral devices and provide a logical interface for +the application developer. The RTEMS I/O manager provides +directives which allow applications to access these device +drivers in a consistent fashion. A Board Support Package may +include device drivers to access the hardware on the target +platform. These devices typically include serial and parallel +ports, counter/timer peripherals, real-time clocks, disk +interfaces, and network controllers. + +For more information on device drivers, refer to the +I/O Manager chapter. + +@ifinfo +@node Clock Tick Device Driver, Board Support Packages User Extensions, Board Support Packages Device Drivers, Board Support Packages Device Drivers +@end ifinfo +@subsection Clock Tick Device Driver + +Most RTEMS applications will include a clock tick +device driver which invokes the clock_tick directive at regular +intervals. The clock tick is necessary if the application is to +utilize timeslicing, the clock manager, the timer manager, the +rate monotonic manager, or the timeout option on blocking +directives. + +The clock tick is usually provided as an interrupt +from a counter/timer or a real-time clock device. When a +counter/timer is used to provide the clock tick, the device is +typically programmed to operate in continuous mode. This mode +selection causes the device to automatically reload the initial +count and continue the countdown without programmer +intervention. This reduces the overhead required to manipulate +the counter/timer in the clock tick ISR and increases the +accuracy of tick occurrences. The initial count can be based on +the microseconds_per_tick field in the RTEMS Configuration +Table. An alternate approach is to set the initial count for a +fixed time period (such as one millisecond) and have the ISR +invoke clock_tick on the microseconds_per_tick boundaries. +Obviously, this can induce some error if the configured +microseconds_per_tick is not evenly divisible by the chosen +clock interrupt quantum. + +It is important to note that the interval between +clock ticks directly impacts the granularity of RTEMS timing +operations. In addition, the frequency of clock ticks is an +important factor in the overall level of system overhead. A +high clock tick frequency results in less processor time being +available for task execution due to the increased number of +clock tick ISRs. + +@ifinfo +@node Board Support Packages User Extensions, Board Support Packages Multiprocessor Communications Interface (MPCI), Clock Tick Device Driver, Board Support Packages +@end ifinfo +@section User Extensions + +RTEMS allows the application developer to augment +selected features by invoking user-supplied extension routines +when the following system events occur: + +@itemize @bullet +@item Task creation +@item Task initiation +@item Task reinitiation +@item Task deletion +@item Task context switch +@item Post task context switch +@item Task begin +@item Task exits +@item Fatal error detection +@end itemize + +User extensions can be used to implement a wide variety of +functions including execution profiling, non-standard +coprocessor support, debug support, and error detection and +recovery. For example, the context of a non-standard numeric +coprocessor may be maintained via the user extensions. In this +example, the task creation and deletion extensions are +responsible for allocating and deallocating the context area, +the task initiation and reinitiation extensions would be +responsible for priming the context area, and the task context +switch extension would save and restore the context of the +device. + +For more information on user extensions, refer to the +User Extensions chapter. + +@ifinfo +@node Board Support Packages Multiprocessor Communications Interface (MPCI), Tightly-Coupled Systems, Board Support Packages User Extensions, Board Support Packages +@end ifinfo +@section Multiprocessor Communications Interface (MPCI) +@ifinfo +@menu +* Tightly-Coupled Systems:: +* Loosely-Coupled Systems:: +* Systems with Mixed Coupling:: +* Heterogeneous Systems:: +@end menu +@end ifinfo + +RTEMS requires that an MPCI layer be provided when a +multiple node application is developed. This MPCI layer must +provide an efficient and reliable communications mechanism +between the multiple nodes. Tasks on different nodes +communicate and synchronize with one another via the MPCI. Each +MPCI layer must be tailored to support the architecture of the +target platform. + +For more information on the MPCI, refer to the +Multiprocessing Manager chapter. + +@ifinfo +@node Tightly-Coupled Systems, Loosely-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI), Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Tightly-Coupled Systems + +A tightly-coupled system is a multiprocessor +configuration in which the processors communicate solely via +shared global memory. The MPCI can simply place the RTEMS +packets in the shared memory space. The two primary +considerations when designing an MPCI for a tightly-coupled +system are data consistency and informing another node of a +packet. + +The data consistency problem may be solved using +atomic "test and set" operations to provide a "lock" in the +shared memory. It is important to minimize the length of time +any particular processor locks a shared data structure. + +The problem of informing another node of a packet can +be addressed using one of two techniques. The first technique +is to use an interprocessor interrupt capability to cause an +interrupt on the receiving node. This technique requires that +special support hardware be provided by either the processor +itself or the target platform. The second technique is to have +a node poll for arrival of packets. The drawback to this +technique is the overhead associated with polling. + +@ifinfo +@node Loosely-Coupled Systems, Systems with Mixed Coupling, Tightly-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Loosely-Coupled Systems + +A loosely-coupled system is a multiprocessor +configuration in which the processors communicate via some type +of communications link which is not shared global memory. The +MPCI sends the RTEMS packets across the communications link to +the destination node. The characteristics of the communications +link vary widely and have a significant impact on the MPCI +layer. For example, the bandwidth of the communications link +has an obvious impact on the maximum MPCI throughput. + +The characteristics of a shared network, such as +Ethernet, lend themselves to supporting an MPCI layer. These +networks provide both the point-to-point and broadcast +capabilities which are expected by RTEMS. + +@ifinfo +@node Systems with Mixed Coupling, Heterogeneous Systems, Loosely-Coupled Systems, Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Systems with Mixed Coupling + +A mixed-coupling system is a multiprocessor +configuration in which the processors communicate via both +shared memory and communications links. A unique characteristic +of mixed-coupling systems is that a node may not have access to +all communication methods. There may be multiple shared memory +areas and communication links. Therefore, one of the primary +functions of the MPCI layer is to efficiently route RTEMS +packets between nodes. This routing may be based on numerous +algorithms. In addition, the router may provide alternate +communications paths in the event of an overload or a partial +failure. + +@ifinfo +@node Heterogeneous Systems, User Extensions Manager, Systems with Mixed Coupling, Board Support Packages Multiprocessor Communications Interface (MPCI) +@end ifinfo +@subsection Heterogeneous Systems + +Designing an MPCI layer for a heterogeneous system +requires special considerations by the developer. RTEMS is +designed to eliminate many of the problems associated with +sharing data in a heterogeneous environment. The MPCI layer +need only address the representation of thirty-two (32) bit +unsigned quantities. + +For more information on supporting a heterogeneous +system, refer the Supporting Heterogeneous Environments in the +Multiprocessing Manager chapter. diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi new file mode 100644 index 0000000000..625f9f934d --- /dev/null +++ b/doc/user/c_user.texi @@ -0,0 +1,159 @@ +\input ../texinfo/texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename c_user +@syncodeindex vr fn +@synindex ky cp +@paragraphindent 0 +@c @smallbook +@c %**end of header + +@c +@c COPYRIGHT (c) 1988-1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Master file for the C User's Guide +@c + +@c Joel's Questions +@c +@c 1. Why does paragraphindent only impact makeinfo? +@c 2. Why does paragraphindent show up in HTML? +@c + +@include ../common/setup.texi + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* RTEMS C User: (c_user). The C User's Guide +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@c variable substitution info: +@c +@c @set RTEMS-LANGUAGE C +@c the language is @value{RTEMS-LANGUAGE} +@c NOTE: don't use underscore in the name +@c + +@c +@c Title Page Stuff +@c + +@set edition 4.0.0a +@set update-date 25 April 1997 +@set update-month April 1997 + +@c +@c I don't really like having a short title page. --joel +@c +@c @shorttitlepage RTEMS Applications C User's Guide + +@setchapternewpage odd +@settitle RTEMS C User's Guide +@titlepage +@finalout + +@title RTEMS Applications C User's Guide +@subtitle Edition @value{edition}, for RTEMS 4.0.0 +@sp 1 +@subtitle @value{update-month} +@author On-Line Applications Research Corporation +@page +@include ../common/cpright.texi +@end titlepage + +@c This prevents a black box from being printed on "overflow" lines. +@c The alternative is to rework a sentence to avoid this problem. + +@include preface.texi +@include overview.texi +@include concepts.texi +@include init.texi +@include task.texi +@include intr.texi +@include clock.texi +@include timer.texi +@include sem.texi +@include msg.texi +@include event.texi +@include signal.texi +@include part.texi +@include region.texi +@include dpmem.texi +@include io.texi +@include fatal.texi +@include schedule.texi +@include rtmon.texi +@include bsp.texi +@include userext.texi +@include conf.texi +@include mp.texi +@include dirstat.texi +@include example.texi +@include glossary.texi +@ifinfo +@node Top, Preface, (dir), (dir) +@top c_user + +This is the online version of the RTEMS C User's Guide. + +@menu +* Preface:: +* Overview:: +* Key Concepts:: +* Initialization Manager:: +* Task Manager:: +* Interrupt Manager:: +* Clock Manager:: +* Timer Manager:: +* Semaphore Manager:: +* Message Manager:: +* Event Manager:: +* Signal Manager:: +* Partition Manager:: +* Region Manager:: +* Dual-Ported Memory Manager:: +* I/O Manager:: +* Fatal Error Manager:: +* Scheduling Concepts:: +* Rate Monotonic Manager:: +* Board Support Packages:: +* User Extensions Manager:: +* Configuring a System:: +* Multiprocessing Manager:: +* Directive Status Codes:: +* Example Application:: +* Glossary:: +* Command and Variable Index:: +* Concept Index:: +@end menu + +@end ifinfo +@c +@c +@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here +@c + +@node Command and Variable Index, Concept Index, Glossary, Top +@unnumbered Command and Variable Index + +There are currently no Command and Variable Index entries. + +@c @printindex fn + +@node Concept Index, , Command and Variable Index, Top +@unnumbered Concept Index + +There are currently no Concept Index entries. +@c @printindex cp + +@contents +@bye + diff --git a/doc/user/clock.t b/doc/user/clock.t new file mode 100644 index 0000000000..f90d5c20b6 --- /dev/null +++ b/doc/user/clock.t @@ -0,0 +1,356 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Clock Manager, Clock Manager Introduction, INTERRUPT_CATCH - Establish an ISR, Top +@end ifinfo +@chapter Clock Manager +@ifinfo +@menu +* Clock Manager Introduction:: +* Clock Manager Background:: +* Clock Manager Operations:: +* Clock Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Clock Manager Introduction, Clock Manager Background, Clock Manager, Clock Manager +@end ifinfo +@section Introduction + +The clock manager provides support for time of day +and other time related capabilities. The directives provided by +the clock manager are: + +@itemize @bullet +@item @code{clock_set} - Set system date and time +@item @code{clock_get} - Get system date and time information +@item @code{clock_tick} - Announce a clock tick +@end itemize + +@ifinfo +@node Clock Manager Background, Required Support, Clock Manager Introduction, Clock Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Required Support:: +* Time and Date Data Structures:: +* Clock Tick and Timeslicing:: +* Delays:: +* Timeouts:: +@end menu +@end ifinfo + +@ifinfo +@node Required Support, Time and Date Data Structures, Clock Manager Background, Clock Manager Background +@end ifinfo +@subsection Required Support + +For the features provided by the clock manager to be +utilized, periodic timer interrupts are required. Therefore, a +real-time clock or hardware timer is necessary to create the +timer interrupts. The clock_tick directive is normally called +by the timer ISR to announce to RTEMS that a system clock tick +has occurred. Elapsed time is measured in ticks. A tick is +defined to be an integral number of microseconds which is +specified by the user in the Configuration Table. + +@ifinfo +@node Time and Date Data Structures, Clock Tick and Timeslicing, Required Support, Clock Manager Background +@end ifinfo +@subsection Time and Date Data Structures + +The clock facilities of the clock manager operate +upon calendar time. These directives utilize the following date +and time structure for the native time and date format: + +@example +struct rtems_tod_control @{ + rtems_unsigned32 year; /* greater than 1987 */ + rtems_unsigned32 month; /* 1 - 12 */ + rtems_unsigned32 day; /* 1 - 31 */ + rtems_unsigned32 hour; /* 0 - 23 */ + rtems_unsigned32 minute; /* 0 - 59 */ + rtems_unsigned32 second; /* 0 - 59 */ + rtems_unsigned32 ticks; /* elapsed between seconds */ +@}; + +typedef struct rtems_tod_control rtems_time_of_day; +@end example + + +The native date and time format is the only format +supported when setting the system date and time using the +clock_get directive. Some applications expect to operate on a +"UNIX-style" date and time data structure. The clock_get +directive can optionally return the current date and time in the +following structure: + +@example +@group +typedef struct @{ + rtems_unsigned32 seconds; /* seconds since RTEMS epoch*/ + rtems_unsigned32 microseconds; /* since last second */ +@} rtems_clock_time_value_control; +@end group +@end example + + +The seconds field in this structure is the number of +seconds since the RTEMS epoch of January 1, 1988. + +@ifinfo +@node Clock Tick and Timeslicing, Delays, Time and Date Data Structures, Clock Manager Background +@end ifinfo +@subsection Clock Tick and Timeslicing + +Timeslicing is a task scheduling discipline in which +tasks of equal priority are executed for a specific period of +time before control of the CPU is passed to another task. It is +also sometimes referred to as the automatic round-robin +scheduling algorithm. The length of time allocated to each task +is known as the quantum or timeslice. + +The system's timeslice is defined as an integral +number of ticks, and is specified in the Configuration Table. +The timeslice is defined for the entire system of tasks, but +timeslicing is enabled and disabled on a per task basis. + +The clock_tick directive implements timeslicing by +decrementing the running task's time-remaining counter when both +timeslicing and preemption are enabled. If the task's timeslice +has expired, then that task will be preempted if there exists a +ready task of equal priority. + +@ifinfo +@node Delays, Timeouts, Clock Tick and Timeslicing, Clock Manager Background +@end ifinfo +@subsection Delays + +A sleep timer allows a task to delay for a given +interval or up until a given time, and then wake and continue +execution. This type of timer is created automatically by the +task_wake_after and task_wake_when directives and, as a result, +does not have an RTEMS ID. Once activated, a sleep timer cannot +be explicitly deleted. Each task may activate one and only one +sleep timer at a time. + +@ifinfo +@node Timeouts, Clock Manager Operations, Delays, Clock Manager Background +@end ifinfo +@subsection Timeouts + +Timeouts are a special type of timer automatically +created when the timeout option is used on the +message_queue_receive, event_receive, semaphore_obtain and +region_get_segment directives. Each task may have one and only +one timeout active at a time. When a timeout expires, it +unblocks the task with a timeout status code. + +@ifinfo +@node Clock Manager Operations, Announcing a Tick, Timeouts, Clock Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Tick:: +* Setting the Time:: +* Obtaining the Time:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Tick, Setting the Time, Clock Manager Operations, Clock Manager Operations +@end ifinfo +@subsection Announcing a Tick + +RTEMS provides the clock_tick directive which is +called from the user's real-time clock ISR to inform RTEMS that +a tick has elapsed. The tick frequency value, defined in +microseconds, is a configuration parameter found in the +Configuration Table. RTEMS divides one million microseconds +(one second) by the number of microseconds per tick to determine +the number of calls to the clock_tick directive per second. The +frequency of clock_tick calls determines the resolution +(granularity) for all time dependent RTEMS actions. For +example, calling clock_tick ten times per second yields a higher +resolution than calling clock_tick two times per second. The +clock_tick directive is responsible for maintaining both +calendar time and the dynamic set of timers. + +@ifinfo +@node Setting the Time, Obtaining the Time, Announcing a Tick, Clock Manager Operations +@end ifinfo +@subsection Setting the Time + +The clock_set directive allows a task or an ISR to +set the date and time maintained by RTEMS. If setting the date +and time causes any outstanding timers to pass their deadline, +then the expired timers will be fired during the invocation of +the clock_set directive. + +@ifinfo +@node Obtaining the Time, Clock Manager Directives, Setting the Time, Clock Manager Operations +@end ifinfo +@subsection Obtaining the Time + +The clock_get directive allows a task or an ISR to +obtain the current date and time or date and time related +information. The current date and time can be returned in +either native or UNIX-style format. Additionally, the +application can obtain date and time related information such as +the number of seconds since the RTEMS epoch, the number of ticks +since the executive was initialized, and the number of ticks per +second. The information returned by the clock_get directive is +dependent on the option selected by the caller. The following +options are available: + +@itemize @bullet +@item CLOCK_GET_TOD - obtain native style date and time +@item CLOCK_GET_TIME_VALUE - obtain UNIX-style date and time +@item CLOCK_GET_TICKS_SINCE_BOOT - obtain number of ticks since RTEMS was initialized +@item CLOCK_GET_SECONDS_SINCE_EPOCH - obtain number of seconds since RTEMS epoch +@item CLOCK_GET_TICKS_PER_SECOND - obtain number of clock ticks per second +@end itemize + +Calendar time operations will return an error code if +invoked before the date and time have been set. + +@ifinfo +@node Clock Manager Directives, CLOCK_SET - Set system date and time, Obtaining the Time, Clock Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* CLOCK_SET - Set system date and time:: +* CLOCK_GET - Get system date and time information:: +* CLOCK_TICK - Announce a clock tick:: +@end menu +@end ifinfo + +This section details the clock manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node CLOCK_SET - Set system date and time, CLOCK_GET - Get system date and time information, Clock Manager Directives, Clock Manager Directives +@end ifinfo +@subsection CLOCK_SET - Set system date and time + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_clock_set( + rtems_time_of_day *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - date and time set successfully@* +@code{INVALID_TIME_OF_DAY} - invalid time of day + +@subheading DESCRIPTION: + +This directive sets the system date and time. The +date, time, and ticks in the time_buffer structure are all +range-checked, and an error is returned if any one is out of its +valid range. + +@subheading NOTES: + +Years before 1988 are invalid. + +The system date and time are based on the configured +tick rate (number of microseconds in a tick). + +Setting the time forward may cause a higher priority +task, blocked waiting on a specific time, to be made ready. In +this case, the calling task will be preempted after the next +clock tick. + +Re-initializing RTEMS causes the system date and time +to be reset to an uninitialized state. Another call to +clock_set is required to re-initialize the system date and time +to application specific specifications. + +@page +@ifinfo +@node CLOCK_GET - Get system date and time information, CLOCK_TICK - Announce a clock tick, CLOCK_SET - Set system date and time, Clock Manager Directives +@end ifinfo +@subsection CLOCK_GET - Get system date and time information + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_clock_get( + rtems_clock_get_options option, + void *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - current time obtained successfully@* +@code{NOT_DEFINED} - system date and time is not set + +@subheading DESCRIPTION: + +This directive obtains the system date and time. If +the caller is attempting to obtain the date and time (i.e. +option is set to either CLOCK_GET_SECONDS_SINCE_EPOCH, +CLOCK_GET_TOD, or CLOCK_GET_TIME_VALUE) and the date and time +has not been set with a previous call to clock_set, then the +NOT_DEFINED status code is returned. The caller can always +obtain the number of ticks per second (option is +CLOCK_GET_TICKS_PER_SECOND) and the number of ticks since the +executive was initialized option is CLOCK_GET_TICKS_SINCE_BOOT). + +@subheading NOTES: + +This directive is callable from an ISR. + +This directive will not cause the running task to be +preempted. Re-initializing RTEMS causes the system date and +time to be reset to an uninitialized state. Another call to +clock_set is required to re-initialize the system date and time +to application specific specifications. + +@page +@ifinfo +@node CLOCK_TICK - Announce a clock tick, Timer Manager, CLOCK_GET - Get system date and time information, Clock Manager Directives +@end ifinfo +@subsection CLOCK_TICK - Announce a clock tick + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_clock_tick( void ); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - current time obtained successfully + +@subheading DESCRIPTION: + +This directive announces to RTEMS that a system clock +tick has occurred. The directive is usually called from the +timer interrupt ISR of the local processor. This directive +maintains the system date and time, decrements timers for +delayed tasks, timeouts, rate monotonic periods, and implements +timeslicing. + +@subheading NOTES: + +This directive is typically called from an ISR. + +The microseconds_per_tick and ticks_per_timeslice +parameters in the Configuration Table contain the number of +microseconds per tick and number of ticks per timeslice, +respectively. + diff --git a/doc/user/concepts.t b/doc/user/concepts.t new file mode 100644 index 0000000000..fabcfdf57d --- /dev/null +++ b/doc/user/concepts.t @@ -0,0 +1,322 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c The following figure was replaced with an ASCII equivalent. +@c Figure 2-1 Object ID Composition +@c +@ifinfo +@node Key Concepts, Key Concepts Introduction, Overview Manual Organization, Top +@end ifinfo +@chapter Key Concepts +@ifinfo +@menu +* Key Concepts Introduction:: +* Key Concepts Objects:: +* Key Concepts Communication and Synchronization:: +* Key Concepts Time:: +* Key Concepts Memory Management:: +@end menu +@end ifinfo + +@ifinfo +@node Key Concepts Introduction, Key Concepts Objects, Key Concepts, Key Concepts +@end ifinfo +@section Introduction + +The facilities provided by RTEMS are built upon a +foundation of very powerful concepts. These concepts must be +understood before the application developer can efficiently +utilize RTEMS. The purpose of this chapter is to familiarize +one with these concepts. + +@ifinfo +@node Key Concepts Objects, Key Concepts Communication and Synchronization, Key Concepts Introduction, Key Concepts +@end ifinfo +@section Objects + +RTEMS provides directives which can be used to +dynamically create, delete, and manipulate a set of predefined +object types. These types include tasks, message queues, +semaphores, memory regions, memory partitions, timers, ports, +and rate monotonic periods. The object-oriented nature of RTEMS +encourages the creation of modular applications built upon +re-usable "building block" routines. + +All objects are created on the local node as required +by the application and have an RTEMS assigned ID. All objects +have a user-assigned name. Although a relationship exists +between an object's name and its RTEMS assigned ID, the name and +ID are not identical. Object names are completely arbitrary and +selected by the user as a meaningful "tag" which may commonly +reflect the object's use in the application. Conversely, object +IDs are designed to facilitate efficient object manipulation by +the executive. + +An object name is an unsigned thirty-two bit entity +associated with the object by the user. Although not required +by RTEMS, object names are typically composed of four ASCII +characters which help identify that object. For example, a task +which causes a light to blink might be called "LITE". Utilities +are provided to build an object name from four ASCII characters +and to decompose an object name into four ASCII characters. +However, it is not required that the application use ASCII +characters to build object names. For example, if an +application requires one-hundred tasks, it would be difficult to +assign meaningful ASCII names to each task. A more convenient +approach would be to name them the binary values one through +one-hundred, respectively. + +@need 3000 + +An object ID is a unique unsigned thirty-two bit +entity composed of three parts: object class, node, and index. +The most significant six bits are the object class. The next +ten bits are the number of the node on which this object was +created. The node number is always one (1) in a single +processor system. The least significant sixteen bits form an +identifier within a particular object type. This identifier, +called the object index, ranges in value from 1 to the maximum +number of objects configured for this object type. + +@ifset use-ascii +ASCII +@example +@group + 31 26 25 16 15 0 + +-----------+------------------+-------------------------------+ + | | | | + | Class | Node | Index | + | | | | + +-----------+------------------+-------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\strut#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +#& +\hbox to 1.00in{\enskip#}& +\hbox to 1.00in{\enskip#}& +#\cr +\multispan{9}\cr +\multispan{2}31\hfil&\multispan{2}\hfil26\enskip& + \multispan{1}\enskip25\hfil&\multispan{2}\hfil16\enskip& + \multispan{1}\enskip15\hfil&\multispan{2}\hfil0\cr +&&&&&&&&&\cr +}}\hfil} +\centerline{\vbox{\offinterlineskip\halign{ +\strut\vrule#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +\vrule#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +\vrule#& +\hbox to 0.50in{\enskip#}& +\hbox to 0.50in{\enskip#}& +\vrule#\cr +\multispan{9}\cr +\noalign{\hrule} +&&&&&&&&&\cr +&\multispan{2}\hfil Class\hfil&& + \multispan{2}\hfil Node\hfil&& + \multispan{2}\hfil Index\hfil&\cr +&&&&&&&&&\cr +\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=6 WIDTH="60%" BORDER=0> +<TR><TD ALIGN=left><STRONG>31</STRONG></TD> + <TD ALIGN=right><STRONG>26</STRONG></TD> + <TD ALIGN=left><STRONG>25</STRONG></TD> + <TD ALIGN=right><STRONG>16</STRONG></TD> + <TD ALIGN=left><STRONG>15</STRONG></TD> + <TD ALIGN=right><STRONG>0</STRONG></TD></TR> + </TABLE> +</CENTER> +<CENTER> + <TABLE COLS=6 WIDTH="60%" BORDER=2> +<TR><TD ALIGN=center COLSPAN=2>Class</TD> + <TD ALIGN=center COLSPAN=2>Node</TD> + <TD ALIGN=center COLSPAN=2>Index</TD></TD> + </TABLE> +</CENTER> +@end html +@end ifset + + +The three components of an object ID make it possible +to quickly locate any object in even the most complicated +multiprocessor system. Object ID's are associated with an +object by RTEMS when the object is created and the corresponding +ID is returned by the appropriate object create directive. The +object ID is required as input to all directives involving +objects, except those which create an object or obtain the ID of +an object. + +The object identification directives can be used to +dynamically obtain a particular object's ID given its name. +This mapping is accomplished by searching the name table +associated with this object type. If the name is non-unique, +then the ID associated with the first occurrence of the name +will be returned to the application. Since object IDs are +returned when the object is created, the object identification +directives are not necessary in a properly designed single +processor application. + +An object control block is a data structure defined +by RTEMS which contains the information necessary to manage a +particular object type. For efficiency reasons, the format of +each object type's control block is different. However, many of +the fields are similar in function. The number of each type of +control block is application dependent and determined by the +values specified in the user's Configuration Table. An object +control block is allocated at object create time and freed when +the object is deleted. With the exception of user extension +routines, object control blocks are not directly manipulated by +user applications. + +@ifinfo +@node Key Concepts Communication and Synchronization, Key Concepts Time, Key Concepts Objects, Key Concepts +@end ifinfo +@section Communication and Synchronization + +In real-time multitasking applications, the ability +for cooperating execution threads to communicate and synchronize +with each other is imperative. A real-time executive should +provide an application with the following capabilities: + +@itemize @bullet +@item Data transfer between cooperating tasks +@item Data transfer between tasks and ISRs +@item Synchronization of cooperating tasks +@item Synchronization of tasks and ISRs +@end itemize + +Most RTEMS managers can be used to provide some form +of communication and/or synchronization. However, managers +dedicated specifically to communication and synchronization +provide well established mechanisms which directly map to the +application's varying needs. This level of flexibility allows +the application designer to match the features of a particular +manager with the complexity of communication and synchronization +required. The following managers were specifically designed for +communication and synchronization: + +@itemize @bullet +@item Semaphore +@item Message Queue +@item Event +@item Signal +@end itemize + +The semaphore manager supports mutual exclusion +involving the synchronization of access to one or more shared +user resources. Binary semaphores may utilize the optional +priority inheritance algorithm to avoid the problem of priority +inversion. The message manager supports both communication and +synchronization, while the event manager primarily provides a +high performance synchronization mechanism. The signal manager +supports only asynchronous communication and is typically used +for exception handling. + +@ifinfo +@node Key Concepts Time, Key Concepts Memory Management, Key Concepts Communication and Synchronization, Key Concepts +@end ifinfo +@section Time + +The development of responsive real-time applications +requires an understanding of how RTEMS maintains and supports +time-related operations. The basic unit of time in RTEMS is +known as a tick. The frequency of clock ticks is completely +application dependent and determines the granularity and +accuracy of all interval and calendar time operations. + +By tracking time in units of ticks, RTEMS is capable +of supporting interval timing functions such as task delays, +timeouts, timeslicing, the delayed execution of timer service +routines, and the rate monotonic scheduling of tasks. An +interval is defined as a number of ticks relative to the current +time. For example, when a task delays for an interval of ten +ticks, it is implied that the task will not execute until ten +clock ticks have occurred. + +A characteristic of interval timing is that the +actual interval period may be a fraction of a tick less than the +interval requested. This occurs because the time at which the +delay timer is set up occurs at some time between two clock +ticks. Therefore, the first countdown tick occurs in less than +the complete time interval for a tick. This can be a problem if +the clock granularity is large. + +The rate monotonic scheduling algorithm is a hard +real-time scheduling methodology. This methodology provides +rules which allows one to guarantee that a set of independent +periodic tasks will always meet their deadlines -- even under +transient overload conditions. The rate monotonic manager +provides directives built upon the Clock Manager's interval +timer support routines. + +Interval timing is not sufficient for the many +applications which require that time be kept in wall time or +true calendar form. Consequently, RTEMS maintains the current +date and time. This allows selected time operations to be +scheduled at an actual calendar date and time. For example, a +task could request to delay until midnight on New Year's Eve +before lowering the ball at Times Square. + +Obviously, the directives which use intervals or wall +time cannot operate without some external mechanism which +provides a periodic clock tick. This clock tick is typically +provided by a real time clock or counter/timer device. + +@ifinfo +@node Key Concepts Memory Management, Initialization Manager, Key Concepts Time, Key Concepts +@end ifinfo +@section Memory Management + +RTEMS memory management facilities can be grouped +into two classes: dynamic memory allocation and address +translation. Dynamic memory allocation is required by +applications whose memory requirements vary through the +application's course of execution. Address translation is +needed by applications which share memory with another CPU or an +intelligent Input/Output processor. The following RTEMS +managers provide facilities to manage memory: + +@itemize @bullet +@item Region + +@item Partition + +@item Dual Ported Memory +@end itemize + +RTEMS memory management features allow an application +to create simple memory pools of fixed size buffers and/or more +complex memory pools of variable size segments. The partition +manager provides directives to manage and maintain pools of +fixed size entities such as resource control blocks. +Alternatively, the region manager provides a more general +purpose memory allocation scheme that supports variable size +blocks of memory which are dynamically obtained and freed by the +application. The dual-ported memory manager provides executive +support for address translation between internal and external +dual-ported RAM address space. diff --git a/doc/user/conf.t b/doc/user/conf.t new file mode 100644 index 0000000000..126d9b584b --- /dev/null +++ b/doc/user/conf.t @@ -0,0 +1,752 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Configuring a System, Configuring a System Configuration Table, EXTENSION_DELETE - Delete a extension set, Top +@end ifinfo +@chapter Configuring a System +@ifinfo +@menu +* Configuring a System Configuration Table:: +* Configuring a System RTEMS API Configuration Table:: +* Configuring a System POSIX API Configuration Table:: +* Configuring a System CPU Dependent Information Table:: +* Configuring a System Initialization Task Table:: +* Configuring a System Driver Address Table:: +* Configuring a System User Extensions Table:: +* Configuring a System Multiprocessor Configuration Table:: +* Configuring a System Multiprocessor Communications Interface Table:: +* Configuring a System Determining Memory Requirements:: +* Configuring a System Sizing the RTEMS RAM Workspace:: +@end menu +@end ifinfo + +@ifinfo +@node Configuring a System Configuration Table, Configuring a System RTEMS API Configuration Table, Configuring a System, Configuring a System +@end ifinfo +@section Configuration Table + +The RTEMS Configuration Table is used to tailor an +application for its specific needs. For example, the user can +configure the number of device drivers or which APIs may be used. +THe address of the user-defined Configuration Table is passed as an +argument to the initialize_executive directive, which MUST be +the first RTEMS directive called. The RTEMS Configuration Table +is defined in the following C structure: + +@example +@group +typedef struct @{ + void *work_space_start; + rtems_unsigned32 work_space_size; + rtems_unsigned32 maximum_extensions; + rtems_unsigned32 microseconds_per_tick; + rtems_unsigned32 ticks_per_timeslice; + rtems_unsigned32 maximum_devices; + rtems_unsigned32 number_of_device_drivers; + rtems_driver_address_table *Device_driver_table; + rtems_extensions_table *User_extension_table; + rtems_multiprocessing_table *User_multiprocessing_table; + rtems_api_configuration_table *RTEMS_api_configuration; + posix_api_configuration_table *POSIX_api_configuration; +@} rtems_configuration_table; +@end group +@end example + +@table @b +@item work_space_start +is the address of the RTEMS RAM Workspace. +This area contains items such as the +various object control blocks (TCBs, QCBs, ...) and task stacks. +If the address is not aligned on a four-word boundary, then +RTEMS will invoke the fatal error handler during +initialize_executive. + +@item work_space_size +is the calculated size of the +RTEMS RAM Workspace. The section Sizing the RTEMS RAM Workspace +details how to arrive at this number. + +@item microseconds_per_tick +is number of microseconds per clock tick. + +@item ticks_per_timeslice +is the number of clock ticks for a timeslice. + +@item maximum_devices +is the maximum number of devices that can be registered. + +@item number_of_device_drivers +is the number of device drivers for the system. There should be +the same number of entries in the Device Driver Table. If this field +is zero, then the User_driver_address_table entry should be NULL. + +@item Device_driver_table +is the address of the Device Driver Table. This table contains the entry +points for each device driver. If the number_of_device_drivers field is zero, +then this entry should be NULL. The format of this table will be +discussed below. + +@item User_extension_table +is the address of the User +Extension Table. This table contains the entry points for the +static set of optional user extensions. If no user extensions +are configured, then this entry should be NULL. The format of +this table will be discussed below. + +@item User_multiprocessing_table +is the address of the Multiprocessor Configuration Table. This +table contains information needed by RTEMS only when used in a multiprocessor +configuration. This field must be NULL when RTEMS is used in a +single processor configuration. + +@item RTEMS_api_configuration +is the address of the RTEMS API Configuration Table. This table +contains information needed by the RTEMS API. This field should be +NULL if the RTEMS API is not used. [NOTE: Currently the RTEMS API +is required to support support components such as BSPs and libraries +which use this API.] + +@item POSIX_api_configuration +is the address of the POSIX API Configuration Table. This table +contains information needed by the POSIX API. This field should be +NULL if the POSIX API is not used. + +@end table + +@ifinfo +@node Configuring a System RTEMS API Configuration Table, Configuring a System POSIX API Configuration Table, Configuring a System Configuration Table, Configuring a System +@end ifinfo +@section RTEMS API Configuration Table + +The RTEMS API Configuration Table is used to configure the +managers which constitute the RTEMS API for a particular application. +For example, the user can configure the maximum number of tasks for +this application. The RTEMS API Configuration Table is defined in +the following C structure: + +@example +@group +typedef struct @{ + rtems_unsigned32 maximum_tasks; + rtems_unsigned32 maximum_timers; + rtems_unsigned32 maximum_semaphores; + rtems_unsigned32 maximum_message_queues; + rtems_unsigned32 maximum_partitions; + rtems_unsigned32 maximum_regions; + rtems_unsigned32 maximum_ports; + rtems_unsigned32 maximum_periods; + rtems_unsigned32 number_of_initialization_tasks; + rtems_initialization_tasks_table *User_initialization_tasks_table; +@} rtems_api_configuration_table; +@end group +@end example + +@table @b +@item maximum_tasks +is the maximum number of tasks that +can be concurrently active (created) in the system including +initialization tasks. + +@item maximum_timers +is the maximum number of timers +that can be concurrently active in the system. + +@item maximum_semaphores +is the maximum number of +semaphores that can be concurrently active in the system. + +@item maximum_message_queues +is the maximum number of +message queues that can be concurrently active in the system. + +@item maximum_partitions +is the maximum number of +partitions that can be concurrently active in the system. + +@item maximum_regions +is the maximum number of regions +that can be concurrently active in the system. + +@item maximum_ports +is the maximum number of ports into +dual-port memory areas that can be concurrently active in the +system. + +@item number_of_initialization_tasks +is the number of initialization tasks configured. At least one +initialization task must be configured. + +@item User_initialization_tasks_table +is the address of the Initialization Task Table. This table contains the +information needed to create and start each of the +initialization tasks. The format of this table will be discussed below. + +@end table + +@ifinfo +@node Configuring a System POSIX API Configuration Table, Configuring a System CPU Dependent Information Table, Configuring a System RTEMS API Configuration Table, Configuring a System +@end ifinfo +@section POSIX API Configuration Table + +The POSIX API Configuration Table is used to configure the +managers which constitute the POSIX API for a particular application. +For example, the user can configure the maximum number of threads for +this application. The POSIX API Configuration Table is defined in +the following C structure: + +@example +@group +typedef struct @{ + void *(*entry)(void *); +@} posix_initialization_threads_table; + +typedef struct @{ + int maximum_threads; + int maximum_mutexes; + int maximum_condition_variables; + int maximum_keys; + int maximum_queued_signals; + int number_of_initialization_tasks; + posix_initialization_threads_table *User_initialization_tasks_table; +@} posix_api_configuration_table; +@end group +@end example + +@table @b +@item maximum_threads +is the maximum number of threads that +can be concurrently active (created) in the system including +initialization threads. + +@item maximum_mutexes +is the maximum number of mutexes that can be concurrently +active in the system. + +@item maximum_condition_variables +is the maximum number of condition variables that can be +concurrently active in the system. + +@item maximum_keys +is the maximum number of keys that can be concurrently active in the system. + +@item maximum_queued_signals +is the maximum number of queued signals that can be concurrently +pending in the system. + +@item number_of_initialization_threads +is the number of initialization threads configured. At least one +initialization threads must be configured. + +@item User_initialization_threads_table +is the address of the Initialization Threads Table. This table contains the +information needed to create and start each of the initialization threads. +The format of each entry in this table is defined in the +posix_initialization_threads_table structure. + +@end table + +@ifinfo +@node Configuring a System CPU Dependent Information Table, Configuring a System Initialization Task Table, Configuring a System POSIX API Configuration Table, Configuring a System +@end ifinfo +@section CPU Dependent Information Table + +The CPU Dependent Information Table is used to +describe processor dependent information required by RTEMS. +This table is generally used to supply RTEMS with information +only known by the Board Support Package. The contents of this +table are discussed in the CPU Dependent Information Table +chapter of the C Applications Supplement document for a specific +target processor. + +@ifinfo +@node Configuring a System Initialization Task Table, Configuring a System Driver Address Table, Configuring a System CPU Dependent Information Table, Configuring a System +@end ifinfo +@section Initialization Task Table + +The Initialization Task Table is used to describe +each of the user initialization tasks to the Initialization +Manager. The table contains one entry for each initialization +task the user wishes to create and start. The fields of this +data structure directly correspond to arguments to the +task_create and task_start directives. The number of entries is +found in the number_of_initialization_tasks entry in the +Configuration Table. The format of each entry in the +Initialization Task Table is defined in the following C +structure: + +@example +typedef struct @{ + rtems_name name; + rtems_unsigned32 stack_size; + rtems_task_priority initial_priority; + rtems_attribute attribute_set; + rtems_task_entry entry_point; + rtems_mode mode_set; + rtems_task_argument argument; +@} rtems_initialization_tasks_table; +@end example + +@table @b +@item name +is the name of this initialization task. + +@item stack_size +is the size of the stack for this initialization task. + +@item initial_priority +is the priority of this initialization task. + +@item attribute_set +is the attribute set used during creation of this initialization task. + +@item entry_point +is the address of the entry point of this initialization task. + +@item mode_set +is the initial execution mode of this initialization task. + +@item argument +is the initial argument for this initialization task. + +@end table + +A typical declaration for an Initialization Task Table might appear as follows: + +@example +rtems_initialization_tasks_table +Initialization_tasks[2] = @{ + @{ INIT_1_NAME, + 1024, + 1, + DEFAULT_ATTRIBUTES, + Init_1, + DEFAULT_MODES, + 1 + + @}, + @{ INIT_2_NAME, + 1024, + 250, + FLOATING_POINT, + Init_2, + INTERRUPT_LEVEL(0)|NO_PREEMPT, + 2 + + @} +@}; +@end example + +@ifinfo +@node Configuring a System Driver Address Table, Configuring a System User Extensions Table, Configuring a System Initialization Task Table, Configuring a System +@end ifinfo +@section Driver Address Table + +The Device Driver Table is used to inform the I/O +Manager of the set of entry points for each device driver +configured in the system. The table contains one entry for each +device driver required by the application. The number of +entries is defined in the number_of_device_drivers entry in the +Configuration Table. The format of each entry in the Device +Driver Table is defined in the following C structure: + +@example +typedef struct @{ + rtems_device_driver_entry initialization; + rtems_device_driver_entry open; + rtems_device_driver_entry close; + rtems_device_driver_entry read; + rtems_device_driver_entry write; + rtems_device_driver_entry control; +@} rtems_driver_address_table; +@end example + +@table @b +@item initialization +is the address of the entry point called by io_initialize +to initialize a device driver and its associated devices. + +@item open +is the address of the entry point called by io_open. + +@item close +is the address of the entry point called by io_close. + +@item read +is the address of the entry point called by io_read. + +@item write +is the address of the entry point called by io_write. + +@item control +is the address of the entry point called by io_control. + +@end table + +Driver entry points configured as NULL will always +return a status code of SUCCESSFUL. No user code will be +executed in this situation. + +A typical declaration for a Device Driver Table might appear as follows: + +@example +rtems_driver_address_table Driver_table[2] = @{ + @{ tty_initialize, tty_open, tty_close, /* major = 0 */ + tty_read, tty_write, tty_control + @}, + @{ lp_initialize, lp_open, lp_close, /* major = 1 */ + NULL, lp_write, lp_control + @} +@}; +@end example + +More information regarding the construction and +operation of device drivers is provided in the I/O Manager +chapter. + +@ifinfo +@node Configuring a System User Extensions Table, Configuring a System Multiprocessor Configuration Table, Configuring a System Driver Address Table, Configuring a System +@end ifinfo +@section User Extensions Table + +The User Extensions Table is used to inform RTEMS of +the optional user-supplied static extension set. This table +contains one entry for each possible extension. The entries are +called at critical times in the life of the system and +individual tasks. The application may create dynamic extensions +in addition to this single static set. The format of each entry +in the User Extensions Table is defined in the following C +structure: + +@example +typedef struct @{ + User_extensions_thread_create_extension thread_create; + User_extensions_thread_start_extension thread_start; + User_extensions_thread_restart_extension thread_restart; + User_extensions_thread_delete_extension thread_delete; + User_extensions_thread_switch_extension thread_switch; + User_extensions_thread_post_switch_extension thread_post_switch; + User_extensions_thread_begin_extension thread_begin; + User_extensions_thread_exitted_extension thread_exitted; + User_extensions_fatal_error_extension fatal; +@} User_extensions_Table; +@end example + +@table @b + +@item thread_create +is the address of the +user-supplied subroutine for the TASK_CREATE extension. If this +extension for task creation is defined, it is called from the +task_create directive. A value of NULL indicates that no +extension is provided. + +@item thread_start +is the address of the user-supplied +subroutine for the TASK_START extension. If this extension for +task initiation is defined, it is called from the task_start +directive. A value of NULL indicates that no extension is +provided. + +@item thread_restart +is the address of the user-supplied +subroutine for the TASK_RESTART extension. If this extension +for task re-initiation is defined, it is called from the +task_restart directive. A value of NULL indicates that no +extension is provided. + +@item thread_delete +is the address of the user-supplied +subroutine for the TASK_DELETE extension. If this RTEMS +extension for task deletion is defined, it is called from the +task_delete directive. A value of NULL indicates that no +extension is provided. + +@item thread_switch +is the address of the user-supplied +subroutine for the task context switch extension. This +subroutine is called from RTEMS dispatcher after the current +task has been swapped out but before the new task has been +swapped in. A value of NULL indicates that no extension is +provided. As this routine is invoked after saving the current +task's context and before restoring the heir task's context, it +is not necessary for this routine to save and restore any +registers. + +@item thread_post_switch +is the address of the +user-supplied subroutine for the post task context switch +extension. This subroutine is called from RTEMS dispatcher in +the context of the task which has just been swapped in. + +@item thread_begin +is the address of the user-supplied +subroutine which is invoked immediately before a task begins +execution. It is invoked in the context of the beginning task. +A value of NULL indicates that no extension is provided. + +@item thread_exitted +is the address of the user-supplied +subroutine which is invoked when a task exits. This procedure +is responsible for some action which will allow the system to +continue execution (i.e. delete or restart the task) or to +terminate with a fatal error. If this field is set to NULL, the +default RTEMS task_exitted handler will be invoked. + +@item fatal +is the address of the user-supplied +subroutine for the FATAL extension. This RTEMS extension of +fatal error handling is called from the fatal_error_occurred +directive. If the user's fatal error handler returns or if this +entry is NULL then the default RTEMS fatal error handler will be +executed. + +@end table + +A typical declaration for a User Extension Table +which defines the TASK_CREATE, TASK_DELETE, TASK_SWITCH, and +FATAL extension might appear as follows: + +@example +rtems_extensions_table User_extensions = @{ + task_create_extension, + NULL, + NULL, + task_delete_extension, + task_switch_extension, + NULL, + NULL, + fatal_extension +@}; +@end example + +More information regarding the user extensions is +provided in the User Extensions chapter. + +@ifinfo +@node Configuring a System Multiprocessor Configuration Table, Configuring a System Multiprocessor Communications Interface Table, Configuring a System User Extensions Table, Configuring a System +@end ifinfo +@section Multiprocessor Configuration Table + +The Multiprocessor Configuration Table contains +information needed when using RTEMS in a multiprocessor +configuration. Many of the details associated with configuring +a multiprocessor system are dependent on the multiprocessor +communications layer provided by the user. The address of the +Multiprocessor Configuration Table should be placed in the +User_multiprocessing_table entry in the primary Configuration +Table. Further details regarding many of the entries in the +Multiprocessor Configuration Table will be provided in the +Multiprocessing chapter. The format of the Multiprocessor +Configuration Table is defined in the following C structure: + +@example +typedef struct @{ + rtems_unsigned32 node; + rtems_unsigned32 maximum_nodes; + rtems_unsigned32 maximum_global_objects; + rtems_unsigned32 maximum_proxies; + rtems_mpci_table *User_mpci_table; +@} rtems_multiprocessing_table; +@end example + +@table @b +@item node +is a unique processor identifier +and is used in routing messages between nodes in a +multiprocessor configuration. Each processor must have a unique +node number. RTEMS assumes that node numbers start at one and +increase sequentially. This assumption can be used to advantage +by the user-supplied MPCI layer. Typically, this requirement is +made when the node numbers are used to calculate the address of +inter-processor communication links. Zero should be avoided as +a node number because some MPCI layers use node zero to +represent broadcasted packets. Thus, it is recommended that +node numbers start at one and increase sequentially. + +@item maximum_nodes +is the number of processor nodes in the system. + +@item maximum_global_objects +is the maximum number of global objects which can exist at any +given moment in the entire system. If this parameter is not the +same on all nodes in the system, then a fatal error is generated +to inform the user that the system is inconsistent. + +@item maximum_proxies +is the maximum number of proxies which can exist at any given moment +on this particular node. A proxy is a substitute task control block +which represent a task residing on a remote node when that task blocks +on a remote object. Proxies are used in situations in which delayed +interaction is required with a remote node. + +@item User_mpci_table +is the address of the Multiprocessor Communications Interface +Table. This table contains the entry points of user-provided functions +which constitute the multiprocessor communications layer. This table +must be provided in multiprocessor configurations with all +entries configured. The format of this table and details +regarding its entries can be found in the next section. + +@end table + +@ifinfo +@node Configuring a System Multiprocessor Communications Interface Table, Configuring a System Determining Memory Requirements, Configuring a System Multiprocessor Configuration Table, Configuring a System +@end ifinfo +@section Multiprocessor Communications Interface Table + +The format of this table is defined in the following C structure: + +@example +typedef struct @{ + rtems_unsigned32 default_timeout; /* in ticks */ + rtems_unsigned32 maximum_packet_size; + rtems_mpci_initialization_entry initialization; + rtems_mpci_get_packet_entry get_packet; + rtems_mpci_return_packet_entry return_packet; + rtems_mpci_send_entry send; + rtems_mpci_receive_entry receive; +@} rtems_mpci_table; +@end example + +@table @b +@item default_timeout +is the default maximum length of time a task should block waiting for +a response to a directive which results in communication with a remote node. +The maximum length of time is a function the user supplied +multiprocessor communications layer and the media used. This +timeout only applies to directives which would not block if the +operation were performed locally. + +@item maximum_packet_size +is the size in bytes of the longest packet which the MPCI layer is capable +of sending. This value should represent the total number of bytes available +for a RTEMS interprocessor messages. + +@item initialization +is the address of the entry point for the initialization procedure of the +user supplied multiprocessor communications layer. + +@item get_packet +is the address of the entry point for the procedure called by RTEMS to +obtain a packet from the user supplied multiprocessor communications layer. + +@item return_packet +is the address of the entry point for the procedure called by RTEMS to +return a packet to the user supplied multiprocessor communications layer. + +@item send +is the address of the entry point for the procedure called by RTEMS to +send an envelope to another node. This procedure is part of the user +supplied multiprocessor communications layer. + +@item receive +is the address of the entry point for the +procedure called by RTEMS to retrieve an envelope containing a +message from another node. This procedure is part of the user +supplied multiprocessor communications layer. + +@end table + +More information regarding the required functionality of these +entry points is provided in the Multiprocessor chapter. + +@ifinfo +@node Configuring a System Determining Memory Requirements, Configuring a System Sizing the RTEMS RAM Workspace, Configuring a System Multiprocessor Communications Interface Table, Configuring a System +@end ifinfo +@section Determining Memory Requirements + +Since memory is a critical resource in many real-time +embedded systems, RTEMS was specifically designed to allow +unused managers to be excluded from the run-time environment. +This allows the application designer the flexibility to tailor +RTEMS to most efficiently meet system requirements while still +satisfying even the most stringent memory constraints. As +result, the size of the RTEMS executive is application +dependent. A Memory Requirements worksheet is provided in the C +Applications Supplement document for a specific target +processor. This worksheet can be used to calculate the memory +requirements of a custom RTEMS run-time environment. To insure +that enough memory is allocated for future versions of RTEMS, +the application designer should round these memory requirements +up. The following managers may be optionally excluded: + +@itemize @bullet +@item signal +@item region +@item dual ported memory +@item event +@item multiprocessing +@item partition +@item timer +@item semaphore +@item message +@item rate monotonic +@end itemize + +RTEMS based applications must somehow provide memory +for RTEMS' code and data space. Although RTEMS' data space must +be in RAM, its code space can be located in either ROM or RAM. +In addition, the user must allocate RAM for the RTEMS RAM +Workspace. The size of this area is application dependent and +can be calculated using the formula provided in the Memory +Requirements chapter of the C Applications Supplement document +for a specific target processor. + +All RTEMS data variables and routine names used by +RTEMS begin with the underscore ( _ ) character followed by an +upper-case letter. If RTEMS is linked with an application, then +the application code should NOT contain any symbols which begin +with the underscore character and followed by an upper-case +letter to avoid any naming conflicts. All RTEMS directive names +should be treated as reserved words. + +@ifinfo +@node Configuring a System Sizing the RTEMS RAM Workspace, Multiprocessing Manager, Configuring a System Determining Memory Requirements, Configuring a System +@end ifinfo +@section Sizing the RTEMS RAM Workspace + +The RTEMS RAM Workspace is a user-specified block of +memory reserved for use by RTEMS. The application should NOT +modify this memory. This area consists primarily of the RTEMS +data structures whose exact size depends upon the values +specified in the Configuration Table. In addition, task stacks +and floating point context areas are dynamically allocated from +the RTEMS RAM Workspace. + +The starting address of the RTEMS RAM Workspace must +be aligned on a four-byte boundary. Failure to properly align +the workspace area will result in the fatal_error_occurred +directive being invoked with the INVALID_ADDRESS error code. + +A worksheet is provided in the Memory Requirements +chapter of the C Applications Supplement document for a specific +target processor to assist the user in calculating the minimum +size of the RTEMS RAM Workspace for each application. The value +calculated with this worksheet is the minimum value that should +be specified as the work_space_size parameter of the +Configuration Table. The user is cautioned that future versions +of RTEMS may not have the same memory requirements per object. +Although the value calculated is sufficient for a particular +target processor and release of RTEMS, memory usage is subject +to change across versions and target processors. The user is +advised to allocate somewhat more memory than the worksheet +recommends to insure compatibility with future releases for a +specific target processor and other target processors. To avoid +problems, the user should recalculate the memory requirements +each time one of the following events occurs: + +@itemize @bullet +@item a configuration parameter is modified, +@item task or interrupt stack requirements change, +@item task floating point attribute is altered, +@item RTEMS is upgraded, or +@item the target processor is changed. +@end itemize + +Failure to provide enough space in the RTEMS RAM +Workspace will result in the fatal_error_occurred directive +being invoked with the appropriate error code. diff --git a/doc/user/dirstat.texi b/doc/user/dirstat.texi new file mode 100644 index 0000000000..b703ec5043 --- /dev/null +++ b/doc/user/dirstat.texi @@ -0,0 +1,40 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Directive Status Codes, Example Application, MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Top +@end ifinfo +@chapter Directive Status Codes +@table @b +@item @b{SUCCESSFUL} - successful completion +@item @b{TASK_EXITTED} - returned from a task +@item @b{MP_NOT_CONFIGURED} - multiprocessing not configured +@item @b{INVALID_NAME} - invalid object name +@item @b{INVALID_ID} - invalid object id +@item @b{TOO_MANY} - too many +@item @b{TIMEOUT} - timed out waiting +@item @b{OBJECT_WAS_DELETED} - object was deleted while waiting +@item @b{INVALID_SIZE} - invalid specified size +@item @b{INVALID_ADDRESS} - invalid address specified +@item @b{INVALID_NUMBER} - number was invalid +@item @b{NOT_DEFINED} - item not initialized +@item @b{RESOURCE_IN_USE} - resources outstanding +@item @b{UNSATISFIED} - request not satisfied +@item @b{INCORRECT_STATE} - task is in wrong state +@item @b{ALREADY_SUSPENDED} - task already in state +@item @b{ILLEGAL_ON_SELF} - illegal for calling task +@item @b{ILLEGAL_ON_REMOTE_OBJECT} - illegal for remote object +@item @b{CALLED_FROM_ISR} - invalid environment +@item @b{INVALID_PRIORITY} - invalid task priority +@item @b{INVALID_CLOCK} - invalid time buffer +@item @b{INVALID_NODE} - invalid node id +@item @b{NOT_CONFIGURED} - directive not configured +@item @b{NOT_OWNER_OF_RESOURCE} - not owner of resource +@item @b{NOT_IMPLEMENTED} - directive not implemented +@item @b{INTERNAL_ERROR} - RTEMS inconsistency detected +@item @b{NO_MEMORY} - could not get enough memory +@end table + diff --git a/doc/user/dpmem.t b/doc/user/dpmem.t new file mode 100644 index 0000000000..9432323b02 --- /dev/null +++ b/doc/user/dpmem.t @@ -0,0 +1,324 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Dual-Ported Memory Manager, Dual-Ported Memory Manager Introduction, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Top +@end ifinfo +@chapter Dual-Ported Memory Manager +@ifinfo +@menu +* Dual-Ported Memory Manager Introduction:: +* Dual-Ported Memory Manager Background:: +* Dual-Ported Memory Manager Operations:: +* Dual-Ported Memory Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager, Dual-Ported Memory Manager +@end ifinfo +@section Introduction + +The dual-ported memory manager provides a mechanism +for converting addresses between internal and external +representations for multiple dual-ported memory areas (DPMA). +The directives provided by the dual-ported memory manager are: + +@itemize @bullet +@item @code{port_create} - Create a port +@item @code{port_ident} - Get ID of a port +@item @code{port_delete} - Delete a port +@item @code{port_external_to_internal} - Convert external to internal address +@item @code{port_internal_to_external} - Convert internal to external address +@end itemize + +@ifinfo +@node Dual-Ported Memory Manager Background, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager +@end ifinfo +@section Background + +A dual-ported memory area (DPMA) is an contiguous +block of RAM owned by a particular processor but which can be +accessed by other processors in the system. The owner accesses +the memory using internal addresses, while other processors must +use external addresses. RTEMS defines a port as a particular +mapping of internal and external addresses. + +There are two system configurations in which +dual-ported memory is commonly found. The first is +tightly-coupled multiprocessor computer systems where the +dual-ported memory is shared between all nodes and is used for +inter-node communication. The second configuration is computer +systems with intelligent peripheral controllers. These +controllers typically utilize the DPMA for high-performance data +transfers. + +@ifinfo +@node Dual-Ported Memory Manager Operations, Creating a Port, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Port:: +* Obtaining Port IDs:: +* Converting an Address:: +* Deleting a DPMA Port:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Creating a Port + +The port_create directive creates a port into a DPMA +with the user-defined name. The user specifies the association +between internal and external representations for the port being +created. RTEMS allocates a Dual-Ported Memory Control Block +(DPCB) from the DPCB free list to maintain the newly created +DPMA. RTEMS also generates a unique dual-ported memory port ID +which is returned to the calling task. RTEMS does not +initialize the dual-ported memory area or access any memory +within it. + +@ifinfo +@node Obtaining Port IDs, Converting an Address, Creating a Port, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Obtaining Port IDs + +When a port is created, RTEMS generates a unique port +ID and assigns it to the created port until it is deleted. The +port ID may be obtained by either of two methods. First, as the +result of an invocation of the port_create directive, the task +ID is stored in a user provided location. Second, the port ID +may be obtained later using the port_ident directive. The port +ID is used by other dual-ported memory manager directives to +access this port. + +@ifinfo +@node Converting an Address, Deleting a DPMA Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Converting an Address + +The port_external_to_internal directive is used to +convert an address from external to internal representation for +the specified port. The port_internal_to_external directive is +used to convert an address from internal to external +representation for the specified port. If an attempt is made to +convert an address which lies outside the specified DPMA, then +the address to be converted will be returned. + +@ifinfo +@node Deleting a DPMA Port, Dual-Ported Memory Manager Directives, Converting an Address, Dual-Ported Memory Manager Operations +@end ifinfo +@subsection Deleting a DPMA Port + +A port can be removed from the system and returned to +RTEMS with the port_delete directive. When a port is deleted, +its control block is returned to the DPCB free list. + +@ifinfo +@node Dual-Ported Memory Manager Directives, PORT_CREATE - Create a port, Deleting a DPMA Port, Dual-Ported Memory Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* PORT_CREATE - Create a port:: +* PORT_IDENT - Get ID of a port:: +* PORT_DELETE - Delete a port:: +* PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address:: +* PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address:: +@end menu +@end ifinfo + +This section details the dual-ported memory manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node PORT_CREATE - Create a port, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_CREATE - Create a port + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + rtems_unsigned32 length, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - port created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_ADDRESS} - address not on four byte boundary@* +@code{TOO_MANY} - too many DP memory areas created + +@subheading DESCRIPTION: + +This directive creates a port which resides on the +local node for the specified DPMA. The assigned port id is +returned in id. This port id is used as an argument to other +dual-ported memory manager directives to convert addresses +within this DPMA. + +For control and maintenance of the port, RTEMS +allocates and initializes an DPCB from the DPCB free pool. Thus +memory from the dual-ported memory area is not used to store the +DPCB. + +@subheading NOTES: + +The internal_address and external_address parameters +must be on a four byte boundary. + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node PORT_IDENT - Get ID of a port, PORT_DELETE - Delete a port, PORT_CREATE - Create a port, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_IDENT - Get ID of a port + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - port identified successfully@* +@code{INVALID_NAME} - port name not found + +@subheading DESCRIPTION: + +This directive obtains the port id associated with +the specified name to be acquired. If the port name is not +unique, then the port id will match one of the DPMAs with that +name. However, this port id is not guaranteed to correspond to +the desired DPMA. The port id is used to access this DPMA in +other dual-ported memory area related directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node PORT_DELETE - Delete a port, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_DELETE - Delete a port + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - port deleted successfully@* +@code{INVALID_ID} - invalid port id + +@subheading DESCRIPTION: + +This directive deletes the dual-ported memory area +specified by id. The DPCB for the deleted dual-ported memory +area is reclaimed by RTEMS. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The calling task does not have to be the task that +created the port. Any local task that knows the port id can +delete the port. + +@page +@ifinfo +@node PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, PORT_DELETE - Delete a port, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: + +This directive converts a dual-ported memory address +from external to internal representation for the specified port. +If the given external address is invalid for the specified +port, then the internal address is set to the given external +address. + +@subheading NOTES: + +This directive is callable from an ISR. + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, I/O Manager, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, Dual-Ported Memory Manager Directives +@end ifinfo +@subsection PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: + +This directive converts a dual-ported memory address +from internal to external representation so that it can be +passed to owner of the DPMA represented by the specified port. +If the given internal address is an invalid dual-ported address, +then the external address is set to the given internal address. + +@subheading NOTES: + +This directive is callable from an ISR. + +This directive will not cause the calling task to be +preempted. + + + + + diff --git a/doc/user/event.t b/doc/user/event.t new file mode 100644 index 0000000000..0ec198a5c0 --- /dev/null +++ b/doc/user/event.t @@ -0,0 +1,351 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Event Manager, Event Manager Introduction, MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, Top +@end ifinfo +@chapter Event Manager +@ifinfo +@menu +* Event Manager Introduction:: +* Event Manager Background:: +* Event Manager Operations:: +* Event Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Event Manager Introduction, Event Manager Background, Event Manager, Event Manager +@end ifinfo +@section Introduction + +The event manager provides a high performance method +of intertask communication and synchronization. The directives +provided by the event manager are: + +@itemize @bullet +@item @code{event_send} - Send event set to a task +@item @code{event_receive} - Receive event condition +@end itemize + +@ifinfo +@node Event Manager Background, Event Sets, Event Manager Introduction, Event Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Event Sets:: +* Building an Event Set or Condition:: +* Building an EVENT_RECEIVE Option Set:: +@end menu +@end ifinfo + +@ifinfo +@node Event Sets, Building an Event Set or Condition, Event Manager Background, Event Manager Background +@end ifinfo +@subsection Event Sets + +An event flag is used by a task (or ISR) to inform +another task of the occurrence of a significant situation. +Thirty-two event flags are associated with each task. A +collection of one or more event flags is referred to as an event +set. The application developer should remember the following +key characteristics of event operations when utilizing the event +manager: + +@itemize @bullet +@item Events provide a simple synchronization facility. + +@item Events are aimed at tasks. + +@item Tasks can wait on more than one event simultaneously. + +@item Events are independent of one another. + +@item Events do not hold or transport data. + +@item Events are not queued. In other words, if an event is +sent more than once before being received, the second and +subsequent send operations have no effect. +@end itemize + +An event set is posted when it is directed (or sent) +to a task. A pending event is an event that has been posted but +not received. An event condition is used to specify the events +which the task desires to receive and the algorithm which will +be used to determine when the request is satisfied. An event +condition is satisfied based upon one of two algorithms which +are selected by the user. The EVENT_ANY algorithm states that +an event condition is satisfied when at least a single requested +event is posted. The EVENT_ALL algorithm states that an event +condition is satisfied when every requested event is posted. + +@ifinfo +@node Building an Event Set or Condition, Building an EVENT_RECEIVE Option Set, Event Sets, Event Manager Background +@end ifinfo +@subsection Building an Event Set or Condition + +An event set or condition is built by a bitwise OR of +the desired events. The set of valid events is EVENT_0 through +EVENT_31. If an event is not explicitly specified in the set or +condition, then it is not present. Events are specifically +designed to be mutually exclusive, therefore bitwise OR and +addition operations are equivalent as long as each event appears +exactly once in the event set list. + +For example, when sending the event set consisting of +EVENT_6, EVENT_15, and EVENT_31, the event parameter to the +event_send directive should be EVENT_6 | EVENT_15 | EVENT_31. + +@ifinfo +@node Building an EVENT_RECEIVE Option Set, Event Manager Operations, Building an Event Set or Condition, Event Manager Background +@end ifinfo +@subsection Building an EVENT_RECEIVE Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +event_receive directive are listed in the following table: + +@itemize @bullet +@item WAIT - task will wait for event (default) +@item NO_WAIT - task should not wait +@item EVENT_ALL - return after all events (default) +@item EVENT_ANY - return after any events +@end itemize + +Option values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each option appears exactly once in +the component list. An option listed as a default is not +required to appear in the option list, although it is a good +programming practice to specify default options. If all +defaults are desired, the option DEFAULT_OPTIONS should be +specified on this call. + +This example demonstrates the option parameter needed +to poll for all events in a particular event condition to +arrive. The option parameter passed to the event_receive +directive should be either EVENT_ALL | NO_WAIT or NO_WAIT. The +option parameter can be set to NO_WAIT because EVENT_ALL is the +default condition for event_receive. + +@ifinfo +@node Event Manager Operations, Sending an Event Set, Building an EVENT_RECEIVE Option Set, Event Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Sending an Event Set:: +* Receiving an Event Set:: +* Determining the Pending Event Set:: +* Receiving all Pending Events:: +@end menu +@end ifinfo + +@ifinfo +@node Sending an Event Set, Receiving an Event Set, Event Manager Operations, Event Manager Operations +@end ifinfo +@subsection Sending an Event Set + +The event_send directive allows a task (or an ISR) to +direct an event set to a target task. Based upon the state of +the target task, one of the following situations applies: + +@itemize @bullet +@item Target Task is Blocked Waiting for Events + +@itemize - + +@item If the waiting task's input event condition is +satisfied, then the task is made ready for execution. + +@item If the waiting task's input event condition is not +satisfied, then the event set is posted but left pending and the +task remains blocked. + +@end itemize + +@item Target Task is Not Waiting for Events + +@itemize - +@item The event set is posted and left pending. +@end itemize + +@end itemize + +@ifinfo +@node Receiving an Event Set, Determining the Pending Event Set, Sending an Event Set, Event Manager Operations +@end ifinfo +@subsection Receiving an Event Set + +The event_receive directive is used by tasks to +accept a specific input event condition. The task also +specifies whether the request is satisfied when all requested +events are available or any single requested event is available. +If the requested event condition is satisfied by pending +events, then a successful return code and the satisfying event +set are returned immediately. If the condition is not +satisfied, then one of the following situations applies: + +@itemize @bullet +@item By default, the calling task will wait forever for the +event condition to be satisfied. + +@item Specifying the NO_WAIT option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the period the task will +wait before returning with an error status code. +@end itemize + +@ifinfo +@node Determining the Pending Event Set, Receiving all Pending Events, Receiving an Event Set, Event Manager Operations +@end ifinfo +@subsection Determining the Pending Event Set + +A task can determine the pending event set by calling +the event_receive directive with a value of PENDING_EVENTS for +the input event condition. The pending events are returned to +the calling task but the event set is left unaltered. + +@ifinfo +@node Receiving all Pending Events, Event Manager Directives, Determining the Pending Event Set, Event Manager Operations +@end ifinfo +@subsection Receiving all Pending Events + +A task can receive all of the currently pending +events by calling the event_receive directive with a value of +ALL_EVENTS for the input event condition and NO_WAIT | EVENT_ANY +for the option set. The pending events are returned to the +calling task and the event set is cleared. If no events are +pending then the UNSATISFIED status code will be returned. + +@ifinfo +@node Event Manager Directives, EVENT_SEND - Send event set to a task, Receiving all Pending Events, Event Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* EVENT_SEND - Send event set to a task:: +* EVENT_RECEIVE - Receive event condition:: +@end menu +@end ifinfo + +This section details the event manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node EVENT_SEND - Send event set to a task, EVENT_RECEIVE - Receive event condition, Event Manager Directives, Event Manager Directives +@end ifinfo +@subsection EVENT_SEND - Send event set to a task + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_event_send ( + rtems_id id, + rtems_event_set event_in +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - event set sent successfully@* +@code{INVALID_ID} - invalid task id + +@subheading DESCRIPTION: + +This directive sends an event set, event_in, to the +task specified by id. If a blocked task's input event condition +is satisfied by this directive, then it will be made ready. If +its input event condition is not satisfied, then the events +satisfied are updated and the events not satisfied are left +pending. If the task specified by id is not blocked waiting for +events, then the events sent are left pending. + +@subheading NOTES: + +Specifying SELF for id results in the event set being +sent to the calling task. + +Identical events sent to a task are not queued. In +other words, the second, and subsequent, posting of an event to +a task before it can perform an event_receive has no effect. + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +Sending an event set to a global task which does not +reside on the local node will generate a request telling the +remote node to send the event set to the appropriate task. + +@page +@ifinfo +@node EVENT_RECEIVE - Receive event condition, Signal Manager, EVENT_SEND - Send event set to a task, Event Manager Directives +@end ifinfo +@subsection EVENT_RECEIVE - Receive event condition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_event_receive ( + rtems_event_set event_in, + rtems_option option_set, + rtems_interval ticks, + rtems_event_set *event_out +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - event received successfully@* +@code{UNSATISFIED} - input event not satisfied (NO_WAIT)@* +@code{TIMEOUT} - timed out waiting for event + +@subheading DESCRIPTION: + +This directive attempts to receive the event +condition specified in event_in. If event_in is set to +PENDING_EVENTS, then the current pending events are returned in +event_out and left pending. The WAIT and NO_WAIT options in the +option_set parameter are used to specify whether or not the task +is willing to wait for the event condition to be satisfied. +EVENT_ANY and EVENT_ALL are used in the option_set parameter are +used to specify whether a single event or the complete event set +is necessary to satisfy the event condition. The event_out +parameter is returned to the calling task with the value that +corresponds to the events in event_in that were satisfied. + +If pending events satisfy the event condition, then +event_out is set to the satisfied events and the pending events +in the event condition are cleared. If the event condition is +not satisfied and NO_WAIT is specified, then event_out is set to +the currently satisfied events. If the calling task chooses to +wait, then it will block waiting for the event condition. + +If the calling task must wait for the event condition +to be satisfied, then the timeout parameter is used to specify +the maximum interval to wait. If it is set to NO_TIMEOUT, then +the calling task will wait forever. + +@subheading NOTES: + +This directive only affects the events specified in +event_in. Any pending events that do not correspond to any of +the events specified in event_in will be left pending. + +The following event receive option constants are defined by +RTEMS: + +@itemize @bullet +@item WAIT task will wait for event (default) +@item NO_WAIT task should not wait +@item EVENT_ALL return after all events (default) +@item EVENT_ANY return after any events +@end itemize + diff --git a/doc/user/example.texi b/doc/user/example.texi new file mode 100644 index 0000000000..545cf8e8f4 --- /dev/null +++ b/doc/user/example.texi @@ -0,0 +1,103 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Example Application, Glossary, Directive Status Codes, Top +@end ifinfo +@chapter Example Application + +@example +/* example.c + * + * This file contains an example of a simple RTEMS + * application. It contains a Configuration Table, a + * user initialization task, and a simple task. + * + * This example assumes that a board support package exists + * and invokes the initialize_executive() directive. + */ + +#include "rtems.h" + +rtems_task init_task(); + +#define INIT_NAME build_name( 'A', 'B', 'C', ' ' ' ) + +rtems_initialization_tasks_table init_task = @{ + @{ INIT_NAME, /* init task name "ABC" */ + 1024, /* init task stack size */ + 1, /* init task priority */ + DEFAULT_ATTRIBUTES, /* init task attributes */ + init_task, /* init task entry point */ + TIMESLICE, /* init task initial mode */ + 0 /* init task argument */ + @} +@}; + +rtems_configuration_table User_Configuration_Table = @{ + NULL, /* filled in by the BSP */ + 65536, /* executive RAM size */ + 2, /* maximum tasks */ + 0, /* maximum timers */ + 0, /* maximum semaphores */ + 0, /* maximum message queues */ + 0, /* maximum messages */ + 0, /* maximum partitions */ + 0, /* maximum regions */ + 0, /* maximum ports */ + 0, /* maximum periods */ + 0, /* maximum extensions */ + RTEMS_MILLISECONDS_TO_MICROSECONDS(10), /* number of ms in a tick */ + 1, /* num of ticks in a timeslice */ + 1, /* number of user init tasks */ + init_task_tbl, /* user init task(s) table */ + 0, /* number of device drivers */ + NULL, /* ptr to driver address table */ + NULL, /* ptr to extension table */ + NULL /* ptr to MP config table */ +@}; + +task user_application( + rtems_task_argument ignored +); + +#define USER_APP_NAME 1 /* any 32-bit name; unique helps */ + +rtems_task init_task( + rtems_task_argument ignored +) +@{ + rtems_id tid; + + /* example assumes SUCCESSFUL return value */ + + (void) rtems_task_create( USER_APP_NAME, 1, 1024, + RTEMS_NO_PREEMPT, RTEMS_FLOATING_POINT, &tid ); + (void) rtems_task_start( tid, user_application, 0 ); + (void) rtems_task_delete( SELF ); +@} + + + +rtems_task user_application() + +@{ + /* application specific initialization goes here */ + + while ( 1 ) @{ /* infinite loop */ + + /* APPLICATION CODE GOES HERE + * + * This code will typically include at least one + * directive which causes the calling task to + * give up the processor. + */ + @} +@} +@end example + + + diff --git a/doc/user/fatal.t b/doc/user/fatal.t new file mode 100644 index 0000000000..4f15684195 --- /dev/null +++ b/doc/user/fatal.t @@ -0,0 +1,180 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Fatal Error Manager, Fatal Error Manager Introduction, IO_CONTROL - Special device services, Top +@end ifinfo +@chapter Fatal Error Manager +@ifinfo +@menu +* Fatal Error Manager Introduction:: +* Fatal Error Manager Background:: +* Fatal Error Manager Operations:: +* Fatal Error Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Fatal Error Manager Introduction, Fatal Error Manager Background, Fatal Error Manager, Fatal Error Manager +@end ifinfo +@section Introduction + +The fatal error manager processes all fatal or +irrecoverable errors. The directive provided by the fatal error +manager is: + +@itemize @bullet +@item @code{fatal_error_occurred} - Invoke the fatal error handler +@end itemize + + + +@ifinfo +@node Fatal Error Manager Background, Fatal Error Manager Operations, Fatal Error Manager Introduction, Fatal Error Manager +@end ifinfo +@section Background + +The fatal error manager is called upon detection of +an irrecoverable error condition by either RTEMS or the +application software. Fatal errors can be detected from three +sources: + +@itemize @bullet +@item the executive (RTEMS) +@item user system code +@item user application code +@end itemize + +RTEMS automatically invokes the fatal error manager +upon detection of an error it considers to be fatal. Similarly, +the user should invoke the fatal error manager upon detection of +a fatal error. + +Each status or dynamic user extension set may include +a fatal error handler. The fatal error handler in the static +extension set can be used to provide access to debuggers and +monitors which may be present on the target hardware. If any +user-supplied fatal error handlers are installed, the fatal +error manager will invoke them. If no user handlers are +configured or if all the user handler return control to the +fatal error manager, then the RTEMS default fatal error handler +is invoked. If the default fatal error handler is invoked, then +the system state is marked as failed. + +Although the precise behavior of the default fatal +error handler is processor specific, in general, it will disable +all maskable interrupts, place the error code in a known +processor dependent place (generally either on the stack or in a +register), and halt the processor. The precise actions of the +RTEMS fatal error are discussed in the Default Fatal Error +Processing chapter of the C Applications Supplement document for +a specific target processor. + +@ifinfo +@node Fatal Error Manager Operations, Announcing a Fatal Error, Fatal Error Manager Background, Fatal Error Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Fatal Error:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Fatal Error, Fatal Error Manager Directives, Fatal Error Manager Operations, Fatal Error Manager Operations +@end ifinfo +@subsection Announcing a Fatal Error + +The fatal_error_occurred directive is invoked when a +fatal error is detected. Before invoking any user-supplied +fatal error handlers or the RTEMS fatal error handler, the +fatal_error_occurred directive stores useful information in the +variable _Internal_errors_What_happened. This structure +contains three pieces of information: + +@itemize @bullet +@item the source of the error (API or executive core), + +@item whether the error was generated internally by the +executive, and a + +@item a numeric code to indicate the error type. +@end itemize + +The error type indicator is dependent on the source +of the error and whether or not the error was internally +generated by the executive. + +The fatal_error_directive directive is responsible +for invoking an optional user-supplied fatal error handler +and/or the RTEMS fatal error handler. All fatal error handlers +are passed an error code to describe the error detected. + +Occasionally, an application requires more +sophisticated fatal error processing such as passing control to +a debugger. For these cases, a user-supplied fatal error +handler can be specified in the RTEMS configuration table. The +User Extension Table field fatal contains the address of the +fatal error handler to be executed when the fatal_error_occurred +directive is called. If the field is set to NULL or if the +configured fatal error handler returns to the executive, then +the default handler provided by RTEMS is executed. This default +handler will halt execution on the processor where the error +occurred. + +@ifinfo +@node Fatal Error Manager Directives, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Announcing a Fatal Error, Fatal Error Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* FATAL_ERROR_OCCURRED - Invoke the fatal error handler:: +@end menu +@end ifinfo + +This section details the fatal error manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Scheduling Concepts, Fatal Error Manager Directives, Fatal Error Manager Directives +@end ifinfo +@subsection FATAL_ERROR_OCCURRED - Invoke the fatal error handler + +@subheading CALLING SEQUENCE: + +@example +void volatile rtems_fatal_error_occurred( + rtems_unsigned32 the_error +); +@end example + +@subheading DIRECTIVE STATUS CODES + +NONE + +@subheading DESCRIPTION: + +This directive processes fatal errors. If the FATAL +error extension is defined in the configuration table, then the +user-defined error extension is called. If configured and the +provided FATAL error extension returns, then the RTEMS default +error handler is invoked. This directive can be invoked by +RTEMS or by the user's application code including initialization +tasks, other tasks, and ISRs. + +@subheading NOTES: + +This directive supports local operations only. + +Unless the user-defined error extension takes special +actions such as restarting the calling task, this directive WILL +NOT RETURN to the caller. + +The user-defined extension for this directive may +wish to initiate a global shutdown. diff --git a/doc/user/glossary.texi b/doc/user/glossary.texi new file mode 100644 index 0000000000..58b57061f0 --- /dev/null +++ b/doc/user/glossary.texi @@ -0,0 +1,772 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Glossary, Command and Variable Index, Example Application, Top +@end ifinfo +@chapter Glossary + +@table @b +@item active +A term used to describe an object +which has been created by an application. + +@item aperiodic task +A task which must execute only at +irregular intervals and has only a soft deadline. + +@item application +In this document, software which makes +use of RTEMS. + +@item ASR +see Asynchronous Signal Routine. + +@item asynchronous +Not related in order or timing to +other occurrences in the system. + +@item Asynchronous Signal Routine +Similar to a hardware +interrupt except that it is associated with a task and is run in +the context of a task. The directives provided by the signal +manager are used to service signals. + +@item awakened +A term used to describe a task that has +been unblocked and may be scheduled to the CPU. + +@item big endian +A data representation scheme in which +the bytes composing a numeric value are arranged such that the +most significant byte is at the lowest address. + +@item bit-mapped +A data encoding scheme in which each bit +in a variable is used to represent something different. This +makes for compact data representation. + +@item block +A physically contiguous area of memory. + +@item blocked +The task state entered by a task which has +been previously started and cannot continue execution until the +reason for waiting has been satisfied. + +@item broadcast +To simultaneously send a message to a +logical set of destinations. + +@item BSP +see Board Support Package. + +@item Board Support Package +A collection of device +initialization and control routines specific to a particular +type of board or collection of boards. + +@item buffer +A fixed length block of memory allocated +from a partition. + +@item calling convention +The processor and compiler +dependent rules which define the mechanism used to invoke +subroutines in a high-level language. These rules define the +passing of arguments, the call and return mechanism, and the +register set which must be preserved. + +@item Central Processing Unit +This term is equivalent to +the terms processor and microprocessor. + +@item chain +A data structure which allows for efficient +dynamic addition and removal of elements. It differs from an +array in that it is not limited to a predefined size. + +@item coalesce +The process of merging adjacent holes into +a single larger hole. Sometimes this process is referred to as +garbage collection. + +@item Configuration Table +A table which contains +information used to tailor RTEMS for a particular application. + +@item context +All of the processor registers and +operating system data structures associated with a task. + +@item context switch +Alternate term for task switch. +Taking control of the processor from one task and transferring +it to another task. + +@item control block +A data structure used by the +executive to define and control an object. + +@item core +When used in this manual, this term refers to +the internal executive utility functions. In the interest of +application portability, the core of the executive should not be +used directly by applications. + +@item CPU +An acronym for Central Processing Unit. + +@item critical section +A section of code which must be +executed indivisibly. + +@item CRT +An acronym for Cathode Ray Tube. Normally used +in reference to the man-machine interface. + +@item deadline +A fixed time limit by which a task must +have completed a set of actions. Beyond this point, the results +are of reduced value and may even be considered useless or +harmful. + +@item device +A peripheral used by the application that +requires special operation software. See also device driver. + +@item device driver +Control software for special +peripheral devices used by the application. + +@item directives +RTEMS' provided routines that provide +support mechanisms for real-time applications. + +@item dispatch +The act of loading a task's context onto +the CPU and transferring control of the CPU to that task. + +@item dormant +The state entered by a task after it is +created and before it has been started. + +@item Device Driver Table +A table which contains the +entry points for each of the configured device drivers. + +@item dual-ported +A term used to describe memory which +can be accessed at two different addresses. + +@item embedded +An application that is delivered as a +hidden part of a larger system. For example, the software in a +fuel-injection control system is an embedded application found +in many late-model automobiles. + +@item envelope +A buffer provided by the MPCI layer to +RTEMS which is used to pass messages between nodes in a +multiprocessor system. It typically contains routing +information needed by the MPCI. The contents of an envelope are +referred to as a packet. + +@item entry point +The address at which a function or task +begins to execute. In C, the entry point of a function is the +function's name. + +@item events +A method for task communication and +synchronization. The directives provided by the event manager +are used to service events. + +@item exception +A synonym for interrupt. + +@item executing +The task state entered by a task after it +has been given control of the CPU. + +@item executive +In this document, this term is used to +referred to RTEMS. Commonly, an executive is a small real-time +operating system used in embedded systems. + +@item exported +An object known by all nodes in a +multiprocessor system. An object created with the GLOBAL +attribute will be exported. + +@item external address +The address used to access +dual-ported memory by all the nodes in a system which do not own +the memory. + +@item FIFO +An acronym for First In First Out. + +@item First In First Out +A discipline for manipulating +entries in a data structure. + +@item floating point coprocessor +A component used in +computer systems to enhance performance in mathematically +intensive situations. It is typically viewed as a logical +extension of the primary processor. + +@item freed +A resource that has been released by the +application to RTEMS. + +@item global +An object that has been created with the +GLOBAL attribute and exported to all nodes in a multiprocessor +system. + +@item handler +The equivalent of a manager, except that it +is internal to RTEMS and forms part of the core. A handler is a +collection of routines which provide a related set of functions. +For example, there is a handler used by RTEMS to manage all +objects. + +@item hard real-time system +A real-time system in which a +missed deadline causes the worked performed to have no value or +to result in a catastrophic effect on the integrity of the +system. + +@item heap +A data structure used to dynamically allocate +and deallocate variable sized blocks of memory. + +@item heterogeneous +A multiprocessor computer system +composed of dissimilar processors. + +@item homogeneous +A multiprocessor computer system +composed of a single type of processor. + +@item ID +An RTEMS assigned identification tag used to +access an active object. + +@item IDLE task +A special low priority task which assumes +control of the CPU when no other task is able to execute. + +@item interface +A specification of the methodology used +to connect multiple independent subsystems. + +@item internal address +The address used to access +dual-ported memory by the node which owns the memory. + +@item interrupt +A hardware facility that causes the CPU +to suspend execution, save its status, and transfer control to a +specific location. + +@item interrupt level +A mask used to by the CPU to +determine which pending interrupts should be serviced. If a +pending interrupt is below the current interrupt level, then the +CPU does not recognize that interrupt. + +@item Interrupt Service Routine +An ISR is invoked by the +CPU to process a pending interrupt. + +@item I/O +An acronym for Input/Output. + +@item ISR +An acronym for Interrupt Service Routine. + +@item kernel +In this document, this term is used as a +synonym for executive. + +@item list +A data structure which allows for dynamic +addition and removal of entries. It is not statically limited +to a particular size. + +@item little endian +A data representation scheme in which +the bytes composing a numeric value are arranged such that the +least significant byte is at the lowest address. + +@item local +An object which was created with the LOCAL +attribute and is accessible only on the node it was created and +resides upon. In a single processor configuration, all objects +are local. + +@item local operation +The manipulation of an object which +resides on the same node as the calling task. + +@item logical address +An address used by an application. +In a system without memory management, logical addresses will +equal physical addresses. + +@item loosely-coupled +A multiprocessor configuration +where shared memory is not used for communication. + +@item major number +The index of a device driver in the +Device Driver Table. + +@item manager +A group of related RTEMS' directives which +provide access and control over resources. + +@item memory pool +Used interchangeably with heap. + +@item message +A sixteen byte entity used to communicate +between tasks. Messages are sent to message queues and stored +in message buffers. + +@item message buffer +A block of memory used to store +messages. + +@item message queue +An RTEMS object used to synchronize +and communicate between tasks by transporting messages between +sending and receiving tasks. + +@item Message Queue Control Block +A data structure +associated with each message queue used by RTEMS to manage that +message queue. + +@item minor number +A numeric value passed to a device +driver, the exact usage of which is driver dependent. + +@item mode +An entry in a task's control block that is +used to determine if the task allows preemption, timeslicing, +processing of signals, and the interrupt disable level used by +the task. + +@item MPCI +An acronym for Multiprocessor Communications +Interface Layer. + +@item multiprocessing +The simultaneous execution of two +or more processes by a multiple processor computer system. + +@item multiprocessor +A computer with multiple CPUs +available for executing applications. + +@item Multiprocessor Communications Interface Layer +A set +of user-provided routines which enable the nodes in a +multiprocessor system to communicate with one another. + +@item Multiprocessor Configuration Table +The data +structure defining the characteristics of the multiprocessor +target system with which RTEMS will communicate. + +@item multitasking +The alternation of execution amongst a +group of processes on a single CPU. A scheduling algorithm is +used to determine which process executes at which time. + +@item mutual exclusion +A term used to describe the act of +preventing other tasks from accessing a resource simultaneously. + +@item nested +A term used to describe an ASR that occurs +during another ASR or an ISR that occurs during another ISR. + +@item node +A term used to reference a processor running +RTEMS in a multiprocessor system. + +@item non-existent +The state occupied by an uncreated or +deleted task. + +@item numeric coprocessor +A component used in computer +systems to enhance performance in mathematically intensive +situations. It is typically viewed as a logical extension of +the primary processor. + +@item object +In this document, this term is used to refer +collectively to tasks, timers, message queues, partitions, +regions, semaphores, ports, and rate monotonic periods. All +RTEMS objects have IDs and user-assigned names. + +@item object-oriented +A term used to describe systems +with common mechanisms for utilizing a variety of entities. +Object-oriented systems shield the application from +implementation details. + +@item operating system +The software which controls all +the computer's resources and provides the base upon which +application programs can be written. + +@item overhead +The portion of the CPUs processing power +consumed by the operating system. + +@item packet +A buffer which contains the messages passed +between nodes in a multiprocessor system. A packet is the +contents of an envelope. + +@item partition +An RTEMS object which is used to allocate +and deallocate fixed size blocks of memory from an dynamically +specified area of memory. + +@item Partition Control Block +A data structure associated +with each partition used by RTEMS to manage that partition. + +@item pending +A term used to describe a task blocked +waiting for an event, message, semaphore, or signal. + +@item periodic task +A task which must execute at regular +intervals and comply with a hard deadline. + +@item physical address +The actual hardware address of a +resource. + +@item poll +A mechanism used to determine if an event has +occurred by periodically checking for a particular status. +Typical events include arrival of data, completion of an action, +and errors. + +@item pool +A collection from which resources are +allocated. + +@item portability +A term used to describe the ease with +which software can be rehosted on another computer. + +@item posting +The act of sending an event, message, +semaphore, or signal to a task. + +@item preempt +The act of forcing a task to relinquish the +processor and dispatching to another task. + +@item priority +A mechanism used to represent the relative +importance of an element in a set of items. RTEMS uses priority +to determine which task should execute. + +@item priority inheritance +An algorithm that calls for +the lower priority task holding a resource to have its priority +increased to that of the highest priority task blocked waiting +for that resource. This avoids the problem of priority +inversion. + +@item priority inversion +A form of indefinite +postponement which occurs when a high priority tasks requests +access to shared resource currently allocated to low priority +task. The high priority task must block until the low priority +task releases the resource. + +@item processor utilization +The percentage of processor +time used by a task or a set of tasks. + +@item proxy +An RTEMS control structure used to represent, +on a remote node, a task which must block as part of a remote +operation. + +@item Proxy Control Block +A data structure associated +with each proxy used by RTEMS to manage that proxy. + +@item PTCB +An acronym for Partition Control Block. + +@item PXCB +An acronym for Proxy Control Block. + +@item quantum +The application defined unit of time in +which the processor is allocated. + +@item queue +Alternate term for message queue. + +@item QCB +An acronym for Message Queue Control Block. + +@item ready +A task occupies this state when it is +available to be given control of the CPU. + +@item real-time +A term used to describe systems which are +characterized by requiring deterministic response times to +external stimuli. The external stimuli require that the +response occur at a precise time or the response is incorrect. + +@item reentrant +A term used to describe routines which do +not modify themselves or global variables. + +@item region +An RTEMS object which is used to allocate +and deallocate variable size blocks of memory from a dynamically +specified area of memory. + +@item Region Control Block +A data structure associated +with each region used by RTEMS to manage that region. + +@item registers +Registers are locations physically +located within a component, typically used for device control or +general purpose storage. + +@item remote +Any object that does not reside on the local +node. + +@item remote operation +The manipulation of an object +which does not reside on the same node as the calling task. + +@item return code +Also known as error code or return +value. + +@item resource +A hardware or software entity to which +access must be controlled. + +@item resume +Removing a task from the suspend state. If +the task's state is ready following a call to the task_resume +directive, then the task is available for scheduling. + +@item return code +A value returned by RTEMS directives to +indicate the completion status of the directive. + +@item RNCB +An acronym for Region Control Block. + +@item round-robin +A task scheduling discipline in which +tasks of equal priority are executed in the order in which they +are made ready. + +@item RS-232 +A standard for serial communications. + +@item running +The state of a rate monotonic timer while +it is being used to delineate a period. The timer exits this +state by either expiring or being canceled. + +@item schedule +The process of choosing which task should +next enter the executing state. + +@item schedulable +A set of tasks which can be guaranteed +to meet their deadlines based upon a specific scheduling +algorithm. + +@item segments +Variable sized memory blocks allocated +from a region. + +@item semaphore +An RTEMS object which is used to +synchronize tasks and provide mutually exclusive access to +resources. + +@item Semaphore Control Block +A data structure associated +with each semaphore used by RTEMS to manage that semaphore. + +@item shared memory +Memory which is accessible by +multiple nodes in a multiprocessor system. + +@item signal +An RTEMS provided mechanism to communicate +asynchronously with a task. Upon reception of a signal, the ASR +of the receiving task will be invoked. + +@item signal set +A thirty-two bit entity which is used to +represent a task's collection of pending signals and the signals +sent to a task. + +@item SMCB +An acronym for Semaphore Control Block. + +@item soft real-time system +A real-time system in which a +missed deadline does not compromise the integrity of the system. + +@item sporadic task +A task which executes at irregular +intervals and must comply with a hard deadline. A minimum +period of time between successive iterations of the task can be +guaranteed. + +@item stack +A data structure that is managed using a Last +In First Out (LIFO) discipline. Each task has a stack +associated with it which is used to store return information +and local variables. + +@item status code +Also known as error code or return +value. + +@item suspend +A term used to describe a task that is not +competing for the CPU because it has had a task_suspend +directive. + +@item synchronous +Related in order or timing to other +occurrences in the system. + +@item system call +In this document, this is used as an +alternate term for directive. + +@item target +The system on which the application will +ultimately execute. + +@item task +A logically complete thread of execution. The +CPU is allocated among the ready tasks. + +@item Task Control Block +A data structure associated with +each task used by RTEMS to manage that task. + +@item task switch +Alternate terminology for context +switch. Taking control of the processor from one task and given +to another. + +@item TCB +An acronym for Task Control Block. + +@item tick +The basic unit of time used by RTEMS. It is a +user-configurable number of microseconds. The current tick +expires when the clock_tick directive is invoked. + +@item tightly-coupled +A multiprocessor configuration +system which communicates via shared memory. + +@item timeout +An argument provided to a number of +directives which determines the maximum length of time an +application task is willing to wait to acquire the resource if +it is not immediately available. + +@item timer +An RTEMS object used to invoke subprograms at +a later time. + +@item Timer Control Block +A data structure associated +with each timer used by RTEMS to manage that timer. + +@item timeslicing +A task scheduling discipline in which +tasks of equal priority are executed for a specific period of +time before being preempted by another task. + +@item timeslice +The application defined unit of time in +which the processor is allocated. + +@item TMCB +An acronym for Timer Control Block. + +@item transient overload +A temporary rise in system +activity which may cause deadlines to be missed. Rate Monotonic +Scheduling can be used to determine if all deadlines will be met +under transient overload. + +@item user extensions +Software routines provided by the +application to enhance the functionality of RTEMS. + +@item User Extension Table +A table which contains the +entry points for each user extensions. + +@item User Initialization Tasks Table +A table which +contains the information needed to create and start each of the +user initialization tasks. + +@item user-provided +Alternate term for user-supplied. +This term is used to designate any software routines which must +be written by the application designer. + +@item user-supplied +Alternate term for user-provided. +This term is used to designate any software routines which must +be written by the application designer. + +@item vector +Memory pointers used by the processor to +fetch the address of routines which will handle various +exceptions and interrupts. + +@item wait queue +The list of tasks blocked pending the +release of a particular resource. Message queues, regions, and +semaphores have a wait queue associated with them. + +@item yield +When a task voluntarily releases control of the processor. + +@end table + diff --git a/doc/user/init.t b/doc/user/init.t new file mode 100644 index 0000000000..6b558d4ab4 --- /dev/null +++ b/doc/user/init.t @@ -0,0 +1,408 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Initialization Manager, Initialization Manager Introduction, Key Concepts Memory Management, Top +@end ifinfo +@chapter Initialization Manager +@ifinfo +@menu +* Initialization Manager Introduction:: +* Initialization Manager Background:: +* Initialization Manager Operations:: +* Initialization Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Initialization Manager Introduction, Initialization Manager Background, Initialization Manager, Initialization Manager +@end ifinfo +@section Introduction + +The initialization manager is responsible for +initiating and shutting down RTEMS. Initiating RTEMS involves +creating and starting all configured initialization tasks, and +for invoking the initialization routine for each user-supplied +device driver. In a multiprocessor configuration, this manager +also initializes the interprocessor communications layer. The +directives provided by the initialization manager are: + +@itemize @bullet +@item @code{initialize_executive} - Initialize RTEMS +@item @code{initialize_executive_early} - Initialize RTEMS and do NOT Start Multitasking +@item @code{initialize_executive_late} - Complete Initialization and Start Multitasking +@item @code{shutdown_executive} - Shutdown RTEMS +@end itemize + +@ifinfo +@node Initialization Manager Background, Initialization Tasks, Initialization Manager Introduction, Initialization Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Initialization Tasks:: +* The System Initialization Task:: +* The Idle Task:: +* Initialization Manager Failure:: +@end menu +@end ifinfo + +@ifinfo +@node Initialization Tasks, The System Initialization Task, Initialization Manager Background, Initialization Manager Background +@end ifinfo +@subsection Initialization Tasks + +Initialization task(s) are the mechanism by which +RTEMS transfers initial control to the user's application. +Initialization tasks differ from other application tasks in that +they are defined in the User Initialization Tasks Table and +automatically created and started by RTEMS as part of its +initialization sequence. Since the initialization tasks are +scheduled using the same algorithm as all other RTEMS tasks, +they must be configured at a priority and mode which will insure +that they will complete execution before other application tasks +execute. Although there is no upper limit on the number of +initialization tasks, an application is required to define at +least one. + +A typical initialization task will create and start +the static set of application tasks. It may also create any +other objects used by the application. Initialization tasks +which only perform initialization should delete themselves upon +completion to free resources for other tasks. Initialization +tasks may transform themselves into a "normal" application task. +This transformation typically involves changing priority and +execution mode. RTEMS does not automatically delete the +initialization tasks. + +@ifinfo +@node The System Initialization Task, The Idle Task, Initialization Tasks, Initialization Manager Background +@end ifinfo +@subsection The System Initialization Task + +The System Initialization Task is responsible for +initializing all device drivers. As a result, this task has a +higher priority than all other tasks to insure that no +application tasks executes until all device drivers are +initialized. After device initialization in a single processor +system, this task will delete itself. + +The System Initialization Task must have enough stack +space to successfully execute the initialization routines for +all device drivers and, in multiprocessor configurations, the +Multiprocessor Communications Interface Layer initialization +routine. The CPU Configuration Table contains a field which +allows the application or BSP to increase the default amount of +stack space allocated for this task. + +In multiprocessor configurations, the System +Initialization Task does not delete itself after initializing +the device drivers. Instead it transforms itself into the +Multiprocessing Server which initializes the Multiprocessor +Communications Interface Layer, verifies multiprocessor system +consistency, and processes all requests from remote nodes. + +@ifinfo +@node The Idle Task, Initialization Manager Failure, The System Initialization Task, Initialization Manager Background +@end ifinfo +@subsection The Idle Task + +The Idle Task is the lowest priority task in a system +and executes only when no other task is ready to execute. This +task consists of an infinite loop and will be preempted when any +other task is made ready to execute. + +@ifinfo +@node Initialization Manager Failure, Initialization Manager Operations, The Idle Task, Initialization Manager Background +@end ifinfo +@subsection Initialization Manager Failure + +The fatal_error_occurred directive will be called +from initialize_executive for any of the following reasons: + +@itemize @bullet +@item If either the Configuration Table or the CPU Dependent +Information Table is not provided. + +@item If the starting address of the RTEMS RAM Workspace, +supplied by the application in the Configuration Table, is NULL +or is not aligned on a four-byte boundary. + +@item If the size of the RTEMS RAM Workspace is not large +enough to initialize and configure the system. + +@item If the interrupt stack size specified is too small. + +@item If multiprocessing is configured and the node entry in +the Multiprocessor Configuration Table is not between one and +the maximum_nodes entry. + +@item If a multiprocessor system is being configured and no +Multiprocessor Communications Interface is specified. + +@item If no user initialization tasks are configured. At +least one initialization task must be configured to allow RTEMS +to pass control to the application at the end of the executive +initialization sequence. + +@item If any of the user initialization tasks cannot be +created or started successfully. +@end itemize + +@ifinfo +@node Initialization Manager Operations, Initializing RTEMS, Initialization Manager Failure, Initialization Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Initializing RTEMS:: +* Shutting Down RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Initializing RTEMS, Shutting Down RTEMS, Initialization Manager Operations, Initialization Manager Operations +@end ifinfo +@subsection Initializing RTEMS + +The initialize_executive directive is called by the +board support package at the completion of its initialization +sequence. RTEMS assumes that the board support package +successfully completed its initialization activities. The +initialize_executive directive completes the initialization +sequence by performing the following actions: + +@itemize @bullet +@item Initializing internal RTEMS variables; +@item Allocating system resources; +@item Creating and starting the System Initialization Task; +@item Creating and starting the Idle Task; +@item Creating and starting the user initialization task(s); and +@item Initiating multitasking. +@end itemize + +This directive MUST be called before any other RTEMS +directives. The effect of calling any RTEMS directives before +initialize_executive is unpredictable. Many of RTEMS actions +during initialization are based upon the contents of the +Configuration Table and CPU Dependent Information Table. For +more information regarding the format and contents of these +tables, please refer to the chapter Configuring a System. + +The final step in the initialization sequence is the +initiation of multitasking. When the scheduler and dispatcher +are enabled, the highest priority, ready task will be dispatched +to run. Control will not be returned to the board support +package after multitasking is enabled until shutdown_executive +the directive is called. + +The initialize_executive directive provides a +conceptually simple way to initialize RTEMS. However, in +certain cases, this mechanism cannot be used. The +initialize_executive_early and initialize_executive_late +directives are provided as an alternative mechanism for +initializing RTEMS. The initialize_executive_early directive +returns to the caller BEFORE initiating multitasking. The +initialize_executive_late directive is invoked to start +multitasking. It is critical that only one of the RTEMS +initialization sequences be used in an application. + +@ifinfo +@node Shutting Down RTEMS, Initialization Manager Directives, Initializing RTEMS, Initialization Manager Operations +@end ifinfo +@subsection Shutting Down RTEMS + +The shutdown_executive directive is invoked by the +application to end multitasking and return control to the board +support package. The board support package resumes execution at +the code immediately following the invocation of the +initialize_executive directive. + +@ifinfo +@node Initialization Manager Directives, INITIALIZE_EXECUTIVE - Initialize RTEMS, Shutting Down RTEMS, Initialization Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* INITIALIZE_EXECUTIVE - Initialize RTEMS:: +* INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking:: +* INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking:: +* SHUTDOWN_EXECUTIVE - Shutdown RTEMS:: +@end menu +@end ifinfo + +This section details the initialization manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node INITIALIZE_EXECUTIVE - Initialize RTEMS, INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, Initialization Manager Directives, Initialization Manager Directives +@end ifinfo +@subsection INITIALIZE_EXECUTIVE - Initialize RTEMS + +@subheading CALLING SEQUENCE: + +@example +rtems_interrupt_level rtems_initialize_executive_early( + rtems_configuration_table *configuration_table, + rtems_cpu_table *cpu_table +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called when the board support +package has completed its initialization to allow RTEMS to +initialize the application environment based upon the +information in the Configuration Table, CPU Dependent +Information Table, User Initialization Tasks Table, Device +Driver Table, User Extension Table, Multiprocessor Configuration +Table, and the Multiprocessor Communications Interface (MPCI) +Table. This directive starts multitasking and does not return +to the caller until the shutdown_executive directive is invoked. + +@subheading NOTES: + +This directive MUST be the first RTEMS directive +called and it DOES NOT RETURN to the caller until the +shutdown_executive is invoked. + +This directive causes all nodes in the system to +verify that certain configuration parameters are the same as +those of the local node. If an inconsistency is detected, then +a fatal error is generated. + +The application must use only one of the two +initialization sequences: initialize_executive or +initialize_executive_early and initialize_executive_late. The +initialize_executive directive is logically equivalent to +invoking initialize_executive_early and +initialize_executive_late with no intervening actions. + +@page +@ifinfo +@node INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, INITIALIZE_EXECUTIVE - Initialize RTEMS, Initialization Manager Directives +@end ifinfo +@subsection INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking + +@subheading CALLING SEQUENCE: + +@example +rtems_interrupt_level rtems_initialize_executive_early( + rtems_configuration_table *configuration_table, + rtems_cpu_table *cpu_table +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called when the board support +package has completed its initialization to allow RTEMS to +initialize the application environment based upon the +information in the Configuration Table, CPU Dependent +Information Table, User Initialization Tasks Table, Device +Driver Table, User Extension Table, Multiprocessor Configuration +Table, and the Multiprocessor Communications Interface (MPCI) +Table. This directive returns to the caller after completing +the basic RTEMS initialization but before multitasking is +initiated. The interrupt level in place when the directive is +invoked is returned to the caller. This interrupt level should +be the same one passed to initialize_executive_late. + +@subheading NOTES: + +The application must use only one of the two +initialization sequences: initialize_executive or +initialize_executive_early and initialize_executive_late. + +@page +@ifinfo +@node INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, INITIALIZE_EXECUTIVE_EARLY - Initialize RTEMS and do NOT Start Multitasking, Initialization Manager Directives +@end ifinfo +@subsection INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking + +@subheading CALLING SEQUENCE: + +@example +void rtems_initialize_executive_late( + rtems_interrupt_level bsp_level +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called after the +initialize_executive_early directive has been called to complete +the RTEMS initialization sequence and initiate multitasking. +The interrupt level returned by the initialize_executive_early +directive should be in bsp_level and this value is restored as +part of this directive returning to the caller after the +shutdown_executive directive is invoked. + +@subheading NOTES: + +This directive MUST be the second RTEMS directive +called and it DOES NOT RETURN to the caller until the +shutdown_executive is invoked. + +This directive causes all nodes in the system to +verify that certain configuration parameters are the same as +those of the local node. If an inconsistency is detected, then +a fatal error is generated. + +The application must use only one of the two +initialization sequences: initialize_executive or +initialize_executive_early and initialize_executive_late. + + + +@page +@ifinfo +@node SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Task Manager, INITIALIZE_EXECUTIVE_LATE - Complete Initialization and Start Multitasking, Initialization Manager Directives +@end ifinfo +@subsection SHUTDOWN_EXECUTIVE - Shutdown RTEMS + +@subheading CALLING SEQUENCE: + +@example +void rtems_shutdown_executive( + rtems_unsigned32 result +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive is called when the application wishes +to shutdown RTEMS and return control to the board support +package. The board support package resumes execution at the +code immediately following the invocation of the +initialize_executive directive. + +@subheading NOTES: + +This directive MUST be the last RTEMS directive +invoked by an application and it DOES NOT RETURN to the caller. + +This directive should not be invoked until the +executive has successfully completed initialization. diff --git a/doc/user/intr.t b/doc/user/intr.t new file mode 100644 index 0000000000..8eb076e8f4 --- /dev/null +++ b/doc/user/intr.t @@ -0,0 +1,300 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Interrupt Manager, Interrupt Manager Introduction, TASK_WAKE_WHEN - Wake up when specified, Top +@end ifinfo +@chapter Interrupt Manager +@ifinfo +@menu +* Interrupt Manager Introduction:: +* Interrupt Manager Background:: +* Interrupt Manager Operations:: +* Interrupt Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Interrupt Manager Introduction, Interrupt Manager Background, Interrupt Manager, Interrupt Manager +@end ifinfo +@section Introduction + +Any real-time executive must provide a mechanism for +quick response to externally generated interrupts to satisfy the +critical time constraints of the application. The interrupt +manager provides this mechanism for RTEMS. This manager permits +quick interrupt response times by providing the critical ability +to alter task execution which allows a task to be preempted upon +exit from an ISR. The interrupt manager includes the following +directive: + +@itemize @bullet +@item @code{interrupt_catch} - Establish an ISR +@end itemize + +@ifinfo +@node Interrupt Manager Background, Processing an Interrupt, Interrupt Manager Introduction, Interrupt Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Processing an Interrupt:: +* RTEMS Interrupt Levels:: +* Disabling of Interrupts by RTEMS:: +@end menu +@end ifinfo + +@ifinfo +@node Processing an Interrupt, RTEMS Interrupt Levels, Interrupt Manager Background, Interrupt Manager Background +@end ifinfo +@subsection Processing an Interrupt + +The interrupt manager allows the application to +connect a function to a hardware interrupt vector. When an +interrupt occurs, the processor will automatically vector to +RTEMS. RTEMS saves and restores all registers which are not +preserved by the normal C calling convention for the target +processor and invokes the user's ISR. The user's ISR is +responsible for processing the interrupt, clearing the interrupt +if necessary, and device specific manipulation. + +The interrupt_catch directive connects a procedure to +an interrupt vector. The interrupt service routine is assumed +to abide by these conventions and have a prototype similar to +the following: + +@example +rtems_isr user_isr( + rtems_vector_number vector +); +@end example + +The vector number argument is provided by RTEMS to +allow the application to identify the interrupt source. This +could be used to allow a single routine to service interrupts +from multiple instances of the same device. For example, a +single routine could service interrupts from multiple serial +ports and use the vector number to identify which port requires +servicing. + +To minimize the masking of lower or equal priority +level interrupts, the ISR should perform the minimum actions +required to service the interrupt. Other non-essential actions +should be handled by application tasks. Once the user's ISR has +completed, it returns control to the RTEMS interrupt manager +which will perform task dispatching and restore the registers +saved before the ISR was invoked. + +The RTEMS interrupt manager guarantees that proper +task scheduling and dispatching are performed at the conclusion +of an ISR. A system call made by the ISR may have readied a +task of higher priority than the interrupted task. Therefore, +when the ISR completes, the postponed dispatch processing must +be performed. No dispatch processing is performed as part of +directives which have been invoked by an ISR. + +Applications must adhere to the following rule if +proper task scheduling and dispatching is to be performed: + +@itemize @code{ } + +@item @b{The interrupt manager must be used for all ISRs which +may be interrupted by the highest priority ISR which invokes an +RTEMS directive.} + +@end itemize + + +Consider a processor which allows a numerically low +interrupt level to interrupt a numerically greater interrupt +level. In this example, if an RTEMS directive is used in a +level 4 ISR, then all ISRs which execute at levels 0 through 4 +must use the interrupt manager. + +Interrupts are nested whenever an interrupt occurs +during the execution of another ISR. RTEMS supports efficient +interrupt nesting by allowing the nested ISRs to terminate +without performing any dispatch processing. Only when the +outermost ISR terminates will the postponed dispatching occur. + + + +@ifinfo +@node RTEMS Interrupt Levels, Disabling of Interrupts by RTEMS, Processing an Interrupt, Interrupt Manager Background +@end ifinfo +@subsection RTEMS Interrupt Levels + +Many processors support multiple interrupt levels or +priorities. The exact number of interrupt levels is processor +dependent. RTEMS internally supports 256 interrupt levels which +are mapped to the processor's interrupt levels. For specific +information on the mapping between RTEMS and the target +processor's interrupt levels, refer to the Interrupt Processing +chapter of the C Applications Supplement document for a specific +target processor. + +@ifinfo +@node Disabling of Interrupts by RTEMS, Interrupt Manager Operations, RTEMS Interrupt Levels, Interrupt Manager Background +@end ifinfo +@subsection Disabling of Interrupts by RTEMS + +During the execution of directive calls, critical +sections of code may be executed. When these sections are +encountered, RTEMS disables all maskable interrupts before the +execution of the section and restores them to the previous level +upon completion of the section. RTEMS has been optimized to +insure that interrupts are disabled for a minimum length of +time. The maximum length of time interrupts are disabled by +RTEMS is processor dependent and is detailed in the Timing +Specification chapter of the C Applications Supplement document +for a specific target processor. + +Non-maskable interrupts (NMI) cannot be disabled, and +ISRs which execute at this level MUST NEVER issue RTEMS system +calls. If a directive is invoked, unpredictable results may +occur due to the inability of RTEMS to protect its critical +sections. However, ISRs that make no system calls may safely +execute as non-maskable interrupts. + +@ifinfo +@node Interrupt Manager Operations, Establishing an ISR, Disabling of Interrupts by RTEMS, Interrupt Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Establishing an ISR:: +* Directives Allowed from an ISR:: +@end menu +@end ifinfo + +@ifinfo +@node Establishing an ISR, Directives Allowed from an ISR, Interrupt Manager Operations, Interrupt Manager Operations +@end ifinfo +@subsection Establishing an ISR + +The interrupt_catch directive establishes an ISR for +the system. The address of the ISR and its associated CPU +vector number are specified to this directive. This directive +installs the RTEMS interrupt wrapper in the processor's +Interrupt Vector Table and the address of the user's ISR in the +RTEMS' Vector Table. This directive returns the previous +contents of the specified vector in the RTEMS' Vector Table. + +@ifinfo +@node Directives Allowed from an ISR, Interrupt Manager Directives, Establishing an ISR, Interrupt Manager Operations +@end ifinfo +@subsection Directives Allowed from an ISR + +Using the interrupt manager insures that RTEMS knows +when a directive is being called from an ISR. The ISR may then +use system calls to synchronize itself with an application task. +The synchronization may involve messages, events or signals +being passed by the ISR to the desired task. Directives invoked +by an ISR must operate only on objects which reside on the local +node. The following is a list of RTEMS system calls that may be +made from an ISR: + +@itemize @bullet +@item Task Management + +@itemize - +@item task_get_note, task_set_note, task_suspend, task_resume +@end itemize + +@item Clock Management + +@itemize - +@item clock_get, clock_tick +@end itemize + +@item Message, Event, and Signal Management + +@itemize - +@item message_queue_send, message_queue_urgent +@item event_send +@item signal_send +@end itemize + +@item Semaphore Management + +@itemize - +@item semaphore_release +@end itemize + +@item Dual-Ported Memory Management + +@itemize - +@item port_external_to_internal, port_internal_to_external +@end itemize + +@item IO Management + +@itemize - +@item io_initialize, io_open, io_close, io_read, io_write, io_control +@end itemize + +@item Fatal Error Management + +@itemize - +@item fatal_error_occurred +@end itemize + +@item Multiprocessing + +@itemize - +@item multiprocessing_announce +@end itemize +@end itemize + +@ifinfo +@node Interrupt Manager Directives, INTERRUPT_CATCH - Establish an ISR, Directives Allowed from an ISR, Interrupt Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* INTERRUPT_CATCH - Establish an ISR:: +@end menu +@end ifinfo + +This section details the interrupt manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node INTERRUPT_CATCH - Establish an ISR, Clock Manager, Interrupt Manager Directives, Interrupt Manager Directives +@end ifinfo +@subsection INTERRUPT_CATCH - Establish an ISR + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - ISR established successfully@* +@code{INVALID_NUMBER} - illegal vector number@* +@code{INVALID_ADDRESS} - illegal ISR entry point + +@subheading DESCRIPTION: + +This directive establishes an interrupt service +routine (ISR) for the specified interrupt vector number. The +new_isr_handler parameter specifies the entry point of the ISR. +The entry point of the previous ISR for the specified vector is +returned in old_isr_handler. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + diff --git a/doc/user/io.t b/doc/user/io.t new file mode 100644 index 0000000000..5176b89224 --- /dev/null +++ b/doc/user/io.t @@ -0,0 +1,528 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node I/O Manager, I/O Manager Introduction, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, Top +@end ifinfo +@chapter I/O Manager +@ifinfo +@menu +* I/O Manager Introduction:: +* I/O Manager Background:: +* I/O Manager Operations:: +* I/O Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node I/O Manager Introduction, I/O Manager Background, I/O Manager, I/O Manager +@end ifinfo +@section Introduction + +The input/output interface manager provides a +well-defined mechanism for accessing device drivers and a +structured methodology for organizing device drivers. The +directives provided by the I/O manager are: + +@itemize @bullet +@item @code{io_initialize} - Initialize a device driver +@item @code{io_register_name} - Register a device name +@item @code{io_lookup_name} - Look up a device name +@item @code{io_open} - Open a device +@item @code{io_close} - Close a device +@item @code{io_read} - Read from a device +@item @code{io_write} - Write to a device +@item @code{io_control} - Special device services +@end itemize + + + +@ifinfo +@node I/O Manager Background, Device Driver Table, I/O Manager Introduction, I/O Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Device Driver Table:: +* Major and Minor Device Numbers:: +* Device Names:: +* Device Driver Environment:: +* Device Driver Interface:: +* Device Driver Initialization:: +@end menu +@end ifinfo + +@ifinfo +@node Device Driver Table, Major and Minor Device Numbers, I/O Manager Background, I/O Manager Background +@end ifinfo +@subsection Device Driver Table + +Each application utilizing the RTEMS I/O manager must +specify the address of a Device Driver Table in its +Configuration Table. This table contains each device driver's +entry points. Each device driver may contain the following +entry points: + +@itemize @bullet +@item Initialization +@item Open +@item Close +@item Read +@item Write +@item Control +@end itemize + +If the device driver does not support a particular +entry point, then that entry in the Configuration Table should +be NULL. RTEMS will return SUCCESSFUL as the executive's and +zero (0) as the device driver's return code for these device +driver entry points. + +@ifinfo +@node Major and Minor Device Numbers, Device Names, Device Driver Table, I/O Manager Background +@end ifinfo +@subsection Major and Minor Device Numbers + +Each call to the I/O manager must provide a device's +major and minor numbers as arguments. The major number is the +index of the requested driver's entry points in the Device +Driver Table, and is used to select a specific device driver. +The exact usage of the minor number is driver specific, but is +commonly used to distinguish between a number of devices +controlled by the same driver. + +@ifinfo +@node Device Names, Device Driver Environment, Major and Minor Device Numbers, I/O Manager Background +@end ifinfo +@subsection Device Names + +The I/O Manager provides facilities to associate a +name with a particular device. Directives are provided to +register the name of a device and to look up the major/minor +number pair associated with a device name. + +@ifinfo +@node Device Driver Environment, Device Driver Interface, Device Names, I/O Manager Background +@end ifinfo +@subsection Device Driver Environment + +Application developers, as well as device driver +developers, must be aware of the following regarding the RTEMS +I/O Manager: + +@itemize @bullet +@item A device driver routine executes in the context of the +invoking task. Thus if the driver blocks, the invoking task +blocks. + +@item The device driver is free to change the modes of the +invoking task, although the driver should restore them to their +original values. + +@item Device drivers may be invoked from ISRs. + +@item Only local device drivers are accessible through the I/O +manager. + +@item A device driver routine may invoke all other RTEMS +directives, including I/O directives, on both local and global +objects. + +@end itemize + +Although the RTEMS I/O manager provides a framework +for device drivers, it makes no assumptions regarding the +construction or operation of a device driver. + +@ifinfo +@node Device Driver Interface, Device Driver Initialization, Device Driver Environment, I/O Manager Background +@end ifinfo +@subsection Device Driver Interface + +When an application invokes an I/O manager directive, +RTEMS determines which device driver entry point must be +invoked. The information passed by the application to RTEMS is +then passed to the correct device driver entry point. RTEMS +will invoke each device driver entry point assuming it is +compatible with the following prototype: + +@example +rtems_device_driver io_entry( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument_block +); +@end example + + + +The format and contents of the parameter block are +device driver and entry point dependent. + +It is recommended that a device driver avoid +generating error codes which conflict with those used by +application components. A common technique used to generate +driver specific error codes is to make the most significant part +of the status indicate a driver specific code. + +@ifinfo +@node Device Driver Initialization, I/O Manager Operations, Device Driver Interface, I/O Manager Background +@end ifinfo +@subsection Device Driver Initialization + +RTEMS automatically initializes all device drivers +when multitasking is initiated via the initialize_executive +directive. RTEMS initializes the device drivers by invoking +each device driver initialization entry point with the following +parameters: + +@table @asis +@item major +the major device number for this device driver. + +@item minor +zero. + +@item argument_block +will point to the Configuration Table. + +@end table + +The returned status will be ignored by RTEMS. If the driver +cannot successfully initialize the device, then it should invoke +the fatal_error_occurred directive. + +@ifinfo +@node I/O Manager Operations, Register and Lookup Name, Device Driver Initialization, I/O Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Register and Lookup Name:: +* Accessing an Device Driver:: +@end menu +@end ifinfo + +@ifinfo +@node Register and Lookup Name, Accessing an Device Driver, I/O Manager Operations, I/O Manager Operations +@end ifinfo +@subsection Register and Lookup Name + +The io_register directive associates a name with the +specified device (i.e. major/minor number pair). Device names +are typically registered as part of the device driver +initialization sequence. The io_lookup directive is used to +determine the major/minor number pair associated with the +specified device name. The use of these directives frees the +application from being dependent on the arbitrary assignment of +major numbers in a particular application. No device naming +conventions are dictated by RTEMS. + +@ifinfo +@node Accessing an Device Driver, I/O Manager Directives, Register and Lookup Name, I/O Manager Operations +@end ifinfo +@subsection Accessing an Device Driver + +The I/O manager provides directives which enable the +application program to utilize device drivers in a standard +manner. There is a direct correlation between the RTEMS I/O +manager directives io_initialize, io_open, io_close, io_read, +io_write, and io_control and the underlying device driver entry +points. + +@ifinfo +@node I/O Manager Directives, IO_INITIALIZE - Initialize a device driver, Accessing an Device Driver, I/O Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* IO_INITIALIZE - Initialize a device driver:: +* IO_REGISTER_NAME - Register a device:: +* IO_LOOKUP_NAME - Lookup a device:: +* IO_OPEN - Open a device:: +* IO_CLOSE - Close a device:: +* IO_READ - Read from a device:: +* IO_WRITE - Write to a device:: +* IO_CONTROL - Special device services:: +@end menu +@end ifinfo + +This section details the I/O manager's directives. A +subsection is dedicated to each of this manager's directives and +describes the calling sequence, related constants, usage, and +status codes. + +@page +@ifinfo +@node IO_INITIALIZE - Initialize a device driver, IO_REGISTER_NAME - Register a device, I/O Manager Directives, I/O Manager Directives +@end ifinfo +@subsection IO_INITIALIZE - Initialize a device driver + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_initialize( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver initialization +routine specified in the Device Driver Table for this major +number. This directive is automatically invoked for each device +driver when multitasking is initiated via the +initialize_executive directive. + +A device driver initialization module is responsible +for initializing all hardware and data structures associated +with a device. If necessary, it can allocate memory to be used +during other operations. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +initialized. + +@page +@ifinfo +@node IO_REGISTER_NAME - Register a device, IO_LOOKUP_NAME - Lookup a device, IO_INITIALIZE - Initialize a device driver, I/O Manager Directives +@end ifinfo +@subsection IO_REGISTER_NAME - Register a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_register_name( + char *name, + rtems_device_major_number major, + rtems_device_minor_number minor +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{TOO_MANY} - too many devices registered + +@subheading DESCRIPTION: + +This directive associates name with the specified +major/minor number pair. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node IO_LOOKUP_NAME - Lookup a device, IO_OPEN - Open a device, IO_REGISTER_NAME - Register a device, I/O Manager Directives +@end ifinfo +@subsection IO_LOOKUP_NAME - Lookup a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_lookup( + const char *name, + rtems_driver_name_t **device_info +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{UNSATISFIED} - name not registered + +@subheading DESCRIPTION: + +This directive returns the major/minor number pair +associated with the given device name in device_info. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node IO_OPEN - Open a device, IO_CLOSE - Close a device, IO_LOOKUP_NAME - Lookup a device, I/O Manager Directives +@end ifinfo +@subsection IO_OPEN - Open a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_open( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver open routine +specified in the Device Driver Table for this major number. The +open entry point is commonly used by device drivers to provide +exclusive access to a device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_CLOSE - Close a device, IO_READ - Read from a device, IO_OPEN - Open a device, I/O Manager Directives +@end ifinfo +@subsection IO_CLOSE - Close a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_close( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver close routine +specified in the Device Driver Table for this major number. The +close entry point is commonly used by device drivers to +relinquish exclusive access to a device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_READ - Read from a device, IO_WRITE - Write to a device, IO_CLOSE - Close a device, I/O Manager Directives +@end ifinfo +@subsection IO_READ - Read from a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_read( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver read routine +specified in the Device Driver Table for this major number. +Read operations typically require a buffer address as part of +the argument parameter block. The contents of this buffer will +be replaced with data from the device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_WRITE - Write to a device, IO_CONTROL - Special device services, IO_READ - Read from a device, I/O Manager Directives +@end ifinfo +@subsection IO_WRITE - Write to a device + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_write( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver write routine +specified in the Device Driver Table for this major number. +Write operations typically require a buffer address as part of +the argument parameter block. The contents of this buffer will +be sent to the device. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + +@page +@ifinfo +@node IO_CONTROL - Special device services, Fatal Error Manager, IO_WRITE - Write to a device, I/O Manager Directives +@end ifinfo +@subsection IO_CONTROL - Special device services + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_io_control( + rtems_device_major_number major, + rtems_device_minor_number minor, + void *argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - successfully initialized@* +@code{INVALID_NUMBER} - invalid major device number + +@subheading DESCRIPTION: + +This directive calls the device driver I/O control +routine specified in the Device Driver Table for this major +number. The exact functionality of the driver entry called by +this directive is driver dependent. It should not be assumed +that the control entries of two device drivers are compatible. +For example, an RS-232 driver I/O control operation may change +the baud rate of a serial line, while an I/O control operation +for a floppy disk driver may cause a seek operation. + +@subheading NOTES: + +This directive may or may not cause the calling task +to be preempted. This is dependent on the device driver being +invoked. + + + diff --git a/doc/user/mp.t b/doc/user/mp.t new file mode 100644 index 0000000000..05a62978c4 --- /dev/null +++ b/doc/user/mp.t @@ -0,0 +1,628 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Multiprocessing Manager, Multiprocessing Manager Introduction, Configuring a System Sizing the RTEMS RAM Workspace, Top +@end ifinfo +@chapter Multiprocessing Manager +@ifinfo +@menu +* Multiprocessing Manager Introduction:: +* Multiprocessing Manager Background:: +* Multiprocessing Manager Multiprocessor Communications Interface Layer:: +* Multiprocessing Manager Operations:: +* Multiprocessing Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Multiprocessing Manager Introduction, Multiprocessing Manager Background, Multiprocessing Manager, Multiprocessing Manager +@end ifinfo +@section Introduction + +In multiprocessor real-time systems, new +requirements, such as sharing data and global resources between +processors, are introduced. This requires an efficient and +reliable communications vehicle which allows all processors to +communicate with each other as necessary. In addition, the +ramifications of multiple processors affect each and every +characteristic of a real-time system, almost always making them +more complicated. + +RTEMS addresses these issues by providing simple and +flexible real-time multiprocessing capabilities. The executive +easily lends itself to both tightly-coupled and loosely-coupled +configurations of the target system hardware. In addition, +RTEMS supports systems composed of both homogeneous and +heterogeneous mixtures of processors and target boards. + +A major design goal of the RTEMS executive was to +transcend the physical boundaries of the target hardware +configuration. This goal is achieved by presenting the +application software with a logical view of the target system +where the boundaries between processor nodes are transparent. +As a result, the application developer may designate objects +such as tasks, queues, events, signals, semaphores, and memory +blocks as global objects. These global objects may then be +accessed by any task regardless of the physical location of the +object and the accessing task. RTEMS automatically determines +that the object being accessed resides on another processor and +performs the actions required to access the desired object. +Simply stated, RTEMS allows the entire system, both hardware and +software, to be viewed logically as a single system. + +@ifinfo +@node Multiprocessing Manager Background, Nodes, Multiprocessing Manager Introduction, Multiprocessing Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Nodes:: +* Global Objects:: +* Global Object Table:: +* Remote Operations:: +* Proxies:: +* Multiprocessor Configuration Table:: +@end menu +@end ifinfo + +RTEMS makes no assumptions regarding the connection +media or topology of a multiprocessor system. The tasks which +compose a particular application can be spread among as many +processors as needed to satisfy the application's timing +requirements. The application tasks can interact using a subset +of the RTEMS directives as if they were on the same processor. +These directives allow application tasks to exchange data, +communicate, and synchronize regardless of which processor they +reside upon. + +The RTEMS multiprocessor execution model is multiple +instruction streams with multiple data streams (MIMD). This +execution model has each of the processors executing code +independent of the other processors. Because of this +parallelism, the application designer can more easily guarantee +deterministic behavior. + +By supporting heterogeneous environments, RTEMS +allows the systems designer to select the most efficient +processor for each subsystem of the application. Configuring +RTEMS for a heterogeneous environment is no more difficult than +for a homogeneous one. In keeping with RTEMS philosophy of +providing transparent physical node boundaries, the minimal +heterogeneous processing required is isolated in the MPCI layer. + +@ifinfo +@node Nodes, Global Objects, Multiprocessing Manager Background, Multiprocessing Manager Background +@end ifinfo +@subsection Nodes + +A processor in a RTEMS system is referred to as a +node. Each node is assigned a unique non-zero node number by +the application designer. RTEMS assumes that node numbers are +assigned consecutively from one to maximum_nodes. The node +number, node, and the maximum number of nodes, maximum_nodes, in +a system are found in the Multiprocessor Configuration Table. +The maximum_nodes field and the number of global objects, +maximum_global_objects, is required to be the same on all nodes +in a system. + +The node number is used by RTEMS to identify each +node when performing remote operations. Thus, the +Multiprocessor Communications Interface Layer (MPCI) must be +able to route messages based on the node number. + +@ifinfo +@node Global Objects, Global Object Table, Nodes, Multiprocessing Manager Background +@end ifinfo +@subsection Global Objects + +All RTEMS objects which are created with the GLOBAL +attribute will be known on all other nodes. Global objects can +be referenced from any node in the system, although certain +directive specific restrictions (e.g. one cannot delete a remote +object) may apply. A task does not have to be global to perform +operations involving remote objects. The maximum number of +global objects is the system is user configurable and can be +found in the maximum_global_objects field in the Multiprocessor +Configuration Table. The distribution of tasks to processors is +performed during the application design phase. Dynamic task +relocation is not supported by RTEMS. + +@ifinfo +@node Global Object Table, Remote Operations, Global Objects, Multiprocessing Manager Background +@end ifinfo +@subsection Global Object Table + +RTEMS maintains two tables containing object +information on every node in a multiprocessor system: a local +object table and a global object table. The local object table +on each node is unique and contains information for all objects +created on this node whether those objects are local or global. +The global object table contains information regarding all +global objects in the system and, consequently, is the same on +every node. + +Since each node must maintain an identical copy of +the global object table, the maximum number of entries in each +copy of the table must be the same. The maximum number of +entries in each copy is determined by the +maximum_global_objects parameter in the Multiprocessor +Configuration Table. This parameter, as well as the +maximum_nodes parameter, is required to be the same on all +nodes. To maintain consistency among the table copies, every +node in the system must be informed of the creation or deletion +of a global object. + +@ifinfo +@node Remote Operations, Proxies, Global Object Table, Multiprocessing Manager Background +@end ifinfo +@subsection Remote Operations + +When an application performs an operation on a remote +global object, RTEMS must generate a Remote Request (RQ) message +and send it to the appropriate node. After completing the +requested operation, the remote node will build a Remote +Response (RR) message and send it to the originating node. +Messages generated as a side-effect of a directive (such as +deleting a global task) are known as Remote Processes (RP) and +do not require the receiving node to respond. + +Other than taking slightly longer to execute +directives on remote objects, the application is unaware of the +location of the objects it acts upon. The exact amount of +overhead required for a remote operation is dependent on the +media connecting the nodes and, to a lesser degree, on the +efficiency of the user-provided MPCI routines. + +The following shows the typical transaction sequence +during a remote application: + +@enumerate + +@item The application issues a directive accessing a +remote global object. + +@item RTEMS determines the node on which the object +resides. + +@item RTEMS calls the user-provided MPCI routine +GET_PACKET to obtain a packet in which to build a RQ message. + +@item After building a message packet, RTEMS calls the +user-provided MPCI routine SEND_PACKET to transmit the packet to +the node on which the object resides (referred to as the +destination node). + +@item The calling task is blocked until the RR message +arrives, and control of the processor is transferred to another +task. + +@item The MPCI layer on the destination node senses the +arrival of a packet (commonly in an ISR), and calls the +multiprocessing_announce directive. This directive readies the +Multiprocessing Server. + +@item The Multiprocessing Server calls the user-provided +MPCI routine RECEIVE_PACKET, performs the requested operation, +builds an RR message, and returns it to the originating node. + +@item The MPCI layer on the originating node senses the +arrival of a packet (typically via an interrupt), and calls the +RTEMS multiprocessing_announce directive. This directive +readies the Multiprocessing Server. + +@item The Multiprocessing Server calls the user-provided +MPCI routine RECEIVE_PACKET, readies the original requesting +task, and blocks until another packet arrives. Control is +transferred to the original task which then completes processing +of the directive. + +@end enumerate + +If an uncorrectable error occurs in the user-provided +MPCI layer, the fatal error handler should be invoked. RTEMS +assumes the reliable transmission and reception of messages by +the MPCI and makes no attempt to detect or correct errors. + +@ifinfo +@node Proxies, Multiprocessor Configuration Table, Remote Operations, Multiprocessing Manager Background +@end ifinfo +@subsection Proxies + +A proxy is an RTEMS data structure which resides on a +remote node and is used to represent a task which must block as +part of a remote operation. This action can occur as part of the +semaphore_obtain and message_queue_receive directives. If the +object were local, the task's control block would be available +for modification to indicate it was blocking on a message queue +or semaphore. However, the task's control block resides only on +the same node as the task. As a result, the remote node must +allocate a proxy to represent the task until it can be readied. + +The maximum number of proxies is defined in the +Multiprocessor Configuration Table. Each node in a +multiprocessor system may require a different number of proxies +to be configured. The distribution of proxy control blocks is +application dependent and is different from the distribution of +tasks. + +@ifinfo +@node Multiprocessor Configuration Table, Multiprocessing Manager Multiprocessor Communications Interface Layer, Proxies, Multiprocessing Manager Background +@end ifinfo +@subsection Multiprocessor Configuration Table + +The Multiprocessor Configuration Table contains +information needed by RTEMS when used in a multiprocessor +system. This table is discussed in detail in the section +Multiprocessor Configuration Table of the Configuring a System +chapter. + +@ifinfo +@node Multiprocessing Manager Multiprocessor Communications Interface Layer, INITIALIZATION, Multiprocessor Configuration Table, Multiprocessing Manager +@end ifinfo +@section Multiprocessor Communications Interface Layer +@ifinfo +@menu +* INITIALIZATION:: +* GET_PACKET:: +* RETURN_PACKET:: +* RECEIVE_PACKET:: +* SEND_PACKET:: +* Supporting Heterogeneous Environments:: +@end menu +@end ifinfo + +The Multiprocessor Communications Interface Layer +(MPCI) is a set of user-provided procedures which enable the +nodes in a multiprocessor system to communicate with one +another. These routines are invoked by RTEMS at various times +in the preparation and processing of remote requests. +Interrupts are enabled when an MPCI procedure is invoked. It is +assumed that if the execution mode and/or interrupt level are +altered by the MPCI layer, that they will be restored prior to +returning to RTEMS. + +The MPCI layer is responsible for managing a pool of +buffers called packets and for sending these packets between +system nodes. Packet buffers contain the messages sent between +the nodes. Typically, the MPCI layer will encapsulate the +packet within an envelope which contains the information needed +by the MPCI layer. The number of packets available is dependent +on the MPCI layer implementation. + +The entry points to the routines in the user's MPCI +layer should be placed in the Multiprocessor Communications +Interface Table. The user must provide entry points for each of +the following table entries in a multiprocessor system: + +@itemize @bullet +@item initialization initialize the MPCI +@item get_packet obtain a packet buffer +@item return_packet return a packet buffer +@item send_packet send a packet to another node +@item receive_packet called to get an arrived packet +@end itemize + +A packet is sent by RTEMS in each of the following +situations: + +@itemize @bullet +@item an RQ is generated on an originating node; +@item an RR is generated on a destination node; +@item a global object is created; +@item a global object is deleted; +@item a local task blocked on a remote object is deleted; +@item during system initialization to check for system consistency. +@end itemize + +If the target hardware supports it, the arrival of a +packet at a node may generate an interrupt. Otherwise, the +real-time clock ISR can check for the arrival of a packet. In +any case, the multiprocessing_announce directive must be called +to announce the arrival of a packet. After exiting the ISR, +control will be passed to the Multiprocessing Server to process +the packet. The Multiprocessing Server will call the get_packet +entry to obtain a packet buffer and the receive_entry entry to +copy the message into the buffer obtained. + +@ifinfo +@node INITIALIZATION, GET_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection INITIALIZATION + +The INITIALIZATION component of the user-provided +MPCI layer is called as part of the initialize_executive +directive to initialize the MPCI layer and associated hardware. +It is invoked immediately after all of the device drivers have +been initialized. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_initialization( + rtems_configuration_table *configuration +); +@end group +@end example + +where configuration is the address of the user's +Configuration Table. Operations on global objects cannot be +performed until this component is invoked. The INITIALIZATION +component is invoked only once in the life of any system. If +the MPCI layer cannot be successfully initialized, the fatal +error manager should be invoked by this routine. + +One of the primary functions of the MPCI layer is to +provide the executive with packet buffers. The INITIALIZATION +routine must create and initialize a pool of packet buffers. +There must be enough packet buffers so RTEMS can obtain one +whenever needed. + +@ifinfo +@node GET_PACKET, RETURN_PACKET, INITIALIZATION, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection GET_PACKET + +The GET_PACKET component of the user-provided MPCI +layer is called when RTEMS must obtain a packet buffer to send +or broadcast a message. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_get_packet( + rtems_packet_prefix **packet +); +@end group +@end example + +where packet is the address of a pointer to a packet. +This routine always succeeds and, upon return, packet will +contain the address of a packet. If for any reason, a packet +cannot be successfully obtained, then the fatal error manager +should be invoked. + +RTEMS has been optimized to avoid the need for +obtaining a packet each time a message is sent or broadcast. +For example, RTEMS sends response messages (RR) back to the +originator in the same packet in which the request message (RQ) +arrived. + +@ifinfo +@node RETURN_PACKET, RECEIVE_PACKET, GET_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection RETURN_PACKET + +The RETURN_PACKET component of the user-provided MPCI +layer is called when RTEMS needs to release a packet to the free +packet buffer pool. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_return_packet( + rtems_packet_prefix *packet +); +@end group +@end example + +where packet is the address of a packet. If the +packet cannot be successfully returned, the fatal error manager +should be invoked. + +@ifinfo +@node RECEIVE_PACKET, SEND_PACKET, RETURN_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection RECEIVE_PACKET + +The RECEIVE_PACKET component of the user-provided +MPCI layer is called when RTEMS needs to obtain a packet which +has previously arrived. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_receive_packet( + rtems_packet_prefix **packet +); +@end group +@end example + +where packet is a pointer to the address of a packet +to place the message from another node. If a message is +available, then packet will contain the address of the message +from another node. If no messages are available, this entry +packet should contain NULL. + +@ifinfo +@node SEND_PACKET, Supporting Heterogeneous Environments, RECEIVE_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection SEND_PACKET + +The SEND_PACKET component of the user-provided MPCI +layer is called when RTEMS needs to send a packet containing a +message to another node. This component should be adhere to the +following prototype: + +@example +@group +rtems_mpci_entry user_mpci_send_packet( + rtems_unsigned32 node, + rtems_packet_prefix **packet +); +@end group +@end example + +where node is the node number of the destination and packet is the +address of a packet which containing a message. If the packet cannot +be successfully sent, the fatal error manager should be invoked. + +If node is set to zero, the packet is to be +broadcasted to all other nodes in the system. Although some +MPCI layers will be built upon hardware which support a +broadcast mechanism, others may be required to generate a copy +of the packet for each node in the system. + +Many MPCI layers use the packet_length field of the MP_packet_prefix +of the packet to avoid sending unnecessary data. This is especially +useful if the media connecting the nodes is relatively slow. + +The to_convert field of the MP_packet_prefix portion of the packet indicates +how much of the packet (in unsigned32's) may require conversion in a +heterogeneous system. + +@ifinfo +@node Supporting Heterogeneous Environments, Multiprocessing Manager Operations, SEND_PACKET, Multiprocessing Manager Multiprocessor Communications Interface Layer +@end ifinfo +@subsection Supporting Heterogeneous Environments + +Developing an MPCI layer for a heterogeneous system +requires a thorough understanding of the differences between the +processors which comprise the system. One difficult problem is +the varying data representation schemes used by different +processor types. The most pervasive data representation problem +is the order of the bytes which compose a data entity. +Processors which place the least significant byte at the +smallest address are classified as little endian processors. +Little endian byte-ordering is shown below: + + +@example +@group ++---------------+----------------+---------------+----------------+ +| | | | | +| Byte 3 | Byte 2 | Byte 1 | Byte 0 | +| | | | | ++---------------+----------------+---------------+----------------+ +@end group +@end example + +Conversely, processors which place the most +significant byte at the smallest address are classified as big +endian processors. Big endian byte-ordering is shown below: + +@example +@group ++---------------+----------------+---------------+----------------+ +| | | | | +| Byte 0 | Byte 1 | Byte 2 | Byte 3 | +| | | | | ++---------------+----------------+---------------+----------------+ +@end group +@end example + +Unfortunately, sharing a data structure between big +endian and little endian processors requires translation into a +common endian format. An application designer typically chooses +the common endian format to minimize conversion overhead. + +Another issue in the design of shared data structures +is the alignment of data structure elements. Alignment is both +processor and compiler implementation dependent. For example, +some processors allow data elements to begin on any address +boundary, while others impose restrictions. Common restrictions +are that data elements must begin on either an even address or +on a long word boundary. Violation of these restrictions may +cause an exception or impose a performance penalty. + +Other issues which commonly impact the design of +shared data structures include the representation of floating +point numbers, bit fields, decimal data, and character strings. +In addition, the representation method for negative integers +could be one's or two's complement. These factors combine to +increase the complexity of designing and manipulating data +structures shared between processors. + +RTEMS addressed these issues in the design of the +packets used to communicate between nodes. The RTEMS packet +format is designed to allow the MPCI layer to perform all +necessary conversion without burdening the developer with the +details of the RTEMS packet format. As a result, the MPCI layer +must be aware of the following: + +@itemize @bullet +@item All packets must begin on a four byte boundary. + +@item Packets are composed of both RTEMS and application data. +All RTEMS data is treated as thirty-two (32) bit unsigned +quantities and is in the first MINIMUM_UNSIGNED32S_TO_CONVERT +thirty-two (32) quantities of the packet. + +@item The RTEMS data component of the packet must be in native +endian format. Endian conversion may be performed by either the +sending or receiving MPCI layer. + +@item RTEMS makes no assumptions regarding the application +data component of the packet. +@end itemize + +@ifinfo +@node Multiprocessing Manager Operations, Announcing a Packet, Supporting Heterogeneous Environments, Multiprocessing Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Announcing a Packet:: +@end menu +@end ifinfo + +@ifinfo +@node Announcing a Packet, Multiprocessing Manager Directives, Multiprocessing Manager Operations, Multiprocessing Manager Operations +@end ifinfo +@subsection Announcing a Packet + +The multiprocessing_announce directive is called by +the MPCI layer to inform RTEMS that a packet has arrived from +another node. This directive can be called from an interrupt +service routine or from within a polling routine. + +@ifinfo +@node Multiprocessing Manager Directives, MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Announcing a Packet, Multiprocessing Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet:: +@end menu +@end ifinfo + +This section details the additional directives +required to support RTEMS in a multiprocessor configuration. A +subsection is dedicated to each of this manager's directives and +describes the calling sequence, related constants, usage, and +status codes. + +@page +@ifinfo +@node MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet, Directive Status Codes, Multiprocessing Manager Directives, Multiprocessing Manager Directives +@end ifinfo +@subsection MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet + +@subheading CALLING SEQUENCE: + +@example +void rtems_multiprocessing_announce( void ); +@end example + +@subheading DIRECTIVE STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +This directive informs RTEMS that a multiprocessing +communications packet has arrived from another node. This +directive is called by the user-provided MPCI, and is only used +in multiprocessor configurations. + +@subheading NOTES: + +This directive is typically called from an ISR. + +This directive will almost certainly cause the +calling task to be preempted. + +This directive does not generate activity on remote nodes. diff --git a/doc/user/msg.t b/doc/user/msg.t new file mode 100644 index 0000000000..832b69ef2e --- /dev/null +++ b/doc/user/msg.t @@ -0,0 +1,714 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Message Manager, Message Manager Introduction, SEMAPHORE_RELEASE - Release a semaphore, Top +@end ifinfo +@chapter Message Manager +@ifinfo +@menu +* Message Manager Introduction:: +* Message Manager Background:: +* Message Manager Operations:: +* Message Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Message Manager Introduction, Message Manager Background, Message Manager, Message Manager +@end ifinfo +@section Introduction + +The message manager provides communication and +synchronization capabilities using RTEMS message queues. The +directives provided by the message manager are: + +@itemize @bullet +@item @code{message_queue_create} - Create a queue +@item @code{message_queue_ident} - Get ID of a queue +@item @code{message_queue_delete} - Delete a queue +@item @code{message_queue_send} - Put message at rear of a queue +@item @code{message_queue_urgent} - Put message at front of a queue +@item @code{message_queue_broadcast} - Broadcast N messages to a queue +@item @code{message_queue_receive} - Receive message from a queue +@item @code{message_queue_flush} - Flush all messages on a queue +@end itemize + +@ifinfo +@node Message Manager Background, Messages, Message Manager Introduction, Message Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Messages:: +* Message Queues:: +* Building a Message Queue's Attribute Set:: +* Building a MESSAGE_QUEUE_RECEIVE Option Set:: +@end menu +@end ifinfo + +@ifinfo +@node Messages, Message Queues, Message Manager Background, Message Manager Background +@end ifinfo +@subsection Messages + +A message is a variable length buffer where +information can be stored to support communication. The length +of the message and the information stored in that message are +user-defined and can be actual data, pointer(s), or empty. + +@ifinfo +@node Message Queues, Building a Message Queue's Attribute Set, Messages, Message Manager Background +@end ifinfo +@subsection Message Queues + +A message queue permits the passing of messages among +tasks and ISRs. Message queues can contain a variable number of +messages. Normally messages are sent to and received from the +queue in FIFO order using the message_queue_send directive. +However, the message_queue_urgent directive can be used to place +messages at the head of a queue in LIFO order. + +Synchronization can be accomplished when a task can +wait for a message to arrive at a queue. Also, a task may poll +a queue for the arrival of a message. + +The maximum length message which can be sent is set +on a per message queue basis. + +@ifinfo +@node Building a Message Queue's Attribute Set, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Queues, Message Manager Background +@end ifinfo +@subsection Building a Message Queue's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid message +queue attributes is provided in the following table: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item LOCAL - local message queue (default) +@item GLOBAL - global message queue +@end itemize + + + +An attribute listed as a default is not required to +appear in the attribute list, although it is a good programming +practice to specify default attributes. If all defaults are +desired, the attribute DEFAULT_ATTRIBUTES should be specified on +this call. + +This example demonstrates the attribute_set parameter +needed to create a local message queue with the task priority +waiting queue discipline. The attribute_set parameter to the +message_queue_create directive could be either PRIORITY or LOCAL +| PRIORITY. The attribute_set parameter can be set to PRIORITY +because LOCAL is the default for all created message queues. If +a similar message queue were to be known globally, then the +attribute_set parameter would be GLOBAL | PRIORITY. + +@ifinfo +@node Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager Operations, Building a Message Queue's Attribute Set, Message Manager Background +@end ifinfo +@subsection Building a MESSAGE_QUEUE_RECEIVE Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +message_queue_receive directive are listed in the following +table: + +@itemize @bullet +@item WAIT - task will wait for a message (default) +@item NO_WAIT - task should not wait +@end itemize + +An option listed as a default is not required to +appear in the option OR list, although it is a good programming +practice to specify default options. If all defaults are +desired, the option DEFAULT_OPTIONS should be specified on this +call. + +This example demonstrates the option parameter needed +to poll for a message to arrive. The option parameter passed to +the message_queue_receive directive should be NO_WAIT. + +@ifinfo +@node Message Manager Operations, Creating a Message Queue, Building a MESSAGE_QUEUE_RECEIVE Option Set, Message Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Message Queue:: +* Obtaining Message Queue IDs:: +* Receiving a Message:: +* Sending a Message:: +* Broadcasting a Message:: +* Deleting a Message Queue:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Message Queue, Obtaining Message Queue IDs, Message Manager Operations, Message Manager Operations +@end ifinfo +@subsection Creating a Message Queue + +The message_queue_create directive creates a message +queue with the user-defined name. The user specifies the +maximum message size and maximum number of messages which can be +placed in the message queue at one time. The user may select +FIFO or task priority as the method for placing waiting tasks in +the task wait queue. RTEMS allocates a Queue Control Block +(QCB) from the QCB free list to maintain the newly created queue +as well as memory for the message buffer pool associated with +this message queue. RTEMS also generates a message queue ID +which is returned to the calling task. + +For GLOBAL message queues, the maximum message size +is effectively limited to the longest message which the MPCI is +capable of transmitting. + +@ifinfo +@node Obtaining Message Queue IDs, Receiving a Message, Creating a Message Queue, Message Manager Operations +@end ifinfo +@subsection Obtaining Message Queue IDs + +When a message queue is created, RTEMS generates a +unique message queue ID. The message queue ID may be obtained +by either of two methods. First, as the result of an invocation +of the message_queue_create directive, the queue ID is stored in +a user provided location. Second, the queue ID may be obtained +later using the message_queue_ident directive. The queue ID is +used by other message manager directives to access this message +queue. + +@ifinfo +@node Receiving a Message, Sending a Message, Obtaining Message Queue IDs, Message Manager Operations +@end ifinfo +@subsection Receiving a Message + +The message_queue_receive directive attempts to +retrieve a message from the specified message queue. If at +least one message is in the queue, then the message is removed +from the queue, copied to the caller's message buffer, and +returned immediately along with the length of the message. When +messages are unavailable, one of the following situations +applies: + +@itemize @bullet +@item By default, the calling task will wait forever for the +message to arrive. + +@item Specifying the NO_WAIT option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the period the task will +wait before returning with an error status. +@end itemize + +If the task waits for a message, then it is placed in +the message queue's task wait queue in either FIFO or task +priority order. All tasks waiting on a message queue are +returned an error code when the message queue is deleted. + +@ifinfo +@node Sending a Message, Broadcasting a Message, Receiving a Message, Message Manager Operations +@end ifinfo +@subsection Sending a Message + +Messages can be sent to a queue with the +message_queue_send and message_queue_urgent directives. These +directives work identically when tasks are waiting to receive a +message. A task is removed from the task waiting queue, +unblocked, and the message is copied to a waiting task's +message buffer. + +When no tasks are waiting at the queue, +message_queue_send places the message at the rear of the message +queue, while message_queue_urgent places the message at the +front of the queue. The message is copied to a message buffer +from this message queue's buffer pool and then placed in the +message queue. Neither directive can successfully send a +message to a message queue which has a full queue of pending +messages. + +@ifinfo +@node Broadcasting a Message, Deleting a Message Queue, Sending a Message, Message Manager Operations +@end ifinfo +@subsection Broadcasting a Message + +The message_queue_broadcast directive sends the same +message to every task waiting on the specified message queue as +an atomic operation. The message is copied to each waiting +task's message buffer and each task is unblocked. The number of +tasks which were unblocked is returned to the caller. + +@ifinfo +@node Deleting a Message Queue, Message Manager Directives, Broadcasting a Message, Message Manager Operations +@end ifinfo +@subsection Deleting a Message Queue + +The message_queue_delete directive removes a message +queue from the system and frees its control block as well as the +memory associated with this message queue's message buffer pool. +A message queue can be deleted by any local task that knows the +message queue's ID. As a result of this directive, all tasks +blocked waiting to receive a message from the message queue will +be readied and returned a status code which indicates that the +message queue was deleted. Any subsequent references to the +message queue's name and ID are invalid. Any messages waiting +at the message queue are also deleted and deallocated. + +@ifinfo +@node Message Manager Directives, MESSAGE_QUEUE_CREATE - Create a queue, Deleting a Message Queue, Message Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* MESSAGE_QUEUE_CREATE - Create a queue:: +* MESSAGE_QUEUE_IDENT - Get ID of a queue:: +* MESSAGE_QUEUE_DELETE - Delete a queue:: +* MESSAGE_QUEUE_SEND - Put message at rear of a queue:: +* MESSAGE_QUEUE_URGENT - Put message at front of a queue:: +* MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue:: +* MESSAGE_QUEUE_RECEIVE - Receive message from a queue:: +* MESSAGE_QUEUE_FLUSH - Flush all messages on a queue:: +@end menu +@end ifinfo + +This section details the message manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node MESSAGE_QUEUE_CREATE - Create a queue, MESSAGE_QUEUE_IDENT - Get ID of a queue, Message Manager Directives, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_CREATE - Create a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_create( + rtems_name name, + rtems_unsigned32 count, + rtems_unsigned32 max_message_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - queue created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_NUMBER} - invalid message count@* +@code{INVALID_SIZE} - invalid message size@* +@code{TOO_MANY} - too many queues created@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: + +This directive creates a message queue which resides +on the local node with the user-defined name specified in name. +For control and maintenance of the queue, RTEMS allocates and +initializes a QCB. Memory is allocated from the RTEMS Workspace +for the specified count of messages, each of max_message_size +bytes in length. The RTEMS-assigned queue id, returned in id, +is used to access the message queue. + +Specifying PRIORITY in attribute_set causes tasks +waiting for a message to be serviced according to task priority. +When FIFO is specified, waiting tasks are serviced in First +In-First Out order. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following message queue attribute constants are +defined by RTEMS: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item LOCAL - local message queue (default) +@item GLOBAL - global message queue +@end itemize + +Message queues should not be made global unless +remote tasks must interact with the created message queue. This +is to avoid the system overhead incurred by the creation of a +global message queue. When a global message queue is created, +the message queue's name and id must be transmitted to every +node in the system for insertion in the local copy of the global +object table. + +For GLOBAL message queues, the maximum message size +is effectively limited to the longest message which the MPCI is +capable of transmitting. + +The total number of global objects, including message +queues, is limited by the maximum_global_objects field in the +configuration table. + +@page +@ifinfo +@node MESSAGE_QUEUE_IDENT - Get ID of a queue, MESSAGE_QUEUE_DELETE - Delete a queue, MESSAGE_QUEUE_CREATE - Create a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_IDENT - Get ID of a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - queue identified successfully@* +@code{INVALID_NAME} - queue name not found@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: + +This directive obtains the queue id associated with +the queue name specified in name. If the queue name is not +unique, then the queue id will match one of the queues with that +name. However, this queue id is not guaranteed to correspond to +the desired queue. The queue id is used with other message +related directives to access the message queue. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched +with the local node being searched first. All other nodes are +searched with the lowest numbered node searched first. + +If node is a valid node number which does not +represent the local node, then only the message queues exported +by the designated node are searched. + +This directive does not generate activity on remote +nodes. It accesses only the local copy of the global object +table. + +@page +@ifinfo +@node MESSAGE_QUEUE_DELETE - Delete a queue, MESSAGE_QUEUE_SEND - Put message at rear of a queue, MESSAGE_QUEUE_IDENT - Get ID of a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_DELETE - Delete a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - queue deleted successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote queue + +@subheading DESCRIPTION: + +This directive deletes the message queue specified by +id. As a result of this directive, all tasks blocked waiting to +receive a message from this queue will be readied and returned a +status code which indicates that the message queue was deleted. +If no tasks are waiting, but the queue contains messages, then +RTEMS returns these message buffers back to the system message +buffer pool. The QCB for this queue as well as the memory for +the message buffers is reclaimed by RTEMS. + +@subheading NOTES: + +The calling task will be preempted if its preemption +mode is enabled and one or more local tasks with a higher +priority than the calling task are waiting on the deleted queue. +The calling task will NOT be preempted if the tasks that are +waiting are remote tasks. + +The calling task does not have to be the task that +created the queue, although the task and queue must reside on +the same node. + +When the queue is deleted, any messages in the queue +are returned to the free message buffer pool. Any information +stored in those messages is lost. + +When a global message queue is deleted, the message +queue id must be transmitted to every node in the system for +deletion from the local copy of the global object table. + +Proxies, used to represent remote tasks, are +reclaimed when the message queue is deleted. + +@page +@ifinfo +@node MESSAGE_QUEUE_SEND - Put message at rear of a queue, MESSAGE_QUEUE_URGENT - Put message at front of a queue, MESSAGE_QUEUE_DELETE - Delete a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_SEND - Put message at rear of a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_send( + rtems_id id, + void *buffer, + rtems_unsigned32 size +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message sent successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{INVALID_SIZE} - invalid message size@* +@code{UNSATISFIED} - out of message buffers@* +@code{TOO_MANY} - queue's limit has been reached + +@subheading DESCRIPTION: + +This directive sends the message buffer of size bytes +in length to the queue specified by id. If a task is waiting at +the queue, then the message is copied to the waiting task's +buffer and the task is unblocked. If no tasks are waiting at the +queue, then the message is copied to a message buffer which is +obtained from this message queue's message buffer pool. The +message buffer is then placed at the rear of the queue. + +@subheading NOTES: + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +Sending a message to a global message queue which +does not reside on the local node will generate a request to the +remote node to post the message on the specified message queue. + +If the task to be unblocked resides on a different +node from the message queue, then the message is forwarded to +the appropriate node, the waiting task is unblocked, and the +proxy used to represent the task is reclaimed. + +@page +@ifinfo +@node MESSAGE_QUEUE_URGENT - Put message at front of a queue, MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, MESSAGE_QUEUE_SEND - Put message at rear of a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_URGENT - Put message at front of a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_urgent( + rtems_id id, + void *buffer, + rtems_unsigned32 size +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message sent successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{INVALID_SIZE} - invalid message size@* +@code{UNSATISFIED} - out of message buffers@* +@code{TOO_MANY} - queue's limit has been reached + +@subheading DESCRIPTION: + +This directive sends the message buffer of size bytes +in length to the queue specified by id. If a task is waiting on +the queue, then the message is copied to the task's buffer and +the task is unblocked. If no tasks are waiting on the queue, +then the message is copied to a message buffer which is obtained +from this message queue's message buffer pool. The message +buffer is then placed at the front of the queue. + +@subheading NOTES: + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +Sending a message to a global message queue which +does not reside on the local node will generate a request +telling the remote node to post the message on the specified +message queue. + +If the task to be unblocked resides on a different +node from the message queue, then the message is forwarded to +the appropriate node, the waiting task is unblocked, and the +proxy used to represent the task is reclaimed. + +@page +@ifinfo +@node MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, MESSAGE_QUEUE_RECEIVE - Receive message from a queue, MESSAGE_QUEUE_URGENT - Put message at front of a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_broadcast( + rtems_id id, + void *buffer, + rtems_unsigned32 size, + rtems_unsigned32 *count +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message broadcasted successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{INVALID_SIZE} - invalid message size + +@subheading DESCRIPTION: + +This directive causes all tasks that are waiting at +the queue specified by id to be unblocked and sent the message +contained in buffer. Before a task is unblocked, the message +buffer of size byes in length is copied to that task's message +buffer. The number of tasks that were unblocked is returned in +count. + +@subheading NOTES: + +The calling task will be preempted if it has +preemption enabled and a higher priority task is unblocked as +the result of this directive. + +The execution time of this directive is directly +related to the number of tasks waiting on the message queue, +although it is more efficient than the equivalent number of +invocations of message_queue_send. + +Broadcasting a message to a global message queue +which does not reside on the local node will generate a request +telling the remote node to broadcast the message to the +specified message queue. + +When a task is unblocked which resides on a different +node from the message queue, a copy of the message is forwarded +to the appropriate node, the waiting task is unblocked, and the +proxy used to represent the task is reclaimed. + +@page +@ifinfo +@node MESSAGE_QUEUE_RECEIVE - Receive message from a queue, MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, MESSAGE_QUEUE_BROADCAST - Broadcast N messages to a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_RECEIVE - Receive message from a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_receive( + rtems_id id, + void *buffer, + rtems_unsigned32 *size, + rtems_unsigned32 option_set, + rtems_interval timeout +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message received successfully@* +@code{INVALID_ID} - invalid queue id@* +@code{UNSATISFIED} - queue is empty@* +@code{TIMEOUT} - timed out waiting for message@* +@code{OBJECT_WAS_DELETED} - queue deleted while waiting + +@subheading DESCRIPTION: + +This directive receives a message from the message +queue specified in id. The WAIT and NO_WAIT options of the +options parameter allow the calling task to specify whether to +wait for a message to become available or return immediately. +For either option, if there is at least one message in the +queue, then it is copied to buffer, size is set to return the +length of the message in bytes, and this directive returns +immediately with a successful return code. + +If the calling task chooses to return immediately and +the queue is empty, then a status code indicating this condition +is returned. If the calling task chooses to wait at the message +queue and the queue is empty, then the calling task is placed on +the message wait queue and blocked. If the queue was created +with the PRIORITY option specified, then the calling task is +inserted into the wait queue according to its priority. But, if +the queue was created with the FIFO option specified, then the +calling task is placed at the rear of the wait queue. + +A task choosing to wait at the queue can optionally +specify a timeout value in the timeout parameter. The timeout +parameter specifies the maximum interval to wait before the +calling task desires to be unblocked. If it is set to +NO_TIMEOUT, then the calling task will wait forever. + +@subheading NOTES: + +The following message receive option constants are +defined by RTEMS: + +@itemize @bullet +@item WAIT - task will wait for a message (default) +@item NO_WAIT - task should not wait +@end itemize + + +Receiving a message from a global message queue which +does not reside on the local node will generate a request to the +remote node to obtain a message from the specified message +queue. If no message is available and WAIT was specified, then +the task must be blocked until a message is posted. A proxy is +allocated on the remote node to represent the task until the +message is posted. + +@page +@ifinfo +@node MESSAGE_QUEUE_FLUSH - Flush all messages on a queue, Event Manager, MESSAGE_QUEUE_RECEIVE - Receive message from a queue, Message Manager Directives +@end ifinfo +@subsection MESSAGE_QUEUE_FLUSH - Flush all messages on a queue + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_message_queue_flush( + rtems_id id, + rtems_unsigned32 *count +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - message received successfully@* +@code{INVALID_ID} - invalid queue id + +@subheading DESCRIPTION: + +This directive removes all pending messages from the +specified queue id. The number of messages removed is returned +in count. If no messages are present on the queue, count is set +to zero. + +@subheading NOTES: + +Flushing all messages on a global message queue which +does not reside on the local node will generate a request to the +remote node to actually flush the specified message queue. + + + diff --git a/doc/user/overview.t b/doc/user/overview.t new file mode 100644 index 0000000000..a1c4d4ef01 --- /dev/null +++ b/doc/user/overview.t @@ -0,0 +1,578 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c This chapter is missing the following figures: +@c +@c Figure 1-1 RTEMS Application Architecture +@c Figure 1-2 RTEMS Internal Architecture +@c + +@ifinfo +@node Overview, Overview Introduction, Preface, Top +@end ifinfo +@chapter Overview +@ifinfo +@menu +* Overview Introduction:: +* Overview Real-time Application Systems:: +* Overview Real-time Executive:: +* Overview RTEMS Application Architecture:: +* Overview RTEMS Internal Architecture:: +* Overview User Customization and Extensibility:: +* Overview Portability:: +* Overview Memory Requirements:: +* Overview Audience:: +* Overview Conventions:: +* Overview Manual Organization:: +@end menu +@end ifinfo + +@ifinfo +@node Overview Introduction, Overview Real-time Application Systems, Overview, Overview +@end ifinfo +@section Introduction + +RTEMS, Real-Time Executive for Multiprocessor Systems, is a +real-time executive (kernel) which provides a high performance +environment for embedded military applications including the +following features: + +@itemize @bullet +@item multitasking capabilities +@item homogeneous and heterogeneous multiprocessor systems +@item event-driven, priority-based, preemptive scheduling +@item optional rate monotonic scheduling +@item intertask communication and synchronization +@item priority inheritance +@item responsive interrupt management +@item dynamic memory allocation +@item high level of user configurability +@end itemize + +This manual describes the usage of RTEMS for +applications written in the C programming language. Those +implementation details that are processor dependent are provided +in the C Applications Supplement documents. A supplement +document which addresses specific architectural issues that +affect RTEMS is provided for each processor type that is +supported. + +@ifinfo +@node Overview Real-time Application Systems, Overview Real-time Executive, Overview Introduction, Overview +@end ifinfo +@section Real-time Application Systems + +Real-time application systems are a special class of +computer applications. They have a complex set of +characteristics that distinguish them from other software +problems. Generally, they must adhere to more rigorous +requirements. The correctness of the system depends not only on +the results of computations, but also on the time at which the +results are produced. The most important and complex +characteristic of real-time application systems is that they +must receive and respond to a set of external stimuli within +rigid and critical time constraints referred to as deadlines. +Systems can be buried by an avalanche of interdependent, +asynchronous or cyclical event streams. + +Deadlines can be further characterized as either hard +or soft based upon the value of the results when produced after +the deadline has passed. A deadline is hard if the results have +no value or if their use will result in a catastrophic event. +In contrast, results which are produced after a soft deadline +may have some value. + +Another distinguishing requirement of real-time +application systems is the ability to coordinate or manage a +large number of concurrent activities. Since software is a +synchronous entity, this presents special problems. One +instruction follows another in a repeating synchronous cycle. +Even though mechanisms have been developed to allow for the +processing of external asynchronous events, the software design +efforts required to process and manage these events and tasks +are growing more complicated. + +The design process is complicated further by +spreading this activity over a set of processors instead of a +single processor. The challenges associated with designing and +building real-time application systems become very complex when +multiple processors are involved. New requirements such as +interprocessor communication channels and global resources that +must be shared between competing processors are introduced. The +ramifications of multiple processors complicate each and every +characteristic of a real-time system. + +@ifinfo +@node Overview Real-time Executive, Overview RTEMS Application Architecture, Overview Real-time Application Systems, Overview +@end ifinfo +@section Real-time Executive + +Fortunately, real-time operating systems or real-time +executives serve as a cornerstone on which to build the +application system. A real-time multitasking executive allows +an application to be cast into a set of logical, autonomous +processes or tasks which become quite manageable. Each task is +internally synchronous, but different tasks execute +independently, resulting in an asynchronous processing stream. +Tasks can be dynamically paused for many reasons resulting in a +different task being allowed to execute for a period of time. +The executive also provides an interface to other system +components such as interrupt handlers and device drivers. +System components may request the executive to allocate and +coordinate resources, and to wait for and trigger synchronizing +conditions. The executive system calls effectively extend the +CPU instruction set to support efficient multitasking. By +causing tasks to travel through well-defined state transitions, +system calls permit an application to demand-switch between +tasks in response to real-time events. + +By proper grouping of responses to stimuli into +separate tasks, a system can now asynchronously switch between +independent streams of execution, directly responding to +external stimuli as they occur. This allows the system design +to meet critical performance specifications which are typically +measured by guaranteed response time and transaction throughput. +The multiprocessor extensions of RTEMS provide the features +necessary to manage the extra requirements introduced by a +system distributed across several processors. It removes the +physical barriers of processor boundaries from the world of the +system designer, enabling more critical aspects of the system to +receive the required attention. Such a system, based on an +efficient real-time, multiprocessor executive, is a more +realistic model of the outside world or environment for which it +is designed. As a result, the system will always be more +logical, efficient, and reliable. + +By using the directives provided by RTEMS, the +real-time applications developer is freed from the problem of +controlling and synchronizing multiple tasks and processors. In +addition, one need not develop, test, debug, and document +routines to manage memory, pass messages, or provide mutual +exclusion. The developer is then able to concentrate solely on +the application. By using standard software components, the +time and cost required to develop sophisticated real-time +applications is significantly reduced. + +@ifinfo +@node Overview RTEMS Application Architecture, Overview RTEMS Internal Architecture, Overview Real-time Executive, Overview +@end ifinfo +@section RTEMS Application Architecture + +One important design goal of RTEMS was to provide a +bridge between two critical layers of typical real-time systems. +As shown in the following figure, RTEMS serves as a buffer between the +project dependent application code and the target hardware. +Most hardware dependencies for real-time applications can be +localized to the low level device drivers. The RTEMS I/O +interface manager provides an efficient tool for incorporating +these hardware dependencies into the system while simultaneously +providing a general mechanism to the application code that +accesses them. A well designed real-time system can benefit +from this architecture by building a rich library of standard +application components which can be used repeatedly in other +real-time projects. + +@ifset use-ascii +@example +@group + +-----------------------------------------------------------+ + | Application Dependent Software | + | +----------------------------------------+ | + | | Standard Application Components | | + | | +-------------+---+ | + | +---+-----------+ | | | + | | Board Support | | RTEMS | | + | | Package | | | | + +----+---------------+--------------+-----------------+-----| + | Target Hardware | + +-----------------------------------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.50in{\enskip\hfil#\hfil}& +\vrule#\cr +\multispan{17}\hrulefill\cr +% to force all columns to desired width +& \enskip && \enskip && \enskip && \enskip && + \enskip && \enskip &&\enskip &&\enskip &\cr +% For debugging columns +%& \enskip 0&& \enskip 1&& \enskip 2&& \enskip 3&& +% \enskip 4&& \enskip 5&&\enskip 6&&\enskip 7&\cr +\strut&\multispan{15}&\cr +&\multispan{15}\hfil Application Dependent Software\hfil&\cr +\strut&\multispan{15}&\cr +&\multispan{2}&&\multispan{8}\hrulefill &\multispan{2}&\cr +\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr +&\multispan{2}&&&\multispan{7}\hfil Standard Application Components\hfil& + &\multispan{2}&&\cr +\strut&\multispan{2}&&&\multispan{7}&&\multispan{2}&&\cr +&&\multispan{5}\hrulefill&&\multispan{7}\hrulefill&&\cr +\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr +&&&\multispan{3}\hfil Device\hfil&&&&\multispan{5}\hfil RTEMS\hfil&&&\cr +&&&\multispan{3}\hfil Drivers\hfil&&&&\multispan{5}&&&\cr +\strut&&&\multispan{3} &&&&\multispan{5}&&&\cr +\multispan{17}\hrulefill\cr +\strut&\multispan{15}&\cr +&\multispan{15}\hfil Target Hardware\hfil&\cr +\strut&\multispan{15}&\cr +\multispan{17}\hrulefill\cr +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<IMG SRC="rtemsarc.gif" WIDTH=500 HEIGHT=300 ALT="RTEMS Application Architecture"> +@end html +@end ifset + +@ifinfo +@node Overview RTEMS Internal Architecture, Overview User Customization and Extensibility, Overview RTEMS Application Architecture, Overview +@end ifinfo +@section RTEMS Internal Architecture + +RTEMS can be viewed as a set of layered components that work in +harmony to provide a set of services to a real-time application +system. The executive interface presented to the application is +formed by grouping directives into logical sets called resource managers. +Functions utilized by multiple managers such as scheduling, +dispatching, and object management are provided in the executive +core. The executive core depends on a small set of CPU dependent routines. +Together these components provide a powerful run time +environment that promotes the development of efficient real-time +application systems. The following figure illustrates this organization: + +@ifset use-ascii +@example +@group + +-----------------------------------------------+ + | RTEMS Executive Interface | + +-----------------------------------------------+ + | RTEMS Core | + +-----------------------------------------------+ + | CPU Dependent Code | + +-----------------------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@c for now use the ascii version +@example +@group + +-----------------------------------------------+ + | RTEMS Executive Interface | + +-----------------------------------------------+ + | RTEMS Core | + +-----------------------------------------------+ + | CPU Dependent Code | + +-----------------------------------------------+ +@end group +@end example +@tex +@end tex +@end ifset + +@ifset use-html +@html +<IMG SRC="rtemspie.gif" WIDTH=500 HEIGHT=300 ALT="RTEMS Architecture"> +@end html +@end ifset +Subsequent chapters present a detailed description of the capabilities +provided by each of the following RTEMS managers: + +@itemize @bullet +@item initialization +@item task +@item interrupt +@item clock +@item timer +@item semaphore +@item message +@item event +@item signal +@item partition +@item region +@item dual ported memory +@item I/O +@item fatal error +@item rate monotonic +@item user extensions +@item multiprocessing +@end itemize + +@ifinfo +@node Overview User Customization and Extensibility, Overview Portability, Overview RTEMS Internal Architecture, Overview +@end ifinfo +@section User Customization and Extensibility + +As thirty-two bit microprocessors have decreased in +cost, they have become increasingly common in a variety of +embedded systems. A wide range of custom and general-purpose +processor boards are based on various thirty-two bit processors. +RTEMS was designed to make no assumptions concerning the +characteristics of individual microprocessor families or of +specific support hardware. In addition, RTEMS allows the system +developer a high degree of freedom in customizing and extending +its features. + +RTEMS assumes the existence of a supported +microprocessor and sufficient memory for both RTEMS and the +real-time application. Board dependent components such as +clocks, interrupt controllers, or I/O devices can be easily +integrated with RTEMS. The customization and extensibility +features allow RTEMS to efficiently support as many environments +as possible. + +@ifinfo +@node Overview Portability, Overview Memory Requirements, Overview User Customization and Extensibility, Overview +@end ifinfo +@section Portability + +The issue of portability was the major factor in the +creation of RTEMS. Since RTEMS is designed to isolate the +hardware dependencies in the specific board support packages, +the real-time application should be easily ported to any other +processor. The use of RTEMS allows the development of real-time +applications which can be completely independent of a particular +microprocessor architecture. + +@ifinfo +@node Overview Memory Requirements, Overview Audience, Overview Portability, Overview +@end ifinfo +@section Memory Requirements + +Since memory is a critical resource in many real-time +embedded systems, RTEMS was specifically designed to allow +unused managers to be excluded from the run-time environment. +This allows the application designer the flexibility to tailor +RTEMS to most efficiently meet system requirements while still +satisfying even the most stringent memory constraints. As a +result, the size of the RTEMS executive is application +dependent. A worksheet is provided in the Memory Requirements +chapter of the C Applications Supplement document for a specific +target processor. The worksheet is used to calculate the memory +requirements of a custom RTEMS run-time environment. The +following managers may be optionally excluded: + +@itemize @bullet +@item clock +@item timer +@item semaphore +@item message +@item event +@item signal +@item partition +@item region +@item dual ported memory +@item I/O +@item rate monotonic +@item fatal error +@item multiprocessing +@end itemize + +RTEMS utilizes memory for both code and data space. +Although RTEMS' data space must be in RAM, its code space can be +located in either ROM or RAM. + +@ifinfo +@node Overview Audience, Overview Conventions, Overview Memory Requirements, Overview +@end ifinfo +@section Audience + +This manual was written for experienced real-time +software developers. Although some background is provided, it +is assumed that the reader is familiar with the concepts of task +management as well as intertask communication and +synchronization. Since directives, user related data +structures, and examples are presented in C, a basic +understanding of the C programming language is required to fully +understand the material presented. However, because of the +similarity of the Ada and C RTEMS implementations, users will +find that the use and behavior of the two implementations is +very similar. A working knowledge of the target processor is +helpful in understanding some of RTEMS' features. A thorough +understanding of the executive cannot be obtained without +studying the entire manual because many of RTEMS' concepts and +features are interrelated. Experienced RTEMS users will find +that the manual organization facilitates its use as a reference +document. + +@ifinfo +@node Overview Conventions, Overview Manual Organization, Overview Audience, Overview +@end ifinfo +@section Conventions + +The following conventions are used in this manual: + +@itemize @bullet +@item Significant words or phrases as well as all directive +names are printed in bold type. + +@item Items in bold capital letters are constants defined by +RTEMS. Each language interface provided by RTEMS includes a +file containing the standard set of constants, data types, and +structure definitions which can be incorporated into the user +application. + +@item A number of type definitions are provided by RTEMS and +can be found in rtems.h. + +@item The characters "0x" preceding a number indicates that +the number is in hexadecimal format. Any other numbers are +assumed to be in decimal format. +@end itemize + +@ifinfo +@node Overview Manual Organization, Key Concepts, Overview Conventions, Overview +@end ifinfo +@section Manual Organization + +This first chapter has presented the introductory and +background material for the RTEMS executive. The remaining +chapters of this manual present a detailed description of RTEMS +and the environment, including run time behavior, it creates for +the user. + +A chapter is dedicated to each manager and provides a +detailed discussion of each RTEMS manager and the directives +which it provides. The presentation format for each directive +includes the following sections: + +@itemize @bullet +@item Calling sequence +@item Directive status codes +@item Description +@item Notes +@end itemize + +The following provides an overview of the remainder +of this manual: + +@table @asis +@item Chapter 2 +Key Concepts: presents an +introduction to the ideas which are common across multiple RTEMS +managers. + +@item Chapter 3: +Initialization Manager: describes the functionality and directives +provided by the Initialization Manager. + +@item Chapter 4: +Task Manager: describes the functionality and directives provided +by the Task Manager. + +@item Chapter 5: +Interrupt Manager: describes the functionality and directives +provided by the Interrupt Manager. + +@item Chapter 6: +Clock Manager: describes the functionality and directives +provided by the Clock Manager. + +@item Chapter 7 +Timer Manager: describes the functionality and directives provided +by the Timer Manager. + +@item Chapter 8: +Semaphore Manager: describes the functionality and directives +provided by the Semaphore Manager. + +@item Chapter 9: +Message Manager: describes the functionality and directives +provided by the Message Manager. + +@item Chapter 10: +Event Manager: describes the +functionality and directives provided by the Event Manager. + +@item Chapter 11: +Signal Manager: describes the +functionality and directives provided by the Signal Manager. + +@item Chapter 12: +Partition Manager: describes the +functionality and directives provided by the Partition Manager. + +@item Chapter 13: +Region Manager: describes the +functionality and directives provided by the Region Manager. + +@item Chapter 14: +Dual-Ported Memory Manager: describes +the functionality and directives provided by the Dual-Ported +Memory Manager. + +@item Chapter 15: +I/O Manager: describes the +functionality and directives provided by the I/O Manager. + +@item Chapter 16: +Fatal Error Manager: describes the functionality and directives +provided by the Fatal Error Manager. + +@item Chapter 17: +Scheduling Concepts: details the RTEMS scheduling algorithm and +task state transitions. + +@item Chapter 18: +Rate Monotonic Manager: describes the functionality and directives +provided by the Rate Monotonic Manager. + +@item Chapter 19: +Board Support Packages: defines the +functionality required of user-supplied board support packages. + +@item Chapter 20: +User Extensions: shows the user how to +extend RTEMS to incorporate custom features. + +@item Chapter 21: +Configuring a System: details the process by which one tailors RTEMS +for a particular single-processor or multiprocessor application. + +@item Chapter 22: +Multiprocessing Manager: presents a +conceptual overview of the multiprocessing capabilities provided +by RTEMS as well as describing the Multiprocessing +Communications Interface Layer and Multiprocessing Manager +directives. + +@item Chapter 23: +Directive Status Codes: provides a definition of each of the +directive status codes referenced in this manual. + +@item Chapter 24: +Example Application: provides a template for simple RTEMS applications. + +@item Chapter 25: +Glossary: defines terms used throughout this manual. + +@end table + + diff --git a/doc/user/part.t b/doc/user/part.t new file mode 100644 index 0000000000..302f426497 --- /dev/null +++ b/doc/user/part.t @@ -0,0 +1,423 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Partition Manager, Partition Manager Introduction, SIGNAL_SEND - Send signal set to a task, Top +@end ifinfo +@chapter Partition Manager +@ifinfo +@menu +* Partition Manager Introduction:: +* Partition Manager Background:: +* Partition Manager Operations:: +* Partition Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Partition Manager Introduction, Partition Manager Background, Partition Manager, Partition Manager +@end ifinfo +@section Introduction + +The partition manager provides facilities to +dynamically allocate memory in fixed-size units. The directives +provided by the partition manager are: + +@itemize @bullet +@item @code{partition_create} - Create a partition +@item @code{partition_ident} - Get ID of a partition +@item @code{partition_delete} - Delete a partition +@item @code{partition_get_buffer} - Get buffer from a partition +@item @code{partition_return_buffer} - Return buffer to a partition +@end itemize + +@ifinfo +@node Partition Manager Background, Partition Manager Definitions, Partition Manager Introduction, Partition Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Partition Manager Definitions:: +* Building a Partition's Attribute Set:: +@end menu +@end ifinfo + +@ifinfo +@node Partition Manager Definitions, Building a Partition's Attribute Set, Partition Manager Background, Partition Manager Background +@end ifinfo +@subsection Partition Manager Definitions + +A partition is a physically contiguous memory area +divided into fixed-size buffers that can be dynamically +allocated and deallocated. + +Partitions are managed and maintained as a list of +buffers. Buffers are obtained from the front of the partition's +free buffer chain and returned to the rear of the same chain. +When a buffer is on the free buffer chain, RTEMS uses eight +bytes of each buffer as the free buffer chain. When a buffer is +allocated, the entire buffer is available for application use. +Therefore, modifying memory that is outside of an allocated +buffer could destroy the free buffer chain or the contents of an +adjacent allocated buffer. + +@ifinfo +@node Building a Partition's Attribute Set, Partition Manager Operations, Partition Manager Definitions, Partition Manager Background +@end ifinfo +@subsection Building a Partition's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid partition +attributes is provided in the following table: + +@itemize @bullet +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + + + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An attribute listed as a default is not +required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all +defaults are desired, the attribute DEFAULT_ATTRIBUTES should be +specified on this call. The attribute_set parameter should be +GLOBAL to indicate that the partition is to be known globally. + +@ifinfo +@node Partition Manager Operations, Creating a Partition, Building a Partition's Attribute Set, Partition Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Partition:: +* Obtaining Partition IDs:: +* Acquiring a Buffer:: +* Releasing a Buffer:: +* Deleting a Partition:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Partition, Obtaining Partition IDs, Partition Manager Operations, Partition Manager Operations +@end ifinfo +@subsection Creating a Partition + +The partition_create directive creates a partition +with a user-specified name. The partition's name, starting +address, length and buffer size are all specified to the +partition_create directive. RTEMS allocates a Partition Control +Block (PTCB) from the PTCB free list. This data structure is +used by RTEMS to manage the newly created partition. The number +of buffers in the partition is calculated based upon the +specified partition length and buffer size, and returned to the +calling task along with a unique partition ID. + +@ifinfo +@node Obtaining Partition IDs, Acquiring a Buffer, Creating a Partition, Partition Manager Operations +@end ifinfo +@subsection Obtaining Partition IDs + +When a partition is created, RTEMS generates a unique +partition ID and assigned it to the created partition until it +is deleted. The partition ID may be obtained by either of two +methods. First, as the result of an invocation of the +partition_create directive, the partition ID is stored in a user +provided location. Second, the partition ID may be obtained +later using the partition_ident directive. The partition ID is +used by other partition manager directives to access this +partition. + +@ifinfo +@node Acquiring a Buffer, Releasing a Buffer, Obtaining Partition IDs, Partition Manager Operations +@end ifinfo +@subsection Acquiring a Buffer + +A buffer can be obtained by calling the +partition_get_buffer directive. If a buffer is available, then +it is returned immediately with a successful return code. +Otherwise, an unsuccessful return code is returned immediately +to the caller. Tasks cannot block to wait for a buffer to +become available. + +@ifinfo +@node Releasing a Buffer, Deleting a Partition, Acquiring a Buffer, Partition Manager Operations +@end ifinfo +@subsection Releasing a Buffer + +Buffers are returned to a partition's free buffer +chain with the partition_return_buffer directive. This +directive returns an error status code if the returned buffer +was not previously allocated from this partition. + +@ifinfo +@node Deleting a Partition, Partition Manager Directives, Releasing a Buffer, Partition Manager Operations +@end ifinfo +@subsection Deleting a Partition + +The partition_delete directive allows a partition to +be removed and returned to RTEMS. When a partition is deleted, +the PTCB for that partition is returned to the PTCB free list. +A partition with buffers still allocated cannot be deleted. Any +task attempting to do so will be returned an error status code. + +@ifinfo +@node Partition Manager Directives, PARTITION_CREATE - Create a partition, Deleting a Partition, Partition Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* PARTITION_CREATE - Create a partition:: +* PARTITION_IDENT - Get ID of a partition:: +* PARTITION_DELETE - Delete a partition:: +* PARTITION_GET_BUFFER - Get buffer from a partition:: +* PARTITION_RETURN_BUFFER - Return buffer to a partition:: +@end menu +@end ifinfo + +This section details the partition manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node PARTITION_CREATE - Create a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives, Partition Manager Directives +@end ifinfo +@subsection PARTITION_CREATE - Create a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_create( + rtems_name name, + void *starting_address, + rtems_unsigned32 length, + rtems_unsigned32 buffer_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - partition created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{TOO_MANY} - too many partitions created@* +@code{INVALID_ADDRESS} - address not on four byte boundary@* +@code{INVALID_SIZE} - length or buffer size is 0@* +@code{INVALID_SIZE} - length is less than the buffer size@* +@code{INVALID_SIZE} - buffer size not a multiple of 4@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: + +This directive creates a partition of fixed size +buffers from a physically contiguous memory space which starts +at starting_address and is length bytes in size. Each allocated +buffer is to be of buffer_length in bytes. The assigned +partition id is returned in id. This partition id is used to +access the partition with other partition related directives. +For control and maintenance of the partition, RTEMS allocates a +PTCB from the local PTCB free pool and initializes it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The starting_address and buffer_size parameters must +be multiples of four. + +Memory from the partition is not used by RTEMS to +store the Partition Control Block. + +The following partition attribute constants are +defined by RTEMS: + +@itemize @bullet +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + +The PTCB for a global partition is allocated on the +local node. The memory space used for the partition must reside +in shared memory. Partitions should not be made global unless +remote tasks must interact with the partition. This is to avoid +the overhead incurred by the creation of a global partition. +When a global partition is created, the partition's name and id +must be transmitted to every node in the system for insertion in +the local copy of the global object table. + +The total number of global objects, including +partitions, is limited by the maximum_global_objects field in +the Configuration Table. + +@page +@ifinfo +@node PARTITION_IDENT - Get ID of a partition, PARTITION_DELETE - Delete a partition, PARTITION_CREATE - Create a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_IDENT - Get ID of a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - partition identified successfully@* +@code{INVALID_NAME} - partition name not found@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: + +This directive obtains the partition id associated +with the partition name. If the partition name is not unique, +then the partition id will match one of the partitions with that +name. However, this partition id is not guaranteed to +correspond to the desired partition. The partition id is used +with other partition related directives to access the partition. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched +with the local node being searched first. All other nodes are +searched with the lowest numbered node searched first. + +If node is a valid node number which does not +represent the local node, then only the partitions exported by +the designated node are searched. + +This directive does not generate activity on remote +nodes. It accesses only the local copy of the global object +table. + +@page +@ifinfo +@node PARTITION_DELETE - Delete a partition, PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_IDENT - Get ID of a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_DELETE - Delete a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - partition deleted successfully@* +@code{INVALID_ID} - invalid partition id@* +@code{RESOURCE_IN_USE} - buffers still in use@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote partition + +@subheading DESCRIPTION: + +This directive deletes the partition specified by id. +The partition cannot be deleted if any of its buffers are still +allocated. The PTCB for the deleted partition is reclaimed by +RTEMS. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The calling task does not have to be the task that +created the partition. Any local task that knows the partition +id can delete the partition. + +When a global partition is deleted, the partition id +must be transmitted to every node in the system for deletion +from the local copy of the global object table. + +The partition must reside on the local node, even if +the partition was created with the GLOBAL option. + +@page +@ifinfo +@node PARTITION_GET_BUFFER - Get buffer from a partition, PARTITION_RETURN_BUFFER - Return buffer to a partition, PARTITION_DELETE - Delete a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_GET_BUFFER - Get buffer from a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_get_buffer( + rtems_id id, + void **buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - buffer obtained successfully@* +@code{INVALID_ID} - invalid partition id@* +@code{UNSATISFIED} - all buffers are allocated + +@subheading DESCRIPTION: + +This directive allows a buffer to be obtained from +the partition specified in id. The address of the allocated +buffer is returned in buffer. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +All buffers begin on a four byte boundary. + +A task cannot wait on a buffer to become available. + +Getting a buffer from a global partition which does +not reside on the local node will generate a request telling the +remote node to allocate a buffer from the specified partition. + +@page +@ifinfo +@node PARTITION_RETURN_BUFFER - Return buffer to a partition, Region Manager, PARTITION_GET_BUFFER - Get buffer from a partition, Partition Manager Directives +@end ifinfo +@subsection PARTITION_RETURN_BUFFER - Return buffer to a partition + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_partition_return_buffer( + rtems_id id, + void *buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - buffer returned successfully@* +@code{INVALID_ID} - invalid partition id@* +@code{INVALID_ADDRESS} - buffer address not in partition + +@subheading DESCRIPTION: + +This directive returns the buffer specified by buffer +to the partition specified by id. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +Returning a buffer to a global partition which does +not reside on the local node will generate a request telling the +remote node to return the buffer to the specified partition. diff --git a/doc/user/preface.texi b/doc/user/preface.texi new file mode 100644 index 0000000000..c9154192a6 --- /dev/null +++ b/doc/user/preface.texi @@ -0,0 +1,173 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Preface, Overview, Top, Top +@end ifinfo +@unnumbered Preface + +In recent years, the cost required to develop a +software product has increased significantly while the target +hardware costs have decreased. Now a larger portion of money is +expended in developing, using, and maintaining software. The +trend in computing costs is the complete dominance of software +over hardware costs. Because of this, it is necessary that +formal disciplines be established to increase the probability +that software is characterized by a high degree of correctness, +maintainability, and portability. In addition, these +disciplines must promote practices that aid in the consistent +and orderly development of a software system within schedule and +budgetary constraints. To be effective, these disciplines must +adopt standards which channel individual software efforts toward +a common goal. + +The push for standards in the software development +field has been met with various degrees of success. The +Microprocessor Operating Systems Interfaces (MOSI) effort has +experienced only limited success. As popular as the UNIX +operating system has grown, the attempt to develop a standard +interface definition to allow portable application development +has only recently begun to produce the results needed in this +area. Unfortunately, very little effort has been expended to +provide standards addressing the needs of the real-time +community. Several organizations have addressed this need +during recent years. + +The Real Time Executive Interface Definition (RTEID) +was developed by Motorola with technical input from Software +Components Group. RTEID was adopted by the VMEbus International +Trade Association (VITA) as a baseline draft for their proposed +standard multiprocessor, real-time executive interface, Open +Real-Time Kernel Interface Definition (ORKID). These two groups +are currently working together with the IEEE P1003.4 committee +to insure that the functionality of their proposed standards is +adopted as the real-time extensions to POSIX. + +This emerging standard defines an interface for the +development of real-time software to ease the writing of +real-time application programs that are directly portable across +multiple real-time executive implementations. This interface +includes both the source code interfaces and run-time behavior +as seen by a real-time application. It does not include the +details of how a kernel implements these functions. The +standard's goal is to serve as a complete definition of external +interfaces so that application code that conforms to these +interfaces will execute properly in all real-time executive +environments. With the use of a standards compliant executive, +routines that acquire memory blocks, create and manage message +queues, establish and use semaphores, and send and receive +signals need not be redeveloped for a different real-time +environment as long as the new environment is compliant with the +standard. Software developers need only concentrate on the +hardware dependencies of the real-time system. Furthermore, +most hardware dependencies for real-time applications can be +localized to the device drivers. + +A compliant executive provides simple and flexible +real-time multiprocessing. It easily lends itself to both +tightly-coupled and loosely-coupled configurations (depending on +the system hardware configuration). Objects such as tasks, +queues, events, signals, semaphores, and memory blocks can be +designated as global objects and accessed by any task regardless +of which processor the object and the accessing task reside. + +The acceptance of a standard for real-time executives +will produce the same advantages enjoyed from the push for UNIX +standardization by AT&T's System V Interface Definition and +IEEE's POSIX efforts. A compliant multiprocessing executive +will allow close coupling between UNIX systems and real-time +executives to provide the many benefits of the UNIX development +environment to be applied to real-time software development. +Together they provide the necessary laboratory environment to +implement real-time, distributed, embedded systems using a wide +variety of computer architectures. + +A study was completed in 1988, within the Research, +Development, and Engineering Center, U.S. Army Missile Command, +which compared the various aspects of the Ada programming +language as they related to the application of Ada code in +distributed and/or multiple processing systems. Several +critical conclusions were derived from the study. These +conclusions have a major impact on the way the Army develops +application software for embedded applications. These impacts +apply to both in-house software development and contractor +developed software. + +A conclusion of the analysis, which has been +previously recognized by other agencies attempting to utilize +Ada in a distributed or multiprocessing environment, is that the +Ada programming language does not adequately support +multiprocessing. Ada does provide a mechanism for +multi-tasking, however, this capability exists only for a single +processor system. The language also does not have inherent +capabilities to access global named variables, flags or program +code. These critical features are essential in order for data +to be shared between processors. However, these drawbacks do +have workarounds which are sometimes awkward and defeat the +intent of software maintainability and portability goals. + +Another conclusion drawn from the analysis, was that +the run time executives being delivered with the Ada compilers +were too slow and inefficient to be used in modern missile +systems. A run time executive is the core part of the run time +system code, or operating system code, that controls task +scheduling, input/output management and memory management. +Traditionally, whenever efficient executive (also known as +kernel) code was required by the application, the user developed +in-house software. This software was usually written in +assembly language for optimization. + +Because of this shortcoming in the Ada programming +language, software developers in research and development and +contractors for project managed systems, are mandated by +technology to purchase and utilize off-the-shelf third party +kernel code. The contractor, and eventually the Government, +must pay a licensing fee for every copy of the kernel code used +in an embedded system. + +The main drawback to this development environment is +that the Government does not own, nor has the right to modify +code contained within the kernel. V&V techniques in this +situation are more difficult than if the complete source code +were available. Responsibility for system failures due to faulty +software is yet another area to be resolved under this +environment. + +The Guidance and Control Directorate began a software +development effort to address these problems. A project to +develop an experimental run time kernel was begun that will +eliminate the major drawbacks of the Ada programming language +mentioned above. The Real Time Executive for Multiprocessor Systems +(RTEMS) provides full capabilities for management of tasks, +interrupts, time, and multiple processors in addition to those +features typical of generic operating systems. The code is +Government owned, so no licensing fees are necessary. RTEMS has +been implemented in both the Ada and C programming languages. +It has been ported to the Motorola MC68xxx family, the Intel +i80386 and above, and the Intel i80960 family. Support for +other processor families, including RISC, CISC, and DSP, is +planned. Since almost all of RTEMS is written in a high level +language, ports to additional processor families require minimal +effort. + +RTEMS multiprocessor support is capable of handling +either homogeneous or heterogeneous systems. The kernel +automatically compensates for architectural differences (byte +swapping, etc.) between processors. This allows a much easier +transition from one processor family to another without a major +system redesign. + +Since the proposed standards are still in draft form, +RTEMS cannot and does not claim compliance. However, the status +of the standard is being carefully monitored to guarantee that +RTEMS provides the functionality specified in the standard. +Once approved, RTEMS will be made compliant. + +This document is a detailed users guide for a +functionally compliant real-time multiprocessor executive. It +describes the user interface and run-time behavior of Release +@value{RTEMS-RELEASE} of the C implementation of RTEMS. + diff --git a/doc/user/region.t b/doc/user/region.t new file mode 100644 index 0000000000..22a24cfb95 --- /dev/null +++ b/doc/user/region.t @@ -0,0 +1,601 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Region Manager, Region Manager Introduction, PARTITION_RETURN_BUFFER - Return buffer to a partition, Top +@end ifinfo +@chapter Region Manager +@ifinfo +@menu +* Region Manager Introduction:: +* Region Manager Background:: +* Region Manager Operations:: +* Region Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Region Manager Introduction, Region Manager Background, Region Manager, Region Manager +@end ifinfo +@section Introduction + +The region manager provides facilities to dynamically +allocate memory in variable sized units. The directives +provided by the region manager are: + +@itemize @bullet +@item @code{region_create} - Create a region +@item @code{region_ident} - Get ID of a region +@item @code{region_delete} - Delete a region +@item @code{region_extend} - Add memory to a region +@item @code{region_get_segment} - Get segment from a region +@item @code{region_return_segment} - Return segment to a region +@item @code{region_get_segment_size} - Obtain size of a segment +@end itemize + +@ifinfo +@node Region Manager Background, Region Manager Definitions, Region Manager Introduction, Region Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Region Manager Definitions:: +* Building an Attribute Set:: +* Building an Option Set:: +@end menu +@end ifinfo + +@ifinfo +@node Region Manager Definitions, Building an Attribute Set, Region Manager Background, Region Manager Background +@end ifinfo +@subsection Region Manager Definitions + +A region makes up a physically contiguous memory +space with user-defined boundaries from which variable-sized +segments are dynamically allocated and deallocated. A segment +is a variable size section of memory which is allocated in +multiples of a user-defined page size. This page size is +required to be a multiple of four greater than or equal to four. +For example, if a request for a 350-byte segment is made in a +region with 256-byte pages, then a 512-byte segment is allocated. + +Regions are organized as doubly linked chains of +variable sized memory blocks. Memory requests are allocated +using a first-fit algorithm. If available, the requester +receives the number of bytes requested (rounded up to the next +page size). RTEMS requires some overhead from the region's +memory for each segment that is allocated. Therefore, an +application should only modify the memory of a segment that has +been obtained from the region. The application should NOT +modify the memory outside of any obtained segments and within +the region's boundaries while the region is currently active in +the system. + +Upon return to the region, the free block is +coalesced with its neighbors (if free) on both sides to produce +the largest possible unused block. + +@ifinfo +@node Building an Attribute Set, Building an Option Set, Region Manager Definitions, Region Manager Background +@end ifinfo +@subsection Building an Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The set of valid region +attributes is provided in the following table: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@end itemize + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An attribute listed as a default is not +required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all +defaults are desired, the attribute DEFAULT_ATTRIBUTES should be +specified on this call. + +This example demonstrates the attribute_set parameter +needed to create a region with the task priority waiting queue +discipline. The attribute_set parameter to the region_create +directive should be PRIORITY. + +@ifinfo +@node Building an Option Set, Region Manager Operations, Building an Attribute Set, Region Manager Background +@end ifinfo +@subsection Building an Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +region_get_segment directive are listed in the following table: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +Option values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each option appears exactly once in +the component list. An option listed as a default is not +required to appear in the option list, although it is a good +programming practice to specify default options. If all +defaults are desired, the option DEFAULT_OPTIONS should be +specified on this call. + +This example demonstrates the option parameter needed +to poll for a segment. The option parameter passed to the +region_get_segment directive should be NO_WAIT. + +@ifinfo +@node Region Manager Operations, Creating a Region, Building an Option Set, Region Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Region:: +* Obtaining Region IDs:: +* Adding Memory to a Region:: +* Acquiring a Segment:: +* Releasing a Segment:: +* Obtaining the Size of a Segment:: +* Deleting a Region:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Region, Obtaining Region IDs, Region Manager Operations, Region Manager Operations +@end ifinfo +@subsection Creating a Region + +The region_create directive creates a region with the +user-defined name. The user may select FIFO or task priority as +the method for placing waiting tasks in the task wait queue. +RTEMS allocates a Region Control Block (RNCB) from the RNCB free +list to maintain the newly created region. RTEMS also generates +a unique region ID which is returned to the calling task. + +It is not possible to calculate the exact number of +bytes available to the user since RTEMS requires overhead for +each segment allocated. For example, a region with one segment +that is the size of the entire region has more available bytes +than a region with two segments that collectively are the size +of the entire region. This is because the region with one +segment requires only the overhead for one segment, while the +other region requires the overhead for two segments. + +Due to automatic coalescing, the number of segments +in the region dynamically changes. Therefore, the total +overhead required by RTEMS dynamically changes. + +@ifinfo +@node Obtaining Region IDs, Adding Memory to a Region, Creating a Region, Region Manager Operations +@end ifinfo +@subsection Obtaining Region IDs + +When a region is created, RTEMS generates a unique +region ID and assigns it to the created region until it is +deleted. The region ID may be obtained by either of two +methods. First, as the result of an invocation of the +region_create directive, the region ID is stored in a user +provided location. Second, the region ID may be obtained later +using the region_ident directive. The region ID is used by +other region manager directives to access this region. + +@ifinfo +@node Adding Memory to a Region, Acquiring a Segment, Obtaining Region IDs, Region Manager Operations +@end ifinfo +@subsection Adding Memory to a Region + +The region_extend directive may be used to add memory +to an existing region. The caller specifies the size in bytes +and starting address of the memory being added. + +NOTE: Please see the release notes or RTEMS source +code for information regarding restrictions on the location of +the memory being added in relation to memory already in the +region. + +@ifinfo +@node Acquiring a Segment, Releasing a Segment, Adding Memory to a Region, Region Manager Operations +@end ifinfo +@subsection Acquiring a Segment + +The region_get_segment directive attempts to acquire +a segment from a specified region. If the region has enough +available free memory, then a segment is returned successfully +to the caller. When the segment cannot be allocated, one of the +following situations applies: + +@itemize @bullet +@item By default, the calling task will wait forever to acquire the segment. + +@item Specifying the NO_WAIT option forces an immediate return +with an error status code. + +@item Specifying a timeout limits the interval the task will +wait before returning with an error status code. +@end itemize + +If the task waits for the segment, then it is placed +in the region's task wait queue in either FIFO or task priority +order. All tasks waiting on a region are returned an error when +the message queue is deleted. + +@ifinfo +@node Releasing a Segment, Obtaining the Size of a Segment, Acquiring a Segment, Region Manager Operations +@end ifinfo +@subsection Releasing a Segment + +When a segment is returned to a region by the +region_return_segment directive, it is merged with its +unallocated neighbors to form the largest possible segment. The +first task on the wait queue is examined to determine if its +segment request can now be satisfied. If so, it is given a +segment and unblocked. This process is repeated until the first +task's segment request cannot be satisfied. + +@ifinfo +@node Obtaining the Size of a Segment, Deleting a Region, Releasing a Segment, Region Manager Operations +@end ifinfo +@subsection Obtaining the Size of a Segment + +The region_get_segment_size directive returns the +size in bytes of the specified segment. The size returned +includes any "extra" memory included in the segment because of +rounding up to a page size boundary. + +@ifinfo +@node Deleting a Region, Region Manager Directives, Obtaining the Size of a Segment, Region Manager Operations +@end ifinfo +@subsection Deleting a Region + +A region can be removed from the system and returned +to RTEMS with the region_delete directive. When a region is +deleted, its control block is returned to the RNCB free list. A +region with segments still allocated is not allowed to be +deleted. Any task attempting to do so will be returned an +error. As a result of this directive, all tasks blocked waiting +to obtain a segment from the region will be readied and returned +a status code which indicates that the region was deleted. + +@ifinfo +@node Region Manager Directives, REGION_CREATE - Create a region, Deleting a Region, Region Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* REGION_CREATE - Create a region:: +* REGION_IDENT - Get ID of a region:: +* REGION_DELETE - Delete a region:: +* REGION_EXTEND - Add memory to a region:: +* REGION_GET_SEGMENT - Get segment from a region:: +* REGION_RETURN_SEGMENT - Return segment to a region:: +* REGION_GET_SEGMENT_SIZE - Obtain size of a segment:: +@end menu +@end ifinfo + +This section details the region manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node REGION_CREATE - Create a region, REGION_IDENT - Get ID of a region, Region Manager Directives, Region Manager Directives +@end ifinfo +@subsection REGION_CREATE - Create a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + rtems_unsigned32 length, + rtems_unsigned32 page_size, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_ADDRESS} - address not on four byte boundary@* +@code{TOO_MANY} - too many regions created@* +@code{INVALID_SIZE} - invalid page size + +@subheading DESCRIPTION: + +This directive creates a region from a physically +contiguous memory space which starts at starting_address and is +length bytes long. Segments allocated from the region will be a +multiple of page_size bytes in length. The assigned region id +is returned in id. This region id is used as an argument to +other region related directives to access the region. + +For control and maintenance of the region, RTEMS +allocates and initializes an RNCB from the RNCB free pool. Thus +memory from the region is not used to store the RNCB. However, +some overhead within the region is required by RTEMS each time a +segment is constructed in the region. + +Specifying PRIORITY in attribute_set causes tasks +waiting for a segment to be serviced according to task priority. +Specifying FIFO in attribute_set or selecting +DEFAULT_ATTRIBUTES will cause waiting tasks to be serviced in +First In-First Out order. + +The starting_address parameter must be aligned on a +four byte boundary. The page_size parameter must be a multiple +of four greater than or equal to four. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following region attribute constants are defined +by RTEMS: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@end itemize + +@page +@ifinfo +@node REGION_IDENT - Get ID of a region, REGION_DELETE - Delete a region, REGION_CREATE - Create a region, Region Manager Directives +@end ifinfo +@subsection REGION_IDENT - Get ID of a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region identified successfully@* +@code{INVALID_NAME} - region name not found + +@subheading DESCRIPTION: + +This directive obtains the region id associated with +the region name to be acquired. If the region name is not +unique, then the region id will match one of the regions with +that name. However, this region id is not guaranteed to +correspond to the desired region. The region id is used to +access this region in other region manager directives. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + +@page +@ifinfo +@node REGION_DELETE - Delete a region, REGION_EXTEND - Add memory to a region, REGION_IDENT - Get ID of a region, Region Manager Directives +@end ifinfo +@subsection REGION_DELETE - Delete a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region deleted successfully@* +@code{INVALID_ID} - invalid region id@* +@code{RESOURCE_IN_USE} - segments still in use + +@subheading DESCRIPTION: + +This directive deletes the region specified by id. +The region cannot be deleted if any of its segments are still +allocated. The RNCB for the deleted region is reclaimed by +RTEMS. + +@subheading NOTES: + +This directive will not cause the calling task to be preempted. + +The calling task does not have to be the task that +created the region. Any local task that knows the region id can +delete the region. + +@page +@ifinfo +@node REGION_EXTEND - Add memory to a region, REGION_GET_SEGMENT - Get segment from a region, REGION_DELETE - Delete a region, Region Manager Directives +@end ifinfo +@subsection REGION_EXTEND - Add memory to a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_extend( + rtems_id id, + void *starting_address, + rtems_unsigned32 length +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - region extended successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_ADDRESS} - invalid address of area to add + +@subheading DESCRIPTION: + +This directive adds the memory which starts at +starting_address for length bytes to the region specified by id. + +@subheading NOTES: + +This directive will not cause the calling task to be preempted. + +The calling task does not have to be the task that +created the region. Any local task that knows the region id can +extend the region. + +@page +@ifinfo +@node REGION_GET_SEGMENT - Get segment from a region, REGION_RETURN_SEGMENT - Return segment to a region, REGION_EXTEND - Add memory to a region, Region Manager Directives +@end ifinfo +@subsection REGION_GET_SEGMENT - Get segment from a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_get_segment( + rtems_id id, + rtems_unsigned32 size, + rtems_option option_set, + rtems_interval timeout, + void **segment +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - segment obtained successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_SIZE} - request is for zero bytes or exceeds +the size of maximum segment which is possible for this region@* +@code{UNSATISFIED} - segment of requested size not available@* +@code{TIMEOUT} - timed out waiting for segment@* +@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting + +@subheading DESCRIPTION: + +This directive obtains a variable size segment from +the region specified by id. The address of the allocated +segment is returned in segment. The WAIT and NO_WAIT components +of the options parameter are used to specify whether the calling +tasks wish to wait for a segment to become available or return +immediately if no segment is available. For either option, if a +sufficiently sized segment is available, then the segment is +successfully acquired by returning immediately with the +SUCCESSFUL status code. + +If the calling task chooses to return immediately and +a segment large enough is not available, then an error code +indicating this fact is returned. If the calling task chooses +to wait for the segment and a segment large enough is not +available, then the calling task is placed on the region's +segment wait queue and blocked. If the region was created with +the PRIORITY option, then the calling task is inserted into the +wait queue according to its priority. However, if the region +was created with the FIFO option, then the calling task is +placed at the rear of the wait queue. + +The timeout parameter specifies the maximum interval +that a task is willing to wait to obtain a segment. If timeout +is set to NO_TIMEOUT, then the calling task will wait forever. + +@subheading NOTES: + +The actual length of the allocated segment may be +larger than the requested size because a segment size is always +a multiple of the region's page size. + +The following segment acquisition option constants +are defined by RTEMS: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +@page +@ifinfo +@node REGION_RETURN_SEGMENT - Return segment to a region, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, REGION_GET_SEGMENT - Get segment from a region, Region Manager Directives +@end ifinfo +@subsection REGION_RETURN_SEGMENT - Return segment to a region + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_return_segment( + rtems_id id, + void *segment +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - segment returned successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_ADDRESS} - segment address not in region + +@subheading DESCRIPTION: + +This directive returns the segment specified by +segment to the region specified by id. The returned segment is +merged with its neighbors to form the largest possible segment. +The first task on the wait queue is examined to determine if its +segment request can now be satisfied. If so, it is given a +segment and unblocked. This process is repeated until the first +task's segment request cannot be satisfied. + +@subheading NOTES: + +This directive will cause the calling task to be +preempted if one or more local tasks are waiting for a segment +and the following conditions exist: + +@itemize @bullet +@item a waiting task has a higher priority than the calling task + +@item the size of the segment required by the waiting task +is less than or equal to the size of the segment returned. +@end itemize + +@page +@ifinfo +@node REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Dual-Ported Memory Manager, REGION_RETURN_SEGMENT - Return segment to a region, Region Manager Directives +@end ifinfo +@subsection REGION_GET_SEGMENT_SIZE - Obtain size of a segment + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_region_get_segment_size( + rtems_id id, + void *segment, + rtems_unsigned32 *size +); +@end example + +@subheading DIRECTIVE STATUS CODES: + +@code{SUCCESSFUL} - segment obtained successfully@* +@code{INVALID_ID} - invalid region id@* +@code{INVALID_ADDRESS} - segment address not in region + +@subheading DESCRIPTION: + +This directive obtains the size in bytes of the specified segment. + +@subheading NOTES: + +The actual length of the allocated segment may be +larger than the requested size because a segment size is always +a multiple of the region's page size. + diff --git a/doc/user/rtemsarc.gif b/doc/user/rtemsarc.gif Binary files differnew file mode 100644 index 0000000000..fea62ecb42 --- /dev/null +++ b/doc/user/rtemsarc.gif diff --git a/doc/user/rtemspie.gif b/doc/user/rtemspie.gif Binary files differnew file mode 100644 index 0000000000..8341861b0d --- /dev/null +++ b/doc/user/rtemspie.gif diff --git a/doc/user/rtmon.t b/doc/user/rtmon.t new file mode 100644 index 0000000000..91fb23b2bf --- /dev/null +++ b/doc/user/rtmon.t @@ -0,0 +1,1148 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c Open Issues +@c - nicen up the tables +@c - use math mode to print formulas +@c + +@ifinfo +@node Rate Monotonic Manager, Rate Monotonic Manager Introduction, Scheduling Concepts Task State Transitions, Top +@end ifinfo +@chapter Rate Monotonic Manager +@ifinfo +@menu +* Rate Monotonic Manager Introduction:: +* Rate Monotonic Manager Background:: +* Rate Monotonic Manager Operations:: +* Rate Monotonic Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Rate Monotonic Manager Introduction, Rate Monotonic Manager Background, Rate Monotonic Manager, Rate Monotonic Manager +@end ifinfo +@section Introduction + +The rate monotonic manager provides facilities to +implement tasks which execute in a periodic fashion. The +directives provided by the rate monotonic manager are: + +@itemize @bullet +@item @code{rate_monotonic_create} - Create a rate monotonic period +@item @code{rate_monotonic_ident} - Get ID of a period +@item @code{rate_monotonic_cancel} - Cancel a period +@item @code{rate_monotonic_delete} - Delete a rate monotonic period +@item @code{rate_monotonic_period} - Conclude current/Start next period +@item @code{rate_monotonic_get_status} - Obtain status information on period +@end itemize + +@ifinfo +@node Rate Monotonic Manager Background, Rate Monotonic Manager Definitions, Rate Monotonic Manager Introduction, Rate Monotonic Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Rate Monotonic Manager Definitions:: +* Rate Monotonic Scheduling Algorithm:: +* Schedulability Analysis:: +* Assumptions:: +* Processor Utilization Rule:: +* Processor Utilization Rule Example:: +* First Deadline Rule:: +* First Deadline Rule Example:: +* Relaxation of Assumptions:: +* Further Reading:: +@end menu +@end ifinfo + +The rate monotonic manager provides facilities to +manage the execution of periodic tasks. This manager was +designed to support application designers who utilize the Rate +Monotonic Scheduling Algorithm (RMS) to insure that their +periodic tasks will meet their deadlines, even under transient +overload conditions. Although designed for hard real-time +systems, the services provided by the rate monotonic manager may +be used by any application which requires periodic tasks. + +@ifinfo +@node Rate Monotonic Manager Definitions, Rate Monotonic Scheduling Algorithm, Rate Monotonic Manager Background, Rate Monotonic Manager Background +@end ifinfo +@subsection Rate Monotonic Manager Definitions + +A periodic task is one which must be executed at a +regular interval. The interval between successive iterations of +the task is referred to as its period. Periodic tasks can be +characterized by the length of their period and execution time. +The period and execution time of a task can be used to determine +the processor utilization for that task. Processor utilization +is the percentage of processor time used and can be calculated +on a per-task or system-wide basis. Typically, the task's +worst-case execution time will be less than its period. For +example, a periodic task's requirements may state that it should +execute for 10 milliseconds every 100 milliseconds. Although +the execution time may be the average, worst, or best case, the +worst-case execution time is more appropriate for use when +analyzing system behavior under transient overload conditions. + +In contrast, an aperiodic task executes at irregular +intervals and has only a soft deadline. In other words, the +deadlines for aperiodic tasks are not rigid, but adequate +response times are desirable. For example, an aperiodic task +may process user input from a terminal. + +Finally, a sporadic task is an aperiodic task with a +hard deadline and minimum interarrival time. The minimum +interarrival time is the minimum period of time which exists +between successive iterations of the task. For example, a +sporadic task could be used to process the pressing of a fire +button on a joystick. The mechanical action of the fire button +insures a minimum time period between successive activations, +but the missile must be launched by a hard deadline. + +@ifinfo +@node Rate Monotonic Scheduling Algorithm, Schedulability Analysis, Rate Monotonic Manager Definitions, Rate Monotonic Manager Background +@end ifinfo +@subsection Rate Monotonic Scheduling Algorithm + +The Rate Monotonic Scheduling Algorithm (RMS) is +important to real-time systems designers because it allows one +to guarantee that a set of tasks is schedulable. A set of tasks +is said to be schedulable if all of the tasks can meet their +deadlines. RMS provides a set of rules which can be used to +perform a guaranteed schedulability analysis for a task set. +This analysis determines whether a task set is schedulable under +worst-case conditions and emphasizes the predictability of the +system's behavior. It has been proven that: + +@itemize @code{ } +@b{RMS is an optimal static priority algorithm for +scheduling independent, preemptible, periodic tasks +on a single processor.} +@end itemize + +RMS is optimal in the sense that if a set of tasks +can be scheduled by any static priority algorithm, then RMS will +be able to schedule that task set. RMS bases it schedulability +analysis on the processor utilization level below which all +deadlines can be met. + +RMS calls for the static assignment of task +priorities based upon their period. The shorter a task's +period, the higher its priority. For example, a task with a 1 +millisecond period has higher priority than a task with a 100 +millisecond period. If two tasks have the same period, than RMS +does not distinguish between the tasks. However, RTEMS +specifies that when given tasks of equal priority, the task +which has been ready longest will execute first. RMS's priority +assignment scheme does not provide one with exact numeric values +for task priorities. For example, consider the following task +set and priority assignments: + +@ifset use-ascii +@example +@group ++--------------------+---------------------+---------------------+ +| Task | Period | Priority | +| | (in milliseconds) | | ++--------------------+---------------------+---------------------+ +| 1 | 100 | Low | ++--------------------+---------------------+---------------------+ +| 2 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 3 | 50 | Medium | ++--------------------+---------------------+---------------------+ +| 4 | 25 | High | ++--------------------+---------------------+---------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.25in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Task&& \bf Period && \bf Priority &\cr +& && \bf (in milliseconds) && &\cr\noalign{\hrule} +& 1 && 100 && Low &\cr\noalign{\hrule} +& 2 && 50 && Medium &\cr\noalign{\hrule} +& 3 && 50 && Medium &\cr\noalign{\hrule} +& 4 && 25 && Low &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=3 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Task</STRONG></TD> + <TD ALIGN=center><STRONG>Period (in milliseconds)</STRONG></TD> + <TD ALIGN=center><STRONG>Priority</STRONG></TD></TR> +<TR><TD ALIGN=center>1</TD> + <TD ALIGN=center>100 </TD> + <TD ALIGN=center>Low</TD></TR> +<TR><TD ALIGN=center>2</TD> + <TD ALIGN=center>50 </TD> + <TD ALIGN=center>Medium</TD></TR> +<TR><TD ALIGN=center>3</TD> + <TD ALIGN=center>50 </TD> + <TD ALIGN=center>Medium</TD></TR> +<TR><TD ALIGN=center>4</TD> + <TD ALIGN=center>25 </TD> + <TD ALIGN=center>High</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +RMS only calls for task 1 to have the lowest +priority, task 4 to have the highest priority, and tasks 2 and 3 +to have an equal priority between that of tasks 1 and 4. The +actual RTEMS priorities assigned to the tasks must only adhere +to those guidelines. + +Many applications have tasks with both hard and soft +deadlines. The tasks with hard deadlines are typically referred +to as the critical task set, with the soft deadline tasks being +the non-critical task set. The critical task set can be +scheduled using RMS, with the non-critical tasks not executing +under transient overload, by simply assigning priorities such +that the lowest priority critical task (i.e. longest period) has +a higher priority than the highest priority non-critical task. +Although RMS may be used to assign priorities to the +non-critical tasks, it is not necessary. In this instance, +schedulability is only guaranteed for the critical task set. + +@ifinfo +@node Schedulability Analysis, Assumptions, Rate Monotonic Scheduling Algorithm, Rate Monotonic Manager Background +@end ifinfo +@subsection Schedulability Analysis + +RMS allows application designers to insure that tasks +can meet all deadlines, even under transient overload, without +knowing exactly when any given task will execute by applying +proven schedulability analysis rules. + +@lowersections + +@ifinfo +@node Assumptions, Processor Utilization Rule, Schedulability Analysis, Rate Monotonic Manager Background +@end ifinfo +@subsection Assumptions + +The schedulability analysis rules for RMS were +developed based on the following assumptions: + + +@itemize @bullet +@item The requests for all tasks for which hard deadlines +exist are periodic, with a constant interval between requests. + +@item Each task must complete before the next request for it +occurs. + +@item The tasks are independent in that a task does not depend +on the initiation or completion of requests for other tasks. + +@item The execution time for each task without preemption or +interruption is constant and does not vary. + +@item Any non-periodic tasks in the system are special. These +tasks displace periodic tasks while executing and do not have +hard, critical deadlines. +@end itemize + +Once the basic schedulability analysis is understood, +some of the above assumptions can be relaxed and the +side-effects accounted for. + +@ifinfo +@node Processor Utilization Rule, Processor Utilization Rule Example, Assumptions, Rate Monotonic Manager Background +@end ifinfo +@subsection Processor Utilization Rule + +The Processor Utilization Rule requires that +processor utilization be calculated based upon the period and +execution time of each task. The fraction of processor time +spent executing task index is Time(index) / Period(index). The +processor utilization can be calculated as follows: + +@example +@group +Utilization = 0 + +for index = 1 to maximum_tasks + Utilization = Utilization + (Time(index)/Period(index)) +@end group +@end example + +To insure schedulability even under transient +overload, the processor utilization must adhere to the following +rule: + +@example +Utilization = maximum_tasks * (2(1/maximum_tasks) - 1) +@end example + +As the number of tasks increases, the above formula +approaches ln(2) for a worst-case utilization factor of +approximately 0.693. Many tasks sets can be scheduled with a +greater utilization factor. In fact, the average processor +utilization threshold for a randomly generated task set is +approximately 0.88. + +@ifinfo +@node Processor Utilization Rule Example, First Deadline Rule, Processor Utilization Rule, Rate Monotonic Manager Background +@end ifinfo +@subsection Processor Utilization Rule Example + +This example illustrates the application of the +Processor Utilization Rule to an application with three critical +periodic tasks. The following table details the RMS priority, +period, execution time, and processor utilization for each task: + +@ifset use-ascii +@example +@group + +------------+----------+--------+-----------+-------------+ + | Task | RMS | Period | Execution | Processor | + | | Priority | | Time | Utilization | + +------------+----------+--------+-----------+-------------+ + | 1 | High | 100 | 15 | 0.15 | + +------------+----------+--------+-----------+-------------+ + | 2 | Medium | 200 | 50 | 0.25 | + +------------+----------+--------+-----------+-------------+ + | 3 | Low | 300 | 100 | 0.33 | + +------------+----------+--------+-----------+-------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr +& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule} +& 1 && High && 100 && 15 && 0.15 &\cr\noalign{\hrule} +& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule} +& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=5 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Task</STRONG></TD> + <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD> + <TD ALIGN=center><STRONG>Period</STRONG></TD> + <TD ALIGN=center><STRONG>Execution Time</STRONG></TD> + <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR> +<TR><TD ALIGN=center>1</TD> + <TD ALIGN=center>High</TD> + <TD ALIGN=center>100</TD> + <TD ALIGN=center>15</TD> + <TD ALIGN=center>0.15</TD></TR> +<TR><TD ALIGN=center>2</TD> + <TD ALIGN=center>Medium</TD> + <TD ALIGN=center>200</TD> + <TD ALIGN=center>50</TD> + <TD ALIGN=center>0.25</TD></TR> +<TR><TD ALIGN=center>3</TD> + <TD ALIGN=center>Low</TD> + <TD ALIGN=center>300</TD> + <TD ALIGN=center>100</TD> + <TD ALIGN=center>0.33</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +The total processor utilization for this task set is +0.73 which is below the upper bound of 3 * (2(1/3) - 1), or +0.779, imposed by the Processor Utilization Rule. Therefore, +this task set is guaranteed to be schedulable using RMS. + +@ifinfo +@node First Deadline Rule, First Deadline Rule Example, Processor Utilization Rule Example, Rate Monotonic Manager Background +@end ifinfo +@subsection First Deadline Rule + +If a given set of tasks do exceed the processor +utilization upper limit imposed by the Processor Utilization +Rule, they can still be guaranteed to meet all their deadlines +by application of the First Deadline Rule. This rule can be +stated as follows: + +For a given set of independent periodic tasks, if +each task meets its first deadline when all tasks are started at +the same time, then the deadlines will always be met for any +combination of start times. + +A key point with this rule is that ALL periodic tasks +are assumed to start at the exact same instant in time. +Although this assumption may seem to be invalid, RTEMS makes it +quite easy to insure. By having a non-preemptible user +initialization task, all application tasks, regardless of +priority, can be created and started before the initialization +deletes itself. This technique insures that all tasks begin to +compete for execution time at the same instant -- when the user +initialization task deletes itself. + +@ifinfo +@node First Deadline Rule Example, Relaxation of Assumptions, First Deadline Rule, Rate Monotonic Manager Background +@end ifinfo +@subsection First Deadline Rule Example + +The First Deadline Rule can insure schedulability +even when the Processor Utilization Rule fails. The example +below is a modification of the Processor Utilization Rule +example where task execution time has been increased from 15 to +25 units. The following table details the RMS priority, period, +execution time, and processor utilization for each task: + +@ifset use-ascii +@example +@group + +------------+----------+--------+-----------+-------------+ + | Task | RMS | Period | Execution | Processor | + | | Priority | | Time | Utilization | + +------------+----------+--------+-----------+-------------+ + | 1 | High | 100 | 25 | 0.25 | + +------------+----------+--------+-----------+-------------+ + | 2 | Medium | 200 | 50 | 0.25 | + +------------+----------+--------+-----------+-------------+ + | 3 | Low | 300 | 100 | 0.33 | + +------------+----------+--------+-----------+-------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Task&& \bf RMS && \bf Period && \bf Execution &&\bf Processor&\cr +& && \bf Priority && &&\bf Time &&\bf Utilization &\cr\noalign{\hrule} +& 1 && High && 100 && 25 && 0.25 &\cr\noalign{\hrule} +& 2 && Medium && 200 && 50 && 0.25 &\cr\noalign{\hrule} +& 3 && Low && 300 && 100 && 0.33 &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=5 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Task</STRONG></TD> + <TD ALIGN=center><STRONG>RMS Priority</STRONG></TD> + <TD ALIGN=center><STRONG>Period</STRONG></TD> + <TD ALIGN=center><STRONG>Execution Time</STRONG></TD> + <TD ALIGN=center><STRONG>Processor Utilization</STRONG></TD></TR> +<TR><TD ALIGN=center>1</TD> + <TD ALIGN=center>High</TD> + <TD ALIGN=center>100</TD> + <TD ALIGN=center>25</TD> + <TD ALIGN=center>0.25</TD></TR> +<TR><TD ALIGN=center>2</TD> + <TD ALIGN=center>Medium</TD> + <TD ALIGN=center>200</TD> + <TD ALIGN=center>50</TD> + <TD ALIGN=center>0.25</TD></TR> +<TR><TD ALIGN=center>3</TD> + <TD ALIGN=center>Low</TD> + <TD ALIGN=center>300</TD> + <TD ALIGN=center>100</TD> + <TD ALIGN=center>0.33</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +The total processor utilization for the modified task +set is 0.83 which is above the upper bound of 3 * (2(1/3) - 1), +or 0.779, imposed by the Processor Utilization Rule. Therefore, +this task set is not guaranteed to be schedulable using RMS. +However, the First Deadline Rule can guarantee the +schedulability of this task set. This rule calls for one to +examine each occurrence of deadline until either all tasks have +met their deadline or one task failed to meet its first +deadline. The following table details the time of each deadline +occurrence, the maximum number of times each task may have run, +the total execution time, and whether all the deadlines have +been met. + +@ifset use-ascii +@example +@group ++----------+------+------+------+----------------------+---------------+ +| Deadline | Task | Task | Task | Total | All Deadlines | +| Time | 1 | 2 | 3 | Execution Time | Met? | ++----------+------+------+------+----------------------+---------------+ +| 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO | ++----------+------+------+------+----------------------+---------------+ +| 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | ++----------+------+------+------+----------------------+---------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@sp 1 +@tex +\centerline{\vbox{\offinterlineskip\halign{ +\vrule\strut#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 0.75in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 2.00in{\enskip\hfil#\hfil}& +\vrule#& +\hbox to 1.00in{\enskip\hfil#\hfil}& +\vrule#\cr\noalign{\hrule} +&\bf Deadline&& \bf Task &&\bf Task&&\bf Task&&\bf Total &&\bf All Deadlines &\cr +&\bf Time && \bf 1 &&\bf 2 &&\bf 3 &&\bf Execution Time &&\bf Net?&\cr\noalign{\hrule} +& 100&& 1 && 1 && 1 && 25 + 50 + 100 = 175 && NO &\cr\noalign{\hrule} +& 200&& 2 && 1 && 1 && 50 + 50 + 100 = 200 && YES &\cr\noalign{\hrule} +}}\hfil} +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=6 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Deadline Time</STRONG></TD> + <TD ALIGN=center><STRONG>Task 1</STRONG></TD> + <TD ALIGN=center><STRONG>Task 2</STRONG></TD> + <TD ALIGN=center><STRONG>Task 3</STRONG></TD> + <TD ALIGN=center><STRONG>Total Execution Time</STRONG></TD> + <TD ALIGN=center><STRONG>All Deadlines Met?</STRONG></TD></TR> +<TR><TD ALIGN=center>100</TD> + <TD ALIGN=center>1</TD> + <TD ALIGN=center>1</TD> + <TD ALIGN=center>1</TD> + <TD ALIGN=center>25 + 50 + 100 = 175</TD> + <TD ALIGN=center>NO</TD></TR> +<TR><TD ALIGN=center>200</TD> + <TD ALIGN=center>2</TD> + <TD ALIGN=center>1</TD> + <TD ALIGN=center>1</TD> + <TD ALIGN=center>50 + 50 + 100 = 175</TD> + <TD ALIGN=center>YES</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +The key to this analysis is to recognize when each +task will execute. For example at time 100, task 1 must have +met its first deadline, but tasks 2 and 3 may also have begun +execution. In this example, at time 100 tasks 1 and 2 have +completed execution and thus have met their first deadline. +Tasks 1 and 2 have used (25 + 50) = 75 time units, leaving (100 +- 75) = 25 time units for task 3 to begin. Because task 3 takes +100 ticks to execute, it will not have completed execution at +time 100. Thus at time 100, all of the tasks except task 3 have +met their first deadline. + +At time 200, task 1 must have met its second deadline +and task 2 its first deadline. As a result, of the first 200 +time units, task 1 uses (2 * 25) = 50 and task 2 uses 50, +leaving (200 - 100) time units for task 3. Task 3 requires 100 +time units to execute, thus it will have completed execution at +time 200. Thus, all of the tasks have met their first deadlines +at time 200, and the task set is schedulable using the First +Deadline Rule. + +@ifinfo +@node Relaxation of Assumptions, Further Reading, First Deadline Rule Example, Rate Monotonic Manager Background +@end ifinfo +@subsection Relaxation of Assumptions + +The assumptions used to develop the RMS +schedulability rules are uncommon in most real-time systems. +For example, it was assumed that tasks have constant unvarying +execution time. It is possible to relax this assumption, simply +by using the worst-case execution time of each task. + +Another assumption is that the tasks are independent. +This means that the tasks do not wait for one another or +contend for resources. This assumption can be relaxed by +accounting for the amount of time a task spends waiting to +acquire resources. Similarly, each task's execution time must +account for any I/O performed and any RTEMS directive calls. + +In addition, the assumptions did not account for the +time spent executing interrupt service routines. This can be +accounted for by including all the processor utilization by +interrupt service routines in the utilization calculation. +Similarly, one should also account for the impact of delays in +accessing local memory caused by direct memory access and other +processors accessing local dual-ported memory. + +The assumption that nonperiodic tasks are used only +for initialization or failure-recovery can be relaxed by placing +all periodic tasks in the critical task set. This task set can +be scheduled and analyzed using RMS. All nonperiodic tasks are +placed in the non-critical task set. Although the critical task +set can be guaranteed to execute even under transient overload, +the non-critical task set is not guaranteed to execute. + +In conclusion, the application designer must be fully +cognizant of the system and its run-time behavior when +performing schedulability analysis for a system using RMS. +Every hardware and software factor which impacts the execution +time of each task must be accounted for in the schedulability +analysis. + +@ifinfo +@node Further Reading, Rate Monotonic Manager Operations, Relaxation of Assumptions, Rate Monotonic Manager Background +@end ifinfo +@subsection Further Reading + +For more information on Rate Monotonic Scheduling and +its schedulability analysis, the reader is referred to the +following: + +@itemize @code{ } +@item @cite{C. L. Liu and J. W. Layland. "Scheduling Algorithms for +Multiprogramming in a Hard Real Time Environment." @b{Journal of +the Association of Computing Machinery}. January 1973. pp. 46-61.} + +@item @cite{John Lehoczky, Lui Sha, and Ye Ding. "The Rate Monotonic +Scheduling Algorithm: Exact Characterization and Average Case +Behavior." @b{IEEE Real-Time Systems Symposium}. 1989. pp. 166-171.} + +@item @cite{Lui Sha and John Goodenough. "Real-Time Scheduling +Theory and Ada." @b{IEEE Computer}. April 1990. pp. 53-62.} + +@item @cite{Alan Burns. "Scheduling hard real-time systems: a +review." @b{Software Engineering Journal}. May 1991. pp. 116-128.} +@end itemize + +@raisesections + +@ifinfo +@node Rate Monotonic Manager Operations, Creating a Rate Monotonic Period, Further Reading, Rate Monotonic Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Rate Monotonic Period:: +* Manipulating a Period:: +* Obtaining a Period's Status:: +* Canceling a Period:: +* Deleting a Rate Monotonic Period:: +* Examples:: +* Simple Periodic Task:: +* Task with Multiple Periods:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Rate Monotonic Period, Manipulating a Period, Rate Monotonic Manager Operations, Rate Monotonic Manager Operations +@end ifinfo +@subsection Creating a Rate Monotonic Period + +The rate_monotonic_create directive creates a rate +monotonic period which is to be used by the calling task to +delineate a period. RTEMS allocates a Period Control Block +(PCB) from the PCB free list. This data structure is used by +RTEMS to manage the newly created rate monotonic period. RTEMS +returns a unique period ID to the application which is used by +other rate monotonic manager directives to access this rate +monotonic period. + +@ifinfo +@node Manipulating a Period, Obtaining a Period's Status, Creating a Rate Monotonic Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Manipulating a Period + +The rate_monotonic_period directive is used to +establish and maintain periodic execution utilizing a previously +created rate monotonic period. Once initiated by the +rate_monotonic_period directive, the period is said to run until +it either expires or is reinitiated. The state of the rate +monotonic period results in one of the following scenarios: + +@itemize @bullet +@item If the rate monotonic period is running, the calling +task will be blocked for the remainder of the outstanding period +and, upon completion of that period, the period will be +reinitiated with the specified period. + +@item If the rate monotonic period is not currently running +and has not expired, it is initiated with a length of period +ticks and the calling task returns immediately. + +@item If the rate monotonic period has expired before the task +invokes the rate_monotonic_period directive, the period will be +initiated with a length of period ticks and the calling task +returns immediately with a timeout error status. +@end itemize + +@ifinfo +@node Obtaining a Period's Status, Canceling a Period, Manipulating a Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Obtaining a Period's Status + +If the rate_monotonic_period directive is invoked +with a period of PERIOD_STATUS ticks, the current state of the +specified rate monotonic period will be returned. The following +table details the relationship between the period's status and +the directive status code returned by the rate_monotonic_period +directive: + +@itemize @bullet +@item SUCCESSFUL - period is running + +@item TIMEOUT - period has expired + +@item NOT_DEFINED - period has never been initiated +@end itemize + +Obtaining the status of a rate monotonic period does +not alter the state or length of that period. + +@ifinfo +@node Canceling a Period, Deleting a Rate Monotonic Period, Obtaining a Period's Status, Rate Monotonic Manager Operations +@end ifinfo +@subsection Canceling a Period + +The rate_monotonic_cancel directive is used to stop +the period maintained by the specified rate monotonic period. +The period is stopped and the rate monotonic period can be +reinitiated using the rate_monotonic_period directive. + +@ifinfo +@node Deleting a Rate Monotonic Period, Examples, Canceling a Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Deleting a Rate Monotonic Period + +The rate_monotonic_delete directive is used to delete +a rate monotonic period. If the period is running and has not +expired, the period is automatically canceled. The rate +monotonic period's control block is returned to the PCB free +list when it is deleted. A rate monotonic period can be deleted +by a task other than the task which created the period. + +@ifinfo +@node Examples, Simple Periodic Task, Deleting a Rate Monotonic Period, Rate Monotonic Manager Operations +@end ifinfo +@subsection Examples + +The following sections illustrate common uses of rate +monotonic periods to construct periodic tasks. + +@ifinfo +@node Simple Periodic Task, Task with Multiple Periods, Examples, Rate Monotonic Manager Operations +@end ifinfo +@subsection Simple Periodic Task + +This example consists of a single periodic task +which, after initialization, executes every 100 clock ticks. + +@page +@example +rtems_task Periodic_task() +@{ + rtems_name name; + rtems_id period; + rtems_status_code status; + + name = build_name( 'P', 'E', 'R', 'D' ); + + (void) rate_monotonic_create( name, &period ); + + while ( 1 ) @{ + if ( rate_monotonic_period( period, 100 ) == TIMEOUT ) + break; + + /* Perform some periodic actions */ + @} + + /* missed period so delete period and SELF */ + + (void) rate_monotonic_delete( period ); + (void) task_delete( SELF ); +@} +@end example + + +The above task creates a rate monotonic period as +part of its initialization. The first time the loop is +executed, the rate_monotonic_period directive will initiate the +period for 100 ticks and return immediately. Subsequent +invocations of the rate_monotonic_period directive will result +in the task blocking for the remainder of the 100 tick period. +If, for any reason, the body of the loop takes more than 100 +ticks to execute, the rate_monotonic_period directive will +return the TIMEOUT status. If the above task misses its +deadline, it will delete the rate monotonic period and itself. + +@ifinfo +@node Task with Multiple Periods, Rate Monotonic Manager Directives, Simple Periodic Task, Rate Monotonic Manager Operations +@end ifinfo +@subsection Task with Multiple Periods + +This example consists of a single periodic task +which, after initialization, performs two sets of actions every +100 clock ticks. The first set of actions is performed in the +first forty clock ticks of every 100 clock ticks, while the +second set of actions is performed between the fortieth and +seventieth clock ticks. The last thirty clock ticks are not +used by this task. + +@page +@example +task Periodic_task() +@{ + rtems_name name_1, name_2; + rtems_id period_1, period_2; + rtems_status_code status; + + name_1 = build_name( 'P', 'E', 'R', '1' ); + name_2 = build_name( 'P', 'E', 'R', '2' ); + + (void ) rate_monotonic_create( name_1, &period_1 ); + (void ) rate_monotonic_create( name_2, &period_2 ); + + while ( 1 ) @{ + if ( rate_monotonic_period( period_1, 100 ) == TIMEOUT ) + break; + + if ( rate_monotonic_period( period_2, 40 ) == TIMEOUT ) + break; + + /* + * Perform first set of actions between clock + * ticks 0 and 39 of every 100 ticks. + */ + + if ( rate_monotonic_period( period_2, 30 ) == TIMEOUT ) + break; + + /* + * Perform second set of actions between clock 40 and 69 + * of every 100 ticks. THEN ... + * + * Check to make sure we didn't miss the period_2 period. + */ + + if ( rate_monotonic_period( period_2, STATUS ) == TIMEOUT ) + break; + + (void) rate_monotonic_cancel( period_2 ); + @} + + /* missed period so delete period and SELF */ + + (void ) rate_monotonic_delete( period_1 ); + (void ) rate_monotonic_delete( period_2 ); + (void ) task_delete( SELF ); +@} +@end example + +The above task creates two rate monotonic periods as +part of its initialization. The first time the loop is +executed, the rate_monotonic_period directive will initiate the +period_1 period for 100 ticks and return immediately. +Subsequent invocations of the rate_monotonic_period directive +for period_1 will result in the task blocking for the remainder +of the 100 tick period. The period_2 period is used to control +the execution time of the two sets of actions within each 100 +tick period established by period_1. The rate_monotonic_cancel( +period_2 ) call is performed to insure that the period_2 period +does not expire while the task is blocked on the period_1 +period. If this cancel operation were not performed, every time +the rate_monotonic_period( period_1, 40 ) call is executed, +except for the initial one, a directive status of TIMEOUT is +returned. It is important to note that every time this call is +made, the period_1 period will be initiated immediately and the +task will not block. + +If, for any reason, the task misses any deadline, the +rate_monotonic_period directive will return the TIMEOUT +directive status. If the above task misses its deadline, it +will delete the rate monotonic periods and itself. + +@ifinfo +@node Rate Monotonic Manager Directives, RATE_MONOTONIC_CREATE - Create a rate monotonic period, Task with Multiple Periods, Rate Monotonic Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* RATE_MONOTONIC_CREATE - Create a rate monotonic period:: +* RATE_MONOTONIC_IDENT - Get ID of a period:: +* RATE_MONOTONIC_CANCEL - Cancel a period:: +* RATE_MONOTONIC_DELETE - Delete a rate monotonic period:: +* RATE_MONOTONIC_PERIOD - Conclude current/Start next period:: +* RATE_MONOTONIC_GET_STATUS - Obtain status information on period:: +@end menu +@end ifinfo + +This section details the rate monotonic manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node RATE_MONOTONIC_CREATE - Create a rate monotonic period, RATE_MONOTONIC_IDENT - Get ID of a period, Rate Monotonic Manager Directives, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_CREATE - Create a rate monotonic period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_create( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - rate monotonic period created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{TOO_MANY} - too many periods created + +@subheading DESCRIPTION: + +This directive creates a rate monotonic period. The +assigned rate monotonic id is returned in id. This id is used +to access the period with other rate monotonic manager +directives. For control and maintenance of the rate monotonic +period, RTEMS allocates a PCB from the local PCB free pool and +initializes it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node RATE_MONOTONIC_IDENT - Get ID of a period, RATE_MONOTONIC_CANCEL - Cancel a period, RATE_MONOTONIC_CREATE - Create a rate monotonic period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_IDENT - Get ID of a period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period identified successfully@* +@code{INVALID_NAME} - period name not found + +@subheading DESCRIPTION: + +This directive obtains the period id associated with +the period name to be acquired. If the period name is not +unique, then the period id will match one of the periods with +that name. However, this period id is not guaranteed to +correspond to the desired period. The period id is used to +access this period in other rate monotonic manager directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node RATE_MONOTONIC_CANCEL - Cancel a period, RATE_MONOTONIC_DELETE - Delete a rate monotonic period, RATE_MONOTONIC_IDENT - Get ID of a period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_CANCEL - Cancel a period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_cancel( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period canceled successfully@* +@code{INVALID_ID} - invalid rate monotonic period id@* +@code{NOT_OWNER_OF_RESOURCE} - rate monotonic period not created by calling task + +@subheading DESCRIPTION: + +This directive cancels the rate monotonic period id. +This period will be reinitiated by the next invocation of +rate_monotonic_period with id. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +The rate monotonic period specified by id must have +been created by the calling task. + +@page +@ifinfo +@node RATE_MONOTONIC_DELETE - Delete a rate monotonic period, RATE_MONOTONIC_PERIOD - Conclude current/Start next period, RATE_MONOTONIC_CANCEL - Cancel a period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_DELETE - Delete a rate monotonic period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period deleted successfully@* +@code{INVALID_ID} - invalid rate monotonic period id + +@subheading DESCRIPTION: + +This directive deletes the rate monotonic period +specified by id. If the period is running, it is automatically +canceled. The PCB for the deleted period is reclaimed by RTEMS. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +A rate monotonic period can be deleted by a task +other than the task which created the period. + +@page +@ifinfo +@node RATE_MONOTONIC_PERIOD - Conclude current/Start next period, RATE_MONOTONIC_GET_STATUS - Obtain status information on period, RATE_MONOTONIC_DELETE - Delete a rate monotonic period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_PERIOD - Conclude current/Start next period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_interval length +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period initiated successfully@* +@code{INVALID_ID} - invalid rate monotonic period id@* +@code{NOT_OWNER_OF_RESOURCE} - period not created by calling task@* +@code{NOT_DEFINED} - period has never been initiated@* +@code{TIMEOUT} - period has expired + +@subheading DESCRIPTION: + +This directive initiates the rate monotonic period id +with a length of period ticks. If id is running, then the +calling task will block for the remainder of the period before +reinitiating the period with the specified period. If id was +not running (either expired or never initiated), the period is +immediately initiated and the directive returns immediately. + +If invoked with a period of PERIOD_STATUS ticks, the +current state of id will be returned. The directive status +indicates the current state of the period. This does not alter +the state or period of the period. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + +--------------------- +@page +@ifinfo +@node RATE_MONOTONIC_GET_STATUS - Obtain status information on period, Board Support Packages, RATE_MONOTONIC_PERIOD - Conclude current/Start next period, Rate Monotonic Manager Directives +@end ifinfo +@subsection RATE_MONOTONIC_GET_STATUS - Obtain status information on period + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_rate_monotonic_period( + rtems_id id, + rtems_rate_monotonic_period_status *status +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - period initiated successfully@* +@code{INVALID_ID} - invalid rate monotonic period id@* +@code{INVALID_ADDRESS} - invalid address of status@* + +@subheading DESCRIPTION: + +This directive returns status information associated with +the rate monotonic period id in the following data structure: + +@example +typedef struct @{ + rtems_rate_monotonic_period_states state; + unsigned32 ticks_since_last_period; + unsigned32 ticks_executed_since_last_period; +@} rtems_rate_monotonic_period_status; +@end example + +If the period's state is RATE_MONOTONIC_INACTIVE, both +ticks_since_last_period and ticks_executed_since_last_period +will be set to 0. Otherwise, ticks_since_last_period will +contain the number of clock ticks which have occurred since +the last invocation of the rtems_rate_monotonic_period directive. +Also in this case, the ticks_executed_since_last_period will indicate +how much processor time the owning task has consumed since the invocation +of the rtems_rate_monotonic_period directive. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. diff --git a/doc/user/schedule.t b/doc/user/schedule.t new file mode 100644 index 0000000000..5781a670b7 --- /dev/null +++ b/doc/user/schedule.t @@ -0,0 +1,426 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c This figure is not included: +@c Figure 17-1 RTEMS Task State Transitions +@c + +@ifinfo +@node Scheduling Concepts, Scheduling Concepts Introduction, FATAL_ERROR_OCCURRED - Invoke the fatal error handler, Top +@end ifinfo +@chapter Scheduling Concepts +@ifinfo +@menu +* Scheduling Concepts Introduction:: +* Scheduling Concepts Scheduling Mechanisms:: +* Scheduling Concepts Task State Transitions:: +@end menu +@end ifinfo + +@ifinfo +@node Scheduling Concepts Introduction, Scheduling Concepts Scheduling Mechanisms, Scheduling Concepts, Scheduling Concepts +@end ifinfo +@section Introduction + +The concept of scheduling in real-time systems +dictates the ability to provide immediate response to specific +external events, particularly the necessity of scheduling tasks +to run within a specified time limit after the occurrence of an +event. For example, software embedded in life-support systems +used to monitor hospital patients must take instant action if a +change in the patient's status is detected. + +The component of RTEMS responsible for providing this +capability is appropriately called the scheduler. The +scheduler's sole purpose is to allocate the all important +resource of processor time to the various tasks competing for +attention. The RTEMS scheduler allocates the processor using a +priority-based, preemptive algorithm augmented to provide +round-robin characteristics within individual priority groups. +The goal of this algorithm is to guarantee that the task which +is executing on the processor at any point in time is the one +with the highest priority among all tasks in the ready state. + +There are two common methods of accomplishing the +mechanics of this algorithm. Both ways involve a list or chain +of tasks in the ready state. One method is to randomly place +tasks in the ready chain forcing the scheduler to scan the +entire chain to determine which task receives the processor. +The other method is to schedule the task by placing it in the +proper place on the ready chain based on the designated +scheduling criteria at the time it enters the ready state. +Thus, when the processor is free, the first task on the ready +chain is allocated the processor. RTEMS schedules tasks using +the second method to guarantee faster response times to external +events. + +@ifinfo +@node Scheduling Concepts Scheduling Mechanisms, Task Priority and Scheduling, Scheduling Concepts Introduction, Scheduling Concepts +@end ifinfo +@section Scheduling Mechanisms +@ifinfo +@menu +* Task Priority and Scheduling:: +* Preemption:: +* Timeslicing:: +* Manual Round-Robin:: +* Dispatching Tasks:: +@end menu +@end ifinfo + +RTEMS provides four mechanisms which allow the user +to impact the task scheduling process: + +@itemize @bullet +@item user-selectable task priority level +@item task preemption control +@item task timeslicing control +@item manual round-robin selection +@end itemize + +Each of these methods provides a powerful capability +to customize sets of tasks to satisfy the unique and particular +requirements encountered in custom real-time applications. +Although each mechanism operates independently, there is a +precedence relationship which governs the effects of scheduling +modifications. The evaluation order for scheduling +characteristics is always priority, preemption mode, and +timeslicing. When reading the descriptions of timeslicing and +manual round-robin it is important to keep in mind that +preemption (if enabled) of a task by higher priority tasks will +occur as required, overriding the other factors presented in the +description. + +@ifinfo +@node Task Priority and Scheduling, Preemption, Scheduling Concepts Scheduling Mechanisms, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Task Priority and Scheduling + +The most significant of these mechanisms is the +ability for the user to assign a priority level to each +individual task when it is created and to alter a task's +priority at run-time. RTEMS provides 255 priority levels. +Level 255 is the lowest priority and level 1 is the highest. +When a task is added to the ready chain, it is placed behind all +other tasks of the same priority. This rule provides a +round-robin within priority group scheduling characteristic. +This means that in a group of equal priority tasks, tasks will +execute in the order they become ready or FIFO order. Even +though there are ways to manipulate and adjust task priorities, +the most important rule to remember is: + +@itemize @code{ } +@item @b{The RTEMS scheduler will always select the highest +priority task that is ready to run when allocating the processor +to a task.} +@end itemize + +@ifinfo +@node Preemption, Timeslicing, Task Priority and Scheduling, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Preemption + +Another way the user can alter the basic scheduling +algorithm is by manipulating the preemption mode flag +(PREEMPT_MASK) of individual tasks. If preemption is disabled +for a task (NO_PREEMPT), then the task will not relinquish +control of the processor until it terminates, blocks, or +re-enables preemption. Even tasks which become ready to run and +possess higher priority levels will not be allowed to execute. +Note that the preemption setting has no effect on the manner in +which a task is scheduled. It only applies once a task has +control of the processor. + +@ifinfo +@node Timeslicing, Manual Round-Robin, Preemption, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Timeslicing + +Timeslicing or round-robin scheduling is an +additional method which can be used to alter the basic +scheduling algorithm. Like preemption, timeslicing is specified +on a task by task basis using the timeslicing mode flag +(TIMESLICE_MASK). If timeslicing is enabled for a task +(TIMESLICE), then RTEMS will limit the amount of time the task +can execute before the processor is allocated to another task. +Each tick of the real-time clock reduces the currently running +task's timeslice. When the execution time equals the timeslice, +RTEMS will dispatch another task of the same priority to +execute. If there are no other tasks of the same priority ready +to execute, then the current task is allocated an additional +timeslice and continues to run. Remember that a higher priority +task will preempt the task (unless preemption is disabled) as +soon as it is ready to run, even if the task has not used up its +entire timeslice. + +@ifinfo +@node Manual Round-Robin, Dispatching Tasks, Timeslicing, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Manual Round-Robin + +The final mechanism for altering the RTEMS scheduling +algorithm is called manual round-robin. Manual round-robin is +invoked by using the task_wake_after directive with a time +interval of YIELD_PROCESSOR. This allows a task to give up the +processor and be immediately returned to the ready chain at the +end of its priority group. If no other tasks of the same +priority are ready to run, then the task does not lose control +of the processor. + +@ifinfo +@node Dispatching Tasks, Scheduling Concepts Task State Transitions, Manual Round-Robin, Scheduling Concepts Scheduling Mechanisms +@end ifinfo +@subsection Dispatching Tasks + +The dispatcher is the RTEMS component responsible for +allocating the processor to a ready task. In order to allocate +the processor to one task, it must be deallocated or retrieved +from the task currently using it. This involves a concept +called a context switch. To perform a context switch, the +dispatcher saves the context of the current task and restores +the context of the task which has been allocated to the +processor. Saving and restoring a task's context is the +storing/loading of all the essential information about a task to +enable it to continue execution without any effects of the +interruption. For example, the contents of a task's register +set must be the same when it is given the processor as they were +when it was taken away. All of the information that must be +saved or restored for a context switch is located either in the +TCB or on the task's stacks. + +Tasks that utilize a numeric coprocessor and are +created with the FLOATING_POINT attribute require additional +operations during a context switch. These additional operations +are necessary to save and restore the floating point context of +FLOATING_POINT tasks. To avoid unnecessary save and restore +operations, the state of the numeric coprocessor is only saved +when a FLOATING_POINT task is dispatched and that task was not +the last task to utilize the coprocessor. + +@ifinfo +@node Scheduling Concepts Task State Transitions, Rate Monotonic Manager, Dispatching Tasks, Scheduling Concepts +@end ifinfo +@section Task State Transitions + +Tasks in an RTEMS system must always be in one of the +five allowable task states. These states are: executing, ready, +blocked, dormant, and non-existent. + +@ifset use-ascii +@example +@group + +-------------------------------------------------------------+ + | Non-existent | + | +-------------------------------------------------------+ | + | | | | + | | | | + | | Creating +---------+ Deleting | | + | | -------------------> | Dormant | -------------------> | | + | | +---------+ | | + | | | | | + | | Starting | | | + | | | | | + | | V Deleting | | + | | +-------> +-------+ -------------------> | | + | | Yielding / +----- | Ready | ------+ | | + | | / / +-------+ <--+ \ | | + | | / / \ \ Blocking | | + | | / / Dispatching Readying \ \ | | + | | / V \ V | | + | | +-----------+ Blocking +---------+ | | + | | | Executing | --------------> | Blocked | | | + | | +-----------+ +---------+ | | + | | | | + | | | | + | +-------------------------------------------------------+ | + | Non-existent | + +-------------------------------------------------------------+ +@end group +@end example +@end ifset + +@ifset use-tex +@c for now use the ascii version +@example +@group + +-------------------------------------------------------------+ + | Non-existent | + | +-------------------------------------------------------+ | + | | | | + | | | | + | | Creating +---------+ Deleting | | + | | -------------------> | Dormant | -------------------> | | + | | +---------+ | | + | | | | | + | | Starting | | | + | | | | | + | | V Deleting | | + | | +-------> +-------+ -------------------> | | + | | Yielding / +----- | Ready | ------+ | | + | | / / +-------+ <--+ \ | | + | | / / \ \ Blocking | | + | | / / Dispatching Readying \ \ | | + | | / V \ V | | + | | +-----------+ Blocking +---------+ | | + | | | Executing | --------------> | Blocked | | | + | | +-----------+ +---------+ | | + | | | | + | | | | + | +-------------------------------------------------------+ | + | Non-existent | + +-------------------------------------------------------------+ +@end group +@end example +@tex +@end tex +@end ifset + +@ifset use-html +@html +<IMG SRC="states.gif" WIDTH=550 HEIGHT=400 ALT="RTEMS Task States"> +@end html +@end ifset + +A task occupies the non-existent state before a +task_create has been issued on its behalf. A task enters the +non-existent state from any other state in the system when it is +deleted with the task_delete directive. While a task occupies +this state it does not have a TCB or a task ID assigned to it; +therefore, no other tasks in the system may reference this task. + +When a task is created via the task_create directive +it enters the dormant state. This state is not entered through +any other means. Although the task exists in the system, it +cannot actively compete for system resources. It will remain in +the dormant state until it is started via the task_start +directive, at which time it enters the ready state. The task is +now permitted to be scheduled for the processor and to compete +for other system resources. + +A task occupies the blocked state whenever it is +unable to be scheduled to run. A running task may block itself +or be blocked by other tasks in the system. The running task +blocks itself through voluntary operations that cause the task +to wait. The only way a task can block a task other than itself +is with the task_suspend directive. A task enters the blocked +state due to any of the following conditions: + +@itemize @bullet +@item A task issues a task_suspend directive which blocks +either itself or another task in the system. + +@item The running task issues a message_queue_receive +directive with the wait option and the message queue is empty. + +@item The running task issues an event_receive directive with +the wait option and the currently pending events do not satisfy +the request. + +@item The running task issues a semaphore_obtain directive +with the wait option and the requested semaphore is unavailable. + +@item The running task issues a task_wake_after directive +which blocks the task for the given time interval. If the time +interval specified is zero, the task yields the processor and +remains in the ready state. + +@item The running task issues a task_wake_when directive which +blocks the task until the requested date and time arrives. + +@item The running task issues a region_get_segment directive +with the wait option and there is not an available segment large +enough to satisfy the task's request. + +@item The running task issues a rate_monotonic_period +directive and must wait for the specified rate monotonic period +to conclude. +@end itemize + +A blocked task may also be suspended. Therefore, +both the suspension and the blocking condition must be removed +before the task becomes ready to run again. + +A task occupies the ready state when it is able to be +scheduled to run, but currently does not have control of the +processor. Tasks of the same or higher priority will yield the +processor by either becoming blocked, completing their +timeslice, or being deleted. All tasks with the same priority +will execute in FIFO order. A task enters the ready state due +to any of the following conditions: + +@itemize @bullet + +@item A running task issues a task_resume directive for a task +that is suspended and the task is not blocked waiting on any +resource. + +@item A running task issues a message_queue_send, +message_queue_broadcast, or a message_queue_urgent directive +which posts a message to the queue on which the blocked task is +waiting. + +@item A running task issues an event_send directive which +sends an event condition to a task which is blocked waiting on +that event condition. + +@item A running task issues a semaphore_release directive +which releases the semaphore on which the blocked task is +waiting. + +@item A timeout interval expires for a task which was blocked +by a call to the task_wake_after directive. + +@item A timeout period expires for a task which blocked by a +call to the task_wake_when directive. + +@item A running task issues a region_return_segment directive +which releases a segment to the region on which the blocked task +is waiting and a resulting segment is large enough to satisfy +the task's request. + +@item A rate monotonic period expires for a task which blocked +by a call to the rate_monotonic_period directive. + +@item A timeout interval expires for a task which was blocked +waiting on a message, event, semaphore, or segment with a +timeout specified. + +@item A running task issues a directive which deletes a +message queue, a semaphore, or a region on which the blocked +task is waiting. + +@item A running task issues a task_restart directive for the +blocked task. + +@item The running task, with its preemption mode enabled, may +be made ready by issuing any of the directives that may unblock +a task with a higher priority. This directive may be issued +from the running task itself or from an ISR. + +A ready task occupies the executing state when it has +control of the CPU. A task enters the executing state due to +any of the following conditions: + +@item The task is the highest priority ready task in the +system. + +@item The running task blocks and the task is next in the +scheduling queue. The task may be of equal priority as in +round-robin scheduling or the task may possess the highest +priority of the remaining ready tasks. + +@item The running task may reenable its preemption mode and a +task exists in the ready queue that has a higher priority than +the running task. + +@item The running task lowers its own priority and another +task is of higher priority as a result. + +@item The running task raises the priority of a task above its +own and the running task is in preemption mode. + +@end itemize diff --git a/doc/user/sem.t b/doc/user/sem.t new file mode 100644 index 0000000000..2e45af686c --- /dev/null +++ b/doc/user/sem.t @@ -0,0 +1,722 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Semaphore Manager, Semaphore Manager Introduction, TIMER_RESET - Reset an interval timer, Top +@end ifinfo +@chapter Semaphore Manager +@ifinfo +@menu +* Semaphore Manager Introduction:: +* Semaphore Manager Background:: +* Semaphore Manager Operations:: +* Semaphore Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Semaphore Manager Introduction, Semaphore Manager Background, Semaphore Manager, Semaphore Manager +@end ifinfo +@section Introduction + +The semaphore manager utilizes standard Dijkstra +counting semaphores to provide synchronization and mutual +exclusion capabilities. The directives provided by the +semaphore manager are: + +@itemize @bullet +@item @code{semaphore_create} - Create a semaphore +@item @code{semaphore_ident} - Get ID of a semaphore +@item @code{semaphore_delete} - Delete a semaphore +@item @code{semaphore_obtain} - Acquire a semaphore +@item @code{semaphore_release} - Release a semaphore +@end itemize + +@ifinfo +@node Semaphore Manager Background, Nested Resource Access, Semaphore Manager Introduction, Semaphore Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Nested Resource Access:: +* Priority Inversion:: +* Priority Inheritance:: +* Priority Ceiling:: +* Building a Semaphore's Attribute Set:: +* Building a SEMAPHORE_OBTAIN Option Set:: +@end menu +@end ifinfo + +A semaphore can be viewed as a protected variable +whose value can be modified only with the semaphore_create, +semaphore_obtain, and semaphore_release directives. RTEMS +supports both binary and counting semaphores. A binary semaphore +is restricted to values of zero or one, while a counting +semaphore can assume any non-negative integer value. + +A binary semaphore can be used to control access to a +single resource. In particular, it can be used to enforce +mutual exclusion for a critical section in user code. In this +instance, the semaphore would be created with an initial count +of one to indicate that no task is executing the critical +section of code. Upon entry to the critical section, a task +must issue the semaphore_obtain directive to prevent other tasks +from entering the critical section. Upon exit from the critical +section, the task must issue the semaphore_release directive to +allow another task to execute the critical section. + +A counting semaphore can be used to control access to +a pool of two or more resources. For example, access to three +printers could be administered by a semaphore created with an +initial count of three. When a task requires access to one of +the printers, it issues the semaphore_obtain directive to obtain +access to a printer. If a printer is not currently available, +the task can wait for a printer to become available or return +immediately. When the task has completed printing, it should +issue the semaphore_release directive to allow other tasks +access to the printer. + +Task synchronization may be achieved by creating a +semaphore with an initial count of zero. One task waits for the +arrival of another task by issuing a semaphore_obtain directive +when it reaches a synchronization point. The other task +performs a corresponding semaphore_release operation when it +reaches its synchronization point, thus unblocking the pending +task. + +@ifinfo +@node Nested Resource Access, Priority Inversion, Semaphore Manager Background, Semaphore Manager Background +@end ifinfo +@subsection Nested Resource Access + +Deadlock occurs when a task owning a binary semaphore +attempts to acquire that same semaphore and blocks as result. +Since the semaphore is allocated to a task, it cannot be +deleted. Therefore, the task that currently holds the semaphore +and is also blocked waiting for that semaphore will never +execute again. + +RTEMS addresses this problem by allowing the task +holding the binary semaphore to obtain the same binary semaphore +multiple times in a nested manner. Each semaphore_obtain must +be accompanied with a semaphore_release. The semaphore will +only be made available for acquisition by other tasks when the +outermost semaphore_obtain is matched with a semaphore_release. + + +@ifinfo +@node Priority Inversion, Priority Inheritance, Nested Resource Access, Semaphore Manager Background +@end ifinfo +@subsection Priority Inversion + +Priority inversion is a form of indefinite +postponement which is common in multitasking, preemptive +executives with shared resources. Priority inversion occurs +when a high priority tasks requests access to shared resource +which is currently allocated to low priority task. The high +priority task must block until the low priority task releases +the resource. This problem is exacerbated when the low priority +task is prevented from executing by one or more medium priority +tasks. Because the low priority task is not executing, it +cannot complete its interaction with the resource and release +that resource. The high priority task is effectively prevented +from executing by lower priority tasks. + +@ifinfo +@node Priority Inheritance, Priority Ceiling, Priority Inversion, Semaphore Manager Background +@end ifinfo +@subsection Priority Inheritance + +Priority inheritance is an algorithm that calls for +the lower priority task holding a resource to have its priority +increased to that of the highest priority task blocked waiting +for that resource. Each time a task blocks attempting to obtain +the resource, the task holding the resource may have its +priority increased. + +RTEMS supports priority inheritance for local, binary +semaphores that use the priority task wait queue blocking +discipline. When a task of higher priority than the task +holding the semaphore blocks, the priority of the task holding +the semaphore is increased to that of the blocking task. When +the task holding the task completely releases the binary +semaphore (i.e. not for a nested release), the holder's priority +is restored to the value it had before any higher priority was +inherited. + +The RTEMS implementation of the priority inheritance +algorithm takes into account the scenario in which a task holds +more than one binary semaphore. The holding task will execute +at the priority of the higher of the highest ceiling priority or +at the priority of the highest priority task blocked waiting for +any of the semaphores the task holds. Only when the task +releases ALL of the binary semaphores it holds will its priority +be restored to the normal value. + +@ifinfo +@node Priority Ceiling, Building a Semaphore's Attribute Set, Priority Inheritance, Semaphore Manager Background +@end ifinfo +@subsection Priority Ceiling + +Priority ceiling is an algorithm that calls for the +lower priority task holding a resource to have its priority +increased to that of the highest priority task which will EVER +block waiting for that resource. This algorithm addresses the +problem of priority inversion although it avoids the possibility +of changing the priority of the task holding the resource +multiple times. The priority ceiling algorithm will only change +the priority of the task holding the resource a maximum of one +time. The ceiling priority is set at creation time and must be +the priority of the highest priority task which will ever +attempt to acquire that semaphore. + +RTEMS supports priority ceiling for local, binary +semaphores that use the priority task wait queue blocking +discipline. When a task of lower priority than the ceiling +priority successfully obtains the semaphore, its priority is +raised to the ceiling priority. When the task holding the task +completely releases the binary semaphore (i.e. not for a nested +release), the holder's priority is restored to the value it had +before any higher priority was put into effect. + +The need to identify the highest priority task which +will attempt to obtain a particular semaphore can be a difficult +task in a large, complicated system. Although the priority +ceiling algorithm is more efficient than the priority +inheritance algorithm with respect to the maximum number of task +priority changes which may occur while a task holds a particular +semaphore, the priority inheritance algorithm is more forgiving +in that it does not require this apriori information. + +The RTEMS implementation of the priority ceiling +algorithm takes into account the scenario in which a task holds +more than one binary semaphore. The holding task will execute +at the priority of the higher of the highest ceiling priority or +at the priority of the highest priority task blocked waiting for +any of the semaphores the task holds. Only when the task +releases ALL of the binary semaphores it holds will its priority +be restored to the normal value. + +@ifinfo +@node Building a Semaphore's Attribute Set, Building a SEMAPHORE_OBTAIN Option Set, Priority Ceiling, Semaphore Manager Background +@end ifinfo +@subsection Building a Semaphore's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The following table lists +the set of valid semaphore attributes: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default) +@item COUNTING_SEMAPHORE - no restriction on values +@item NO_INHERIT_PRIORITY - do not use priority inheritance (default) +@item INHERIT_PRIORITY - use priority inheritance +@item PRIORITY_CEILING - use priority ceiling +@item NO_PRIORITY_CEILING - do not use priority ceiling (default) +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An attribute listed as a default is not +required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all +defaults are desired, the attribute DEFAULT_ATTRIBUTES should be +specified on this call. + +This example demonstrates the attribute_set parameter +needed to create a local semaphore with the task priority +waiting queue discipline. The attribute_set parameter passed to +the semaphore_create directive could be either PRIORITY or LOCAL +| PRIORITY. The attribute_set parameter can be set to PRIORITY +because LOCAL is the default for all created tasks. If a +similar semaphore were to be known globally, then the +attribute_set parameter would be GLOBAL | PRIORITY. + +@ifinfo +@node Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager Operations, Building a Semaphore's Attribute Set, Semaphore Manager Background +@end ifinfo +@subsection Building a SEMAPHORE_OBTAIN Option Set + +In general, an option is built by a bitwise OR of the +desired option components. The set of valid options for the +semaphore_obtain directive are listed in the following table: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +Option values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. An option listed as a default is not +required to appear in the list, although it is a good +programming practice to specify default options. If all +defaults are desired, the option DEFAULT_OPTIONS should be +specified on this call. + +This example demonstrates the option parameter needed +to poll for a semaphore. The option parameter passed to the +semaphore_obtain directive should be NO_WAIT. + +@ifinfo +@node Semaphore Manager Operations, Creating a Semaphore, Building a SEMAPHORE_OBTAIN Option Set, Semaphore Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Semaphore:: +* Obtaining Semaphore IDs:: +* Acquiring a Semaphore:: +* Releasing a Semaphore:: +* Deleting a Semaphore:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations, Semaphore Manager Operations +@end ifinfo +@subsection Creating a Semaphore + +The semaphore_create directive creates a binary or +counting semaphore with a user-specified name as well as an +initial count. If a binary semaphore is created with a count of +zero (0) to indicate that it has been allocated, then the task +creating the semaphore is considered the current holder of the +semaphore. At create time the method for ordering waiting tasks +in the semaphore's task wait queue (by FIFO or task priority) is +specified. Additionally, the priority inheritance or priority +ceiling algorithm may be selected for local, binary semaphores +that use the priority task wait queue blocking discipline. If +the priority ceiling algorithm is selected, then the highest +priority of any task which will attempt to obtain this semaphore +must be specified. RTEMS allocates a Semaphore Control Block +(SMCB) from the SMCB free list. This data structure is used by +RTEMS to manage the newly created semaphore. Also, a unique +semaphore ID is generated and returned to the calling task. + +@ifinfo +@node Obtaining Semaphore IDs, Acquiring a Semaphore, Creating a Semaphore, Semaphore Manager Operations +@end ifinfo +@subsection Obtaining Semaphore IDs + +When a semaphore is created, RTEMS generates a unique +semaphore ID and assigns it to the created semaphore until it is +deleted. The semaphore ID may be obtained by either of two +methods. First, as the result of an invocation of the +semaphore_create directive, the semaphore ID is stored in a user +provided location. Second, the semaphore ID may be obtained +later using the semaphore_ident directive. The semaphore ID is +used by other semaphore manager directives to access this +semaphore. + +@ifinfo +@node Acquiring a Semaphore, Releasing a Semaphore, Obtaining Semaphore IDs, Semaphore Manager Operations +@end ifinfo +@subsection Acquiring a Semaphore + +The semaphore_obtain directive is used to acquire the +specified semaphore. A simplified version of the +semaphore_obtain directive can be described as follows: + +@example +if semaphore's count is greater than zero + then decrement semaphore's count + else wait for release of semaphore + +return SUCCESSFUL +@end example + +When the semaphore cannot be immediately acquired, +one of the following situations applies: + +@itemize @bullet +@item By default, the calling task will wait forever to +acquire the semaphore. + +@item Specifying NO_WAIT forces an immediate return with an +error status code. + +@item Specifying a timeout limits the interval the task will +wait before returning with an error status code. +@end itemize + +If the task waits to acquire the semaphore, then it +is placed in the semaphore's task wait queue in either FIFO or +task priority order. If the task blocked waiting for a binary +semaphore using priority inheritance and the task's priority is +greater than that of the task currently holding the semaphore, +then the holding task will inherit the priority of the blocking +task. All tasks waiting on a semaphore are returned an error +code when the semaphore is deleted. + +When a task successfully obtains a semaphore using +priority ceiling and the priority ceiling for this semaphore is +greater than that of the holder, then the holder's priority will +be elevated. + +@ifinfo +@node Releasing a Semaphore, Deleting a Semaphore, Acquiring a Semaphore, Semaphore Manager Operations +@end ifinfo +@subsection Releasing a Semaphore + +The semaphore_release directive is used to release +the specified semaphore. A simplified version of the +semaphore_release directive can be described as follows: + +@example +if no tasks are waiting on this semaphore + then increment semaphore's count + else assign semaphore to a waiting task + +return SUCCESSFUL +@end example + +If this is the outermost release of a binary +semaphore that uses priority inheritance or priority ceiling and +the task does not currently hold any other binary semaphores, +then the task performing the semaphore_release will have its +priority restored to its normal value. + +@ifinfo +@node Deleting a Semaphore, Semaphore Manager Directives, Releasing a Semaphore, Semaphore Manager Operations +@end ifinfo +@subsection Deleting a Semaphore + +The semaphore_delete directive removes a semaphore +from the system and frees its control block. A semaphore can be +deleted by any local task that knows the semaphore's ID. As a +result of this directive, all tasks blocked waiting to acquire +the semaphore will be readied and returned a status code which +indicates that the semaphore was deleted. Any subsequent +references to the semaphore's name and ID are invalid. + +@ifinfo +@node Semaphore Manager Directives, SEMAPHORE_CREATE - Create a semaphore, Deleting a Semaphore, Semaphore Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* SEMAPHORE_CREATE - Create a semaphore:: +* SEMAPHORE_IDENT - Get ID of a semaphore:: +* SEMAPHORE_DELETE - Delete a semaphore:: +* SEMAPHORE_OBTAIN - Acquire a semaphore:: +* SEMAPHORE_RELEASE - Release a semaphore:: +@end menu +@end ifinfo + +This section details the semaphore manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node SEMAPHORE_CREATE - Create a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_CREATE - Create a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_create( + rtems_name name, + rtems_unsigned32 count, + rtems_attribute attribute_set, + rtems_task_priority priority_ceiling, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{TOO_MANY} - too many semaphores created@* +@code{NOT_DEFINED} - invalid attribute set@* +@code{INVALID_NUMBER} - invalid starting count for binary semaphore@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: + +This directive creates a semaphore which resides on +the local node. The created semaphore has the user-defined name +specified in name and the initial count specified in count. For +control and maintenance of the semaphore, RTEMS allocates and +initializes a SMCB. The RTEMS-assigned semaphore id is returned +in id. This semaphore id is used with other semaphore related +directives to access the semaphore. + +Specifying PRIORITY in attribute_set causes tasks +waiting for a semaphore to be serviced according to task +priority. When FIFO is selected, tasks are serviced in First +In-First Out order. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The priority inheritance and priority ceiling +algorithms are only supported for local, binary semaphores that +use the priority task wait queue blocking discipline. + +The following semaphore attribute constants are +defined by RTEMS: + +@itemize @bullet +@item FIFO - tasks wait by FIFO (default) +@item PRIORITY - tasks wait by priority +@item BINARY_SEMAPHORE - restrict values to 0 and 1 (default) +@item COUNTING_SEMAPHORE - no restriction on values +@item NO_INHERIT_PRIORITY - do not use priority inheritance (default) +@item INHERIT_PRIORITY - use priority inheritance +@item PRIORITY_CEILING - use priority ceiling +@item NO_PRIORITY_CEILING - do not use priority ceiling (default) +@item LOCAL - local task (default) +@item GLOBAL - global task +@end itemize + + + +Semaphores should not be made global unless remote +tasks must interact with the created semaphore. This is to +avoid the system overhead incurred by the creation of a global +semaphore. When a global semaphore is created, the semaphore's +name and id must be transmitted to every node in the system for +insertion in the local copy of the global object table. + +The total number of global objects, including +semaphores, is limited by the maximum_global_objects field in +the Configuration Table. + +@page +@ifinfo +@node SEMAPHORE_IDENT - Get ID of a semaphore, SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_CREATE - Create a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_IDENT - Get ID of a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore identified successfully@* +@code{INVALID_NAME} - semaphore name not found@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: + +This directive obtains the semaphore id associated +with the semaphore name. If the semaphore name is not unique, +then the semaphore id will match one of the semaphores with that +name. However, this semaphore id is not guaranteed to +correspond to the desired semaphore. The semaphore id is used +by other semaphore related directives to access the semaphore. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched +with the local node being searched first. All other nodes are +searched with the lowest numbered node searched first. + +If node is a valid node number which does not +represent the local node, then only the semaphores exported by +the designated node are searched. + +This directive does not generate activity on remote +nodes. It accesses only the local copy of the global object +table. + +@page +@ifinfo +@node SEMAPHORE_DELETE - Delete a semaphore, SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_IDENT - Get ID of a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_DELETE - Delete a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore deleted successfully@* +@code{INVALID_ID} - invalid semaphore id@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@* +@code{RESOURCE_IN_USE} - binary semaphore is in use + +@subheading DESCRIPTION: + +This directive deletes the semaphore specified by id. +All tasks blocked waiting to acquire the semaphore will be +readied and returned a status code which indicates that the +semaphore was deleted. The SMCB for this semaphore is reclaimed +by RTEMS. + +@subheading NOTES: + +The calling task will be preempted if it is enabled +by the task's execution mode and a higher priority local task is +waiting on the deleted semaphore. The calling task will NOT be +preempted if all of the tasks that are waiting on the semaphore +are remote tasks. + +The calling task does not have to be the task that +created the semaphore. Any local task that knows the semaphore +id can delete the semaphore. + +When a global semaphore is deleted, the semaphore id +must be transmitted to every node in the system for deletion +from the local copy of the global object table. + +The semaphore must reside on the local node, even if +the semaphore was created with the GLOBAL option. + +Proxies, used to represent remote tasks, are +reclaimed when the semaphore is deleted. + +@page +@ifinfo +@node SEMAPHORE_OBTAIN - Acquire a semaphore, SEMAPHORE_RELEASE - Release a semaphore, SEMAPHORE_DELETE - Delete a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_OBTAIN - Acquire a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_obtain( + rtems_id id, + rtems_unsigned32 option_set, + rtems_interval timeout +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore obtained successfully@* +@code{UNSATISFIED} - semaphore not available@* +@code{TIMEOUT} - timed out waiting for semaphore@* +@code{OBJECT_WAS_DELETED} - semaphore deleted while waiting@* +@code{INVALID_ID} - invalid semaphore id + +@subheading DESCRIPTION: + +This directive acquires the semaphore specified by +id. The WAIT and NO_WAIT components of the options parameter +indicate whether the calling task wants to wait for the +semaphore to become available or return immediately if the +semaphore is not currently available. With either WAIT or +NO_WAIT, if the current semaphore count is positive, then it is +decremented by one and the semaphore is successfully acquired by +returning immediately with a successful return code. + +If the calling task chooses to return immediately and +the current semaphore count is zero or negative, then a status +code is returned indicating that the semaphore is not available. +If the calling task chooses to wait for a semaphore and the +current semaphore count is zero or negative, then it is +decremented by one and the calling task is placed on the +semaphore's wait queue and blocked. If the semaphore was +created with the PRIORITY attribute, then the calling task is +inserted into the queue according to its priority. However, if +the semaphore was created with the FIFO attribute, then the +calling task is placed at the rear of the wait queue. If the +binary semaphore was created with the INHERIT_PRIORITY +attribute, then the priority of the task currently holding the +binary semaphore is guaranteed to be greater than or equal to +that of the blocking task. If the binary semaphore was created +with the PRIORITY_CEILING attribute, a task successfully obtains +the semaphore, and the priority of that task is greater than the +ceiling priority for this semaphore, then the priority of the +task obtaining the semaphore is elevated to that of the ceiling. + +The timeout parameter specifies the maximum interval +the calling task is willing to be blocked waiting for the +semaphore. If it is set to NO_TIMEOUT, then the calling task +will wait forever. If the semaphore is available or the NO_WAIT +option component is set, then timeout is ignored. + +@subheading NOTES: +The following semaphore acquisition option constants +are defined by RTEMS: + +@itemize @bullet +@item WAIT - task will wait for semaphore (default) +@item NO_WAIT - task should not wait +@end itemize + +Attempting to obtain a global semaphore which does not reside on +the local node will generate a request to the remote node to +access the semaphore. If the semaphore is not available and +NO_WAIT was not specified, then the task must be blocked until +the semaphore is released. A proxy is allocated on the remote +node to represent the task until the semaphore is released. + +@page +@ifinfo +@node SEMAPHORE_RELEASE - Release a semaphore, Message Manager, SEMAPHORE_OBTAIN - Acquire a semaphore, Semaphore Manager Directives +@end ifinfo +@subsection SEMAPHORE_RELEASE - Release a semaphore + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_semaphore_release( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - semaphore released successfully@* +@code{INVALID_ID} - invalid semaphore id@* +@code{NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore + +@subheading DESCRIPTION: + +This directive releases the semaphore specified by +id. The semaphore count is incremented by one. If the count is +zero or negative, then the first task on this semaphore's wait +queue is removed and unblocked. The unblocked task may preempt +the running task if the running task's preemption mode is +enabled and the unblocked task has a higher priority than the +running task. + +@subheading NOTES: + +The calling task may be preempted if it causes a +higher priority task to be made ready for execution. + +Releasing a global semaphore which does not reside on +the local node will generate a request telling the remote node +to release the semaphore. + +If the task to be unblocked resides on a different +node from the semaphore, then the semaphore allocation is +forwarded to the appropriate node, the waiting task is +unblocked, and the proxy used to represent the task is reclaimed. + +The outermost release of a local, binary, priority +inheritance or priority ceiling semaphore may result in the +calling task having its priority lowered. This will occur if +the calling task holds no other binary semaphores and it has +inherited a higher priority. + diff --git a/doc/user/signal.t b/doc/user/signal.t new file mode 100644 index 0000000000..f6a53c1967 --- /dev/null +++ b/doc/user/signal.t @@ -0,0 +1,354 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Signal Manager, Signal Manager Introduction, EVENT_RECEIVE - Receive event condition, Top +@end ifinfo +@chapter Signal Manager +@ifinfo +@menu +* Signal Manager Introduction:: +* Signal Manager Background:: +* Signal Manager Operations:: +* Signal Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager +@end ifinfo +@section Introduction + +The signal manager provides the capabilities required +for asynchronous communication. The directives provided by the +signal manager are: + +@itemize @bullet +@item @code{signal_catch} - Establish an ASR +@item @code{signal_send} - Send signal set to a task +@end itemize + +@ifinfo +@node Signal Manager Background, Signal Manager Definitions, Signal Manager Introduction, Signal Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Signal Manager Definitions:: +* A Comparison of ASRs and ISRs:: +* Building a Signal Set:: +* Building an ASR's Mode:: +@end menu +@end ifinfo + +@ifinfo +@node Signal Manager Definitions, A Comparison of ASRs and ISRs, Signal Manager Background, Signal Manager Background +@end ifinfo +@subsection Signal Manager Definitions + +The signal manager allows a task to optionally define +an asynchronous signal routine (ASR). An ASR is to a task what +an ISR is to an application's set of tasks. When the processor +is interrupted, the execution of an application is also +interrupted and an ISR is given control. Similarly, when a +signal is sent to a task, that task's execution path will be +"interrupted" by the ASR. Sending a signal to a task has no +effect on the receiving task's current execution state. + +A signal flag is used by a task (or ISR) to inform +another task of the occurrence of a significant situation. +Thirty-two signal flags are associated with each task. A +collection of one or more signals is referred to as a signal +set. A signal set is posted when it is directed (or sent) to a +task. A pending signal is a signal that has been sent to a task +with a valid ASR, but has not been processed by that task's ASR. + + +@ifinfo +@node A Comparison of ASRs and ISRs, Building a Signal Set, Signal Manager Definitions, Signal Manager Background +@end ifinfo +@subsection A Comparison of ASRs and ISRs + +The format of an ASR is similar to that of an ISR +with the following exceptions: + +@itemize @bullet +@item ISRs are scheduled by the processor hardware. ASRs are +scheduled by RTEMS. + +@item ISRs do not execute in the context of a task and may +invoke only a subset of directives. ASRs execute in the context +of a task and may execute any directive. + +@item When an ISR is invoked, it is passed the vector number +as its argument. When an ASR is invoked, it is passed the +signal set as its argument. + +@item An ASR has a task mode which can be different from that +of the task. An ISR does not execute as a task and, as a +result, does not have a task mode. +@end itemize + +@ifinfo +@node Building a Signal Set, Building an ASR's Mode, A Comparison of ASRs and ISRs, Signal Manager Background +@end ifinfo +@subsection Building a Signal Set + +A signal set is built by a bitwise OR of the desired +signals. The set of valid signals is SIGNAL_0 through +SIGNAL_31. If a signal is not explicitly specified in the +signal set, then it is not present. Signal values are +specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as +each signal appears exactly once in the component list. + +This example demonstrates the signal parameter used +when sending the signal set consisting of SIGNAL_6, SIGNAL_15, +and SIGNAL_31. The signal parameter provided to the signal_send +directive should be SIGNAL_6 | SIGNAL_15 | SIGNAL_31. + +@ifinfo +@node Building an ASR's Mode, Signal Manager Operations, Building a Signal Set, Signal Manager Background +@end ifinfo +@subsection Building an ASR's Mode + +In general, an ASR's mode is built by a bitwise OR of +the desired mode components. The set of valid mode components +is the same as those allowed with the task_create and task_mode +directives. A complete list of mode options is provided in the +following table: + +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize + +Mode values are specifically designed to be mutually +exclusive, therefore bitwise OR and addition operations are +equivalent as long as each mode appears exactly once in the +component list. A mode component listed as a default is not +required to appear in the mode list, although it is a good +programming practice to specify default components. If all +defaults are desired, the mode DEFAULT_MODES should be specified +on this call. + +This example demonstrates the mode parameter used +with the signal_catch to establish an ASR which executes at +interrupt level three and is non-preemptible. The mode should +be set to INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the +desired processor mode and interrupt level. + +@ifinfo +@node Signal Manager Operations, Establishing an ASR, Building an ASR's Mode, Signal Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Establishing an ASR:: +* Sending a Signal Set:: +* Processing an ASR:: +@end menu +@end ifinfo + +@ifinfo +@node Establishing an ASR, Sending a Signal Set, Signal Manager Operations, Signal Manager Operations +@end ifinfo +@subsection Establishing an ASR + +The signal_catch directive establishes an ASR for the +calling task. The address of the ASR and its execution mode are +specified to this directive. The ASR's mode is distinct from +the task's mode. For example, the task may allow preemption, +while that task's ASR may have preemption disabled. Until a +task calls signal_catch the first time, its ASR is invalid, and +no signal sets can be sent to the task. + +A task may invalidate its ASR and discard all pending +signals by calling signal_catch with a value of NULL for the +ASR's address. When a task's ASR is invalid, new signal sets +sent to this task are discarded. + +A task may disable ASR processing (NO_ASR) via the +task_mode directive. When a task's ASR is disabled, the signals +sent to it are left pending to be processed later when the ASR +is enabled. + +Any directive that can be called from a task can also +be called from an ASR. A task is only allowed one active ASR. +Thus, each call to signal_catch replaces the previous one. + +Normally, signal processing is disabled for the ASR's +execution mode, but if signal processing is enabled for the ASR, +the ASR must be reentrant. + +@ifinfo +@node Sending a Signal Set, Processing an ASR, Establishing an ASR, Signal Manager Operations +@end ifinfo +@subsection Sending a Signal Set + +The signal_send directive allows both tasks and ISRs +to send signals to a target task. The target task and a set of +signals are specified to the signal_send directive. The sending +of a signal to a task has no effect on the execution state of +that task. If the task is not the currently running task, then +the signals are left pending and processed by the task's ASR the +next time the task is dispatched to run. The ASR is executed +immediately before the task is dispatched. If the currently +running task sends a signal to itself or is sent a signal from +an ISR, its ASR is immediately dispatched to run provided signal +processing is enabled. + +If an ASR with signals enabled is preempted by +another task or an ISR and a new signal set is sent, then a new +copy of the ASR will be invoked, nesting the preempted ASR. +Upon completion of processing the new signal set, control will +return to the preempted ASR. In this situation, the ASR must be +reentrant. + +Like events, identical signals sent to a task are not +queued. In other words, sending the same signal multiple times +to a task (without any intermediate signal processing occurring +for the task), has the same result as sending that signal to +that task once. + +@ifinfo +@node Processing an ASR, Signal Manager Directives, Sending a Signal Set, Signal Manager Operations +@end ifinfo +@subsection Processing an ASR + +Asynchronous signals were designed to provide the +capability to generate software interrupts. The processing of +software interrupts parallels that of hardware interrupts. As a +result, the differences between the formats of ASRs and ISRs is +limited to the meaning of the single argument passed to an ASR. +The ASR should have the following calling sequence and adhere to +C calling conventions: + +@example +rtems_asr user_routine( + rtems_signal_set signals +); +@end example + +When the ASR returns to RTEMS the mode and execution +path of the interrupted task (or ASR) is restored to the context +prior to entering the ASR. + +@ifinfo +@node Signal Manager Directives, SIGNAL_CATCH - Establish an ASR, Processing an ASR, Signal Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* SIGNAL_CATCH - Establish an ASR:: +* SIGNAL_SEND - Send signal set to a task:: +@end menu +@end ifinfo + +This section details the signal manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node SIGNAL_CATCH - Establish an ASR, SIGNAL_SEND - Send signal set to a task, Signal Manager Directives, Signal Manager Directives +@end ifinfo +@subsection SIGNAL_CATCH - Establish an ASR + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_signal_catch( + rtems_asr_entry asr_handler, + rtems_mode mode +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: + +This directive establishes an asynchronous signal +routine (ASR) for the calling task. The asr_handler parameter +specifies the entry point of the ASR. If asr_handler is NULL, +the ASR for the calling task is invalidated and all pending +signals are cleared. Any signals sent to a task with an invalid +ASR are discarded. The mode parameter specifies the execution +mode for the ASR. This execution mode supersedes the task's +execution mode while the ASR is executing. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +The following task mode constants are defined by RTEMS: + +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize + +@page +@ifinfo +@node SIGNAL_SEND - Send signal set to a task, Partition Manager, SIGNAL_CATCH - Establish an ASR, Signal Manager Directives +@end ifinfo +@subsection SIGNAL_SEND - Send signal set to a task + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_signal_send( + rtems_id id, + rtems_signal_set signal_set +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - signal sent successfully@* +@code{INVALID_ID} - task id invalid@* +@code{NOT_DEFINED} - ASR invalid + +@subheading DESCRIPTION: + +This directive sends a signal set to the task +specified in id. The signal_set parameter contains the signal +set to be sent to the task. + +If a caller sends a signal set to a task with an +invalid ASR, then an error code is returned to the caller. If a +caller sends a signal set to a task whose ASR is valid but +disabled, then the signal set will be caught and left pending +for the ASR to process when it is enabled. If a caller sends a +signal set to a task with an ASR that is both valid and enabled, +then the signal set is caught and the ASR will execute the next +time the task is dispatched to run. + +@subheading NOTES: + +Sending a signal set to a task has no effect on that +task's state. If a signal set is sent to a blocked task, then +the task will remain blocked and the signals will be processed +when the task becomes the running task. + +Sending a signal set to a global task which does not +reside on the local node will generate a request telling the +remote node to send the signal set to the specified task. + diff --git a/doc/user/states.gif b/doc/user/states.gif Binary files differnew file mode 100644 index 0000000000..cd0799ea2e --- /dev/null +++ b/doc/user/states.gif diff --git a/doc/user/task.t b/doc/user/task.t new file mode 100644 index 0000000000..730bb73ad2 --- /dev/null +++ b/doc/user/task.t @@ -0,0 +1,1313 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Task Manager, Task Manager Introduction, SHUTDOWN_EXECUTIVE - Shutdown RTEMS, Top +@end ifinfo + +@chapter Task Manager + +@ifinfo +@menu +* Task Manager Introduction:: +* Task Manager Background:: +* Task Manager Operations:: +* Task Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Task Manager Introduction, Task Manager Background, Task Manager, Task Manager +@end ifinfo +@section Introduction + +The task manager provides a comprehensive set of directives to +create, delete, and administer tasks. The directives provided +by the task manager are: + +@itemize @bullet +@item @code{task_create} - Create a task +@item @code{task_ident} - Get ID of a task +@item @code{task_start} - Start a task +@item @code{task_restart} - Restart a task +@item @code{task_delete} - Delete a task +@item @code{task_suspend} - Suspend a task +@item @code{task_resume} - Resume a task +@item @code{task_set_priority} - Set task priority +@item @code{task_mode} - Change current task's mode +@item @code{task_get_note} - Get task notepad entry +@item @code{task_set_note} - Set task notepad entry +@item @code{task_wake_after} - Wake up after interval +@item @code{task_wake_when} - Wake up when specified +@end itemize + +@ifinfo +@node Task Manager Background, Task Definition, Task Manager Introduction, Task Manager +@end ifinfo + +@section Background + +@ifinfo +@menu +* Task Definition:: +* Task Control Block:: +* Task States:: +* Task Priority:: +* Task Mode:: +* Accessing Task Arguments:: +* Floating Point Considerations:: +* Building a Task's Attribute Set:: +* Building a Mode and Mask:: +@end menu + +@end ifinfo + +@ifinfo +@node Task Definition, Task Control Block, Task Manager Background, Task Manager Background +@end ifinfo + +@subsection Task Definition + +Many definitions of a task have been proposed in computer +literature. Unfortunately, none of these definitions +encompasses all facets of the concept in a manner which is +operating system independent. Several of the more common +definitions are provided to enable each user to select a +definition which best matches their own experience and +understanding of the task concept: + +@itemize @bullet +@item a "dispatchable" unit. + +@item an entity to which the processor is allocated. + +@item an atomic unit of a real-time, multiprocessor system. + +@item single threads of execution which concurrently compete for resources. + +@item a sequence of closely related computations which can execute +concurrently with other computational sequences. + +@end itemize + +From RTEMS' perspective, a task is the smallest thread of +execution which can compete on its own for system resources. A +task is manifested by the existence of a task control block +(TCB). + +@ifinfo +@node Task Control Block, Task States, Task Definition, Task Manager Background +@end ifinfo +@subsection Task Control Block + +The Task Control Block (TCB) is an RTEMS defined data structure +which contains all the information that is pertinent to the +execution of a task. During system initialization, RTEMS +reserves a TCB for each task configured. A TCB is allocated +upon creation of the task and is returned to the TCB free list +upon deletion of the task. + +The TCB's elements are modified as a result of system calls made +by the application in response to external and internal stimuli. +TCBs are the only RTEMS internal data structure that can be +accessed by an application via user extension routines. The TCB +contains a task's name, ID, current priority, current and +starting states, execution mode, set of notepad locations, TCB +user extension pointer, scheduling control structures, as well +as data required by a blocked task. + +A task's context is stored in the TCB when a task switch occurs. +When the task regains control of the processor, its context is +restored from the TCB. When a task is restarted, the initial +state of the task is restored from the starting context area in +the task's TCB. + +@ifinfo +@node Task States, Task Priority, Task Control Block, Task Manager Background +@end ifinfo +@subsection Task States + +A task may exist in one of the following five states: + +@itemize @bullet +@item @code{executing} - Currently scheduled to the CPU +@item @code{ready} - May be scheduled to the CPU +@item @code{blocked} - Unable to be scheduled to the CPU +@item @code{dormant} - Created task that is not started +@item @code{non-existent} - Uncreated or deleted task +@end itemize + +An active task may occupy the executing, ready, blocked or +dormant state, otherwise the task is considered non-existent. +One or more tasks may be active in the system simultaneously. +Multiple tasks communicate, synchronize, and compete for system +resources with each other via system calls. The multiple tasks +appear to execute in parallel, but actually each is dispatched +to the CPU for periods of time determined by the RTEMS +scheduling algorithm. The scheduling of a task is based on its +current state and priority. + +@ifinfo +@node Task Priority, Task Mode, Task States, Task Manager Background +@end ifinfo +@subsection Task Priority + +A task's priority determines its importance in relation to the +other tasks executing on the same processor. RTEMS supports 255 +levels of priority ranging from 1 to 255. Tasks of numerically +smaller priority values are more important tasks than tasks of +numerically larger priority values. For example, a task at +priority level 5 is of higher privilege than a task at priority +level 10. There is no limit to the number of tasks assigned to +the same priority. + +Each task has a priority associated with it at all times. The +initial value of this priority is assigned at task creation +time. The priority of a task may be changed at any subsequent +time. + +Priorities are used by the scheduler to determine which ready +task will be allowed to execute. In general, the higher the +logical priority of a task, the more likely it is to receive +processor execution time. + +@ifinfo +@node Task Mode, Accessing Task Arguments, Task Priority, Task Manager Background +@end ifinfo +@subsection Task Mode + +A task's mode is a combination of the following four components: + +@itemize @bullet +@item preemption +@item ASR processing +@item timeslicing +@item interrupt level +@end itemize + +It is used to modify RTEMS' scheduling process and to alter the +execution environment of the task. + +The preemption component allows a task to determine when control +of the processor is relinquished. If preemption is disabled +(NO_PREEMPT), the task will retain control of the processor as +long as it is in the executing state -- even if a higher +priority task is made ready. If preemption is enabled (PREEMPT) +and a higher priority task is made ready, then the processor +will be taken away from the current task immediately and given +to the higher priority task. + +The timeslicing component is used by the RTEMS scheduler to +determine how the processor is allocated to tasks of equal +priority. If timeslicing is enabled (TIMESLICE), then RTEMS +will limit the amount of time the task can execute before the +processor is allocated to another ready task of equal priority. +The length of the timeslice is application dependent and +specified in the Configuration Table. If timeslicing is +disabled (NO_TIMESLICE), then the task will be allowed to +execute until a task of higher priority is made ready. If +NO_PREEMPT is selected, then the timeslicing component is +ignored by the scheduler. + +The asynchronous signal processing component is used to +determine when received signals are to be processed by the task. + If signal processing is enabled (ASR), then signals sent to the +task will be processed the next time the task executes. If +signal processing is disabled (NO_ASR), then all signals +received by the task will remain posted until signal processing +is enabled. This component affects only tasks which have +established a routine to process asynchronous signals. + +The interrupt level component is used to determine which +interrupts will be enabled when the task is executing. +INTERRUPT_LEVEL(n) specifies that the task will execute at +interrupt level n. + +@itemize @bullet +@item @code{PREEMPT} - enable preemption (default) +@item @code{NO_PREEMPT} - disable preemption +@item @code{NO_TIMESLICE} - disable timeslicing (default) +@item @code{TIMESLICE} - enable timeslicing +@item @code{ASR} - enable ASR processing (default) +@item @code{NO_ASR} - disable ASR processing +@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default) +@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n +@end itemize + +@ifinfo +@node Accessing Task Arguments, Floating Point Considerations, Task Mode, Task Manager Background +@end ifinfo +@subsection Accessing Task Arguments + +All RTEMS tasks are invoked with a single argument which is +specified when they are started or restarted. The argument is +commonly used to communicate startup information to the task. +The simplest manner in which to define a task which accesses it +argument is: + +@example +rtems_task user_task( + rtems_task_argument argument +); +@end example + +Application tasks requiring more information may view this +single argument as an index into an array of parameter blocks. + +@ifinfo +@node Floating Point Considerations, Building a Task's Attribute Set, Accessing Task Arguments, Task Manager Background +@end ifinfo +@subsection Floating Point Considerations + +Creating a task with the FLOATING_POINT flag results in +additional memory being allocated for the TCB to store the state +of the numeric coprocessor during task switches. This +additional memory is NOT allocated for NO_FLOATING_POINT tasks. +Saving and restoring the context of a FLOATING_POINT task takes +longer than that of a NO_FLOATING_POINT task because of the +relatively large amount of time required for the numeric +coprocessor to save or restore its computational state. + +Since RTEMS was designed specifically for embedded military +applications which are floating point intensive, the executive +is optimized to avoid unnecessarily saving and restoring the +state of the numeric coprocessor. The state of the numeric +coprocessor is only saved when a FLOATING_POINT task is +dispatched and that task was not the last task to utilize the +coprocessor. In a system with only one FLOATING_POINT task, the +state of the numeric coprocessor will never be saved or +restored. + +Although the overhead imposed by FLOATING_POINT tasks is +minimal, some applications may wish to completely avoid the +overhead associated with FLOATING_POINT tasks and still utilize +a numeric coprocessor. By preventing a task from being +preempted while performing a sequence of floating point +operations, a NO_FLOATING_POINT task can utilize the numeric +coprocessor without incurring the overhead of a FLOATING_POINT +context switch. This approach also avoids the allocation of a +floating point context area. However, if this approach is taken +by the application designer, NO tasks should be created as +FLOATING_POINT tasks. Otherwise, the floating point context +will not be correctly maintained because RTEMS assumes that the +state of the numeric coprocessor will not be altered by +NO_FLOATING_POINT tasks. + +If the supported processor type does not have hardware floating +capabilities or a standard numeric coprocessor, RTEMS will not +provide built-in support for hardware floating point on that +processor. In this case, all tasks are considered +NO_FLOATING_POINT whether created as FLOATING_POINT or +NO_FLOATING_POINT tasks. A floating point emulation software +library must be utilized for floating point operations. + +On some processors, it is possible to disable the floating point +unit dynamically. If this capability is supported by the target +processor, then RTEMS will utilize this capability to enable the +floating point unit only for tasks which are created with the +FLOATING_POINT attribute. The consequence of a +NO_FLOATING_POINT task attempting to access the floating point +unit is CPU dependent but will i general result in an exception +condition. + +@ifinfo +@node Building a Task's Attribute Set, Building a Mode and Mask, Floating Point Considerations, Task Manager Background +@end ifinfo +@subsection Building a Task's Attribute Set + +In general, an attribute set is built by a bitwise OR of the +desired components. The set of valid task attribute components +is listed below: + +@itemize @bullet +@item @code{NO_FLOATING_POINT} - does not use coprocessor (default) +@item @code{FLOATING_POINT} - uses numeric coprocessor +@item @code{LOCAL} - local task (default) +@item @code{GLOBAL} - global task +@end itemize + +Attribute values are specifically designed to be mutually +exclusive, therefore bitwise OR and addition operations are +equivalent as long as each attribute appears exactly once in the +component list. A component listed as a default is not required +to appear in the component list, although it is a good +programming practice to specify default components. If all +defaults are desired, then DEFAULT_ATTRIBUTES should be used. + +This example demonstrates the attribute_set parameter needed to +create a local task which utilizes the numeric coprocessor. The +attribute_set parameter could be FLOATING_POINT or LOCAL | +FLOATING_POINT. The attribute_set parameter can be set to +FLOATING_POINT because LOCAL is the default for all created +tasks. If the task were global and used the numeric +coprocessor, then the attribute_set parameter would be GLOBAL | +FLOATING_POINT. + +@ifinfo +@node Building a Mode and Mask, Task Manager Operations, Building a Task's Attribute Set, Task Manager Background +@end ifinfo +@subsection Building a Mode and Mask + +In general, a mode and its corresponding mask is built by a +bitwise OR of the desired components. The set of valid mode +constants and each mode's corresponding mask constant is +listed below: + +@ifset use-ascii +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n +@end itemize +@end ifset + +@ifset use-tex +@sp 1 +@c this is temporary +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize + +@tex +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=3 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD> + <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD> + <TD ALIGN=center><STRONG>Description</STRONG></TD></TR> +<TR><TD ALIGN=center>PREEMPT</TD> + <TD ALIGN=center>PREEMPT_MASK</TD> + <TD ALIGN=center>enables preemption</TD></TR> +<TR><TD ALIGN=center>NO_PREEMPT</TD> + <TD ALIGN=center>PREEMPT_MASK</TD> + <TD ALIGN=center>disables preemption</TD></TR> +<TR><TD ALIGN=center>NO_TIMESLICE</TD> + <TD ALIGN=center>TIMESLICE_MASK</TD> + <TD ALIGN=center>disables timeslicing</TD></TR> +<TR><TD ALIGN=center>TIMESLICE</TD> + <TD ALIGN=center>TIMESLICE_MASK</TD> + <TD ALIGN=center>enables timeslicing</TD></TR> +<TR><TD ALIGN=center>ASR</TD> + <TD ALIGN=center>ASR_MASK</TD> + <TD ALIGN=center>enables ASR processing</TD></TR> +<TR><TD ALIGN=center>NO_ASR</TD> + <TD ALIGN=center>ASR_MASK</TD> + <TD ALIGN=center>disables ASR processing</TD></TR> +<TR><TD ALIGN=center>INTERRUPT_LEVEL(0)</TD> + <TD ALIGN=center>INTERRUPT_MASK</TD> + <TD ALIGN=center>enables all interrupts</TD></TR> +<TR><TD ALIGN=center>INTERRUPT_LEVEL(n)</TD> + <TD ALIGN=center>INTERRUPT_MASK</TD> + <TD ALIGN=center>sets interrupts level n</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + + + + +Mode values are specifically designed to be mutually exclusive, +therefore bitwise OR and addition operations are equivalent as +long as each mode appears exactly once in the component list. A +mode component listed as a default is not required to appear in +the mode component list, although it is a good programming +practice to specify default components. If all defaults are +desired, the mode DEFAULT_MODES and the mask ALL_MODE_MASKS +should be used. + +The following example demonstrates the mode and mask parameters +used with the task_mode directive to place a task at interrupt +level 3 and make it non-preemptible. The mode should be set to +INTERRUPT_LEVEL(3) | NO_PREEMPT to indicate the desired +preemption mode and interrupt level, while the mask parameter +should be set to INTERRUPT_MASK | NO_PREEMPT_MASK to indicate +that the calling task's interrupt level and preemption mode are +being altered. + +@ifinfo +@node Task Manager Operations, Creating Tasks, Building a Mode and Mask, Task Manager +@end ifinfo + +@section Operations + +@ifinfo +@menu +* Creating Tasks:: +* Obtaining Task IDs:: +* Starting and Restarting Tasks:: +* Suspending and Resuming Tasks:: +* Delaying the Currently Executing Task:: +* Changing Task Priority:: +* Changing Task Mode:: +* Notepad Locations:: +* Task Deletion:: +@end menu +@end ifinfo + +@ifinfo +@node Creating Tasks, Obtaining Task IDs, Task Manager Operations, Task Manager Operations +@end ifinfo +@subsection Creating Tasks + +The task_create directive creates a task by allocating a task +control block, assigning the task a user-specified name, +allocating it a stack and floating point context area, setting a +user-specified initial priority, setting a user-specified +initial mode, and assigning it a task ID. Newly created tasks +are initially placed in the dormant state. All RTEMS tasks +execute in the most privileged mode of the processor. + +@ifinfo +@node Obtaining Task IDs, Starting and Restarting Tasks, Creating Tasks, Task Manager Operations +@end ifinfo +@subsection Obtaining Task IDs + +When a task is created, RTEMS generates a unique task ID and +assigns it to the created task until it is deleted. The task ID +may be obtained by either of two methods. First, as the result +of an invocation of the task_create directive, the task ID is +stored in a user provided location. Second, the task ID may be +obtained later using the task_ident directive. The task ID is +used by other directives to manipulate this task. + +@ifinfo +@node Starting and Restarting Tasks, Suspending and Resuming Tasks, Obtaining Task IDs, Task Manager Operations +@end ifinfo +@subsection Starting and Restarting Tasks + +The task_start directive is used to place a dormant task in the +ready state. This enables the task to compete, based on its +current priority, for the processor and other system resources. +Any actions, such as suspension or change of priority, performed +on a task prior to starting it are nullified when the task is +started. + +With the task_start directive the user specifies the task's +starting address and argument. The argument is used to +communicate some startup information to the task. As part of +this directive, RTEMS initializes the task's stack based upon +the task's initial execution mode and start address. The +starting argument is passed to the task in accordance with the +target processor's calling convention. + +The task_restart directive restarts a task at its initial +starting address with its original priority and execution mode, +but with a possibly different argument. The new argument may be +used to distinguish between the original invocation of the task +and subsequent invocations. The task's stack and control block +are modified to reflect their original creation values. +Although references to resources that have been requested are +cleared, resources allocated by the task are NOT automatically +returned to RTEMS. A task cannot be restarted unless it has +previously been started (i.e. dormant tasks cannot be +restarted). All restarted tasks are placed in the ready state. + +@ifinfo +@node Suspending and Resuming Tasks, Delaying the Currently Executing Task, Starting and Restarting Tasks, Task Manager Operations +@end ifinfo +@subsection Suspending and Resuming Tasks + +The task_suspend directive is used to place either the caller or +another task into a suspended state. The task remains suspended +until a task_resume directive is issued. This implies that a +task may be suspended as well as blocked waiting either to +acquire a resource or for the expiration of a timer. + +The task_resume directive is used to remove another task from +the suspended state. If the task is not also blocked, resuming +it will place it in the ready state, allowing it to once again +compete for the processor and resources. If the task was +blocked as well as suspended, this directive clears the +suspension and leaves the task in the blocked state. + +@ifinfo +@node Delaying the Currently Executing Task, Changing Task Priority, Suspending and Resuming Tasks, Task Manager Operations +@end ifinfo +@subsection Delaying the Currently Executing Task + +The task_wake_after directive creates a sleep timer which allows +a task to go to sleep for a specified interval. The task is +blocked until the delay interval has elapsed, at which time the +task is unblocked. A task calling the task_wake_after directive +with a delay interval of YIELD_PROCESSOR ticks will yield the +processor to any other ready task of equal or greater priority +and remain ready to execute. + +The task_wake_when directive creates a sleep timer which allows +a task to go to sleep until a specified date and time. The +calling task is blocked until the specified date and time has +occurred, at which time the task is unblocked. + +@ifinfo +@node Changing Task Priority, Changing Task Mode, Delaying the Currently Executing Task, Task Manager Operations +@end ifinfo +@subsection Changing Task Priority + +The task_set_priority directive is used to obtain or change the +current priority of either the calling task or another task. If +the new priority requested is CURRENT_PRIORITY or the task's +actual priority, then the current priority will be returned and +the task's priority will remain unchanged. If the task's +priority is altered, then the task will be scheduled according +to its new priority. + +The task_restart directive resets the priority of a task to its +original value. + +@ifinfo +@node Changing Task Mode, Notepad Locations, Changing Task Priority, Task Manager Operations +@end ifinfo +@subsection Changing Task Mode + +The task_mode directive is used to obtain or change the current +execution mode of the calling task. A task's execution mode is +used to enable preemption, timeslicing, ASR processing, and to +set the task's interrupt level. + +The task_restart directive resets the mode of a task to its +original value. + +@ifinfo +@node Notepad Locations, Task Deletion, Changing Task Mode, Task Manager Operations +@end ifinfo +@subsection Notepad Locations + +RTEMS provides sixteen notepad locations for each task. Each +notepad location may contain a note consisting of four bytes of +information. RTEMS provides two directives, task_set_note and +task_get_note, that enable a user to access and change the +notepad locations. The task_set_note directive enables the user +to set a task's notepad entry to a specified note. The +task_get_note directive allows the user to obtain the note +contained in any one of the sixteen notepads of a specified task. + +@ifinfo +@node Task Deletion, Task Manager Directives, Notepad Locations, Task Manager Operations +@end ifinfo +@subsection Task Deletion + +RTEMS provides the task_delete directive to allow a task to +delete itself or any other task. This directive removes all +RTEMS references to the task, frees the task's control block, +removes it from resource wait queues, and deallocates its stack +as well as the optional floating point context. The task's name +and ID become inactive at this time, and any subsequent +references to either of them is invalid. In fact, RTEMS may +reuse the task ID for another task which is created later in the +application. + +Unexpired delay timers (i.e. those used by task_wake_after and +task_wake_when) and timeout timers associated with the task are +automatically deleted, however, other resources dynamically +allocated by the task are NOT automatically returned to RTEMS. +Therefore, before a task is deleted, all of its dynamically +allocated resources should be deallocated by the user. This may +be accomplished by instructing the task to delete itself rather +than directly deleting the task. Other tasks may instruct a +task to delete itself by sending a "delete self" message, event, +or signal, or by restarting the task with special arguments +which instruct the task to delete itself. + +@ifinfo +@node Task Manager Directives, TASK_CREATE - Create a task, Task Deletion, Task Manager +@end ifinfo + +@section Directives + +@ifinfo +@menu +* TASK_CREATE - Create a task:: +* TASK_IDENT - Get ID of a task:: +* TASK_START - Start a task:: +* TASK_RESTART - Restart a task:: +* TASK_DELETE - Delete a task:: +* TASK_SUSPEND - Suspend a task:: +* TASK_RESUME - Resume a task:: +* TASK_SET_PRIORITY - Set task priority:: +* TASK_MODE - Change current task's mode:: +* TASK_GET_NOTE - Get task notepad entry:: +* TASK_SET_NOTE - Set task notepad entry:: +* TASK_WAKE_AFTER - Wake up after interval:: +* TASK_WAKE_WHEN - Wake up when specified:: +@end menu +@end ifinfo + +This section details the task manager's directives. A +subsection is dedicated to each of this manager's directives and +describes the calling sequence, related constants, usage, and +status codes. + +@page + +@ifinfo +@node TASK_CREATE - Create a task, TASK_IDENT - Get ID of a task, Task Manager Directives, Task Manager Directives +@end ifinfo +@subsection TASK_CREATE - Create a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_create( + rtems_name name, + rtems_task_priority initial_priority, + rtems_unsigned32 stack_size, + rtems_mode initial_modes, + rtems_attribute attribute_set, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task created successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_SIZE} - stack too small@* +@code{INVALID_PRIORITY} - invalid task priority@* +@code{MP_NOT_CONFIGURED} - multiprocessing not configured@* +@code{TOO_MANY} - too many tasks created@* +@code{UNSATISFIED} - not enough memory for stack/FP context@* +@code{TOO_MANY} - too many global objects + +@subheading DESCRIPTION: +This directive creates a task which resides on the local node. +It allocates and initializes a TCB, a stack, and an optional +floating point context area. The mode parameter contains values +which sets the task's initial execution mode. The +FLOATING_POINT attribute should be specified if the created task +is to use a numeric coprocessor. For performance reasons, it is +recommended that tasks not using the numeric coprocessor should +specify the NO_FLOATING_POINT attribute. If the GLOBAL +attribute is specified, the task can be accessed from remote +nodes. The task id, returned in id, is used in other task +related directives to access the task. When created, a task is +placed in the dormant state and can only be made ready to +execute using the directive task_start. + +@subheading NOTES: +This directive will not cause the calling task to be preempted. + +Valid task priorities range from a high of 1 to a low of 255. + +RTEMS supports a maximum of 256 interrupt levels which are +mapped onto the interrupt levels actually supported by the +target processor. + +The requested stack size should be at least MINIMUM_STACK_SIZE +bytes. The value of MINIMUM_STACK_SIZE is processor dependent. +Application developers should consider the stack usage of the +device drivers when calculating the stack size required for +tasks which utilize the driver. + +The following task attribute constants are defined by RTEMS: + +@itemize @bullet +@item @code{NO_FLOATING_POINT} - does not use coprocessor (default) +@item @code{FLOATING_POINT} - uses numeric coprocessor +@item @code{LOCAL} - local task (default) +@item @code{GLOBAL} - global task +@end itemize + +The following task mode constants are defined by RTEMS: + +@itemize @bullet +@item @code{PREEMPT} - enable preemption (default) +@item @code{NO_PREEMPT} - disable preemption +@item @code{NO_TIMESLICE} - disable timeslicing (default) +@item @code{TIMESLICE} - enable timeslicing +@item @code{ASR} - enable ASR processing (default) +@item @code{NO_ASR} - disable ASR processing +@item @code{INTERRUPT_LEVEL(0)} - enable all interrupts (default) +@item @code{INTERRUPT_LEVEL(n)} - execute at interrupt level n +@end itemize + +Tasks should not be made global unless remote tasks must +interact with them. This avoids the system overhead incurred by +the creation of a global task. When a global task is created, +the task's name and id must be transmitted to every node in the +system for insertion in the local copy of the global object +table. + +The total number of global objects, including tasks, is limited +by the maximum_global_objects field in the Configuration Table. + +@page + +@ifinfo +@node TASK_IDENT - Get ID of a task, TASK_START - Start a task, TASK_CREATE - Create a task, Task Manager Directives +@end ifinfo +@subsection TASK_IDENT - Get ID of a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_ident( + rtems_name name, + rtems_unsigned32 node, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task identified successfully@* +@code{INVALID_NAME} - invalid task name@* +@code{INVALID_NODE} - invalid node id + +@subheading DESCRIPTION: +This directive obtains the task id associated with the task name +specified in name. A task may obtain its own id by specifying +SELF or its own task name in name. If the task name is not +unique, then the task id returned will match one of the tasks +with that name. However, this task id is not guaranteed to +correspond to the desired task. The task id, returned in id, is +used in other task related directives to access the task. + +@subheading NOTES: +This directive will not cause the running task to be preempted. + +If node is SEARCH_ALL_NODES, all nodes are searched with the +local node being searched first. All other nodes are searched +with the lowest numbered node searched first. + +If node is a valid node number which does not represent the +local node, then only the tasks exported by the designated node +are searched. + +This directive does not generate activity on remote nodes. It +accesses only the local copy of the global object table. + +@page + +@ifinfo +@node TASK_START - Start a task, TASK_RESTART - Restart a task, TASK_IDENT - Get ID of a task, Task Manager Directives +@end ifinfo +@subsection TASK_START - Start a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_start( + rtems_id id, + rtems_task_entry entry_point, + rtems_task_argument argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - ask started successfully@* +@code{INVALID_ADDRESS} - invalid task entry point@* +@code{INVALID_ID} - invalid task id@* +@code{INCORRECT_STATE} - task not in the dormant state@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot start remote task + +@subheading DESCRIPTION: +This directive readies the task, specified by tid, for execution +based on the priority and execution mode specified when the task +was created. The starting address of the task is given in +entry_point. The task's starting argument is contained in +argument. This argument can be a single value or used as an +index into an array of parameter blocks. + +@subheading NOTES: +The calling task will be preempted if its preemption mode is +enabled and the task being started has a higher priority. + +Any actions performed on a dormant task such as suspension or +change of priority are nullified when the task is initiated via +the task_start directive. + +@page + +@ifinfo +@node TASK_RESTART - Restart a task, TASK_DELETE - Delete a task, TASK_START - Start a task, Task Manager Directives +@end ifinfo +@subsection TASK_RESTART - Restart a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_restart( + rtems_id id, + rtems_task_argument argument +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{INCORRECT_STATE} - task never started@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task + +@subheading DESCRIPTION: +This directive resets the task specified by id to begin +execution at its original starting address. The task's priority +and execution mode are set to the original creation values. If +the task is currently blocked, RTEMS automatically makes the +task ready. A task can be restarted from any state, except the +dormant state. + +The task's starting argument is contained in argument. This +argument can be a single value or an index into an array of +parameter blocks. This new argument may be used to distinguish +between the initial task_start of the task and any ensuing calls +to task_restart of the task. This can be beneficial in deleting +a task. Instead of deleting a task using the task_delete +directive, a task can delete another task by restarting that +task, and allowing that task to release resources back to RTEMS +and then delete itself. + +@subheading NOTES: +If id is SELF, the calling task will be restarted and will not +return from this directive. + +The calling task will be preempted if its preemption mode is +enabled and the task being restarted has a higher priority. + +The task must reside on the local node, even if the task was +created with the GLOBAL option. + +@page + +@ifinfo +@node TASK_DELETE - Delete a task, TASK_SUSPEND - Suspend a task, TASK_RESTART - Restart a task, Task Manager Directives +@end ifinfo +@subsection TASK_DELETE - Delete a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{ILLEGAL_ON_REMOTE_OBJECT} - cannot restart remote task + +@subheading DESCRIPTION: +This directive deletes a task, either the calling task or +another task, as specified by id. RTEMS stops the execution of +the task and reclaims the stack memory, any allocated delay or +timeout timers, the TCB, and, if the task is FLOATING_POINT, its +floating point context area. RTEMS does not reclaim the +following resources: region segments, partition buffers, +semaphores, timers, or rate monotonic periods. + +@subheading NOTES: +A task is responsible for releasing its resources back to RTEMS +before deletion. To insure proper deallocation of resources, a +task should not be deleted unless it is unable to execute or +does not hold any RTEMS resources. If a task holds RTEMS +resources, the task should be allowed to deallocate its +resources before deletion. A task can be directed to release +its resources and delete itself by restarting it with a special +argument or by sending it a message, an event, or a signal. + +Deletion of the current task (SELF) will force RTEMS to select +another task to execute. + +When a global task is deleted, the task id must be transmitted +to every node in the system for deletion from the local copy of +the global object table. + +The task must reside on the local node, even if the task was +created with the GLOBAL option. + +@page + +@ifinfo +@node TASK_SUSPEND - Suspend a task, TASK_RESUME - Resume a task, TASK_DELETE - Delete a task, Task Manager Directives +@end ifinfo +@subsection TASK_SUSPEND - Suspend a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_suspend( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{ALREADY_SUSPENDED} - task already suspended + +@subheading DESCRIPTION: +This directive suspends the task specified by id from further +execution by placing it in the suspended state. This state is +additive to any other blocked state that the task may already be +in. The task will not execute again until another task issues +the task_resume directive for this task and any blocked state +has been removed. + +@subheading NOTES: +The requesting task can suspend itself by specifying SELF as id. +In this case, the task will be suspended and a successful +return code will be returned when the task is resumed. + +Suspending a global task which does not reside on the local node +will generate a request to the remote node to suspend the +specified task. + +@page + +@ifinfo +@node TASK_RESUME - Resume a task, TASK_SET_PRIORITY - Set task priority, TASK_SUSPEND - Suspend a task, Task Manager Directives +@end ifinfo +@subsection TASK_RESUME - Resume a task + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_resume( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task restarted successfully@* +@code{INVALID_ID} - task id invalid@* +@code{INCORRECT_STATE} - task not suspended + +@subheading DESCRIPTION: +This directive removes the task specified by id from the +suspended state. If the task is in the ready state after the +suspension is removed, then it will be scheduled to run. If the +task is still in a blocked state after the suspension is +removed, then it will remain in that blocked state. + +@subheading NOTES: +The running task may be preempted if its preemption mode is +enabled and the local task being resumed has a higher priority. + +Resuming a global task which does not reside on the local node +will generate a request to the remote node to resume the +specified task. + +@page + +@ifinfo +@node TASK_SET_PRIORITY - Set task priority, TASK_MODE - Change current task's mode, TASK_RESUME - Resume a task, Task Manager Directives +@end ifinfo +@subsection TASK_SET_PRIORITY - Set task priority + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_set_priority( + rtems_id id, + rtems_task_priority new_priority, + rtems_task_priority *old_priority +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task priority set successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_PRIORITY} - invalid task priority + +@subheading DESCRIPTION: +This directive manipulates the priority of the task specified by +id. An id of SELF is used to indicate the calling task. When +new_priority is not equal to CURRENT_PRIORITY, the specified +task's previous priority is returned in old_priority. When +new_priority is CURRENT_PRIORITY, the specified task's current +priority is returned in old_priority. Valid priorities range +from a high of 1 to a low of 255. + +@subheading NOTES: +The calling task may be preempted if its preemption mode is +enabled and it lowers its own priority or raises another task's +priority. + +Setting the priority of a global task which does not reside on +the local node will generate a request to the remote node to +change the priority of the specified task. + +If the task specified by id is currently holding any binary +semaphores which use the priority inheritance algorithm, then +the task's priority cannot be lowered immediately. If the +task's priority were lowered immediately, then priority +inversion results. The requested lowering of the task's +priority will occur when the task has released all priority +inheritance binary semaphores. The task's priority can be +increased regardless of the task's use of priority inheritance +binary semaphores. + +@page + +@ifinfo +@node TASK_MODE - Change current task's mode, TASK_GET_NOTE - Get task notepad entry, TASK_SET_PRIORITY - Set task priority, Task Manager Directives +@end ifinfo +@subsection TASK_MODE - Change current task's mode + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_mode( + rtems_mode mode_set, + rtems_mode mask, + rtems_mode *previous_mode_set +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task mode set successfully + +@subheading DESCRIPTION: +This directive manipulates the execution mode of the calling +task. A task's execution mode enables and disables preemption, +timeslicing, asynchronous signal processing, as well as +specifying the current interrupt level. To modify an execution +mode, the mode class(es) to be changed must be specified in the +mask parameter and the desired mode(s) must be specified in the +mode parameter. + +@subheading NOTES: +The calling task will be preempted if it enables preemption and +a higher priority task is ready to run. + +Enabling timeslicing has no effect if preemption is enabled. + +A task can obtain its current execution mode, without modifying +it, by calling this directive with a mask value of CURRENT_MODE. + +To temporarily disable the processing of a valid ASR, a task +should call this directive with the NO_ASR indicator specified +in mode. + +The set of task mode constants and each mode's corresponding +mask constant is provided in the following table: + +@ifset use-ascii +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize +@end ifset + +@ifset use-tex +@sp 1 +@c this is temporary +@itemize @bullet +@item PREEMPT is masked by PREEMPT_MASK and enables preemption +@item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption +@item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing +@item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing +@item ASR is masked by ASR_MASK and enables ASR processing +@item NO_ASR is masked by ASR_MASK and disables ASR processing +@item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts +@item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n + +@end itemize + +@tex +@end tex +@end ifset + +@ifset use-html +@html +<CENTER> + <TABLE COLS=3 WIDTH="80%" BORDER=2> +<TR><TD ALIGN=center><STRONG>Mode Constant</STRONG></TD> + <TD ALIGN=center><STRONG>Mask Constant</STRONG></TD> + <TD ALIGN=center><STRONG>Description</STRONG></TD></TR> +<TR><TD ALIGN=center>PREEMPT</TD> + <TD ALIGN=center>PREEMPT_MASK</TD> + <TD ALIGN=center>enables preemption</TD></TR> +<TR><TD ALIGN=center>NO_PREEMPT</TD> + <TD ALIGN=center>PREEMPT_MASK</TD> + <TD ALIGN=center>disables preemption</TD></TR> +<TR><TD ALIGN=center>NO_TIMESLICE</TD> + <TD ALIGN=center>TIMESLICE_MASK</TD> + <TD ALIGN=center>disables timeslicing</TD></TR> +<TR><TD ALIGN=center>TIMESLICE</TD> + <TD ALIGN=center>TIMESLICE_MASK</TD> + <TD ALIGN=center>enables timeslicing</TD></TR> +<TR><TD ALIGN=center>ASR</TD> + <TD ALIGN=center>ASR_MASK</TD> + <TD ALIGN=center>enables ASR processing</TD></TR> +<TR><TD ALIGN=center>NO_ASR</TD> + <TD ALIGN=center>ASR_MASK</TD> + <TD ALIGN=center>disables ASR processing</TD></TR> +<TR><TD ALIGN=center>INTERRUPT_LEVEL(0)</TD> + <TD ALIGN=center>INTERRUPT_MASK</TD> + <TD ALIGN=center>enables all interrupts</TD></TR> +<TR><TD ALIGN=center>INTERRUPT_LEVEL(n)</TD> + <TD ALIGN=center>INTERRUPT_MASK</TD> + <TD ALIGN=center>sets interrupts level n</TD></TR> + </TABLE> +</CENTER> +@end html +@end ifset + +@page + +@ifinfo +@node TASK_GET_NOTE - Get task notepad entry, TASK_SET_NOTE - Set task notepad entry, TASK_MODE - Change current task's mode, Task Manager Directives +@end ifinfo +@subsection TASK_GET_NOTE - Get task notepad entry + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_get_note( + rtems_id id, + rtems_unsigned32 notepad, + rtems_unsigned32 *note +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - note obtained successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_NUMBER} - invalid notepad location + +@subheading DESCRIPTION: +This directive returns the note contained in the notepad +location of the task specified by id. + +@subheading NOTES: +This directive will not cause the running task to be preempted. + +If id is set to SELF, the calling task accesses its own notepad. + +@c This version of the paragraph avoids the overfull hbox error. +@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the +@c sixteen notepad locations. + +The sixteen notepad locations can be accessed using the constants +NOTEPAD_0 through NOTEPAD_15. + +Getting a note of a global task which does not reside on the +local node will generate a request to the remote node to obtain +the notepad entry of the specified task. + +@page + +@ifinfo +@node TASK_SET_NOTE - Set task notepad entry, TASK_WAKE_AFTER - Wake up after interval, TASK_GET_NOTE - Get task notepad entry, Task Manager Directives +@end ifinfo +@subsection TASK_SET_NOTE - Set task notepad entry + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_set_note( + rtems_id id, + rtems_unsigned32 notepad, + rtems_unsigned32 note +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - task's note set successfully@* +@code{INVALID_ID} - invalid task id@* +@code{INVALID_NUMBER} - invalid notepad location + +@subheading DESCRIPTION: +This directive sets the notepad entry for the task specified by +id to the value note. + +@subheading NOTES: +If id is set to SELF, the calling task accesses its own notepad +locations. + +This directive will not cause the running task to be preempted. + +@c This version of the paragraph avoids the overfull hbox error. +@c The constants NOTEPAD_0 through NOTEPAD_15 can be used to access the +@c sixteen notepad locations. + +The sixteen notepad locations can be accessed using the constants +NOTEPAD_0 through NOTEPAD_15. + +Setting a notepad location of a global task which does not +reside on the local node will generate a request to the remote +node to set the specified notepad entry. + +@page + +@ifinfo +@node TASK_WAKE_AFTER - Wake up after interval, TASK_WAKE_WHEN - Wake up when specified, TASK_SET_NOTE - Set task notepad entry, Task Manager Directives +@end ifinfo +@subsection TASK_WAKE_AFTER - Wake up after interval + +@subheading CALLING SEQUENCE: +@example +rtems_status_code rtems_task_wake_after( + rtems_interval ticks +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - always successful + +@subheading DESCRIPTION: +This directive blocks the calling task for the specified number +of system clock ticks. When the requested interval has elapsed, +the task is made ready. The clock_tick directive automatically +updates the delay period. + +@subheading NOTES: +Setting the system date and time with the clock_set directive +has no effect on a task_wake_after blocked task. + +A task may give up the processor and remain in the ready state +by specifying a value of YIELD_PROCESSOR in ticks. + +The maximum timer interval that can be specified is the maximum +value which can be represented by the rtems_unsigned32 type. + +@page + +@ifinfo +@node TASK_WAKE_WHEN - Wake up when specified, Interrupt Manager, TASK_WAKE_AFTER - Wake up after interval, Task Manager Directives +@end ifinfo +@subsection TASK_WAKE_WHEN - Wake up when specified + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_task_wake_when( + rtems_time_of_day *time_buffer +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - awakened at date/time successfully@* +@code{INVALID_TIME_OF_DAY} - invalid time buffer@* +@code{NOT_DEFINED} - system date and time is not set + +@subheading DESCRIPTION: +This directive blocks a task until the date and time specified +in time_buffer. At the requested date and time, the calling +task will be unblocked and made ready to execute. + +@subheading NOTES: +The ticks portion of time_buffer structure is ignored. The +timing granularity of this directive is a second. diff --git a/doc/user/timer.t b/doc/user/timer.t new file mode 100644 index 0000000000..d0dcb8ba71 --- /dev/null +++ b/doc/user/timer.t @@ -0,0 +1,441 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node Timer Manager, Timer Manager Introduction, CLOCK_TICK - Announce a clock tick, Top +@end ifinfo +@chapter Timer Manager +@ifinfo +@menu +* Timer Manager Introduction:: +* Timer Manager Background:: +* Timer Manager Operations:: +* Timer Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node Timer Manager Introduction, Timer Manager Background, Timer Manager, Timer Manager +@end ifinfo +@section Introduction + +The timer manager provides support for timer +facilities. The directives provided by the timer manager are: + +@itemize @bullet +@item @code{timer_create} - Create a timer +@item @code{timer_ident} - Get ID of a timer +@item @code{timer_cancel} - Cancel a timer +@item @code{timer_delete} - Delete a timer +@item @code{timer_fire_after} - Fire timer after interval +@item @code{timer_fire_when} - Fire timer when specified +@item @code{timer_reset} - Reset an interval timer +@end itemize + + +@ifinfo +@node Timer Manager Background, Timers, Timer Manager Introduction, Timer Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Timers:: +* Timer Service Routines:: +@end menu +@end ifinfo + +@ifinfo +@node Timers, Timer Service Routines, Timer Manager Background, Timer Manager Background +@end ifinfo +@subsection Timers + +A timer is an RTEMS object which allows the +application to schedule operations to occur at specific times in +the future. User supplied timer service routines are invoked by +the clock_tick directive when the timer fires. Timer service +routines may perform any operations or directives which normally +would be performed by the application code which invoked the +clock_tick directive. + +The timer can be used to implement watchdog routines +which only fire to denote that an application error has +occurred. The timer is reset at specific points in the +application to insure that the watchdog does not fire. Thus, if +the application does not reset the watchdog timer, then the +timer service routine will fire to indicate that the application +has failed to reach a reset point. This use of a timer is +sometimes referred to as a "keep alive" or a "deadman" timer. + +@ifinfo +@node Timer Service Routines, Timer Manager Operations, Timers, Timer Manager Background +@end ifinfo +@subsection Timer Service Routines + +The timer service routine should adhere to C calling +conventions and have a prototype similar to the following:: + +@example +rtems_timer_service_routine user_routine( + rtems_id timer_id, + void *user_data +); +@end example + + + +Where the timer_id parameter is the RTEMS object ID +of the timer which is being fired and user_data is a pointer to +user-defined information which may be utilized by the timer +service routine. The argument user_data may be NULL. + +@ifinfo +@node Timer Manager Operations, Creating a Timer, Timer Service Routines, Timer Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating a Timer:: +* Obtaining Timer IDs:: +* Initiating an Interval Timer:: +* Initiating a Time of Day Timer:: +* Canceling a Timer:: +* Resetting a Timer:: +* Deleting a Timer:: +@end menu +@end ifinfo + +@ifinfo +@node Creating a Timer, Obtaining Timer IDs, Timer Manager Operations, Timer Manager Operations +@end ifinfo +@subsection Creating a Timer + +The timer_create directive creates a timer by +allocating a Timer Control Block (TMCB), assigning the timer a +user-specified name, and assigning it a timer ID. Newly created +timers do not have a timer service routine associated with them +and are not active. + +@ifinfo +@node Obtaining Timer IDs, Initiating an Interval Timer, Creating a Timer, Timer Manager Operations +@end ifinfo +@subsection Obtaining Timer IDs + +When a timer is created, RTEMS generates a unique +timer ID and assigns it to the created timer until it is +deleted. The timer ID may be obtained by either of two methods. +First, as the result of an invocation of the timer_create +directive, the timer ID is stored in a user provided location. +Second, the timer ID may be obtained later using the timer_ident +directive. The timer ID is used by other directives to +manipulate this timer. + +@ifinfo +@node Initiating an Interval Timer, Initiating a Time of Day Timer, Obtaining Timer IDs, Timer Manager Operations +@end ifinfo +@subsection Initiating an Interval Timer + +The timer_fire_after directive initiates a timer to +fire a user provided timer service routine after the specified +number of clock ticks have elapsed. When the interval has +elapsed, the timer service routine will be invoked from the +clock_tick directive. + +@ifinfo +@node Initiating a Time of Day Timer, Canceling a Timer, Initiating an Interval Timer, Timer Manager Operations +@end ifinfo +@subsection Initiating a Time of Day Timer + +The timer_fire_when directive initiates a timer to +fire a user provided timer service routine when the specified +time of day has been reached. When the interval has elapsed, +the timer service routine will be invoked from the clock_tick +directive. + +@ifinfo +@node Canceling a Timer, Resetting a Timer, Initiating a Time of Day Timer, Timer Manager Operations +@end ifinfo +@subsection Canceling a Timer + +The timer_cancel directive is used to halt the +specified timer. Once canceled, the timer service routine will +not fire unless the timer is reinitiated. The timer can be +reinitiated using the timer_reset, timer_fire_after, and +timer_fire_when directives. + +@ifinfo +@node Resetting a Timer, Deleting a Timer, Canceling a Timer, Timer Manager Operations +@end ifinfo +@subsection Resetting a Timer + +The timer_reset directive is used to restore an +interval timer initiated by a previous invocation of +timer_fire_after to its original interval length. The timer +service routine is not changed or fired by this directive. + +@ifinfo +@node Deleting a Timer, Timer Manager Directives, Resetting a Timer, Timer Manager Operations +@end ifinfo +@subsection Deleting a Timer + +The timer_delete directive is used to delete a timer. +If the timer is running and has not expired, the timer is +automatically canceled. The timer's control block is returned +to the TMCB free list when it is deleted. A timer can be +deleted by a task other than the task which created the timer. +Any subsequent references to the timer's name and ID are invalid. + +@ifinfo +@node Timer Manager Directives, TIMER_CREATE - Create a timer, Deleting a Timer, Timer Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* TIMER_CREATE - Create a timer:: +* TIMER_IDENT - Get ID of a timer:: +* TIMER_CANCEL - Cancel a timer:: +* TIMER_DELETE - Delete a timer:: +* TIMER_FIRE_AFTER - Fire timer after interval:: +* TIMER_FIRE_WHEN - Fire timer when specified:: +* TIMER_RESET - Reset an interval timer:: +@end menu +@end ifinfo + +This section details the timer manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@ifinfo +@node TIMER_CREATE - Create a timer, TIMER_IDENT - Get ID of a timer, Timer Manager Directives, Timer Manager Directives +@end ifinfo +@subsection TIMER_CREATE - Create a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_create( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer created successfully@* +@code{INVALID_NAME} - invalid timer name@* +@code{TOO_MANY} - too many timers created + +@subheading DESCRIPTION: + +This directive creates a timer. The assigned timer +id is returned in id. This id is used to access the timer with +other timer manager directives. For control and maintenance of +the timer, RTEMS allocates a TMCB from the local TMCB free pool +and initializes it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node TIMER_IDENT - Get ID of a timer, TIMER_CANCEL - Cancel a timer, TIMER_CREATE - Create a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_IDENT - Get ID of a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer identified successfully@* +@code{INVALID_NAME} - timer name not found + +@subheading DESCRIPTION: + +This directive obtains the timer id associated with +the timer name to be acquired. If the timer name is not unique, +then the timer id will match one of the timers with that name. +However, this timer id is not guaranteed to correspond to the +desired timer. The timer id is used to access this timer in +other timer related directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node TIMER_CANCEL - Cancel a timer, TIMER_DELETE - Delete a timer, TIMER_IDENT - Get ID of a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_CANCEL - Cancel a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_cancel( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer canceled successfully@* +@code{INVALID_ID} - invalid timer id + +@subheading DESCRIPTION: + +This directive cancels the timer id. This timer will +be reinitiated by the next invocation of timer_reset, +timer_fire_after, or timer_fire_when with id. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + +@page +@ifinfo +@node TIMER_DELETE - Delete a timer, TIMER_FIRE_AFTER - Fire timer after interval, TIMER_CANCEL - Cancel a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_DELETE - Delete a timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer deleted successfully@* +@code{INVALID_ID} - invalid timer id + +@subheading DESCRIPTION: + +This directive deletes the timer specified by id. If +the timer is running, it is automatically canceled. The TMCB +for the deleted timer is reclaimed by RTEMS. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +A timer can be deleted by a task other than the task +which created the timer. + +@page +@ifinfo +@node TIMER_FIRE_AFTER - Fire timer after interval, TIMER_FIRE_WHEN - Fire timer when specified, TIMER_DELETE - Delete a timer, Timer Manager Directives +@end ifinfo +@subsection TIMER_FIRE_AFTER - Fire timer after interval + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer initiated successfully@* +@code{INVALID_ID} - invalid timer id@* +@code{INVALID_NUMBER} - invalid interval + +@subheading DESCRIPTION: + +This directive initiates the timer specified by id. +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire after an +interval ticks clock ticks has passed. When the timer fires, +the timer service routine routine will be invoked with the +argument user_data. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node TIMER_FIRE_WHEN - Fire timer when specified, TIMER_RESET - Reset an interval timer, TIMER_FIRE_AFTER - Fire timer after interval, Timer Manager Directives +@end ifinfo +@subsection TIMER_FIRE_WHEN - Fire timer when specified + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_fire_when( + rtems_id id, + rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer initiated successfully@* +@code{INVALID_ID} - invalid timer id@* +@code{NOT_DEFINED} - system date and time is not set@* +@code{INVALID_CLOCK} - invalid time of day + +@subheading DESCRIPTION: + +This directive initiates the timer specified by id. +If the timer is running, it is automatically canceled before +being initiated. The timer is scheduled to fire at the time of +day specified by wall_time. When the timer fires, the timer +service routine routine will be invoked with the argument +user_data. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node TIMER_RESET - Reset an interval timer, Semaphore Manager, TIMER_FIRE_WHEN - Fire timer when specified, Timer Manager Directives +@end ifinfo +@subsection TIMER_RESET - Reset an interval timer + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_timer_reset( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - timer reset successfully@* +@code{INVALID_ID} - invalid timer id@* +@code{NOT_DEFINED} - attempted to reset a when timer + +@subheading DESCRIPTION: + +This directive resets the timer associated with id. +This timer must have been previously initiated with a +timer_fire_after directive. If active the timer is canceled, +after which the timer is reinitiated using the same interval and +timer service routine which the original timer_fire_after +directive used. + +@subheading NOTES: + +This directive will not cause the running task to be preempted. + diff --git a/doc/user/userext.t b/doc/user/userext.t new file mode 100644 index 0000000000..8166aa1a0e --- /dev/null +++ b/doc/user/userext.t @@ -0,0 +1,649 @@ +@c +@c COPYRIGHT (c) 1996. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c + +@ifinfo +@node User Extensions Manager, User Extensions Manager Introduction, Heterogeneous Systems, Top +@end ifinfo +@chapter User Extensions Manager +@ifinfo +@menu +* User Extensions Manager Introduction:: +* User Extensions Manager Background:: +* User Extensions Manager Operations:: +* User Extensions Manager Directives:: +@end menu +@end ifinfo + +@ifinfo +@node User Extensions Manager Introduction, User Extensions Manager Background, User Extensions Manager, User Extensions Manager +@end ifinfo +@section Introduction + +The RTEMS User Extensions Manager allows the +application developer to augment the executive by allowing them +to supply extension routines which are invoked at critical +system events. The directives provided by the user extensions +manager are: + +@itemize @bullet +@item @code{extension_create} - Create an extension set +@item @code{extension_ident} - Get ID of an extension set +@item @code{extension_delete} - Delete an extension set +@end itemize + +@ifinfo +@node User Extensions Manager Background, Extension Sets, User Extensions Manager Introduction, User Extensions Manager +@end ifinfo +@section Background +@ifinfo +@menu +* Extension Sets:: +* TCB Extension Area:: +* Extensions:: +* TASK_CREATE Extension:: +* TASK_START Extension:: +* TASK_RESTART Extension:: +* TASK_DELETE Extension:: +* TASK_SWITCH Extension:: +* TASK_POST_SWITCH Extension:: +* TASK_BEGIN Extension:: +* TASK_EXITTED Extension:: +* FATAL Error Extension:: +* Order of Invocation:: +@end menu +@end ifinfo + +User extension routines are invoked when the +following system events occur: + +@itemize @bullet +@item Task creation +@item Task initiation +@item Task reinitiation +@item Task deletion +@item Task context switch +@item Post task context switch +@item Task begin +@item Task exits +@item Fatal error detection +@end itemize + +These extensions are invoked as a function with +arguments that are appropriate to the system event. + +@ifinfo +@node Extension Sets, TCB Extension Area, User Extensions Manager Background, User Extensions Manager Background +@end ifinfo +@subsection Extension Sets + +An extension set is defined as a set of routines +which are invoked at each of the critical system events at which +user extension routines are invoked. Together a set of these +routines typically perform a specific functionality such as +performance monitoring or debugger support. RTEMS is informed of +the entry points which constitute an extension set via the +following structure: + +@example +@group +typedef struct @{ + User_extensions_thread_create_extension thread_create; + User_extensions_thread_start_extension thread_start; + User_extensions_thread_restart_extension thread_restart; + User_extensions_thread_delete_extension thread_delete; + User_extensions_thread_switch_extension thread_switch; + User_extensions_thread_post_switch_extension thread_post_switch; + User_extensions_thread_begin_extension thread_begin; + User_extensions_thread_exitted_extension thread_exitted; + User_extensions_fatal_error_extension fatal; +@} User_extensions_Table; +@end group +@end example + + +RTEMS allows the user to have multiple extension sets +active at the same time. First, a single static extension set +may be defined as the application's User Extension Table which +is included as part of the Configuration Table. This extension +set is active for the entire life of the system and may not be +deleted. This extension set is especially important because it +is the only way the application can provided a FATAL error +extension which is invoked if RTEMS fails during the +initialize_executive directive. The static extension set is +optional and may be configured as NULL if no static extension +set is required. + +Second, the user can install dynamic extensions using +the extension_create directive. These extensions are RTEMS +objects in that they have a name, an ID, and can be dynamically +created and deleted. In contrast to the static extension set, +these extensions can only be created and installed after the +initialize_executive directive successfully completes execution. +Dynamic extensions are useful for encapsulating the +functionality of an extension set. For example, the application +could use extensions to manage a special coprocessor, do +performance monitoring, and to do stack bounds checking. Each +of these extension sets could be written and installed +independently of the others. + +All user extensions are optional and RTEMS places no +naming restrictions on the user. + +@ifinfo +@node TCB Extension Area, Extensions, Extension Sets, User Extensions Manager Background +@end ifinfo +@subsection TCB Extension Area + +RTEMS provides for a pointer to a user-defined data +area for each extension set to be linked to each task's control +block. This set of pointers is an extension of the TCB and can +be used to store additional data required by the user's +extension functions. It is also possible for a user extension +to utilize the notepad locations associated with each task +although this may conflict with application usage of those +particular notepads. + +The TCB extension is an array of pointers in the TCB. +The number of pointers in the area is the same as the number of +user extension sets configured. This allows an application to +augment the TCB with user-defined information. For example, an +application could implement task profiling by storing timing +statistics in the TCB's extended memory area. When a task +context switch is being executed, the TASK_SWITCH extension +could read a real-time clock to calculate how long the task +being swapped out has run as well as timestamp the starting time +for the task being swapped in. + +If used, the extended memory area for the TCB should +be allocated and the TCB extension pointer should be set at the +time the task is created or started by either the TASK_CREATE or +TASK_START extension. The application is responsible for +managing this extended memory area for the TCBs. The memory may +be reinitialized by the TASK_RESTART extension and should be +deallocated by the TASK_DELETE extension when the task is +deleted. Since the TCB extension buffers would most likely be +of a fixed size, the RTEMS partition manager could be used to +manage the application's extended memory area. The application +could create a partition of fixed size TCB extension buffers and +use the partition manager's allocation and deallocation +directives to obtain and release the extension buffers. + +@ifinfo +@node Extensions, TASK_CREATE Extension, TCB Extension Area, User Extensions Manager Background +@end ifinfo +@subsection Extensions + +The sections that follow will contain a description +of each extension. Each section will contain a prototype of a +function with the appropriate calling sequence for the +corresponding extension. The names given for the C function and +its arguments are all defined by the user. The names used in +the examples were arbitrarily chosen and impose no naming +conventions on the user. + +@ifinfo +@node TASK_CREATE Extension, TASK_START Extension, Extensions, User Extensions Manager Background +@end ifinfo +@subsection TASK_CREATE Extension + +The TASK_CREATE extension directly corresponds to the +task_create directive. If this extension is defined in any +static or dynamic extension set and a task is being created, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_create( + rtems_tcb *current_task, + rtems_tcb *new_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and new_task can be used to access +the TCB for the new task being created. This extension is +invoked from the task_create directive after new_task has been +completely initialized, but before it is placed on a ready TCB +chain. + +@ifinfo +@node TASK_START Extension, TASK_RESTART Extension, TASK_CREATE Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_START Extension + +The TASK_START extension directly corresponds to the +task_start directive. If this extension is defined in any +static or dynamic extension set and a task is being started, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_start( + rtems_tcb *current_task, + rtems_tcb *started_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and started_task can be used to +access the TCB for the dormant task being started. This +extension is invoked from the task_start directive after +started_task has been made ready to start execution, but before +it is placed on a ready TCB chain. + +@ifinfo +@node TASK_RESTART Extension, TASK_DELETE Extension, TASK_START Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_RESTART Extension + +The TASK_RESTART extension directly corresponds to +the task_restart directive. If this extension is defined in any +static or dynamic extension set and a task is being restarted, +then the extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_restart( + rtems_tcb *current_task, + rtems_tcb *restarted_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and restarted_task can be used to +access the TCB for the task being restarted. This extension is +invoked from the task_restart directive after restarted_task has +been made ready to start execution, but before it is placed on a +ready TCB chain. + +@ifinfo +@node TASK_DELETE Extension, TASK_SWITCH Extension, TASK_RESTART Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_DELETE Extension + +The TASK_DELETE extension is associated with the +task_delete directive. If this extension is defined in any +static or dynamic extension set and a task is being deleted, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_delete( + rtems_tcb *current_task, + rtems_tcb *deleted_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task, and deleted_task can be used to +access the TCB for the task being deleted. This extension is +invoked from the task_delete directive after the TCB has been +removed from a ready TCB chain, but before all its resources +including the TCB have been returned to their respective free +pools. This extension should not call any RTEMS directives if a +task is deleting itself (current_task is equal to deleted_task). + +@ifinfo +@node TASK_SWITCH Extension, TASK_POST_SWITCH Extension, TASK_DELETE Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_SWITCH Extension + +The TASK_SWITCH extension corresponds to a task +context switch. If this extension is defined in any static or +dynamic extension set and a task context switch is in progress, +then the extension routine will automatically be invoked by +RTEMS. The extension should have a prototype similar to the +following: + +@example +rtems_extension user_task_switch( + rtems_tcb *current_task, + rtems_tcb *heir_task +); +@end example + +where current_task can be used to access the TCB for +the task that is being swapped out, and heir_task can be used to +access the TCB for the task being swapped in. This extension is +invoked from RTEMS' dispatcher routine after the current_task +context has been saved, but before the heir_task context has +been restored. This extension should not call any RTEMS +directives. + +@ifinfo +@node TASK_POST_SWITCH Extension, TASK_BEGIN Extension, TASK_SWITCH Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_POST_SWITCH Extension + +The TASK_POST_SWITCH extension corresponds to a task +context switch. If this extension is defined in any static or +dynamic extension set and a raw task context switch has been +completed, then the extension routine will automatically be +invoked by RTEMS. The extension should have a prototype similar +to the following: + +@example +rtems_extension user_task_post_switch( + rtems_tcb *current_task +); +@end example + +where current_task can be used to access the TCB for +the task that is being swapped out, and heir_task can be used to +access the TCB for the task being swapped in. This extension is +invoked from RTEMS' dispatcher routine after the current_task +context has been restored and the extension runs in the context +of the current_task. + +@ifinfo +@node TASK_BEGIN Extension, TASK_EXITTED Extension, TASK_POST_SWITCH Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_BEGIN Extension + +The TASK_BEGIN extension is invoked when a task +begins execution. It is invoked immediately before the body of +the starting procedure and executes in the context in the task. +This user extension have a prototype similar to the following: + +@example +rtems_extension user_task_begin( + rtems_tcb *current_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task which has begun. The distinction +between the TASK_BEGIN and TASK_START extension is that the +TASK_BEGIN extension is executed in the context of the actual +task while the TASK_START extension is executed in the context +of the task performing the task_start directive. For most +extensions, this is not a critical distinction. + +@ifinfo +@node TASK_EXITTED Extension, FATAL Error Extension, TASK_BEGIN Extension, User Extensions Manager Background +@end ifinfo +@subsection TASK_EXITTED Extension + +The TASK_EXITTED extension is invoked when a task +exits the body of the starting procedure by either an implicit +or explicit return statement. This user extension have a +prototype similar to the following: + +@example +rtems_extension user_task_exitted( + rtems_tcb *current_task +); +@end example + +where current_task can be used to access the TCB for +the currently executing task which has just exitted. + +Although exiting of task is often considered to be a +fatal error, this extension allows recovery by either restarting +or deleting the exiting task. If the user does not wish to +recover, then a fatal error may be reported. If the user does +not provide a TASK_EXITTED extension or the provided handler +returns control to RTEMS, then the RTEMS default handler will be +used. This default handler invokes the directive +fatal_error_occurred with the TASK_EXITTED directive status. + +@lowersections + +@ifinfo +@node FATAL Error Extension, Order of Invocation, TASK_EXITTED Extension, User Extensions Manager Background +@end ifinfo +@subsection FATAL Error Extension + +The FATAL error extension is associated with the +fatal_error_occurred directive. If this extension is defined in +any static or dynamic extension set and the fatal_error_occurred +directive has been invoked, then this extension will be called. +This extension should have a prototype similar to the following: + +@example +rtems_extension user_fatal_error_extension( + Internal_errors_Source the_source, + rtems_boolean is_internal, + rtems_unsigned32 the_error +); +@end example + +where the_error is the error code passed to the +fatal_error_occurred directive. This extension is invoked from +the fatal_error_occurred directive. + +If defined, the user's FATAL error extension is +invoked before RTEMS' default fatal error routine is invoked and +the processor is stopped. For example, this extension could be +used to pass control to a debugger when a fatal error occurs. +This extension should not call any RTEMS directives. + +@raisesections + +@ifinfo +@node Order of Invocation, User Extensions Manager Operations, FATAL Error Extension, User Extensions Manager Background +@end ifinfo +@subsection Order of Invocation + +When one of the critical system events occur, the +user extensions are invoked in either "forward" or "reverse" +order. Forward order indicates that the static extension set is +invoked followed by the dynamic extension sets in the order in +which they were created. Reverse order means that the dynamic +extension sets are invoked in the opposite of the order in which +they were created followed by the static extension set. By +invoking the extension sets in this order, extensions can be +built upon one another. At the following system events, the +extensions are invoked in forward order: + +@itemize @bullet +@item Task creation +@item Task initiation +@item Task reinitiation +@item Task deletion +@item Task context switch +@item Post task context switch +@item Task begins to execute +@end itemize + + +At the following system events, the extensions are +invoked in reverse order: + +@itemize @bullet +@item Task deletion +@item Fatal error detection +@end itemize + +At these system events, the extensions are invoked in +reverse order to insure that if an extension set is built upon +another, the more complicated extension is invoked before the +extension set it is built upon. For example, by invoking the +static extension set last it is known that the "system" fatal +error extension will be the last fatal error extension executed. +Another example is use of the task delete extension by the +Standard C Library. Extension sets which are installed after +the Standard C Library will operate correctly even if they +utilize the C Library because the C Library's TASK_DELETE +extension is invoked after that of the other extensions. + +@ifinfo +@node User Extensions Manager Operations, Creating an Extension Set, Order of Invocation, User Extensions Manager +@end ifinfo +@section Operations +@ifinfo +@menu +* Creating an Extension Set:: +* Obtaining Extension Set IDs:: +* Deleting an Extension Set:: +@end menu +@end ifinfo + +@ifinfo +@node Creating an Extension Set, Obtaining Extension Set IDs, User Extensions Manager Operations, User Extensions Manager Operations +@end ifinfo +@subsection Creating an Extension Set + +The extension_create directive creates and installs +an extension set by allocating a Extension Set Control Block +(ESCB), assigning the extension set a user-specified name, and +assigning it an extension set ID. Newly created extension sets +are immediately installed and are invoked upon the next system +even supporting an extension. + +@ifinfo +@node Obtaining Extension Set IDs, Deleting an Extension Set, Creating an Extension Set, User Extensions Manager Operations +@end ifinfo +@subsection Obtaining Extension Set IDs + +When an extension set is created, RTEMS generates a +unique extension set ID and assigns it to the created extension +set until it is deleted. The extension ID may be obtained by +either of two methods. First, as the result of an invocation of +the extension_create directive, the extension set ID is stored +in a user provided location. Second, the extension set ID may +be obtained later using the extension_ident directive. The +extension set ID is used by other directives to manipulate this +extension set. + +@ifinfo +@node Deleting an Extension Set, User Extensions Manager Directives, Obtaining Extension Set IDs, User Extensions Manager Operations +@end ifinfo +@subsection Deleting an Extension Set + +The extension_delete directive is used to delete an +extension set. The extension set's control block is returned to +the ESCB free list when it is deleted. An extension set can be +deleted by a task other than the task which created the +extension set. Any subsequent references to the extension's +name and ID are invalid. + +@ifinfo +@node User Extensions Manager Directives, EXTENSION_CREATE - Create a extension set, Deleting an Extension Set, User Extensions Manager +@end ifinfo +@section Directives +@ifinfo +@menu +* EXTENSION_CREATE - Create a extension set:: +* EXTENSION_IDENT - Get ID of a extension set:: +* EXTENSION_DELETE - Delete a extension set:: +@end menu +@end ifinfo + +This section details the user extension manager's +directives. A subsection is dedicated to each of this manager's +directives and describes the calling sequence, related +constants, usage, and status codes. + +@page +@ifinfo +@node EXTENSION_CREATE - Create a extension set, EXTENSION_IDENT - Get ID of a extension set, User Extensions Manager Directives, User Extensions Manager Directives +@end ifinfo +@subsection EXTENSION_CREATE - Create a extension set + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_extension_create( + rtems_name name, + rtems_extensions_table *table, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - extension set created successfully@* +@code{INVALID_NAME} - invalid extension set name@* +@code{TOO_MANY} - too many extension sets created + +@subheading DESCRIPTION: + +This directive creates a extension set. The assigned +extension set id is returned in id. This id is used to access +the extension set with other user extension manager directives. +For control and maintenance of the extension set, RTEMS +allocates an ESCB from the local ESCB free pool and initializes +it. + +@subheading NOTES: + +This directive will not cause the calling task to be +preempted. + +@page +@ifinfo +@node EXTENSION_IDENT - Get ID of a extension set, EXTENSION_DELETE - Delete a extension set, EXTENSION_CREATE - Create a extension set, User Extensions Manager Directives +@end ifinfo +@subsection EXTENSION_IDENT - Get ID of a extension set + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_extension_ident( + rtems_name name, + rtems_id *id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - extension set identified successfully@* +@code{INVALID_NAME} - extension set name not found + +@subheading DESCRIPTION: + +This directive obtains the extension set id +associated with the extension set name to be acquired. If the +extension set name is not unique, then the extension set id will +match one of the extension sets with that name. However, this +extension set id is not guaranteed to correspond to the desired +extension set. The extension set id is used to access this +extension set in other extension set related directives. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@page +@ifinfo +@node EXTENSION_DELETE - Delete a extension set, Configuring a System, EXTENSION_IDENT - Get ID of a extension set, User Extensions Manager Directives +@end ifinfo +@subsection EXTENSION_DELETE - Delete a extension set + +@subheading CALLING SEQUENCE: + +@example +rtems_status_code rtems_extension_delete( + rtems_id id +); +@end example + +@subheading DIRECTIVE STATUS CODES: +@code{SUCCESSFUL} - extension set deleted successfully@* +@code{INVALID_ID} - invalid extension set id + +@subheading DESCRIPTION: + +This directive deletes the extension set specified by +id. If the extension set is running, it is automatically +canceled. The ESCB for the deleted extension set is reclaimed +by RTEMS. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +A extension set can be deleted by a task other than +the task which created the extension set. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. |
