udi_status_t(3udi)

---

UDI status code

SYNOPSIS

#include <udi.h>

typedef udi_ubit32_t udi_status_t;
 
/* Mask Values and Flags for udi_status_t */
 

#define  UDI_STATUS_CODE_MASK				0x0000FFFF
 
#define  UDI_STAT_META_SPECIFIC				0x00008000
 
#define  UDI_SPECIFIC_STATUS_MASK				0x00007FFF
 
#define  UDI_CORRELATE_OFFSET				16
 
#define  UDI_CORRELATE_MASK				0xFFFF0000
 
/* Common Status Values */
 

#define  UDI_OK				0
 
#define  UDI_STAT_NOT_SUPPORTED				1
 
#define  UDI_STAT_NOT_UNDERSTOOD				2
 
#define  UDI_STAT_INVALID_STATE				3
 
#define  UDI_STAT_MISTAKEN_IDENTITY				4
 
#define  UDI_STAT_ABORTED				5
 
#define  UDI_STAT_TIMEOUT				6
 
#define  UDI_STAT_BUSY				7
 
#define  UDI_STAT_RESOURCE_UNAVAIL				8
 
#define  UDI_STAT_HW_PROBLEM				9
 
#define  UDI_STAT_NOT_RESPONDING				10
 
#define  UDI_STAT_DATA_UNDERRUN				11
 
#define  UDI_STAT_DATA_OVERRUN				12
 
#define  UDI_STAT_DATA_ERROR				13
 
#define  UDI_STAT_PARENT_DRV_ERROR				14
 
#define  UDI_STAT_CANNOT_BIND				15
 
#define  UDI_STAT_CANNOT_BIND_EXCL				16
 
#define  UDI_STAT_TOO_MANY_PARENTS				17
 
#define  UDI_STAT_BAD_PARENT_TYPE				18
 
#define  UDI_STAT_TERMINATED				19
 
#define  UDI_STAT_ATTR_MISMATCH				20
 

description UDI status values are 32-bit integers that are logically subdivided into a 16-bit status code field, and a 16-bit correlation field. Modules within the UDI environment must report status using this format. ("Modules" in the context of this section refers to drivers and environment services.) A module reports successful completion by setting the status value to UDI_OK.

To separate and distinguish between common status codes and metalanguage-specific status codes the status code, in the low-order 16-bits, is further sub-divided into a 1-bit "metalanguage-specific status flag" (0 = common status, 1 = metalanguage-specific status)-designated by UDI_STAT_META_SPECIFIC, and a 15-bit "specific status code"-designated by UDI_SPECIFIC_STATUS_MASK.

However, drivers do not generally need to be aware of this additional subdivision because the status code values are defined to include the flag bit, and drivers can just assign the UDI-defined status identifier into the udi_status_t (taking into account the correlation field, as described below). Metalanguage designers must make sure that UDI_STAT_META_SPECIFIC is or'ed into each of their metalanguage-specific status mnemonic constants.

When an error must be signalled, the reporting module selects an appropriate status code value (either one of the common ones shown below, or a call-specific or metalanguage-specific code appropriate to the context in which the error is encountered) and assigns it into a udi_status_t parameter. This status value shall contain zero in the correlation field in order to indicate that this is a new error, rather than a derivative error. The udi_status_t value is used in a call to udi_log_write (see page 17-7), which will record all the data pertinent to the error in a logging file and assign a correlation value to the error. This correlation value will be placed in the 16 most-significant bits of the udi_status_t on return. This combined value will be passed by the driver to other entities that are affected by the error. When this error in turn results in a derivative error worth logging (e.g., lost link connection results in a file access error) the next reporting module will replace the 16 least-significant bits of the udi_status_t with a new appropriate value but will maintain the correlation field contents. When called with a derivative status, udi_log_write will record that same correlation value, together with all the data pertinent to the new error. In this way, the individual entries in the log file can be threaded together by the correlation value to trace back to the original error for the root cause.

To check for a specific status code value, the driver writer can mask off the correlation field and compare the remaining value:

if ((status & UDI_STATUS_CODE_MASK) == UDI_STAT_XXX)

	handle_error();
 

9.9.1.1 Common Status Codes

The UDI environment defines several status codes for use in reporting various common problems and conditions within UDI drivers and metalanguages. It is important to note that any driver internal errors will have indeterminate results but very likely will result in the driver instance being killed without ever being re-entered, therefore there are no corresponding error codes defined for related conditions (e.g. invalid argument errors). For related information see Section 4.10.

UDI status error codes are defined with mnemonic constants as shown in the following table.

Table 9-2 Common UDI Status Codes

Status Code	Value	Meaning	Description
UDI_OK	0	Success	The request completed properly without any exceptional conditions.
UDI_STAT_NOT_SUPPORTED	1	Not supported	This operation is not supported by this UDI environment implementation or the combination of parameters specified for this operation cannot be supported by this environment or hardware.
UDI_STAT_NOT_UNDERSTOOD	2	Request not understood	The parameters specified for this operation exceed valid ranges, or the combination of parameters does not make sense for this operation. Used only for channel operations; if out-of-range values are used with service calls, the driver instance may be terminated with extreme prejudice.
UDI_STAT_INVALID_STATE	3	Invalid state	The request is understood and implemented, but is not valid in the current state. This is typically used for channel operations; UDI service operations are typically not stateful.
UDI_STAT_MISTAKEN_IDENTITY	4	Mistaken identity	The request is understood and implemented, but is inappropriate for the device or other object to which it refers. This is typically used when a parameter selects a physical resource that is not present for a particular device.
UDI_STAT_ABORTED	5	Operation aborted	The operation was successfully aborted as a result of a udi_cancel or udi_channel_op_abort service call or a metalanguage-specific cancellation request.
UDI_STAT_TIMEOUT	6	Operation exceeded specified time period	The operation had an associated timeout value which was exceeded causing this operation to be aborted.
UDI_STAT_BUSY	7	Resource busy	The device or associated resource is currently busy and cannot handle this request at this time (or queue this request for later handling).
UDI_STAT_RESOURCE_UNAVAIL	8	No resources available	There are insufficient resources to satisfy this request. There is no guarantee or expectation that sufficient resources will become available in the future.
UDI_STAT_HW_PROBLEM	9	Hardware problem	A problem has been detected with the associated hardware that prevents this request from being executed successfully and is not covered by a more specific error indication.
UDI_STAT_NOT_RESPONDING	10	Device not responding	The device is not present or not responding.
UDI_STAT_DATA_UNDERRUN	11	Data underrun	A data transfer from a device transferred less data than expected.
UDI_STAT_DATA_OVERRUN	12	Data overrun	A data transfer from a device attempted to transfer more data than expected.
UDI_STAT_DATA_ERROR	13	Data error	Data corruption was detected during a transfer, typically by a parity or checksum check.
UDI_STAT_PARENT_DRV_ERROR	14	Parent driver error	A parent (or ancestor) of the driver reporting this condition has encountered an error that has prevented the request from being successfully executed. There will typically be a correlated error log issued by the parent driver.
UDI_STAT_CANNOT_BIND	15	Cannot bind to parent	The driver tried to bind to its parent, but was rejected by the parent driver. Also used by the parent to indicate such rejection to its child.
UDI_STAT_CANNOT_BIND_EXCL	16	Cannot bind exclusively to parent	A request to bind exclusively to a driver cannot be satisfied because another child instance is already bound.
UDI_STAT_TOO_MANY_PARENTS	17	Too many parents for this driver	The request to bind to a parent cannot be supported because this driver instance is already bound to the maximum number of parents that it can support.
UDI_STAT_BAD_PARENT_TYPE	18	Cannot bind to this type of parent device	The request to bind to a parent cannot be satisfied because the parent metalanguage or device properties (as determined by the parent-specified enumeration attributes) for the binding is not a type supported by this driver instance in its current state.
UDI_STAT_TERMINATED	19	Region was abruptly terminated	The request failed because the target region was abruptly terminated. Drivers must not generate this status code directly. It is used when the environment generates responses on behalf of a terminated driver instance. When a driver receives an operation with this status code, it must ignore all other metalanguage-specific control block fields and parameters except buffer pointers.
UDI_STAT_ATTR_MISMATCH	20	Driver/device cannot comply with custom attribute setting.	The driver has been given a custom attribute value that it cannot set on its device. This status can be used during either a parent or child binding.

The status codes here may be supplemented by various Physical I/O status codes or metalanguage-specific status codes as defined in the corresponding UDI specification books.

9.9.2 Data Layout Specifier

Purpose:

The data layout specifier type is used to describe the layout of control blocks and other driver data structures that may be transferred between regions by using channel operations. Data layout specifiers are primarily used by metalanguage libraries to describe the layout of all fixed structures passed via channel operations. Drivers may in some cases need to declare layout specifiers themselves, to use with udi_cb_init_t or udi_cb_alloc_dynamic; this allows a driver to register the layout of inline memory structures that aren't strictly typed by the metalanguage.