[dif/pattgen] Add header containing API proposal

This proposes (and adds) a DIF API for the Pattern Generator IP.

Signed-off-by: Timothy Trippel <ttrippel@google.com>

sw/device/lib/dif/dif_pattgen.h

@@ -11,13 +11,140 @@
  * Functions
  */
 
+#include <stdint.h>
+
+#include "sw/device/lib/dif/dif_base.h"
+
 #include "sw/device/lib/dif/autogen/dif_pattgen_autogen.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif  // __cplusplus
 
-// TODO: Add DIFs.
+/**
+ * Helper X macro for defining enums and case statements related to Pattern
+ * Generator channels. If an additional channel is ever added to the hardware,
+ * this list can be updated.
+ */
+#define DIF_PATTGEN_CHANNEL_LIST(X) \
+  X(0)                              \
+  X(1)
+
+/**
+ * Helper macro for defining a `dif_pattgen_channel_t` enumeration constant.
+ * @channel_ Pattern Generator channel of the enumeration constant.
+ */
+#define PATTGEN_CHANNEL_ENUM_INIT_(channel_) \
+  kDifPattgenChannel##channel_ = channel_,
+
+/**
+ * A Pattern Generator channel.
+ */
+typedef enum dif_pattgen_channel {
+  DIF_PATTGEN_CHANNEL_LIST(PATTGEN_CHANNEL_ENUM_INIT_)
+} dif_pattgen_channel_t;
+
+#undef PATTGEN_CHANNEL_ENUM_INIT_
+
+/**
+ * The polarity of a Pattern Generator channel.
+ */
+typedef enum dif_pattgen_polarity {
+  /**
+   * Low polarity indicates the output data signal (PDA) changes on a falling
+   * output clock (PCL) edge.
+   */
+  kDifPattgenPolarityLow = 0,
+  /**
+   * High polarity indicates the output data signal (PDA) changes on a rising
+   * output clock (PCL) edge.
+   */
+  kDifPattgenPolarityHigh = 1,
+} dif_pattgen_polarity_t;
+
+/**
+ * Runtime configuration for a Pattern Generator channel.
+ */
+typedef struct dif_pattgen_channel_config {
+  /**
+   * The polarity of the channel.
+   */
+  dif_pattgen_polarity_t polarity;
+  /**
+   * The I/O clock divisor that determines the frequency of channel's clock.
+   */
+  uint32_t clock_divisor;
+  /**
+   * The lower 32-bits of the seed pattern.
+   *
+   * Some bits may go unused depending on the value of `seed_pattern_length`.
+   */
+  uint32_t seed_pattern_lower_word;
+  /**
+   * The upper 32-bits of the seed pattern.
+   *
+   * Some, or all, bits may go unused depending on the value of
+   * `seed_pattern_length`.
+   */
+  uint32_t seed_pattern_upper_word;
+  /**
+   * The length of the seed pattern in bits.
+   *
+   * Valid range: [0, 63]
+   */
+  uint8_t seed_pattern_length;
+  /**
+   * The number of times to repeat the pattern.
+   *
+   * Valid range: [0, 1023]
+   */
+  uint16_t num_pattern_repetitions;
+} dif_pattgen_channel_config_t;
+
+/**
+ * Configures a Pattern Generator channel.
+ *
+ * This should be called once for each channel to be configured.
+ *
+ * Since writes to channel configuration registers have no effect when the
+ * channel is enabled, this function will return `kDifError` if the channel is
+ * enabled.
+ *
+ * @param pattgen A Pattern Generator handle.
+ * @param channel The channel to configure.
+ * @param config Runtime configuration parameters.
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+dif_result_t dif_pattgen_configure_channel(const dif_pattgen_t *pattgen,
+                                           dif_pattgen_channel_t channel,
+                                           dif_pattgen_channel_config_t config);
+
+/**
+ * Sets the enablement state of a Pattern Generator channel.
+ *
+ * @param pattgen A Pattern Generator handle.
+ * @param channel The channel to set the enablement state of.
+ * @param enabled The enablement state to configure the channel in.
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+dif_result_t dif_pattgen_channel_set_enabled(const dif_pattgen_t *pattgen,
+                                             dif_pattgen_channel_t channel,
+                                             dif_toggle_t enabled);
+
+/**
+ * Gets the enablement state of a Pattern Generator channel.
+ *
+ * @param pattgen A Pattern Generator handle.
+ * @param channel The channel to get the enablement state of.
+ * @param[out] is_enabled The enablement state of the channel.
+ * @return The result of the operation.
+ */
+OT_WARN_UNUSED_RESULT
+dif_result_t dif_pattgen_channel_get_enabled(const dif_pattgen_t *pattgen,
+                                             dif_pattgen_channel_t channel,
+                                             dif_toggle_t *is_enabled);
 
 #ifdef __cplusplus
 }  // extern "C"