| 1 | /*␊ |
| 2 | *Copyright (c) 2000 Apple Computer, Inc. All rights reserved.␊ |
| 3 | *␊ |
| 4 | *@APPLE_LICENSE_HEADER_START@␊ |
| 5 | *␊ |
| 6 | *The contents of this file constitute Original Code as defined in and␊ |
| 7 | *are subject to the Apple Public Source License Version 1.1 (the␊ |
| 8 | *"License"). You may not use this file except in compliance with the␊ |
| 9 | *License. Please obtain a copy of the License at␊ |
| 10 | *http://www.apple.com/publicsource and read it before using this file.␊ |
| 11 | *␊ |
| 12 | *This Original Code and all software distributed under the License are␊ |
| 13 | *distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER␊ |
| 14 | *EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,␊ |
| 15 | *INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,␊ |
| 16 | *FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the␊ |
| 17 | *License for the specific language governing rights and limitations␊ |
| 18 | *under the License.␊ |
| 19 | *␊ |
| 20 | *@APPLE_LICENSE_HEADER_END@␊ |
| 21 | */␊ |
| 22 | /*␊ |
| 23 | * IOSerialStreamSync.h␊ |
| 24 | *␊ |
| 25 | * 2000-10-21␉gvdl␉Initial real change to IOKit serial family.␊ |
| 26 | *␊ |
| 27 | */␊ |
| 28 | ␊ |
| 29 | #ifndef␉_SERIAL_IOSERIALSTREAMSYNC_H␊ |
| 30 | #define␉_SERIAL_IOSERIALSTREAMSYNC_H␊ |
| 31 | ␊ |
| 32 | #include <IOKit/IOService.h>␊ |
| 33 | ␊ |
| 34 | #ifdef __LP64__␊ |
| 35 | ␊ |
| 36 | #define PD_DATA_MASK 0x03U␊ |
| 37 | #define PD_DATA_VOID 0x00U␊ |
| 38 | #define PD_DATA_BYTE 0x01U␊ |
| 39 | #define PD_DATA_WORD 0x02U␊ |
| 40 | #define PD_DATA_LONG 0x03U␊ |
| 41 | ␊ |
| 42 | #else␊ |
| 43 | ␊ |
| 44 | #define PD_DATA_MASK 0x03UL␊ |
| 45 | #define PD_DATA_VOID 0x00UL␊ |
| 46 | #define PD_DATA_BYTE 0x01UL␊ |
| 47 | #define PD_DATA_WORD 0x02UL␊ |
| 48 | #define PD_DATA_LONG 0x03UL␊ |
| 49 | ␊ |
| 50 | #endif␊ |
| 51 | ␊ |
| 52 | #define PD_OP(x)␉((x) << 2)␊ |
| 53 | #define PD_E_MASK␉(~PD_DATA_MASK)␊ |
| 54 | ␊ |
| 55 | /* General Command & Status events */␊ |
| 56 | #define PD_E_EOQ␉␉(PD_DATA_VOID|PD_OP( 0))␉// Always nextEvent on empty queue␊ |
| 57 | #define PD_E_ACTIVE␉␉(PD_DATA_BYTE|PD_OP( 1))␉// BOOL start/shutdown chip␊ |
| 58 | ␊ |
| 59 | /* Queue management events - all units are multiples of characters␊ |
| 60 | *based on the current character size␊ |
| 61 | */␊ |
| 62 | #define PD_E_TXQ_SIZE ␉␉(PD_DATA_LONG|PD_OP( 2))␊ |
| 63 | #define PD_E_RXQ_SIZE␉␉(PD_DATA_LONG|PD_OP( 3))␊ |
| 64 | #define PD_E_TXQ_LOW_WATER␉(PD_DATA_LONG|PD_OP( 4))␊ |
| 65 | #define PD_E_RXQ_LOW_WATER␉(PD_DATA_LONG|PD_OP( 5))␊ |
| 66 | #define PD_E_TXQ_HIGH_WATER␉(PD_DATA_LONG|PD_OP( 6))␊ |
| 67 | #define PD_E_RXQ_HIGH_WATER␉(PD_DATA_LONG|PD_OP( 7))␊ |
| 68 | #define PD_E_TXQ_AVAILABLE␉(PD_DATA_LONG|PD_OP( 8))␊ |
| 69 | #define PD_E_RXQ_AVAILABLE␉(PD_DATA_LONG|PD_OP( 9))␊ |
| 70 | #define PD_E_TXQ_FLUSH ␉␉(PD_DATA_VOID|PD_OP(10))␊ |
| 71 | #define PD_E_RXQ_FLUSH␉␉(PD_DATA_LONG|PD_OP(11))␊ |
| 72 | ␊ |
| 73 | /* port & link characteristics - units are half bits */␊ |
| 74 | #define PD_E_DATA_RATE ␉␉(PD_DATA_LONG|PD_OP(12))␉// raw bits of symbols per second␊ |
| 75 | #define PD_E_RX_DATA_RATE␉(PD_DATA_LONG|PD_OP(13))␊ |
| 76 | #define PD_E_DATA_SIZE ␉␉(PD_DATA_LONG|PD_OP(14))␉// raw bits per symbol␊ |
| 77 | #define PD_E_RX_DATA_SIZE␉(PD_DATA_LONG|PD_OP(15))␊ |
| 78 | #define PD_E_DATA_INTEGRITY␉(PD_DATA_LONG|PD_OP(16))␉// parity or ECC method␊ |
| 79 | #define PD_E_RX_DATA_INTEGRITY␉(PD_DATA_LONG|PD_OP(17))␊ |
| 80 | #define PD_E_EXTERNAL_CLOCK_MODE (PD_DATA_LONG|PD_OP(28))␉// multiplier between clock and data rates␊ |
| 81 | ␊ |
| 82 | /* timeout events */␊ |
| 83 | #define PD_E_DELAY␉␉(PD_DATA_LONG|PD_OP(18))␉// inter-character delay (us)␊ |
| 84 | #define PD_E_DATA_LATENCY␉(PD_DATA_LONG|PD_OP(19))␉// A dequeueData Latency timeout␊ |
| 85 | ␉␉␉␉␉␉␉␉// rcs Secondary Timer mainly to fix performance ␊ |
| 86 | ␉␉␉␉␉␉␉␉// problems with MIDI and IRDA drivers.␊ |
| 87 | ␉␉␉␉␉␉␉␉// Midi and Irda drivers will issue an IOCTL␊ |
| 88 | ␉␉␉␉␉␉␉␉// call with this as the selector and␊ |
| 89 | ␉␉␉␉␉␉␉␉// the Data as the value they want the rate set␊ |
| 90 | ␉␉␉␉␉␉␉␉// to (Typically 1 for IrDA devices) ␊ |
| 91 | #define PD_E_FLOW_CONTROL (PD_DATA_LONG|PD_OP(20)) ␉// enable/disable each flow mechanism␊ |
| 92 | ␊ |
| 93 | /* I/O events */␊ |
| 94 | #define PD_E_VALID_DATA ␉(PD_DATA_VOID|PD_OP(21))␉// A valid frame was received␊ |
| 95 | #define PD_E_VALID_DATA_BYTE ␉(PD_DATA_BYTE|PD_E_VALID_DATA)␊ |
| 96 | #define PD_E_VALID_DATA_WORD ␉(PD_DATA_WORD|PD_E_VALID_DATA)␊ |
| 97 | #define PD_E_VALID_DATA_LONG ␉(PD_DATA_LONG|PD_E_VALID_DATA)␊ |
| 98 | ␊ |
| 99 | #define PD_E_SPECIAL␉␉(PD_DATA_VOID|PD_OP(22))␉// valid data received with 'special' value␊ |
| 100 | #define PD_E_SPECIAL_BYTE ␉(PD_DATA_BYTE|PD_E_SPECIAL)␊ |
| 101 | #define PD_E_SPECIAL_WORD ␉(PD_DATA_WORD|PD_E_SPECIAL)␊ |
| 102 | #define PD_E_SPECIAL_LONG ␉(PD_DATA_LONG|PD_E_SPECIAL)␊ |
| 103 | ␊ |
| 104 | #define PD_E_FRAMING_ERROR ␉(PD_DATA_VOID|PD_OP(23))␉// Failure occured assembling frame␊ |
| 105 | #define PD_E_FRAMING_BYTE ␉(PD_DATA_BYTE|PD_E_FRAMING_ERROR)␊ |
| 106 | #define PD_E_FRAMING_WORD ␉(PD_DATA_WORD|PD_E_FRAMING_ERROR)␊ |
| 107 | #define PD_E_FRAMING_LONG ␉(PD_DATA_LONG|PD_E_FRAMING_ERROR)␊ |
| 108 | ␊ |
| 109 | #define PD_E_INTEGRITY_ERROR ␉(PD_DATA_VOID|PD_OP(24))␉// An uncorrectable frame was received␊ |
| 110 | #define PD_E_INTEGRITY_BYTE ␉(PD_DATA_BYTE|PD_E_INTEGRITY_ERROR)␊ |
| 111 | #define PD_E_INTEGRITY_WORD ␉(PD_DATA_WORD|PD_E_INTEGRITY_ERROR)␊ |
| 112 | #define PD_E_INTEGRITY_LONG ␉(PD_DATA_LONG|PD_E_INTEGRITY_ERROR)␊ |
| 113 | ␊ |
| 114 | #define PD_E_INTEGRITY_WARNING ␉(PD_DATA_VOID|PD_OP(25))␉// A correctable frame was received␊ |
| 115 | #define PD_E_HW_OVERRUN_ERROR ␉(PD_DATA_VOID|PD_OP(26))␉// Hardware's buffer overflowed, data lost␊ |
| 116 | #define PD_E_SW_OVERRUN_ERROR ␉(PD_DATA_VOID|PD_OP(27))␉// Driver's buffer overflowed, data lost␊ |
| 117 | ␊ |
| 118 | /*␊ |
| 119 | *The variables below make up the bits returned␊ |
| 120 | *by the State methods:- getState, setState, watchState␊ |
| 121 | */␊ |
| 122 | #define PD_S_MASK␉␉0xffff0000UL␊ |
| 123 | #define PD_S_RX_OFFSET␉␉7␊ |
| 124 | ␊ |
| 125 | #define PD_S_ACQUIRED␉␉0x80000000UL␊ |
| 126 | #define PD_S_ACTIVE␉␉0x40000000UL␊ |
| 127 | ␊ |
| 128 | #define PD_S_TX_ENABLE␉␉0x20000000UL␊ |
| 129 | #define PD_S_TX_BUSY␉␉0x10000000UL␊ |
| 130 | #define PD_S_TX_EVENT ␉␉0x08000000UL␊ |
| 131 | #define PD_S_TXQ_EMPTY ␉␉0x04000000UL␊ |
| 132 | #define PD_S_TXQ_LOW_WATER ␉0x02000000UL␊ |
| 133 | #define PD_S_TXQ_HIGH_WATER ␉0x01000000UL␊ |
| 134 | #define PD_S_TXQ_FULL ␉␉0x00800000UL␊ |
| 135 | #define PD_S_TXQ_MASK␉␉( PD_S_TXQ_EMPTY | PD_S_TXQ_LOW_WATER \␊ |
| 136 | | PD_S_TXQ_FULL | PD_S_TXQ_HIGH_WATER )␊ |
| 137 | ␊ |
| 138 | #define PD_S_RX_ENABLE␉␉(PD_S_TX_ENABLE >> PD_S_RX_OFFSET)␊ |
| 139 | #define PD_S_RX_BUSY␉␉(PD_S_TX_BUSY >> PD_S_RX_OFFSET)␊ |
| 140 | #define PD_S_RX_EVENT␉␉(PD_S_TX_EVENT >> PD_S_RX_OFFSET)␊ |
| 141 | #define PD_S_RXQ_EMPTY ␉␉(PD_S_TXQ_EMPTY >> PD_S_RX_OFFSET)␊ |
| 142 | #define PD_S_RXQ_LOW_WATER␉(PD_S_TXQ_LOW_WATER >> PD_S_RX_OFFSET)␊ |
| 143 | #define PD_S_RXQ_HIGH_WATER␉(PD_S_TXQ_HIGH_WATER >> PD_S_RX_OFFSET)␊ |
| 144 | #define PD_S_RXQ_FULL ␉␉(PD_S_TXQ_FULL >> PD_S_RX_OFFSET)␊ |
| 145 | #define PD_S_RXQ_MASK␉␉(PD_S_TXQ_MASK >> PD_S_RX_OFFSET)␊ |
| 146 | ␊ |
| 147 | class IOSerialDriverSync;␊ |
| 148 | class IOSerialStreamSync : public IOService␊ |
| 149 | {␊ |
| 150 | OSDeclareDefaultStructors(IOSerialStreamSync);␊ |
| 151 | ␊ |
| 152 | protected:␊ |
| 153 | IOSerialDriverSync *fProvider;␊ |
| 154 | void *fRefCon;␊ |
| 155 | ␊ |
| 156 | public:␊ |
| 157 | /* acquire tests and sets the state of the port object. If the port was␊ |
| 158 | *available, then the state is set to busy, and kIOReturnSuccess is returned.␊ |
| 159 | *If the port was already busy and sleep is YES, then the thread will sleep␊ |
| 160 | *until the port is freed, then re-attempts the acquire. If the port was␊ |
| 161 | *already busy and sleep in NO, then kIOReturnExclusiveAccess is returned.␊ |
| 162 | */ ␊ |
| 163 | virtual IOReturn acquirePort(bool sleep);␊ |
| 164 | ␊ |
| 165 | /* release sets the state of the port object to available and wakes up any␊ |
| 166 | *threads sleeping for access to this port. It will return kIOReturnSuccess␊ |
| 167 | *if the port was in a busy state, and kIOReturnNotOpen if it was available.␊ |
| 168 | */␊ |
| 169 | virtual IOReturn releasePort();␊ |
| 170 | ␊ |
| 171 | /*␊ |
| 172 | *Set the state for the port device.␊ |
| 173 | */␊ |
| 174 | virtual IOReturn setState(UInt32 state, UInt32 mask);␊ |
| 175 | ␊ |
| 176 | /*␊ |
| 177 | *Get the state for the port device.␊ |
| 178 | */␊ |
| 179 | virtual UInt32 getState();␊ |
| 180 | ␊ |
| 181 | /*␊ |
| 182 | *Wait for the at least one of the state bits defined in mask to be equal␊ |
| 183 | *to the value defined in state.␊ |
| 184 | *Check on entry then sleep until necessary.␊ |
| 185 | */␊ |
| 186 | virtual IOReturn watchState(UInt32 *state, UInt32 mask);␊ |
| 187 | ␊ |
| 188 | /* nextEvent returns the type of the next event on the RX queue. If no␊ |
| 189 | *events are present on the RX queue, then EOQ is returned.␊ |
| 190 | */␊ |
| 191 | virtual UInt32 nextEvent();␊ |
| 192 | ␊ |
| 193 | /* executeEvent causes the specified event to be processed immediately.␊ |
| 194 | *This is primarily used for channel control commands like START & STOP␊ |
| 195 | */␊ |
| 196 | virtual IOReturn executeEvent(UInt32 event, UInt32 data);␊ |
| 197 | ␊ |
| 198 | /* requestEvent processes the specified event as an immediate request and␊ |
| 199 | *returns the results in data. This is primarily used for getting link␊ |
| 200 | *status information and verifying baud rate and such.␊ |
| 201 | */␊ |
| 202 | virtual IOReturn requestEvent(UInt32 event, UInt32 *data);␊ |
| 203 | ␊ |
| 204 | /* enqueueEvent will place the specified event into the TX queue. The␊ |
| 205 | *sleep argument allows the caller to specify the enqueueEvent's␊ |
| 206 | *behaviour when the TX queue is full. If sleep is true, then this␊ |
| 207 | *method will sleep until the event is enqueued. If sleep is false,␊ |
| 208 | *then enqueueEvent will immediatly return kIOReturnNoResources.␊ |
| 209 | */␊ |
| 210 | virtual IOReturn enqueueEvent(UInt32 event, UInt32 data, bool sleep);␊ |
| 211 | ␊ |
| 212 | /* dequeueEvent will remove the oldest event from the RX queue and return␊ |
| 213 | *it in event & data. The sleep argument defines the behaviour if the RX␊ |
| 214 | *queue is empty. If sleep is true, then this method will sleep until an␊ |
| 215 | *event is available. If sleep is false, then an EOQ event will be␊ |
| 216 | *returned. In either case kIOReturnSuccess is returned.␊ |
| 217 | */␊ |
| 218 | virtual IOReturn dequeueEvent(UInt32 *event, UInt32 *data, bool sleep);␊ |
| 219 | ␊ |
| 220 | /* enqueueData will attempt to copy data from the specified buffer to the␊ |
| 221 | *TX queue as a sequence of VALID_DATA events. The argument bufferSize␊ |
| 222 | *specifies the number of bytes to be sent. The actual number of bytes␊ |
| 223 | *transferred is returned in transferCount. If sleep is true, then this␊ |
| 224 | *method will sleep until all bytes can be transferred. If sleep is␊ |
| 225 | *false, then as many bytes as possible will be copied to the TX queue.␊ |
| 226 | */␊ |
| 227 | virtual IOReturn enqueueData(UInt8 *buffer, UInt32 size, UInt32 *count, bool sleep );␊ |
| 228 | ␊ |
| 229 | /* dequeueData will attempt to copy data from the RX queue to the specified␊ |
| 230 | *buffer. No more than bufferSize VALID_DATA events will be transferred.␊ |
| 231 | *In other words, copying will continue until either a non-data event is␊ |
| 232 | *encountered or the transfer buffer is full. The actual number of bytes␊ |
| 233 | *transferred is returned in transferCount.␊ |
| 234 | *␊ |
| 235 | *The sleep semantics of this method are slightly more complicated than␊ |
| 236 | *other methods in this API: Basically, this method will continue to␊ |
| 237 | *sleep until either minCount characters have been received or a non␊ |
| 238 | *data event is next in the RX queue. If minCount is zero, then this␊ |
| 239 | *method never sleeps and will return immediatly if the queue is empty.␊ |
| 240 | *␊ |
| 241 | *The latency parameter specifies the maximum amount of time that should␊ |
| 242 | *pass after the first character is available before the routine returns.␊ |
| 243 | *This allows the caller to specify a 'packet' timeout. The unit of the␊ |
| 244 | *latency parameter is microseconds, though the exact delay may vary␊ |
| 245 | *depending on the granularity of the timeout services available to the␊ |
| 246 | *driver.␊ |
| 247 | */␊ |
| 248 | virtual IOReturn dequeueData(UInt8 *buffer, UInt32 size, UInt32 *count, UInt32 min);␊ |
| 249 | ␊ |
| 250 | /*␉Internal for IOSerialDriver only */␊ |
| 251 | virtual bool init(OSDictionary *dictionary = 0, void *refCon = 0);␊ |
| 252 | virtual bool attach(IOService *provider);␊ |
| 253 | void *getRefCon() const { return fRefCon; }␊ |
| 254 | ␊ |
| 255 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 0);␊ |
| 256 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 1);␊ |
| 257 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 2);␊ |
| 258 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 3);␊ |
| 259 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 4);␊ |
| 260 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 5);␊ |
| 261 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 6);␊ |
| 262 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 7);␊ |
| 263 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 8);␊ |
| 264 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 9);␊ |
| 265 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 10);␊ |
| 266 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 11);␊ |
| 267 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 12);␊ |
| 268 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 13);␊ |
| 269 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 14);␊ |
| 270 | OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 15);␊ |
| 271 | };␊ |
| 272 | ␊ |
| 273 | #endif /* !_SERIAL_IOSERIALSTREAMSYNC_H */␊ |
| 274 | ␊ |
| 275 | ␊ |
| 276 | |
