[Documentation]: Update probing info in sbus_drivers.txt

Signed-off-by: David S. Miller <davem@davemloft.net>

[Documentation]: Update probing info in sbus_drivers.txt
Signed-off-by: David S. Miller <davem@davemloft.net>
David S. Miller
1 parent 3d4253d9af
Showing 1 changed file with 65 additions and 30 deletions Side-by-side Diff
Documentation/sparc/sbus_drivers.txt
@@ -25,43 +25,85 @@
 used members of this structure, and their typical usage,
 will be detailed below.
  
-	Here is how probing is performed by an SBUS driver
-under Linux:
+	Here is a piece of skeleton code for perofming a device
+probe in an SBUS driverunder Linux:
  
-	static void init_one_mydevice(struct sbus_dev *sdev)
+	static int __devinit mydevice_probe_one(struct sbus_dev *sdev)
 	{
+		struct mysdevice *mp = kzalloc(sizeof(*mp), GFP_KERNEL);
+
+		if (!mp)
+			return -ENODEV;
+
 		...
+		dev_set_drvdata(&sdev->ofdev.dev, mp);
+		return 0;
+		...
 	}
  
-	static int mydevice_match(struct sbus_dev *sdev)
+	static int __devinit mydevice_probe(struct of_device *dev,
+				            const struct of_device_id *match)
 	{
-		if (some_criteria(sdev))
-			return 1;
-		return 0;
+		struct sbus_dev *sdev = to_sbus_device(&dev->dev);
+
+		return mydevice_probe_one(sdev);
 	}
  
-	static void mydevice_probe(void)
+	static int __devexit mydevice_remove(struct of_device *dev)
 	{
-		struct sbus_bus *sbus;
-		struct sbus_dev *sdev;
+		struct sbus_dev *sdev = to_sbus_device(&dev->dev);
+		struct mydevice *mp = dev_get_drvdata(&dev->dev);
  
-		for_each_sbus(sbus) {
-			for_each_sbusdev(sdev, sbus) {
-				if (mydevice_match(sdev))
-					init_one_mydevice(sdev);
-			}
-		}
+		return mydevice_remove_one(sdev, mp);
 	}
  
-	All this does is walk through all SBUS devices in the
-system, checks each to see if it is of the type which
-your driver is written for, and if so it calls the init
-routine to attach the device and prepare to drive it.
+	static struct of_device_id mydevice_match[] = {
+		{
+			.name = "mydevice",
+		},
+		{},
+	};
  
-	"init_one_mydevice" might do things like allocate software
-state structures, map in I/O registers, place the hardware
-into an initialized state, etc.
+	MODULE_DEVICE_TABLE(of, mydevice_match);
  
+	static struct of_platform_driver mydevice_driver = {
+		.name		= "mydevice",
+		.match_table	= mydevice_match,
+		.probe		= mydevice_probe,
+		.remove		= __devexit_p(mydevice_remove),
+	};
+
+	static int __init mydevice_init(void)
+	{
+		return of_register_driver(&mydevice_driver, &sbus_bus_type);
+	}
+
+	static void __exit mydevice_exit(void)
+	{
+		of_unregister_driver(&mydevice_driver);
+	}
+
+	module_init(mydevice_init);
+	module_exit(mydevice_exit);
+
+	The mydevice_match table is a series of entries which
+describes what SBUS devices your driver is meant for.  In the
+simplest case you specify a string for the 'name' field.  Every
+SBUS device with a 'name' property matching your string will
+be passed one-by-one to your .probe method.
+
+	You should store away your device private state structure
+pointer in the drvdata area so that you can retrieve it later on
+in your .remove method.
+
+	Any memory allocated, registers mapped, IRQs registered,
+etc. must be undone by your .remove method so that all resources
+of your device are relased by the time it returns.
+
+	You should _NOT_ use the for_each_sbus(), for_each_sbusdev(),
+and for_all_sbusdev() interfaces.  They are deprecated, will be
+removed, and no new driver should reference them ever.
+
 		Mapping and Accessing I/O Registers
  
 	Each SBUS device structure contains an array of descriptors
@@ -263,11 +305,4 @@
 	Lance driver abuses consistent mappings for data transfer.
 It is a nifty trick which we do not particularly recommend...
 Just check it out and know that it's legal.
-
-			Bad examples, do NOT use
-
-	drivers/video/cgsix.c
-	This one uses result of sbus_ioremap as if it is an address.
-This does NOT work on sparc64 and therefore is broken. We will
-convert it at a later date.
...	...	@@ -25,43 +25,85 @@
25	25	used members of this structure, and their typical usage,
26	26	will be detailed below.
27	27
28		- Here is how probing is performed by an SBUS driver
29		-under Linux:
	28	+ Here is a piece of skeleton code for perofming a device
	29	+probe in an SBUS driverunder Linux:
30	30
31		- static void init_one_mydevice(struct sbus_dev *sdev)
	31	+ static int __devinit mydevice_probe_one(struct sbus_dev *sdev)
32	32	{
	33	+ struct mysdevice mp = kzalloc(sizeof(mp), GFP_KERNEL);
	34	+
	35	+ if (!mp)
	36	+ return -ENODEV;
	37	+
33	38	...
	39	+ dev_set_drvdata(&sdev->ofdev.dev, mp);
	40	+ return 0;
	41	+ ...
34	42	}
35	43
36		- static int mydevice_match(struct sbus_dev *sdev)
	44	+ static int __devinit mydevice_probe(struct of_device *dev,
	45	+ const struct of_device_id *match)
37	46	{
38		- if (some_criteria(sdev))
39		- return 1;
40		- return 0;
	47	+ struct sbus_dev *sdev = to_sbus_device(&dev->dev);
	48	+
	49	+ return mydevice_probe_one(sdev);
41	50	}
42	51
43		- static void mydevice_probe(void)
	52	+ static int __devexit mydevice_remove(struct of_device *dev)
44	53	{
45		- struct sbus_bus *sbus;
46		- struct sbus_dev *sdev;
	54	+ struct sbus_dev *sdev = to_sbus_device(&dev->dev);
	55	+ struct mydevice *mp = dev_get_drvdata(&dev->dev);
47	56
48		- for_each_sbus(sbus) {
49		- for_each_sbusdev(sdev, sbus) {
50		- if (mydevice_match(sdev))
51		- init_one_mydevice(sdev);
52		- }
53		- }
	57	+ return mydevice_remove_one(sdev, mp);
54	58	}
55	59
56		- All this does is walk through all SBUS devices in the
57		-system, checks each to see if it is of the type which
58		-your driver is written for, and if so it calls the init
59		-routine to attach the device and prepare to drive it.
	60	+ static struct of_device_id mydevice_match[] = {
	61	+ {
	62	+ .name = "mydevice",
	63	+ },
	64	+ {},
	65	+ };
60	66
61		- "init_one_mydevice" might do things like allocate software
62		-state structures, map in I/O registers, place the hardware
63		-into an initialized state, etc.
	67	+ MODULE_DEVICE_TABLE(of, mydevice_match);
64	68
	69	+ static struct of_platform_driver mydevice_driver = {
	70	+ .name = "mydevice",
	71	+ .match_table = mydevice_match,
	72	+ .probe = mydevice_probe,
	73	+ .remove = __devexit_p(mydevice_remove),
	74	+ };
	75	+
	76	+ static int __init mydevice_init(void)
	77	+ {
	78	+ return of_register_driver(&mydevice_driver, &sbus_bus_type);
	79	+ }
	80	+
	81	+ static void __exit mydevice_exit(void)
	82	+ {
	83	+ of_unregister_driver(&mydevice_driver);
	84	+ }
	85	+
	86	+ module_init(mydevice_init);
	87	+ module_exit(mydevice_exit);
	88	+
	89	+ The mydevice_match table is a series of entries which
	90	+describes what SBUS devices your driver is meant for. In the
	91	+simplest case you specify a string for the 'name' field. Every
	92	+SBUS device with a 'name' property matching your string will
	93	+be passed one-by-one to your .probe method.
	94	+
	95	+ You should store away your device private state structure
	96	+pointer in the drvdata area so that you can retrieve it later on
	97	+in your .remove method.
	98	+
	99	+ Any memory allocated, registers mapped, IRQs registered,
	100	+etc. must be undone by your .remove method so that all resources
	101	+of your device are relased by the time it returns.
	102	+
	103	+ You should _NOT_ use the for_each_sbus(), for_each_sbusdev(),
	104	+and for_all_sbusdev() interfaces. They are deprecated, will be
	105	+removed, and no new driver should reference them ever.
	106	+
65	107	Mapping and Accessing I/O Registers
66	108
67	109	Each SBUS device structure contains an array of descriptors
...	...	@@ -263,11 +305,4 @@
263	305	Lance driver abuses consistent mappings for data transfer.
264	306	It is a nifty trick which we do not particularly recommend...
265	307	Just check it out and know that it's legal.
266		-
267		- Bad examples, do NOT use
268		-
269		- drivers/video/cgsix.c
270		- This one uses result of sbus_ioremap as if it is an address.
271		-This does NOT work on sparc64 and therefore is broken. We will
272		-convert it at a later date.