Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_clkmgr.h File Reference

(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"

Go to the source code of this file.

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

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

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

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

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
handleClock Manager Handle.
clockGateable Clock ID.
[out]is_enabledwhether 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
handleClock Manager Handle.
clockGateable Clock ID.
new_statewhether 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
handleClock Manager Handle.
clockHintable Clock ID.
[out]is_enabledwhether 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
handleClock Manager Handle.
clockHintable Clock ID.
[out]hinted_is_enabledthe 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
handleClock Manager Handle.
clockHintable Clock ID.
new_statewhether 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
paramsHardware instance parameters.
[out]handleOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 29 of file dif_clkmgr.c.