From 140d88165c25137e871f9559e67986ed89251105 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Wed, 18 Aug 2010 11:41:22 -0300 Subject: [PATCH] [media] media: Media device information query Create the following ioctl and implement it at the media device level to query device information. - MEDIA_IOC_DEVICE_INFO: Query media device information The ioctl and its data structure are defined in the new kernel header linux/media.h available to userspace applications. Signed-off-by: Laurent Pinchart Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media-entities.tmpl | 12 ++ .../DocBook/v4l/media-controller.xml | 10 ++ .../DocBook/v4l/media-func-close.xml | 59 ++++++++ .../DocBook/v4l/media-func-ioctl.xml | 116 +++++++++++++++ Documentation/DocBook/v4l/media-func-open.xml | 94 +++++++++++++ .../DocBook/v4l/media-ioc-device-info.xml | 132 ++++++++++++++++++ drivers/media/media-device.c | 57 ++++++++ include/linux/Kbuild | 1 + include/linux/media.h | 45 ++++++ 9 files changed, 526 insertions(+) create mode 100644 Documentation/DocBook/v4l/media-func-close.xml create mode 100644 Documentation/DocBook/v4l/media-func-ioctl.xml create mode 100644 Documentation/DocBook/v4l/media-func-open.xml create mode 100644 Documentation/DocBook/v4l/media-ioc-device-info.xml create mode 100644 include/linux/media.h diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index c47897f046b1..034f891399ed 100644 --- a/Documentation/DocBook/media-entities.tmpl +++ b/Documentation/DocBook/media-entities.tmpl @@ -11,6 +11,10 @@ select()"> write()"> +close()"> +ioctl()"> +open()"> + VIDIOC_CROPCAP"> VIDIOC_DBG_G_CHIP_IDENT"> @@ -87,6 +91,8 @@ VIDIOC_TRY_FMT"> VIDIOC_UNSUBSCRIBE_EVENT"> +MEDIA_IOC_DEVICE_INFO"> + v4l2_std_id"> @@ -184,6 +190,8 @@ v4l2_vbi_format"> v4l2_window"> +media_device_info"> + EACCES error code"> EAGAIN error code"> @@ -328,6 +336,10 @@ + + + + diff --git a/Documentation/DocBook/v4l/media-controller.xml b/Documentation/DocBook/v4l/media-controller.xml index f89228d3ec2a..a46b786e9f2b 100644 --- a/Documentation/DocBook/v4l/media-controller.xml +++ b/Documentation/DocBook/v4l/media-controller.xml @@ -74,3 +74,13 @@ pad to a sink pad. + + + Function Reference + + &sub-media-open; + &sub-media-close; + &sub-media-ioctl; + + &sub-media-ioc-device-info; + diff --git a/Documentation/DocBook/v4l/media-func-close.xml b/Documentation/DocBook/v4l/media-func-close.xml new file mode 100644 index 000000000000..be149c802aeb --- /dev/null +++ b/Documentation/DocBook/v4l/media-func-close.xml @@ -0,0 +1,59 @@ + + + media close() + &manvol; + + + + media-close + Close a media device + + + + + #include <unistd.h> + + int close + int fd + + + + + + Arguments + + + + fd + + &fd; + + + + + + + Description + + Closes the media device. Resources associated with the file descriptor + are freed. The device configuration remain unchanged. + + + + Return Value + + close returns 0 on success. On error, -1 is + returned, and errno is set appropriately. Possible error + codes are: + + + + EBADF + + fd is not a valid open file descriptor. + + + + + + diff --git a/Documentation/DocBook/v4l/media-func-ioctl.xml b/Documentation/DocBook/v4l/media-func-ioctl.xml new file mode 100644 index 000000000000..bda8604de15c --- /dev/null +++ b/Documentation/DocBook/v4l/media-func-ioctl.xml @@ -0,0 +1,116 @@ + + + media ioctl() + &manvol; + + + + media-ioctl + Control a media device + + + + + #include <sys/ioctl.h> + + int ioctl + int fd + int request + void *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + Media ioctl request code as defined in the media.h header file, + for example MEDIA_IOC_SETUP_LINK. + + + + argp + + Pointer to a request-specific structure. + + + + + + + Description + The ioctl() function manipulates media device + parameters. The argument fd must be an open file + descriptor. + The ioctl request code specifies the media + function to be called. It has encoded in it whether the argument is an + input, output or read/write parameter, and the size of the argument + argp in bytes. + Macros and structures definitions specifying media ioctl requests and + their parameters are located in the media.h header file. All media ioctl + requests, their respective function and parameters are specified in + . + + + + Return Value + + ioctl() returns 0 on + success. On failure, -1 is returned, and the + errno variable is set appropriately. Generic error codes + are listed below, and request-specific error codes are listed in the + individual requests descriptions. + When an ioctl that takes an output or read/write parameter fails, + the parameter remains unmodified. + + + + EBADF + + fd is not a valid open file descriptor. + + + + + EFAULT + + argp references an inaccessible memory + area. + + + + EINVAL + + The request or the data pointed to by + argp is not valid. This is a very common error + code, see the individual ioctl requests listed in + for actual causes. + + + + ENOMEM + + Insufficient kernel memory was available to complete the + request. + + + + ENOTTY + + fd is not associated with a character + special device. + + + + + diff --git a/Documentation/DocBook/v4l/media-func-open.xml b/Documentation/DocBook/v4l/media-func-open.xml new file mode 100644 index 000000000000..f7df034dc9ed --- /dev/null +++ b/Documentation/DocBook/v4l/media-func-open.xml @@ -0,0 +1,94 @@ + + + media open() + &manvol; + + + + media-open + Open a media device + + + + + #include <fcntl.h> + + int open + const char *device_name + int flags + + + + + + Arguments + + + + device_name + + Device to be opened. + + + + flags + + Open flags. Access mode must be either O_RDONLY + or O_RDWR. Other flags have no effect. + + + + + + Description + To open a media device applications call open() + with the desired device name. The function has no side effects; the device + configuration remain unchanged. + When the device is opened in read-only mode, attemps to modify its + configuration will result in an error, and errno will be + set to EBADF. + + + Return Value + + open returns the new file descriptor on success. + On error, -1 is returned, and errno is set appropriately. + Possible error codes are: + + + + EACCES + + The requested access to the file is not allowed. + + + + EMFILE + + The process already has the maximum number of files open. + + + + + ENFILE + + The system limit on the total number of open files has been + reached. + + + + ENOMEM + + Insufficient kernel memory was available. + + + + ENXIO + + No device corresponding to this device special file exists. + + + + + + diff --git a/Documentation/DocBook/v4l/media-ioc-device-info.xml b/Documentation/DocBook/v4l/media-ioc-device-info.xml new file mode 100644 index 000000000000..278a3120ee2e --- /dev/null +++ b/Documentation/DocBook/v4l/media-ioc-device-info.xml @@ -0,0 +1,132 @@ + + + ioctl MEDIA_IOC_DEVICE_INFO + &manvol; + + + + MEDIA_IOC_DEVICE_INFO + Query device information + + + + + + int ioctl + int fd + int request + struct media_device_info *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + MEDIA_IOC_DEVICE_INFO + + + + argp + + + + + + + + + Description + + All media devices must support the MEDIA_IOC_DEVICE_INFO + ioctl. To query device information, applications call the ioctl with a + pointer to a &media-device-info;. The driver fills the structure and returns + the information to the application. + The ioctl never fails. + + + struct <structname>media_device_info</structname> + + &cs-str; + + + char + driver[16] + Name of the driver implementing the media API as a + NUL-terminated ASCII string. The driver version is stored in the + driver_version field. + Driver specific applications can use this information to + verify the driver identity. It is also useful to work around + known bugs, or to identify drivers in error reports. + + + char + model[32] + Device model name as a NUL-terminated UTF-8 string. The + device version is stored in the device_version + field and is not be appended to the model name. + + + char + serial[40] + Serial number as a NUL-terminated ASCII string. + + + char + bus_info[32] + Location of the device in the system as a NUL-terminated + ASCII string. This includes the bus type name (PCI, USB, ...) and a + bus-specific identifier. + + + __u32 + media_version + Media API version, formatted with the + KERNEL_VERSION() macro. + + + __u32 + hw_revision + Hardware device revision in a driver-specific format. + + + __u32 + media_version + Media device driver version, formatted with the + KERNEL_VERSION() macro. Together with the + driver field this identifies a particular + driver. + + + __u32 + reserved[31] + Reserved for future extensions. Drivers and applications must + set this array to zero. + + + +
+ The serial and bus_info + fields can be used to distinguish between multiple instances of otherwise + identical hardware. The serial number takes precedence when provided and can + be assumed to be unique. If the serial number is an empty string, the + bus_info field can be used instead. The + bus_info field is guaranteed to be unique, but + can vary across reboots or device unplug/replug. + + + + Return value + This function doesn't return specific error codes. + + diff --git a/drivers/media/media-device.c b/drivers/media/media-device.c index d2bc809d7a2a..92e0d4eb84b8 100644 --- a/drivers/media/media-device.c +++ b/drivers/media/media-device.c @@ -22,13 +22,70 @@ #include #include +#include #include #include #include +/* ----------------------------------------------------------------------------- + * Userspace API + */ + +static int media_device_open(struct file *filp) +{ + return 0; +} + +static int media_device_close(struct file *filp) +{ + return 0; +} + +static int media_device_get_info(struct media_device *dev, + struct media_device_info __user *__info) +{ + struct media_device_info info; + + memset(&info, 0, sizeof(info)); + + strlcpy(info.driver, dev->dev->driver->name, sizeof(info.driver)); + strlcpy(info.model, dev->model, sizeof(info.model)); + strlcpy(info.serial, dev->serial, sizeof(info.serial)); + strlcpy(info.bus_info, dev->bus_info, sizeof(info.bus_info)); + + info.media_version = MEDIA_API_VERSION; + info.hw_revision = dev->hw_revision; + info.driver_version = dev->driver_version; + + return copy_to_user(__info, &info, sizeof(*__info)); +} + +static long media_device_ioctl(struct file *filp, unsigned int cmd, + unsigned long arg) +{ + struct media_devnode *devnode = media_devnode_data(filp); + struct media_device *dev = to_media_device(devnode); + long ret; + + switch (cmd) { + case MEDIA_IOC_DEVICE_INFO: + ret = media_device_get_info(dev, + (struct media_device_info __user *)arg); + break; + + default: + ret = -ENOIOCTLCMD; + } + + return ret; +} + static const struct media_file_operations media_device_fops = { .owner = THIS_MODULE, + .open = media_device_open, + .ioctl = media_device_ioctl, + .release = media_device_close, }; /* ----------------------------------------------------------------------------- diff --git a/include/linux/Kbuild b/include/linux/Kbuild index b0ada6f37dd6..31eb174a2267 100644 --- a/include/linux/Kbuild +++ b/include/linux/Kbuild @@ -233,6 +233,7 @@ header-y += magic.h header-y += major.h header-y += map_to_7segment.h header-y += matroxfb.h +header-y += media.h header-y += mempolicy.h header-y += meye.h header-y += mii.h diff --git a/include/linux/media.h b/include/linux/media.h new file mode 100644 index 000000000000..64090db3c1fc --- /dev/null +++ b/include/linux/media.h @@ -0,0 +1,45 @@ +/* + * Multimedia device API + * + * Copyright (C) 2010 Nokia Corporation + * + * Contacts: Laurent Pinchart + * Sakari Ailus + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License version 2 as + * published by the Free Software Foundation. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +#ifndef __LINUX_MEDIA_H +#define __LINUX_MEDIA_H + +#include +#include +#include + +#define MEDIA_API_VERSION KERNEL_VERSION(0, 1, 0) + +struct media_device_info { + char driver[16]; + char model[32]; + char serial[40]; + char bus_info[32]; + __u32 media_version; + __u32 hw_revision; + __u32 driver_version; + __u32 reserved[31]; +}; + +#define MEDIA_IOC_DEVICE_INFO _IOWR('M', 1, struct media_device_info) + +#endif /* __LINUX_MEDIA_H */ -- 2.39.5