include/video/adf.h

   1 /*
   2  * Copyright (C) 2013 Google, Inc.
   3  *
   4  * This software is licensed under the terms of the GNU General Public
   5  * License version 2, as published by the Free Software Foundation, and
   6  * may be copied, distributed, and modified under those terms.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU General Public License for more details.
  12  *
  13  */
  14
  15 #ifndef _VIDEO_ADF_H
  16 #define _VIDEO_ADF_H
  17
  18 #include <linux/device.h>
  19 #include <linux/dma-buf.h>
  20 #include <linux/idr.h>
  21 #include <linux/kref.h>
  22 #include <linux/kthread.h>
  23 #include <linux/ktime.h>
  24 #include <linux/list.h>
  25 #include <linux/module.h>
  26 #include <linux/platform_device.h>
  27 #include <linux/scatterlist.h>
  28 #include <linux/sched.h>
  29 #include <linux/spinlock.h>
  30 #include <linux/wait.h>
  31 #include <linux/workqueue.h>
  32 #include <uapi/video/adf.h>
  33 #include "sync.h"
  34
  35 struct adf_obj;
  36 struct adf_obj_ops;
  37 struct adf_device;
  38 struct adf_device_ops;
  39 struct adf_interface;
  40 struct adf_interface_ops;
  41 struct adf_overlay_engine;
  42 struct adf_overlay_engine_ops;
  43
  44 /**
  45  * struct adf_buffer - buffer displayed by adf_post
  46  *
  47  * @overlay_engine: target overlay engine
  48  * @w: width of display region in pixels
  49  * @h: height of display region in pixels
  50  * @format: DRM-style fourcc, see drm_fourcc.h for standard formats
  51  * @dma_bufs: dma_buf for each plane
  52  * @offset: location of first pixel to scan out, in bytes
  53  * @pitch: length of a scanline including padding, in bytes
  54  * @n_planes: number of planes in buffer
  55  * @acquire_fence: sync_fence which will clear when the buffer is
  56  *      ready for display
  57  *
  58  * &struct adf_buffer is the in-kernel counterpart to the userspace-facing
  59  * &struct adf_buffer_config.
  60  */
  61 struct adf_buffer {
  62         struct adf_overlay_engine *overlay_engine;
  63
  64         u32 w;
  65         u32 h;
  66         u32 format;
  67
  68         struct dma_buf *dma_bufs[ADF_MAX_PLANES];
  69         u32 offset[ADF_MAX_PLANES];
  70         u32 pitch[ADF_MAX_PLANES];
  71         u8 n_planes;
  72
  73         struct sync_fence *acquire_fence;
  74 };
  75
  76 /**
  77  * struct adf_buffer_mapping - state for mapping a &struct adf_buffer into the
  78  * display device
  79  *
  80  * @attachments: dma-buf attachment for each plane
  81  * @sg_tables: SG tables for each plane
  82  */
  83 struct adf_buffer_mapping {
  84         struct dma_buf_attachment *attachments[ADF_MAX_PLANES];
  85         struct sg_table *sg_tables[ADF_MAX_PLANES];
  86 };
  87
  88 /**
  89  * struct adf_post - request to flip to a new set of buffers
  90  *
  91  * @n_bufs: number of buffers displayed
  92  * @bufs: buffers displayed
  93  * @mappings: in-device mapping state for each buffer
  94  * @custom_data_size: size of driver-private data
  95  * @custom_data: driver-private data
  96  *
  97  * &struct adf_post is the in-kernel counterpart to the userspace-facing
  98  * &struct adf_post_config.
  99  */
 100 struct adf_post {
 101         size_t n_bufs;
 102         struct adf_buffer *bufs;
 103         struct adf_buffer_mapping *mappings;
 104
 105         size_t custom_data_size;
 106         void *custom_data;
 107 };
 108
 109 /**
 110  * struct adf_attachment - description of attachment between an overlay engine
 111  * and an interface
 112  *
 113  * @overlay_engine: the overlay engine
 114  * @interface: the interface
 115  *
 116  * &struct adf_attachment is the in-kernel counterpart to the userspace-facing
 117  * &struct adf_attachment_config.
 118  */
 119 struct adf_attachment {
 120         struct adf_overlay_engine *overlay_engine;
 121         struct adf_interface *interface;
 122 };
 123
 124 struct adf_pending_post {
 125         struct list_head head;
 126         struct adf_post config;
 127         void *state;
 128 };
 129
 130 enum adf_obj_type {
 131         ADF_OBJ_OVERLAY_ENGINE = 0,
 132         ADF_OBJ_INTERFACE = 1,
 133         ADF_OBJ_DEVICE = 2,
 134 };
 135
 136 /**
 137  * struct adf_obj_ops - common ADF object implementation ops
 138  *
 139  * @open: handle opening the object's device node
 140  * @release: handle releasing an open file
 141  * @ioctl: handle custom ioctls
 142  *
 143  * @supports_event: return whether the object supports generating events of type
 144  *      @type
 145  * @set_event: enable or disable events of type @type
 146  * @event_type_str: return a string representation of custom event @type
 147  *      (@type >= %ADF_EVENT_DEVICE_CUSTOM).
 148  *
 149  * @custom_data: copy up to %ADF_MAX_CUSTOM_DATA_SIZE bytes of driver-private
 150  *      data into @data (allocated by ADF) and return the number of copied bytes
 151  *      in @size.  Return 0 on success or an error code (<0) on failure.
 152  */
 153 struct adf_obj_ops {
 154         /* optional */
 155         int (*open)(struct adf_obj *obj, struct inode *inode,
 156                         struct file *file);
 157         /* optional */
 158         void (*release)(struct adf_obj *obj, struct inode *inode,
 159                         struct file *file);
 160         /* optional */
 161         long (*ioctl)(struct adf_obj *obj, unsigned int cmd, unsigned long arg);
 162
 163         /* optional */
 164         bool (*supports_event)(struct adf_obj *obj, enum adf_event_type type);
 165         /* required if supports_event is implemented */
 166         void (*set_event)(struct adf_obj *obj, enum adf_event_type type,
 167                         bool enabled);
 168         /* optional */
 169         const char *(*event_type_str)(struct adf_obj *obj,
 170                         enum adf_event_type type);
 171
 172         /* optional */
 173         int (*custom_data)(struct adf_obj *obj, void *data, size_t *size);
 174 };
 175
 176 struct adf_obj {
 177         enum adf_obj_type type;
 178         char name[ADF_NAME_LEN];
 179         struct adf_device *parent;
 180
 181         const struct adf_obj_ops *ops;
 182
 183         struct device dev;
 184
 185         struct spinlock file_lock;
 186         struct list_head file_list;
 187
 188         struct mutex event_lock;
 189         struct rb_root event_refcount;
 190
 191         int id;
 192         int minor;
 193 };
 194
 195 /**
 196  * struct adf_device_quirks - common display device quirks
 197  *
 198  * @buffer_padding: whether the last scanline of a buffer extends to the
 199  *      buffer's pitch (@ADF_BUFFER_PADDED_TO_PITCH) or just to the visible
 200  *      width (@ADF_BUFFER_UNPADDED)
 201  */
 202 struct adf_device_quirks {
 203         /* optional, defaults to ADF_BUFFER_PADDED_TO_PITCH */
 204         enum {
 205                 ADF_BUFFER_PADDED_TO_PITCH = 0,
 206                 ADF_BUFFER_UNPADDED = 1,
 207         } buffer_padding;
 208 };
 209
 210 /**
 211  * struct adf_device_ops - display device implementation ops
 212  *
 213  * @owner: device's module
 214  * @base: common operations (see &struct adf_obj_ops)
 215  * @quirks: device's quirks (see &struct adf_device_quirks)
 216  *
 217  * @attach: attach overlay engine @eng to interface @intf.  Return 0 on success
 218  *      or error code (<0) on failure.
 219  * @detach: detach overlay engine @eng from interface @intf.  Return 0 on
 220  *      success or error code (<0) on failure.
 221  *
 222  * @validate_custom_format: validate the number and size of planes
 223  *      in buffers with a custom format (i.e., not one of the @DRM_FORMAT_*
 224  *      types defined in drm/drm_fourcc.h).  Return 0 if the buffer is valid or
 225  *      an error code (<0) otherwise.
 226  *
 227  * @validate: validate that the proposed configuration @cfg is legal.  The
 228  *      driver may optionally allocate and return some driver-private state in
 229  *      @driver_state, which will be passed to the corresponding post().  The
 230  *      driver may NOT commit any changes to hardware.  Return 0 if @cfg is
 231  *      valid or an error code (<0) otherwise.
 232  * @complete_fence: create a hardware-backed sync fence to be signaled when
 233  *      @cfg is removed from the screen.  If unimplemented, ADF automatically
 234  *      creates an sw_sync fence.  Return the sync fence on success or a
 235  *      PTR_ERR() on failure.
 236  * @post: flip @cfg onto the screen.  Wait for the display to begin scanning out
 237  *      @cfg before returning.
 238  * @advance_timeline: signal the sync fence for the last configuration to leave
 239  *      the display.  If unimplemented, ADF automatically advances an sw_sync
 240  *      timeline.
 241  * @state_free: free driver-private state allocated during validate()
 242  */
 243 struct adf_device_ops {
 244         /* required */
 245         struct module *owner;
 246         const struct adf_obj_ops base;
 247         /* optional */
 248         const struct adf_device_quirks quirks;
 249
 250         /* optional */
 251         int (*attach)(struct adf_device *dev, struct adf_overlay_engine *eng,
 252                         struct adf_interface *intf);
 253         /* optional */
 254         int (*detach)(struct adf_device *dev, struct adf_overlay_engine *eng,
 255                         struct adf_interface *intf);
 256
 257         /* required if any of the device's overlay engines supports at least one
 258            custom format */
 259         int (*validate_custom_format)(struct adf_device *dev,
 260                         struct adf_buffer *buf);
 261
 262         /* required */
 263         int (*validate)(struct adf_device *dev, struct adf_post *cfg,
 264                         void **driver_state);
 265         /* optional */
 266         struct sync_fence *(*complete_fence)(struct adf_device *dev,
 267                         struct adf_post *cfg, void *driver_state);
 268         /* required */
 269         void (*post)(struct adf_device *dev, struct adf_post *cfg,
 270                         void *driver_state);
 271         /* required if complete_fence is implemented */
 272         void (*advance_timeline)(struct adf_device *dev,
 273                         struct adf_post *cfg, void *driver_state);
 274         /* required if validate allocates driver state */
 275         void (*state_free)(struct adf_device *dev, void *driver_state);
 276 };
 277
 278 struct adf_attachment_list {
 279         struct adf_attachment attachment;
 280         struct list_head head;
 281 };
 282
 283 struct adf_device {
 284         struct adf_obj base;
 285         struct device *dev;
 286
 287         const struct adf_device_ops *ops;
 288
 289         struct mutex client_lock;
 290
 291         struct idr interfaces;
 292         size_t n_interfaces;
 293         struct idr overlay_engines;
 294
 295         struct list_head post_list;
 296         struct mutex post_lock;
 297         struct kthread_worker post_worker;
 298         struct task_struct *post_thread;
 299         struct kthread_work post_work;
 300
 301         struct list_head attached;
 302         size_t n_attached;
 303         struct list_head attach_allowed;
 304         size_t n_attach_allowed;
 305
 306         struct adf_pending_post *onscreen;
 307
 308         struct sw_sync_timeline *timeline;
 309         int timeline_max;
 310 };
 311
 312 /**
 313  * struct adf_interface_ops - display interface implementation ops
 314  *
 315  * @base: common operations (see &struct adf_obj_ops)
 316  *
 317  * @blank: change the display's DPMS state.  Return 0 on success or error
 318  *      code (<0) on failure.
 319  *
 320  * @alloc_simple_buffer: allocate a buffer with the specified @w, @h, and
 321  *      @format.  @format will be a standard RGB format (i.e.,
 322  *      adf_format_is_rgb(@format) == true).  Return 0 on success or error code
 323  *      (<0) on failure.  On success, return the buffer, offset, and pitch in
 324  *      @dma_buf, @offset, and @pitch respectively.
 325  * @describe_simple_post: provide driver-private data needed to post a single
 326  *      buffer @buf.  Copy up to ADF_MAX_CUSTOM_DATA_SIZE bytes into @data
 327  *      (allocated by ADF) and return the number of bytes in @size.  Return 0 on
 328  *      success or error code (<0) on failure.
 329  *
 330  * @modeset: change the interface's mode.  @mode is not necessarily part of the
 331  *      modelist passed to adf_hotplug_notify_connected(); the driver may
 332  *      accept or reject custom modes at its discretion.  Return 0 on success or
 333  *      error code (<0) if the mode could not be set.
 334  *
 335  * @screen_size: copy the screen dimensions in millimeters into @width_mm
 336  *      and @height_mm.  Return 0 on success or error code (<0) if the display
 337  *      dimensions are unknown.
 338  *
 339  * @type_str: return a string representation of custom @intf->type
 340  *      (@intf->type >= @ADF_INTF_TYPE_DEVICE_CUSTOM).
 341  */
 342 struct adf_interface_ops {
 343         const struct adf_obj_ops base;
 344
 345         /* optional */
 346         int (*blank)(struct adf_interface *intf, u8 state);
 347
 348         /* optional */
 349         int (*alloc_simple_buffer)(struct adf_interface *intf,
 350                         u16 w, u16 h, u32 format,
 351                         struct dma_buf **dma_buf, u32 *offset, u32 *pitch);
 352         /* optional */
 353         int (*describe_simple_post)(struct adf_interface *intf,
 354                         struct adf_buffer *fb, void *data, size_t *size);
 355
 356         /* optional */
 357         int (*modeset)(struct adf_interface *intf,
 358                         struct drm_mode_modeinfo *mode);
 359
 360         /* optional */
 361         int (*screen_size)(struct adf_interface *intf, u16 *width_mm,
 362                         u16 *height_mm);
 363
 364         /* optional */
 365         const char *(*type_str)(struct adf_interface *intf);
 366 };
 367
 368 struct adf_interface {
 369         struct adf_obj base;
 370         const struct adf_interface_ops *ops;
 371
 372         struct drm_mode_modeinfo current_mode;
 373
 374         enum adf_interface_type type;
 375         u32 idx;
 376         u32 flags;
 377
 378         wait_queue_head_t vsync_wait;
 379         ktime_t vsync_timestamp;
 380         rwlock_t vsync_lock;
 381
 382         u8 dpms_state;
 383
 384         bool hotplug_detect;
 385         struct drm_mode_modeinfo *modelist;
 386         size_t n_modes;
 387         rwlock_t hotplug_modelist_lock;
 388 };
 389
 390 /**
 391  * struct adf_interface_ops - overlay engine implementation ops
 392  *
 393  * @base: common operations (see &struct adf_obj_ops)
 394  *
 395  * @supported_formats: list of fourccs the overlay engine can scan out
 396  * @n_supported_formats: length of supported_formats, up to
 397  *      ADF_MAX_SUPPORTED_FORMATS
 398  */
 399 struct adf_overlay_engine_ops {
 400         const struct adf_obj_ops base;
 401
 402         /* required */
 403         const u32 *supported_formats;
 404         /* required */
 405         const size_t n_supported_formats;
 406 };
 407
 408 struct adf_overlay_engine {
 409         struct adf_obj base;
 410
 411         const struct adf_overlay_engine_ops *ops;
 412 };
 413
 414 #define adf_obj_to_device(ptr) \
 415         container_of((ptr), struct adf_device, base)
 416
 417 #define adf_obj_to_interface(ptr) \
 418         container_of((ptr), struct adf_interface, base)
 419
 420 #define adf_obj_to_overlay_engine(ptr) \
 421         container_of((ptr), struct adf_overlay_engine, base)
 422
 423 int __printf(4, 5) adf_device_init(struct adf_device *dev,
 424                 struct device *parent, const struct adf_device_ops *ops,
 425                 const char *fmt, ...);
 426 void adf_device_destroy(struct adf_device *dev);
 427 int __printf(7, 8) adf_interface_init(struct adf_interface *intf,
 428                 struct adf_device *dev, enum adf_interface_type type, u32 idx,
 429                 u32 flags, const struct adf_interface_ops *ops, const char *fmt,
 430                 ...);
 431 void adf_interface_destroy(struct adf_interface *intf);
 432 static inline struct adf_device *adf_interface_parent(
 433                 struct adf_interface *intf)
 434 {
 435         return intf->base.parent;
 436 }
 437 int __printf(4, 5) adf_overlay_engine_init(struct adf_overlay_engine *eng,
 438                 struct adf_device *dev,
 439                 const struct adf_overlay_engine_ops *ops, const char *fmt, ...);
 440 void adf_overlay_engine_destroy(struct adf_overlay_engine *eng);
 441 static inline struct adf_device *adf_overlay_engine_parent(
 442                 struct adf_overlay_engine *eng)
 443 {
 444         return eng->base.parent;
 445 }
 446
 447 int adf_attachment_allow(struct adf_device *dev, struct adf_overlay_engine *eng,
 448                 struct adf_interface *intf);
 449
 450 const char *adf_obj_type_str(enum adf_obj_type type);
 451 const char *adf_interface_type_str(struct adf_interface *intf);
 452 const char *adf_event_type_str(struct adf_obj *obj, enum adf_event_type type);
 453
 454 #define ADF_FORMAT_STR_SIZE 5
 455 void adf_format_str(u32 format, char buf[ADF_FORMAT_STR_SIZE]);
 456 int adf_format_validate_yuv(struct adf_device *dev, struct adf_buffer *buf,
 457                 u8 num_planes, u8 hsub, u8 vsub, u8 cpp[]);
 458 /**
 459  * adf_format_validate_rgb - validate the number and size of planes in buffers
 460  * with a custom RGB format.
 461  *
 462  * @dev: ADF device performing the validation
 463  * @buf: buffer to validate
 464  * @cpp: expected bytes per pixel
 465  *
 466  * adf_format_validate_rgb() is intended to be called as a helper from @dev's
 467  * validate_custom_format() op.  @buf must have a single RGB plane.
 468  *
 469  * Returns 0 if @buf has a single plane with sufficient size, or -EINVAL
 470  * otherwise.
 471  */
 472 static inline int adf_format_validate_rgb(struct adf_device *dev,
 473                 struct adf_buffer *buf, u8 cpp)
 474 {
 475         return adf_format_validate_yuv(dev, buf, 1, 1, 1, &cpp);
 476 }
 477
 478 int adf_event_get(struct adf_obj *obj, enum adf_event_type type);
 479 int adf_event_put(struct adf_obj *obj, enum adf_event_type type);
 480 int adf_event_notify(struct adf_obj *obj, struct adf_event *event);
 481
 482 static inline void adf_vsync_get(struct adf_interface *intf)
 483 {
 484         adf_event_get(&intf->base, ADF_EVENT_VSYNC);
 485 }
 486
 487 static inline void adf_vsync_put(struct adf_interface *intf)
 488 {
 489         adf_event_put(&intf->base, ADF_EVENT_VSYNC);
 490 }
 491
 492 int adf_vsync_wait(struct adf_interface *intf, long timeout);
 493 void adf_vsync_notify(struct adf_interface *intf, ktime_t timestamp);
 494
 495 int adf_hotplug_notify_connected(struct adf_interface *intf,
 496                 struct drm_mode_modeinfo *modelist, size_t n_modes);
 497 void adf_hotplug_notify_disconnected(struct adf_interface *intf);
 498
 499 void adf_modeinfo_set_name(struct drm_mode_modeinfo *mode);
 500 void adf_modeinfo_set_vrefresh(struct drm_mode_modeinfo *mode);
 501
 502 #endif /* _VIDEO_ADF_H */