# Timer HAL interface documentation

## Hardware introduction

K230 internally integrates 6 hardware timers (Timer0~Timer5) and supports upward counting mode. Each timer can independently configure frequency, period and working mode. It also provides a software timer function, implemented based on POSIX timer, which can be used in timing scenarios that do not require high accuracy.

---

## Data structure description

### `rt_hwtimer_info_t`

**Description**: Timer hardware feature information.

- `maxfreq`: Maximum supported counting frequency
- `minfreq`: Minimum supported counting frequency
- `maxcnt`: counter maximum value
- `cntmode`: counting mode (HWTIMER_CNTMODE_UP: counting up)

### `rt_hwtimer_mode_t`

**Description**: Timer working mode enumeration.

- `HWTIMER_MODE_ONESHOT`: Single trigger mode
- `HWTIMER_MODE_PERIOD`: Period trigger mode

### `timer_irq_callback`

**Description**: Timer interrupt callback function type.

```c
typedef void (*timer_irq_callback)(void* args);
```

---

## Hardware timer interface

### `int drv_hard_timer_inst_create(int id, drv_hard_timer_inst_t** inst);`

**Function**: Create a hardware timer instance.

**parameter**:

- `id`: timer number, range `[0, 5]`
- `inst`: used to store the created timer instance pointer

**Return Value**:

- `0`: Success
- `Negative value`: failed

---

### `void drv_hard_timer_inst_destroy(drv_hard_timer_inst_t** inst);`

**Function**: Destroy the hardware timer instance and release resources.

**parameter**:

- `inst`: pointer to timer instance pointer

---

### `int drv_hard_timer_get_info(drv_hard_timer_inst_t* inst, rt_hwtimer_info_t* info);`

**Function**: Get timer hardware characteristics information.

**parameter**:

- `inst`: timer instance pointer
- `info`: Structure pointer used to store timer information

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_set_mode(drv_hard_timer_inst_t* inst, rt_hwtimer_mode_t mode);`

**Function**: Set timer working mode. Must be set when the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `mode`: Working mode (single or periodic)

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_set_freq(drv_hard_timer_inst_t* inst, uint32_t freq);`

**Function**: Set the timer counting frequency. Must be set when the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `freq`: Counting frequency (Hz), needs to be within the range supported by the hardware

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_set_period(drv_hard_timer_inst_t* inst, uint32_t period_ms);`

**Function**: Set timer period. Must be set when the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `period_ms`: Timing period (milliseconds)

**Return Value**:

- `0`: Success
- `-1`: Failure (period out of range)

---

### `int drv_hard_timer_get_freq(drv_hard_timer_inst_t* inst, uint32_t* freq);`

**Function**: Get the current counting frequency of the timer.

**parameter**:

- `inst`: timer instance pointer
- `freq`: Pointer used to store frequency value (Hz)

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_start(drv_hard_timer_inst_t* inst);`

**Function**: Start timer.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_stop(drv_hard_timer_inst_t* inst);`

**Function**: Stop timer.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_register_irq(drv_hard_timer_inst_t* inst, timer_irq_callback callback, void* userargs);`

**Function**: Register timer interrupt callback function. Must be registered while the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `callback`: Interrupt callback function
- `userargs`: User parameters passed to the callback function

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_hard_timer_unregister_irq(drv_hard_timer_inst_t* inst);`

**Function**: Logout timer interrupt callback. Must log out while the timer is stopped.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### Helper function

#### `int drv_hard_timer_get_id(drv_hard_timer_inst_t* inst);`

**Function**: Get the timer number.

#### `int drv_hard_timer_is_started(drv_hard_timer_inst_t* inst);`

**Function**: Query whether the timer has been started.

---

## Software timer interface

### `int drv_soft_timer_create(drv_soft_timer_inst_t** inst);`

**Function**: Create software timer instance. The system supports only one software timer instance.

**parameter**:

- `inst`: used to store the created timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `void drv_soft_timer_destroy(drv_soft_timer_inst_t** inst);`

**Function**: Destroy software timer instance.

**parameter**:

- `inst`: pointer to timer instance pointer

---

### `int drv_soft_timer_set_mode(drv_soft_timer_inst_t* inst, rt_hwtimer_mode_t mode);`

**Function**: Set the software timer working mode. Must be set when the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `mode`: Working mode (single or periodic)

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_soft_timer_set_period(drv_soft_timer_inst_t* inst, int period_ms);`

**Function**: Set software timer period. Must be set when the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `period_ms`: Timing period (milliseconds)

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_soft_timer_start(drv_soft_timer_inst_t* inst);`

**Function**: Start software timer.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_soft_timer_stop(drv_soft_timer_inst_t* inst);`

**Function**: Stop software timer.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_soft_timer_register_irq(drv_soft_timer_inst_t* inst, timer_irq_callback callback, void* userargs);`

**Function**: Register software timer callback function. Must be registered while the timer is stopped.

**parameter**:

- `inst`: timer instance pointer
- `callback`: callback function
- `userargs`: User parameters passed to the callback function

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_soft_timer_unregister_irq(drv_soft_timer_inst_t* inst);`

**Function**: Logout software timer callback. Must log out while the timer is stopped.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `0`: Success
- `-1`: failed

---

### `int drv_soft_timer_is_started(drv_soft_timer_inst_t* inst);`

**Function**: Query whether the software timer has been started.

**parameter**:

- `inst`: timer instance pointer

**Return Value**:

- `1`: Started
- `0`: Not started

---

## Usage example

Please refer to `src/rtsmart/libs/testcases/rtsmart_hal/test_timer.c`