/******************************************************************* * Pilot Software * * Copyright (c) 1994-1997, Palm Computing Inc., All Rights Reserved * *------------------------------------------------------------------- * FileName: * SerialMgr.h * * Description: * Include file for Serial manager * * History: * 2/7/95 Created by Ron Marianetti * 7/6/95 vmk added serDefaultSettings * *******************************************************************/ #ifndef __SERIAL_MGR_H #define __SERIAL_MGR_H // Pilot common definitions #include #include /******************************************************************** * Serial Manager Errors * the constant serErrorClass is defined in SystemMgr.h ********************************************************************/ #pragma mark -Error Codes- #define serErrBadParam (serErrorClass | 1) #define serErrBadPort (serErrorClass | 2) #define serErrNoMem (serErrorClass | 3) #define serErrBadConnID (serErrorClass | 4) #define serErrTimeOut (serErrorClass | 5) #define serErrLineErr (serErrorClass | 6) #define serErrAlreadyOpen (serErrorClass | 7) #define serErrStillOpen (serErrorClass | 8) #define serErrNotOpen (serErrorClass | 9) #define serErrNotSupported (serErrorClass | 10) // functionality not supported /******************************************************************** * Serial Settings Descriptor ********************************************************************/ #pragma mark -Configuration Settings- typedef struct SerSettingsType { ULong baudRate; // baud rate ULong flags; // miscellaneous settings Long ctsTimeout; // max # of ticks to wait for CTS to become asserted // before transmitting; used only when // configured with serSettingsFlagCTSAutoM. } SerSettingsType; typedef SerSettingsType* SerSettingsPtr; #define serSettingsFlagStopBitsM 0x00000001 // mask for stop bits field #define serSettingsFlagStopBits1 0x00000000 // 1 stop bits #define serSettingsFlagStopBits2 0x00000001 // 2 stop bits #define serSettingsFlagParityOnM 0x00000002 // mask for parity on #define serSettingsFlagParityEvenM 0x00000004 // mask for parity even #define serSettingsFlagXonXoffM 0x00000008 // mask for Xon/Xoff flow control #define serSettingsFlagRTSAutoM 0x00000010 // mask for RTS rcv flow control #define serSettingsFlagCTSAutoM 0x00000020 // mask for CTS xmit flow control #define serSettingsFlagBitsPerCharM 0x000000C0 // mask for bits/char #define serSettingsFlagBitsPerChar5 0x00000000 // 5 bits/char #define serSettingsFlagBitsPerChar6 0x00000040 // 6 bits/char #define serSettingsFlagBitsPerChar7 0x00000080 // 7 bits/char #define serSettingsFlagBitsPerChar8 0x000000C0 // 8 bits/char // Default settings #define serDefaultSettings (serSettingsFlagBitsPerChar8 | \ serSettingsFlagStopBits1 | \ serSettingsFlagRTSAutoM) #define serDefaultCTSTimeout (5*sysTicksPerSecond); // // mask values for the lineErrors from SerGetStatus // #pragma mark -Line Errors- #define serLineErrorParity 0x0001 // parity error #define serLineErrorHWOverrun 0x0002 // HW overrun #define serLineErrorFraming 0x0004 // framing error #define serLineErrorBreak 0x0008 // break signal asserted #define serLineErrorHShake 0x0010 // line hand-shake error #define serLineErrorSWOverrun 0x0020 // HW overrun /******************************************************************** * Type of a wakeup handler procedure which can be installed through the * SerSetWakeupHandler() call. ********************************************************************/ typedef void (*SerWakeupHandler) (DWord refCon); /******************************************************************** * Type of an emulator-mode only blocking hook routine installed via * SerControl function serCtlEmuSetBlockingHook. This is supported only * under emulation mode. The argument to the function is the value * specified in the SerCallbackEntryType structure. The callback returns * true if serial manager should abort the current blocking action, such * as when an app quit event has been received; under normal conditions, * the callback returns true. The callback can additionally process * events to enable user interaction with the UI. ********************************************************************/ typedef Boolean (*SerBlockingHookHandler) (DWord userRef); /******************************************************************** * Serial Library Control Enumerations (Pilot 2.0) ********************************************************************/ #pragma mark -Control Enumerations- /******************************************************************** * Structure for specifying callback routines. ********************************************************************/ typedef struct SerCallbackEntryType { Ptr funcP; // function pointer DWord userRef; // ref value to pass to callback } SerCallbackEntryType; typedef SerCallbackEntryType* SerCallbackEntryPtr; // v2.0 extension // DOLATER... add DTR control and status typedef enum SerCtlEnum { serCtlFirstReserved = 0, // RESERVE 0 serCtlStartBreak, // turn RS232 break signal on: // users are responsible for ensuring that the break is set // long enough to genearate a valie BREAK! // valueP = 0, valueLenP = 0 serCtlStopBreak, // turn RS232 break signal off: // valueP = 0, valueLenP = 0 serCtlBreakStatus, // Get RS232 break signal status(on or off): // valueP = ptr to Word for returning status(0 = off, !0 = on) // *valueLenP = sizeof(Word) serCtlStartLocalLoopback, // Start local loopback test // valueP = 0, valueLenP = 0 serCtlStopLocalLoopback, // Stop local loopback test // valueP = 0, valueLenP = 0 serCtlMaxBaud, // Get maximum supported baud rate: // valueP = ptr to DWord for returned baud // *valueLenP = sizeof(DWord) serCtlHandshakeThreshold, // retrieve HW handshake threshold; this is the maximum baud rate // which does not require hardware handshaking // valueP = ptr to DWord for returned baud // *valueLenP = sizeof(DWord) serCtlEmuSetBlockingHook, // Set a blocking hook routine FOR EMULATION // MODE ONLY - NOT SUPPORTED ON THE PILOT //PASS: // valueP = ptr to SerCallbackEntryType // *valueLenP = sizeof(SerCallbackEntryType) //RETURNS: // the old settings in the first argument serCtlLAST // ADD NEW ENTRIES BEFORE THIS ONE } SerCtlEnum; /******************************************************************** * Serial Library Routines * These are define as external calls only under emulation mode or * under native mode from the module that actually installs the trap * vectors ********************************************************************/ #pragma mark -API Functions- #ifdef __cplusplus extern "C" { #endif // Used by mac applications to map the pilot serial port to a particular // macintosh port. UInt SerSetMapPort( UInt pilotPort, UInt macPort ); // Acquires and opens a serial port with given baud and default settings. Err SerOpen(UInt refNum, UInt port, ULong baud) SYS_TRAP(sysLibTrapOpen); // Used by debugger to re-initialize serial port if necessary Err SerDbgAssureOpen(UInt refNum, UInt port, ULong baud); // Closes the serial connection previously opened with SerOpen. Err SerClose(UInt refNum) SYS_TRAP(sysLibTrapClose); // Puts serial library to sleep Err SerSleep(UInt refNum) SYS_TRAP(sysLibTrapSleep); // Wake Serial library Err SerWake(UInt refNum) SYS_TRAP(sysLibTrapWake); // Get attributes of the serial connection Err SerGetSettings(UInt refNum, SerSettingsPtr settingsP) SYS_TRAP(sysLibTrapCustom); // Set attributes of the serial connection Err SerSetSettings(UInt refNum, SerSettingsPtr settingsP) SYS_TRAP(sysLibTrapCustom+1); // Return status of serial connection Word SerGetStatus(UInt refNum, BooleanPtr ctsOnP, BooleanPtr dsrOnP) SYS_TRAP(sysLibTrapCustom+2); // Reset error condition of serial connection Err SerClearErr(UInt refNum) SYS_TRAP(sysLibTrapCustom+3); // Sends a buffer of data (may queue it up and return). Err SerSend10(UInt refNum, VoidPtr bufP, ULong size) SYS_TRAP(sysLibTrapCustom+4); // Waits until the serial transmit buffer empties. Err SerSendWait(UInt refNum, Long timeout) SYS_TRAP(sysLibTrapCustom+5); // Returns how many characters are left in the send queue waiting // for transmission Err SerSendCheck(UInt refNum, ULongPtr numBytesP) SYS_TRAP(sysLibTrapCustom+6); // Flushes the data out of the transmit buffer Err SerSendFlush(UInt refNum) SYS_TRAP(sysLibTrapCustom+7); // Receives a buffer of data of the given size. Err SerReceive10(UInt refNum, VoidPtr bufP, ULong bytes, Long timeout) SYS_TRAP(sysLibTrapCustom+8); // Waits for at least 'bytes' bytes of data to arrive at the serial input. // but does not read them in Err SerReceiveWait(UInt refNum, ULong bytes, Long timeout) SYS_TRAP(sysLibTrapCustom+9); // Returns how many characters are in the receive queue Err SerReceiveCheck(UInt refNum, ULongPtr numBytesP) SYS_TRAP(sysLibTrapCustom+10); // Flushes any data coming into the serial port, discarding the data. void SerReceiveFlush(UInt refNum, Long timeout) SYS_TRAP(sysLibTrapCustom+11); // Specify a new input buffer. To restore the original buffer, pass // bufSize = 0. Err SerSetReceiveBuffer(UInt refNum, VoidPtr bufP, UInt bufSize) SYS_TRAP(sysLibTrapCustom+12); // The receive character interrupt service routine, called by kernel when // a UART interrupt is detected. DOLATER... generalize ISP's for multiple Serial libs Boolean SerReceiveISP(void) SYS_TRAP(sysTrapSerReceiveISP); // "Back Door" into the serial receive queue. Used by applications (like TCP Media layers) // that need faster access to received characters Err SerReceiveWindowOpen(UInt refNum, BytePtr* bufPP, DWordPtr sizeP) SYS_TRAP(sysLibTrapCustom+13); Err SerReceiveWindowClose(UInt refNum, DWord bytesPulled) SYS_TRAP(sysLibTrapCustom+14); // Can be called by applications that need an alternate wakeup mechanism // when characters get enqueued by the interrupt routine. Err SerSetWakeupHandler(UInt refNum, SerWakeupHandler procP, DWord refCon) SYS_TRAP(sysLibTrapCustom+15); // Called to prime wakeup handler Err SerPrimeWakeupHandler(UInt refNum, Word minBytes) SYS_TRAP(sysLibTrapCustom+16); // Called to prime wakeup handler // (v2.0 extension) Err SerControl(UInt refNum, Word op, VoidPtr valueP, WordPtr valueLenP) SYS_TRAP(sysLibTrapCustom+17); // Sends a buffer of data (may queue it up and return). ULong SerSend(UInt refNum, VoidPtr bufP, ULong count, Err* errP) SYS_TRAP(sysLibTrapCustom+18); // Receives a buffer of data of the given size. ULong SerReceive(UInt refNum, VoidPtr bufP, ULong count, Long timeout, Err* errP) SYS_TRAP(sysLibTrapCustom+19); #ifdef __cplusplus } #endif #endif //__SERIAL_MGR_H