Embedded Design Handbook

ID 683689
Date 8/28/2023
Public
Document Table of Contents

4.2.3.3.1. Timers

The HAL provides two types of timer services, a system clock timer and a timestamp timer. The system clock timer is used to control, monitor, and schedule system events. The timestamp variant is used to make high performance timing measurements. Each of these timer services is assigned to a single Intel Avalon Timer peripheral.

For more information about this peripheral, refer to the Interval Timer Core chapter of the Embedded Peripherals IP User Guide.

System Clock Timer

The system clock timer resource is used to trigger periodic events (alarms), and as a timekeeping device that counts system clock ticks. The system clock timer service requires that a timer peripheral be present in the Platform Designer system. This timer peripheral must be dedicated to the HAL system clock timer service.

Note: Only one system clock timer service may be identified in the BSP library. This timer should be accessed only by HAL supplied routines.

The hal.sys_clk_timer setting controls the BSP project configuration for the system clock timer. This setting configures one of the timers available in your Platform Designer design as the system clock timer.

Intel provides separate APIs for application-level system clock functionality and for generating alarms.

Application-level system clock functionality is provided by two separate classes of APIs, one Nios® II specific and the other Unix-like. The Intel function alt_nticks returns the number of clock ticks that have elapsed. You can convert this value to seconds by dividing by the value returned by the alt_ticks_per_second() function. For most embedded applications, this function is sufficient for rudimentary time keeping.

The POSIX-like gettimeofday() function behaves differently in the HAL than on a Unix workstation. On a workstation, with a battery backed-up, real-time clock, this function returns an absolute time value, with the value zero representing 00:00 Coordinated Universal Time (UTC), January 1, 1970, whereas in the HAL, this function returns a time value starting from system power-up. By default, the function assumes system power-up to have occurred on January 1, 1970. Use the settimeofday() function to correct the HAL gettimeofday() response. The times() function exhibits the same behavior difference.

Consider the following common issues and important points before you implement a system clock timer:
  • System Clock Resolution—The timer’s period value specifies the rate at which the HAL BSP project increments the internal variable for the system clock counter. If the system clock increments too slowly for your application, you can decrease the timer's period in Platform Designer.
  • Rollover—The internal, global variable that stores the number of system clock counts (since reset) is a 32-bit unsigned integer. No rollover protection is offered for this variable. Therefore, you should calculate when the rollover event occurs in your system, and plan the application accordingly.
  • Performance Impact—Every clock tick causes the execution of an interrupt service routine. Executing this routine leads to a minor performance penalty. If your system hardware specifies a short timer period, the cumulative interrupt latency may impact your overall system performance.

The alarm API allows you to schedule events based on the system clock timer, in the same way an alarm clock operates. The API consists of the alt_alarm_start() function, which registers an alarm, and the alt_alarm_stop() function, which disables a registered alarm.

Consider the following common issues and important points before you implement an alarm:

  • Interrupt Service Routine (ISR) context—A common mistake is to program the alarm callback function to call a service that depends on interrupts being enabled (such as the printf() function). This mistake causes the system to deadlock, because the alarm callback function occurs in an interrupt context, while interrupts are disabled.
  • Resetting the alarm—The callback function can reset the alarm by returning a nonzero value. Internally, the alt_alarm_start() function is called by the callback function with this value.
  • Chaining—The alt_alarm_start() function is capable of handling one or more registered events, each with its own callback function and number of system clock ticks to the alarm.
  • Rollover—The alarm API handles clock rollover conditions for registered alarms seamlessly.

A good timer period for most embedded systems is 50 ms. This value provides enough resolution for most system events, but does not seriously impact performance nor roll over the system clock counter too quickly.

Timestamp Timer

The timestamp timer service provides applications with an accurate way to measure the duration of an event in the system. The timestamp timer service requires that a timer peripheral be present in the Platform Designer system. This timer peripheral must be dedicated to the HAL timestamp timer service.

Only one timestamp timer service may be identified in the BSP library file. This timer should be accessed only by HAL supplied routines.

The hal.timestamp_timer setting controls the BSP configuration for the timer. This setting configures one of the timers available in the Platform Designer design as the timestamp timer.

Intel provides a timestamp API. The timestamp API is very simple. It includes the alt_timestamp_start() function, which makes the timer operational, and the alt_timestamp() function, which returns the current timer count.

Consider the following common issues and important points before you implement a timestamp timer:

  • Timer Frequency—The timestamp timer decrements at the clock rate of the clock that feeds it in the Platform Designer system. You can modify this frequency in Platform Designer.
  • Rollover—The timestamp timer has no rollover event. When the alt_timestamp() function returns the value 0, the timer has run down.
  • Maximum Time—The timer peripheral has 32 bits available to store the timer value. Therefore, the maximum duration a timestamp timer can count is ((1/timer frequency) × 232) seconds.

For more information about the APIs that control the timestamp and system clock timer services, refer to the HAL API Reference chapter of the Nios® II Gen2 Software Developer's Handbook.