Chameleon

Chameleon Svn Source Tree

Root/trunk/i386/include/IOKit/graphics/IOFramebuffer.h

1/*␊
2 * Copyright (c) 1998-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#ifndef _IOKIT_IOFRAMEBUFFER_H␊
24#define _IOKIT_IOFRAMEBUFFER_H␊
25␊
26#include <IOKit/IOService.h>␊
27#include <IOKit/IOInterruptEventSource.h>␊
28#include <IOKit/graphics/IOGraphicsDevice.h>␊
29#include <IOKit/graphics/IOFramebufferShared.h>␊
30#include <IOKit/IOLib.h>␊
31␊
32class IOFramebuffer;␊
33class IOBufferMemoryDescriptor;␊
34␊
35typedef void (*CursorBlitProc)(␊
36 IOFramebuffer * inst,␊
37 void * shmem,␊
38 volatile unsigned char *vramPtr,␊
39 unsigned int cursStart,␊
40 unsigned int vramRow,␊
41 unsigned int cursRow,␊
42 int width,␊
43 int height );␊
44␊
45typedef void (*CursorRemoveProc)(␊
46 IOFramebuffer * inst,␊
47 void * shmem,␊
48 volatile unsigned char *vramPtr,␊
49 unsigned int vramRow,␊
50 int width,␊
51 int height );␊
52␊
53␊
54typedef void * IOFBCursorRef;␊
55␊
56struct IOFBCursorControlCallouts {␊
57 IOReturn (*setCursorImage) (void * self, void * ref,␊
58 IOHardwareCursorDescriptor * description, IOFBCursorRef cursorImage);␊
59 IOReturn (*setCursorState) (void * self, void * ref,␊
60 SInt32 x, SInt32 y, bool visible);␊
61 UInt32 reserved[30];␊
62};␊
63typedef struct IOFBCursorControlCallouts IOFBCursorControlCallouts;␊
64␊
65struct IOFBCursorControlAttribute {␊
66 void * self;␊
67 void * ref;␊
68 const IOFBCursorControlCallouts * callouts;␊
69 UInt32 reserved[29];␊
70};␊
71typedef struct IOFBCursorControlAttribute IOFBCursorControlAttribute;␊
72␊
73// clock & data values␊
74enum {␊
75 kIODDCLow = 0,␊
76 kIODDCHigh = 1,␊
77 kIODDCTristate = 2␊
78};␊
79// ddcBlockType constants␊
80enum {␊
81 // EDID block type.␊
82 kIODDCBlockTypeEDID = 0␊
83};␊
84␊
85// ddcFlags constants␊
86enum {␊
87 // Force a new read of the EDID.␊
88 kIODDCForceRead = 0x00000001␊
89};␊
90␊
91enum {␊
92 kDisabledInterruptState = 0,␊
93 kEnabledInterruptState = 1␊
94};␊
95␊
96typedef void (*IOFBInterruptProc)( OSObject * target, void * ref );␊
97␊
98␊
99typedef IOReturn (*IOFramebufferNotificationHandler)␊
100 (OSObject * self, void * ref,␊
101 IOFramebuffer * framebuffer, IOIndex event,␊
102 void * info);␊
103␊
104// IOFramebufferNotificationHandler events␊
105enum {␊
106 kIOFBNotifyDisplayModeWillChange = 1,␊
107 kIOFBNotifyDisplayModeDidChange = 2,␊
108␊
109 kIOFBNotifyWillSleep = 3,␊
110 kIOFBNotifyDidWake = 4,␊
111␊
112 kIOFBNotifyDidPowerOff = 5,␊
113 kIOFBNotifyWillPowerOn = 6,␊
114␊
115 kIOFBNotifyDidSleep = kIOFBNotifyDidPowerOff,␊
116 kIOFBNotifyWillWake = kIOFBNotifyWillPowerOn,␊
117␊
118 kIOFBNotifyWillPowerOff = 7,␊
119 kIOFBNotifyDidPowerOn = 8,␊
120␊
121 kIOFBNotifyWillChangeSpeed = 9,␊
122 kIOFBNotifyDidChangeSpeed = 10,␊
123␊
124 kIOFBNotifyClamshellChange = 20,␊
125␊
126 kIOFBNotifyCaptureChange = 30,␊
127␊
128 kIOFBNotifyOnlineChange = 40,␊
129␊
130 kIOFBNotifyDisplayDimsChange = 50,␊
131␊
132 kIOFBNotifyProbed = 60,␊
133␊
134 kIOFBNotifyVRAMReady = 70,␊
135␊
136 kIOFBNotifyWillNotify = 80,␊
137 kIOFBNotifyDidNotify = 81,␊
138};␊
139␊
140struct IOFramebufferNotificationNotify␊
141{␊
142␉IOIndex event;␊
143␉void * info;␊
144};␊
145␊
146enum {␊
147 kFBDisplayUsablePowerState = 0x80000000,␊
148 kFBDisplayPowerStateMask = 0x0000ffff␊
149};␊
150␊
151#define kIOFBDependentIDKey "IOFBDependentID"␊
152#define kIOFBDependentIndexKey "IOFBDependentIndex"␊
153␊
154struct StdFBShmem_t;␊
155class IOFramebufferUserClient;␊
156class IODisplay;␊
157␊
158/*! @class IOFramebuffer : public IOGraphicsDevice␊
159 @abstract The base class for graphics devices to be made available as part of the desktop.␊
160 @discussion The IOFramebuffer base class defines APIs used to publish a linear framebuffer device. Device driver writers should subclass this class to provide a X native driver. Mac OS X will also utilize 'ndrv' drivers via a subclass of IOFramebuffer IONDRVFramebuffer that does not require device driver writers to provide a X native driver.␊
161 ␊
162 There are no in kernel clients of IOFramebuffer aside from rudimentary console and panic UI supported by the IOFramebuffer class. The IOFramebuffer class provides the IOUserClient implementation to allow the CoreGraphics server to provide the user accessible interface to all displays on a Mac OS X system, and this is further layered underneath application frameworks. Device driver writers should not need any knowledge of this part of the interfaces. Similarly the instance variables of IOFramebuffer are mostly used for cursor rendering which is handled by the IOFramebuffer class, and should be avoided by subclass implementors. Only IOFramebuffer methods with header documentation in this header are designed for subclasses to implement.␊
163␊
164 IOFramebuffer provides simple dumb framebuffer operation - accceleration for 2D, 3D and video may be provided by a separate implementation of the IOAccelerator class.␊
165*/␊
166␊
167class IOFramebuffer : public IOGraphicsDevice␊
168{␊
169 friend class IOFramebufferUserClient;␊
170 friend class IOFramebufferSharedUserClient;␊
171 friend class IOFramebufferParameterHandler;␊
172 friend class IODisplay;␊
173␊
174 OSDeclareDefaultStructors(IOFramebuffer)␊
175␊
176protected:␊
177/*! @struct ExpansionData␊
178 @discussion This structure will be used to expand the capablilties of this class in the future.␊
179 */ ␊
180 struct ExpansionData { };␊
181␊
182/*! @var reserved␊
183 Reserved for future use. (Internal use only) */␊
184 ExpansionData * reserved;␊
185␊
186private:␊
187␊
188protected:␊
189 StdFBShmem_t * priv;␊
190 int shmemClientVersion;␊
191 IOBufferMemoryDescriptor * sharedCursor;␊
192␊
193 union {␊
194 struct {␊
195 /* Mapping tables used in cursor drawing to 5-5-5 displays. */␊
196 unsigned char * _bm34To35SampleTable;␊
197 unsigned char * _bm35To34SampleTable;␊
198 /* Mapping tables used in cursor drawing to 8-bit RGB displays. */␊
199 unsigned int * _bm256To38SampleTable;␊
200 unsigned char * _bm38To256SampleTable;␊
201 } t;␊
202 UInt8 * tables[ 4 ];␊
203 } colorConvert;␊
204 ␊
205 /* cursor blitting vars */␊
206 CursorBlitProc cursorBlitProc;␊
207 CursorRemoveProc cursorRemoveProc;␊
208␊
209 IOGSize maxCursorSize;␊
210 void * _IOFramebuffer_reservedE[7];␊
211 const char * thisName;␊
212 volatile unsigned char * cursorSave;␊
213 unsigned int white;␊
214␊
215 IOGPoint nextCursorLoc;␊
216 int nextCursorFrame;␊
217 SInt32 connectChange;␊
218 semaphore_t vblSemaphore;␊
219␊
220 /* memory ranges */␊
221 volatile unsigned char * frameBuffer;␊
222 unsigned int totalWidth;␊
223 unsigned int rowBytes;␊
224 unsigned int bytesPerPixel;␊
225␊
226 IOMemoryMap * vramMap;␊
227 IOByteCount vramMapOffset;␊
228 OSArray * userAccessRanges;␊
229 unsigned int suspended:1;␊
230 unsigned int captured:1;␊
231 unsigned int sleepConnectCheck:1;␊
232 unsigned int messaged:1;␊
233 unsigned int cursorEnable:1;␊
234 unsigned int _IOFramebuffer_reservedC:27;␊
235 IOFramebuffer * nextDependent;␊
236 OSSet * fbNotifications;␊
237␊
238 class IOFramebufferUserClient * serverConnect;␊
239 class IOFramebufferSharedUserClient * sharedConnect;␊
240␊
241 unsigned int opened:1;␊
242 unsigned int dead:1;␊
243 unsigned int configPending:1;␊
244 unsigned int serverNotified:1;␊
245 unsigned int serverState:1;␊
246 unsigned int serverPendingAck:1;␊
247 unsigned int isUsable:1;␊
248 unsigned int mirrored:1;␊
249 unsigned int pendingPowerState:4;␊
250 unsigned int pendingPowerChange:1;␊
251 unsigned int pagingState:1;␊
252 unsigned int mirrorPrimary:1;␊
253 unsigned int mirrorSWCursor:1;␊
254␊
255 bool clutValid;␊
256 bool currentMono;␊
257 bool needCursorService;␊
258 bool haveVBLService;␊
259 bool haveHWCursor;␊
260 bool hwCursorLoaded;␊
261␊
262 void * serverMsg;␊
263 IOInterruptEventSource * deferredEvents;␊
264␊
265 /* Reserved for future expansion. */␊
266 int _IOFramebuffer_reserved[5];␊
267␊
268private:␊
269 struct IOFramebufferPrivate * __private;␊
270␊
271public:␊
272/*! @function doI2CRequest␊
273 @abstract Carry out an I2C request.␊
274 @discussion IOFramebuffer subclasses may optionally implement this method to perform I2C bus requests on one of the buses they support. Alternatively they may implement the setDDCClock(), setDDCData(), readDDCClock(), readDDCData() methods and respond from getAttributeForConnection() to the kConnectionSupportsLLDDCSense attribute with success, in which case IOFramebuffer::doI2CRequest() will carry out a software implementation of I2C using the low level routines and conforming to the timing constraints passed in the timing parameter. Subclasses may pass timing parameters tuned for the specific bus, otherwise VESA DDC defaults will apply.␊
275 @timing event Subclasses may pass timing parameters tuned for the specific bus, otherwise if NULL, VESA DDC defaults will apply.␊
276 @param request An IOI2CRequest structure. The request should be carried out synchronously if the completion routine is NULL, otherwise it may optionally be carried out asynchronously. The completion routine should be called if supplied.␊
277 @result an IOReturn code. If kIOReturnSuccces, the result of the transaction is returned in the requests result field.␊
278*/␊
279 virtual IOReturn doI2CRequest( UInt32 bus, struct IOI2CBusTiming * timing, struct IOI2CRequest * request );␊
280␊
281private:␊
282 OSMetaClassDeclareReservedUsed(IOFramebuffer, 0);␊
283␊
284 OSMetaClassDeclareReservedUnused(IOFramebuffer, 1);␊
285 OSMetaClassDeclareReservedUnused(IOFramebuffer, 2);␊
286 OSMetaClassDeclareReservedUnused(IOFramebuffer, 3);␊
287 OSMetaClassDeclareReservedUnused(IOFramebuffer, 4);␊
288 OSMetaClassDeclareReservedUnused(IOFramebuffer, 5);␊
289 OSMetaClassDeclareReservedUnused(IOFramebuffer, 6);␊
290 OSMetaClassDeclareReservedUnused(IOFramebuffer, 7);␊
291 OSMetaClassDeclareReservedUnused(IOFramebuffer, 8);␊
292 OSMetaClassDeclareReservedUnused(IOFramebuffer, 9);␊
293 OSMetaClassDeclareReservedUnused(IOFramebuffer, 10);␊
294 OSMetaClassDeclareReservedUnused(IOFramebuffer, 11);␊
295 OSMetaClassDeclareReservedUnused(IOFramebuffer, 12);␊
296 OSMetaClassDeclareReservedUnused(IOFramebuffer, 13);␊
297 OSMetaClassDeclareReservedUnused(IOFramebuffer, 14);␊
298 OSMetaClassDeclareReservedUnused(IOFramebuffer, 15);␊
299 OSMetaClassDeclareReservedUnused(IOFramebuffer, 16);␊
300 OSMetaClassDeclareReservedUnused(IOFramebuffer, 17);␊
301 OSMetaClassDeclareReservedUnused(IOFramebuffer, 18);␊
302 OSMetaClassDeclareReservedUnused(IOFramebuffer, 19);␊
303 OSMetaClassDeclareReservedUnused(IOFramebuffer, 20);␊
304 OSMetaClassDeclareReservedUnused(IOFramebuffer, 21);␊
305 OSMetaClassDeclareReservedUnused(IOFramebuffer, 22);␊
306 OSMetaClassDeclareReservedUnused(IOFramebuffer, 23);␊
307 OSMetaClassDeclareReservedUnused(IOFramebuffer, 24);␊
308 OSMetaClassDeclareReservedUnused(IOFramebuffer, 25);␊
309 OSMetaClassDeclareReservedUnused(IOFramebuffer, 26);␊
310 OSMetaClassDeclareReservedUnused(IOFramebuffer, 27);␊
311 OSMetaClassDeclareReservedUnused(IOFramebuffer, 28);␊
312 OSMetaClassDeclareReservedUnused(IOFramebuffer, 29);␊
313 OSMetaClassDeclareReservedUnused(IOFramebuffer, 30);␊
314 OSMetaClassDeclareReservedUnused(IOFramebuffer, 31);␊
315␊
316␊
317public:␊
318 static void initialize();␊
319␊
320 virtual bool requestTerminate( IOService * provider, IOOptionBits options );␊
321 virtual IOService * probe( IOService * provider, SInt32 * score );␊
322 virtual bool start( IOService * provider );␊
323 virtual void stop( IOService * provider );␊
324 virtual void free();␊
325 virtual IOWorkLoop * getWorkLoop() const;␊
326␊
327 IOWorkLoop * getGraphicsSystemWorkLoop() const;␊
328 IOWorkLoop * getControllerWorkLoop() const;␊
329␊
330 virtual IOReturn requestProbe( IOOptionBits options );␊
331␊
332 virtual IOReturn powerStateWillChangeTo ( IOPMPowerFlags, unsigned long, IOService* );␊
333 virtual IOReturn powerStateDidChangeTo ( IOPMPowerFlags, unsigned long, IOService* );␊
334 virtual IOReturn setPowerState( unsigned long powerStateOrdinal, IOService * device);␊
335 virtual IOReturn setAggressiveness( unsigned long type, unsigned long newLevel );␊
336 virtual IOReturn getAggressiveness( unsigned long type, unsigned long * currentLevel );␊
337 virtual IOReturn newUserClient( task_t owningTask,␊
338 void * security_id,␊
339 UInt32 type,␊
340 IOUserClient ** handler );␊
341 virtual IOReturn callPlatformFunction( const OSSymbol * functionName,␊
342 bool waitForFunction,␊
343 void *p1, void *p2,␊
344 void *p3, void *p4 );␊
345␊
346 virtual void hideCursor( void );␊
347 virtual void showCursor( IOGPoint * cursorLoc, int frame );␊
348 virtual void moveCursor( IOGPoint * cursorLoc, int frame );␊
349 // virtual␊
350 void resetCursor( void );␊
351␊
352 virtual void getVBLTime( AbsoluteTime * time, AbsoluteTime * delta );␊
353␊
354 virtual void getBoundingRect ( IOGBounds ** bounds );␊
355␊
356 virtual IOReturn open( void );␊
357 ␊
358 virtual void close( void );␊
359␊
360 virtual bool isConsoleDevice( void );␊
361␊
362 virtual IOReturn setupForCurrentConfig( void );␊
363␊
364 virtual bool serializeInfo( OSSerialize * s );␊
365 virtual bool setNumber( OSDictionary * dict, const char * key,␊
366 UInt32 number );␊
367␊
368 IONotifier * addFramebufferNotification(␊
369 IOFramebufferNotificationHandler handler,␊
370 OSObject * self, void * ref);␊
371␊
372/*! @function getApertureRange␊
373 @abstract Return reference to IODeviceMemory object representing memory range of framebuffer.␊
374 @discussion IOFramebuffer subclasses must implement this method to describe the memory used by the framebuffer in the current mode. The OS will map this memory range into user space for client access - the range should only include vram memory not hardware registers.␊
375 @param aperture The system will only access the aperture kIOFBSystemAperture.␊
376 @result an IODeviceMemory instance. A reference will be consumed by the caller for each call of this method - the implementatation should create a new instance of IODeviceMemory for each call, or return one instance with a retain for each call.␊
377*/␊
378␊
379 virtual IODeviceMemory * getApertureRange( IOPixelAperture aperture ) = 0;␊
380␊
381/*! @function getVRAMRange␊
382 @abstract Return reference to IODeviceMemory object representing memory range of all the cards vram.␊
383 @discussion IOFramebuffer subclasses should implement this method to describe all the vram memory available on the card. The OS will map this memory range into user space for client access - the range should only include vram memory not hardware registers.␊
384 @result an IODeviceMemory instance. A reference will be consumed by the caller for each call of this method - the implementatation should create a new instance of IODeviceMemory for each call, or return one instance with a retain for each call.␊
385*/␊
386␊
387 virtual IODeviceMemory * getVRAMRange( void );␊
388␊
389protected:␊
390␊
391/*! @function handleEvent␊
392 @abstract Notify IOFramebuffer superclass code of events.␊
393 @discussion IOFramebuffer subclasses should call this IOFramebuffer method on certain power state changes.␊
394 @param event The event that has occurred:<br>␊
395 kIOFBNotifyWillPowerOff call before entering a state other than the maximum.<br>␊
396 kIOFBNotifyDidPowerOn call after entering the maximum power state.<br>␊
397 kIOFBNotifyWillPowerOff call before entering a state other than the maximum.<br>␊
398 kIOFBNotifyDidPowerOn call after entering a state other than the maximum.<br>␊
399 @param info None of the above events require additional info, pass zero.␊
400 @result an IOReturn code, safely ignored.␊
401*/␊
402␊
403 IOReturn handleEvent( IOIndex event, void * info = 0 );␊
404␊
405␊
406 IOReturn deliverFramebufferNotification(␊
407 IOIndex event, void * info = 0 );␊
408␊
409#ifdef IOFRAMEBUFFER_PRIVATE␊
410#include <IOKit/graphics/IOFramebufferPrivate.h>␊
411#endif␊
412␊
413public:␊
414/*! @function enableController␊
415 @abstract Perform first time setup of the framebuffer.␊
416 @discussion IOFramebuffer subclasses should perform their initialization of the hardware here. The IOService start() method is not called at a time appropriate for this initialization.␊
417 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
418*/␊
419␊
420 virtual IOReturn enableController( void );␊
421␊
422/*! @function getPixelFormats␊
423 @abstract List the pixel formats the framebuffer supports.␊
424 @discussion IOFramebuffer subclasses must implement this method to return an array of strings representing the possible pixel formats available in the framebuffer.␊
425 @result A const char * pointer. The string consists of a concatenation of each pixel format string separated by the NULL character. The commonly supported pixel formats for Mac OS X are defined as IO8BitIndexedPixels, IO16BitDirectPixels, IO32BitDirectPixels.␊
426*/␊
427␊
428 virtual const char * getPixelFormats( void ) = 0;␊
429␊
430/*! @function getDisplayModeCount␊
431 @abstract Return the number of display modes the framebuffer supports.␊
432 @discussion IOFramebuffer subclasses must implement this method to return a count of the display modes available. This count should change unless a connection change is posted for the device indicated the framebuffer and/or display configuration has changed.␊
433 @result A count of the display modes available.␊
434*/␊
435␊
436 virtual IOItemCount getDisplayModeCount( void ) = 0;␊
437␊
438/*! @function getDisplayModes␊
439 @abstract Return the number of display modes the framebuffer supports.␊
440 @discussion IOFramebuffer subclasses must implement this method to return an array of display mode IDs available for the framebuffer. The IDs are defined by the driver in the range 0x00000001 - 0x7fffffff, and should be constant for a given display mode. ␊
441 @param allDisplayModes A caller allocated buffer with the size given by the result of getDisplayModeCount().␊
442 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
443*/␊
444 ␊
445 virtual IOReturn getDisplayModes( IODisplayModeID * allDisplayModes ) = 0;␊
446␊
447/*! @function getInformationForDisplayMode␊
448 @abstract Return information about a given display mode.␊
449 @discussion IOFramebuffer subclasses must implement this method to return information in the IODisplayModeInformation structure for the display mode with the passed ID. ␊
450 @param displayMode A display mode ID previously returned by getDisplayModes().␊
451 @param info Pointer to a structure of type IODisplayModeInformation to be filled out by the driver. IODisplayModeInformation is documented in IOGraphicsTypes.h.␊
452 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
453*/␊
454␊
455 virtual IOReturn getInformationForDisplayMode( IODisplayModeID displayMode,␊
456 IODisplayModeInformation * info ) = 0;␊
457␊
458/*! @function getPixelFormatsForDisplayMode␊
459 @abstract Obsolete.␊
460 @discussion IOFramebuffer subclasses must implement this method to return zero. ␊
461 @param displayMode Ignored.␊
462 @param depth Ignored.␊
463 @result Return zero.␊
464*/␊
465␊
466 virtual UInt64 getPixelFormatsForDisplayMode( IODisplayModeID displayMode,␊
467 IOIndex depth ) = 0;␊
468␊
469/*! @function getPixelInformation␊
470 @abstract Return information about the framebuffer format for a given display mode and depth.␊
471 @discussion IOFramebuffer subclasses must implement this method to return information in the IOPixelInformation structure for the display mode with the passed ID, depth index and aperture. The aperture utilized by the system is always kIOFBSystemAperture. Drivers may define alternative apertures, being a view of the framebuffer in a different pixel format from the default.␊
472 @param displayMode A display mode ID previously returned by getDisplayModes().␊
473 @param depth An index from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure (inclusive).␊
474 @param info Pointer to a structure of type IOPixelInformation to be filled out by the driver. IOPixelInformation is documented in IOGraphicsTypes.h.␊
475 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
476*/␊
477␊
478 virtual IOReturn getPixelInformation(␊
479 IODisplayModeID displayMode, IOIndex depth,␊
480 IOPixelAperture aperture, IOPixelInformation * pixelInfo ) = 0;␊
481␊
482/*! @function getCurrentDisplayMode␊
483 @abstract Return the framebuffers current display mode and depth.␊
484 @discussion IOFramebuffer subclasses must implement this method to return the current mode and depth.␊
485 @param displayMode A display mode ID representing the current mode.␊
486 @param depth An index indicating the depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.␊
487 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
488*/␊
489␊
490 virtual IOReturn getCurrentDisplayMode( IODisplayModeID * displayMode,␊
491 IOIndex * depth ) = 0;␊
492␊
493/*! @function setCurrentDisplayMode␊
494 @abstract Set the framebuffers current display mode and depth.␊
495 @discussion IOFramebuffer subclasses should implement this method to set the current mode and depth. Other than at enableController() time, this is the only method that should change the framebuffer format and is synchronized with clients and attached accelerators to make sure access to the device is disallowed during the change.␊
496 @param displayMode A display mode ID representing the new mode.␊
497 @param depth An index indicating the new depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.␊
498 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
499*/␊
500␊
501 virtual IOReturn setDisplayMode( IODisplayModeID displayMode,␊
502 IOIndex depth );␊
503␊
504/*! @function setApertureEnable␊
505 @abstract Enable an aperture on the framebuffer (usually unimplemented, no OS usage).␊
506 @discussion IOFramebuffer subclasses may implement this method to set enable a non standard aperture. The system does not call this method.␊
507 @param aperture A device specific aperture index.␊
508 @param enable Device specific mask of options.␊
509 @result an IOReturn code.␊
510*/␊
511␊
512 virtual IOReturn setApertureEnable( IOPixelAperture aperture,␊
513 IOOptionBits enable );␊
514␊
515/*! @function setStartupDisplayMode␊
516 @abstract Set the framebuffers display mode and depth to be used during boot and at startup.␊
517 @discussion IOFramebuffer subclasses should implement this method to set the mode and depth to be used during boot and at startup, to reduce needed mode changes during boot when the display connection type is the same. If possible this mode should also be used by the OpenFirmware driver for the card.␊
518 @param displayMode A display mode ID representing the new startup mode.␊
519 @param depth An index indicating the new startup depth configuration of the framebuffer. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.␊
520 @result an IOReturn code.␊
521*/␊
522␊
523 virtual IOReturn setStartupDisplayMode( IODisplayModeID displayMode,␊
524 IOIndex depth );␊
525␊
526/*! @function getCurrentDisplayMode␊
527 @abstract Return the framebuffers display mode and depth to be used during boot and at startup.␊
528 @discussion IOFramebuffer subclasses should implement this method to return the current mode and depth.␊
529 @param displayMode A display mode ID representing the mode used during startup.␊
530 @param depth An index indicating the depth configuration of the framebuffer used during startup. The index should range from zero to the value of the maxDepthIndex field from the IODisplayModeInformation structure for the display mode.␊
531 @result an IOReturn code.␊
532*/␊
533␊
534 virtual IOReturn getStartupDisplayMode( IODisplayModeID * displayMode,␊
535 IOIndex * depth );␊
536␊
537/*! @function setCLUTWithEntries␊
538 @abstract Set the color lookup table to be used by the framebuffer in indexed modes.␊
539 @discussion IOFramebuffer subclasses may implement this method to allow a palette to be set for indexed display modes. It will not be called on framebuffers in direct display modes.␊
540 @param colors A pointer to an array of numEntries RGB color entries.␊
541 @param index The index of the first entry to set.␊
542 @param numEntries The number of entries in the table.␊
543 @param options Options controlling the operation. <br>␊
544 kSetCLUTByValue is set if the index field of each entry should be used to set the table sparsely, otherwise consecutive entries from the index parameter should be set.<br>␊
545 kSetCLUTImmediately is set if the CLUT set should not be synchronized with the vertical blank, otherwise it should.<br>␊
546 kSetCLUTWithLuminance is set if the CLUT should be set to a gray value equivalent in luminance to the passed color entry.<br>␊
547 @result an IOReturn code.␊
548*/␊
549␊
550 virtual IOReturn setCLUTWithEntries( IOColorEntry * colors, UInt32 index,␊
551 UInt32 numEntries, IOOptionBits options );␊
552␊
553/*! @function setGammaTable␊
554 @abstract Set the gamma table to be used by the framebuffer.␊
555 @discussion IOFramebuffer subclasses should implement this method to allow a gamma table to be set. ␊
556 @param channelCount Defines the number of channels in the supplied data. OS X will pass three for separate R, G, B data, or one if the same data should apply to all channels.␊
557 @param dataCount The number of data entries per channel.␊
558 @param dataWidth The number of bits in each entry. 8 for Mac OS X 10.1 and earlier, 16 for later releases.␊
559 @param data The packed array of correction data. Data is passed for the R (or single) channel followed by the G & B channels. Each entry is one or two bytes (if dataWidth > 8).␊
560 @result an IOReturn code.␊
561*/␊
562␊
563 virtual IOReturn setGammaTable( UInt32 channelCount, UInt32 dataCount,␊
564 UInt32 dataWidth, void * data );␊
565␊
566/*! @function setAttribute␊
567 @abstract Generic method to set some attribute of the framebuffer device.␊
568 @discussion IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be set. ␊
569 @param attribute Defines the attribute to be set. Some defined attributes are:<br> ␊
570 kIOPowerAttribute The IOFramebuffer class implements most power management (IOService) methods. It calls the subclass to carry out the power management state change with this attribute. When carrying out power state changes, the subclass should call IOFramebuffer::handleEvent for certain changes - set that method for more information.␊
571 @param value The new value for the attribute.␊
572 @result an IOReturn code.␊
573*/␊
574␊
575 virtual IOReturn setAttribute( IOSelect attribute, uintptr_t value );␊
576␊
577/*! @function getAttribute␊
578 @abstract Generic method to retrieve some attribute of the framebuffer device.␊
579 @discussion IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be returned. ␊
580 @param attribute Defines the attribute to be set. Some defined attributes are:<br> ␊
581 kIOHardwareCursorAttribute If the device supports a hardware cursor and implements the setCursorImage() and setCursorState() calls it should return true for this attribute.␊
582 @param value Returns the value for the attribute.␊
583 @result an IOReturn code.␊
584*/␊
585␊
586 virtual IOReturn getAttribute( IOSelect attribute, uintptr_t * value );␊
587␊
588/*! @function getTimingInfoForDisplayMode␊
589 @abstract Returns a timing description for a display mode.␊
590 @discussion IOFramebuffer subclasses should implement this method to return timing information for a display mode. This allows the OS to enable display modes based on its knowledge of the connected display type. Two types of timing information are defined, by Apple defined constant, or by a detailed description of the timing parameters of the mode. ␊
591 @param displayMode A display mode ID representing the mode to examine.␊
592 @param info The driver returns the information for the display mode in this structure.<br>␊
593 If the mode has an Apple defined constant, such as timingVESA_1024x768_75hz, it should be returned in the appleTimingID field. Otherwise the field should be set to timingInvalid.<br>␊
594 If the driver is able to supply detailed timing information, it should return it in the detailedInfo.v2 field of the structure, otherwise the driver should clear the kIODetailedTimingValid flag from the flags field.<br>␊
595 The IODetailedTimingInformationV2 structure is documented in IOGraphicsTypes.h␊
596 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from using the device.␊
597*/␊
598␊
599 virtual IOReturn getTimingInfoForDisplayMode(␊
600 IODisplayModeID displayMode, IOTimingInformation * info );␊
601␊
602/*! @function validateDetailedTiming␊
603 @abstract Reports whether a detailed timing is able to be programmed with the device.␊
604 @discussion IOFramebuffer subclasses may implement programmable mode functionality where the OS is able to install modes described by a detailed timing into the driver. ␊
605 @param description A pointer to a IODetailedTimingInformationV2 structure. The driver should examine this description and change any fields that it cannot implement to reflect its closest possible implementation.␊
606 @param descripSize sizeof(IODetailedTimingInformationV2)␊
607 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from installing the programmable mode.␊
608*/␊
609␊
610 virtual IOReturn validateDetailedTiming(␊
611 void * description, IOByteCount descripSize );␊
612␊
613/*! @function setDetailedTimings␊
614 @abstract Installs an array of OS programmed detailed timings to be made available by the driver.␊
615 @discussion IOFramebuffer subclasses may implement programmable mode functionality where the OS is able to install modes described by a detailed timing into the driver. The driver needs to add these modes to its internal mode list if it provides this functionality.␊
616 @param array An OSArray of OSData objects. Each OSData contains one IODetailedTimingInformationV2 structure. All the data described by the array should be copied or retained by this call until the next invocation of this method.␊
617 @result an IOReturn code. A return other than kIOReturnSuccess will prevent the system from installing the programmable modes.␊
618*/␊
619␊
620 virtual IOReturn setDetailedTimings( OSArray * array );␊
621␊
622/*! @function getConnectionCount␊
623 @abstract Reports the number of display connections the device supports, driven from one framebuffer.␊
624 @discussion IOFramebuffer subclasses may implement functionality where a single framebuffer drives multiple displays. This is not recommended or fully supported and instead multihead cards should implement multiple instances of IOFramebuffer objects to provide full functionality.␊
625 @result A count of the number of display connections reported by the framebuffer. Current versions of OS X only support one connection completely.␊
626*/␊
627␊
628 virtual IOItemCount getConnectionCount( void );␊
629␊
630␊
631/*! @function setAttributeForConnection␊
632 @abstract Generic method to set some attribute of the framebuffer device, specific to one display connection.␊
633 @discussion IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be set, specific to one display connection. ␊
634 @param attribute Defines the attribute to be set. Some defined attributes are:<br> ␊
635 kIOCapturedAttribute If the device supports hotplugging displays, it should disable the generation of hot plug interrupts when the attribute kIOCapturedAttribute is set to true.␊
636 @param value The new value for the attribute.␊
637 @result an IOReturn code.␊
638*/␊
639␊
640 virtual IOReturn setAttributeForConnection( IOIndex connectIndex,␊
641 IOSelect attribute, uintptr_t value );␊
642␊
643/*! @function getAttributeForConnection␊
644 @abstract Generic method to retrieve some attribute of the framebuffer device, specific to one display connection.␊
645 @discussion IOFramebuffer subclasses may implement this method to allow arbitrary attribute/value pairs to be returned, specific to one display connection. ␊
646 @param attribute Defines the attribute to be returned. Some defined attributes are:<br> ␊
647 kConnectionSupportsHLDDCSense If the framebuffer supports the DDC methods hasDDCConnect() and getDDCBlock() it should return success (and no value) for this attribute.<br>␊
648 kConnectionSupportsLLDDCSense If the framebuffer wishes to make use of IOFramebuffer::doI2CRequest software implementation of I2C it should implement the I2C methods setDDCClock(), setDDCData(), readDDCClock(), readDDCData(), and it should return success (and no value) for this attribute.<br>␊
649 @param value Returns the value for the attribute.␊
650 @result an IOReturn code.␊
651*/␊
652␊
653 virtual IOReturn getAttributeForConnection( IOIndex connectIndex,␊
654 IOSelect attribute, uintptr_t * value );␊
655␊
656/*! @function convertCursorImage␊
657 @abstract Utility method of IOFramebuffer to convert cursor image to a hardware cursor format.␊
658 @discussion IOFramebuffer subclasses may implement hardware cursor functionality, if so they should pass the cursor image given by the setCursorImage() method, with a description of their hardware cursor format, to this helper function to this routine to convert the image to one suitable for the hardware.␊
659 @param cursorImage Opaque cursor parameter from the setCursorImage() call.␊
660 @param description Describes the cursor format supported by the driver.␊
661 @param cursor Structure describing the drivers allocated buffer to receive the converted image.␊
662 @result a bool indicating the conversion was successful.␊
663*/␊
664␊
665 virtual bool convertCursorImage( void * cursorImage,␊
666 IOHardwareCursorDescriptor * description,␊
667 IOHardwareCursorInfo * cursor );␊
668␊
669/*! @function setCursorImage␊
670 @abstract Set a new image for the hardware cursor.␊
671 @discussion IOFramebuffer subclasses may implement hardware cursor functionality, if so they should implement this method to change the hardware cursor image. The image should be passed to the convertCursorImage() method with each type of cursor format the hardware supports until success, if all fail the hardware cursor should be hidden and kIOReturnUnsupported returned.␊
672 @param cursorImage Opaque cursor description. This should be passed to the convertCursorImage() method to convert to a format specific to the hardware.␊
673 @result An IOReturn code.␊
674*/␊
675␊
676 virtual IOReturn setCursorImage( void * cursorImage );␊
677␊
678/*! @function setCursorState␊
679 @abstract Set a new position and visibility for the hardware cursor.␊
680 @discussion IOFramebuffer subclasses may implement hardware cursor functionality, if so they should implement this method to change the position and visibility of the cursor.␊
681 @param x Left coordinate of the cursor image. A signed value, will be negative if the cursor's hot spot and position place it partly offscreen.␊
682 @param y Top coordinate of the cursor image. A signed value, will be negative if the cursor's hot spot and position place it partly offscreen.␊
683 @param visible Visible state of the cursor.␊
684 @result An IOReturn code.␊
685*/␊
686␊
687 virtual IOReturn setCursorState( SInt32 x, SInt32 y, bool visible );␊
688␊
689/*! @function flushCursor␊
690 @abstract Perform any needed cache flushing after software cursor rendering.␊
691 @discussion IOFramebuffer implements software cursor functionality when a hardware cursor is unavailable. Some hardware may need to flush a cache after the processor has finished lifting and dropping the software cursor.␊
692*/␊
693␊
694 virtual void flushCursor( void );␊
695␊
696/*! @function getAppleSense␊
697 @abstract Return display sense information for legacy Apple sensing.␊
698 @discussion Hardware that supports simple display sensing, or the classic 3 pin Apple sensing described in Designing Cards and Drivers, should implement this method to return sense information.␊
699 @param connectIndex Index of the display connection, from zero to the value of getConnectionCount().␊
700 @param senseType Return zero to indicate legacy Apple sensing.␊
701 @param primary Return the value of the primary Apple sense code.␊
702 @param extended Return the value of the secondary Apple sense code.␊
703 @param displayType Return an Apple defined constant for the type of display sensed. For example, kVGAConnect, kNTSCConnect, kPALConnect etc.␊
704 @result An IOReturn code.␊
705*/␊
706␊
707 virtual IOReturn getAppleSense( IOIndex connectIndex,␊
708 UInt32 * senseType,␊
709 UInt32 * primary,␊
710 UInt32 * extended,␊
711 UInt32 * displayType );␊
712␊
713/*! @function connectFlags␊
714 @abstract Return display sense information for legacy Apple sensing.␊
715 @discussion Hardware that supports simple display sensing, or the classic 3 pin Apple sensing described in Designing Cards and Drivers, should implement this method to return mode flags relative to the sensed display. If this method is unimplemented, all modes have are given the flags kDisplayModeValidFlag | kDisplayModeSafeFlag.␊
716 @param connectIndex Index of the display connection, from zero to the value of getConnectionCount().␊
717 @param displayMode A display mode ID.␊
718 @param flags Return the flags value for the given mode with the connected display. Flags are:<br>␊
719 kDisplayModeValidFlag - mode is considered valid for the connected display by the driver.␊
720 kDisplayModeSafeFlag - mode is considered safe (not requiring mode change confirmation) for the connected display by the driver.␊
721 kDisplayModeDefaultFlag - mode is considered default for the connected display by the driver.␊
722 @result An IOReturn code.␊
723*/␊
724␊
725 virtual IOReturn connectFlags( IOIndex connectIndex,␊
726 IODisplayModeID displayMode, IOOptionBits * flags );␊
727␊
728 //// IOLowLevelDDCSense␊
729␊
730/*! @function setDDCClock␊
731 @abstract Sets the state of the I2C clock line on a bus.␊
732 @discussion Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to set the state of the I2C clock line on the given bus. Otherwise may be unimplemented.␊
733 @param bus Index of the bus.␊
734 @param value One of kIODDCLow, kIODDCHigh, kIODDCTristate.␊
735*/␊
736␊
737 virtual void setDDCClock( IOIndex bus, UInt32 value );␊
738␊
739/*! @function setDDCData␊
740 @abstract Sets the state of the I2C data line on a bus.␊
741 @discussion Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to set the state of the I2C data line on the given bus. Otherwise may be unimplemented.␊
742 @param bus Index of the bus.␊
743 @param value One of kIODDCLow, kIODDCHigh, kIODDCTristate.␊
744*/␊
745 virtual void setDDCData( IOIndex bus, UInt32 value );␊
746␊
747/*! @function readDDCClock␊
748 @abstract Reads the input state of the I2C clock line on a bus.␊
749 @discussion Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to return the input state of the I2C clock line on the given bus. Otherwise may be unimplemented.␊
750 @param bus Index of the bus.␊
751 @result A boolean reflecting the current state of the clock line on the given bus.␊
752*/␊
753 virtual bool readDDCClock( IOIndex bus );␊
754␊
755/*! @function readDDCData␊
756 @abstract Reads the input state of the I2C data line on a bus.␊
757 @discussion Framebuffers making use of the IOFramebuffer::doI2CRequest() software implementation of I2C should implement this method to return the input state of the I2C data line on the given bus. Otherwise may be unimplemented.␊
758 @param bus Index of the bus.␊
759 @result A boolean reflecting the current state of the data line on the given bus.␊
760*/␊
761 virtual bool readDDCData( IOIndex bus );␊
762␊
763 virtual IOReturn enableDDCRaster( bool enable );␊
764␊
765/*! @function hasDDCConnect␊
766 @abstract Return display DDC connect state.␊
767 @discussion Hardware that supports DDC/EDID display sensing should implement this method to return true if a DDC display is detected. They should also return success for the connection attribute kConnectionSupportsHLDDCSense (from getAttributeForConnection()).␊
768 @param connectIndex Index of the display connection, from zero to the value of getConnectionCount().␊
769 @result True if a DDC display is detected.␊
770*/␊
771␊
772 virtual bool hasDDCConnect( IOIndex connectIndex );␊
773␊
774/*! @function getDDCBlock␊
775 @abstract Return display EDID data.␊
776 @discussion Hardware that supports DDC/EDID display sensing should implement this method to return EDID data in 128 byte blocks.␊
777 @param connectIndex Index of the display connection, from zero to the value of getConnectionCount().␊
778 @param blockNumber Block number, ranging from one to the number of blocks return by the display.␊
779 @param blockType kIODDCBlockTypeEDID will be passed. ␊
780 @param options No options are currently defined.␊
781 @param data Caller allocated buffer to receive the blocks data.␊
782 @param length In/out parameter - callers allocated buffer size, driver returns actual size.␊
783 @result An IOReturn code.␊
784*/␊
785␊
786 virtual IOReturn getDDCBlock( IOIndex connectIndex, UInt32 blockNumber,␊
787 IOSelect blockType, IOOptionBits options,␊
788 UInt8 * data, IOByteCount * length );␊
789␊
790/*! @function registerForInterruptType␊
791 @abstract Set callbacks for driver to call on interrupt events.␊
792 @discussion The IOFramebuffer class will call its subclasses to set callbacks to be called on interrupt events generated by hardware events. Only two are currently in use - vertical blank interrupts and connection changed interrupts.␊
793 @param interruptType One of these constants:<br>␊
794 kIOFBVBLInterruptType Specifying a vertical blanking interrupt.␊
795 kIOFBConnectInterruptType Specify the display connection should be resensed.␊
796 @param proc C callback to be called by the driver when the specified event occurs.␊
797 @param target Target parameter for the callback proc.␊
798 @param ref Ref parameter for the callback proc.␊
799 @param interruptRef The subclass should return an opaque reference to the installed interrupt handler, for use with unregisterInterrupt() and setInterruptState().␊
800 @result An IOReturn code.␊
801*/␊
802␊
803 virtual IOReturn registerForInterruptType( IOSelect interruptType,␊
804 IOFBInterruptProc proc, OSObject * target, void * ref,␊
805 void ** interruptRef );␊
806␊
807/*! @function unregisterInterrupt␊
808 @abstract Remove a callback previously installed by registerForInterruptType().␊
809 @discussion Remove a callback previously installed by registerForInterruptType().␊
810 @param interruptRef The interruptRef returned from the registerForInterruptType call that installed the interrupt.␊
811 @result An IOReturn code.␊
812*/␊
813␊
814 virtual IOReturn unregisterInterrupt( void * interruptRef );␊
815␊
816/*! @function unregisterInterrupt␊
817 @abstract Enable or disable a callback previously installed by registerForInterruptType().␊
818 @discussion Enable or disable a callback previously installed by registerForInterruptType().␊
819 @param state True or false to enable the callback.␊
820 @result An IOReturn code.␊
821*/␊
822␊
823 virtual IOReturn setInterruptState( void * interruptRef, UInt32 state );␊
824␊
825 virtual IOReturn getNotificationSemaphore( IOSelect interruptType,␊
826 semaphore_t * semaphore );␊
827␊
828␉IOReturn setBackingFramebuffer(const IOPixelInformation * info,␊
829␉␉␉␉␉␉␉␉␉uint32_t bufferCount,␊
830␉␉␉␉␉␉␉␉␉void * mappedAddress[]);␊
831␉IOReturn switchBackingFramebuffer(uint32_t bufferIndex);␊
832␊
833/* non WL clients apis␊
834*/␊
835 IOReturn setAttributeExt( IOSelect attribute, uintptr_t value );␊
836 ␊
837 IOReturn getAttributeExt( IOSelect attribute, uintptr_t * value );␊
838 ␊
839 IOReturn setAttributeForConnectionExt( IOIndex connectIndex,␊
840 IOSelect attribute, uintptr_t value );␊
841 ␊
842 IOReturn getAttributeForConnectionExt( IOIndex connectIndex,␊
843 IOSelect attribute, uintptr_t * value );␊
844};␊
845␊
846#endif /* ! _IOKIT_IOFRAMEBUFFER_H */␊
847

Archive Download this file

Revision: 2783