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_ops - display device implementation ops
 197  *
 198  * @owner: device's module
 199  * @base: common operations (see &struct adf_obj_ops)
 200  *
 201  * @attach: attach overlay engine @eng to interface @intf.  Return 0 on success
 202  *      or error code (<0) on failure.
 203  * @detach: detach overlay engine @eng from interface @intf.  Return 0 on
 204  *      success or error code (<0) on failure.
 205  *
 206  * @validate_custom_format: validate the number and size of planes
 207  *      in buffers with a custom format (i.e., not one of the @DRM_FORMAT_*
 208  *      types defined in drm/drm_fourcc.h).  Return 0 if the buffer is valid or
 209  *      an error code (<0) otherwise.
 210  *
 211  * @validate: validate that the proposed configuration @cfg is legal.  The
 212  *      driver may optionally allocate and return some driver-private state in
 213  *      @driver_state, which will be passed to the corresponding post().  The
 214  *      driver may NOT commit any changes to hardware.  Return 0 if @cfg is
 215  *      valid or an error code (<0) otherwise.
 216  * @complete_fence: create a hardware-backed sync fence to be signaled when
 217  *      @cfg is removed from the screen.  If unimplemented, ADF automatically
 218  *      creates an sw_sync fence.  Return the sync fence on success or a
 219  *      PTR_ERR() on failure.
 220  * @post: flip @cfg onto the screen.  Wait for the display to begin scanning out
 221  *      @cfg before returning.
 222  * @advance_timeline: signal the sync fence for the last configuration to leave
 223  *      the display.  If unimplemented, ADF automatically advances an sw_sync
 224  *      timeline.
 225  * @state_free: free driver-private state allocated during validate()
 226  */
 227 struct adf_device_ops {
 228         /* required */
 229         struct module *owner;
 230         const struct adf_obj_ops base;
 231
 232         /* optional */
 233         int (*attach)(struct adf_device *dev, struct adf_overlay_engine *eng,
 234                         struct adf_interface *intf);
 235         /* optional */
 236         int (*detach)(struct adf_device *dev, struct adf_overlay_engine *eng,
 237                         struct adf_interface *intf);
 238
 239         /* required if any of the device's overlay engines supports at least one
 240            custom format */
 241         int (*validate_custom_format)(struct adf_device *dev,
 242                         struct adf_buffer *buf);
 243
 244         /* required */
 245         int (*validate)(struct adf_device *dev, struct adf_post *cfg,
 246                         void **driver_state);
 247         /* optional */
 248         struct sync_fence *(*complete_fence)(struct adf_device *dev,
 249                         struct adf_post *cfg, void *driver_state);
 250         /* required */
 251         void (*post)(struct adf_device *dev, struct adf_post *cfg,
 252                         void *driver_state);
 253         /* required if complete_fence is implemented */
 254         void (*advance_timeline)(struct adf_device *dev,
 255                         struct adf_post *cfg, void *driver_state);
 256         /* required if validate allocates driver state */
 257         void (*state_free)(struct adf_device *dev, void *driver_state);
 258 };
 259
 260 struct adf_attachment_list {
 261         struct adf_attachment attachment;
 262         struct list_head head;
 263 };
 264
 265 struct adf_device {
 266         struct adf_obj base;
 267         struct device *dev;
 268
 269         const struct adf_device_ops *ops;
 270
 271         struct mutex client_lock;
 272
 273         struct idr interfaces;
 274         size_t n_interfaces;
 275         struct idr overlay_engines;
 276
 277         struct list_head post_list;
 278         struct mutex post_lock;
 279         struct kthread_worker post_worker;
 280         struct task_struct *post_thread;
 281         struct kthread_work post_work;
 282
 283         struct list_head attached;
 284         size_t n_attached;
 285         struct list_head attach_allowed;
 286         size_t n_attach_allowed;
 287
 288         struct adf_pending_post *onscreen;
 289
 290         struct sw_sync_timeline *timeline;
 291         int timeline_max;
 292 };
 293
 294 /**
 295  * struct adf_interface_ops - display interface implementation ops
 296  *
 297  * @base: common operations (see &struct adf_obj_ops)
 298  *
 299  * @blank: change the display's DPMS state.  Return 0 on success or error
 300  *      code (<0) on failure.
 301  *
 302  * @alloc_simple_buffer: allocate a buffer with the specified @w, @h, and
 303  *      @format.  @format will be a standard RGB format (i.e.,
 304  *      adf_format_is_rgb(@format) == true).  Return 0 on success or error code
 305  *      (<0) on failure.  On success, return the buffer, offset, and pitch in
 306  *      @dma_buf, @offset, and @pitch respectively.
 307  * @describe_simple_post: provide driver-private data needed to post a single
 308  *      buffer @buf.  Copy up to ADF_MAX_CUSTOM_DATA_SIZE bytes into @data
 309  *      (allocated by ADF) and return the number of bytes in @size.  Return 0 on
 310  *      success or error code (<0) on failure.
 311  *
 312  * @modeset: change the interface's mode.  @mode is not necessarily part of the
 313  *      modelist passed to adf_hotplug_notify_connected(); the driver may
 314  *      accept or reject custom modes at its discretion.  Return 0 on success or
 315  *      error code (<0) if the mode could not be set.
 316  *
 317  * @screen_size: copy the screen dimensions in millimeters into @width_mm
 318  *      and @height_mm.  Return 0 on success or error code (<0) if the display
 319  *      dimensions are unknown.
 320  *
 321  * @type_str: return a string representation of custom @intf->type
 322  *      (@intf->type >= @ADF_INTF_TYPE_DEVICE_CUSTOM).
 323  */
 324 struct adf_interface_ops {
 325         const struct adf_obj_ops base;
 326
 327         /* optional */
 328         int (*blank)(struct adf_interface *intf, u8 state);
 329
 330         /* optional */
 331         int (*alloc_simple_buffer)(struct adf_interface *intf,
 332                         u16 w, u16 h, u32 format,
 333                         struct dma_buf **dma_buf, u32 *offset, u32 *pitch);
 334         /* optional */
 335         int (*describe_simple_post)(struct adf_interface *intf,
 336                         struct adf_buffer *fb, void *data, size_t *size);
 337
 338         /* optional */
 339         int (*modeset)(struct adf_interface *intf,
 340                         struct drm_mode_modeinfo *mode);
 341
 342         /* optional */
 343         int (*screen_size)(struct adf_interface *intf, u16 *width_mm,
 344                         u16 *height_mm);
 345
 346         /* optional */
 347         const char *(*type_str)(struct adf_interface *intf);
 348 };
 349
 350 struct adf_interface {
 351         struct adf_obj base;
 352         const struct adf_interface_ops *ops;
 353
 354         struct drm_mode_modeinfo current_mode;
 355
 356         enum adf_interface_type type;
 357         u32 idx;
 358
 359         wait_queue_head_t vsync_wait;
 360         ktime_t vsync_timestamp;
 361         rwlock_t vsync_lock;
 362
 363         u8 dpms_state;
 364
 365         bool hotplug_detect;
 366         struct drm_mode_modeinfo *modelist;
 367         size_t n_modes;
 368         rwlock_t hotplug_modelist_lock;
 369 };
 370
 371 /**
 372  * struct adf_interface_ops - overlay engine implementation ops
 373  *
 374  * @base: common operations (see &struct adf_obj_ops)
 375  *
 376  * @supported_formats: list of fourccs the overlay engine can scan out
 377  * @n_supported_formats: length of supported_formats, up to
 378  *      ADF_MAX_SUPPORTED_FORMATS
 379  */
 380 struct adf_overlay_engine_ops {
 381         const struct adf_obj_ops base;
 382
 383         /* required */
 384         const u32 *supported_formats;
 385         /* required */
 386         const size_t n_supported_formats;
 387 };
 388
 389 struct adf_overlay_engine {
 390         struct adf_obj base;
 391
 392         const struct adf_overlay_engine_ops *ops;
 393 };
 394
 395 #define adf_obj_to_device(ptr) \
 396         container_of((ptr), struct adf_device, base)
 397
 398 #define adf_obj_to_interface(ptr) \
 399         container_of((ptr), struct adf_interface, base)
 400
 401 #define adf_obj_to_overlay_engine(ptr) \
 402         container_of((ptr), struct adf_overlay_engine, base)
 403
 404 int __printf(4, 5) adf_device_init(struct adf_device *dev,
 405                 struct device *parent, const struct adf_device_ops *ops,
 406                 const char *fmt, ...);
 407 void adf_device_destroy(struct adf_device *dev);
 408 int __printf(6, 7) adf_interface_init(struct adf_interface *intf,
 409                 struct adf_device *dev, enum adf_interface_type type, u32 idx,
 410                 const struct adf_interface_ops *ops, const char *fmt, ...);
 411 void adf_interface_destroy(struct adf_interface *intf);
 412 static inline struct adf_device *adf_interface_parent(
 413                 struct adf_interface *intf)
 414 {
 415         return intf->base.parent;
 416 }
 417 int __printf(4, 5) adf_overlay_engine_init(struct adf_overlay_engine *eng,
 418                 struct adf_device *dev,
 419                 const struct adf_overlay_engine_ops *ops, const char *fmt, ...);
 420 void adf_overlay_engine_destroy(struct adf_overlay_engine *eng);
 421 static inline struct adf_device *adf_overlay_engine_parent(
 422                 struct adf_overlay_engine *eng)
 423 {
 424         return eng->base.parent;
 425 }
 426
 427 int adf_attachment_allow(struct adf_device *dev, struct adf_overlay_engine *eng,
 428                 struct adf_interface *intf);
 429
 430 const char *adf_obj_type_str(enum adf_obj_type type);
 431 const char *adf_interface_type_str(struct adf_interface *intf);
 432 const char *adf_event_type_str(struct adf_obj *obj, enum adf_event_type type);
 433
 434 #define ADF_FORMAT_STR_SIZE 5
 435 void adf_format_str(u32 format, char buf[ADF_FORMAT_STR_SIZE]);
 436
 437 int adf_event_get(struct adf_obj *obj, enum adf_event_type type);
 438 int adf_event_put(struct adf_obj *obj, enum adf_event_type type);
 439 int adf_event_notify(struct adf_obj *obj, struct adf_event *event);
 440
 441 static inline void adf_vsync_get(struct adf_interface *intf)
 442 {
 443         adf_event_get(&intf->base, ADF_EVENT_VSYNC);
 444 }
 445
 446 static inline void adf_vsync_put(struct adf_interface *intf)
 447 {
 448         adf_event_put(&intf->base, ADF_EVENT_VSYNC);
 449 }
 450
 451 int adf_vsync_wait(struct adf_interface *intf, long timeout);
 452 void adf_vsync_notify(struct adf_interface *intf, ktime_t timestamp);
 453
 454 int adf_hotplug_notify_connected(struct adf_interface *intf,
 455                 struct drm_mode_modeinfo *modelist, size_t n_modes);
 456 void adf_hotplug_notify_disconnected(struct adf_interface *intf);
 457
 458 #endif /* _VIDEO_ADF_H */