V4L/DVB (12417): I2C cleanups and version checks

The structure and comments of the I2C part have been adopted to fit to the
USB part.

Some additional cleanups and precisements have been made to the version
detection and checking functionality to clearly separate HW/SW/FW version.

Signed-off-by: Tobias Lorenz <tobias.lorenz@gmx.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

3 files changed, 257 insertions, 76 deletions

diff --git a/drivers/media/radio/si470x/radio-si470x-i2c.c b/drivers/media/radio/si470x/radio-si470x-i2c.c
index 218102184702..2d53b6a9409b 100644
--- a/drivers/media/radio/si470x/radio-si470x-i2c.c
+++ b/drivers/media/radio/si470x/radio-si470x-i2c.c
@@ -3,53 +3,88 @@
  *
  * I2C driver for radios with Silicon Labs Si470x FM Radio Receivers
  *
- * Copyright (C) 2009 Samsung Electronics Co.Ltd
+ * Copyright (c) 2009 Samsung Electronics Co.Ltd
  * Author: Joonyoung Shim <jy0922.shim@samsung.com>
  *
- *  This program is free software; you can redistribute  it and/or modify it
- *  under  the terms of  the GNU General  Public License as published by the
- *  Free Software Foundation;  either version 2 of the  License, or (at your
- *  option) any later version.
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
  *
+ * 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.
  *
- * TODO:
+ * 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
+ */
+
+
+/*
+ * ToDo:
  * - RDS support
- *
  */
 
-#include <linux/module.h>
-#include <linux/init.h>
+
+/* driver definitions */
+#define DRIVER_AUTHOR "Joonyoung Shim <jy0922.shim@samsung.com>";
+#define DRIVER_KERNEL_VERSION KERNEL_VERSION(1, 0, 0)
+#define DRIVER_CARD "Silicon Labs Si470x FM Radio Receiver"
+#define DRIVER_DESC "I2C radio driver for Si470x FM Radio Receivers"
+#define DRIVER_VERSION "1.0.0"
+
+/* kernel includes */
 #include <linux/i2c.h>
 #include <linux/delay.h>
 
 #include "radio-si470x.h"
 
-#define DRIVER_KERNEL_VERSION	KERNEL_VERSION(1, 0, 0)
-#define DRIVER_CARD		"Silicon Labs Si470x FM Radio Receiver"
-#define DRIVER_VERSION		"1.0.0"
 
-/* starting with the upper byte of register 0x0a */
+/* I2C Device ID List */
+static const struct i2c_device_id si470x_i2c_id[] = {
+	/* Generic Entry */
+	{ "si470x", 0 },
+	/* Terminating entry */
+	{ }
+};
+MODULE_DEVICE_TABLE(i2c, si470x_i2c_id);
+
+
+
+/**************************************************************************
+ * Module Parameters
+ **************************************************************************/
+
+/* Radio Nr */
+static int radio_nr = -1;
+module_param(radio_nr, int, 0444);
+MODULE_PARM_DESC(radio_nr, "Radio Nr");
+
+
+
+/**************************************************************************
+ * I2C Definitions
+ **************************************************************************/
+
+/* Write starts with the upper byte of register 0x02 */
+#define WRITE_REG_NUM		8
+#define WRITE_INDEX(i)		(i + 0x02)
+
+/* Read starts with the upper byte of register 0x0a */
 #define READ_REG_NUM		RADIO_REGISTER_NUM
 #define READ_INDEX(i)		((i + RADIO_REGISTER_NUM - 0x0a) % READ_REG_NUM)
 
-static int si470x_get_all_registers(struct si470x_device *radio)
-{
-	int i;
-	u16 buf[READ_REG_NUM];
-	struct i2c_msg msgs[1] = {
-		{ radio->client->addr, I2C_M_RD, sizeof(u16) * READ_REG_NUM,
-			(void *)buf },
-	};
-
-	if (i2c_transfer(radio->client->adapter, msgs, 1) != 1)
-		return -EIO;
 
-	for (i = 0; i < READ_REG_NUM; i++)
-		radio->registers[i] = __be16_to_cpu(buf[READ_INDEX(i)]);
 
-	return 0;
-}
+/**************************************************************************
+ * General Driver Functions - REGISTERs
+ **************************************************************************/
 
+/*
+ * si470x_get_register - read register
+ */
 int si470x_get_register(struct si470x_device *radio, int regnr)
 {
 	u16 buf[READ_REG_NUM];
@@ -66,10 +101,10 @@ int si470x_get_register(struct si470x_device *radio, int regnr)
 	return 0;
 }
 
-/* starting with the upper byte of register 0x02h */
-#define WRITE_REG_NUM		8
-#define WRITE_INDEX(i)		(i + 0x02)
 
+/*
+ * si470x_set_register - write register
+ */
 int si470x_set_register(struct si470x_device *radio, int regnr)
 {
 	int i;
@@ -88,11 +123,56 @@ int si470x_set_register(struct si470x_device *radio, int regnr)
 	return 0;
 }
 
+
+
+/**************************************************************************
+ * General Driver Functions - ENTIRE REGISTERS
+ **************************************************************************/
+
+/*
+ * si470x_get_all_registers - read entire registers
+ */
+static int si470x_get_all_registers(struct si470x_device *radio)
+{
+	int i;
+	u16 buf[READ_REG_NUM];
+	struct i2c_msg msgs[1] = {
+		{ radio->client->addr, I2C_M_RD, sizeof(u16) * READ_REG_NUM,
+			(void *)buf },
+	};
+
+	if (i2c_transfer(radio->client->adapter, msgs, 1) != 1)
+		return -EIO;
+
+	for (i = 0; i < READ_REG_NUM; i++)
+		radio->registers[i] = __be16_to_cpu(buf[READ_INDEX(i)]);
+
+	return 0;
+}
+
+
+
+/**************************************************************************
+ * General Driver Functions - DISCONNECT_CHECK
+ **************************************************************************/
+
+/*
+ * si470x_disconnect_check - check whether radio disconnects
+ */
 int si470x_disconnect_check(struct si470x_device *radio)
 {
 	return 0;
 }
 
+
+
+/**************************************************************************
+ * File Operations Interface
+ **************************************************************************/
+
+/*
+ * si470x_fops_open - file open
+ */
 static int si470x_fops_open(struct file *file)
 {
 	struct si470x_device *radio = video_drvdata(file);
@@ -104,11 +184,16 @@ static int si470x_fops_open(struct file *file)
 	if (radio->users == 1)
 		/* start radio */
 		retval = si470x_start(radio);
+
 	mutex_unlock(&radio->lock);
 
 	return retval;
 }
 
+
+/*
+ * si470x_fops_release - file release
+ */
 static int si470x_fops_release(struct file *file)
 {
 	struct si470x_device *radio = video_drvdata(file);
@@ -123,11 +208,16 @@ static int si470x_fops_release(struct file *file)
 	if (radio->users == 0)
 		/* stop radio */
 		retval = si470x_stop(radio);
+
 	mutex_unlock(&radio->lock);
 
 	return retval;
 }
 
+
+/*
+ * si470x_fops - file operations interface
+ */
 const struct v4l2_file_operations si470x_fops = {
 	.owner		= THIS_MODULE,
 	.ioctl		= video_ioctl2,
@@ -135,6 +225,15 @@ const struct v4l2_file_operations si470x_fops = {
 	.release	= si470x_fops_release,
 };
 
+
+
+/**************************************************************************
+ * Video4Linux Interface
+ **************************************************************************/
+
+/*
+ * si470x_vidioc_querycap - query device capabilities
+ */
 int si470x_vidioc_querycap(struct file *file, void *priv,
 		struct v4l2_capability *capability)
 {
@@ -147,11 +246,21 @@ int si470x_vidioc_querycap(struct file *file, void *priv,
 	return 0;
 }
 
+
+
+/**************************************************************************
+ * I2C Interface
+ **************************************************************************/
+
+/*
+ * si470x_i2c_probe - probe for the device
+ */
 static int __devinit si470x_i2c_probe(struct i2c_client *client,
 		const struct i2c_device_id *id)
 {
 	struct si470x_device *radio;
 	int retval = 0;
+	unsigned char version_warning = 0;
 
 	/* private data allocation and initialization */
 	radio = kzalloc(sizeof(struct si470x_device), GFP_KERNEL);
@@ -159,8 +268,8 @@ static int __devinit si470x_i2c_probe(struct i2c_client *client,
 		retval = -ENOMEM;
 		goto err_initial;
 	}
-	radio->client = client;
 	radio->users = 0;
+	radio->client = client;
 	mutex_init(&radio->lock);
 
 	/* video device allocation and initialization */
@@ -181,28 +290,47 @@ static int __devinit si470x_i2c_probe(struct i2c_client *client,
 	}
 	msleep(110);
 
-	/* show some infos about the specific si470x device */
+	/* get device and chip versions */
 	if (si470x_get_all_registers(radio) < 0) {
 		retval = -EIO;
-		goto err_radio;
+		goto err_video;
 	}
 	dev_info(&client->dev, "DeviceID=0x%4.4hx ChipID=0x%4.4hx\n",
 			radio->registers[DEVICEID], radio->registers[CHIPID]);
+	if ((radio->registers[CHIPID] & CHIPID_FIRMWARE) < RADIO_FW_VERSION) {
+		dev_warn(&client->dev,
+			"This driver is known to work with "
+			"firmware version %hu,\n", RADIO_FW_VERSION);
+		dev_warn(&client->dev,
+			"but the device has firmware version %hu.\n",
+			radio->registers[CHIPID] & CHIPID_FIRMWARE);
+		version_warning = 1;
+	}
+
+	/* give out version warning */
+	if (version_warning == 1) {
+		dev_warn(&client->dev,
+			"If you have some trouble using this driver,\n");
+		dev_warn(&client->dev,
+			"please report to V4L ML at "
+			"linux-media@vger.kernel.org\n");
+	}
 
 	/* set initial frequency */
 	si470x_set_freq(radio, 87.5 * FREQ_MUL); /* available in all regions */
 
 	/* register video device */
-	retval = video_register_device(radio->videodev, VFL_TYPE_RADIO, -1);
+	retval = video_register_device(radio->videodev, VFL_TYPE_RADIO,
+			radio_nr);
 	if (retval) {
 		dev_warn(&client->dev, "Could not register video device\n");
 		goto err_all;
 	}
-
 	i2c_set_clientdata(client, radio);
 
 	return 0;
 err_all:
+err_video:
 	video_device_release(radio->videodev);
 err_radio:
 	kfree(radio);
@@ -210,6 +338,10 @@ err_initial:
 	return retval;
 }
 
+
+/*
+ * si470x_i2c_remove - remove the device
+ */
 static __devexit int si470x_i2c_remove(struct i2c_client *client)
 {
 	struct si470x_device *radio = i2c_get_clientdata(client);
@@ -221,34 +353,49 @@ static __devexit int si470x_i2c_remove(struct i2c_client *client)
 	return 0;
 }
 
-static const struct i2c_device_id si470x_i2c_id[] = {
-	{ "si470x", 0 },
-	{ }
-};
-MODULE_DEVICE_TABLE(i2c, si470x_i2c_id);
 
+/*
+ * si470x_i2c_driver - i2c driver interface
+ */
 static struct i2c_driver si470x_i2c_driver = {
 	.driver = {
-		.name = "si470x",
-		.owner = THIS_MODULE,
+		.name		= "si470x",
+		.owner		= THIS_MODULE,
 	},
-	.probe = si470x_i2c_probe,
-	.remove = __devexit_p(si470x_i2c_remove),
-	.id_table = si470x_i2c_id,
+	.probe			= si470x_i2c_probe,
+	.remove			= __devexit_p(si470x_i2c_remove),
+	.id_table		= si470x_i2c_id,
 };
 
+
+
+/**************************************************************************
+ * Module Interface
+ **************************************************************************/
+
+/*
+ * si470x_i2c_init - module init
+ */
 static int __init si470x_i2c_init(void)
 {
+	printk(KERN_INFO DRIVER_DESC ", Version " DRIVER_VERSION "\n");
 	return i2c_add_driver(&si470x_i2c_driver);
 }
-module_init(si470x_i2c_init);
 
+
+/*
+ * si470x_i2c_exit - module exit
+ */
 static void __exit si470x_i2c_exit(void)
 {
 	i2c_del_driver(&si470x_i2c_driver);
 }
+
+
+module_init(si470x_i2c_init);
 module_exit(si470x_i2c_exit);
 
-MODULE_DESCRIPTION("i2c radio driver for si470x fm radio receivers");
-MODULE_AUTHOR("Joonyoung Shim <jy0922.shim@samsung.com>");
 MODULE_LICENSE("GPL");
+MODULE_AUTHOR(DRIVER_AUTHOR);
+MODULE_DESCRIPTION(DRIVER_DESC);
+MODULE_VERSION(DRIVER_VERSION);
diff --git a/drivers/media/radio/si470x/radio-si470x-usb.c b/drivers/media/radio/si470x/radio-si470x-usb.c
index 2f5cf6c7234d..f2d0e1ddb301 100644
--- a/drivers/media/radio/si470x/radio-si470x-usb.c
+++ b/drivers/media/radio/si470x/radio-si470x-usb.c
@@ -138,16 +138,12 @@ MODULE_PARM_DESC(max_rds_errors, "RDS maximum block errors: *1*");
 
 
 /**************************************************************************
- * Software/Hardware Versions
+ * Software/Hardware Versions from Scratch Page
  **************************************************************************/
 #define RADIO_SW_VERSION_NOT_BOOTLOADABLE	6
 #define RADIO_SW_VERSION			7
-#define RADIO_SW_VERSION_CURRENT		15
 #define RADIO_HW_VERSION			1
 
-#define SCRATCH_PAGE_SW_VERSION	1
-#define SCRATCH_PAGE_HW_VERSION	2
-
 
 
 /**************************************************************************
@@ -745,6 +741,7 @@ static int si470x_usb_driver_probe(struct usb_interface *intf,
 	struct usb_host_interface *iface_desc;
 	struct usb_endpoint_descriptor *endpoint;
 	int i, int_end_size, retval = 0;
+	unsigned char version_warning = 0;
 
 	/* private data allocation and initialization */
 	radio = kzalloc(sizeof(struct si470x_device), GFP_KERNEL);
@@ -801,13 +798,22 @@ static int si470x_usb_driver_probe(struct usb_interface *intf,
 			sizeof(si470x_viddev_template));
 	video_set_drvdata(radio->videodev, radio);
 
-	/* show some infos about the specific si470x device */
+	/* get device and chip versions */
 	if (si470x_get_all_registers(radio) < 0) {
 		retval = -EIO;
 		goto err_video;
 	}
 	dev_info(&intf->dev, "DeviceID=0x%4.4hx ChipID=0x%4.4hx\n",
 			radio->registers[DEVICEID], radio->registers[CHIPID]);
+	if ((radio->registers[CHIPID] & CHIPID_FIRMWARE) < RADIO_FW_VERSION) {
+		dev_warn(&intf->dev,
+			"This driver is known to work with "
+			"firmware version %hu,\n", RADIO_FW_VERSION);
+		dev_warn(&intf->dev,
+			"but the device has firmware version %hu.\n",
+			radio->registers[CHIPID] & CHIPID_FIRMWARE);
+		version_warning = 1;
+	}
 
 	/* get software and hardware versions */
 	if (si470x_get_scratch_page_versions(radio) < 0) {
@@ -816,16 +822,27 @@ static int si470x_usb_driver_probe(struct usb_interface *intf,
 	}
 	dev_info(&intf->dev, "software version %d, hardware version %d\n",
 			radio->software_version, radio->hardware_version);
-
-	/* check if device and firmware is current */
-	if ((radio->registers[CHIPID] & CHIPID_FIRMWARE)
-			< RADIO_SW_VERSION_CURRENT) {
+	if (radio->software_version < RADIO_SW_VERSION) {
 		dev_warn(&intf->dev,
 			"This driver is known to work with "
-			"firmware version %hu,\n", RADIO_SW_VERSION_CURRENT);
+			"software version %hu,\n", RADIO_SW_VERSION);
 		dev_warn(&intf->dev,
-			"but the device has firmware version %hu.\n",
-			radio->registers[CHIPID] & CHIPID_FIRMWARE);
+			"but the device has software version %hu.\n",
+			radio->software_version);
+		version_warning = 1;
+	}
+	if (radio->hardware_version < RADIO_HW_VERSION) {
+		dev_warn(&intf->dev,
+			"This driver is known to work with "
+			"hardware version %hu,\n", RADIO_HW_VERSION);
+		dev_warn(&intf->dev,
+			"but the device has hardware version %hu.\n",
+			radio->hardware_version);
+		version_warning = 1;
+	}
+
+	/* give out version warning */
+	if (version_warning == 1) {
 		dev_warn(&intf->dev,
 			"If you have some trouble using this driver,\n");
 		dev_warn(&intf->dev,
diff --git a/drivers/media/radio/si470x/radio-si470x.h b/drivers/media/radio/si470x/radio-si470x.h
index 794112c759b8..d0af194d194c 100644
--- a/drivers/media/radio/si470x/radio-si470x.h
+++ b/drivers/media/radio/si470x/radio-si470x.h
@@ -41,6 +41,7 @@
 #include <asm/unaligned.h>
 
 
+
 /**************************************************************************
  * Register Definitions
  **************************************************************************/
@@ -133,6 +134,7 @@
 #define RDSD_RDSD		0xffff	/* bits 15..00: RDS Block D Data (Si4701 only) */
 
 
+
 /**************************************************************************
  * General Driver Definitions
  **************************************************************************/
@@ -143,9 +145,19 @@
 struct si470x_device {
 	struct video_device *videodev;
 
-#if defined(CONFIG_I2C_SI470X) || defined(CONFIG_I2C_SI470X_MODULE)
-	struct i2c_client *client;
-#endif
+	/* driver management */
+	unsigned int users;
+
+	/* Silabs internal registers (0..15) */
+	unsigned short registers[RADIO_REGISTER_NUM];
+
+	/* RDS receive buffer */
+	wait_queue_head_t read_queue;
+	struct mutex lock;		/* buffer locking */
+	unsigned char *buffer;		/* size is always multiple of three */
+	unsigned int buf_size;
+	unsigned int rd_index;
+	unsigned int wr_index;
 
 #if defined(CONFIG_USB_SI470X) || defined(CONFIG_USB_SI470X_MODULE)
 	/* reference to USB and video device */
@@ -166,21 +178,26 @@ struct si470x_device {
 	unsigned char disconnected;
 	struct mutex disconnect_lock;
 #endif
-	unsigned int users;
-
-	/* Silabs internal registers (0..15) */
-	unsigned short registers[RADIO_REGISTER_NUM];
 
-	/* RDS receive buffer */
-	wait_queue_head_t read_queue;
-	struct mutex lock;		/* buffer locking */
-	unsigned char *buffer;		/* size is always multiple of three */
-	unsigned int buf_size;
-	unsigned int rd_index;
-	unsigned int wr_index;
+#if defined(CONFIG_I2C_SI470X) || defined(CONFIG_I2C_SI470X_MODULE)
+	struct i2c_client *client;
+#endif
 };
 
 
+
+/**************************************************************************
+ * Firmware Versions
+ **************************************************************************/
+
+#define RADIO_FW_VERSION	15
+
+
+
+/**************************************************************************
+ * Frequency Multiplicator
+ **************************************************************************/
+
 /*
  * The frequency is set in units of 62.5 Hz when using V4L2_TUNER_CAP_LOW,
  * 62.5 kHz otherwise.