A DIF is a “Device Interface Function”. DIFs are low-level routines for accessing the hardware functionality directly, and are agnostic to the particular environment or context they are called from. The intention is that DIFs are high-quality software artifacts which can be used during design verification and early silicon verification.
Although DIFs are high-quality software artifacts, they are not a hardware abstraction layer (HAL), nor do they follow the device driver model of any particular operating system, and as such, DIFs are not intended to be used by production firmware. DIFs, in combination with the hardware specification, may be illustrative for writing drivers, but should not be considered drivers themselves.
This subtree provides headers and libraries known collectively as the DIF libraries.
There is one DIF library per hardware IP, and each one contains the DIFs required to actuate all of the specification-required functionality of the hardware they are written for.
Each DIF library contains both auto-generated (which are checked-in to our repository under the autogen/ subtree), and manually-implemented DIFs (which are not sub-foldered).
Developers should use the util/make_new_dif.py script to both auto-generate a subset of DIFs, and instantiate some initial boilerplate templates that should be subsequently edited. Specifically, the script will create:
autogen/dif_<ip>_autogen.h, based on util/make_new_dif/templates/dif_autogen.h.tpl,autogen/dif_<ip>_autogen.c, based on util/make_new_dif/templates/dif_autogen.c.tpl, andautogen/dif_<ip>_autogen_unittest.cc, based on util/make_new_dif/templates/dif_autogen_unittest.cc.tpl.util/make_new_dif/templates/dif_template.h.tpl], anddoc/project/sw_checklist.md.tpl.Only the second set of files will need checking and editing, but the templates serve to avoid most of the copy/paste required, while keeping our DIF libraries consistent across IPs.
Further documentation for the script is provided in the script's source. Additionally, please invoke util/make_new_dif.py --help for detailed usage.
This directory also contains checklists for each DIF, in markdown format. They are linked to from the Hardware Dashboard, in the Development Stage column.
DIFs are very low-level software, so they have a more rigorous coding style than other parts of the codebase.
DIFs should follow the OpenTitan C/C++ style guide where it does not contradict with the guidelines below.
The guidelines below apply to writing DIFs, and code should be written in a similar style to the existing DIF libraries in this directory.
Side-effects include (but are not limited to) writing to memory, including memory-mapped hardware, and modifying processor CSRs.
sw/device/lib/base/bitfield.hsw/device/lib/base/mmio.hsw/device/lib/base/memory.hsw/device/lib/dif/dif_base.h#include the (private) auto-generated header, so that DIF consumers need only #include the public DIF header to make use of an IP's DIF library.The following rules specify the basic API that each DIF must conform to. These rules specify the names of types, constants, and functions that each DIF must define for providing certain kinds of non-device-specific functionality (such as initializing handles or managing interrupts).
Notational caveats:
<ip> is the “short IP name” of the peripheral, in snake_case or PascalCase as is appropriate.handle is not normative, and DIF libraries are free to choose a different, but consistent, name for it.dif_result_t, a global DIF return type defined in sw/device/lib/dif/dif_base.h.Our aim is that a single DIF library can be used with multiple instances of the same IP on the same chip, even when those IPs have been instantiated with different hardware parameters.
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>_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.
There are two categories of base types:
sw/device/lib/dif/dif_base.h and used in all DIF libraries, andThe base types defined in sw/device/lib/dif/dif_base.h include:
dif_result_t -- an enum representing global DIF return codes.dif_toggle_t -- an enum to be used instead of a bool when describing enablement states.The base types that are expected to be defined separately by all DIF libraries include:
dif_<ip>_t -- an auto-generated type representing a handle to the peripheral. Its first (and only) field is always the base address for the peripheral registers, styled mmio_region_t base_addr;. This type is usually passed by const pointer, except when it is being initialized (see dif_<ip>_init() below).dif_<ip>_config_t -- a manually-defined struct representing runtime configuration parameters for the peripheral. It is only present when dif_<ip>_configure() is defined. This type is always passed by value.The following functions are the basic functionality for initializing and handling the lifetime of a handle.
dif_result_t dif_<ip>_init(mmio_region_t base_addr, dif_<ip>_t *handle); initializes handle with with the base address of the instantiated IP this DIF is targeting to use. This DIF is auto-generated.
dif_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 only need to be called once for the lifetime of the handle. If there is no meaningful state to configure, this function may be omitted. In particular, DIF libraries providing transaction functions will usually have no need for this function at all. This DIF is manually-implemented.
The following types and functions are the standard interface for transaction-oriented peripherals, in which a client schedules an operation to be completed at some point in the future. All types and functions listed here are manually-implemented.
dif_<ip>_transaction_t is a struct representing runtime parameters for starting a hardware transaction. It is only present when dif_<ip>_start() is defined. This type is always passed by value. A DIF library my opt to use another pre-existing type instead, when that type provides a more semantically appropriate meaning.dif_<ip>_output_t is a struct describing how to output a completed transaction. Often, this will be a type like uint8_t *. The same caveats about a DIF library providing a different type apply here.dif_result_t dif_<ip>_start(const dif_<ip>_t *handle, dif_<ip>_transaction_t transaction); starts a transaction on a transaction-oriented peripheral. This function may be called multiple times, but each call should be paired with a dif_<ip>_end() call.dif_result_t dif_<ip>_end(const dif_<ip>_t *handle, dif_<ip>_output_t out); completes a transaction started with dif_<ip>_start(), writing its results to a location specified in out.If a peripheral supports multiple transaction modes with incompatible parameter types, the above names may be duplicated by inserting mode_<mode> after <ip>. For example,
dif_result_t dif_<ip>_mode_<mode>_end(const dif_<ip>_t *handle,
dif_<ip>_mode_<mode>_output_t out);
There is no requirement that _start() and _end() share the same set of <mode>s; for example, there might be a single dif_<ip>_start() but many dif_<ip>_mode_<mode>_end()s. This style of API is preferred over using unions with dif_<ip>_transaction_t and dif_<ip>_output_t.
The following functions are the standard interface for peripherals that can lock portions of their software-accessible functionality. All types and functions listed here are manually-implemented.
kDifLocked is the global return result enum of an operation that can be locked out. DIFs which may fail due to lockout, which is software-detectable, should return this value when possible.dif_result_t dif_<ip>_lock(const dif_<ip>_t *handle); locks out all portions of the peripheral which can be locked. If a peripheral can be locked-out piecewise, dif_<ip>_lock_<operation>() functions may be provided alongside or in lieu of dif_<ip>_lock().dif_result_t dif_<ip>_is_locked(const dif_<ip>_t *handle, bool *is_locked); checks whether the peripheral has been locked out. As with dif_<ip>_lock(), DIF libraries may provide a piecewise version of this API.The following types and functions are the standard interface for peripherals that provide a collection of INTR_ENABLE, INTR_STATE, and INTR_TEST registers for interrupt management. A DIF library for a peripheral providing such registers must provide this interface. To ensure this, all interrupt DIFs, including: headers, (C) implementations, and unit tests, are auto-generated from templates and an IP's HJSON configuration file using the util/make_new_dif.py tool (described above).
If a peripheral is defined with no_auto_intr_regs: true, this exact API is not required even if the INTR_ registers are provided (though DIF libraries are encouraged to follow it where it makes sense). In these cases, auto-generated interrupt DIFs may not exist.
dif_<ip>_irq_t is an enum that lists all of the interrupt types for this peripheral. These derived from the interrupt_list attribute within an IP's HJSON file.dif_result_t dif_<ip>_irq_get_state(const dif_<ip>_t *handle, dif_<ip>_irq_state_snapshot_t *snapshot, bool *is_pending); returns a snapshot of the entire interrupt state register, to check the status of all interrupts for a peripheral.dif_result_t dif_<ip>_irq_is_pending(const dif_<ip>_t *handle, dif_<ip>_irq_t irq, bool *is_pending); checks whether a specific interrupt is pending (i.e., if the interrupt has been asserted but not yet cleared).dif_result_t dif_<ip>_irq_acknowledge_all(const dif_<ip>_t *handle); acknowledges all interrupts have been serviced, marking them as complete by clearing all pending bits. This function does nothing and returns kDifOk if no interrupts were pending.dif_result_t dif_<ip>_irq_acknowledge(const dif_<ip>_t *handle, dif_<ip>_irq_t irq); acknowledges that an interrupt has been serviced, marking it as complete by clearing its pending bit. This function does nothing and returns kDifOk if the interrupt wasn't pending.dif_result_t dif_<ip>_irq_get_enabled(const dif_<ip>_t *handle, dif_<ip>_irq_t irq, const dif_<ip>_toggle_t *state); gets whether an interrupt is enabled (i.e., masked).dif_result_t dif_<ip>_irq_set_enabled(const dif_<ip>_t *handle, dif_<ip>_irq_t irq, dif_<ip>_toggle_t state); sets whether a particular interrupt is enabled (i.e., masked).dif_result_t dif_<ip>_irq_force(const dif_<ip>_t *handle, dif_<ip>_irq_t irq); forcibly asserts a specific interrupt, causing it to be serviced as if hardware had triggered it.Additionally, the following types allow for batch save/restore operations on the interrupt enable register:
dif_<ip>_irq_enable_snapshot_t is a type that encapsulates restorable interrupt enablement state, to be used with the two functions below. This type should be treated as opaque by clients.dif_result_t dif_<ip>_irq_disable_all(const dif_<ip>_t *handle, dif_<ip>_irq_enable_snapshot_t *snapshot); disables all interrupts associated with the peripheral, saving them to *snapshot. snapshot may be null, in which case the previous enablement state is not saved.dif_result_t dif_<ip>_irq_restore_all(const dif_<ip>_t *handle, const dif_<ip>_irq_enable_snapshot_t *snapshot); restores an interrupt enablement snapshot produced by the above function.Each DIF has an associated unit test, written in C++. For auto-generated DIFs, their associated unit tests are also auto-generated. For manually-implemented DIFs, their associated unit tests follow the conventions:
dif_<ip>_unittest namespace.<ip>Test, which derives testing::Test and mock_mmio::MmioTest.<function>Test, which derives <ip>Test. Multiple similar functions may be grouped under one fixture.EXPECT_DIF_OK, defined in dif_test_base.h whenever possible (e.g. do not write EXPECT_EQ(<long expression>, kDifOk);).The following rules must be followed by public DIF functions (those declared in the DIF library‘s header file). Internal DIF functions (those declared static and not declared in the DIF library’s header file) should follow these rules but there are some relaxations of these rules for them described at the end.
DIF declarations must match their definitions exactly.
const or volatile (cv-qualified) in DIF signatures.DIFs must use one of the dif_result_t enums (described in sw/device/lib/dif/dif_base.h) rather than booleans for reporting errors. If a DIF can either error or instead produce a value, it must return a dif_result_t, and use an out-parameter for returning the produced value.
OT_WARN_UNUSED_RESULT, to help minimize mistakes from failing to check a result. This guidance applies to static helper functions that return an error of some kind as well.void.DIFs must check their arguments against preconditions using “guard statements”. A guard statement is a simple if statement at the start of a function which only returns an error code if the preconditions are not met. Guard statements must cover the following checks:
mmio_region_t are not pointers, and cannot meaningfully be checked for non-nullness.Switch statements in DIFs must always have a default case, including when switching on an enum value (an “enum switch”).
kDifError or the equivalent return code value from a global DIF return code enum. If the enum switch is part of a guard statement, it may return kDifBadArg instead.case for enum constants that are unreachable due to a guard statement.DIFs must use sw/device/lib/base/mmio.h for accessing memory-mapped hardware. DIFs must not use sw/device/lib/base/memory.h for accessing memory-mapped hardware.
Internal DIF functions, which are not intended to be part of a public DIF library interface, must not be declared in the DIF library header, and must be marked static.
static DIF functions should not be marked static inline.