About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / driver-model / platform.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	Platform Devices and Drivers
2	~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3	See <linux/platform_device.h> for the driver model interface to the
4	platform bus:  platform_device, and platform_driver.  This pseudo-bus
5	is used to connect devices on busses with minimal infrastructure,
6	like those used to integrate peripherals on many system-on-chip
7	processors, or some "legacy" PC interconnects; as opposed to large
8	formally specified ones like PCI or USB.
9	
10	
11	Platform devices
12	~~~~~~~~~~~~~~~~
13	Platform devices are devices that typically appear as autonomous
14	entities in the system. This includes legacy port-based devices and
15	host bridges to peripheral buses, and most controllers integrated
16	into system-on-chip platforms.  What they usually have in common
17	is direct addressing from a CPU bus.  Rarely, a platform_device will
18	be connected through a segment of some other kind of bus; but its
19	registers will still be directly addressable.
20	
21	Platform devices are given a name, used in driver binding, and a
22	list of resources such as addresses and IRQs.
23	
24	struct platform_device {
25		const char	*name;
26		u32		id;
27		struct device	dev;
28		u32		num_resources;
29		struct resource	*resource;
30	};
31	
32	
33	Platform drivers
34	~~~~~~~~~~~~~~~~
35	Platform drivers follow the standard driver model convention, where
36	discovery/enumeration is handled outside the drivers, and drivers
37	provide probe() and remove() methods.  They support power management
38	and shutdown notifications using the standard conventions.
39	
40	struct platform_driver {
41		int (*probe)(struct platform_device *);
42		int (*remove)(struct platform_device *);
43		void (*shutdown)(struct platform_device *);
44		int (*suspend)(struct platform_device *, pm_message_t state);
45		int (*suspend_late)(struct platform_device *, pm_message_t state);
46		int (*resume_early)(struct platform_device *);
47		int (*resume)(struct platform_device *);
48		struct device_driver driver;
49	};
50	
51	Note that probe() should in general verify that the specified device hardware
52	actually exists; sometimes platform setup code can't be sure.  The probing
53	can use device resources, including clocks, and device platform_data.
54	
55	Platform drivers register themselves the normal way:
56	
57		int platform_driver_register(struct platform_driver *drv);
58	
59	Or, in common situations where the device is known not to be hot-pluggable,
60	the probe() routine can live in an init section to reduce the driver's
61	runtime memory footprint:
62	
63		int platform_driver_probe(struct platform_driver *drv,
64				  int (*probe)(struct platform_device *))
65	
66	Kernel modules can be composed of several platform drivers. The platform core
67	provides helpers to register and unregister an array of drivers:
68	
69		int __platform_register_drivers(struct platform_driver * const *drivers,
70					      unsigned int count, struct module *owner);
71		void platform_unregister_drivers(struct platform_driver * const *drivers,
72						 unsigned int count);
73	
74	If one of the drivers fails to register, all drivers registered up to that
75	point will be unregistered in reverse order. Note that there is a convenience
76	macro that passes THIS_MODULE as owner parameter:
77	
78		#define platform_register_drivers(drivers, count)
79	
80	
81	Device Enumeration
82	~~~~~~~~~~~~~~~~~~
83	As a rule, platform specific (and often board-specific) setup code will
84	register platform devices:
85	
86		int platform_device_register(struct platform_device *pdev);
87	
88		int platform_add_devices(struct platform_device **pdevs, int ndev);
89	
90	The general rule is to register only those devices that actually exist,
91	but in some cases extra devices might be registered.  For example, a kernel
92	might be configured to work with an external network adapter that might not
93	be populated on all boards, or likewise to work with an integrated controller
94	that some boards might not hook up to any peripherals.
95	
96	In some cases, boot firmware will export tables describing the devices
97	that are populated on a given board.   Without such tables, often the
98	only way for system setup code to set up the correct devices is to build
99	a kernel for a specific target board.  Such board-specific kernels are
100	common with embedded and custom systems development.
101	
102	In many cases, the memory and IRQ resources associated with the platform
103	device are not enough to let the device's driver work.  Board setup code
104	will often provide additional information using the device's platform_data
105	field to hold additional information.
106	
107	Embedded systems frequently need one or more clocks for platform devices,
108	which are normally kept off until they're actively needed (to save power).
109	System setup also associates those clocks with the device, so that that
110	calls to clk_get(&pdev->dev, clock_name) return them as needed.
111	
112	
113	Legacy Drivers:  Device Probing
114	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115	Some drivers are not fully converted to the driver model, because they take
116	on a non-driver role:  the driver registers its platform device, rather than
117	leaving that for system infrastructure.  Such drivers can't be hotplugged
118	or coldplugged, since those mechanisms require device creation to be in a
119	different system component than the driver.
120	
121	The only "good" reason for this is to handle older system designs which, like
122	original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware
123	configuration.  Newer systems have largely abandoned that model, in favor of
124	bus-level support for dynamic configuration (PCI, USB), or device tables
125	provided by the boot firmware (e.g. PNPACPI on x86).  There are too many
126	conflicting options about what might be where, and even educated guesses by
127	an operating system will be wrong often enough to make trouble.
128	
129	This style of driver is discouraged.  If you're updating such a driver,
130	please try to move the device enumeration to a more appropriate location,
131	outside the driver.  This will usually be cleanup, since such drivers
132	tend to already have "normal" modes, such as ones using device nodes that
133	were created by PNP or by platform device setup.
134	
135	None the less, there are some APIs to support such legacy drivers.  Avoid
136	using these calls except with such hotplug-deficient drivers.
137	
138		struct platform_device *platform_device_alloc(
139				const char *name, int id);
140	
141	You can use platform_device_alloc() to dynamically allocate a device, which
142	you will then initialize with resources and platform_device_register().
143	A better solution is usually:
144	
145		struct platform_device *platform_device_register_simple(
146				const char *name, int id,
147				struct resource *res, unsigned int nres);
148	
149	You can use platform_device_register_simple() as a one-step call to allocate
150	and register a device.
151	
152	
153	Device Naming and Driver Binding
154	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155	The platform_device.dev.bus_id is the canonical name for the devices.
156	It's built from two components:
157	
158	    * platform_device.name ... which is also used to for driver matching.
159	
160	    * platform_device.id ... the device instance number, or else "-1"
161	      to indicate there's only one.
162	
163	These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and
164	"serial/3" indicates bus_id "serial.3"; both would use the platform_driver
165	named "serial".  While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id)
166	and use the platform_driver called "my_rtc".
167	
168	Driver binding is performed automatically by the driver core, invoking
169	driver probe() after finding a match between device and driver.  If the
170	probe() succeeds, the driver and device are bound as usual.  There are
171	three different ways to find such a match:
172	
173	    - Whenever a device is registered, the drivers for that bus are
174	      checked for matches.  Platform devices should be registered very
175	      early during system boot.
176	
177	    - When a driver is registered using platform_driver_register(), all
178	      unbound devices on that bus are checked for matches.  Drivers
179	      usually register later during booting, or by module loading.
180	
181	    - Registering a driver using platform_driver_probe() works just like
182	      using platform_driver_register(), except that the driver won't
183	      be probed later if another device registers.  (Which is OK, since
184	      this interface is only for use with non-hotpluggable devices.)
185	
186	
187	Early Platform Devices and Drivers
188	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189	The early platform interfaces provide platform data to platform device
190	drivers early on during the system boot. The code is built on top of the
191	early_param() command line parsing and can be executed very early on.
192	
193	Example: "earlyprintk" class early serial console in 6 steps
194	
195	1. Registering early platform device data
196	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
197	The architecture code registers platform device data using the function
198	early_platform_add_devices(). In the case of early serial console this
199	should be hardware configuration for the serial port. Devices registered
200	at this point will later on be matched against early platform drivers.
201	
202	2. Parsing kernel command line
203	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
204	The architecture code calls parse_early_param() to parse the kernel
205	command line. This will execute all matching early_param() callbacks.
206	User specified early platform devices will be registered at this point.
207	For the early serial console case the user can specify port on the
208	kernel command line as "earlyprintk=serial.0" where "earlyprintk" is
209	the class string, "serial" is the name of the platform driver and
210	0 is the platform device id. If the id is -1 then the dot and the
211	id can be omitted.
212	
213	3. Installing early platform drivers belonging to a certain class
214	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215	The architecture code may optionally force registration of all early
216	platform drivers belonging to a certain class using the function
217	early_platform_driver_register_all(). User specified devices from
218	step 2 have priority over these. This step is omitted by the serial
219	driver example since the early serial driver code should be disabled
220	unless the user has specified port on the kernel command line.
221	
222	4. Early platform driver registration
223	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
224	Compiled-in platform drivers making use of early_platform_init() are
225	automatically registered during step 2 or 3. The serial driver example
226	should use early_platform_init("earlyprintk", &platform_driver).
227	
228	5. Probing of early platform drivers belonging to a certain class
229	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
230	The architecture code calls early_platform_driver_probe() to match
231	registered early platform devices associated with a certain class with
232	registered early platform drivers. Matched devices will get probed().
233	This step can be executed at any point during the early boot. As soon
234	as possible may be good for the serial port case.
235	
236	6. Inside the early platform driver probe()
237	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
238	The driver code needs to take special care during early boot, especially
239	when it comes to memory allocation and interrupt registration. The code
240	in the probe() function can use is_early_platform_device() to check if
241	it is called at early platform device or at the regular platform device
242	time. The early serial driver performs register_console() at this point.
243	
244	For further information, see <linux/platform_device.h>.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog