TIMER USER GUIDE

---

REVISION HISTORY

Revision No.	Description	Date
1.0	Initial release	04/21/2023

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

1. Register Timer
2. Start the timer
3. Interrupt functions for executing timers and processing functions for calling timers in the system
4. Stop timer
5. Unregister timer

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

• Quantity of hardware

  • 8 PM-timer

  • 4 NonPM-timer

• CLK

  • PM-timer0 ~ PM-timer3 and NonPM-timers use the same clock, with a default frequency of 12MHz, PM timer4~PM timer7 each use different clocks.

  • PM-timer0 ~ PM-timer3 each use different hardware interrupt numbers, while PM-timer4 ~ PM-timer7 use the same hardware interrupt number.

• Limitation

  • Software limitation: 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-->
    [*] SStar SoC platform drivers-->
        [*] Sigmastar 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 = "sstar,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 = "sstar,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	"sstar,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 sstar_timer_ut_callback(void *pdata)
{
   int *timer_done = pdata;

   *timer_done = 1;
  }

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

  handle = sstar_timer_register(timer_id, SSTAR_TIMER_MODE_RUNLOOP,
                                sstar_timer_ut_callback, &timer_done)))
  if (handle == NULL)
  {
    pr_err("register timer fail\n");
    return -1;
  }

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

  sstar_timer_unregister(handle);
  return 0;

}

6.6. UT case

The kernel unit test cases for timers are defined in the kernel/drivers/stars/timer/ut directory. Executing make in the directory for compilation will result in the test case timer_ut.ko. Copy timer_ut.ko to the board and execute insmod timer_ut.ko for testing.

7. API reference

This functional module provides the following interfaces:

API Name	Function
sstar_timer_register	Register timer
sstar_timer_unregister	Unregister timer
sstar_timer_start	Start timer
sstar_timer_stop	Stop timer
sstar_timer_get_current	Get the time that has passed since the timer was started until now
sstar_timer_device_count	Get the number of timers
sstar_timer_find_idle	Find the first avaiable timer

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

7.1. sstar_timer_register

• Function

  Register timer

• Grammar

  sstar_timer_handle sstar_timer_register(unsigned int timer_id,
                                    enum sstar_timer_mode mode,
                                    sstar_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. sstar_timer_unregister

• Function

  Unregister timer

• Grammar

  int sstar_timer_unregister(sstar_timer_handle handle)
  

• Parameters

  Parameter Name	Description
  handle	Pointer to a specific timer

• Return value

  Return value	Description
  0	Successful
  other	Failed

7.3. sstar_timer_start

• Function

  Start timer

• Grammar

  int sstar_timer_start(sstar_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
  other	Failed

7.4. sstar_timer_stop

• Function

  Stop timer

• Grammar

  int sstar_timer_stop(sstar_timer_handle handle)
  

• Parameters

  Parameter Name	Description
  handle	Pointer to a specific timer

• Return value

  Return value	Description
  0	Successful
  other	Failed

7.5. sstar_timer_get_current

• Function

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

• Grammar

  int sstar_timer_get_current(sstar_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
  other	Failed

7.6. sstar_timer_device_count

• Function

  Get the number of timers

• Grammar

  int sstar_timer_device_count(void)
  

• Parameters

  Parameter Name	Description
  void	NA

• Return value

  Return value	Description
  int	The number of timers

7.7. sstar_timer_find_idle

• Function

  Find the first avaiable timer

• Grammar

  int sstar_timer_find_idle(void)
  

• Parameters

  Parameter Name	Description
  void	NA

• Return value

  Return value	Description
  int	The first available timer number

8. FAQ

NA