device/clock.h header reference
[Devices support library module]

The source code of this header can be browsed online.

Description  

This header provides functions designed to manage power and clock supplied to a device. This API is designed to be used from any device drivers where managing incoming clock and power signals is needed.

Physical clock and power signal connections points are represented in the software by source endpoint (struct dev_clock_src_ep_s) and sink endpoint (struct dev_clock_sink_ep_s) objects allocated in device private data by the drivers. The former are handled by clock and power provider devices while the latter are handled by clock and power consumer devices.

This API provides gating, throttling and frequency notification features only for the clock and power signals associated to the sink endpoints owned by the consumer device.

Endpoints setup in device drivers  

Endpoints are linked together dynamically when the device drivers which own the sink endpoint calls the dev_drv_clock_init on initialization. Endpoint links will match actual hardware connections as described using DEV_RES_CLK_SRC device resources attached to the clock consumer device.

Depending on the flags passed to the function, some clock and power signals may be enabled on initialization (see below). Moreover the device driver may learn the current frequency of the input clock signal.

In order to simplify drivers code, an empty struct dev_clock_src_ep_s structure along with dummy implementations of the dev_drv_clock_init and the dev_drv_clock_cleanup functions are also available when the CONFIG_DEVICE_CLOCK token is not defined.

See also dev_clock_sink_link and dev_clock_sink_unlink.

Enabling clock and power signals  

Depending on the hardware, some gates may only be enabled asynchronously. In this case, the device driver will have to handle delayed gate enabling events. This also applies when signals are enabled at link time (on driver initialization).

Once linked, the sink endpoint owned by the driver of the consumer device can be used in various ways:

  • When CONFIG_DEVICE_CLOCK_GATING is defined, clock and power signals gating can be requested by calling the dev_clock_sink_gate function. In the other case, gates can only be enabled at endpoint link time and are left enabled until the endpoint is unlinked.

  • When CONFIG_DEVICE_CLOCK_THROTTLE is defined, predefined clock throttling modes can be advised by calling the dev_clock_sink_throttle function.

  • Device drivers can not trigger frequency changes which would impact other devices. However, when the clock manager hardware provide a frequency scaler for the specific signal associated to the endpoint, the dev_clock_sink_scaler_set function may be used. This function is useful when the only prescaler available is on the clock manager side, for instance for the baud rate generator of an UART.

Source endpoints  

Unlike sink endpoints which may belong to any kind of device, source endpoints are owned by clock provider devices which implement the DRIVER_CLASS_CMU driver API defined in device/class/cmu.h.

Device clocking modes and sink endpoints  

Device drivers may define a set of clocking modes. Meaning and count of said modes is device-specific. With CONFIG_DEVICE_CLOCK_THROTTLE enabled, devices may dynamically change clocking mode for each sink endpoint. A mapping from device clocking mode to peer CMU device configuration IDs is defined in the device resources, see DEV_STATIC_RES_CLOCK_MODES.

This way, a device driver defines its behavioral modes, and platform designer defines the mapping between device modes and acceptable peer CMU device configuration. Each sink endpoint list compatible clocking configurations, CMU driver takes the one matching all the requirements.

Mode selection is done asynchronously and sink endpoints will be notified of clock changes through usual clock notification ways, see DEV_USE_CLOCK_SINK_FREQ_CHANGED and DEV_CLOCK_EP_FREQ_NOTIFY.

Members  

Types  

Functions  

Macros  

Members detail  

#define DEV_STATIC_RES_CLK_SRC(__src, __src_id, __sink_id)  

This macro is declared in device/clock.h source file, line 605.

This macro specifies a clock endpoint link.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK )

See also DEV_RES_CLK_SRC, device_res_add_clock_src and DEV_DECLARE_STATIC.

#define DEV_STATIC_RES_CLK_SRC(__src, __src_id, __sink_id)  

This macro is declared in device/clock.h source file, line 618.

Documentation from alternate declaration:

This macro specifies a clock endpoint link.

Preprocessor condition: not defined( CONFIG_DEVICE_CLOCK )

See also DEV_RES_CLK_SRC, device_res_add_clock_src and DEV_DECLARE_STATIC.

#define DEV_STATIC_RES_CLOCK_MODES(__sink_id, ...)  

This macro is declared in device/clock.h source file, line 639.

This macro specifies the mapping between device driver throttling clock mode ids and CMU device config ID.

This macro is flagged as experimental.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK_THROTTLE )

See also DEV_RES_CLK_MODES and DEV_DECLARE_STATIC.

#define DEV_STATIC_RES_CLOCK_MODES(__sink_id, ...)  

This macro is declared in device/clock.h source file, line 652.

Documentation from alternate declaration:

This macro specifies the mapping between device driver throttling clock mode ids and CMU device config ID.

Preprocessor condition: not defined( CONFIG_DEVICE_CLOCK_THROTTLE )

See also DEV_RES_CLK_MODES and DEV_DECLARE_STATIC.

#define _DEV_STATIC_RES_CLOCK_MODES_VA(a, b, c, d, e, f, g, h, ...)  

This macro is declared in device/clock.h source file, line 630.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK_THROTTLE )

#define _DEV_STATIC_RES_CMU_MODE(i, a)  

This macro is declared in device/clock.h source file, line 627.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK_THROTTLE )

#define __DEVICE_CLOCK_H__  

This macro is declared in device/clock.h source file, line 131.

enum dev_clock_ep_flags_e  

This enum is declared in device/clock.h source file, line 150.

This enum specifies clock endpoint flags.

See also struct dev_clock_src_ep_s and struct dev_clock_sink_ep_s.

IdentifierDescription
DEV_CLOCK_EP_POWERFor a source endpoint, this specifies if the power gate is currently enabled. For a sink endpoint, this specifies that power gate enabling is required.
DEV_CLOCK_EP_CLOCKFor a source endpoint, this specifies if the clock gate is currently enabled. For a sink endpoint, this specifies that clock gate enabling is required.
DEV_CLOCK_EP_POWER_CLOCKThis specifies both DEV_CLOCK_EP_POWER and DEV_CLOCK_EP_CLOCK
DEV_CLOCK_EP_ANYThis specifies both DEV_CLOCK_EP_POWER and DEV_CLOCK_EP_CLOCK as well as future gates.
DEV_CLOCK_EP_NONEThis specifies that no gate is enabled.
DEV_CLOCK_EP_GATING_SYNCFor a sink endpoint, this specifies that the gate enabling operations performed by the dev_clock_src_setup_t function of the clock provider can not be asynchronous. The clock provider driver must return an error if synchronous clock enabling is not supported when DEV_CLOCK_SRC_SETUP_LINK is invoked. This flag can not be changed once the endpoint has been linked.
DEV_CLOCK_EP_FREQ_NOTIFY For a sink endpoint, this specifies if the clock frequency change notification is required. This is ignored unless CONFIG_DEVICE_CLOCK_VARFREQ is defined.
DEV_CLOCK_EP_VARFREQThis enum_value specifies if the frequency of the endpoint can change. This is ignored unless CONFIG_DEVICE_CLOCK_VARFREQ is defined.

struct dev_clock_notify_s  

This struct is declared in device/clock.h source file, line 457.

This struct is used as argument to the dev_cmu_src_notify function and dev_use_t function when used with the DEV_USE_CLOCK_SINK_FREQ_CHANGED operation.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK_VARFREQ )

FieldDescription
struct dev_clock_sink_ep_s * sink;
struct dev_freq_s freq;

error_t dev_clock_notify_scaler_set(struct dev_clock_notify_s *notify, const struct dev_freq_ratio_s *scale)  

This function is declared in device/clock.h source file, line 473.

This function is an equivalent to dev_clock_sink_scaler_set when calling from dev_use_t function of a driver while in a #DEV_USE_CLOCK_SINK_FREQ_CHANGED.

This is available when CONFIG_DEVICE_CLOCK is defined.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK_VARFREQ )

struct dev_clock_sink_ep_s  

This struct is declared in device/clock.h source file, line 375.

Clock and power signal sink endpoint structure. Sink endpoints can be dynamically linked to a single clock source endpoint.

When belonging to a clock provider, a sink endpoint is a type of internal clock tree node which can be used as an external clock source.

When CONFIG_DEVICE_CLOCK is not defined, this structure contains no fields.

See also struct dev_clock_src_ep_s.

FieldDescription
struct device_s * dev;pointer to associated clock/power consumer
struct dev_clock_src_ep_s * src; pointer to linked source ep in clock provider device
struct dev_clock_sink_ep_s * next; pointer to sibling sink ep in device sharing the same clock signal
uint32_t mode_ids:CONFIG_DEVICE_CLOCK_MODE_COUNT*CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2; lookup table used to convert between device driver specific mode id to minimal CMU config mode ID. This is copied from DEV_RES_CLK_MODES resource matching the endpoint at initialization
uint32_t configid_min:CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2; current minimal CMU config mode requested by sink
enum dev_clock_ep_flags_e flags:8;endpoint flags

error_t dev_clock_sink_gate(struct dev_clock_sink_ep_s *sink, enum dev_clock_ep_flags_e gates)  

This function enables or disables clock and power signals associated with a sink endpoint. This is usually called from a clock/power consumer device driver.

This function returns 0 under the following conditions:

  • when disabling gates,

  • when some gates are already enabled,

  • when immediate enabling was possible. This is always the case when DEV_CLOCK_EP_GATING_SYNC is set.

When enabling a gate requires time and the DEV_CLOCK_EP_GATING_SYNC sink flag is not set, the function returns -EAGAIN and the dev_use_t function of the associated device driver will be called with the DEV_USE_CLOCK_SINK_GATE_DONE operation once all requested gates are enabled.

This is available when CONFIG_DEVICE_CLOCK_GATING is defined.

void dev_clock_sink_init(struct device_s *dev, struct dev_clock_sink_ep_s *sink, enum dev_clock_ep_flags_e flags)  

This function is declared in device/clock.h source file, line 499.

This function initializes a clock sink endpoint node.

This is available when CONFIG_DEVICE_CLOCK is defined.

error_t dev_clock_sink_link(struct dev_clock_sink_ep_s *sink, uint_fast8_t id, struct dev_freq_s *freq)  

This function links a clock sink endpoint to the appropriate source endpoint of a clock provider device as described in the device resources. This function is typically called from a device driver initialization function. The endpoint must have been initialized previously by calling dev_clock_sink_init.

If the sink endpoint has been initialized with some initially enabled gate flags, the clock provider of the source will be required to enable the gates. In this case, when enabling a gate requires time and the DEV_CLOCK_EP_GATING_SYNC sink flag is not set, the dev_use_t function of the associated device driver will be called with the DEV_USE_CLOCK_SINK_GATE_DONE operation once all requested gates are enabled.

When not NULL, the freq parameter is set according to the current clock tree multiplexers and scalers configuration, no matter if the clock gate is currently enabled. If the clock provider does not support reporting frequency, a DEV_RES_FREQ resource entry is searched. If none are found, an error is returned.

When CONFIG_DEVICE_CLOCK_VARFREQ is defined, and the DEV_CLOCK_EP_FREQ_NOTIFY flag is set, any subsequent clock frequency change will be reported to the device driver.

This is available when CONFIG_DEVICE_CLOCK is defined.

error_t dev_clock_sink_scaler_set(struct dev_clock_sink_ep_s *sink, const struct dev_freq_ratio_s *scale)  

This function attempts to apply an additional frequency scale factor to the clock signal of a source endpoint. This is only permitted when the source endpoint has no other linked sink.

This is available when CONFIG_DEVICE_CLOCK is defined.

error_t dev_clock_sink_throttle(struct dev_clock_sink_ep_s *sink, uint_fast8_t mode_id)  

This function changes the clock throttle mode of a sink endpoint. This is usually called from a clock/power consumer device driver.

The value of mode_id is driver specific; a DEV_RES_CLK_MODES resource entry for the sink endpoint must define minimal config ID for the attached CMU device for each device mode.

This *may* change some clock frequencies, depending on state of other sink endpoints linked to the same source as well as clock mode expressed in the device tree. Any frequency change will be reported as usual if notifications are enabled on the sink.

This is available when CONFIG_DEVICE_CLOCK_THROTTLE is defined.

void dev_clock_sink_unlink(struct dev_clock_sink_ep_s *sink)  

This function unlink a clock sink endpoint. Some gates on the source endpoints will be disabled as needed.

This is available when CONFIG_DEVICE_CLOCK is defined.

See also dev_drv_clock_cleanup.

void dev_clock_source_init(struct device_s *dev, struct dev_clock_src_ep_s *src, dev_clock_src_setup_t *setup)  

This function is declared in device/clock.h source file, line 489.

This function initializes a clock source endpoint node.

This is available when CONFIG_DEVICE_CLOCK is defined.

struct dev_clock_src_ep_s  

This struct is declared in device/clock.h source file, line 325.

Clock and power signals source endpoint object. It may be used to notify clock frequency changes to the consumer and request clock and power gating from the provider.

When CONFIG_DEVICE_CLOCK_SHARING is defined, source endpoints on a clock provider device can be dynamically linked to multiple sink endpoints on consumer devices. This way a provider can feed clock and/or power to multiple devices.

On the clock provider side, a source endpoint is a type of internal clock tree node which can be used as a connection point from the provider device to an external consumer device.

When CONFIG_DEVICE_CLOCK is not defined, this structure contains no fields.

See also struct dev_clock_sink_ep_s.

FieldDescription
struct device_s * dev;pointer to associated clock/power provider
struct dev_clock_sink_ep_s * sink_head; pointer to the first linked sink ep in the linked list
dev_clock_src_setup_t * f_setup; pointer to the endpoint configuration function of the clock signal provider device.
uint8_t notify_count; number of sink endpoints which currently expect to have a frequency change notification.
uint32_t configid_ctr:CONFIG_DEVICE_CLOCK_SHARING_MAX_LOG2*CONFIG_DEVICE_CMU_CONFIGID_COUNT; counter of sinks requesting a given minimal config ID, per config ID.
uint32_t configid_min:CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2; current minimal config ID requested by source endpoint
enum dev_clock_ep_flags_e flags:8;endpoint flags

struct dev_clock_src_throttle_s  

This struct is declared in device/clock.h source file, line 270.

FieldDescription
uint_fast8_t configid_old;CMU device config ID requested (at least) before the switch.
uint_fast8_t configid_new;CMU device config ID requested (at least) after the switch.

void dev_drv_clock_cleanup(struct device_s *dev, struct dev_clock_sink_ep_s *sink)  

This function is declared in device/clock.h source file, line 567.

This helper function may be called from the device driver initialization and cleanup functions. When CONFIG_DEVICE_CLOCK is defined, dev_clock_sink_unlink is called.

error_t dev_drv_clock_init(struct device_s *dev, struct dev_clock_sink_ep_s *sink, uint_fast8_t id, enum dev_clock_ep_flags_e flags, struct dev_freq_s *freq)  

This function is declared in device/clock.h source file, line 547.

This helper function may be called from the device driver initialization function. When CONFIG_DEVICE_CLOCK is defined It takes care of calling dev_clock_sink_init and dev_clock_sink_link. It forwards the return value of the latter.

When CONFIG_DEVICE_CLOCK is not defined and is not NULL, the frequency is searched in the device resources.

See also dev_drv_clock_cleanup.

error_t device_res_add_clock_src(struct device_s *dev, const char *src_name, uint_fast8_t src_id, uint_fast8_t sink_id)  

This function is declared in device/clock.h source file, line 599.

This function adds a clock endpoint link in the device resources.

This entry defines a link between the source endpoint with the node id src_id (relevant to clock provider device) and the sink endpoint with node id sink_id (relevant to the present device).

This is available when CONFIG_DEVICE_CLOCK and CONFIG_DEVICE_RESOURCE_ALLOC are both defined.

See also DEV_RES_CLK_SRC.

#define DEV_CLOCK_SRC_SETUP(n)  

This macro is declared in device/clock.h source file, line 293.

This macro is for internal use only.

See also dev_clock_src_setup_t.

enum dev_clock_src_setup_op_e  

This enum is declared in device/clock.h source file, line 192.

This enum specifies operations for the dev_clock_src_setup_t function.

This enum is for internal use only.

IdentifierDescription
DEV_CLOCK_SRC_SETUP_LINKThis operation is invoked from the dev_clock_sink_link function when a new sink endpoint is about to be linked. A pointer to the sink is passed as parameter. The linking is aborted if an error is returned.
When CONFIG_DEVICE_CLOCK_GATING is defined, this hook may be used by the clock provider in order to prepare its internal clock tree for gating the clock and power signals associated to the endpoint. It is implementation defined if some parts of the clock tree are gated at this point.
Some checks should also be performed. If synchronous gate enabling operations is not supported (see DEV_CLOCK_SRC_SETUP_GATES) and the DEV_CLOCK_EP_GATING_SYNC flag of the sink is set, then the -ENOTSUP error must be returned.
DEV_CLOCK_SRC_SETUP_UNLINKThis operation is used when a sink endpoint has been unlinked.
See also DEV_CLOCK_SRC_SETUP_LINK.
DEV_CLOCK_SRC_SETUP_NOTIFYThis operation is used when the frequency change notification flags of the source endpoint is set. This hook can be used by the clock provider if it needs to update internal data to support frequency change notification.
DEV_CLOCK_SRC_SETUP_NONOTIFYThis is similar to DEV_CLOCK_SRC_SETUP_NOTIFY
DEV_CLOCK_SRC_SETUP_SCALERThis operation sets the value of the frequency scaler. This is initiated on a linked sink by a call to dev_clock_sink_scaler_set. A default implementation should return -ENOTSUP.
DEV_CLOCK_SRC_SETUP_GATESThis operation requests a gates change on a clock source endpoint. This operation is invoked from the dev_clock_sink_link function as well as from the dev_clock_sink_gate function when CONFIG_DEVICE_CLOCK_GATING is defined.
Requested gates are passed as parameters. DEV_CLOCK_EP_POWER, DEV_CLOCK_EP_CLOCK and DEV_CLOCK_EP_NONE are possible values.
The clock provider driver must perform the gate changes then update the source endpoint flags by calling the dev_cmu_src_update_sync function.
If an enabling operation can be completed immediately, the function returns 0. When the requested change takes time, the function must return -EAGAIN, unless the DEV_CLOCK_EP_GATING_SYNC flag is used. When doing so, the dev_cmu_src_update_async function must later be called so that drivers associated to sink endpoints are notified that enabling is effective. Disabling operations can be silently delayed and do not require notification.
When CONFIG_DEVICE_CLOCK_GATING is defined, this operation may be used multiple times even before the gate changes are effective. In the other case this operation is only used when endpoints are linked and unlinked.
DEV_CLOCK_SRC_SETUP_THROTTLEThis operation sets the frequency throttle mode of the endpoint. This is initiated on a linked sink by a call to dev_clock_sink_throttle. Throttling may be done asynchronously.

typedef error_t (dev_clock_src_setup_t)(struct dev_clock_src_ep_s *src, enum dev_clock_src_setup_op_e op, const union dev_clock_src_setup_u *param)   

This typedef is declared in device/clock.h source file, line 305.

This typedef is the source endpoint operation function. This typedef is implemented by clock provider drivers and should not be called directly.

The device lock must be held when calling this function.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CLOCK_SRC_SETUP macro.

See also enum dev_clock_src_setup_op_e.

union dev_clock_src_setup_u  

This union is declared in device/clock.h source file, line 280.

This union contains parameters passed to the dev_clock_src_setup_t function.

This union is for internal use only.

Valid XHTML 1.0 StrictGenerated by diaxen on Wed Oct 17 21:18:38 2018 using MkDoc