1// SPDX-License-Identifier: GPL-2.0
2/*
3 * (C) COPYRIGHT 2016 ARM Limited. All rights reserved.
4 * Author: Brian Starkey <brian.starkey@arm.com>
5 *
6 * This program is free software and is provided to you under the terms of the
7 * GNU General Public License version 2 as published by the Free Software
8 * Foundation, and any use by you of this program is subject to the terms
9 * of such GNU licence.
10 */
11
12#include <linux/dma-fence.h>
13#include <linux/export.h>
14
15#include <drm/drm_crtc.h>
16#include <drm/drm_device.h>
17#include <drm/drm_drv.h>
18#include <drm/drm_framebuffer.h>
19#include <drm/drm_managed.h>
20#include <drm/drm_modeset_helper_vtables.h>
21#include <drm/drm_property.h>
22#include <drm/drm_writeback.h>
23
24/**
25 * DOC: overview
26 *
27 * Writeback connectors are used to expose hardware which can write the output
28 * from a CRTC to a memory buffer. They are used and act similarly to other
29 * types of connectors, with some important differences:
30 *
31 * * Writeback connectors don't provide a way to output visually to the user.
32 *
33 * * Writeback connectors are visible to userspace only when the client sets
34 * DRM_CLIENT_CAP_WRITEBACK_CONNECTORS.
35 *
36 * * Writeback connectors don't have EDID.
37 *
38 * A framebuffer may only be attached to a writeback connector when the
39 * connector is attached to a CRTC. The WRITEBACK_FB_ID property which sets the
40 * framebuffer applies only to a single commit (see below). A framebuffer may
41 * not be attached while the CRTC is off.
42 *
43 * Unlike with planes, when a writeback framebuffer is removed by userspace DRM
44 * makes no attempt to remove it from active use by the connector. This is
45 * because no method is provided to abort a writeback operation, and in any
46 * case making a new commit whilst a writeback is ongoing is undefined (see
47 * WRITEBACK_OUT_FENCE_PTR below). As soon as the current writeback is finished,
48 * the framebuffer will automatically no longer be in active use. As it will
49 * also have already been removed from the framebuffer list, there will be no
50 * way for any userspace application to retrieve a reference to it in the
51 * intervening period.
52 *
53 * Writeback connectors have some additional properties, which userspace
54 * can use to query and control them:
55 *
56 * "WRITEBACK_FB_ID":
57 * Write-only object property storing a DRM_MODE_OBJECT_FB: it stores the
58 * framebuffer to be written by the writeback connector. This property is
59 * similar to the FB_ID property on planes, but will always read as zero
60 * and is not preserved across commits.
61 * Userspace must set this property to an output buffer every time it
62 * wishes the buffer to get filled.
63 *
64 * "WRITEBACK_PIXEL_FORMATS":
65 * Immutable blob property to store the supported pixel formats table. The
66 * data is an array of u32 DRM_FORMAT_* fourcc values.
67 * Userspace can use this blob to find out what pixel formats are supported
68 * by the connector's writeback engine.
69 *
70 * "WRITEBACK_OUT_FENCE_PTR":
71 * Userspace can use this property to provide a pointer for the kernel to
72 * fill with a sync_file file descriptor, which will signal once the
73 * writeback is finished. The value should be the address of a 32-bit
74 * signed integer, cast to a u64.
75 * Userspace should wait for this fence to signal before making another
76 * commit affecting any of the same CRTCs, Planes or Connectors.
77 * **Failure to do so will result in undefined behaviour.**
78 * For this reason it is strongly recommended that all userspace
79 * applications making use of writeback connectors *always* retrieve an
80 * out-fence for the commit and use it appropriately.
81 * From userspace, this property will always read as zero.
82 */
83
84#define fence_to_wb_connector(x) container_of(x->lock, \
85 struct drm_writeback_connector, \
86 fence_lock)
87
88static const char *drm_writeback_fence_get_driver_name(struct dma_fence *fence)
89{
90 struct drm_writeback_connector *wb_connector =
91 fence_to_wb_connector(fence);
92
93 return wb_connector->base.dev->driver->name;
94}
95
96static const char *
97drm_writeback_fence_get_timeline_name(struct dma_fence *fence)
98{
99 struct drm_writeback_connector *wb_connector =
100 fence_to_wb_connector(fence);
101
102 return wb_connector->timeline_name;
103}
104
105static const struct dma_fence_ops drm_writeback_fence_ops = {
106 .get_driver_name = drm_writeback_fence_get_driver_name,
107 .get_timeline_name = drm_writeback_fence_get_timeline_name,
108};
109
110static int create_writeback_properties(struct drm_device *dev)
111{
112 struct drm_property *prop;
113
114 if (!dev->mode_config.writeback_fb_id_property) {
115 prop = drm_property_create_object(dev, DRM_MODE_PROP_ATOMIC,
116 name: "WRITEBACK_FB_ID",
117 DRM_MODE_OBJECT_FB);
118 if (!prop)
119 return -ENOMEM;
120 dev->mode_config.writeback_fb_id_property = prop;
121 }
122
123 if (!dev->mode_config.writeback_pixel_formats_property) {
124 prop = drm_property_create(dev, DRM_MODE_PROP_BLOB |
125 DRM_MODE_PROP_ATOMIC |
126 DRM_MODE_PROP_IMMUTABLE,
127 name: "WRITEBACK_PIXEL_FORMATS", num_values: 0);
128 if (!prop)
129 return -ENOMEM;
130 dev->mode_config.writeback_pixel_formats_property = prop;
131 }
132
133 if (!dev->mode_config.writeback_out_fence_ptr_property) {
134 prop = drm_property_create_range(dev, DRM_MODE_PROP_ATOMIC,
135 name: "WRITEBACK_OUT_FENCE_PTR", min: 0,
136 U64_MAX);
137 if (!prop)
138 return -ENOMEM;
139 dev->mode_config.writeback_out_fence_ptr_property = prop;
140 }
141
142 return 0;
143}
144
145static const struct drm_encoder_funcs drm_writeback_encoder_funcs = {
146 .destroy = drm_encoder_cleanup,
147};
148
149/**
150 * drm_writeback_connector_init - Initialize a writeback connector and its properties
151 * @dev: DRM device
152 * @wb_connector: Writeback connector to initialize
153 * @con_funcs: Connector funcs vtable
154 * @enc_helper_funcs: Encoder helper funcs vtable to be used by the internal encoder
155 * @formats: Array of supported pixel formats for the writeback engine
156 * @n_formats: Length of the formats array
157 * @possible_crtcs: possible crtcs for the internal writeback encoder
158 *
159 * This function creates the writeback-connector-specific properties if they
160 * have not been already created, initializes the connector as
161 * type DRM_MODE_CONNECTOR_WRITEBACK, and correctly initializes the property
162 * values. It will also create an internal encoder associated with the
163 * drm_writeback_connector and set it to use the @enc_helper_funcs vtable for
164 * the encoder helper.
165 *
166 * Drivers should always use this function instead of drm_connector_init() to
167 * set up writeback connectors.
168 *
169 * Returns: 0 on success, or a negative error code
170 */
171int drm_writeback_connector_init(struct drm_device *dev,
172 struct drm_writeback_connector *wb_connector,
173 const struct drm_connector_funcs *con_funcs,
174 const struct drm_encoder_helper_funcs *enc_helper_funcs,
175 const u32 *formats, int n_formats,
176 u32 possible_crtcs)
177{
178 int ret = 0;
179
180 drm_encoder_helper_add(encoder: &wb_connector->encoder, funcs: enc_helper_funcs);
181
182 wb_connector->encoder.possible_crtcs = possible_crtcs;
183
184 ret = drm_encoder_init(dev, encoder: &wb_connector->encoder,
185 funcs: &drm_writeback_encoder_funcs,
186 DRM_MODE_ENCODER_VIRTUAL, NULL);
187 if (ret)
188 return ret;
189
190 ret = drm_writeback_connector_init_with_encoder(dev, wb_connector, enc: &wb_connector->encoder,
191 con_funcs, formats, n_formats);
192
193 if (ret)
194 drm_encoder_cleanup(encoder: &wb_connector->encoder);
195
196 return ret;
197}
198EXPORT_SYMBOL(drm_writeback_connector_init);
199
200static void delete_writeback_properties(struct drm_device *dev)
201{
202 if (dev->mode_config.writeback_pixel_formats_property) {
203 drm_property_destroy(dev, property: dev->mode_config.writeback_pixel_formats_property);
204 dev->mode_config.writeback_pixel_formats_property = NULL;
205 }
206 if (dev->mode_config.writeback_out_fence_ptr_property) {
207 drm_property_destroy(dev, property: dev->mode_config.writeback_out_fence_ptr_property);
208 dev->mode_config.writeback_out_fence_ptr_property = NULL;
209 }
210 if (dev->mode_config.writeback_fb_id_property) {
211 drm_property_destroy(dev, property: dev->mode_config.writeback_fb_id_property);
212 dev->mode_config.writeback_fb_id_property = NULL;
213 }
214}
215
216/**
217 * __drm_writeback_connector_init - Initialize a writeback connector with
218 * a custom encoder
219 *
220 * @dev: DRM device
221 * @wb_connector: Writeback connector to initialize
222 * @enc: handle to the already initialized drm encoder
223 * @formats: Array of supported pixel formats for the writeback engine
224 * @n_formats: Length of the formats array
225 *
226 * This function creates the writeback-connector-specific properties if they
227 * have not been already created, initializes the connector as
228 * type DRM_MODE_CONNECTOR_WRITEBACK, and correctly initializes the property
229 * values.
230 *
231 * This function assumes that the drm_writeback_connector's encoder has already been
232 * created and initialized before invoking this function.
233 *
234 * In addition, this function also assumes that callers of this API will manage
235 * assigning the encoder helper functions, possible_crtcs and any other encoder
236 * specific operation.
237 *
238 * Returns: 0 on success, or a negative error code
239 */
240static int __drm_writeback_connector_init(struct drm_device *dev,
241 struct drm_writeback_connector *wb_connector,
242 struct drm_encoder *enc, const u32 *formats,
243 int n_formats)
244{
245 struct drm_connector *connector = &wb_connector->base;
246 struct drm_mode_config *config = &dev->mode_config;
247 struct drm_property_blob *blob;
248 int ret = create_writeback_properties(dev);
249
250 if (ret != 0)
251 goto failed_properties;
252
253 connector->interlace_allowed = 0;
254
255 ret = drm_connector_attach_encoder(connector, encoder: enc);
256 if (ret)
257 goto failed_properties;
258
259 blob = drm_property_create_blob(dev, length: n_formats * sizeof(*formats),
260 data: formats);
261 if (IS_ERR(ptr: blob)) {
262 ret = PTR_ERR(ptr: blob);
263 goto failed_properties;
264 }
265
266 INIT_LIST_HEAD(list: &wb_connector->job_queue);
267 spin_lock_init(&wb_connector->job_lock);
268
269 wb_connector->fence_context = dma_fence_context_alloc(num: 1);
270 spin_lock_init(&wb_connector->fence_lock);
271 snprintf(buf: wb_connector->timeline_name,
272 size: sizeof(wb_connector->timeline_name),
273 fmt: "CONNECTOR:%d-%s", connector->base.id, connector->name);
274
275 drm_object_attach_property(obj: &connector->base,
276 property: config->writeback_out_fence_ptr_property, init_val: 0);
277
278 drm_object_attach_property(obj: &connector->base,
279 property: config->writeback_fb_id_property, init_val: 0);
280
281 drm_object_attach_property(obj: &connector->base,
282 property: config->writeback_pixel_formats_property,
283 init_val: blob->base.id);
284 wb_connector->pixel_formats_blob_ptr = blob;
285
286 return 0;
287failed_properties:
288 delete_writeback_properties(dev);
289 return ret;
290}
291
292/**
293 * drm_writeback_connector_init_with_encoder - Initialize a writeback connector with
294 * a custom encoder
295 *
296 * @dev: DRM device
297 * @wb_connector: Writeback connector to initialize
298 * @enc: handle to the already initialized drm encoder
299 * @con_funcs: Connector funcs vtable
300 * @formats: Array of supported pixel formats for the writeback engine
301 * @n_formats: Length of the formats array
302 *
303 * This function creates the writeback-connector-specific properties if they
304 * have not been already created, initializes the connector as
305 * type DRM_MODE_CONNECTOR_WRITEBACK, and correctly initializes the property
306 * values.
307 *
308 * This function assumes that the drm_writeback_connector's encoder has already been
309 * created and initialized before invoking this function.
310 *
311 * In addition, this function also assumes that callers of this API will manage
312 * assigning the encoder helper functions, possible_crtcs and any other encoder
313 * specific operation.
314 *
315 * Drivers should always use this function instead of drm_connector_init() to
316 * set up writeback connectors if they want to manage themselves the lifetime of the
317 * associated encoder.
318 *
319 * Returns: 0 on success, or a negative error code
320 */
321int drm_writeback_connector_init_with_encoder(struct drm_device *dev,
322 struct drm_writeback_connector *wb_connector,
323 struct drm_encoder *enc,
324 const struct drm_connector_funcs *con_funcs,
325 const u32 *formats, int n_formats)
326{
327 struct drm_connector *connector = &wb_connector->base;
328 int ret;
329
330 ret = drm_connector_init(dev, connector, funcs: con_funcs,
331 DRM_MODE_CONNECTOR_WRITEBACK);
332 if (ret)
333 return ret;
334
335 ret = __drm_writeback_connector_init(dev, wb_connector, enc, formats,
336 n_formats);
337 if (ret)
338 drm_connector_cleanup(connector);
339
340 return ret;
341}
342EXPORT_SYMBOL(drm_writeback_connector_init_with_encoder);
343
344/**
345 * drm_writeback_connector_cleanup - Cleanup the writeback connector
346 * @dev: DRM device
347 * @data: Pointer to the writeback connector to clean up
348 *
349 * This will decrement the reference counter of blobs and destroy properties. It
350 * will also clean the remaining jobs in this writeback connector. Caution: This helper will not
351 * clean up the attached encoder and the drm_connector.
352 */
353static void drm_writeback_connector_cleanup(struct drm_device *dev,
354 void *data)
355{
356 unsigned long flags;
357 struct drm_writeback_job *pos, *n;
358 struct drm_writeback_connector *wb_connector = data;
359
360 delete_writeback_properties(dev);
361 drm_property_blob_put(blob: wb_connector->pixel_formats_blob_ptr);
362
363 spin_lock_irqsave(&wb_connector->job_lock, flags);
364 list_for_each_entry_safe(pos, n, &wb_connector->job_queue, list_entry) {
365 list_del(entry: &pos->list_entry);
366 drm_writeback_cleanup_job(job: pos);
367 }
368 spin_unlock_irqrestore(lock: &wb_connector->job_lock, flags);
369}
370
371/**
372 * drmm_writeback_connector_init - Initialize a writeback connector with
373 * a custom encoder
374 *
375 * @dev: DRM device
376 * @wb_connector: Writeback connector to initialize
377 * @con_funcs: Connector funcs vtable
378 * @enc: Encoder to connect this writeback connector
379 * @formats: Array of supported pixel formats for the writeback engine
380 * @n_formats: Length of the formats array
381 *
382 * This function initialize a writeback connector and register its cleanup.
383 *
384 * This function creates the writeback-connector-specific properties if they
385 * have not been already created, initializes the connector as
386 * type DRM_MODE_CONNECTOR_WRITEBACK, and correctly initializes the property
387 * values.
388 *
389 * Returns: 0 on success, or a negative error code
390 */
391int drmm_writeback_connector_init(struct drm_device *dev,
392 struct drm_writeback_connector *wb_connector,
393 const struct drm_connector_funcs *con_funcs,
394 struct drm_encoder *enc,
395 const u32 *formats, int n_formats)
396{
397 struct drm_connector *connector = &wb_connector->base;
398 int ret;
399
400 ret = drmm_connector_init(dev, connector, funcs: con_funcs,
401 DRM_MODE_CONNECTOR_WRITEBACK, NULL);
402 if (ret)
403 return ret;
404
405 ret = __drm_writeback_connector_init(dev, wb_connector, enc, formats,
406 n_formats);
407 if (ret)
408 return ret;
409
410 ret = drmm_add_action_or_reset(dev, drm_writeback_connector_cleanup,
411 wb_connector);
412 if (ret)
413 return ret;
414
415 return 0;
416}
417EXPORT_SYMBOL(drmm_writeback_connector_init);
418
419int drm_writeback_set_fb(struct drm_connector_state *conn_state,
420 struct drm_framebuffer *fb)
421{
422 WARN_ON(conn_state->connector->connector_type != DRM_MODE_CONNECTOR_WRITEBACK);
423
424 if (!conn_state->writeback_job) {
425 conn_state->writeback_job =
426 kzalloc(sizeof(*conn_state->writeback_job), GFP_KERNEL);
427 if (!conn_state->writeback_job)
428 return -ENOMEM;
429
430 conn_state->writeback_job->connector =
431 drm_connector_to_writeback(connector: conn_state->connector);
432 }
433
434 drm_framebuffer_assign(p: &conn_state->writeback_job->fb, fb);
435 return 0;
436}
437
438int drm_writeback_prepare_job(struct drm_writeback_job *job)
439{
440 struct drm_writeback_connector *connector = job->connector;
441 const struct drm_connector_helper_funcs *funcs =
442 connector->base.helper_private;
443 int ret;
444
445 if (funcs->prepare_writeback_job) {
446 ret = funcs->prepare_writeback_job(connector, job);
447 if (ret < 0)
448 return ret;
449 }
450
451 job->prepared = true;
452 return 0;
453}
454EXPORT_SYMBOL(drm_writeback_prepare_job);
455
456/**
457 * drm_writeback_queue_job - Queue a writeback job for later signalling
458 * @wb_connector: The writeback connector to queue a job on
459 * @conn_state: The connector state containing the job to queue
460 *
461 * This function adds the job contained in @conn_state to the job_queue for a
462 * writeback connector. It takes ownership of the writeback job and sets the
463 * @conn_state->writeback_job to NULL, and so no access to the job may be
464 * performed by the caller after this function returns.
465 *
466 * Drivers must ensure that for a given writeback connector, jobs are queued in
467 * exactly the same order as they will be completed by the hardware (and
468 * signaled via drm_writeback_signal_completion).
469 *
470 * For every call to drm_writeback_queue_job() there must be exactly one call to
471 * drm_writeback_signal_completion()
472 *
473 * See also: drm_writeback_signal_completion()
474 */
475void drm_writeback_queue_job(struct drm_writeback_connector *wb_connector,
476 struct drm_connector_state *conn_state)
477{
478 struct drm_writeback_job *job;
479 unsigned long flags;
480
481 job = conn_state->writeback_job;
482 conn_state->writeback_job = NULL;
483
484 spin_lock_irqsave(&wb_connector->job_lock, flags);
485 list_add_tail(new: &job->list_entry, head: &wb_connector->job_queue);
486 spin_unlock_irqrestore(lock: &wb_connector->job_lock, flags);
487}
488EXPORT_SYMBOL(drm_writeback_queue_job);
489
490void drm_writeback_cleanup_job(struct drm_writeback_job *job)
491{
492 struct drm_writeback_connector *connector = job->connector;
493 const struct drm_connector_helper_funcs *funcs =
494 connector->base.helper_private;
495
496 if (job->prepared && funcs->cleanup_writeback_job)
497 funcs->cleanup_writeback_job(connector, job);
498
499 if (job->fb)
500 drm_framebuffer_put(fb: job->fb);
501
502 if (job->out_fence)
503 dma_fence_put(fence: job->out_fence);
504
505 kfree(objp: job);
506}
507EXPORT_SYMBOL(drm_writeback_cleanup_job);
508
509/*
510 * @cleanup_work: deferred cleanup of a writeback job
511 *
512 * The job cannot be cleaned up directly in drm_writeback_signal_completion,
513 * because it may be called in interrupt context. Dropping the framebuffer
514 * reference can sleep, and so the cleanup is deferred to a workqueue.
515 */
516static void cleanup_work(struct work_struct *work)
517{
518 struct drm_writeback_job *job = container_of(work,
519 struct drm_writeback_job,
520 cleanup_work);
521
522 drm_writeback_cleanup_job(job);
523}
524
525/**
526 * drm_writeback_signal_completion - Signal the completion of a writeback job
527 * @wb_connector: The writeback connector whose job is complete
528 * @status: Status code to set in the writeback out_fence (0 for success)
529 *
530 * Drivers should call this to signal the completion of a previously queued
531 * writeback job. It should be called as soon as possible after the hardware
532 * has finished writing, and may be called from interrupt context.
533 * It is the driver's responsibility to ensure that for a given connector, the
534 * hardware completes writeback jobs in the same order as they are queued.
535 *
536 * Unless the driver is holding its own reference to the framebuffer, it must
537 * not be accessed after calling this function.
538 *
539 * See also: drm_writeback_queue_job()
540 */
541void
542drm_writeback_signal_completion(struct drm_writeback_connector *wb_connector,
543 int status)
544{
545 unsigned long flags;
546 struct drm_writeback_job *job;
547 struct dma_fence *out_fence;
548
549 spin_lock_irqsave(&wb_connector->job_lock, flags);
550 job = list_first_entry_or_null(&wb_connector->job_queue,
551 struct drm_writeback_job,
552 list_entry);
553 if (job)
554 list_del(entry: &job->list_entry);
555
556 spin_unlock_irqrestore(lock: &wb_connector->job_lock, flags);
557
558 if (WARN_ON(!job))
559 return;
560
561 out_fence = job->out_fence;
562 if (out_fence) {
563 if (status)
564 dma_fence_set_error(fence: out_fence, error: status);
565 dma_fence_signal(fence: out_fence);
566 dma_fence_put(fence: out_fence);
567 job->out_fence = NULL;
568 }
569
570 INIT_WORK(&job->cleanup_work, cleanup_work);
571 queue_work(wq: system_long_wq, work: &job->cleanup_work);
572}
573EXPORT_SYMBOL(drm_writeback_signal_completion);
574
575struct dma_fence *
576drm_writeback_get_out_fence(struct drm_writeback_connector *wb_connector)
577{
578 struct dma_fence *fence;
579
580 if (WARN_ON(wb_connector->base.connector_type !=
581 DRM_MODE_CONNECTOR_WRITEBACK))
582 return NULL;
583
584 fence = kzalloc(sizeof(*fence), GFP_KERNEL);
585 if (!fence)
586 return NULL;
587
588 dma_fence_init(fence, ops: &drm_writeback_fence_ops,
589 lock: &wb_connector->fence_lock, context: wb_connector->fence_context,
590 seqno: ++wb_connector->fence_seqno);
591
592 return fence;
593}
594EXPORT_SYMBOL(drm_writeback_get_out_fence);
595