drm_client.h

  1/* SPDX-License-Identifier: GPL-2.0 or MIT */
  2
  3#ifndef _DRM_CLIENT_H_
  4#define _DRM_CLIENT_H_
  5
  6#include <linux/iosys-map.h>
  7#include <linux/lockdep.h>
  8#include <linux/mutex.h>
  9#include <linux/types.h>
 10
 11#include <drm/drm_connector.h>
 12#include <drm/drm_crtc.h>
 13
 14struct drm_client_dev;
 15struct drm_device;
 16struct drm_file;
 17struct drm_framebuffer;
 18struct drm_gem_object;
 19struct drm_minor;
 20struct module;
 21
 22/**
 23 * struct drm_client_funcs - DRM client callbacks
 24 */
 25struct drm_client_funcs {
 26	/**
 27	 * @owner: The module owner
 28	 */
 29	struct module *owner;
 30
 31	/**
 32	 * @free:
 33	 *
 34	 * Called when the client gets unregistered. Implementations should
 35	 * release all client-specific data and free the memory.
 36	 *
 37	 * This callback is optional.
 38	 */
 39	void (*free)(struct drm_client_dev *client);
 40
 41	/**
 42	 * @unregister:
 43	 *
 44	 * Called when &drm_device is unregistered. The client should respond by
 45	 * releasing its resources using drm_client_release().
 46	 *
 47	 * This callback is optional.
 48	 */
 49	void (*unregister)(struct drm_client_dev *client);
 50
 51	/**
 52	 * @restore:
 53	 *
 54	 * Called on drm_lastclose(). The first client instance in the list that
 55	 * returns zero gets the privilege to restore and no more clients are
 56	 * called. This callback is not called after @unregister has been called.
 57	 *
 58	 * Note that the core does not guarantee exclusion against concurrent
 59	 * drm_open(). Clients need to ensure this themselves, for example by
 60	 * using drm_master_internal_acquire() and drm_master_internal_release().
 61	 *
 62	 * If the caller passes force, the client should ignore any present DRM
 63	 * master and restore the display anyway.
 64	 *
 65	 * This callback is optional.
 66	 */
 67	int (*restore)(struct drm_client_dev *client, bool force);
 68
 69	/**
 70	 * @hotplug:
 71	 *
 72	 * Called on drm_kms_helper_hotplug_event().
 73	 * This callback is not called after @unregister has been called.
 74	 *
 75	 * This callback is optional.
 76	 */
 77	int (*hotplug)(struct drm_client_dev *client);
 78
 79	/**
 80	 * @suspend:
 81	 *
 82	 * Called when suspending the device.
 83	 *
 84	 * This callback is optional.
 85	 */
 86	int (*suspend)(struct drm_client_dev *client);
 87
 88	/**
 89	 * @resume:
 90	 *
 91	 * Called when resuming the device from suspend.
 92	 *
 93	 * This callback is optional.
 94	 */
 95	int (*resume)(struct drm_client_dev *client);
 96};
 97
 98/**
 99 * struct drm_client_dev - DRM client instance
100 */
101struct drm_client_dev {
102	/**
103	 * @dev: DRM device
104	 */
105	struct drm_device *dev;
106
107	/**
108	 * @name: Name of the client.
109	 */
110	const char *name;
111
112	/**
113	 * @list:
114	 *
115	 * List of all clients of a DRM device, linked into
116	 * &drm_device.clientlist. Protected by &drm_device.clientlist_mutex.
117	 */
118	struct list_head list;
119
120	/**
121	 * @funcs: DRM client functions (optional)
122	 */
123	const struct drm_client_funcs *funcs;
124
125	/**
126	 * @file: DRM file
127	 */
128	struct drm_file *file;
129
130	/**
131	 * @modeset_mutex: Protects @modesets.
132	 */
133	struct mutex modeset_mutex;
134
135	/**
136	 * @modesets: CRTC configurations
137	 */
138	struct drm_mode_set *modesets;
139
140	/**
141	 * @suspended:
142	 *
143	 * The client has been suspended.
144	 */
145	bool suspended;
146
147	/**
148	 * @hotplug_pending:
149	 *
150	 * A hotplug event has been received while the client was suspended.
151	 * Try again on resume.
152	 */
153	bool hotplug_pending;
154
155	/**
156	 * @hotplug_failed:
157	 *
158	 * Set by client hotplug helpers if the hotplugging failed
159	 * before. It is usually not tried again.
160	 */
161	bool hotplug_failed;
162};
163
164int drm_client_init(struct drm_device *dev, struct drm_client_dev *client,
165		    const char *name, const struct drm_client_funcs *funcs);
166void drm_client_release(struct drm_client_dev *client);
167void drm_client_register(struct drm_client_dev *client);
168
169/**
170 * struct drm_client_buffer - DRM client buffer
171 */
172struct drm_client_buffer {
173	/**
174	 * @client: DRM client
175	 */
176	struct drm_client_dev *client;
177
178	/**
179	 * @gem: GEM object backing this buffer
180	 *
181	 * FIXME: The DRM framebuffer holds a reference on its GEM
182	 * buffer objects. Do not use this field in new code and
183	 * update existing users.
184	 */
185	struct drm_gem_object *gem;
186
187	/**
188	 * @map: Virtual address for the buffer
189	 */
190	struct iosys_map map;
191
192	/**
193	 * @fb: DRM framebuffer
194	 */
195	struct drm_framebuffer *fb;
196};
197
198struct drm_client_buffer *
199drm_client_buffer_create_dumb(struct drm_client_dev *client, u32 width, u32 height, u32 format);
200void drm_client_buffer_delete(struct drm_client_buffer *buffer);
201int drm_client_buffer_flush(struct drm_client_buffer *buffer, struct drm_rect *rect);
202int drm_client_buffer_vmap_local(struct drm_client_buffer *buffer,
203				 struct iosys_map *map_copy);
204void drm_client_buffer_vunmap_local(struct drm_client_buffer *buffer);
205int drm_client_buffer_vmap(struct drm_client_buffer *buffer,
206			   struct iosys_map *map);
207void drm_client_buffer_vunmap(struct drm_client_buffer *buffer);
208
209int drm_client_modeset_create(struct drm_client_dev *client);
210void drm_client_modeset_free(struct drm_client_dev *client);
211int drm_client_modeset_probe(struct drm_client_dev *client, unsigned int width, unsigned int height);
212bool drm_client_rotation(struct drm_mode_set *modeset, unsigned int *rotation);
213int drm_client_modeset_check(struct drm_client_dev *client);
214int drm_client_modeset_commit_locked(struct drm_client_dev *client);
215int drm_client_modeset_commit(struct drm_client_dev *client);
216int drm_client_modeset_dpms(struct drm_client_dev *client, int mode);
217int drm_client_modeset_wait_for_vblank(struct drm_client_dev *client, unsigned int crtc_index);
218
219/**
220 * drm_client_for_each_modeset() - Iterate over client modesets
221 * @modeset: &drm_mode_set loop cursor
222 * @client: DRM client
223 */
224#define drm_client_for_each_modeset(modeset, client) \
225	for (({ lockdep_assert_held(&(client)->modeset_mutex); }), \
226	     modeset = (client)->modesets; modeset->crtc; modeset++)
227
228/**
229 * drm_client_for_each_connector_iter - connector_list iterator macro
230 * @connector: &struct drm_connector pointer used as cursor
231 * @iter: &struct drm_connector_list_iter
232 *
233 * This iterates the connectors that are useable for internal clients (excludes
234 * writeback connectors).
235 *
236 * For more info see drm_for_each_connector_iter().
237 */
238#define drm_client_for_each_connector_iter(connector, iter) \
239	drm_for_each_connector_iter(connector, iter) \
240		if (connector->connector_type != DRM_MODE_CONNECTOR_WRITEBACK)
241
242#endif