Software APIs
Macros | Typedefs | Enumerations | Functions
dif_base.h File Reference

(8b2da8d)

Shared macros and headers for DIFs. More...

#include <stdbool.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/multibits.h"
#include "sw/device/lib/base/internal/status.h"

Go to the source code of this file.

Macros

#define USING_INTERNAL_STATUS
 
#define DIF_RETURN_IF_ERROR(expr_)
 Evaluate an expression and return if the result is an error. More...
 

Typedefs

typedef enum dif_result dif_result_t
 The result of a DIF operation. More...
 
typedef enum dif_toggle dif_toggle_t
 A toggle state: enabled, or disabled. More...
 
typedef enum dif_irq_type dif_irq_type_t
 An interrupt type: event, or status. More...
 

Enumerations

enum  dif_result {
  kDifOk = kOk,
  kDifError = kInternal,
  kDifBadArg = kInvalidArgument,
  kDifLocked = kFailedPrecondition,
  kDifUnavailable = kUnavailable,
  kDifIpFifoFull = kResourceExhausted,
  kDifOutOfRange = kOutOfRange,
  kDifUnaligned = kUnimplemented
}
 The result of a DIF operation. More...
 
enum  dif_toggle {
  kDifToggleDisabled = 0,
  kDifToggleEnabled = 1
}
 A toggle state: enabled, or disabled. More...
 
enum  dif_irq_type {
  kDifIrqTypeEvent = 0,
  kDifIrqTypeStatus = 1
}
 An interrupt type: event, or status. More...
 

Functions

OT_WARN_UNUSED_RESULT bool dif_is_valid_toggle (dif_toggle_t val)
 Checks if a DIF toggle type is valid. More...
 
OT_WARN_UNUSED_RESULT bool dif_toggle_to_bool (dif_toggle_t val)
 Converts a dif_toggle_t to a bool. More...
 
OT_WARN_UNUSED_RESULT dif_toggle_t dif_bool_to_toggle (bool val)
 Converts a bool to a dif_toggle_t. More...
 
OT_WARN_UNUSED_RESULT dif_toggle_t dif_multi_bit_bool_to_toggle (multi_bit_bool_t val)
 Converts a multi-bit bool to a dif_toggle_t. More...
 
OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool4 (dif_toggle_t val)
 Converts a dif_toggle_t to a multi_bit_bool_t of 4 bits. More...
 
OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool8 (dif_toggle_t val)
 Converts a dif_toggle_t to a multi_bit_bool_t of 8 bits. More...
 
OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool12 (dif_toggle_t val)
 Converts a dif_toggle_t to a multi_bit_bool_t of 12 bits. More...
 
OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool16 (dif_toggle_t val)
 Converts a dif_toggle_t to a multi_bit_bool_t of 16 bits. More...
 

Detailed Description

Shared macros and headers for DIFs.

Definition in file dif_base.h.

Macro Definition Documentation

◆ DIF_RETURN_IF_ERROR

#define DIF_RETURN_IF_ERROR (   expr_)
Value:
do { \
dif_result_t local_error_ = (expr_); \
if (local_error_ != kDifOk) { \
return local_error_; \
} \
} while (false)

Evaluate an expression and return if the result is an error.

Parameters
expr_An expression which results in an dif_result_t.

Definition at line 31 of file dif_base.h.

Typedef Documentation

◆ dif_irq_type_t

An interrupt type: event, or status.

This enum may be used instead when describing an interrupt type. Specifically, event interrupts require software to manually clear them by writing to the interrupt status register (after handling the root cause), while status interrupts clear immediately when the root cause of the iterrupt has been handled.

◆ dif_result_t

typedef enum dif_result dif_result_t

The result of a DIF operation.

NOTE: additional result values can be defined in the manually-implemented header by creating an additional *_result_t enum type. See the Lifecycle Controller DIF for how this may be implemented.

◆ dif_toggle_t

typedef enum dif_toggle dif_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_irq_type

An interrupt type: event, or status.

This enum may be used instead when describing an interrupt type. Specifically, event interrupts require software to manually clear them by writing to the interrupt status register (after handling the root cause), while status interrupts clear immediately when the root cause of the iterrupt has been handled.

Enumerator
kDifIrqTypeEvent 

Event type interrupt.

kDifIrqTypeStatus 

Status type interrupt.

Definition at line 116 of file dif_base.h.

◆ dif_result

enum dif_result

The result of a DIF operation.

NOTE: additional result values can be defined in the manually-implemented header by creating an additional *_result_t enum type. See the Lifecycle Controller DIF for how this may be implemented.

Enumerator
kDifOk 

Indicates that the operation succeeded.

kDifError 

Indicates some unspecified failure.

kDifBadArg 

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

When this value is returned, no hardware operations occurred.

kDifLocked 

The operation failed because writes to a required register are disabled.

kDifUnavailable 

The operation failed because the IP is processing an operation, and will finish in some amount of time.

A function that returns this error may be retried at any time, and is guaranteed to have not produced any side effects.

kDifIpFifoFull 

Indicates that the Ip's FIFO (if it has one or more of) is full.

kDifOutOfRange 

Indicates that the attempted operation would attempt a read/write to an address that would go out of range.

kDifUnaligned 

Indicates that the attempted operation would attempt a read/write to an address that is not aligned.

Definition at line 46 of file dif_base.h.

◆ dif_toggle

enum dif_toggle

A toggle state: enabled, or disabled.

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

Enumerator
kDifToggleDisabled 

The "disabled" state.

kDifToggleEnabled 

The "enabled" state.

Definition at line 96 of file dif_base.h.

Function Documentation

◆ dif_bool_to_toggle()

OT_WARN_UNUSED_RESULT dif_toggle_t dif_bool_to_toggle ( bool  val)
inline

Converts a bool to a dif_toggle_t.

Parameters
valA bool value.
Returns
Corresponding dif_toggle_t value.

Definition at line 170 of file dif_base.h.

◆ dif_is_valid_toggle()

OT_WARN_UNUSED_RESULT bool dif_is_valid_toggle ( dif_toggle_t  val)
inline

Checks if a DIF toggle type is valid.

Parameters
valA potential dif_toggle_t value.
Returns
Bool indicating validity of toggle value.

Definition at line 134 of file dif_base.h.

◆ dif_multi_bit_bool_to_toggle()

OT_WARN_UNUSED_RESULT dif_toggle_t dif_multi_bit_bool_to_toggle ( multi_bit_bool_t  val)
inline

Converts a multi-bit bool to a dif_toggle_t.

Parameters
valA multi-bit bool value.
Returns
Corresponding dif_toggle_t value.

Definition at line 181 of file dif_base.h.

◆ dif_toggle_to_bool()

OT_WARN_UNUSED_RESULT bool dif_toggle_to_bool ( dif_toggle_t  val)
inline

Converts a dif_toggle_t to a bool.

Parameters
valA dif_toggle_t value.
Returns
Corresponding bool value.

Definition at line 152 of file dif_base.h.

◆ dif_toggle_to_multi_bit_bool12()

OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool12 ( dif_toggle_t  val)
inline

Converts a dif_toggle_t to a multi_bit_bool_t of 12 bits.

Parameters
valA dif_toggle_t value.
Returns
Corresponding multi_bit_bool_t value. Invalid values resolve to "false".

Definition at line 233 of file dif_base.h.

◆ dif_toggle_to_multi_bit_bool16()

OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool16 ( dif_toggle_t  val)
inline

Converts a dif_toggle_t to a multi_bit_bool_t of 16 bits.

Parameters
valA dif_toggle_t value.
Returns
Corresponding multi_bit_bool_t value. Invalid values resolve to "false".

Definition at line 249 of file dif_base.h.

◆ dif_toggle_to_multi_bit_bool4()

OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool4 ( dif_toggle_t  val)
inline

Converts a dif_toggle_t to a multi_bit_bool_t of 4 bits.

Parameters
valA dif_toggle_t value.
Returns
Corresponding multi_bit_bool_t value. Invalid values resolve to "false".

Definition at line 201 of file dif_base.h.

◆ dif_toggle_to_multi_bit_bool8()

OT_WARN_UNUSED_RESULT multi_bit_bool_t dif_toggle_to_multi_bit_bool8 ( dif_toggle_t  val)
inline

Converts a dif_toggle_t to a multi_bit_bool_t of 8 bits.

Parameters
valA dif_toggle_t value.
Returns
Corresponding multi_bit_bool_t value. Invalid values resolve to "false".

Definition at line 217 of file dif_base.h.