/include/linux/spmi.h

  1/* Copyright (c) 2012, The Linux Foundation. All rights reserved.
  2 *
  3 * This program is free software; you can redistribute it and/or modify
  4 * it under the terms of the GNU General Public License version 2 and
  5 * only version 2 as published by the Free Software Foundation.
  6 *
  7 * This program is distributed in the hope that it will be useful,
  8 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 10 * GNU General Public License for more details.
 11 */
 12
 13#ifndef _LINUX_SPMI_H
 14#define _LINUX_SPMI_H
 15
 16#include <linux/types.h>
 17#include <linux/device.h>
 18#include <linux/mod_devicetable.h>
 19
 20/* Maximum slave identifier */
 21#define SPMI_MAX_SLAVE_ID		16
 22
 23/* SPMI Commands */
 24enum spmi_commands {
 25	SPMI_CMD_EXT_WRITE = 0x00,
 26	SPMI_CMD_RESET = 0x10,
 27	SPMI_CMD_SLEEP = 0x11,
 28	SPMI_CMD_SHUTDOWN = 0x12,
 29	SPMI_CMD_WAKEUP = 0x13,
 30	SPMI_CMD_AUTHENTICATE = 0x14,
 31	SPMI_CMD_MSTR_READ = 0x15,
 32	SPMI_CMD_MSTR_WRITE = 0x16,
 33	SPMI_CMD_TRANSFER_BUS_OWNERSHIP = 0x1A,
 34	SPMI_CMD_DDB_MASTER_READ = 0x1B,
 35	SPMI_CMD_DDB_SLAVE_READ = 0x1C,
 36	SPMI_CMD_EXT_READ = 0x20,
 37	SPMI_CMD_EXT_WRITEL = 0x30,
 38	SPMI_CMD_EXT_READL = 0x38,
 39	SPMI_CMD_WRITE = 0x40,
 40	SPMI_CMD_READ = 0x60,
 41	SPMI_CMD_ZERO_WRITE = 0x80,
 42};
 43
 44struct spmi_device;
 45
 46/**
 47 * struct spmi_controller: interface to the SPMI master controller
 48 * @nr: board-specific number identifier for this controller/bus
 49 * @name: name for this controller
 50 * @cmd: sends a non-data command sequence on the SPMI bus.
 51 * @read_cmd: sends a register read command sequence on the SPMI bus.
 52 * @write_cmd: sends a register write command sequence on the SPMI bus.
 53 */
 54struct spmi_controller {
 55	struct device		dev;
 56	unsigned int		nr;
 57	struct list_head	list;
 58	int		(*cmd)(struct spmi_controller *, u8 opcode, u8 sid);
 59	int		(*read_cmd)(struct spmi_controller *,
 60				u8 opcode, u8 sid, u16 addr, u8 bc, u8 *buf);
 61	int		(*write_cmd)(struct spmi_controller *,
 62				u8 opcode, u8 sid, u16 addr, u8 bc, u8 *buf);
 63};
 64#define to_spmi_controller(d) container_of(d, struct spmi_controller, dev)
 65
 66/**
 67 * struct spmi_driver: Manage SPMI generic/slave device driver
 68 * @probe: binds this driver to a SPMI device.
 69 * @remove: unbinds this driver from the SPMI device.
 70 * @shutdown: standard shutdown callback used during powerdown/halt.
 71 * @suspend: standard suspend callback used during system suspend
 72 * @resume: standard resume callback used during system resume
 73 * @driver: SPMI device drivers should initialize name and owner field of
 74 *	    this structure
 75 * @id_table: list of SPMI devices supported by this driver
 76 */
 77struct spmi_driver {
 78	int				(*probe)(struct spmi_device *dev);
 79	int				(*remove)(struct spmi_device *dev);
 80	void				(*shutdown)(struct spmi_device *dev);
 81	int				(*suspend)(struct spmi_device *dev,
 82					pm_message_t pmesg);
 83	int				(*resume)(struct spmi_device *dev);
 84
 85	struct device_driver		driver;
 86	const struct spmi_device_id	*id_table;
 87};
 88#define to_spmi_driver(d) container_of(d, struct spmi_driver, driver)
 89
 90/**
 91 * struct spmi_resource: spmi_resource for one device_node
 92 * @num_resources: number of resources for this device node
 93 * @resources: array of resources for this device_node
 94 * @of_node: device_node of the resource in question
 95 * @label: name used to reference the device from the driver
 96 *
 97 * Note that we explicitly add a 'label' pointer here since per
 98 * the ePAPR 2.2.2, the device_node->name should be generic and not
 99 * reflect precise programming model. Thus label enables a
100 * platform specific name to be assigned with the 'label' binding to
101 * allow for unique query names.
102 */
103struct spmi_resource {
104	struct resource		*resource;
105	u32			num_resources;
106	struct device_node	*of_node;
107	const char		*label;
108};
109
110/**
111 * Client/device handle (struct spmi_device):
112 * ------------------------------------------
113 *  This is the client/device handle returned when a SPMI device
114 *  is registered with a controller.
115 *  Pointer to this structure is used by client-driver as a handle.
116 *  @dev: Driver model representation of the device.
117 *  @name: Name of driver to use with this device.
118 *  @ctrl: SPMI controller managing the bus hosting this device.
119 *  @res: SPMI resource for the primary node
120 *  @dev_node: array of SPMI resources when used with spmi-dev-container.
121 *  @num_dev_node: number of device_node structures.
122 *  @sid: Slave Identifier.
123 */
124struct spmi_device {
125	struct device		dev;
126	const char		*name;
127	struct spmi_controller	*ctrl;
128	struct spmi_resource	res;
129	struct spmi_resource	*dev_node;
130	u32			num_dev_node;
131	u8			sid;
132};
133#define to_spmi_device(d) container_of(d, struct spmi_device, dev)
134
135/**
136 * struct spmi_boardinfo: Declare board info for SPMI device bringup.
137 * @name: Name of driver to use with this device.
138 * @slave_id: slave identifier.
139 * @spmi_device: device to be registered with the SPMI framework.
140 * @of_node: pointer to the OpenFirmware device node.
141 * @res: SPMI resource for the primary node
142 * @dev_node: array of SPMI resources when used with spmi-dev-container.
143 * @num_dev_node: number of device_node structures.
144 * @platform_data: goes to spmi_device.dev.platform_data
145 */
146struct spmi_boardinfo {
147	char			name[SPMI_NAME_SIZE];
148	uint8_t			slave_id;
149	struct device_node	*of_node;
150	struct spmi_resource	res;
151	struct spmi_resource	*dev_node;
152	u32			num_dev_node;
153	const void		*platform_data;
154};
155
156/**
157 * spmi_driver_register: Client driver registration with SPMI framework.
158 * @drv: client driver to be associated with client-device.
159 *
160 * This API will register the client driver with the SPMI framework.
161 * It is called from the driver's module-init function.
162 */
163extern int spmi_driver_register(struct spmi_driver *drv);
164
165/**
166 * spmi_driver_unregister - reverse effect of spmi_driver_register
167 * @sdrv: the driver to unregister
168 * Context: can sleep
169 */
170static inline void spmi_driver_unregister(struct spmi_driver *sdrv)
171{
172	if (sdrv)
173		driver_unregister(&sdrv->driver);
174}
175
176/**
177 * spmi_add_controller: Controller bring-up.
178 * @ctrl: controller to be registered.
179 *
180 * A controller is registered with the framework using this API. ctrl->nr is the
181 * desired number with which SPMI framework registers the controller.
182 * Function will return -EBUSY if the number is in use.
183 */
184extern int spmi_add_controller(struct spmi_controller *ctrl);
185
186/**
187 * spmi_del_controller: Controller tear-down.
188 * Controller added with the above API is teared down using this API.
189 */
190extern int spmi_del_controller(struct spmi_controller *ctrl);
191
192/**
193 * spmi_busnum_to_ctrl: Map bus number to controller
194 * @busnum: bus number
195 *
196 * Returns controller device representing this bus number
197 */
198extern struct spmi_controller *spmi_busnum_to_ctrl(u32 bus_num);
199
200/**
201 * spmi_alloc_device: Allocate a new SPMI devices.
202 * @ctrl: controller to which this device is to be added to.
203 * Context: can sleep
204 *
205 * Allows a driver to allocate and initialize a SPMI device without
206 * registering it immediately.  This allows a driver to directly fill
207 * the spmi_device structure before calling spmi_add_device().
208 *
209 * Caller is responsible to call spmi_add_device() on the returned
210 * spmi_device.  If the caller needs to discard the spmi_device without
211 * adding it, then spmi_dev_put() should be called.
212 */
213extern struct spmi_device *spmi_alloc_device(struct spmi_controller *ctrl);
214
215/**
216 * spmi_add_device: Add spmi_device allocated with spmi_alloc_device().
217 * @spmi_dev: spmi_device to be added (registered).
218 */
219extern int spmi_add_device(struct spmi_device *spmi_dev);
220
221/**
222 * spmi_new_device: Instantiates a new SPMI device
223 * @ctrl: controller to which this device is to be added to.
224 * @info: board information for this device.
225 *
226 * Returns the new device or NULL.
227 */
228extern struct spmi_device *spmi_new_device(struct spmi_controller *ctrl,
229					struct spmi_boardinfo const *info);
230
231/* spmi_remove_device: Remove the effect of spmi_add_device() */
232extern void spmi_remove_device(struct spmi_device *spmi_dev);
233
234#ifdef CONFIG_SPMI
235/**
236 * spmi_register_board_info: Board-initialization routine.
237 * @bus_num: controller number (bus) on which this device will sit.
238 * @info: list of all devices on all controllers present on the board.
239 * @n: number of entries.
240 *
241 * API enumerates respective devices on corresponding controller.
242 * Called from board-init function.
243 */
244extern int spmi_register_board_info(int busnum,
245			struct spmi_boardinfo const *info, unsigned n);
246#else
247static inline int spmi_register_board_info(int busnum,
248			struct spmi_boardinfo const *info, unsigned n)
249{
250	return 0;
251}
252#endif
253
254static inline void *spmi_get_ctrldata(const struct spmi_controller *ctrl)
255{
256	return dev_get_drvdata(&ctrl->dev);
257}
258
259static inline void spmi_set_ctrldata(struct spmi_controller *ctrl, void *data)
260{
261	dev_set_drvdata(&ctrl->dev, data);
262}
263
264static inline void *spmi_get_devicedata(const struct spmi_device *dev)
265{
266	return dev_get_drvdata(&dev->dev);
267}
268
269static inline void spmi_set_devicedata(struct spmi_device *dev, void *data)
270{
271	dev_set_drvdata(&dev->dev, data);
272}
273
274static inline void spmi_dev_put(struct spmi_device *spmidev)
275{
276	if (spmidev)
277		put_device(&spmidev->dev);
278}
279
280/**
281 * spmi_register_read() - register read
282 * @ctrl: SPMI controller.
283 * @sid: slave identifier.
284 * @ad: slave register address (5-bit address).
285 * @buf: buffer to be populated with data from the Slave.
286 *
287 * Reads 1 byte of data from a Slave device register.
288 */
289extern int spmi_register_read(struct spmi_controller *ctrl,
290					u8 sid, u8 ad, u8 *buf);
291
292/**
293 * spmi_ext_register_read() - extended register read
294 * @ctrl: SPMI controller.
295 * @sid: slave identifier.
296 * @ad: slave register address (8-bit address).
297 * @len: the request number of bytes to read (up to 16 bytes).
298 * @buf: buffer to be populated with data from the Slave.
299 *
300 * Reads up to 16 bytes of data from the extended register space on a
301 * Slave device.
302 */
303extern int spmi_ext_register_read(struct spmi_controller *ctrl,
304					u8 sid, u8 ad, u8 *buf, int len);
305
306/**
307 * spmi_ext_register_readl() - extended register read long
308 * @ctrl: SPMI controller.
309 * @sid: slave identifier.
310 * @ad: slave register address (16-bit address).
311 * @len: the request number of bytes to read (up to 8 bytes).
312 * @buf: buffer to be populated with data from the Slave.
313 *
314 * Reads up to 8 bytes of data from the extended register space on a
315 * Slave device using 16-bit address.
316 */
317extern int spmi_ext_register_readl(struct spmi_controller *ctrl,
318					u8 sid, u16 ad, u8 *buf, int len);
319
320/**
321 * spmi_register_write() - register write
322 * @ctrl: SPMI controller.
323 * @sid: slave identifier.
324 * @ad: slave register address (5-bit address).
325 * @buf: buffer containing the data to be transferred to the Slave.
326 *
327 * Writes 1 byte of data to a Slave device register.
328 */
329extern int spmi_register_write(struct spmi_controller *ctrl,
330					u8 sid, u8 ad, u8 *buf);
331
332/**
333 * spmi_register_zero_write() - register zero write
334 * @ctrl: SPMI controller.
335 * @sid: slave identifier.
336 * @data: the data to be written to register 0 (7-bits).
337 *
338 * Writes data to register 0 of the Slave device.
339 */
340extern int spmi_register_zero_write(struct spmi_controller *ctrl,
341					u8 sid, u8 data);
342
343/**
344 * spmi_ext_register_write() - extended register write
345 * @ctrl: SPMI controller.
346 * @sid: slave identifier.
347 * @ad: slave register address (8-bit address).
348 * @buf: buffer containing the data to be transferred to the Slave.
349 * @len: the request number of bytes to read (up to 16 bytes).
350 *
351 * Writes up to 16 bytes of data to the extended register space of a
352 * Slave device.
353 */
354extern int spmi_ext_register_write(struct spmi_controller *ctrl,
355					u8 sid, u8 ad, u8 *buf, int len);
356
357/**
358 * spmi_ext_register_writel() - extended register write long
359 * @ctrl: SPMI controller.
360 * @sid: slave identifier.
361 * @ad: slave register address (16-bit address).
362 * @buf: buffer containing the data to be transferred to the Slave.
363 * @len: the request number of bytes to read (up to 8 bytes).
364 *
365 * Writes up to 8 bytes of data to the extended register space of a
366 * Slave device using 16-bit address.
367 */
368extern int spmi_ext_register_writel(struct spmi_controller *ctrl,
369					u8 sid, u16 ad, u8 *buf, int len);
370
371/**
372 * spmi_command_reset() - sends RESET command to the specified slave
373 * @ctrl: SPMI controller.
374 * @sid: slave identifier.
375 *
376 * The Reset command initializes the Slave and forces all registers to
377 * their reset values. The Slave shall enter the STARTUP state after
378 * receiving a Reset command.
379 *
380 * Returns
381 * -EINVAL for invalid slave identifier.
382 * -EPERM if the SPMI transaction is denied due to permission issues.
383 * -EIO if the SPMI transaction fails (parity errors, etc).
384 * -ETIMEDOUT if the SPMI transaction times out.
385 */
386extern int spmi_command_reset(struct spmi_controller *ctrl, u8 sid);
387
388/**
389 * spmi_command_sleep() - sends SLEEP command to the specified slave
390 * @ctrl: SPMI controller.
391 * @sid: slave identifier.
392 *
393 * The Sleep command causes the Slave to enter the user defined SLEEP state.
394 *
395 * Returns
396 * -EINVAL for invalid slave identifier.
397 * -EPERM if the SPMI transaction is denied due to permission issues.
398 * -EIO if the SPMI transaction fails (parity errors, etc).
399 * -ETIMEDOUT if the SPMI transaction times out.
400 */
401extern int spmi_command_sleep(struct spmi_controller *ctrl, u8 sid);
402
403/**
404 * spmi_command_wakeup() - sends WAKEUP command to the specified slave
405 * @ctrl: SPMI controller.
406 * @sid: slave identifier.
407 *
408 * The Wakeup command causes the Slave to move from the SLEEP state to
409 * the ACTIVE state.
410 *
411 * Returns
412 * -EINVAL for invalid slave identifier.
413 * -EPERM if the SPMI transaction is denied due to permission issues.
414 * -EIO if the SPMI transaction fails (parity errors, etc).
415 * -ETIMEDOUT if the SPMI transaction times out.
416 */
417extern int spmi_command_wakeup(struct spmi_controller *ctrl, u8 sid);
418
419/**
420 * spmi_command_shutdown() - sends SHUTDOWN command to the specified slave
421 * @ctrl: SPMI controller.
422 * @sid: slave identifier.
423 *
424 * The Shutdown command causes the Slave to enter the SHUTDOWN state.
425 *
426 * Returns
427 * -EINVAL for invalid slave identifier.
428 * -EPERM if the SPMI transaction is denied due to permission issues.
429 * -EIO if the SPMI transaction fails (parity errors, etc).
430 * -ETIMEDOUT if the SPMI transaction times out.
431 */
432extern int spmi_command_shutdown(struct spmi_controller *ctrl, u8 sid);
433
434/**
435 * spmi_for_each_container_dev - iterate over the array of devnode resources.
436 * @res: spmi_resource pointer used as the array cursor
437 * @spmi_dev: spmi_device to iterate
438 *
439 * Only useable in spmi-dev-container configurations.
440 */
441#define spmi_for_each_container_dev(res, spmi_dev)			      \
442	for (res = ((spmi_dev)->dev_node ? &(spmi_dev)->dev_node[0] : NULL);  \
443	     (res - (spmi_dev)->dev_node) < (spmi_dev)->num_dev_node; res++)
444
445extern struct resource *spmi_get_resource(struct spmi_device *dev,
446				      struct spmi_resource *node,
447				      unsigned int type, unsigned int res_num);
448
449struct resource *spmi_get_resource_byname(struct spmi_device *dev,
450					  struct spmi_resource *node,
451					  unsigned int type,
452					  const char *name);
453
454extern int spmi_get_irq(struct spmi_device *dev, struct spmi_resource *node,
455						 unsigned int res_num);
456
457extern int spmi_get_irq_byname(struct spmi_device *dev,
458			       struct spmi_resource *node, const char *name);
459
460/**
461 * spmi_get_node_name - return device name for spmi node
462 * @dev: spmi device handle
463 *
464 * Get the primary node name of a spmi_device coresponding with
465 * with the 'label' binding.
466 *
467 * Returns NULL if no primary dev name has been assigned to this spmi_device.
468 */
469static inline const char *spmi_get_primary_dev_name(struct spmi_device *dev)
470{
471	if (dev->res.label)
472		return dev->res.label;
473	return NULL;
474}
475
476struct spmi_resource *spmi_get_dev_container_byname(struct spmi_device *dev,
477						    const char *label);
478#endif