Subversion Repositories neorv32

<<<
:sectnums:
==== General Purpose Timer (GPTMR)

[cols="<3,<3,<4"]
[frame="topbot",grid="none"]
|=======================
| Hardware source file(s): | neorv32_gptmr.vhd | 
| Software driver file(s): | neorv32_gptmr.c |
|                          | neorv32_gptmr.h |
| Top entity port:         | none | 
| Configuration generics:  | _IO_GPTMR_EN_ | implement timer when _true_
| CPU interrupts:          | fast IRQ channel 12 | transmission done interrupt (see <<_processor_interrupts>>)
|=======================


**Theory of Operation**

The general purpose timer module provides a simple yet universal 32-bit timer. The timer is implemented if
_IO_GPTMR_EN_ top generic is set _true_. It provides a 32-bit counter register (`COUNT`) and a 32-bit threshold
register (`THRES`). An interrupt is generated whenever the value of the counter registers matches the one from
threshold register.

The timer is enabled by setting the _GPTMR_CTRL_EN_ bit in the device's control register `CTRL`. The `COUNT`
register will start incrementing at a programmable rate, which scales the main processor clock. The
pre-scaler value is configured via the three _GPTMR_CTRL_PRSCx_ control register bits:

.GPTMR prescaler configuration
[cols="<4,^1,^1,^1,^1,^1,^1,^1,^1"]
[options="header",grid="rows"]
|=======================
| **`GPTMR_CTRL_PRSCx`**      | `0b000` | `0b001` | `0b010` | `0b011` | `0b100` | `0b101` | `0b110` | `0b111`
| Resulting `clock_prescaler` |       2 |       4 |       8 |      64 |     128 |    1024 |    2048 |    4096
|=======================

The timer provides two operation modes that are configured by the _GPTMR_CTRL_MODE_ control register bit:
if _GPTMR_CTRL_MODE_ is cleared (`0`) the timer operates in _single-shot mode_. As soon as `COUNT` matches
`THRES` an interrupt request is generated and the timer stops operation (i.e. it stops incrementing). If
_GPTMR_CTRL_MODE_ is set (`1`) the timer operates in _continuous mode_. When `COUNT` matches `THRES` an interrupt
request is generated and `COUNT` is automatically reset to all-zero before continuing to increment.

[NOTE]
Disabling the timer will not clear the `COUNT` register. However, it can be manually reset at any time by
writing zero to it.


**Timer Interrupt**

The timer interrupt gets pending when the timer is enabled and `COUNT` matches `THRES`. The interrupt
request is indicated via the _GPTMR_CTRL_ALARM_ control register bit. This bit as well as the actual
interrupt keeps pending until the bit is explicitly cleared by application software or if the
timer is disabled.


.GPTMR register map (`struct NEORV32_GPTMR`)
[cols="<2,<2,<4,^1,<7"]
[options="header",grid="all"]
|=======================
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
.6+<| `0xffffff60` .6+<| `NEORV32_GPTMR.CTRL` <|`0` _GPTMR_CTRL_EN_    ^| r/w <| Timer enable flag
                                              <|`1` _GPTMR_CTRL_PRSC0_ ^| r/w .3+| 3-bit clock prescaler select
                                              <|`2` _GPTMR_CTRL_PRSC1_ ^| r/w 
                                              <|`3` _GPTMR_CTRL_PRSC2_ ^| r/w 
                                              <|`4` _GPTMR_CTRL_MODE_  ^| r/w <| Counter mode: `0`=single-shot, `1`=continuous
                                              <|`5` _GPTMR_CTRL_ALARM_ ^| r/c <| Pending interrupt/alarm, cleared by setting bit to zero
| `0xffffff64` | `NEORV32_GPTMR.THRES` |`31:0` | r/w | Threshold value register
| `0xffffff68` | `NEORV32_GPTMR.COUNT` |`31:0` | r/w | Counter register
|=======================