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

The source code of this header can be browsed online.

Description  

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.

CMU device configuration selection  

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:

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.

Members  

Types  

Functions  

Macros  

Members detail  

#define CONFIG_DEVICE_CLOCK_MASKW  

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

#define DEV_CMU_APP_CONFIGID_SET(n)  

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

See also dev_cmu_app_configid_set_t.

#define DEV_CMU_COMMIT(n)  

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

See also dev_cmu_commit_t.

#define DEV_CMU_CONFIG_MUX(n)  

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

See also dev_cmu_config_mux_t.

#define DEV_CMU_CONFIG_OSC(n)  

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

See also dev_cmu_config_osc_t.

#define DEV_CMU_NODE_INFO(n)  

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

See also dev_cmu_node_info_t.

#define DEV_CMU_ROLLBACK(n)  

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

See also dev_cmu_rollback_t.

#define DEV_STATIC_RES_CMU_MUX(__parent_id, __node_id, __config_mask, __num, __denom)  

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

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.

#define DEV_STATIC_RES_CMU_MUX(__parent_id, __node_id, __config_mask, __num, __denom)  

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

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.

#define DEV_STATIC_RES_CMU_OSC(__node_id, __config_id, __num, __denom)  

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

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.

#define DEV_STATIC_RES_CMU_OSC(__node_id, __config_id, __num, __denom)  

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

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.

#define DEV_STATIC_RES_CMU_OSC_ACC(__node_id, __config_id, __num, __denom, _acc_m, _acc_e)  

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

This macro is similar to DEV_STATIC_RES_CMU_OSC

Preprocessor condition: defined( CONFIG_DEVICE_CLOCK )

#define DEV_STATIC_RES_CMU_OSC_ACC(__node_id, __config_id, __num, __denom, _acc_m, _acc_e)  

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

Documentation from alternate declaration:

This macro is similar to DEV_STATIC_RES_CMU_OSC

Preprocessor condition: not defined( CONFIG_DEVICE_CLOCK )

#define DRIVER_CMU_CONFIG_OPS_DECLARE(prefix)  

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.

#define DRIVER_CMU_METHODS(prefix)  

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

#define __DEVICE_CMU_H__  

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

bool_t dev_clock_src_is_clock_requested(const struct dev_clock_src_ep_s *src)  

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

This function tells whether a source endpoint currently requests clock.

bool_t dev_clock_src_is_power_requested(const struct dev_clock_src_ep_s *src)  

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

This function tells whether a source endpoint currently requests power.

typedef uint_fast8_t dev_cmu_config_id_t  

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.

typedef uint64_t dev_cmu_config_mask_t  

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.

typedef uint32_t dev_cmu_config_mask_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.

typedef uint16_t dev_cmu_config_mask_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.

error_t dev_cmu_init(struct device_s *dev, const struct device_cmu_config_ops_s *ops)  

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.

typedef uint_fast8_t dev_cmu_node_id_t  

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.

enum dev_cmu_node_info_e  

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.

IdentifierDescription
DEV_CMU_INFO_FREQ
DEV_CMU_INFO_NAME
DEV_CMU_INFO_PARENT
DEV_CMU_INFO_RUNNING
DEV_CMU_INFO_SINK
DEV_CMU_INFO_SRC
DEV_CMU_INFO_ACCURACY
DEV_CMU_INFO_SCALEFor scale-enabled source endpoints

error_t dev_cmu_node_info_get(struct device_cmu_s *accessor, dev_cmu_node_id_t node_id, enum dev_cmu_node_info_e *mask, struct dev_cmu_node_info_s *info)  

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.

struct dev_cmu_node_info_s  

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.

FieldDescription
struct dev_freq_s freq;Node current clock frequency
const char * name;Node name
dev_cmu_node_id_t parent_id;Node id of the currently selected parent node in the tree.
bool_t running;Specifies if the clock is currently running.
struct dev_clock_sink_ep_s * sink;Pointer to sink endpoint object when relevant
struct dev_clock_src_ep_s * src;Pointer to source endpoint object when relevant
struct dev_freq_ratio_s scale;Source endpoint frequency scale

void dev_cmu_src_update_async(struct dev_clock_src_ep_s *src, enum dev_clock_ep_flags_e gates)  

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.

void dev_cmu_src_update_sync(struct dev_clock_src_ep_s *src, enum dev_clock_ep_flags_e gates)  

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.

struct device_cmu_s  

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.

FieldDescription
union <anonymous> {
struct device_accessor_s base;
struct <anonymous> {
struct device_s * dev;
struct driver_cmu_s * api;
uint_fast8_t number;
};
};

struct device_accessor_s * device_cmu_s_base(struct device_cmu_s *x)  

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

struct device_cmu_s * device_cmu_s_cast(struct device_accessor_s *x)  

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

error_t device_res_add_cmu_mux(struct device_s *dev, dev_cmu_node_id_t parent_id, dev_cmu_node_id_t node_id, dev_cmu_config_mask_t config_mask, const struct dev_freq_ratio_s *ratio)  

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

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.

error_t device_res_add_cmu_osc(struct device_s *dev, dev_cmu_node_id_t node_id, dev_cmu_config_mask_t config_mask, uint64_t num, uint32_t denom)  

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

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.

struct driver_cmu_s  

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.

typedef error_t (dev_cmu_app_configid_set_t)(struct device_cmu_s *accessor, uint_fast8_t config_id)   

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.

typedef error_t (dev_cmu_commit_t)(struct device_s *dev)   

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.

typedef error_t (dev_cmu_config_mux_t)(struct device_s *dev, dev_cmu_node_id_t node_id, dev_cmu_node_id_t parent_id, struct dev_freq_ratio_s *ratio)   

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.

typedef error_t (dev_cmu_config_osc_t)(struct device_s *dev, dev_cmu_node_id_t node_id, struct dev_freq_s *freq)   

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.

error_t dev_cmu_configid_set(struct device_s *dev, const struct device_cmu_config_ops_s *ops, uint_fast8_t config_id)  

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

This function is for internal use only.

typedef error_t (dev_cmu_node_info_t)(struct device_cmu_s *accessor, dev_cmu_node_id_t node_id, enum dev_cmu_node_info_e *mask, struct dev_cmu_node_info_s *info)   

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.

typedef error_t (dev_cmu_rollback_t)(struct device_s *dev)   

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.

void dev_cmu_src_notify(struct dev_clock_src_ep_s *src, struct dev_clock_notify_s *param)  

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.

struct device_cmu_config_ops_s  

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.

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