|
|
udi_dma_constraints_attr_set(3udi)
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