====== Introduction ======

The clock management module (acronym: clk) deals with clock signals across a microcontroller.

====== Basic assumptions ======

It is understood that clock architecture is very different in various microcontrollers. It is not expected that the clock module will provide means for the application or portable components to manage clocks in a portable way. Rather the clock module is a tool for port development, unifying how clocks are dealt with in ports.

The clk module should provide means to:
  * set frequency of different clocks inside microcontroller (CPU clock, peripheral clocks etc.)
  * get actual frequency of these clocks (read it from hardware)
  * provide means to describe fixed clock sources (like XTALs, clock generators etc.)

====== Architecture ======

The central element of the solution is the clock signal itself. 
The main property of a clock signal is it's frequency, however it is noticed this frequency:
  * may be fixed (constant) which is the case in ex. for XTAL oscillators
  * may be derrived from another clock signal (source clock) through a prescaller or multiplier or both (PLLs)

====== Class model ======

The clk class model describes the clock interface:

<uml>
class Clock {
  virtual uint32_t getFrequency() = 0;
  virtual bool setFrequency(uint32_t frequency) = 0;
  virtual bool setClockSource(Clock& clockSource) = 0;
  virtual Clock& getClockSource() = 0;
}
note right: This is the basic abstract interface describing a clock

Clock <|-- FixedClock

class FixedClock {
  #const uint32_t frequency;
}
note right: This is the ready-to-use utility class for describing fixed clocks.

</uml>

The clk class model also provides the ClockedPeripheral class that can be used as a basis for peripheral classes to unify how peripherals use the clock.

<uml>
class ClockedPeripheral {
  #Clock& clock;
  ClockedPeripheral(Clock& clockSource)
}
</uml>

Here's how we can use it:

<uml>
class SerialPort
class ClockedPeripheral 
namespace stm32 {
class Usart
.SerialPort <|-- Usart
.ClockedPeripheral <|-- Usart
}
</uml>

====== Examples ======

See [[example on implementing clk module in STM32F1]]

====== Known limitations ======

  * The clk module does not describe controlled oscillators (VCOs etc.).
  * The ClockedPeripheral class assumes that each peripheral has only one clock.

====== Known issues ====== 

Should the Clock class have enable() and disable() methods ?

Rationale: the on/off functionality is not available in all clocks

