[dif] Deprecrate `dif_<ip>_params_t` struct.
This partially addresses #8409 by:
1. deprecating dif_<ip>_params_t struct from the
util/make_new_dif/dif_template.h.tpl, and
2. updates the DIF website documentation to match.
Signed-off-by: Timothy Trippel <ttrippel@google.com>
diff --git a/sw/device/lib/dif/README.md b/sw/device/lib/dif/README.md
index 161dce2..e286412 100644
--- a/sw/device/lib/dif/README.md
+++ b/sw/device/lib/dif/README.md
@@ -98,31 +98,10 @@
At the moment, we have a good approach to being able to address separate
hardware instances instantiated at separate addresses, as long as they have the
-same hardware parameters (see the `base_addr` member in `dif_<ip>_params_t`).
-Most other parameters come from the specific IP on a case-by-case basis.
-
-As much as possible, we would like to hide these parameters underneath the
-interface of the DIF, but this is not always possible, especially where
-particular functionality requires the DIF caller to allocate memory. This should
-be done even if the current DIF implementation does not support changing
-parameters, so we can add this parameterization later.
-
-In order to support exposing these parameters to callers, DIFs should provide
-query functions which take a `dif_<ip>_params_t`, rather than `#define`s or
-global variable definitions. These functions do not have to return
-`dif_<ip>_result_t` if they do not error.
-
-An example of such a query function is provided in the template, called
-`dif_<ip>_get_size`, but we are not placing restrictions on the naming of these
-functions.
-
-One implication of this decision is that we will not always be able to provide
-struct definitions containing fixed-size buffers, which we have relied upon in
-the past. These structs should instead use a pointer and a size member to safely
-store the buffer outside the struct and use it without overflows. From the DIF's
-perspective, these buffers are dynamically allocated, even if we get static
-information about their size from other information (e.g. topgen).
-
+same hardware parameters (see the `base_addr` member in `dif_<ip>_t`).
+Most other parameters come from the specific IP on a case-by-case basis, and are
+extracted from the IP's auto-generated register header file, e.g.,
+`<ip>_regs.h`.
#### Base Types
@@ -135,10 +114,6 @@
This type is usually passed by `const` pointer, except when it is
being initialized (see `dif_<ip>_init()` below).
This type is always passed by value.
-* `dif_<ip>_params_t` is a *manually-defined* struct representing hardware
- instantiation parameters that a DIF library cannot know in advance. This type
- is optional, and may not be defined for IPs that do not have hardware
- instantiation parameters outside their instantiation specific base address.
* `dif_<ip>_config_t` is a *manually-defined* struct representing runtime
configuration parameters. It is only present when `dif_<ip>_configure()` is
defined. This type is always passed by value.
@@ -173,11 +148,6 @@
hardware operations. `handle` may point to uninitialized data on function entry,
but if the function returns `Ok`, then `handle` must point to initialized data.
- Additionally, this function may take an additional argument, of type
- `dif_<ip>_params_t`, for parameter validation. This argument will only be
- provided for peripherals that have additional hardware instantiation
- parameters besides a base address (e.g., the alert handler).
-
* `result_t dif_<ip>_configure(const dif_<ip>_t *handle, dif_<ip>_config_t
config);` configures the hardware managed by `handle` with runtime parameters
in an implementation-defined way. This function should be "one-off": it should
diff --git a/util/make_new_dif/dif_template.h.tpl b/util/make_new_dif/dif_template.h.tpl
index dc2a89c..f51ffcf 100644
--- a/util/make_new_dif/dif_template.h.tpl
+++ b/util/make_new_dif/dif_template.h.tpl
@@ -43,21 +43,6 @@
#endif // __cplusplus
/**
- * Hardware instantiation parameters for ${ip.name_long_lower}.
- *
- * This struct describes information about the underlying HARDWARE that is
- * not determined until the hardware IP is used as part of a top-level
- * design. This EXCLUDES the base address of the IP as this is defined the IP's
- * handle struct which is autogenerated using the
- * util/make_new_dif/dif_autogen.h.tpl template. This is typically only used
- * with templated (generic) IPs, such as the Alert Handler.
- */
-typedef struct dif_${ip.name_snake}_params {
- // Fields, if necessary.
- // DO NOT include the IP's base address as a field, see above.
-} dif_${ip.name_snake}_params_t;
-
-/**
* Runtime configuration for ${ip.name_long_lower}.
*
* This struct describes (SOFTWARE) runtime information for one-time
@@ -83,31 +68,17 @@
} dif_${ip.name_snake}_output_t;
/**
- * Calculates information needed to safely call a DIF. Functions like this
- * should be used instead of global variables or #defines.
- *
- * This function does not actuate the hardware.
- *
- * @param params Hardware instantiation parameters.
- * @return The information required.
- */
-OT_WARN_UNUSED_RESULT
-uint32_t dif_${ip.name_snake}_get_size(dif_${ip.name_snake}_params_t params);
-
-/**
* Creates a new handle for ${ip.name_long_lower}.
*
* This function does not actuate the hardware.
*
* @param base_addr The MMIO base address of the IP.
- * @param params Hardware instantiation parameters. (optional, may remove)
* @param[out] ${ip.name_snake} Out param for the initialized handle.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_${ip.name_snake}_init(
mmio_region_t base_addr,
- dif_${ip.name_snake}_params_t params,
dif_${ip.name_snake}_t *${ip.name_snake});
/**
