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

The source code of this header can be browsed online.

This header defines the API implemented by clock management units drivers along with some related function provided by the device library. A clock management driver is responsible for dealing with other device driver clock and power management requests as well as applying the user requested clock configuration.

The driver API provides functions to update the internal clock tree configuration. These functions are implemented by clock management driver and should not be called directly; the library functions should be used instead so that the user only has access to a viable set of clock configurations.

A clock management unit device is a black box which contains a clock tree made of internal nodes of four different types: oscillators, mux, sink endpoints and source endpoints. Each node in the internal tree is assigned a compile time numerical id.

The driver provides functions to specify and apply a configuration for some of the internal nodes of the tree. The following list describes the role of the various node types:

• Oscillator nodes are used to represent a clock source internal to the device. They usually represent a fixed frequency crystal directly managed by the device or an internal oscillator with an optionally variable frequency. The API allow specifying the frequency and accuracy of the oscillator. An oscillator node do not have a parent in the tree.

• Mux nodes are used to choose between multiple parent clock nodes and optionally scale the frequency of the selected parent. The set of usable parent nodes is usually restricted and may even be of size 1. Likewise the possible values for the scale factor is usually restricted by the hardware. They are used to represent clock multiplexer, divider and PLLs in the hardware tree.

• Sink endpoint nodes have an associated struct dev_clock_sink_ep_s object. They represent an input connected to the output of an other clock management unit. They do not have a parent in the tree and do not need configuration.

• Source endpoint nodes have an associated struct dev_clock_src_ep_s object. They represent a clock output which can be connected to the input of consumer device. Depending on clock tree, they may need configuration (selectable parent, ratio, etc.). They may also raise management request operations through the dev_clock_src_setup_t function.

Links between endpoint may convey a clock signal, a power supply or both. The driver of the clock management unit must be able to handle clock management operations on its source endpoints needed by driver of linked consumer devices. This includes endpoint linking operations, gating operations and frequency change notifications. This operations are defined in device/clock.h.

See also DRIVER_CLASS_CMU.

Some sets of valid node configuration entries may be defined by attaching DEV_RES_CMU_MUX and DEV_RES_CMU_OSC resources to a clock management device. Each entry may be associated to one or more configuration id which can be activated.

Power/Clock configuration IDs are defined with an order. When multiple configurations are possible, driver will select the one with the lowest ID.

The configuration 0 is loaded from the cmu driver initialization be calling the dev_cmu_init function.

On a running platform, CMU device configuration mode is a merge of:

• Application-required configuration ID,

• Connected sink endpoint clocking modes (when CONFIG_DEVICE_CLOCK_THROTTLE is defined).

The user may change the set of active node configuration entries at any time by calling dev_cmu_app_configid_set_t.

Because of configuration ID ordering, platform designer should order its configuration IDs from lowest power consumption to highest.

This macro is declared in device/class/cmu.h source file, line 127.

This macro is declared in device/class/cmu.h source file, line 287.

See also dev_cmu_app_configid_set_t.

This macro is declared in device/class/cmu.h source file, line 194.

See also dev_cmu_commit_t.

This macro is declared in device/class/cmu.h source file, line 151.

See also dev_cmu_config_mux_t.

This macro is declared in device/class/cmu.h source file, line 174.

See also dev_cmu_config_osc_t.

This macro is declared in device/class/cmu.h source file, line 265.

See also dev_cmu_node_info_t.

This macro is declared in device/class/cmu.h source file, line 218.

See also dev_cmu_rollback_t.

This macro is declared in device/class/cmu.h source file, line 474.

This macro specifies a clock mux resource entry in a static device resources table declaration.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK )

See also DEV_RES_CMU_MUX, device_res_add_cmu_mux and DEV_DECLARE_STATIC.

This macro is declared in device/class/cmu.h source file, line 523.

Documentation from alternate declaration:

This macro specifies a clock mux resource entry in a static device resources table declaration.

Preprocessor condition: not defined( CONFIG_DEVICE_CLOCK )

See also DEV_RES_CMU_MUX, device_res_add_cmu_mux and DEV_DECLARE_STATIC.

This macro is declared in device/class/cmu.h source file, line 492.

This macro specifies a clock source oscillator resource entry in a static device resources table declaration. A default value is used for frequency accuracy.

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK )

See also DEV_RES_CMU_OSC, device_res_add_cmu_osc and DEV_DECLARE_STATIC.

This macro is declared in device/class/cmu.h source file, line 530.

Documentation from alternate declaration:

This macro specifies a clock source oscillator resource entry in a static device resources table declaration. A default value is used for frequency accuracy.

Preprocessor condition: not defined( CONFIG_DEVICE_CLOCK )

See also DEV_RES_CMU_OSC, device_res_add_cmu_osc and DEV_DECLARE_STATIC.

This macro is declared in device/class/cmu.h source file, line 506.

This macro is similar to DEV_STATIC_RES_CMU_OSC

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK )

This macro is declared in device/class/cmu.h source file, line 536.

Documentation from alternate declaration:

This macro is similar to DEV_STATIC_RES_CMU_OSC

Preprocessor condition: not defined( CONFIG_DEVICE_CLOCK )

This macro is declared in device/class/cmu.h source file, line 315.

this macro is a helper to declare a struct device_cmu_config_ops_s structure.

This macro is declared in device/class/cmu.h source file, line 328.

This macro is declared in device/class/cmu.h source file, line 118.

This function is declared in device/class/cmu.h source file, line 409.

This function tells whether a source endpoint currently requests clock.

This is available when CONFIG_DEVICE_CLOCK is defined.

This function is declared in device/class/cmu.h source file, line 394.

This function tells whether a source endpoint currently requests power.

This is available when CONFIG_DEVICE_CLOCK is defined.

This typedef is declared in device/class/cmu.h source file, line 133.

Index of the configuration associated with a set of DEV_RES_CMU_MUX and DEV_RES_CMU_OSC resources in the device tree.

This typedef is declared in device/class/cmu.h source file, line 137.

Mask of configuration ids

Alternate declarations with same identifier: [1], [2], [3].

Preprocessor condition: CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2 == 6

See also dev_cmu_config_id_t.

This typedef is declared in device/class/cmu.h source file, line 139.

Documentation from alternate declaration:

Mask of configuration ids

Alternate declarations with same identifier: [1], [2], [3].

Preprocessor condition: not ( CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2 == 6 ) and ( CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2 == 5 )

See also dev_cmu_config_id_t.

This typedef is declared in device/class/cmu.h source file, line 141.

Documentation from alternate declaration:

Mask of configuration ids

Alternate declarations with same identifier: [1], [2], [3].

Preprocessor condition: not ( CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2 == 6 ) and not ( CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2 == 5 ) and ( CONFIG_DEVICE_CMU_CONFIGID_COUNT_LOG2 < 5 )

See also dev_cmu_config_id_t.

This function is declared in device/class/cmu.h source file, line 343.

This function must be used to perform initial clock configuration.

This function is similar to dev_cmu_config but is designed to be called from the initialization function of cmu device drivers. It selects resource associated to config id 0.

This is available when CONFIG_DEVICE_CLOCK is defined.

This typedef is declared in device/class/cmu.h source file, line 149.

Index of the clock tree node inside a device. Nodes are numbered as follow: source eps nodes, sink eps nodes, internal nodes, oscillator nodes.

This enum is declared in device/class/cmu.h source file, line 233.

This enum specifies node information to retrieve for the dev_cmu_node_info_t function.

This function is declared in device/class/cmu.h source file, line 425.

This function is a wrapper for the dev_cmu_node_info_t function which takes care of locking the device.

This is available when CONFIG_DEVICE_CLOCK is defined.

This struct is declared in device/class/cmu.h source file, line 248.

This struct stores node information retrieved by the dev_cmu_node_info_t function.

This function is declared in device/class/cmu.h source file, line 387.

This function function is called by the clock provider device driver when the requested gates has been enabled asynchronously.

This function will propagate the change to all connected sink endpoints by calling the dev_use_t function of the associated device driver with the DEV_USE_CLOCK_SINK_GATE_DONE operation.

This is available when CONFIG_DEVICE_CLOCK_GATING is defined.

This function is declared in device/class/cmu.h source file, line 376.

This helper updates the gates state of a source endpoint when enabled synchronously from endpoint setup handler. This function is called by the clock provider device driver when the state of the requested gates has been updated.

This is available when CONFIG_DEVICE_CLOCK is defined.

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 19 in device/class/cmu.h source file, line 327.

This struct is the device accessor object type for the cmu device class. This accessor must be initialized by calling the device_get_accessor function.

See also DRIVER_CLASS_CMU, struct device_accessor_s and Device accessor.

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 40 in device/class/cmu.h source file, line 327.

This function casts a cmu device accessor to a generic device accessor

This function is declared in DRIVER_CLASS_TYPES function like macro expansion, line 33 in device/class/cmu.h source file, line 327.

This function casts a generic device accessor to a cmu device accessor

This function is declared in device/class/cmu.h source file, line 467.

This function adds an internal clock mux entry in the device resource list.

This entry specifies the parent clock signal used to generate the clock for an other clock signal node. This entry belongs to a configuration set that is defined by config_mask. All clock related resources associated with a given configuration id can be applied by calling dev_cmu_config.

The parent clock can be scaled up or down by a fraction defined by fnum and fdenom parameters.

Depending on the clock device driver and clock signal, a default mux may be used if no resource entry is present for a given node.

note: the validity of the mux and scaling factor is the responsibility of the programmer. There may be no internal validity check on clocking configurations.

This is available when CONFIG_DEVICE_CLOCK and CONFIG_DEVICE_RESOURCE_ALLOC are both defined.

See also DEV_RES_CMU_MUX.

This function is declared in device/class/cmu.h source file, line 579.

This function adds a clock frequency resource entry to a device.

This entry specifies a frequency value for an internal oscillator node. This entry belongs to a configuration set that is defined by config_mask. All clock related resources associated with a given configuration id can be applied by calling dev_cmu_config.

This may be used to specify the frequency of an external clock source or to configure the frequency of an internal oscillator. In the later case, the internal oscillator may have a default frequency value and the resource entry is not mandatory.

This is available when CONFIG_DEVICE_CLOCK and CONFIG_DEVICE_RESOURCE_ALLOC are both defined.

See also DEV_RES_CMU_OSC.

This struct is declared in DRIVER_CLASS_TYPES function like macro expansion, line 5 in device/class/cmu.h source file, line 327.

This struct is the driver API descriptor for the cmu device class.

See also DRIVER_CLASS_CMU and struct driver_class_s.

This typedef is declared in device/class/cmu.h source file, line 298.

This typedef informs the device of configuration id required by the application code. Driver should merge it with requirements from source endpoints, if CONFIG_DEVICE_CLOCK_THROTTLE is defined.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CMU_APP_CONFIGID_SET macro.

See also dev_cmu_app_configid_set.

This typedef is declared in device/class/cmu.h source file, line 214.

This typedef starts the configuration of the clocks based on parameters passed to previous calls to the dev_cmu_config_mux_t and dev_cmu_config_osc_t functions.

The driver may further delay the configuration of some clock signals and make it effective only when appropriate. Depending on the hardware, this may happen immediately or may be delayed until the clock signal is not used anymore. The driver may also choose to internally switch to an alternate clock source during the PLL lock period. In any case the clock provider must ensure that clock signals keep running smoothly if currently in use or return an error.

The dev_cmu_src_notify function is called by the driver for all impacted source endpoints once the change has occurred. The device lock must be held when calling this function.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CMU_COMMIT macro.

This typedef is declared in device/class/cmu.h source file, line 170.

This typedef sets the next configuration of a clock mux node internal to the device.

This function acts on endpoint nodes and internal clock signals nodes. The function have to select the mux to the parent clock node inside the device and optionally update the clock scale factor associated to this mux.

No hardware configuration actually takes place before the call to the dev_cmu_commit_t function. The device lock must be held when calling this function.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CMU_CONFIG_MUX macro.

This typedef is declared in device/class/cmu.h source file, line 190.

This typedef sets the next configuration of a clock oscillator node internal to the device.

This typedef sets the oscillator frequency value and the accuracy values.

No hardware configuration actually takes place before the call to the dev_cmu_commit_t function. The device lock must be held when calling this function.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CMU_CONFIG_OSC macro.

This function is declared in device/class/cmu.h source file, line 351.

This helper iterates on resources to configure relevant muxes and oscillator nodes, then commits the changes.

This function is for internal use only.

This typedef is declared in device/class/cmu.h source file, line 285.

This typedef retrieves information about an internal clock node. The mask parameter specifies which information are fetched and is updated according to what is actually available.

Driver may set more fields than actually requested by mask upon calling.

The device lock must be held when calling this function.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CMU_NODE_INFO macro.

See also struct dev_cmu_node_info_s, enum dev_cmu_node_info_e and dev_cmu_node_info.

This typedef is declared in device/class/cmu.h source file, line 227.

This typedef discard all configuration changes requests made by calling the dev_cmu_config_mux_t and dev_cmu_config_osc_t functions. This can be used to revert to a known state in case of error.

The device lock must be held when calling this function.

This typedef is for internal use only.

This declaration involves expansion of the DEV_CMU_ROLLBACK macro.

This function is declared in device/class/cmu.h source file, line 364.

This helper function is called by the clock provider device driver when the frequency of a clock source endpoint changes.

This function will propagate the change to all connected sink endpoints by calling the dev_use_t function of the associated device driver with the DEV_USE_CLOCK_SINK_FREQ_CHANGED operation. The sink field of param is set by the function.

This is available when CONFIG_DEVICE_CLOCK_VARFREQ is defined.

This function is for internal use only.

This struct is declared in device/class/cmu.h source file, line 305.

this struct defines an API for a CMU driver. It must be passed to libdevice helpers to accomplish various management tasks.

This struct is for internal use only.