|
|
| |
|
|
|
DMA Constraints Management
2.1 Overview
The service calls in this chapter are used to manage constraints objects that are used to reflect drivers' constraints on buffer data and transfer properties. Constraints are used to indicate the data access capabilities and restrictions of the hardware and associated drivers as well as the various capabilities of software modules and drivers in the I/O handling path.
Constraints are first constructed in the environment by starting with a completely unconstrained set of constraints attributes, and are subjected to any restrictions imposed by the native bridge or any intervening bus bridges and then passed to the driver as its initial constraints object. Constraints may subsequently be set to more restrictive values by that driver or any other module in the data path, including the environment, the bus and any bus bridges, and any children of the driver.
To provide this capability, UDI defines a set of services used to set the values of various constraints. The environment implementation of constraints may include the ability to update the constraints at any time due to hardware events (e.g. hot swap), reconfiguration events (hardware or software), or changes in software parameters.
2.1.1 Constraints Attributes
Constraints may be imposed from several sources and are specified in terms of constraints attributes.
At the lowest level, constraints attributes indicate the host data access capabilities of the device. Any restrictions of the DMA engine on the device should be indicated by restricting one or more constraints attributes accordingly. For example, a device with only a 16-bit DMA address generation capability would indicate this by modifying the initial address-size constraints settings.
The constraints may then be combined in various combinations with other constraints or specific constraints attributes may be set by a driver to accurately represent the situations where the corresponding constraints apply. Drivers with different DMA constraints for different types of operations will typically have a different constraints handle for each operation type. Multiplexing drivers would typically combine constraints as dictated by the multiplexing possibilities to ensure that the constraints used are sufficient for all possible DMA uses.
The UDI environment need not adhere to constraints at resource allocation time. Instead, constraints may be ignored by the environment (if desired) up to such time as the constraint is applicable. A DMA constraint does not need to be explicitly adhered to until such time as a DMA mapping operation is performed. If the constraint is not honored at the time of initial resource allocation, the resource may need to be re-allocated at the time the constraint must be honored.
2.2 Constraints Attributes Service Calls and Structures
The functions in this section provide constraints attribute management services. These services include the ability to set or reset attributes on an existing constraints object, to combine constraints objects by merging attributes, and to make copies of existing constraints objects.
NAME udi_dma_constraints_attr_spec_t
Specify attribute/value pair
#include <udi.h>typedef struct { udi_dma_constraints_attr_t attr_type; udi_ubit32_t attr_value; } udi_dma_constraints_attr_spec_t;MEMBERS attr_type is the attribute being specified.
attr_value is the value for the attribute.
DESCRIPTION The udi_dma_constraints_attr_spec_t structure is used to associate an attribute with its corresponding value. An array of these structures is used as an argument for the udi_dma_constraints_attr_set operation to specify a list of attributes and their values to be set.
REFERENCES udi_dma_constraints_attr_t, udi_dma_constraints_attr_set
NAME udi_dma_constraints_attr_set
Set constraints attributes
#include <udi.h>void udi_dma_constraints_attr_set ( udi_dma_constraints_attr_set_call_t *callback, udi_cb_t *gcb, udi_dma_constraints_t src_constraints, const udi_dma_constraints_attr_spec_t *attr_list, udi_ubit16_t list_length, udi_ubit8_t flags ); typedef void udi_dma_constraints_attr_set_call_t ( udi_cb_t *gcb, udi_dma_constraints_t new_constraints, udi_status_t status ); /* Constraints Flags */#define UDI_DMA_CONSTRAINTS_COPY (1U<<0)ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Standard Calling Sequences" in the UDI Core Specification
src_constraints is a constraints handle for the constraints object to be modified.
attr_list is the list of attributes and values to set.
list_length is the number of valid entries in the attr_list array.
flags is a bitmask of optional flags, which may include zero or more of the following:
UDI_DMA_CONSTRAINTS_COPY Make a copy of src_constraints before applying the new attributes.
new_constraints is a new constraints handle for the modified constraints object. This replaces the src_constraints handle.
status is a UDI status code indicating the success or failure of the constraints modification operation.
DESCRIPTION udi_dma_constraints_attr_set sets or changes one or more attribute values in the constraints object referenced by the src_constraints handle. The attr_list argument indicates this driver's requirements for the specified constraints attributes.
If UDI_DMA_CONSTRAINTS_COPY is set in flags, then src_constraints must be non-null, and a new constraints object will be allocated with its values copied from src_constraints; the new attribute values from attr_list will be applied to the new copy, which will then be passed back to the driver via new_constraints; the original source constraints object will retain its original values, but must not again be referenced by the driver until the callback.
If UDI_DMA_CONSTRAINTS_COPY is not set, the original source object (if any) will be consumed, and a handle to the newly modified object will be passed back to the driver via new_constraints in the callback. In this case, the driver must subsequently use the new_constraints value in place of src_constraints. If src_constraints was null, a new constraints object will be allocated.
Most attributes have a defined range of least restrictive to most restrictive values, as specified with the description of the attribute. In these cases, udi_dma_constraints_attr_set sets the new value for an attribute to be the more restrictive of the specified attr_list entry's attr_value and the attribute's current value.
For example, if the current value of UDI_DMA_ELEMENT_LENGTH_BITS were 64 and the attr_list entry's attr_value were 32, the new value would be 32; but if attr_list entry's attr_value were 128, the attribute value would remain set to 64, since 64 is more restrictive than 128 for UDI_DMA_ELEMENT_LENGTH_BITS.
A few attributes have no defined sense of less or more restrictive. These are marked as "N/A" (not applicable). For these attributes, the new value is simply set to the value specified in the attr_list entry.
Once all attributes in the attr_list have been processed, the callback routine is invoked to notify the driver that the constraints object has been modified and the success or failure of that modification.
The udi_dma_constraints_attr_set operation may fail with status set to UDI_STAT_NOT_SUPPORTED if the requested attributes cannot be supported on a given system. The UDI_STAT_NOT_SUPPORTED error case is not intended to catch invalid attribute values. If attribute values are used that are outside the valid ranges documented for the attribute, the results are implementation-dependent.
If status indicates failure, the constraints object passed back in new_constraints shall have the same constraints attribute values as the original, and no additional constraints objects shall be allocated (even if UDI_DMA_CONSTRAINTS_COPY was set in the call).
WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Standard Calling Sequences" in the UDI Core Specification.
Use of the attr_list parameter must conform to the rules described in Section 5.2.1.1, "Using Memory Pointers with Asynchronous Service Calls".
STATUS VALUES UDI_OK successful modification of the constraints attributes
UDI_STAT_NOT_SUPPORTED environment and/or platform cannot support the requested combination of attributes.
REFERENCES udi_dma_constraints_attr_spec_t, udi_dma_constraints_attr_reset
NAME udi_dma_constraints_attr_reset
Reset a constraints attribute to default
#include <udi.h>void udi_dma_constraints_attr_reset ( udi_dma_constraints_t constraints, udi_dma_constraints_attr_t attr_type );ARGUMENTS constraints is a constraints handle for the constraints object to be modified.
attr_type is the attribute to reset.
DESCRIPTION udi_dma_constraints_attr_reset is used to reset a constraints attribute back to its default value (which is also usually the least restrictive). This is usually needed when a particular module provides special handling relative to the constraints attribute such that any restrictions imposed by parent or child drivers are not transferred through this driver.
REFERENCES udi_dma_constraints_attr_set, udi_dma_constraints_attr_t
NAME udi_dma_constraints_free
Free a constraints object
#include <udi.h>void udi_dma_constraints_free ( udi_dma_constraints_t constraints );ARGUMENTS constraints is a handle for the constraints object being deallocated.
DESCRIPTION udi_dma_constraints_free releases all resources associated with the constraints object.
If constraints is equal to UDI_NULL_CONSTRAINTS, explicitly or implicitly (zeroed by initial value or by using udi_memset), this function acts as a no-op. Otherwise, constraints must have been allocated by udi_dma_constraints_combine or passed to the driver via a channel operation.
| |
|
|
|