Difference between revisions of "TIM Linux driver"

[quality revision] [quality revision]
m
(Merge articles)
 
Warning.png This section has not been yet updated/tested for/with the STM32 MPU ecosystem-v3 flow.
Information provided in this section may not be not fully applicable for v3 and you may need to proceed to some adaptations.
We apologize for this inconvenient.

1 Article purpose[edit]

This article introduces the TIM Linux® driver for the TIM internal peripheral[1]:

  • Which TIM features are supported by the driver
  • How to configure, use and debug the driver
  • What is the driver structure, and where the source code can be found.


2 Short description[edit]

The TIM[1] Linux driver (kernel space) is based on the PWM, and IIO and counter frameworks. It provides several functionalities:

MFD driver:

  • handles registers, clock and DMA[2] resources
  • detects the TIM counter resolution, e.g. 16 or 32 bits.

PWM driver:

  • detects the number of TIM channels.
  • handles PWM output channels.
  • handles PWM capture channels (input). Note that the PWM capture relies on DMA, which is handled by the MFD core.

IIO driver:

  • handles hardware trigger sources (synchronously with PWM) for other internal peripherals such as ADC[3], DAC[4], DFSDM[5].

counter driver:

  • handles the quadrature encoder interface[6].

3 Configuration[edit]

3.1 Kernel configuration[edit]

Activate the TIM[1] Linux driver in the kernel configuration using the Linux Menuconfig tool: Menuconfig or how to configure kernel.

Enable the following configurations (and their dependencies):

  • CONFIG_MFD_STM32_TIMERS
  • CONFIG_PWM_STM32
  • CONFIG_IIO_STM32_TIMER_TRIGGER
  • CONFIG_STM32_TIMER_CNT
Device Drivers  --->
  -> Multifunction device drivers  --->
     <*> Support for STM32 Timers
  -> Pulse-width modulation (PWM) support  --->
     <*> STMicroelectronics STM32 PWM
  -> Industrial I/O support  --->
     -> Triggers - standalone  --->
        <*> STM32 timer trigger
  -> Counter support  --->
     <*> STM32 Timer encoder counter driver

3.2 Device tree[edit]

Refer to the TIM device tree configuration article when configuring the TIM Linux kernel driver.

4 How to use[edit]

How to use PWM with sysfs interface

How to set up a TIM or LPTIM trigger using the sysfs interface

How to use the quadrature encoder with the sysfs interface

5 How to trace and debug[edit]

The TIM[1] Linux driver can access the timer registers through REGMAP.

It comes with debugfs[7] entries, which allow dumping registers:

$ cd /sys/kernel/debug/regmap
$ ls
40004000.timer  44000000.timer

$ cd 44000000.timer
$ cat registers
000: 00000081
004: 00000000
008: 00000000
00c: 00000000
...

It also comes with tracepoints[8]:

$ cd /sys/kernel/debug/tracing
$ cat available_events | grep regmap
...
regmap:regmap_reg_read
regmap:regmap_reg_write

6 Source code location[edit]

The TIM Linux driver source code is composed of:

7 References[edit]


=={{EcosystemFlow/Warning| flow=Current}}
== Article purpose ==
This article introduces the TIM Linux<sup>&reg;</sup> driver for the TIM internal peripheral<ref name="TIM internal peripheral">[[TIM internal peripheral]]</ref>:
* Which TIM features are supported by the driver
* How to configure, use and debug the driver 
* What is the driver structure, and where the source code can be found.
{{ReviewsComments|-- [[User:Nathalie Sangouard|Nathalie Sangouard]] ([[User talk:Nathalie Sangouard|talk]]) 16:48, 13 November 2020 (CET)<br />Article to be updated to be compliant with ecosystem v2.0.0 (BZ 80500)}}
== Short description ==
The ''TIM''<ref name="TIM internal peripheral"/> Linux driver (kernel space) is based on the [[PWM overview|PWM]],  and [[IIO overview|IIO]] and <span style="color: {{STLightBlue}};">counter</span> frameworks. It provides several functionalities:

'''MFD driver''':
* handles registers, clock and DMA<ref name="DMA internal peripheral">[[DMA_internal_peripheral]]</ref> resources
* detects the TIM counter resolution, e.g. 16 or 32 bits.
'''PWM driver''':
* detects the number of TIM channels.
* handles '''PWM output''' channels.
* handles '''PWM capture''' channels (input). Note that the PWM capture relies on DMA, which is handled by the MFD core.
'''IIO driver''':
* handles hardware '''trigger sources''' (synchronously with PWM) for other internal peripherals such as ADC<ref name="adc_internal">[[ADC internal peripheral]]</ref>, DAC<ref name="dac_internal">[[DAC internal peripheral]]</ref>, DFSDM<ref name="dfsdm_internal">[[DFSDM internal peripheral]]</ref>.'''counter driver''':* handles the '''quadrature encoder''' interface<ref>[https://en.wikipedia.org/wiki/Rotary_encoder#Incremental_encoder Incremental encoder] Incremental encoder overview</ref>.

== Configuration ==
=== Kernel configuration ===
Activate the TIM<ref name="TIM internal peripheral"/> Linux driver in the kernel configuration using the Linux Menuconfig tool: [[Menuconfig or how to configure kernel]].

Enable the following configurations (and their dependencies):
* CONFIG_MFD_STM32_TIMERS
* CONFIG_PWM_STM32
* CONFIG_IIO_STM32_TIMER_TRIGGER* CONFIG_STM32_TIMER_CNT

Device Drivers  --->
   -> Multifunction device drivers  ---><*> Support for STM32 Timers
   -> Pulse-width modulation (PWM) support  ---><*> STMicroelectronics STM32 PWM
   -> Industrial I/O support  --->
      -> Triggers - standalone  ---><*> STM32 timer trigger
  -> Counter support  ---><*> STM32 Timer encoder counter driver
=== Device tree ===
Refer to the [[TIM device tree configuration]] article when configuring the TIM Linux kernel driver.

== How to use ==
[[PWM_overview#How_to_use_PWM_with_sysfs_interface|How to use PWM with sysfs interface]]

[[How to use the IIO user space interface#How to set up a TIM or LPTIM trigger using the sysfs interface|How to set up a TIM or LPTIM trigger using the sysfs interface]]

[[How to use the IIO user space interface#How to use the quadrature encoder with the sysfs interface|How to use the quadrature encoder with the sysfs interface]]

== How to trace and debug ==
The ''TIM''<ref name="TIM internal peripheral"/> Linux driver can access the timer registers through REGMAP.

It comes with debugfs<ref name="debugfs">[[Debugfs]]</ref> entries, which allow dumping registers:
 $ cd /sys/kernel/debug/regmap
 $ ls
 40004000.timer  44000000.timer

 $ cd 44000000.timer
 $ cat registers
 000: 00000081
 004: 00000000
 008: 00000000
 00c: 00000000
 ...

It also comes with tracepoints<ref name="ftrace">[[Ftrace]]</ref>:
 $ cd /sys/kernel/debug/tracing
 $ cat available_events | grep regmap
 ...
 regmap:regmap_reg_read
 regmap:regmap_reg_write

== Source code location ==
The TIM Linux driver source code is composed of:
* {{CodeSource | Linux kernel | drivers/mfd/stm32-timers.c | stm32-timers.c MFD driver}} to handle common resources: registers, clock, dmas.
* {{CodeSource | Linux kernel | drivers/pwm/pwm-stm32.c | pwm-stm32.c PWM driver}} to handle PWM channel(s).
* {{CodeSource | Linux kernel | drivers/iio/trigger/stm32-timer-trigger.c | stm32-timer-trigger.c IIO driver}} to handle trigger source for other internal peripherals.
* {{CodeSource | Linux kernel | drivers/counter/stm32-timer-cnt.c | stm32-timer-cnt.c counter driver}} to handle the  and quadrature encoder interface.
* {{CodeSource | Linux kernel | include/linux/mfd/stm32-timers.h}} and {{CodeSource | Linux kernel | include/linux/iio/timer/stm32-timer-trigger.h}} header files

==References==<references />

<noinclude>

[[Category:Timers]]
[[Category:IIO]]
{{PublicationRequestId | 9233 | 2018-10-15 | AnneJ}}
{{ArticleBasedOnModel | Linux driver article model}}</noinclude>
Line 1: Line 1:
{{EcosystemFlow/Warning| flow=Current}}
 
 
== Article purpose ==
 
== Article purpose ==
 
This article introduces the TIM Linux<sup>&reg;</sup> driver for the TIM internal peripheral<ref name="TIM internal peripheral">[[TIM internal peripheral]]</ref>:
 
This article introduces the TIM Linux<sup>&reg;</sup> driver for the TIM internal peripheral<ref name="TIM internal peripheral">[[TIM internal peripheral]]</ref>:
Line 5: Line 4:
 
* How to configure, use and debug the driver  
 
* How to configure, use and debug the driver  
 
* What is the driver structure, and where the source code can be found.
 
* What is the driver structure, and where the source code can be found.
 
{{ReviewsComments|-- [[User:Nathalie Sangouard|Nathalie Sangouard]] ([[User talk:Nathalie Sangouard|talk]]) 16:48, 13 November 2020 (CET)<br />Article to be updated to be compliant with ecosystem v2.0.0 (BZ 80500)}}
 
   
 
== Short description ==
 
== Short description ==
The ''TIM''<ref name="TIM internal peripheral"/> Linux driver (kernel space) is based on the [[PWM overview|PWM]] and [[IIO overview|IIO]] frameworks. It provides several functionalities:
+
The ''TIM''<ref name="TIM internal peripheral"/> Linux driver (kernel space) is based on the [[PWM overview|PWM]], [[IIO overview|IIO]] and <span style="color: {{STLightBlue}};">counter</span> frameworks. It provides several functionalities:
   
 
'''MFD driver''':
 
'''MFD driver''':
Line 20: Line 17:
 
'''IIO driver''':
 
'''IIO driver''':
 
* handles hardware '''trigger sources''' (synchronously with PWM) for other internal peripherals such as ADC<ref name="adc_internal">[[ADC internal peripheral]]</ref>, DAC<ref name="dac_internal">[[DAC internal peripheral]]</ref>, DFSDM<ref name="dfsdm_internal">[[DFSDM internal peripheral]]</ref>.
 
* handles hardware '''trigger sources''' (synchronously with PWM) for other internal peripherals such as ADC<ref name="adc_internal">[[ADC internal peripheral]]</ref>, DAC<ref name="dac_internal">[[DAC internal peripheral]]</ref>, DFSDM<ref name="dfsdm_internal">[[DFSDM internal peripheral]]</ref>.
  +
'''counter driver''':
 
* handles the '''quadrature encoder''' interface<ref>[https://en.wikipedia.org/wiki/Rotary_encoder#Incremental_encoder Incremental encoder] Incremental encoder overview</ref>.
 
* handles the '''quadrature encoder''' interface<ref>[https://en.wikipedia.org/wiki/Rotary_encoder#Incremental_encoder Incremental encoder] Incremental encoder overview</ref>.
   
Line 30: Line 28:
 
* CONFIG_PWM_STM32
 
* CONFIG_PWM_STM32
 
* CONFIG_IIO_STM32_TIMER_TRIGGER
 
* CONFIG_IIO_STM32_TIMER_TRIGGER
  +
* CONFIG_STM32_TIMER_CNT
   
 
  Device Drivers  --->
 
  Device Drivers  --->
Line 39: Line 38:
 
       -> Triggers - standalone  --->
 
       -> Triggers - standalone  --->
 
         <*> STM32 timer trigger
 
         <*> STM32 timer trigger
  +
  -> Counter support  --->
  +
      <*> STM32 Timer encoder counter driver
   
 
=== Device tree ===
 
=== Device tree ===
Line 77: Line 78:
 
* {{CodeSource | Linux kernel | drivers/mfd/stm32-timers.c | stm32-timers.c MFD driver}} to handle common resources: registers, clock, dmas.
 
* {{CodeSource | Linux kernel | drivers/mfd/stm32-timers.c | stm32-timers.c MFD driver}} to handle common resources: registers, clock, dmas.
 
* {{CodeSource | Linux kernel | drivers/pwm/pwm-stm32.c | pwm-stm32.c PWM driver}} to handle PWM channel(s).
 
* {{CodeSource | Linux kernel | drivers/pwm/pwm-stm32.c | pwm-stm32.c PWM driver}} to handle PWM channel(s).
* {{CodeSource | Linux kernel | drivers/iio/trigger/stm32-timer-trigger.c | stm32-timer-trigger.c IIO driver}} to handle trigger source for other internal peripherals and quadrature encoder interface.
+
* {{CodeSource | Linux kernel | drivers/iio/trigger/stm32-timer-trigger.c | stm32-timer-trigger.c IIO driver}} to handle trigger source for other internal peripherals.
  +
* {{CodeSource | Linux kernel | drivers/counter/stm32-timer-cnt.c | stm32-timer-cnt.c counter driver}} to handle the quadrature encoder interface.
 
* {{CodeSource | Linux kernel | include/linux/mfd/stm32-timers.h}} and {{CodeSource | Linux kernel | include/linux/iio/timer/stm32-timer-trigger.h}} header files
 
* {{CodeSource | Linux kernel | include/linux/mfd/stm32-timers.h}} and {{CodeSource | Linux kernel | include/linux/iio/timer/stm32-timer-trigger.h}} header files