xf86drmMode.h revision 48246ce7 
1/*
2 * \file xf86drmMode.h
3 * Header for DRM modesetting interface.
4 *
5 * \author Jakob Bornecrantz <wallbraker@gmail.com>
6 *
7 * \par Acknowledgements:
8 * Feb 2007, Dave Airlie <airlied@linux.ie>
9 */
10
11/*
12 * Copyright (c) 2007-2008 Tungsten Graphics, Inc., Cedar Park, Texas.
13 * Copyright (c) 2007-2008 Dave Airlie <airlied@linux.ie>
14 * Copyright (c) 2007-2008 Jakob Bornecrantz <wallbraker@gmail.com>
15 *
16 * Permission is hereby granted, free of charge, to any person obtaining a
17 * copy of this software and associated documentation files (the "Software"),
18 * to deal in the Software without restriction, including without limitation
19 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
20 * and/or sell copies of the Software, and to permit persons to whom the
21 * Software is furnished to do so, subject to the following conditions:
22 *
23 * The above copyright notice and this permission notice shall be included in
24 * all copies or substantial portions of the Software.
25 *
26 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
27 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
28 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
29 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
30 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
31 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
32 * IN THE SOFTWARE.
33 *
34 */
35
36#ifndef _XF86DRMMODE_H_
37#define _XF86DRMMODE_H_
38
39#if defined(__cplusplus)
40extern "C" {
41#endif
42
43#include <drm.h>
44#include <drm_mode.h>
45#include <stdbool.h>
46#include <stddef.h>
47#include <stdint.h>
48
49/*
50 * This is the interface for modesetting for drm.
51 *
52 * It aims to provide a randr1.2 compatible interface for modesettings in the
53 * kernel, the interface is also meant to be used by libraries like EGL.
54 *
55 * More information can be found in randrproto.txt which can be found here:
56 * http://gitweb.freedesktop.org/?p=xorg/proto/randrproto.git
57 *
58 * There are some major differences to be noted. Unlike the randr1.2 proto you
59 * need to create the memory object of the framebuffer yourself with the ttm
60 * buffer object interface. This object needs to be pinned.
61 */
62
63/*
64 * Feature defines
65 *
66 * Just because these are defined doesn't mean that the kernel
67 * can do that feature, its just for new code vs old libdrm.
68 */
69#define DRM_MODE_FEATURE_KMS		1
70#define DRM_MODE_FEATURE_DIRTYFB	1
71
72
73typedef struct _drmModeRes {
74
75	int count_fbs;
76	uint32_t *fbs;
77
78	int count_crtcs;
79	uint32_t *crtcs;
80
81	int count_connectors;
82	uint32_t *connectors;
83
84	int count_encoders;
85	uint32_t *encoders;
86
87	uint32_t min_width, max_width;
88	uint32_t min_height, max_height;
89} drmModeRes, *drmModeResPtr;
90
91typedef struct _drmModeModeInfo {
92	uint32_t clock;
93	uint16_t hdisplay, hsync_start, hsync_end, htotal, hskew;
94	uint16_t vdisplay, vsync_start, vsync_end, vtotal, vscan;
95
96	uint32_t vrefresh;
97
98	uint32_t flags;
99	uint32_t type;
100	char name[DRM_DISPLAY_MODE_LEN];
101} drmModeModeInfo, *drmModeModeInfoPtr;
102
103typedef struct _drmModeFB {
104	uint32_t fb_id;
105	uint32_t width, height;
106	uint32_t pitch;
107	uint32_t bpp;
108	uint32_t depth;
109	/* driver specific handle */
110	uint32_t handle;
111} drmModeFB, *drmModeFBPtr;
112
113typedef struct _drmModeFB2 {
114	uint32_t fb_id;
115	uint32_t width, height;
116	uint32_t pixel_format; /* fourcc code from drm_fourcc.h */
117	uint64_t modifier; /* applies to all buffers */
118	uint32_t flags;
119
120	/* per-plane GEM handle; may be duplicate entries for multiple planes */
121	uint32_t handles[4];
122	uint32_t pitches[4]; /* bytes */
123	uint32_t offsets[4]; /* bytes */
124} drmModeFB2, *drmModeFB2Ptr;
125
126typedef struct drm_clip_rect drmModeClip, *drmModeClipPtr;
127
128typedef struct _drmModePropertyBlob {
129	uint32_t id;
130	uint32_t length;
131	void *data;
132} drmModePropertyBlobRes, *drmModePropertyBlobPtr;
133
134typedef struct _drmModeProperty {
135	uint32_t prop_id;
136	uint32_t flags;
137	char name[DRM_PROP_NAME_LEN];
138	int count_values;
139	uint64_t *values; /* store the blob lengths */
140	int count_enums;
141	struct drm_mode_property_enum *enums;
142	int count_blobs;
143	uint32_t *blob_ids; /* store the blob IDs */
144} drmModePropertyRes, *drmModePropertyPtr;
145
146static inline uint32_t drmModeGetPropertyType(const drmModePropertyRes *prop)
147{
148	return prop->flags & (DRM_MODE_PROP_LEGACY_TYPE | DRM_MODE_PROP_EXTENDED_TYPE);
149}
150
151static inline int drm_property_type_is(const drmModePropertyPtr property,
152		uint32_t type)
153{
154	return drmModeGetPropertyType(property) == type;
155}
156
157typedef struct _drmModeCrtc {
158	uint32_t crtc_id;
159	uint32_t buffer_id; /**< FB id to connect to 0 = disconnect */
160
161	uint32_t x, y; /**< Position on the framebuffer */
162	uint32_t width, height;
163	int mode_valid;
164	drmModeModeInfo mode;
165
166	int gamma_size; /**< Number of gamma stops */
167
168} drmModeCrtc, *drmModeCrtcPtr;
169
170typedef struct _drmModeEncoder {
171	uint32_t encoder_id;
172	uint32_t encoder_type;
173	uint32_t crtc_id;
174	uint32_t possible_crtcs;
175	uint32_t possible_clones;
176} drmModeEncoder, *drmModeEncoderPtr;
177
178/**
179 * Describes the connector status.
180 *
181 * DRM_MODE_CONNECTED means that the connector has a sink plugged in.
182 * DRM_MODE_DISCONNECTED means the contrary. DRM_MODE_UNKNOWNCONNECTION is used
183 * when it could be either.
184 *
185 * User-space should first try to enable DRM_MODE_CONNECTED connectors and
186 * ignore other connectors. If there are no DRM_MODE_CONNECTED connectors,
187 * user-space should then try to probe and enable DRM_MODE_UNKNOWNCONNECTION
188 * connectors.
189 */
190typedef enum {
191	DRM_MODE_CONNECTED         = 1,
192	DRM_MODE_DISCONNECTED      = 2,
193	DRM_MODE_UNKNOWNCONNECTION = 3
194} drmModeConnection;
195
196typedef enum {
197	DRM_MODE_SUBPIXEL_UNKNOWN        = 1,
198	DRM_MODE_SUBPIXEL_HORIZONTAL_RGB = 2,
199	DRM_MODE_SUBPIXEL_HORIZONTAL_BGR = 3,
200	DRM_MODE_SUBPIXEL_VERTICAL_RGB   = 4,
201	DRM_MODE_SUBPIXEL_VERTICAL_BGR   = 5,
202	DRM_MODE_SUBPIXEL_NONE           = 6
203} drmModeSubPixel;
204
205typedef struct _drmModeConnector {
206	uint32_t connector_id;
207	uint32_t encoder_id; /**< Encoder currently connected to */
208	uint32_t connector_type;
209	uint32_t connector_type_id;
210	drmModeConnection connection;
211	uint32_t mmWidth, mmHeight; /**< HxW in millimeters */
212	drmModeSubPixel subpixel;
213
214	int count_modes;
215	drmModeModeInfoPtr modes;
216
217	int count_props;
218	uint32_t *props; /**< List of property ids */
219	uint64_t *prop_values; /**< List of property values */
220
221	int count_encoders;
222	uint32_t *encoders; /**< List of encoder ids */
223} drmModeConnector, *drmModeConnectorPtr;
224
225#define DRM_PLANE_TYPE_OVERLAY 0
226#define DRM_PLANE_TYPE_PRIMARY 1
227#define DRM_PLANE_TYPE_CURSOR  2
228
229typedef struct _drmModeObjectProperties {
230	uint32_t count_props;
231	uint32_t *props;
232	uint64_t *prop_values;
233} drmModeObjectProperties, *drmModeObjectPropertiesPtr;
234
235typedef struct _drmModeFormatModifierIterator {
236	uint32_t fmt_idx, mod_idx;
237	uint32_t fmt;
238	uint64_t mod;
239} drmModeFormatModifierIterator;
240
241typedef struct _drmModePlane {
242	uint32_t count_formats;
243	uint32_t *formats;
244	uint32_t plane_id;
245
246	uint32_t crtc_id;
247	uint32_t fb_id;
248
249	uint32_t crtc_x, crtc_y;
250	uint32_t x, y;
251
252	uint32_t possible_crtcs;
253	uint32_t gamma_size;
254} drmModePlane, *drmModePlanePtr;
255
256typedef struct _drmModePlaneRes {
257	uint32_t count_planes;
258	uint32_t *planes;
259} drmModePlaneRes, *drmModePlaneResPtr;
260
261extern void drmModeFreeModeInfo( drmModeModeInfoPtr ptr );
262extern void drmModeFreeResources( drmModeResPtr ptr );
263extern void drmModeFreeFB( drmModeFBPtr ptr );
264extern void drmModeFreeFB2( drmModeFB2Ptr ptr );
265extern void drmModeFreeCrtc( drmModeCrtcPtr ptr );
266extern void drmModeFreeConnector( drmModeConnectorPtr ptr );
267extern void drmModeFreeEncoder( drmModeEncoderPtr ptr );
268extern void drmModeFreePlane( drmModePlanePtr ptr );
269extern void drmModeFreePlaneResources(drmModePlaneResPtr ptr);
270
271/**
272 * Check whether the DRM node supports Kernel Mode-Setting.
273 *
274 * Returns 1 if suitable for KMS, 0 otherwise.
275 */
276extern int drmIsKMS(int fd);
277
278/**
279 * Retrieves all of the resources associated with a card.
280 */
281extern drmModeResPtr drmModeGetResources(int fd);
282
283/*
284 * FrameBuffer manipulation.
285 */
286
287/**
288 * Retrieve information about framebuffer bufferId
289 */
290extern drmModeFBPtr drmModeGetFB(int fd, uint32_t bufferId);
291extern drmModeFB2Ptr drmModeGetFB2(int fd, uint32_t bufferId);
292
293/**
294 * Creates a new framebuffer with an buffer object as its scanout buffer.
295 */
296extern int drmModeAddFB(int fd, uint32_t width, uint32_t height, uint8_t depth,
297			uint8_t bpp, uint32_t pitch, uint32_t bo_handle,
298			uint32_t *buf_id);
299/* ...with a specific pixel format */
300extern int drmModeAddFB2(int fd, uint32_t width, uint32_t height,
301			 uint32_t pixel_format, const uint32_t bo_handles[4],
302			 const uint32_t pitches[4], const uint32_t offsets[4],
303			 uint32_t *buf_id, uint32_t flags);
304
305/* ...with format modifiers */
306int drmModeAddFB2WithModifiers(int fd, uint32_t width, uint32_t height,
307			       uint32_t pixel_format, const uint32_t bo_handles[4],
308			       const uint32_t pitches[4], const uint32_t offsets[4],
309			       const uint64_t modifier[4], uint32_t *buf_id,
310				   uint32_t flags);
311
312/**
313 * Destroies the given framebuffer.
314 */
315extern int drmModeRmFB(int fd, uint32_t bufferId);
316
317/**
318 * Close a framebuffer.
319 *
320 * Same as drmModeRmFB(), except it doesn't implicitly disable planes and CRTCs.
321 */
322extern int drmModeCloseFB(int fd, uint32_t buffer_id);
323
324/**
325 * Mark a region of a framebuffer as dirty.
326 */
327extern int drmModeDirtyFB(int fd, uint32_t bufferId,
328			  drmModeClipPtr clips, uint32_t num_clips);
329
330
331/*
332 * Crtc functions
333 */
334
335/**
336 * Retrieve information about the ctrt crtcId
337 */
338extern drmModeCrtcPtr drmModeGetCrtc(int fd, uint32_t crtcId);
339
340/**
341 * Set the mode on a crtc crtcId with the given mode modeId.
342 */
343int drmModeSetCrtc(int fd, uint32_t crtcId, uint32_t bufferId,
344                   uint32_t x, uint32_t y, uint32_t *connectors, int count,
345		   drmModeModeInfoPtr mode);
346
347/*
348 * Cursor functions
349 */
350
351/**
352 * Set the cursor on crtc
353 */
354int drmModeSetCursor(int fd, uint32_t crtcId, uint32_t bo_handle, uint32_t width, uint32_t height);
355
356int drmModeSetCursor2(int fd, uint32_t crtcId, uint32_t bo_handle, uint32_t width, uint32_t height, int32_t hot_x, int32_t hot_y);
357/**
358 * Move the cursor on crtc
359 */
360int drmModeMoveCursor(int fd, uint32_t crtcId, int x, int y);
361
362/**
363 * Encoder functions
364 */
365drmModeEncoderPtr drmModeGetEncoder(int fd, uint32_t encoder_id);
366
367/*
368 * Connector manipulation
369 */
370
371/**
372 * Retrieve all information about the connector connectorId. This will do a
373 * forced probe on the connector to retrieve remote information such as EDIDs
374 * from the display device.
375 */
376extern drmModeConnectorPtr drmModeGetConnector(int fd,
377					       uint32_t connectorId);
378
379/**
380 * Retrieve current information, i.e the currently active mode and encoder,
381 * about the connector connectorId. This will not do any probing on the
382 * connector or remote device, and only reports what is currently known.
383 * For the complete set of modes and encoders associated with the connector
384 * use drmModeGetConnector() which will do a probe to determine any display
385 * link changes first.
386 */
387extern drmModeConnectorPtr drmModeGetConnectorCurrent(int fd,
388						      uint32_t connector_id);
389
390/**
391 * Get a bitmask of CRTCs a connector is compatible with.
392 *
393 * The bits reference CRTC indices. If the n-th CRTC is compatible with the
394 * connector, the n-th bit will be set. The indices are taken from the array
395 * returned by drmModeGetResources(). The indices are different from the object
396 * IDs.
397 *
398 * Zero is returned on error.
399 */
400extern uint32_t drmModeConnectorGetPossibleCrtcs(int fd,
401                                                 const drmModeConnector *connector);
402
403/**
404 * Attaches the given mode to an connector.
405 */
406extern int drmModeAttachMode(int fd, uint32_t connectorId, drmModeModeInfoPtr mode_info);
407
408/**
409 * Detaches a mode from the connector
410 * must be unused, by the given mode.
411 */
412extern int drmModeDetachMode(int fd, uint32_t connectorId, drmModeModeInfoPtr mode_info);
413
414extern drmModePropertyPtr drmModeGetProperty(int fd, uint32_t propertyId);
415extern void drmModeFreeProperty(drmModePropertyPtr ptr);
416
417extern drmModePropertyBlobPtr drmModeGetPropertyBlob(int fd, uint32_t blob_id);
418extern bool drmModeFormatModifierBlobIterNext(const drmModePropertyBlobRes *blob,
419					      drmModeFormatModifierIterator *iter);
420extern void drmModeFreePropertyBlob(drmModePropertyBlobPtr ptr);
421extern int drmModeConnectorSetProperty(int fd, uint32_t connector_id, uint32_t property_id,
422				    uint64_t value);
423extern int drmCheckModesettingSupported(const char *busid);
424
425extern int drmModeCrtcSetGamma(int fd, uint32_t crtc_id, uint32_t size,
426			       const uint16_t *red, const uint16_t *green, const uint16_t *blue);
427extern int drmModeCrtcGetGamma(int fd, uint32_t crtc_id, uint32_t size,
428			       uint16_t *red, uint16_t *green, uint16_t *blue);
429extern int drmModePageFlip(int fd, uint32_t crtc_id, uint32_t fb_id,
430			   uint32_t flags, void *user_data);
431extern int drmModePageFlipTarget(int fd, uint32_t crtc_id, uint32_t fb_id,
432				 uint32_t flags, void *user_data,
433				 uint32_t target_vblank);
434
435extern drmModePlaneResPtr drmModeGetPlaneResources(int fd);
436extern drmModePlanePtr drmModeGetPlane(int fd, uint32_t plane_id);
437extern int drmModeSetPlane(int fd, uint32_t plane_id, uint32_t crtc_id,
438			   uint32_t fb_id, uint32_t flags,
439			   uint32_t crtc_x, uint32_t crtc_y,
440			   uint32_t crtc_w, uint32_t crtc_h,
441			   uint32_t src_x, uint32_t src_y,
442			   uint32_t src_w, uint32_t src_h);
443
444extern drmModeObjectPropertiesPtr drmModeObjectGetProperties(int fd,
445							uint32_t object_id,
446							uint32_t object_type);
447extern void drmModeFreeObjectProperties(drmModeObjectPropertiesPtr ptr);
448extern int drmModeObjectSetProperty(int fd, uint32_t object_id,
449				    uint32_t object_type, uint32_t property_id,
450				    uint64_t value);
451
452
453typedef struct _drmModeAtomicReq drmModeAtomicReq, *drmModeAtomicReqPtr;
454
455extern drmModeAtomicReqPtr drmModeAtomicAlloc(void);
456extern drmModeAtomicReqPtr drmModeAtomicDuplicate(const drmModeAtomicReqPtr req);
457extern int drmModeAtomicMerge(drmModeAtomicReqPtr base,
458			      const drmModeAtomicReqPtr augment);
459extern void drmModeAtomicFree(drmModeAtomicReqPtr req);
460extern int drmModeAtomicGetCursor(const drmModeAtomicReqPtr req);
461extern void drmModeAtomicSetCursor(drmModeAtomicReqPtr req, int cursor);
462extern int drmModeAtomicAddProperty(drmModeAtomicReqPtr req,
463				    uint32_t object_id,
464				    uint32_t property_id,
465				    uint64_t value);
466extern int drmModeAtomicCommit(int fd,
467			       const drmModeAtomicReqPtr req,
468			       uint32_t flags,
469			       void *user_data);
470
471extern int drmModeCreatePropertyBlob(int fd, const void *data, size_t size,
472				     uint32_t *id);
473extern int drmModeDestroyPropertyBlob(int fd, uint32_t id);
474
475/*
476 * DRM mode lease APIs. These create and manage new drm_masters with
477 * access to a subset of the available DRM resources
478 */
479
480extern int drmModeCreateLease(int fd, const uint32_t *objects, int num_objects, int flags, uint32_t *lessee_id);
481
482typedef struct drmModeLesseeList {
483	uint32_t count;
484	uint32_t lessees[];
485} drmModeLesseeListRes, *drmModeLesseeListPtr;
486
487extern drmModeLesseeListPtr drmModeListLessees(int fd);
488
489typedef struct drmModeObjectList {
490	uint32_t count;
491	uint32_t objects[];
492} drmModeObjectListRes, *drmModeObjectListPtr;
493
494extern drmModeObjectListPtr drmModeGetLease(int fd);
495
496extern int drmModeRevokeLease(int fd, uint32_t lessee_id);
497
498/**
499 * Get a string describing a connector type.
500 *
501 * NULL is returned if the connector type is unsupported. Callers should handle
502 * this gracefully, e.g. by falling back to "Unknown" or printing the raw value.
503 */
504extern const char *
505drmModeGetConnectorTypeName(uint32_t connector_type);
506
507/**
508 * Create a dumb buffer.
509 *
510 * Given a width, height and bits-per-pixel, the kernel will return a buffer
511 * handle, pitch and size. The flags must be zero.
512 *
513 * Returns 0 on success, negative errno on error.
514 */
515extern int
516drmModeCreateDumbBuffer(int fd, uint32_t width, uint32_t height, uint32_t bpp,
517                        uint32_t flags, uint32_t *handle, uint32_t *pitch,
518                        uint64_t *size);
519
520/**
521 * Destroy a dumb buffer.
522 *
523 * Returns 0 on success, negative errno on error.
524 */
525extern int
526drmModeDestroyDumbBuffer(int fd, uint32_t handle);
527
528/**
529 * Prepare a dumb buffer for mapping.
530 *
531 * The kernel returns an offset which can be used as an argument to mmap(2) on
532 * the DRM FD.
533 *
534 * Returns 0 on success, negative errno on error.
535 */
536extern int
537drmModeMapDumbBuffer(int fd, uint32_t handle, uint64_t *offset);
538
539#if defined(__cplusplus)
540}
541#endif
542
543#endif
544