Palm OS SDK Reference

59 Serial and Virtual Drivers

This chapter provides reference material for the new serial manager device driver API: Driver Data Structures Driver Constants Serial Driver-Defined Functions Virtual Driver-Defined Functions Serial Manager Queue Functions
The header file SerialSdrv.h declares the serial driver API and the file SerialVdrv.h declares the virtual driver API. Both types of drivers also use the SerialDrvr.h header file. For more information on writing device drivers for the new serial manager, see section Writing a Serial or Virtual Device Driver in the chapter Serial Communication in the Palm OS Programmer's Companion.

Driver Data Structures

DrvrInfoType

The DrvrInfoType structure defines information about the serial hardware. It is passed to and filled in by the DrvEntryPoint function for a serial driver and the DrvEntryPoint for a virtual driver.

typedef struct {
UInt32 drvrID;
UInt32 drvrVersion;
UInt32 maxBaudRate;
UInt32 handshakeThreshold;
UInt32 portFlags;
Char * portDesc;
DrvrIRQEnum irqType;
UInt8 reserved;
} DrvrInfoType;

Value Descriptions


`drvrID`	4-character creator type, such as 'u328'
`drvrVersion`	Version of code that works for this hardware. For this release, all serial drivers should return version `kDrvrVersion` here.
`maxBaudRate`	Maximum baud rate supported by this hardware
`handshakeThreshold`	Baud rate at which hardware handshaking is necessary to be used
`portFlags`	Bit flags denoting features of this hardware. The flags are described in Port Feature Constants.
`portDesc`	Pointer to null-terminated string describing this hardware. This string appears in the Connection panel to describe the port to the user (only if the `portCncMgrVisible` bit in `portFlags` is set). Can be `NULL` if the driver contains a resource (of type 'tSTR' and id `kPortDescStrID`) that supplies this string.
`irqType`	IRQ line being used for this hardware. Specify one of the `DrvrIRQEnum` values. For a virtual driver, specify `drvrIRQNone`.
`reserved`	Reserved for future use.

DrvrRcvQType

The DrvrRcvQType structure defines the virtual driver receive buffer and function pointers to functions that access and save data to the buffer. A pointer to this structure is passed to the VdrvOpen function. The DrvrHWRcvQPtr type defines a pointer to a DrvrRcvQType structure.

typedef struct DrvrRcvQType {
void *rcvQ;
WriteByteProcPtr qWriteByte;
WriteBlockProcPtr qWriteBlock;
GetSizeProcPtr qGetSize;
GetSpaceProcPtr qGetSpace;
} DrvrRcvQType;

typedef DrvrRcvQType *DrvrHWRcvQPtr;

Value Descriptions


`rcvQ`	Pointer to the receive buffer.
`qWriteByte`	Function pointer to a function that the virtual driver can use to write one byte to the new serial manager's receive queue. See the WriteByte function.
`qWriteBlock`	Function pointer to a function that the virtual driver can use to write a block of bytes to the new serial manager's receive queue. See the WriteBlock function.
`qGetSize`	Function pointer to a function that the virtual driver can use to get the total size of the new serial manager's receive queue. See the GetSize function.
`qGetSpace`	Function pointer to a function that the virtual driver can use to get the available space in the new serial manager's receive queue. See the GetSpace function.

DrvrStatusEnum

The DdrvStatusEnum enumerated type specifies serial status bit flags. Return these enumerated types from the SdrvStatus and VdrvStatus calls.

typedef enum DrvrStatusEnum {
drvrStatusCtsOn = 0x0001,
drvrStatusRtsOn = 0x0002,
drvrStatusDsrOn = 0x0004,
drvrStatusTxFifoFull = 0x0008,
drvrStatusTxFifoEmpty = 0x0010,
drvrStatusBreakAsserted = 0x0020,
drvrStatusDataReady = 0x0040, // For polling mode debugger only
drvrStatusLineErr = 0x0080 // For polling mode debugger only
} DrvrStatusEnum;

Value Descriptions


`drvrStatusCtsOn`	Set if CTS line is active.
`drvrStatusRtsOn`	Set if RTS line is active.
`drvrStatusDsrOn`	Set if DSR is on.
`drvrStatusTxFifoFull`	Set if transmit FIFO is full; cleared if FIFO has space.
`drvrStatusTxFifoEmpty`	Set if transmit FIFO is empty.
`drvrStatusBreakAsserted`	Set if sending break characters is enabled.
`drvrStatusDataReady`	Used by debugger only.
`drvrStatusLineErr`	Used by debugger only.

SdrvAPIType

The SdrvAPIType structure defines the function pointers to the required serial driver functions. When passed a pointer to this structure in the DrvEntryPoint function, that function must fill in the pointers to the serial driver functions appropriately.

typedef struct {
SdrvOpenProcPtr drvOpen;
SdrvCloseProcPtr drvClose;
SdrvControlProcPtr drvControl;
SdrvStatusProcPtr drvStatus;
SdrvReadCharProcPtr drvReadChar;
SdrvWriteCharProcPtr drvWriteChar;
} SdrvAPIType;

Value Descriptions


`drvOpen`	Pointer to the driver open function.
`drvClose`	Pointer to the driver close function.
`drvControl`	Pointer to the driver control function.
`drvStatus`	Pointer to the driver status function.
`drvReadChar`	Pointer to the driver read character function.
`drvWriteChar`	Pointer to the driver write character function.

SdrvCtlOpCodeEnum

The SdrvCtlOpCodeEnum enumerated type specifies a serial control operation. You should handle each of these enumerated types when passed for the controlCode parameter to the SdrvControl call.

typedef enum SdrvCtlOpCodeEnum {
    sdrvOpCodeNoOp = 0,
    sdrvOpCodeSetBaudRate = 0x1000,
    sdrvOpCodeSetSettingsFlags,
    sdrvOpCodeClearErr,
    sdrvOpCodeEnableUART,
    sdrvOpCodeDisableUART,
    sdrvOpCodeEnableUARTInterrupts,
    sdrvOpCodeDisableUARTInterrupts,
    sdrvOpCodeSetSleepMode,
    sdrvOpCodeSetWakeupMode,
    sdrvOpCodeRxEnable,
    sdrvOpCodeRxDisable,
    sdrvOpCodeLineEnable,
    sdrvOpCodeFIFOCount,
    sdrvOpCodeEnableIRDA,
    sdrvOpCodeDisableIRDA,
    sdrvOpCodeStartBreak,
    sdrvOpCodeStopBreak,
    sdrvOpCodeStartLoopback,
    sdrvOpCodeStopLoopback,
    sdrvOpCodeFlushTxFIFO,
    sdrvOpCodeFlushRxFIFO,
    sdrvOpCodeGetOptTransmitSize,
    sdrvOpCodeEnableRTS,
    sdrvOpCodeDisableRTS,
    sdrvOpCodeUserDef = 0x2000
} SdrvCtlOpCodeEnum;

Value Descriptions


`sdvrOpCodeSetBaudRate`	Sets the baud rate for the UART.
`sdvrOpCodeSetSettingsFlags`	Sets the data transmission options. The bit flags are described in Serial Settings Constants.
`sdvrOpCodeClearError`	Clears the hardware error state.
`sdvrOpCodeEnableUart`	Powers-up the UART and the line-drivers.
`sdvrOpCodeDisableUART`	Powers-down the UART and the line drivers.
`sdvrOpCodeEnableUARTInterrupts`	Enables the appropriate UART receive interrupts.
`sdvrOpCodeDisableUARTInterrupt` s	Disables all UART interrupts.
`sdvrOpCodeSetSleepMode`	Puts the UART in sleep mode.
`sdvrOpCodeSetWakeupMode`	Wakes up the UART from sleep mode.
`sdvrOpCodeRxEnable`	Enables the receive FIFO, enables UART interrupts, and does whatever else is necessary to allow the UART to receive data.
`sdvrOpCodeRxDisable`	Disables the receive FIFO and UART interrupts and does whatever is needed to prevent the UART from receiving data.
`sdvrOpCodeLineEnable`	Enables the main serial line driver for the UART.
`sdvrOpCodeFIFOCount`	Returns the number of bytes currently in the FIFO (or best estimate).
`sdvrOpCodeEnableIRDA`	Enable the IRDA mode and power up the IR line drivers.
`sdvrOpCodeDisableIRDA`	Disable the IRDA mode and disable the IR line drivers.
`sdvrOpCodeStartBreak`	Sends a break character or enables the sending of break characters.
`sdvrOpCodeStopBreak`	Stops sending break characters.
`sdvrOpCodeStartLoopback`	Places the UART in loopback mode.
`sdvrOpCodeStopLoopback`	Stops loopback mode.
`SdrvOpCodeFlushTxFIFO`	Flushes the contents of the transmit FIFO.
`sdrvOpCodeFlushRxFIFO`	Flushes the contents of the receive FIFO.
`sdrvOpCodeGetOptTransmitSize`	Returns the optimum buffer size for sending data or returns 0 to specify any buffer size is acceptable.
`sdrvOpCodeEnableRTS`	Asserts the RTS line.
`sdrvOpCodeDisableRTS`	Deasserts the RTS line.
`sdvrOpCodeUserDef`	User defined function invoked via SrmControl.

VdrvAPIType

The VdrvAPIType structure defines function pointers to the required virtual driver functions. When passed a pointer to this structure in the DrvEntryPoint function, that function must fill in the pointers to the virtual driver functions appropriately.

typedef struct {
VdrvOpenProcPtr drvOpen;
VdrvCloseProcPtr drvClose;
VdrvControlProcPtr drvControl;
VdrvStatusProcPtr drvStatus;
VdrvReadProcPtr drvRead;
VdrvWriteProcPtr drvWrite;
} VdrvAPIType;

Value Descriptions


`drvOpen`	Pointer to the driver open function.
`drvClose`	Pointer to the driver close function.
`drvControl`	Pointer to the driver control function.
`drvStatus`	Pointer to the driver status function.
`drvRead`	Pointer to the driver read function.
`drvWrite`	Pointer to the driver write function.

VdrvCtlOpCodeEnum

The VdrvCtlOpCodeEnum enumerated type specifies a serial control operation. You should handle each of these enumerated types when passed for the controlCode parameter to the VdrvControl call.

typedef enum VdrvCtlOpCodeEnum {
    vdrvOpCodeNoOp = 0,
    vdrvOpCodeSetBaudRate = 0x1000,
    vdrvOpCodeSetSettingsFlags,
    vdrvOpCodeSetCtsTimeout,
    vdrvOpCodeClearErr,
    vdrvOpCodeSetSleepMode,
    vdrvOpCodeSetWakeupMode,
    vdrvOpCodeFIFOCount,
    vdrvOpCodeStartBreak,
    vdrvOpCodeStopBreak,
    vdrvOpCodeStartLoopback,
    vdrvOpCodeStopLoopback,
    vdrvOpCodeFlushTxFIFO,
    vdrvOpCodeFlushRxFIFO,
    vdrvOpCodeSendBufferedData,
    vdrvOpCodeRcvCheckIdle,
    vdrvOpCodeEmuSetBlockingHook,
    vdrvOpCodeGetOptTransmitSize,
    vdrvOpCodeGetMaxRcvBlockSize,
    vdrvOpCodeNotifyBytesReadFromQ,
    vdrvOpCodeUserDef = 0x2000
} VdrvCtlOpCodeEnum;

Value Descriptions


`vdvrOpCodeSetBaudRate`	Sets the baud rate.
`vdvrOpCodeSetSettingsFlags`	Sets the data transmission options. The bit flags are described in Serial Settings Constants.
`vdrvOpCodeSetCtsTimeout`	Hardware handshake timeout.
`vdvrOpCodeClearError`	Clears the hardware error state.
`vdvrOpCodeSetSleepMode`	Puts the port in sleep mode (not typically used for virtual drivers).
`vdvrOpCodeSetWakeupMode`	Wakes up the port from sleep mode (not typically used for virtual drivers).
`vdvrOpCodeFIFOCount`	Returns the number of bytes currently in the FIFO (or best estimate).
`vdvrOpCodeStartBreak`	Sends a break character or enables the sending of break characters.
`vdvrOpCodeStopBreak`	Stops sending break characters.
`vdvrOpCodeStartLoopback`	Starts loopback mode (not typically used for virtual drivers).
`vdvrOpCodeStopLoopback`	Stops loopback mode (not typically used for virtual drivers).
`vdrvOpCodeFlushTxFIFO`	Flushes the contents of the transmit FIFO.
`vdrvOpCodeFlushRxFIFO`	Flushes the contents of the receive FIFO.
`vdrvOpCodeSendBufferedData`	Notifies virtual device to send any buffered data it has not emptied from its internal buffers.
`vdrvOpCodeRcvCheckIdle`	Called periodically to allow virtual device time to check if there is data to be received. Because virtual devices execute in the same thread as applications, they can be prevented from handling notifications of received data.
`vdrvOpCodeEmuSetBlockingHook`	Special opCode for the Simulator.
`vdrvOpCodeGetOptTransmitSize`	Returns the optimum buffer size for sending data or returns 0 to specify any buffer size is acceptable.
`vdrvOpCodeGetMaxRcvBlockSize`	Returns the maximum receive block size that the serial manager should request from the virtual device. Can be used to implement flow control.
`vdrvOpCodeNotifyBytesReadFromQ`	Tells the virtual device that some number of bytes have been read from the receive queue by the client application. Can be used to implement flow control.
`vdvrOpCodeUserDef`	User defined function invoked via SrmControl.

Driver Constants

Port Feature Constants

These flag constants describe serial hardware capabilities. portPhysicalPort Should be set for a physical port, unset for a virtual port portRS232Capable Set if this hardware has a RS-232 port portIRDACapable Set if this hardware has an IR port and supports IRDA mode portCradlePort Set if this hardware controls the cradle port portExternalPort Set if this hardware port is external or on a memory card portModemPort Set if this hardware communicates with a modem portCncMgrVisible Set if this serial port's name is to be displayed in the Connection panel portPrivateUse Set if this driver is for special software and not general applications.

`portPhysicalPort`	Should be set for a physical port, unset for a virtual port
`portRS232Capable`	Set if this hardware has a RS-232 port
`portIRDACapable`	Set if this hardware has an IR port and supports IRDA mode
`portCradlePort`	Set if this hardware controls the cradle port
`portExternalPort`	Set if this hardware port is external or on a memory card
`portModemPort`	Set if this hardware communicates with a modem
`portCncMgrVisible`	Set if this serial port's name is to be displayed in the Connection panel
`portPrivateUse`	Set if this driver is for special software and not general applications.

Serial Driver-Defined Functions

The functions in this section must be defined by your serial driver.

DrvEntryPoint

Purpose

Entry point for the serial driver.

Prototype

Err DrvEntryPoint(DrvrEntryOpCodeEnum opCode, void * uartData)

Parameters

-> opCode Entry function code.

<-> uartData Pointer to data specific to the opCode.

Result


0	No error.
-1	The opCode is invalid or the hardware could not be found.

Comments

This functions serves a dual purpose based on the value of the opCode parameter. The two possible codes are drvrEntryGetUartFeatures and drvrEntryGetDrvrFuncts.
DrvEntryPoint is called with the drvrEntryGetUartFeatures code when the new serial manager is installed into the system at boot time and is looking for all UART hardware currently connected to the device. When this opCode is set, the uartData pointer points to a DrvrInfoType structure. This function does not allocate the structure, it just fills in the fields with information.
This function should check to make sure the hardware exists in the current system. If the hardware cannot be found, the function should leave the DrvrInfoType struct untouched and return a -1 error.
The driver needs to supply a string that describes the port it manages. This string is displayed to the user in the Connection panel and is returned by the SrmGetDeviceInfo function. To set this string, copy it into the portDesc field of the DrvrInfoType structure. Alternatively, you can supply this string in a driver resource of type 'tSTR' and id kPortDescStrID.
DrvEntryPoint is called with the drvrEntryGetDrvrFuncts code when a serial port is opened. The uartData pointer points to a SdrvAPIType structure and DrvEntryPoint must fill in the fields of this structure with appropriate function pointers.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvClose

Purpose

Handles all activities needed to power-down the UART.

Prototype

Err SdrvClose(SdrvDataPtr drvrDataP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

Result


0	No error.

Comments

This function should disable all UART interrupts for the Dragonball processor as well as for the UART, place the UART in sleep mode, power down the transceiver, and do whatever other necessary tasks there may be. Additionally, this function should remove the interrupt handler installed by SdrvOpen.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvControl

Purpose

Extends the SrmControl function to the level of the hardware.

Prototype

Err *SdrvControl(SdrvDataPtr drvrDataP, SdrvCtlOpCodeEnum controlCode, void * controlDataP, UInt16 * controlDataLenP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

-> controlCode Control function opCode. One of the opCodes listed in the SdrvCtlOpCodeEnum type.

<-> controlDataP Pointer to data for the specified control function.

<-> controlDataLenP Pointer to length of control data being passed in or out.

Result


0	No error.
`serErrNotSupported`	`controlCode` not supported.
`serErrBadParam`	`controlDataP` or `controlDataLenP` is bad.

Comments

This function should support the opCodes listed in the SdrvCtlOpCodeEnum type. If this function does not support an opCode, it must return the serErrNotSupported error code for that opCode.
Table 59.1 shows what is passed for the controlDataP and controlDataLenP parameters for each of the control codes that use them. Control codes not listed do not use these parameters.

Table 59.1 SdrvControl Parameters

sdvrOpCodeSetBaudRate -> controlDataP = Pointer to Int32 (baud rate), -> controlDataLenP = Pointer to sizeof(Int32).

sdvrOpCodeSetSettingsFlags -> controlDataP = Pointer to UInt32 (bitfield; see Serial Settings Constants) -> controlDataLenP = Pointer to sizeof(UInt32)

sdvrOpCodeFIFOCount -> controlDataP = Pointer to Int16, which contains the number of bytes in the FIFO. -> controlDataLenP = Pointer to sizeof(Int16).

sdrvOpCodeGetOptTransmitSize <- controlDataP = Pointer to Int32, <- controlDataLenP = Pointer to sizeof(Int32). Return the optimum buffer size for sending data, or 0 to specify any buffer size is acceptable.

sdvrOpCodeUserDef <-> controlDataP = Pointer from SrmControl (user-defined data), <-> controlDataLenP = Pointer to sizeof(Int32).

**Table 59.1 SdrvControl Parameters**
`sdvrOpCodeSetBaudRate`	-> `controlDataP` = Pointer to `Int32` (baud rate), -> `controlDataLenP` = Pointer to `sizeof(Int32)`.
`sdvrOpCodeSetSettingsFlags`	-> controlDataP = Pointer to `UInt32` (bitfield; see Serial Settings Constants) -> controlDataLenP = Pointer to `sizeof(UInt32)`
`sdvrOpCodeFIFOCount`	-> controlDataP = Pointer to `Int16`, which contains the number of bytes in the FIFO. -> controlDataLenP = Pointer to `sizeof(Int16)`.
`sdrvOpCodeGetOptTransmitSize`	<- controlDataP = Pointer to `Int32`, <- controlDataLenP = Pointer to `sizeof(Int32)`. Return the optimum buffer size for sending data, or 0 to specify any buffer size is acceptable.
`sdvrOpCodeUserDef`	<-> `controlDataP` = Pointer from SrmControl (user-defined data), <-> `controlDataLenP` = Pointer to `sizeof(Int32)`.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvISP

Purpose

An interrupt service routine called when a hardware interrupt is generated on the IRQ line associated with the serial hardware.

Prototype

asm Boolean SdrvISP(UInt32 param: __A0):__D0

Parameters

A0 = param Pointer to the driver's private global area.

Result

D0 returns a Boolean value. Return true if this UART has data that needs to be read; return false if no other interrupt service is needed.

Comments

This function can retrieve its globals from the low-memory global they were saved in (via the pointer in A0) and then must determine if the interrupt is for this particular serial hardware. If so, it must call the saveDataProc function (passed into SdrvOpen) with the portP pointer as the parameter. The saveDataProc function, supplied by the new serial manager, handles reading the data from the UART by calling the SdrvReadChar function.
The SdrvISP function must be installed in the appropriate IRQ handler by the SdrvOpen routine.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvOpen

Purpose

Initializes the serial hardware to send and receive data.

Prototype

Err SdrvOpen(SdrvDataPtr* drvrDataP, UInt32 baudRate, void * portP, SerialMgrISPProcPtr saveDataProc)

Parameters

<-> drvrDataP Pointer to a pointer to the driver's private global area (allocated by this function).

-> baudRate Initial baud rate setting.

-> portP Pointer to the open port data.

-> saveDataProc Pointer to the function where data received by interrupt is to be saved. The typedef for this function is shown in the Comments section.

Result


0	No error.

Comments

Here is the typedef for the saveDataProc function:

typedef void (*SerialMgrISPProcPtr)(void * portP:__A0)

To accomplish serial hardware initialization, SdrvOpen must perform the following tasks: Allocate global data needed by the driver. There is a low memory global (GIrqNGlobalsP) for every IRQ line in the system. At open time, a serial driver must save its global data in this low memory global because when the interrupt is called there is no way to get the globals through the driver data parameter that the serial manager normally supplies. Save the portP and saveDataProc parameters passed to SdrvOpen in the global variable structure, because they are needed when the SdrvISP function is called. When the interrupt routine subsequently gets called, the driver gets access to the low memory globals which contain the saveDataProc function and the portP pointer. This pointer is passed into the new serial manager, which then calls the driver SdrvReadChar function in order to read all the bytes and fill its queue. Save the pointer to the globals in the appropriate low memory global variable for the IRQ line the device is using (for example, a device which uses IRQ3 would use the GIrq3GlobalsP). You can find the IRQ global variables defined in the header file globals.h. Save the pointer to the globals in the drvrDataP parameter passed into the SdrvOpen function. This private global data pointer is passed to every serial driver function so they all have access to the global data. Patch out the appropriate interrupt handler trap and replace it with the serial driver's ISP function (SdrvISP). For example, the system trap to be patched for IRQ3 is called sysTrapHwrIRQ3Handler (see SysTraps.h). Be sure to save the old interrupt handler to be re-installed when DrvClose is called. Here is an example of how to do this:

oldIntHandler = SysGetTrapAddress(sysTrapHwrIRQ3Handler);

SysSetTrapAddress(sysTrapHwrIRQ3Handler, SdrvISP);

If there is another serial device sharing the same IRQ line, you must tail-patch the IRQ handler rather than replace it. In other words, you must call the previously installed handler after your own handler executes. Set up and open the hardware to its default state.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvReadChar

Purpose

Reads a byte (if available) from the receive FIFO of the UART.

Prototype

asm UInt16 SdrvReadChar(SdrvDataPtr drvrDataP:__A0):__D0

Parameters

A1 = drvrDataP Pointer to the driver's private global area.

Result

D0 returns an Int16 value. The returned 16-bit word contains the data byte read from the hardware in the low-order byte. If there is an error, the error code is returned in the low-order byte and the error flag ($80) is set in the high-order byte.

Comments

This function should be written in 68K assembly language for speed, but can be written in a higher-level language as long as the register usage for the parameters and return values is obeyed. If this function is too slow, hardware overruns may occur.
This function is responsible for translating break, framing, parity, and overrun errors back to the calling function. If an error is received by the hardware, the high-order byte of the return value should be set to $80 to mark the low-order byte as an error code and not a readable byte. The error code returned in the low-order byte of D0 should be translated into one of the following four serial manager error codes: serLineErrorBreak, serLineErrorFraming, serLineErrorParity, or serLineErrorHWOverrun.
SdrvReadChar executes during interrupt time, and cannot call any OS functions that are normally not allowed to be called during this time. All registers needed for this function should be saved onto the stack (except for D0). The A1 register must not be changed on exit.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvStatus

Purpose

Returns UART status.

Prototype

UInt16 SdrvStatus(SdrvDataPtr drvrDataP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

Result

An unsigned long bitfield denoting the status of the UART. The individual bit flags are described in the DrvrStatusEnum type.

Comments

The drvrStatusCtsOn flag should be set if the UART's CTS line is active. The drvrStatusRtsOn flag should be set if the RTS line for the UART is currently high. The drvrStatusDsrOn flag should be set if DSR is turned on. Again, this may not be supported on all UARTs and should be set or cleared based on the type of hardware used. The drvrStatusTxFifoFull flag is set if the transmit FIFO for the hardware has no available space to receive more data and the flag should be cleared if the transmit FIFO does have available space. And the drvrStatusBreakAsserted flag should be set if the UART currently has sending break characters enabled.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

SdrvWriteChar

Purpose

Writes a byte to the appropriate UART register for transmission.

Prototype

Err SdrvWriteChar(SdrvDataPtr drvrDataP, UInt8 aChar)

Parameters

-> drvrDataP Pointer to the driver's private global area.

-> aChar Byte of data to be written to the UART.

Result


0	No error.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Virtual Driver-Defined Functions

The functions in this section must be defined by your virtual driver.

DrvEntryPoint

Purpose

Entry point for the virtual driver.

Prototype

Err DrvEntryPoint(DrvrEntryOpCodeEnum opCode, void * uartData)

Parameters

-> opCode Entry function code.

<-> uartData Pointer to data specific to the opCode.

Result


0	No error.
-1	The opCode is invalid or the hardware could not be found.

Comments

This functions serves a dual purpose based on the value of the opCode parameter. The two possible codes are drvrEntryGetUartFeatures and drvrEntryGetDrvrFuncts.
DrvEntryPoint is called with the drvrEntryGetUartFeatures code when the new serial manager is installed into the system at boot time and is looking for all installed drivers. When this opCode is set, the uartData pointer points to a DrvrInfoType structure. This function does not allocate the structure, it just fills in the fields with information.
This function should check to make sure the associated serial device can operate under the current OS and system settings. If the hardware cannot be found, the function should leave the DrvrInfoType struct untouched and return a -1 error.
The driver needs to supply a string that describes the port it manages. This string is displayed to the user in the Connection panel and is returned by the SrmGetDeviceInfo function. To set this string, copy it into the portDesc field of the DrvrInfoType structure. Alternatively, you can supply this string in a driver resource of type 'tSTR' and id kPortDescStrID.
DrvEntryPoint is called with the drvrEntryGetDrvrFuncts code when a virtual port is opened. The uartData pointer points to a VdrvAPIType structure and DrvEntryPoint must fill in the fields of this structure with appropriate function pointers.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

VdrvClose

Purpose

Handles all activities needed to close the virtual device.

Prototype

Err VdrvClose(VdrvDataPtr drvrDataP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

Result


0	No error.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

VdrvControl

Purpose

Extends the SrmControl function to the level of the virtual device.

Prototype

Err *VdrvControl(VdrvDataPtr drvrDataP, VdrvCtlOpCodeEnum controlCode, void * controlDataP, UInt16 * controlDataLenP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

-> controlCode Control function opCode. One of the opCodes listed in the VdrvCtlOpCodeEnum type.

<-> controlDataP Pointer to data for the specified control function.

<-> controlDataLenP Pointer to length of control data being passed in or out.

Result


0	No error.
`serErrNotSupported`	`controlCode` not supported.
`serErrBadParam`	`controlDataP` or `ControlDataLenP` is bad.

Comments

This function should support the opCodes listed in the VdrvCtlOpCodeEnum type. If this function does not support an opCode, it must return the serErrNotSupported error code for that opCode.
Table 59.2 shows what is passed for the controlDataP and controlDataLenP parameters for each of the control codes that use them. Control codes not listed do not use these parameters.

Table 59.2 VdrvControl Parameters


`vdvrOpCodeSetBaudRate`	-> `controlDataP` = Pointer to `Int32` (baud rate), -> `controlDataLenP` = Pointer to `sizeof(Int32)`.
`vdvrOpCodeSetSettingsFlags`	-> controlDataP = Pointer to `UInt32` (bitfield; see Serial Settings Constants) -> controlDataLenP = Pointer to `sizeof(UInt32)`
`vdvrOpCodeFIFOCount`	-> controlDataP = Pointer to `Int16`, which contains the number of bytes in the FIFO. -> controlDataLenP = Pointer to `sizeof(Int16)`.
`vdrvOpCodeGetOptTransmitSize`	<- controlDataP = Pointer to `Int32` (buffer size), <- controlDataLenP = Pointer to `sizeof(Int32)`. Return the optimum buffer size for sending data, or 0 to specify any buffer size is acceptable.
`vdrvOpCodeGetMaxRcvBlockSize`	<- controlDataP = Pointer to `Int32` (block size), <- controlDataLenP = Pointer to `sizeof(Int32)`. Return the maximum block size that the serial manager should request from the virtual device.
`vdrvOpCodeNotifyBytesReadFromQ`	-> controlDataP = Pointer to `Int32` (number of bytes read), -> controlDataLenP = Pointer to `sizeof(Int32)`.
`vdvrOpCodeUserDef`	<-> `controlDataP` = Pointer from SrmControl (user-defined data), <-> `controlDataLenP` = Pointer to `sizeof(Int32)`.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

VdrvOpen

Purpose

Initializes the virtual device to begin communication.

Prototype

Err VdrvOpen(VdrvDataPtr* drvrDataP, UInt32 baudRate, DrvrHWRcvQPtr rcvQP)

Parameters

<-> drvrDataP Pointer to a pointer to the driver's private global area (allocated by this function). A pointer to this private global area is passed to the other virtual driver functions.

-> baudRate Initial baud rate setting.

-> rcvQP Pointer to the driver's receive queue buffer structure. For details on the fields, see DrvrRcvQType.

Result


0	No error.

Comments

This function must allocate and initialize any global variables (and pass back a pointer to a pointer to them in drvrDataP), do any set-up necessary for communicating with other software, and save the rcvQP pointer since it will need the functions and pointers to structures enclosed within to be able to save received data into the new serial manager's receive queue.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

VdrvStatus

Purpose

Returns virtual device status.

Prototype

UInt16 VdrvStatus(VdrvDataPtr drvrDataP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

Result

An unsigned long bitfield denoting the status of the virtual device, but only if the virtual device is emulating hardware. The individual bit flags are described in the DrvrStatusEnum type.

Comments

Generally, status is returned only to the client application using the virtual device. The new serial manager does not use status information from virtual devices.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

VdrvWrite

Purpose

Writes a block of bytes.

Prototype

UInt32 VdrvWrite(VdrvDataPtr drvrDataP, void * bufP, UInt32 size, Err* errP)

Parameters

-> drvrDataP Pointer to the driver's private global area.

-> bufP Pointer to buffer containing the data to be written to the virtual device.

-> size Number of bytes in the buffer bufP.

<- errP Pointer to an error code resulting from the operation. Zero is returned if there is no error.

Result

Returns the actual number of bytes written.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Serial Manager Queue Functions

The functions in this section are supplied by the new serial manager to the virtual driver via the DrvrRcvQType passed to the VdrvOpen function.

GetSize

Purpose

Returns the total size of the new serial manager's receive queue.

Prototype

typedef UInt32 (*GetSizeProcPtr)(void * theQ)

Parameters

-> theQ Pointer to the receive queue.

Result

Size in bytes of the new serial manager's receive queue.

Comments

This function is useful for implementing flow control.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

GetSpace

Purpose

Returns the available space in the new serial manager's receive queue.

Prototype

typedef UInt32 (*GetSpaceProcPtr)(void * theQ)

Parameters

-> theQ Pointer to the receive queue.

Result

Size in bytes of the available space in the new serial manager's receive queue.

Comments

This function is useful for implementing flow control.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

WriteBlock

Purpose

Writes a block of bytes to the new serial manager's receive queue.

Prototype

typedef Err (*WriteBlockProcPtr)(void * theQ, UInt8 * bufP, UInt16 size, UInt16 lineErrs)

Parameters

-> theQ Pointer to the receive queue.

-> bufP Pointer to the buffer holding bytes for the WriteBlock function.

-> size Size of bufP.

-> lineErrs Any serial line errors received should be reported here.

Result


0	No error.
`serErrLineErr`	There was a software overrun line error.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

WriteByte

Purpose

Writes one byte to the new serial manager's receive queue.

Prototype

typedef Err (*WriteByteProcPtr)(void * theQ, UInt8 theByte, UInt16 lineErrs)

Parameters

-> theQ Pointer to the receive queue.

-> theByte The byte to be written to the queue.

-> lineErrs Any serial line errors received should be reported here.

Result


0	No error.
`serErrLineErr`	There was a software overrun line error.

Compatibility

Implemented only if New Serial Manager Feature Set is present.

Palm OS SDK Reference

This is page 61 of 85 in this book

Palm Computing Platform Development Zone

59 Serial and Virtual Drivers

Driver Data Structures

DrvrInfoType

Value Descriptions

DrvrRcvQType

Value Descriptions

DrvrStatusEnum

Value Descriptions

SdrvAPIType

Value Descriptions

SdrvCtlOpCodeEnum

Value Descriptions

VdrvAPIType

Value Descriptions

VdrvCtlOpCodeEnum

Value Descriptions

Driver Constants

Port Feature Constants

Serial Driver-Defined Functions

DrvEntryPoint

Purpose

Prototype

Parameters

Result

Comments

Compatibility

SdrvClose

Purpose

Prototype

Parameters

Result

Comments

Compatibility

SdrvControl

Purpose

Prototype

Parameters

Result

Comments

Table 59.1 SdrvControl Parameters

Compatibility

SdrvISP

Purpose

Prototype

Parameters

Result

Comments

Compatibility

See Also

SdrvOpen

Purpose

Prototype

Parameters

Result

Comments

Compatibility

See Also

SdrvReadChar

Purpose

Prototype

Parameters

Result

Comments

Compatibility

SdrvStatus

Purpose

Prototype

Parameters

Result

Comments

Compatibility

SdrvWriteChar

Purpose

Prototype

Parameters

Result

Compatibility

Virtual Driver-Defined Functions

DrvEntryPoint

Purpose