[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Base Operating System and Extensions Technical Reference, Volume 2

read_real_time or time_base_to_time Subroutine

Purpose

Read the processor real time clock or time base registers to obtain high-resolution elapsed time.

Library

Standard C Library (libc.a)

Syntax

#include <sys/time.h>
#include <sys/systemcfg.h>
int read_real_time(timebasestruct_t 
*t,
                           size_t 
size_of_timebasestruct_t);
int time_base_to_time(timebasestruct_t 
*t,
                           size_t size_of_timebasestruct_t);

Description

These subroutines are designed to be used for making high-resolution measurement of elapsed time, using the processor real time clock or time base registers. The read_real_time subroutine reads the value of the appropriate registers and stores them in a structure. The time_base_to_time subroutine converts time base data to real time, if necessary. This process is divided into two steps because the process of reading the time is usually part of the timed code, and so the conversion from time base to real time can be moved out of the timed code.

The read_real_time subroutine reads either the processor real time clock (for POWER or PowerPC 601 RISC Microprocessor) or the time base register (in the case of PowerPC processors other than the PowerPC 601 RISC Microprocessor). The t argument is a pointer to a timebasestruct_t, where the time values are recorded.

After calling read_real_time, if running on a processor with a real time clock, t->tb_high and t->tb_low contain the current clock values (seconds and nanoseconds), and t->flag contains the RTC_POWER.

If running on a processor with a time base register, t->tb_high and t-tb_low contain the current values of the time base register, and t->flag contains RTC_POWER_PPC.

The time_base_to_time subroutine converts time base information to real time, if necessary. It is recommended that applications unconditionally call the time_base_to_time subroutine rather than performing a check to see if it is necessary.

If t->flag is RTC_POWER, the subroutine simply returns (the data is already in real time format).

If t->flag is RTC_POWER_PPC, the time base information in t->tb_high and t->tb_low is converted to seconds and nanoseconds; t->tb_high is replaced by the seconds; t->tb_low is replaced by the nanoseconds; and t->flag is changed to RTC_POWER.

Parameters

t Points to a timebasestruct_t.

Return Values

The read_real_time subroutine returns RTC_POWER if the contents of the real time clock has been recorded in the timebasestruct, or returns RTC_POWER_PPC if the content of the time base registers has been recorded in the timebasestruct.

The time_base_to_time subroutine returns 0 if the conversion to real time is successful (or not necessary), otherwise -1 is returned.

Examples

This example shows the time it takes for print_f to print the comment between the begin and end time codes:

#include <stdio.h>
#include <sys/time.h>
 
int
main(void)
{
   timebasestruct_t start, finish;
   int val = 3;
   int secs, n_secs;
 
   /* get the time before the operation begins */
   read_real_time(&start, TIMEBASE_SZ);
 
   /* begin code to be timed */
   (void) printf("This is a sample line %d \n", val);
   /* end code to be timed   */
 
   /* get the time after the operation is complete */
   read_real_time(&finish, TIMEBASE_SZ);
 
   /*
    * Call the conversion routines unconditionally, to ensure
    * that both values are in seconds and nanoseconds regardless
    * of the hardware platform. 
    */
   time_base_to_time(&start, TIMEBASE_SZ);
   time_base_to_time(&finish, TIMEBASE_SZ);
 
   /* subtract the starting time from the ending time */
   secs = finish.tb_high - start.tb_high;
   n_secs = finish.tb_low - start.tb_low;
 
  /*
   * If there was a carry from low-order to high-order during 
   * the measurement, we may have to undo it. 
   */
   if (n_secs < 0)  {
      secs--;
      n_secs += 1000000000;
      }
 
   (void) printf("Sample time was %d seconds %d nanoseconds\n",
                secs, n_secs);
 
   exit(0);
}

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The gettimer, settimer, restimer, stime, or time Subroutines.

The getrusage, times, or vtimes Subroutines.

High-Resolution Time Measurements Using PowerPC Time Base or POWER Real-Time Clock in AIX General Programming Concepts: Writing and Debugging Programs.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]