(dcee03a)

Clock manager Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Data Structures
struct	dif_clkmgr_params
	Hardware instantiation parameters for a clock manager. More...

struct	dif_clkmgr
	A handle to a clock manager. More...

Typedefs
typedef uint32_t	dif_clkmgr_gateable_clock_t
	An Index of a "Gateable" Clock. More...

typedef uint32_t	dif_clkmgr_hintable_clock_t
	An Index of a "Hintable" Clock. More...

typedef enum dif_clkmgr_toggle	dif_clkmgr_toggle_t
	A toggle state: enabled, or disabled. More...

typedef struct dif_clkmgr_params	dif_clkmgr_params_t
	Hardware instantiation parameters for a clock manager. More...

typedef struct dif_clkmgr	dif_clkmgr_t
	A handle to a clock manager. More...

typedef enum dif_clkmgr_result	dif_clkmgr_result_t
	The result of a clock manager operation.

Enumerations
enum	dif_clkmgr_toggle { kDifClkmgrToggleEnabled, kDifClkmgrToggleDisabled }
	A toggle state: enabled, or disabled. More...

enum	dif_clkmgr_result { kDifClkmgrOk = 0, kDifClkmgrError = 1, kDifClkmgrBadArg = 2 }
	The result of a clock manager operation. More...

Functions
DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t	dif_clkmgr_init (dif_clkmgr_params_t params, dif_clkmgr_t *handle)
	Creates a new handle for a clock manager. More...

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t	dif_clkmgr_gateable_clock_get_enabled (const dif_clkmgr_t handle, dif_clkmgr_gateable_clock_t clock, bool is_enabled)
	Check if a Gateable Clock is Enabled or Disabled. More...

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t	dif_clkmgr_gateable_clock_set_enabled (const dif_clkmgr_t *handle, dif_clkmgr_gateable_clock_t clock, dif_clkmgr_toggle_t new_state)
	Enable or Disable a Gateable Clock. More...

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t	dif_clkmgr_hintable_clock_get_enabled (const dif_clkmgr_t handle, dif_clkmgr_hintable_clock_t clock, bool is_enabled)
	Check if a Hintable Clock is Enabled or Disabled. More...

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t	dif_clkmgr_hintable_clock_set_hint (const dif_clkmgr_t *handle, dif_clkmgr_hintable_clock_t clock, dif_clkmgr_toggle_t new_state)
	Enable or Disable a Hintable Clock. More...

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t	dif_clkmgr_hintable_clock_get_hint (const dif_clkmgr_t handle, dif_clkmgr_hintable_clock_t clock, bool hinted_is_enabled)
	Read the current Hint for a Hintable Clock. More...

Detailed Description

Clock manager Device Interface Functions

Definition in file dif_clkmgr.h.

Data Structure Documentation

◆ dif_clkmgr_params

struct dif_clkmgr_params

Hardware instantiation parameters for a clock manager.

This struct describes information about the underlying hardware instance that is not determined until the hardware design is used as part of a top-level design.

Definition at line 64 of file dif_clkmgr.h.

Data Fields
mmio_region_t	base_addr	The base address for the clock manager hardware registers.
dif_clkmgr_gateable_clock_t	last_gateable_clock	The last index of gateable clocks being managed by this clock manager.
dif_clkmgr_hintable_clock_t	last_hintable_clock	The last index of of hintable clocks being managed by this clock manager.

◆ dif_clkmgr

struct dif_clkmgr

A handle to a clock manager.

This type should be treated as opaque by users.

Definition at line 84 of file dif_clkmgr.h.

Data Fields
dif_clkmgr_params_t	params

Typedef Documentation

◆ dif_clkmgr_gateable_clock_t

typedef uint32_t dif_clkmgr_gateable_clock_t

An Index of a "Gateable" Clock.

"Gateable" clocks are under full software control: they can be enabled and disabled by software, which directly starts and stops the identified clock.

Definition at line 29 of file dif_clkmgr.h.

◆ dif_clkmgr_hintable_clock_t

typedef uint32_t dif_clkmgr_hintable_clock_t

An Index of a "Hintable" Clock.

"Hintable" clocks are under partial software control: software can suggest they are stopped, but the clock manager may delay stopping the peripheral, or may ignore the request altogether.

Definition at line 38 of file dif_clkmgr.h.

◆ dif_clkmgr_params_t

typedef struct dif_clkmgr_params dif_clkmgr_params_t

Hardware instantiation parameters for a clock manager.

This struct describes information about the underlying hardware instance that is not determined until the hardware design is used as part of a top-level design.

◆ dif_clkmgr_t

typedef struct dif_clkmgr dif_clkmgr_t

A handle to a clock manager.

This type should be treated as opaque by users.

◆ dif_clkmgr_toggle_t

typedef enum dif_clkmgr_toggle dif_clkmgr_toggle_t

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumeration Type Documentation

◆ dif_clkmgr_result

enum dif_clkmgr_result

The result of a clock manager operation.

Enumerator

kDifClkmgrOk

Indicates that the operation succeeded.

kDifClkmgrError

Indicates some unspecified failure.

kDifClkmgrBadArg

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 91 of file dif_clkmgr.h.

◆ dif_clkmgr_toggle

enum dif_clkmgr_toggle

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumerator
kDifClkmgrToggleDisabled	The "disabled" state.

Definition at line 46 of file dif_clkmgr.h.

Function Documentation

◆ dif_clkmgr_gateable_clock_get_enabled()

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t dif_clkmgr_gateable_clock_get_enabled	(	const dif_clkmgr_t *	handle,
		dif_clkmgr_gateable_clock_t	clock,
		bool *	is_enabled
	)

Check if a Gateable Clock is Enabled or Disabled.

Parameters

	handle	Clock Manager Handle.
	clock	Gateable Clock ID.
[out]	is_enabled	whether the clock is enabled or not.

Returns: The result of the operation.

Definition at line 47 of file dif_clkmgr.c.

◆ dif_clkmgr_gateable_clock_set_enabled()

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t dif_clkmgr_gateable_clock_set_enabled	(	const dif_clkmgr_t *	handle,
		dif_clkmgr_gateable_clock_t	clock,
		dif_clkmgr_toggle_t	new_state
	)

Enable or Disable a Gateable Clock.

Parameters

handle	Clock Manager Handle.
clock	Gateable Clock ID.
new_state	whether to enable or disable the clock.

Returns: The result of the operation.

Definition at line 62 of file dif_clkmgr.c.

◆ dif_clkmgr_hintable_clock_get_enabled()

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t dif_clkmgr_hintable_clock_get_enabled	(	const dif_clkmgr_t *	handle,
		dif_clkmgr_hintable_clock_t	clock,
		bool *	is_enabled
	)

Check if a Hintable Clock is Enabled or Disabled.

Hintable clocks are not under full software control, but this operation accurately reflects the state of the current clock, regardless of any hint requests made by software.

To read what hint the software has given the hardware, use dif_clkmgr_hintable_clock_get_hint.

Parameters

	handle	Clock Manager Handle.
	clock	Hintable Clock ID.
[out]	is_enabled	whether the clock is enabled or not.

Returns: The result of the operation.

Definition at line 91 of file dif_clkmgr.c.

◆ dif_clkmgr_hintable_clock_get_hint()

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t dif_clkmgr_hintable_clock_get_hint	(	const dif_clkmgr_t *	handle,
		dif_clkmgr_hintable_clock_t	clock,
		bool *	hinted_is_enabled
	)

Read the current Hint for a Hintable Clock.

Hintable clocks are not under full software control; this operation accurately reflects the current software hint, not the current state of the clock.

To read whether the clock is currently enabled or disabled, use dif_clkmgr_hintable_clock_get_enabled.

Parameters

	handle	Clock Manager Handle.
	clock	Hintable Clock ID.
[out]	hinted_is_enabled	the current software request (hint) for this clock.

Returns: The result of the operation.

Definition at line 134 of file dif_clkmgr.c.

◆ dif_clkmgr_hintable_clock_set_hint()

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t dif_clkmgr_hintable_clock_set_hint	(	const dif_clkmgr_t *	handle,
		dif_clkmgr_hintable_clock_t	clock,
		dif_clkmgr_toggle_t	new_state
	)

Enable or Disable a Hintable Clock.

This only sets a hint that the clock should be enabled or disabled. The clock manager is in control of whether the clock should actually be enabled or disabled.

To read what hint the software has given the hardware, use dif_clkmgr_hintable_clock_get_hint. To read whether the clock is currently enabled or disabled, use dif_clkmgr_hintable_clock_get_enabled.

Parameters

handle	Clock Manager Handle.
clock	Hintable Clock ID.
new_state	whether to enable or disable the clock.

Returns: The result of the operation.

Definition at line 106 of file dif_clkmgr.c.

◆ dif_clkmgr_init()

DIF_WARN_UNUSED_RESULT dif_clkmgr_result_t dif_clkmgr_init	(	dif_clkmgr_params_t	params,
		dif_clkmgr_t *	handle
	)

Creates a new handle for a clock manager.

This function does not actuate the hardware.

Parameters

	params	Hardware instance parameters.
[out]	handle	Out param for the initialized handle.

Returns: The result of the operation.

Definition at line 29 of file dif_clkmgr.c.

(dcee03a)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_clkmgr_params

◆ dif_clkmgr

Typedef Documentation

◆ dif_clkmgr_gateable_clock_t

◆ dif_clkmgr_hintable_clock_t

◆ dif_clkmgr_params_t

◆ dif_clkmgr_t

◆ dif_clkmgr_toggle_t

Enumeration Type Documentation

◆ dif_clkmgr_result

◆ dif_clkmgr_toggle

Function Documentation

◆ dif_clkmgr_gateable_clock_get_enabled()

◆ dif_clkmgr_gateable_clock_set_enabled()

◆ dif_clkmgr_hintable_clock_get_enabled()

◆ dif_clkmgr_hintable_clock_get_hint()

◆ dif_clkmgr_hintable_clock_set_hint()

◆ dif_clkmgr_init()