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

[cols="<3,<3,<4"]
[frame="topbot",grid="none"]
|=======================
| Hardware source files:  | neorv32_gptmr.vhd |
| Software driver files:  | neorv32_gptmr.c |
|                         | neorv32_gptmr.h |
| Top entity ports:       | none |
| Configuration generics: | `IO_GPTMR_EN` | implement general purpose timer when `true`
| CPU interrupts:         | fast IRQ channel 12 | timer interrupt (see <<_processor_interrupts>>)
| Access restrictions:  2+| privileged access only, non-32-bit write accesses are ignored
|=======================


**Overview**

The general purpose timer module implements a simple yet universal 32-bit timer. It is implemented if the processor's
`IO_GPTMR_EN` top generic is set `true`. The timer provides a pre-scaled counter register that can trigger an interrupt
when reaching a programmable threshold value.

The GPTMR provides three interface registers : a control register (`CTRL`), a 32-bit counter register (`COUNT`) and a
32-bit threshold register (`THRES`). The timer is globally enabled by setting the `GPTMR_CTRL_EN` bit in the module's
control register. When the timer is enable the `COUNT` register will start incrementing from zero at a programmable
rate that scales the main processor clock. this pre-scaler 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
|=======================

Whenever the counter register `COUNT` equals the programmable threshold value `THRES` the module's interrupt
signal becomes pending (indicated by `GPTMR_CTRL_IRQ_PND` being set). Note that a pending interrupt has to be
cleared manually by writing a `1` to `GPTMR_CTRL_IRQ_CLR`.

The control register's `GPTMR_CTRL_MODE` bit defines what will happen when `COUNT == THRES`.

* `GPTMR_CTRL_MODE = 0`: **single-shot mode** - the `COUNT` register will stop incrementing
* `GPTMR_CTRL_MODE = 1`: **continuous mode** - the `COUNT` register is automatically reset and restarts incrementing from zero

.Resetting the Counter
[NOTE]
Disabling the GPTMR will also clear the `COUNT` register.


**Interrupt**

The GPTRM provides a single interrupt line is triggered whenever `COUNT` equals `THRES`. Once triggered, the interrupt will
stay pending until explicitly cleared by writing a 1 to `GPTMR_CTRL_IRQ_CLR`.


**Register Map**

.GPTMR register map (`struct NEORV32_GPTMR`)
[cols="<4,<2,<4,^1,<7"]
[options="header",grid="all"]
|=======================
| Address | Name [C] | Bit(s), Name [C] | R/W | Function
.6+<| `0xfffff100` .6+<| `CTRL` <|`0`   `GPTMR_CTRL_EN`                       ^| r/w <| Timer enable flag
                                <|`3:1` `GPTMR_CTRL_PRSC2 : GPTMR_CTRL_PRSC0` ^| r/w <| 3-bit clock prescaler select
                                <|`4`   `GPTMR_CTRL_MODE`                     ^| r/w <| Operation mode (0=single-shot, 1=continuous)
                                <|`29:5` -                                    ^| r/- <| _reserved_, read as zero
                                <|`30`  `GPTMR_CTRL_IRQ_CLR`                  ^| -/w <| Write `1` to clear timer-match interrupt; auto-clears
                                <|`31`  `GPTMR_CTRL_IRQ_PND`                  ^| r/- <| Timer-match interrupt pending
| `0xfffff104` | `THRES`   |`31:0` | r/w | Threshold value register
| `0xfffff108` | `COUNT`   |`31:0` | r/- | Counter register
|=======================
