CVS difference for ais/ai-00307.txt

Differences between 1.11 and version 1.12
Log of other versions for file ais/ai-00307.txt

--- ais/ai-00307.txt	2004/06/25 03:12:16	1.11
+++ ais/ai-00307.txt	2004/07/27 23:00:57	1.12
@@ -1,4 +1,5 @@
-!standard D.14 (01)                                  04-03-25  AI95-00307/08
+!standard D.14 (00)                                  04-06-25  AI95-00307/09
+!standard D.14.1 (00)
 !class amendment 02-08-28
 !status Amendment 200Y 04-06-24
 !status ARG Approved 8-0-0  04-06-13
@@ -14,37 +15,22 @@
 !summary
 
 Modern real-time scheduling policies require that applications have
-the ability to measure execution time of tasks, and to detect
-execution time overruns. Two mechanisms were proposed to achieve these
-requirements. One was based on a library-level package, and the other
-one was integrated into the Ada 95 language by creating a new Time
-type that could be used in the languages time constructs such as the
-delay until statement or various forms of the select
-statement. Prototype implementations exist for both.
-
-After discussion by the ARG it was decided that the package
-mechanism was preferable, and a few changes were suggested. This
-document describes the package mechanism only, and includes the
-changes requested by the ARG. A discussion of these changes can be
-found at the end of the "Discussion" section.
-
-This revision of the AI was produced by IRTAW 12 in response to the
-requirement to be able to wait for one or more Timers to expire. This
-has required a restructuring of the proposed solution. The consequence
-is that the Timer is no longer a protected object. Timer expirations
-are notified by the system by calling a protected procedure that is
-passed to it by an access parameter in the Timer operations.
+the ability to the measure execution time of tasks, and to detect
+execution time overruns. This functionality is provided by a new
+package that defines execution time clocks and a child of this package
+which provides timers.
 
 !problem
 
-Real-time analysis techniques are always based on the assumption that
-the application developer can accurately measure the worst-case
-execution time (WCET) of each task. This measurement is always very
+Performance analysis techniques are usually based on the assumption that
+the application developer can accurately measure/estimate the
+execution time of each task. Measurement is always very
 difficult, because, with effects like cache misses, pipelined and
 superscalar processor architectures, etc., the execution time is
 highly unpredictable. There are models that allow calculation of
-WCET's for some architectures, but they are generally very complex
-and not widely available for all architectures.
+worst-case execution time (WCET) for some architectures, but they are
+generally very complex and not widely available for all architectures.
+A language defined means of measuring execution time is desirable.
 
 In hard real-time systems it is essential to monitor the execution
 times of all tasks and detect situations in which the estimated WCET
@@ -231,7 +217,9 @@
 When appropriate, implementations should provide configuration
 mechanisms to change the value of CPU_Tick.
 
-Add new section D.14.1
+
+Add new section D.14.1:
+
 D.14.1 Execution Time Timers
 
 This clause specifies a child of Execution_Time that provides a
@@ -245,7 +233,6 @@
 with Ada.Task_Identification;
 with System;
 with Ada.Real_Time; use Ada.Real_Time;
-with Ada.Execution_Time;
 package Ada.Execution_Time.Timers is
 
    type Timer (T : access Ada.Task_Identification.Task_ID) is
@@ -254,7 +241,7 @@
    type Handler is not null access protected procedure (TM : in out Timer);
 
    Min_Handler_Ceiling : constant System.Any_Priority :=
-    <Implementation Defined>;
+    implementation-defined;
 
    procedure Arm (TM: in out Timer; Interval : Time_Span; H : Handler);
    procedure Arm (TM: in out Timer; Abs_Time : CPU_Time;  H : Handler);
@@ -263,8 +250,8 @@
    function Timer_Has_Expired(TM : Timer) return Boolean;
    function Time_Remaining(TM : Timer) return Time_Span;
 
-   Timer_Error : exception;
-   Timer_Resource_Error : exception;
+   Timer_Error : @b<exception>;
+   Timer_Resource_Error : @b<exception>;
 
 private
    ... --  not specified by the language
@@ -348,6 +335,25 @@
 
 !discussion
 
+Modern real-time scheduling policies require that applications have
+the ability to measure execution time of tasks, and to detect
+execution time overruns. Two mechanisms were proposed to achieve these
+requirements. One was based on a library-level package, and the other
+one was integrated into the Ada 95 language by creating a new Time
+type that could be used in the languages time constructs such as the
+delay until statement or various forms of the select
+statement. Prototype implementations exist for both.
+
+After discussion by the ARG it was decided that the package
+mechanism was preferable.
+
+A revision of the AI was produced by IRTAW 12 in response to the
+requirement to be able to wait for one or more Timers to expire. This
+has required a restructuring of the earlier solution. The consequence
+is that the Timer is no longer a protected object. Timer expirations
+are notified by the system by calling a protected procedure that is
+passed to it by an access parameter in the Timer operations.
+
 A prototype implementations was developed for the initial proposal, using the
 MaRTE operating system that provides a POSIX.13 interface and includes
 execution-time clocks and timers.
@@ -545,8 +551,269 @@
    end Worker;
 
 ...
+
+!corrigendum D.14(01)
+
+@dinsc
+
+This clause specifies an execution-time clock package.
+
+@i<@s8<Static Semantics>>
+
+The following language-defined library package exists:
+
+@xcode<@b<with> Ada.Task_Identification;
+@b<with> Ada.Real_Time; @b<use> Ada.Real_Time;
+@b<package> Ada.Execution_Time @b<is>
+
+   @b<type> CPU_Time @b<is private>;
+   CPU_Time_First : @b<constant> CPU_Time;
+   CPU_Time_Last  : @b<constant> CPU_Time;
+   CPU_Time_Unit  : @b<constant> := @ft<@i<implementation-defined-real-number>>;
+   CPU_Tick : @b<constant> Time_Span;
+
+   @b<function> Clock
+     (T : Ada.Task_Identification.Task_ID
+          := Ada.Task_Identification.Current_Task)
+     @b<return> CPU_Time;
+
+   @b<function> "+"  (Left : CPU_Time; Right : Time_Span) @b<return> CPU_Time;
+   @b<function> "+"  (Left : Time_Span; Right : CPU_Time) @b<return> CPU_Time;
+   @b<function> "-"  (Left : CPU_Time; Right : Time_Span) @b<return> CPU_Time;
+   @b<function> "-"  (Left : CPU_Time; Right : CPU_Time)  @b<return> Time_Span;
+
+   @b<function> "<"  (Left, Right : CPU_Time) @b<return> Boolean;
+   @b<function> "<=" (Left, Right : CPU_Time) @b<return> Boolean;
+   @b<function> "@>"  (Left, Right : CPU_Time) @b<return> Boolean;
+   @b<function> "@>=" (Left, Right : CPU_Time) @b<return> Boolean;
+
+   @b<procedure> Split
+      (T : CPU_Time; SC : @b<out> Seconds_Count; TS : @b<out> Time_Span);
+
+   @b<function> Time_Of (SC : Seconds_Count; TS : Time_Span) @b<return> CPU_Time;
+
+@b<private>
+   ... --  not specified by the language
+@b<end> Ada.Execution_Time;>
+
+Execution time or CPU time of a given task is defined as the time spent
+by the system executing that task, including the time spent executing
+run-time or system services on behalf of it. The mechanism used to
+measure execution time is implementation defined. It is implementation
+defined which task, if any, is charged the execution time that is
+consumed by interrupt handlers and run-time services on behalf of the
+system.
+
+The type CPU_Time represents the execution time of a task. The set of
+values of the type CPU_Time corresponds one-to-one with an
+implementation-defined range of mathematical integers.
+
+The CPU_Time value I represents the half-open execution-time interval
+that starts with I*CPU_Time_Unit and is limited by
+(I+1)*CPU_Time_Unit, where CPU_Time_Unit is an implementation-defined
+real number. For each task, the execution time value is set to zero at
+some unspecified point between the task creation and the start of the
+task's activation.
+
+CPU_Time_First and CPU_Time_Last are the smallest and largest values
+of the Time type, respectively.
+
+@i<@s8<Dynamic Semantics>>
+
+CPU_Time_Unit is the smallest amount of execution time representable
+by the CPU_Time type; it is expressed in seconds. A CPU clock tick is an
+execution time interval during which the clock value (as observed by
+calling the Clock function) remains constant. CPU_Tick is the average
+length of such intervals.
+
+The effects of the operators on CPU_Time and Time_Span are as for the
+operators defined for integer types.
+
+The function Clock returns the amount of execution time of the task
+associated with the execution-time clock of the task represented by T.
+
+The effects of the Split and Time_Of operations are defined as
+follows, treating values of type CPU_Time, Time_Span, and
+Seconds_Count as mathematical integers. The effect of Split (T, SC,
+TS) is to set SC and TS to values such that T*CPU_Time_Unit = SC*1.0 +
+TS*CPU_Time_Unit, and 0.0 <= TS*CPU_Time_Unit < 1.0. The value
+returned by Time_Of(SC,TS) is the execution-time value T such that
+T*CPU_Time_Unit=SC*1.0 + TS*CPU_Time_Unit.
+
+For all the operations and types defined in this package, Tasking_Error
+is raised if the task identified by T has terminated. Program_Error
+is raised if the value of T is Null_Task_ID.
+
+@i<@s8<Erroneous Execution>>
+
+If a value of Task_ID is passed as a parameter to any of the subprograms
+of this package or used to define an object declared by a type provided by
+this package (or any language-defined child package of this package) and the
+corresponding task object no longer exists, the execution of the
+program is erroneous.
+
+@i<@s8<Implementation Requirements>>
+
+The range of CPU_Time values shall be sufficient to uniquely represent
+the range of execution times from the task start-up to 50 years of
+execution time later. CPU_Tick shall be no greater than 1 millisecond.
+
+@i<@s8<Documentation Requirements>>
+
+The implementation shall document the values of CPU_Time_First,
+CPU_Time_Last, CPU_Time_Unit, and CPU_Tick.
+
+The implementation shall document the properties of the underlying
+mechanism used to measure execution times, such as the range of
+values supported and any relevant aspects of the underlying hardware
+or operating system facilities used.
+
+@i<@s8<Metrics>>
+
+The implementation shall document the following metrics:
+
+@xbullet<An upper bound on the execution-time duration of a clock
+tick. This is a value D such that if t1 and t2 are any execution
+times of a given task such that t1<t2 and Clock[t1]=Clock[t2]
+then t2-t1 <= D.>
+
+@xbullet<An upper bound on the size of a clock jump. A clock jump is the
+difference between two successive distinct values of an execution
+-time clock (as observed by calling the Clock function with the
+same Task_Id).>
+
+@xbullet<An upper bound on the execution time of a call to the Clock
+function, in processor clock cycles.>
+
+@xbullet<Upper bounds on the execution times of the operators of the type
+CPU_Time, in processor clock cycles.>
+
+@i<@s8<Implementation Permissions>>
+
+Implementations targeted to machines with word size smaller than 32
+bits need not support the full range and granularity of the CPU_Time
+type.
+
+@i<@s8<Implementation Advice>>
+
+When appropriate, implementations should provide configuration
+mechanisms to change the value of CPU_Tick.
+
+!corrigendum D.14.1(01)
+
+@dinsc
+
+This clause specifies a child of Execution_Time that provides a
+facility for calling a handler when a task has used a defined quantity
+of CPU time.
+
+@i<@s8<Static Semantics>>
+
+The following language-defined library package exists:
+
+@xcode<@b<with> Ada.Task_Identification;
+@b<with> System;
+@b<with> Ada.Real_Time; @b<use> Ada.Real_Time;
+@b<package> Ada.Execution_Time.Timers @b<is>
+
+   @b<type> Timer (T : access Ada.Task_Identification.Task_ID) @b<is>
+      @b<limited private>;
+
+   @b<type> Handler @b<is not null access protected procedure> (TM : @b<in out> Timer);
+
+   Min_Handler_Ceiling : @b<constant> System.Any_Priority :=
+    @ft<@i<implementation-defined>>;
+
+   @b<procedure> Arm (TM: @b<in out> Timer; Interval : Time_Span; H : Handler);
+   @b<procedure> Arm (TM: @b<in out> Timer; Abs_Time : CPU_Time;  H : Handler);
+   @b<procedure> Disarm(TM : @b<in out> Timer);
+
+   @b<function> Timer_Has_Expired(TM : Timer) @b<return> Boolean;
+   @b<function> Time_Remaining(TM : Timer) @b<return> Time_Span;
+
+   Timer_Error : @b<exception>;
+   Timer_Resource_Error : @b<exception>;
+
+@b<private>
+   ... --  not specified by the language
+@b<end> Ada.Execution_Time.Timers;>
+
+The type Timer needs finalization (see 7.6).
+
+@i<@s8<Dynamic Semantics>>
+
+Type Timer represents a software object that is capable of detecting
+execution time overruns. Each timer is attached to a specific
+execution time clock, which is the clock of the task specified
+by the access discriminant T. This type has operations for the
+application tasks to arm or disarm a timer, and to determine whether a timer
+has expired or not (Timer_Has_Expired). In addition, when arming the timer, an
+access to a protected procedure (type Handler) is passed. This procedure
+will be called by the implementation when the timer expires.
+
+The constant Min_Handler_Ceiling is the priority value that will insure that
+no ceiling violation will occur when a handler is executed.
+
+When a Timer object is created, or upon the first call to one of its Arm
+procedures, the resources required to operate a CPU-time timer based on
+the associated execution-time clock will be allocated and initialized.
+The timer is initialized in the disarmed state. If this operation would
+exceed the limit of the maximum number of timers in the system, the
+Timer_Resource_Error exception is raised.
+
+The Arm procedure that takes a Time_Span parameter loads the associated timer
+with the relative value specified by Interval and sets it to the armed state.
+In this state the timer counts execution time and, when the CPU clock
+associated with the timer measures the passage of Interval, it is said to have
+expired. If the timer was already armed, it is rearmed.
+
+The Arm procedure that takes a CPU_Time parameter loads the associated timer
+with the absolute value specified by Abs_Time and sets it to the armed state.
+In this state the timer monitors execution time and, when the CPU clock
+associated with the timer reaches the value Abs_Time, it is said to have
+expired. If the value of Abs_Time had already been reached by the clock at the
+time of the call, the timer is set to the armed state and is said to have
+expired. If the timer was already armed, it is rearmed.
+
+When a Timer expires, the protected procedure Handler is invoked by the system
+with a parameter equal to the Timer.
+
+The Disarm procedure sets the timer to the disarmed state. In this
+state the timer will not expire.
+
+The Time_Has_Expired function returns True if the timer is in the
+armed state and has expired, and returns False if the timer is in the
+armed state but has not yet expired. If the timer is in the disarmed
+state, the Timer_Error exception is raised.
+
+The Time_Remaining function returns, when the timer is in the armed state, the
+CPU time interval that remains until the timer will expire, or a value
+representing zero if the timer has expired. If the timer is in the disarmed
+state, the Timer_Error exception is raised.
+
+The Timer_Error exception is raised by Timer_Has_Expired, or
+Time_Remaining if an attempt is made to use a timer that is in the
+disarmed state.
+
+For all the operations and types defined in this package, Tasking_Error
+is raised if the task identified by T has terminated. Program_Error
+is raised if the value of T is Null_Task_ID.
+
+@i<@s8<Implementation Requirements>>
+
+For a given Timer object, the implementation shall perform the operations
+declared in this package atomically with respect to any of these
+operations on the same Timer object.
+
+When an object of type Timer is finalized, the system resources used by
+the timer shall be deallocated.
+
+@i<@s8<Implementation Permissions>>
+
+Implementations may limit the number of timers that can be defined for
+each task. If this limit is exceeded the Timer_Resource_Error exception
+is raised.
 
---!corrigendum D.13(01)
 
 !ACATS test
 

Questions? Ask the ACAA Technical Agent