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>

1 files changed, 196 insertions, 49 deletions

diff --git a/drivers/media/radio/si470x/radio-si470x-i2c.c b/drivers/media/radio/si470x/radio-si470x-i2c.c
index 21810218470..2d53b6a9409 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);