TIMER USER GUIDE¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	11/06/2024
1.1	Delete Rtos Usage Reference section	04/23/2025

1. OVERVIEW¶

Timer is a hardware module used in computer and microcontroller systems to measure time intervals or generate precise timing events. The basic working principle of a timer is to drive a counter through a clock source. When the counter reaches a preset value, an event is generated, usually through an interrupt to notify the processor.

2. KEYWORD DESCRIPTION¶

PM-timer

Timer powered by PM domain.
NonPMtimer

Timer powered by NonPM domain.
OneShoot mode

A working mode of Timer that triggers an interrupt when the timer reaches a certain time.
RunLoop mode

A working mode of Timer, which will reset the counting core and trigger a loop after the timer is triggered.

3. FUNCTION DESCRIPTION¶

Whether it is PM timer or NonPM timer, the use of timers has the same steps. From a development perspective, there are five steps involved

Register Timer
Start the timer
Interrupt functions for executing timers and processing functions for calling timers in the system
Stop timer
Unregister timer

In addition, when using a timer, the following factors need to be considered:：

Quantity of hardware
- The numbers of PM timer and NonPM timer are determined by the set in Kernel dts, and special attention should be paid to multiple timers that share the same interrupt number.
CLK
- Timer0 ~ Timer7 use the same clock, with a default frequency of 12MHz, Timer8~Timer11 use another clock, with a default frequency of 432M.
Limitation
- Software limitation: If the platform has builtin riscv core, then riscv side and arm side cannot use the same timer at the same time, which may cause interrupt confusion.
working mode
- Timer has two working modes, one is oneshook mode and the other is RunLoop mode.

4. HARDWARE CONNECTION INTRODUCTION¶

NA

5. UBOOT USAGE INTRODUCTION¶

NA

6. Introduction to Kernel Usage¶

6.1. CONFIG configuration¶

The CONFIG configuration related to timer driver is as follows:

Device Drivers-->
    [*] Sgs SoC platform drivers-->
        [*] SGS Timer Driver

6.2. DTS configuration¶

You can set the basic parameters of each timer by configuring PM-timer0 ~ PM-timer7 and NonPM-timer0 ~ NonPM-timer3 in dtsi. The parameters of dtsi are displayed as follows:

1.    PMtimer0: pm-timer0 {
2.        compatible = "sgs,timer";
3.        reg = <0x0 0x1F006040 0x0 0x40>;
4.        interrupts = <GIC_SPI INT_IRQ_PM_TIMER_OR IRQ_TYPE_LEVEL_HIGH>;
5.        clocks = <&CLK_mcu_pm>;
6.        status = "disabled";
7.    }；
8.    ...
9.
10.
11.   nonpm-timer1 {
12.       compatible = "sgs,timer";
13.       reg = <0x0 0x1F2CDE80 0x0 0x40>;
14.       interrupts = <GIC_SPI INT_IRQ_NONPM_TIMER_1 IRQ_TYPE_LEVEL_HIGH>;
15.       clocks = <&CLK_mcu>;
16.       status = "okay";
17.   };
18.   ...

As shown above, the dts content of pm timer and non pm timer is similar, and their attribute definitions are as follows:

Attribute	Desciiption	Set Value	Notes
compatible	Match driver for driver registration	"sgs,timer"	Prohibit modification
reg	Watchdog register information	Hardware design decision	Prohibit modification
interrupts	interrupt type/interrupt number/trigger type	Hardware design decision	Prohibit modification
clocks	Clock info	Hardware design decision	Prohibit modification
status	Select whether to enable this timer	"ok" or "disable"	Modify as needed

6.3. Padmux configuration¶

NA

6.4. Module Usage Introduction¶

6.4.1. SYSFS usage method¶

NA

6.4.2. How to use ioctl¶

NA

6.5. Sample code¶

void drv_timer_ut_callback(void *pdata)
{
   int *timer_done = pdata;

   *timer_done = 1;
  }

static int __init drv_timer_ut_init(void)
{
  int                timer_done   = 0;
  unsigned int       timer_id     = 0;

  handle = drv_timer_register(timer_id, DRV_TIMER_MODE_RUNLOOP,
                                drv_timer_ut_callback, &timer_done)))
  if (handle == NULL)
  {
    pr_err("register timer fail\n");
    return -1;
  }

  drv_timer_start(handle, 2000);
  msleep(2000);
  if (!timer_done)
  {
      pr_err("[TIMER%d][UT] result : FAILED\n", timer_id);
  }

  drv_timer_unregister(handle);
  return 0;

}

6.6. UT case¶

Linux testing demo:< Kernel>/drivers/drv_common/timer/ut/lnx/timer_lnx_ut.c， Compile and you can get timer_lnx_ut.ko, copy it to board then do insmod timer_lnx_ut.ko will begin test.

7. API reference¶

This functional module provides the following interfaces:

API Name	Function
drv_timer_register	Registertimer
drv_timer_unregister	Unregister timer
drv_timer_start	Start timer
drv_timer_stop	Stop timer
drv_timer_get_current	Get the time that has passed since the timer was started until now
drv_timer_device_count	Get the number of timers
drv_timer_find_idle	Find the first avaiable timer

The relevant header file is kernel/drivers/sgs_common/include/drv_timer.h.

7.1. drv_timer_register¶

Function

Register timer

Grammar

drv_timer_handle drv_timer_register(unsigned int timer_id,
                                  enum drv_timer_mode mode,
                                  drv_timer_callback callback,
                                  void *pdata);

Parameters

Parameter Name	Description
timer_id	timer ID [1,max]
mode	timer working model
callback	callback function, which will be called when Timer generates an interrupt
*pdata	Private data passed to callback function

Return value

Return value Description

handle pointer to a specific timer

7.2. drv_timer_unregister¶

Function

Unregister timer

Grammar

 int drv_timer_unregister(drv_timer_handle handle)

Parameters

Parameter Name Description

handle pointer to a specific timer
Return value

Return value Description

0 Successful

7.3. drv_timer_start¶

Function

Start timer

Grammar

int drv_timer_start(drv_timer_handle handle,
                    unsigned long long exp_time)

Parameters

Parameter Name Description

handle pointer to a specific timer

exp_time Timer expiration time (ms)
Return value

Return value Description

0 Successful

7.4. drv_timer_stop¶

Function

Stop timer

Grammar

int drv_timer_stop(drv_timer_handle handle)

Parameters

Parameter Name Description

handle pointer to a specific timer

exp_time Timer expiration time (ms)
Return value

Return value Description

0 Successful

7.5. drv_timer_get_current¶

Function

Get the time that has passed since the timer was started until now.

Grammar

int drv_timer_get_current(drv_timer_handle handle,
                            unsigned long long *ptime)

Parameters

Parameter Name Description

handle pointer to a specific timer

ptime the time that has passed since the timer was started until now (ms)
Return value

Return value Description

0 Successful

7.6. drv_timer_device_count¶

Function

Get the number of timers
Grammar
```
int drv_timer_device_count(void)
```
Parameters

Parameter Name Description

NA NA
Return value

Return value Description

0 the number of timers

7.7. drv_timer_find_idle¶

Function

Find the first avaiable timer
Grammar
```
int drv_timer_find_idle(void)
```
Parameters

Parameter Name Description

NA NA
Return value

Return value Description

0 The first available timer number

8. FAQ¶

NA

Parameter Name	Description
handle	pointer to a specific timer
exp_time	Timer expiration time (ms)

Parameter Name	Description
handle	pointer to a specific timer
ptime	the time that has passed since the timer was started until now (ms)