Open/Close, File Operations and IOCTLs

Open and Close
File Operations
IOCTLs

Open and Close

int (*firstopen) (struct drm_device *);
void (*lastclose) (struct drm_device *);
int (*open) (struct drm_device *, struct drm_file *);
void (*preclose) (struct drm_device *, struct drm_file *);
void (*postclose) (struct drm_device *, struct drm_file *);
Open and close handlers. None of those methods are mandatory.

The firstopen method is called by the DRM core when an application opens a device that has no other opened file handle. Similarly the lastclose method is called when the last application holding a file handle opened on the device closes it. Both methods are mostly used for UMS (User Mode Setting) drivers to acquire and release device resources which should be done in the load and unload methods for KMS drivers.

Note that the lastclose method is also called at module unload time or, for hot-pluggable devices, when the device is unplugged. The firstopen and lastclose calls can thus be unbalanced.

The open method is called every time the device is opened by an application. Drivers can allocate per-file private data in this method and store them in the struct drm_file driver_priv field. Note that the open method is called before firstopen.

The close operation is split into preclose and postclose methods. Drivers must stop and cleanup all per-file operations in the preclose method. For instance pending vertical blanking and page flip events must be cancelled. No per-file operation is allowed on the file handle after returning from the preclose method.

Finally the postclose method is called as the last step of the close operation, right before calling the lastclose method if no other open file handle exists for the device. Drivers that have allocated per-file private data in the open method should free it here.

The lastclose method should restore CRTC and plane properties to default value, so that a subsequent open of the device will not inherit state from the previous user.

File Operations

const struct file_operations *fops
File operations for the DRM device node.

Drivers must define the file operations structure that forms the DRM userspace API entry point, even though most of those operations are implemented in the DRM core. The open, release and ioctl operations are handled by

	.owner = THIS_MODULE,
	.open = drm_open,
	.release = drm_release,
	.unlocked_ioctl = drm_ioctl,
  #ifdef CONFIG_COMPAT
	.compat_ioctl = drm_compat_ioctl,
  #endif
        

Drivers that implement private ioctls that requires 32/64bit compatibility support must provide their own compat_ioctl handler that processes private ioctls and calls drm_compat_ioctl for core ioctls.

The read and poll operations provide support for reading DRM events and polling them. They are implemented by

	.poll = drm_poll,
	.read = drm_read,
	.fasync = drm_fasync,
	.llseek = no_llseek,
	

The memory mapping implementation varies depending on how the driver manages memory. Pre-GEM drivers will use drm_mmap, while GEM-aware drivers will use drm_gem_mmap. See the section called “The Graphics Execution Manager (GEM)”.

	.mmap = drm_gem_mmap,
	

No other file operation is supported by the DRM API.

IOCTLs

struct drm_ioctl_desc *ioctls;
int num_ioctls;
Driver-specific ioctls descriptors table.

Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls descriptors table is indexed by the ioctl number offset from the base value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the table entries.

DRM_IOCTL_DEF_DRV(ioctl, func, flags)

ioctl is the ioctl name. Drivers must define the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number offset from DRM_COMMAND_BASE and the ioctl number respectively. The first macro is private to the device while the second must be exposed to userspace in a public header.

func is a pointer to the ioctl handler function compatible with the drm_ioctl_t type.

typedef int drm_ioctl_t(struct drm_device *dev, void *data,
		struct drm_file *file_priv);

flags is a bitmask combination of the following values. It restricts how the ioctl is allowed to be called.

  • DRM_AUTH - Only authenticated callers allowed

  • DRM_MASTER - The ioctl can only be called on the master file handle

  • DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed

  • DRM_CONTROL_ALLOW - The ioctl can only be called on a control device

  • DRM_UNLOCKED - The ioctl handler will be called without locking the DRM global mutex