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 147class IOSerialDriverSync; 148class IOSerialStreamSync : public IOService 149{ 150 OSDeclareDefaultStructors(IOSerialStreamSync); 151 152protected: 153 IOSerialDriverSync *fProvider; 154 void *fRefCon; 155 156public: 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 255OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 0); 256OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 1); 257OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 2); 258OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 3); 259OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 4); 260OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 5); 261OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 6); 262OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 7); 263OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 8); 264OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 9); 265OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 10); 266OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 11); 267OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 12); 268OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 13); 269OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 14); 270OSMetaClassDeclareReservedUnused(IOSerialStreamSync, 15); 271}; 272 273#endif /* !_SERIAL_IOSERIALSTREAMSYNC_H */ 274 275 276