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	 * @unregister:
 33	 *
 34	 * Called when &drm_device is unregistered. The client should respond by
 35	 * releasing its resources using drm_client_release().
 36	 *
 37	 * This callback is optional.
 38	 */
 39	void (*unregister)(struct drm_client_dev *client);
 40
 41	/**
 42	 * @restore:
 43	 *
 44	 * Called on drm_lastclose(). The first client instance in the list that
 45	 * returns zero gets the privilege to restore and no more clients are
 46	 * called. This callback is not called after @unregister has been called.
 47	 *
 48	 * Note that the core does not guarantee exclusion against concurrent
 49	 * drm_open(). Clients need to ensure this themselves, for example by
 50	 * using drm_master_internal_acquire() and
 51	 * drm_master_internal_release().
 52	 *
 53	 * This callback is optional.
 54	 */
 55	int (*restore)(struct drm_client_dev *client);
 56
 57	/**
 58	 * @hotplug:
 59	 *
 60	 * Called on drm_kms_helper_hotplug_event().
 61	 * This callback is not called after @unregister has been called.
 62	 *
 63	 * This callback is optional.
 64	 */
 65	int (*hotplug)(struct drm_client_dev *client);
 66
 67	/**
 68	 * @suspend:
 69	 *
 70	 * Called when suspending the device.
 71	 *
 72	 * This callback is optional.
 73	 *
 74	 * FIXME: Some callers hold the console lock when invoking this
 75	 *        function. This interferes with fbdev emulation, which
 76	 *        also tries to acquire the lock. Push the console lock
 77	 *        into the callback and remove 'holds_console_lock'.
 78	 */
 79	int (*suspend)(struct drm_client_dev *client, bool holds_console_lock);
 80
 81	/**
 82	 * @resume:
 83	 *
 84	 * Called when resuming the device from suspend.
 85	 *
 86	 * This callback is optional.
 87	 *
 88	 * FIXME: Some callers hold the console lock when invoking this
 89	 *        function. This interferes with fbdev emulation, which
 90	 *        also tries to acquire the lock. Push the console lock
 91	 *        into the callback and remove 'holds_console_lock'.
 92	 */
 93	int (*resume)(struct drm_client_dev *client, bool holds_console_lock);
 94};
 95
 96/**
 97 * struct drm_client_dev - DRM client instance
 98 */
 99struct drm_client_dev {
100	/**
101	 * @dev: DRM device
102	 */
103	struct drm_device *dev;
104
105	/**
106	 * @name: Name of the client.
107	 */
108	const char *name;
109
110	/**
111	 * @list:
112	 *
113	 * List of all clients of a DRM device, linked into
114	 * &drm_device.clientlist. Protected by &drm_device.clientlist_mutex.
115	 */
116	struct list_head list;
117
118	/**
119	 * @funcs: DRM client functions (optional)
120	 */
121	const struct drm_client_funcs *funcs;
122
123	/**
124	 * @file: DRM file
125	 */
126	struct drm_file *file;
127
128	/**
129	 * @modeset_mutex: Protects @modesets.
130	 */
131	struct mutex modeset_mutex;
132
133	/**
134	 * @modesets: CRTC configurations
135	 */
136	struct drm_mode_set *modesets;
137
138	/**
139	 * @suspended:
140	 *
141	 * The client has been suspended.
142	 */
143	bool suspended;
144
145	/**
146	 * @hotplug_failed:
147	 *
148	 * Set by client hotplug helpers if the hotplugging failed
149	 * before. It is usually not tried again.
150	 */
151	bool hotplug_failed;
152};
153
154int drm_client_init(struct drm_device *dev, struct drm_client_dev *client,
155		    const char *name, const struct drm_client_funcs *funcs);
156void drm_client_release(struct drm_client_dev *client);
157void drm_client_register(struct drm_client_dev *client);
158
159/**
160 * struct drm_client_buffer - DRM client buffer
161 */
162struct drm_client_buffer {
163	/**
164	 * @client: DRM client
165	 */
166	struct drm_client_dev *client;
167
168	/**
169	 * @pitch: Buffer pitch
170	 */
171	u32 pitch;
172
173	/**
174	 * @gem: GEM object backing this buffer
175	 *
176	 * FIXME: The dependency on GEM here isn't required, we could
177	 * convert the driver handle to a dma-buf instead and use the
178	 * backend-agnostic dma-buf vmap support instead. This would
179	 * require that the handle2fd prime ioctl is reworked to pull the
180	 * fd_install step out of the driver backend hooks, to make that
181	 * final step optional for internal users.
182	 */
183	struct drm_gem_object *gem;
184
185	/**
186	 * @map: Virtual address for the buffer
187	 */
188	struct iosys_map map;
189
190	/**
191	 * @fb: DRM framebuffer
192	 */
193	struct drm_framebuffer *fb;
194};
195
196struct drm_client_buffer *
197drm_client_framebuffer_create(struct drm_client_dev *client, u32 width, u32 height, u32 format);
198void drm_client_framebuffer_delete(struct drm_client_buffer *buffer);
199int drm_client_framebuffer_flush(struct drm_client_buffer *buffer, struct drm_rect *rect);
200int drm_client_buffer_vmap_local(struct drm_client_buffer *buffer,
201				 struct iosys_map *map_copy);
202void drm_client_buffer_vunmap_local(struct drm_client_buffer *buffer);
203int drm_client_buffer_vmap(struct drm_client_buffer *buffer,
204			   struct iosys_map *map);
205void drm_client_buffer_vunmap(struct drm_client_buffer *buffer);
206
207int drm_client_modeset_create(struct drm_client_dev *client);
208void drm_client_modeset_free(struct drm_client_dev *client);
209int drm_client_modeset_probe(struct drm_client_dev *client, unsigned int width, unsigned int height);
210bool drm_client_rotation(struct drm_mode_set *modeset, unsigned int *rotation);
211int drm_client_modeset_check(struct drm_client_dev *client);
212int drm_client_modeset_commit_locked(struct drm_client_dev *client);
213int drm_client_modeset_commit(struct drm_client_dev *client);
214int drm_client_modeset_dpms(struct drm_client_dev *client, int mode);
215
216/**
217 * drm_client_for_each_modeset() - Iterate over client modesets
218 * @modeset: &drm_mode_set loop cursor
219 * @client: DRM client
220 */
221#define drm_client_for_each_modeset(modeset, client) \
222	for (({ lockdep_assert_held(&(client)->modeset_mutex); }), \
223	     modeset = (client)->modesets; modeset->crtc; modeset++)
224
225/**
226 * drm_client_for_each_connector_iter - connector_list iterator macro
227 * @connector: &struct drm_connector pointer used as cursor
228 * @iter: &struct drm_connector_list_iter
229 *
230 * This iterates the connectors that are useable for internal clients (excludes
231 * writeback connectors).
232 *
233 * For more info see drm_for_each_connector_iter().
234 */
235#define drm_client_for_each_connector_iter(connector, iter) \
236	drm_for_each_connector_iter(connector, iter) \
237		if (connector->connector_type != DRM_MODE_CONNECTOR_WRITEBACK)
238
239#endif