Common use of Generic Interfaces Clause in Contracts

Generic Interfaces. In addition to asynCommon and optionally asynDrvUser, port drivers can implement one or more of the following message and/or register based interfaces. asynOctet methods for message based devices asynFloat64 methods for devices that read/write IEEE float values asynFloat32Array methods for devices that read/write arrays of IEEE 32-bit float values asynFloat64Array methods for devices that read/write arrays of IEEE 64-bit float values asynInt32 methods for devices that read/write integer values. Many analog I/O drivers can use this interface. asynInt64 methods for devices that read/write 64-bit integer values. 8 Standard Interfaces asynInt8Array methods for devices that read/write arrays of 8-bit integer values asynInt16Array methods for devices that read/write arrays of 16-bit integer values asynInt32Array methods for devices that read/write arrays of 32-bit integer values asynInt64Array methods for devices that read/write arrays of 64-bit integer values asynUInt32Digital methods for devices that read/write arrays of digital values. This interface provides a mask to address individual bits within registers. asynGenericPointer methods for devices that read/write arbitrary structures, passed via a void* pointer. The client and the server of course need to agree on the structure type being pointed to. asynEnum methods for devices to define enum strings, values, and severities. asynOption methods for device configuration using key/value pairs. asynManager asynManager is an interface and associated code. It is the "heart" of asynDriver since it manages the interactions between device support code and drivers. It provides the following services: • reporting Method: report • asynUser creation Methods: createAsynUser, duplicateAsynUser, freeAsynUser An asynUser is a "handle" for accessing asynManager services and for calling interfaces implemented by drivers. An asynUser must only be created via a call to createAsynUser or duplicateAsynUser since asynManager keeps private information for each asynUser. freeAsynUser puts the asynUser on a free list rather than calling free. Clients can continually create and free asynUsers quickly and without fragmenting memory. The call to createAsynUser specifies a processCallback and a timeoutCallback. These are the callbacks that will be called as a result of a queueRequest. An asynUser should not be shared between parts of code that can simultaneously access a driver. For example device support for standard EPICS records should create an asynUser for each record instance. • Basic asynUser services Methods: connectDevice, disconnect, findInterface These methods should only be called by the code that created the asynUser. After an asynUser is created the user calls connectDevice. The user is connected to a port driver that can communicate with a device. findInterface is called for each interface the user requires. disconnect is called when the user is done with the device. Generic Interfaces 9 • Queuing services Methods: queueRequest, cancelRequest, lockPort, unlockPort, queueLockPort, queueUnlockPort, blockProcessCallback, unblockProcessCallback queueRequest is a request to call the processCallback specified in the call to createAsynUser. Most interface methods must only be called from processCallback via a call to queueRequest or between calls to lockPort/unlockPort.. Exceptions to this rule must be clearly documented (a common exception are methods registerInterruptUser/cancelInterruptUser). queueRequest semantics differ for ports that can block and ports that do not block When registerPort is called by a driver that can block, a thread is created for the port. A set of queues, based on priority, is created for the thread. queueRequest puts the request on one of the queues. The port thread takes the requests from the queues and calls the associated callback. Only one callback is active at a time. When registerPort is called by a driver that does not block, a mutex is created for the port. queueRequest takes the mutex, calls the callback, and releases the mutex. The mutex guarantees that two callbacks to a port are not active at the same time. lockPort is a request to lock all access to low level drivers until unlockPort is called. If the port blocks then lockPort and all calls to the port driver may block. lockPort/unlockPort are provided for use by code that is willing to block or for communication with synchronous ports. A call to lockPort locks all addresses associated with a multi-address port. Prior to asyn R4-14 pasynManager->lockPort() immediately took the port mutex when it was available, rather than queueing a request to take the mutex. From asyn R4-14 to R4-20 lockPort queues a request to access the port and then blocks until the queue request callback runs in the portThread. When the queue request runs, the thread that called pasynManager->lockPort() executes, and the portThread blocks, until pasynManager->unlockPort() is called. In R4-21 the queued lockPort and unlockPort functions were renamed to queueLockPort and queueUnlockPort, and the original lightweight lockPort and unlockPort functions were restored. Up to R4-32 when queueLockPort called queueRequest it did not specify a timeout. This could lead to code being hung if the port disconnected after the call to queueRequest but before the callback was called. The code would remain hung until the port reconnected. In R4-32 the queueRequest is done with a timeout. The default timeout value is 2.0 seconds but this can be change with the shell command asynSetQueueLockPortTimeout(portName, double timeout). If the pasynUser->timeout passed to queueLockPort is greater than the current port timeout value this larger timeout from the pasynUser is used instead. blockProcessCallback is a request to prevent acccess to a device or port by other asynUsers between queueRequests. blockProcessCallback can be called from a processCallback or when the asynUser has no request queued. When called from processCallback blocking starts immediately, otherwise blocking starts the next time processCallback is called. Blocking means that no other asynUser's processCallback will be called until unblockProcessCallback is called. blockProcessCallback only works with drivers that can block and an error is returned if it is called for non-blocking drivers. • Basic Driver services Methods: registerPort,registerInterface registerPort is called by a portDriver. registerInterface is called by a portDriver or an interposeInterface.

Generic Interfaces. In addition to asynCommon and optionally asynDrvUser, port drivers can implement one or more of the following message and/or register based interfaces. asynOctet methods for message based devices asynFloat64 methods for devices that read/write IEEE float values asynFloat32Array methods for devices that read/write arrays of IEEE 32-bit float values asynFloat64Array methods for devices that read/write arrays of IEEE 64-bit float values asynInt32 methods for devices that read/write integer values. Many analog I/O drivers can use this interface. asynInt64 methods for devices that read/write 64-bit integer values. 8 Standard Interfaces asynInt8Array methods for devices that read/write arrays of 8-bit integer values asynInt16Array methods for devices that read/write arrays of 16-bit integer values asynInt32Array methods for devices that read/write arrays of 32-bit integer values asynInt64Array methods for devices that read/write arrays of 64-bit integer values 8 Standard Interfaces asynUInt32Digital methods for devices that read/write arrays of digital values. This interface provides a mask to address individual bits within registers. asynGenericPointer methods for devices that read/write arbitrary structures, passed via a void* pointer. The client and the server of course need to agree on the structure type being pointed to. asynEnum methods for devices to define enum strings, values, and severities. asynOption methods for device configuration using key/value pairs. pairs.‌ asynManager asynManager is an interface and associated code. It is the "heart" of asynDriver since it manages the interactions between device support code and drivers. It provides the following services: • reporting Method: report • asynUser creation Methods: createAsynUser, duplicateAsynUser, freeAsynUser An asynUser is a "handle" for accessing asynManager services and for calling interfaces implemented by drivers. An asynUser must only be created via a call to createAsynUser or duplicateAsynUser since asynManager keeps private information for each asynUser. freeAsynUser puts the asynUser on a free list rather than calling free. Clients can continually create and free asynUsers quickly and without fragmenting memory. The call to createAsynUser specifies a processCallback and a timeoutCallback. These are the callbacks that will be called as a result of a queueRequest. An asynUser should not be shared between parts of code that can simultaneously access a driver. For example device support for standard EPICS records should create an asynUser for each record instance. • Basic asynUser services Methods: connectDevice, disconnect, findInterface These methods should only be called by the code that created the asynUser. After an asynUser is created the user calls connectDevice. The user is connected to a port driver that can communicate with a device. findInterface is called for each interface the user requires. disconnect is called when the user is done with the device. Generic Interfaces 9 • Queuing services Methods: queueRequest, cancelRequest, lockPort, unlockPort, queueLockPort, queueUnlockPort, blockProcessCallback, unblockProcessCallback queueRequest is a request to call the processCallback specified in the call to createAsynUser. Most interface methods must only be called from processCallback via a call to queueRequest or between calls to lockPort/unlockPort.. Exceptions to this rule must be clearly documented (a common exception are Generic Interfaces 9 methods registerInterruptUser/cancelInterruptUser). queueRequest semantics differ for ports that can block and ports that do not block When registerPort is called by a driver that can block, a thread is created for the port. A set of queues, based on priority, is created for the thread. queueRequest puts the request on one of the queues. The port thread takes the requests from the queues and calls the associated callback. Only one callback is active at a time. When registerPort is called by a driver that does not block, a mutex is created for the port. queueRequest takes the mutex, calls the callback, and releases the mutex. The mutex guarantees that two callbacks to a port are not active at the same time. lockPort is a request to lock all access to low level drivers until unlockPort is called. If the port blocks then lockPort and all calls to the port driver may block. lockPort/unlockPort are provided for use by code that is willing to block or for communication with synchronous ports. A call to lockPort locks all addresses associated with a multi-address port. Prior to asyn R4-14 pasynManager->lockPort() immediately took the port mutex when it was available, rather than queueing a request to take the mutex. From asyn R4-14 to R4-20 lockPort queues a request to access the port and then blocks until the queue request callback runs in the portThread. When the queue request runs, the thread that called pasynManager->lockPort() executes, and the portThread blocks, until pasynManager->unlockPort() is called. In R4-21 the queued lockPort and unlockPort functions were renamed to queueLockPort and queueUnlockPort, and the original lightweight lockPort and unlockPort functions were restored. Up to R4-32 when queueLockPort called queueRequest it did not specify a timeout. This could lead to code being hung if the port disconnected after the call to queueRequest but before the callback was called. The code would remain hung until the port reconnected. In R4-32 the queueRequest is done with a timeout. The default timeout value is 2.0 seconds but this can be change with the shell command asynSetQueueLockPortTimeout(portName, double timeout). If the pasynUser->timeout passed to queueLockPort is greater than the current port timeout value this larger timeout from the pasynUser is used instead. blockProcessCallback is a request to prevent acccess to a device or port by other asynUsers between queueRequests. blockProcessCallback can be called from a processCallback or when the asynUser has no request queued. When called from processCallback blocking starts immediately, otherwise blocking starts the next time processCallback is called. Blocking means that no other asynUser's processCallback will be called until unblockProcessCallback is called. blockProcessCallback only works with drivers that can block and an error is returned if it is called for non-blocking drivers. • Basic Driver services Methods: registerPort,registerInterface registerPort is called by a portDriver. registerInterface is called by a portDriver or an interposeInterface.. Each port driver provides a configuration command that is executed for each port instance. The configuration command performs port specific initializations, calls registerPort, and registerInterface for each interface it implements. • Attribute Retrieval