Software APIs
dif_pattgen.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PATTGEN_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PATTGEN_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/pattgen/doc/">Pattern Generator</a> Device Interface
11 * Functions
12 */
13
14#include <stdint.h>
15
17
19
20#ifdef __cplusplus
21extern "C" {
22#endif // __cplusplus
23
24/**
25 * Helper X macro for defining enums and case statements related to Pattern
26 * Generator channels. If an additional channel is ever added to the hardware,
27 * this list can be updated.
28 */
29#define DIF_PATTGEN_CHANNEL_LIST(X) \
30 X(0) \
31 X(1)
32
33/**
34 * Helper macro for defining a `dif_pattgen_channel_t` enumeration constant.
35 * @channel_ Pattern Generator channel of the enumeration constant.
36 */
37#define PATTGEN_CHANNEL_ENUM_INIT_(channel_) \
38 kDifPattgenChannel##channel_ = channel_,
39
40/**
41 * A Pattern Generator channel.
42 */
46
47#undef PATTGEN_CHANNEL_ENUM_INIT_
48
49/**
50 * The polarity of a Pattern Generator channel.
51 */
53 /**
54 * Low polarity indicates the output data signal (PDA) changes on a falling
55 * output clock (PCL) edge.
56 */
58 /**
59 * High polarity indicates the output data signal (PDA) changes on a rising
60 * output clock (PCL) edge.
61 */
63 /**
64 * Number of polarity values, used for argument validation.
65 */
68
69/**
70 * Runtime configuration for a Pattern Generator channel.
71 */
73 /**
74 * The polarity of the channel.
75 */
77 /**
78 * The I/O clock divisor that determines the frequency of channel's clock.
79 *
80 * Specifically, the output clock frequency (f_pcl) is computed from the I/O
81 * clock frequency (f_io_clk):
82 *
83 * f_pcl = f_io_clk / (2 * (clock_divisor + 1))
84 */
85 uint32_t clock_divisor;
86 /**
87 * The lower 32-bits of the seed pattern.
88 *
89 * Some bits may go unused depending on the value of `seed_pattern_length`.
90 */
92 /**
93 * The upper 32-bits of the seed pattern.
94 *
95 * Some, or all, bits may go unused depending on the value of
96 * `seed_pattern_length`.
97 */
99 /**
100 * The length of the seed pattern.
101 *
102 * Units: bits
103 * Valid range: [1, 64]
104 */
106 /**
107 * The number of times to repeat the pattern.
108 *
109 * Valid range: [1, 1024]
110 */
112 /**
113 * Inactive level of the data signal.
114 *
115 * This is the level of the PDA output when the pattgen is not actively
116 * sending data bits (i.e., when pattgen is disabled or all data bits have
117 * been sent).
118 */
120 /**
121 * Inactive level of the clock signal.
122 *
123 * This is the level of the PCL output when the pattgen is not actively
124 * sending data bits (i.e., when pattgen is disabled or all data bits have
125 * been sent).
126 */
129
130/**
131 * Configures a Pattern Generator channel.
132 *
133 * This should be called once for each channel to be configured.
134 *
135 * Since writes to channel configuration registers have no effect when the
136 * channel is enabled, this function will return `kDifError` if the channel is
137 * enabled.
138 *
139 * @param pattgen A Pattern Generator handle.
140 * @param channel The channel to configure.
141 * @param config Runtime configuration parameters.
142 * @return The result of the operation.
143 */
146 dif_pattgen_channel_t channel,
148
149/**
150 * Sets the enablement state of a Pattern Generator channel.
151 *
152 * @param pattgen A Pattern Generator handle.
153 * @param channel The channel to set the enablement state of.
154 * @param enabled The enablement state to configure the channel in.
155 * @return The result of the operation.
156 */
159 dif_pattgen_channel_t channel,
160 dif_toggle_t enabled);
161
162/**
163 * Gets the enablement state of a Pattern Generator channel.
164 *
165 * @param pattgen A Pattern Generator handle.
166 * @param channel The channel to get the enablement state of.
167 * @param[out] is_enabled The enablement state of the channel.
168 * @return The result of the operation.
169 */
172 dif_pattgen_channel_t channel,
173 dif_toggle_t *is_enabled);
174
175#ifdef __cplusplus
176} // extern "C"
177#endif // __cplusplus
178
179#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_PATTGEN_H_