NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO
#include <ddi/uart/uart.h>
DDI
Provides UART device driver services.
typedef struct { UartVersion version; KnError (*open) (UartId device_id, UartConfig* device_cfg, void* client_cookie, UartCallBack* client_ops, unsigned int* signals); void (*mask) (UartId device_id); void (*unmask) (UartId device_id); void (*transmit) (UartId device_id, unsigned char* buffer, unsigned int size); void (*abort) (UartId device_id); void (*txbreak) (UartId device_id); void (*control) (UartId device_id, unsigned int signals); void (*rxbuffer) (UartId device_id, unsigned char* buffer, unsigned int size); void (*close) (UartId device_id); } UartDevOps;
A pointer to the UartDevOps structure is exported by a driver via the svDeviceRegister microkernel call. A driver client invokes the svDeviceLookup and svDeviceEntry microkernel calls in order to obtain a pointer to the device service routines vector. Once the pointer is obtained, the driver client is able to invoke the driver service routines (via the indirect function call) in order to open/close devices, enable/disable device interrupts, start the data/break transmission, and raise/drop the modem control signals.
open establishes a connection between a driver client and a given device driver instance.
Arguments:
Specifies the UART device identifier.
Points to the UartConfig structure which specifies the serial line configuration (see below) .
Points to the client handle. The client handle is passed back to the client (as the first argument) each time a call-back handler is invoked.
Points to the UartCallBack structure which specifies the client call-back handlers (see section: Up-Call Handlers).
Points to a location where the initial modem status is returned.
The UartConfig structure is the following:
typedef struct { unsigned int baudRate; unsigned char dataBits; unsigned char stopBits; unsigned char parity; unsigned char fifoTrigger; } UartConfig;
The baudRate field specifies the input and output baud rate as an integer value (for example, 9600). The dataBits field specifies the number of data bits per character.
The following constants are allowed:
5 data bits
6 data bits
7 data bits
8 data bits
The stopBits field specifies the number of stop bits. The following constants are allowed:
1 stop bit
1.5 stop bits
2 stop bits
The parity field specifies the parity bit. The following constants are allowed:
No parity bit
Odd parity bit
Even parity bit
Mark (1) parity bit
Space (0) parity bit
The fifoTrigger field specifies the programmable fifo trigger level. It is an integer value which provides an indication to the driver as to how to configure the trigger level of the receive FIFO. When fifoTrigger is zero, the FIFO (if any) is disabled. When the programmable fifo trigger is not available on hardware, this field is ignored by the device driver.
Note that only the generic UART options can be dynamically configured via open. All other device-specific options can only be configured statically through the device node properties.
open keeps the modem control signals (data-set-ready and request-to-send) unchanged (that is, does not drop down the signals), and returns the initial state of modem status signals as the bit-mask of the following flags:
The clear-to-send modem status has been raised/dropped.
The data-set-ready modem status has been raised/dropped.
The data-carrier-detect modem status has been raised/dropped.
The ring-indicator modem status has been raised/dropped.
When a particular modem status is not supported by the UART device, neither the "UP" nor "DOWN" flag is returned. The open function returns the following results:
The UART line has been iniatlized successfully.
The UART cannot be initialized with the configuration provided (for example the baud rate specified is not supported).
open must be the first call issued to the device driver. When K_OK is returned, open puts the device into the interrupt masked state. In order to start the device (that is, to enable interrupts), the unmask down-call must be invoked.
mask
The mask function disables all device interrupts (input, output and special).
Arguments:
Specifies the UART device identifier.
Note that it is up to the client to disable preemption prior to the mask invocation in order to prevent the current thread being preempted while device interrupts are masked.
unmask
The unmask function enables all device interrupts (input, output and special).
Arguments:
Specifies the UART device identifier.
Typically, the mask / unmask pair would be used by the driver client to implement a critical section of code which must be synchronized with the call-back handlers. The mask / unmask pair must not be called by the call-back handlers. This is unnecessary because the interrupts are already masked when the call-back handlers are invoked. The mask / unmask pairs must not be nested.
transmit
The transmit function starts the given buffer transmission.
Arguments:
Specifies the UART device identifier.
Points to the first byte of the output buffer.
Specifies the output buffer size.
It returns immediately without waiting for the buffer transmission to be completed. The driver client is notified about the end of transmission via the txdone call-back handler. The driver client must not issue another transmit or txbreak request until the txdone call-back handler is invoked by the device driver. The transmit down-call must be issued in the masked state. In other words, it must be called from either a critical section protected by mask / unmask or a call-back handler.
abort
The abort function allows the driver client to interrupt the transmission in progress.
Arguments:
Specifies the UART device identifier.
If there is an output in progress, the device driver interrupts (aborts) it and invokes the txdone call-back handler with the UART_SIG_TX_ABORTED flag set. Typically, the abort service routine would be used by the client to implement flow control based on the CTS/RTS modem signals as well as on the XON/XOFF protocol. The abort down-call must be issued in the masked state. In other words, it must be called from either a critical section protected by mask / unmask or a call-back handler.
txbreak
The txbreak function starts the BREAK signal transmission.
Arguments:
Specifies the UART device identifier.
It returns immediately without waiting for the BREAK signal to be sent. The driver client is notified about the end of transmission by the txdone call-back handler with the UART_SIG_TX_BREAK flag set in the signals argument. The driver client must not issue another transmit or txbreak request until the txdone call-back handler is invoked by the device driver. The txbreak down-call must be issued in the masked state. In other words, it must be called from either a critical section protected by mask / unmask or a call-back handler.
control
The control function allows the driver client to raise/drop the modem control signals.
Arguments:
Specifies the UART device identifier.
Specifies the modem control signals to raise/drop.
A combination of the following flags may be specified:
Raise/drop the data-terminal-ready modem control signal
Raise/drop the request-to-send modem control signal
rxbuffer
The rxbuffer function allows the driver client to specify the buffer for received characters.
Arguments:
Specifies the UART device identifier.
Points to the first byte of the receive buffer.
Specifies the receive buffer size.
The driver handles a free position pointer inside the buffer. The pointer is initialized by rxbuffer and updated each time a character is put into the buffer. Typically, the driver invokes the receive call-back handler when the receive FIFO becomes empty. The count argument is passed to the receive handler specifying the number of received characters since the previous receive invocation.
When the receive buffer becomes full (that is, the last available position in the buffer has just been used) the receive call-back handler is invoked immediately with the UART_SIG_RX_BUF_FULL flag set in the signals argument. When a received character cannot be put into the buffer (there is no room) the receive call-back handler is invoked with the UART_SIG_RX_BUF_OVERRUN flag set in the signals argument.
When the receive buffer is not set at all or set to zero, the device driver ignores all input characters and does not invoke the receive handler when a character is received. The rxbuffer down-call must be issued in the masked state. In other words, it must be called from either a critical section protected by mask / unmask or a call-back handler.
close
The close down-call releases the serial line device and puts it in a hung state.
Arguments:
Specifies the UART device identifier.
The close function must be called in the masked state, that is, the mask down-call must be issued before the close one.
close must be the last call issued to the driver. In particular, the driver client must not invoke unmask after returning from close.
The driver client up-call handlers are specified by the UartCallBack structure and given to the device driver as an argument of open.
typedef struct { void (*txdone) (void* client_cookie, unsigned int count, unsigned int signals); void (*receive) (void* client_cookie, unsigned int count, unsigned int signals); } UartCallBack;
txdone
The txdone up-call notifies the driver client that the requested transmission (transmit or txbreak) is finished.
Arguments:
Is the client handle specified in open.
Specifies the number of transmitted characters.
Specifies whether or not the transmission has been aborted.
In the case of data transmission ( transmit ), the txdone up-call notifies the driver client that output is completed or has been interrupted by the abort down-call.
In the case of abort, the UART_SIG_TX_ABORTED flag is set in the signals argument. In both cases, the count argument specifies the number of transmitted characters.
In the case of a BREAK signal transmission ( txbreak ), the txdone up-call notifies the driver client that the BREAK signal has been sent. The UART_SIG_TX_BREAK flag is set in the signals argument. The txdone up-call makes it possible to issue another request ( transmit or txbreak ) to the device driver.
The txdone up-call handler is invoked in the masked state. Typically, it is called from interrupt level.
receive
The receive up-call notifies the driver client that count number of characters have been written to the receive buffer or/and some signals have occurred.
Arguments:
Is the client handle specified in open.
Specifies the number of received characters.
Specifies the received signals and/or error conditions.
The last character in the buffer was received with a parity error.
The last character in the buffer was received with a framing error.
Characters have been lost because of a FIFO overflow.
The receive buffer is full.
Characters have been lost because of the receive buffer overflow.
A BREAK signal has been received.
The clear-to-send modem status has been raised/dropped.
The data-set-ready modem status has been raised/dropped.
The data-carrier-detect modem status has been raised/dropped.
The ring-indicator modem status has been raised/dropped.
The receive up-call handler is invoked in the masked state. Typically, it is called from interrupt level.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
dtreeNodeRoot(9DKI), svDeviceRegister(9DKI), svDriverRegister(9DKI), svMemAlloc(9DKI), svTimeoutSet(9DKI), usecBusyWait(9DKI), DISABLE_PREEMPT(9DKI)
NAME | SYNOPSIS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO