Home | History | Annotate | Line # | Download | only in i2c
      1  1.32   thorpej /*	$NetBSD: i2cvar.h,v 1.32 2025/09/21 14:43:19 thorpej Exp $	*/
      2   1.1   thorpej 
      3   1.1   thorpej /*
      4   1.1   thorpej  * Copyright (c) 2003 Wasabi Systems, Inc.
      5   1.1   thorpej  * All rights reserved.
      6   1.1   thorpej  *
      7   1.1   thorpej  * Written by Steve C. Woodford and Jason R. Thorpe for Wasabi Systems, Inc.
      8   1.1   thorpej  *
      9   1.1   thorpej  * Redistribution and use in source and binary forms, with or without
     10   1.1   thorpej  * modification, are permitted provided that the following conditions
     11   1.1   thorpej  * are met:
     12   1.1   thorpej  * 1. Redistributions of source code must retain the above copyright
     13   1.1   thorpej  *    notice, this list of conditions and the following disclaimer.
     14   1.1   thorpej  * 2. Redistributions in binary form must reproduce the above copyright
     15   1.1   thorpej  *    notice, this list of conditions and the following disclaimer in the
     16   1.1   thorpej  *    documentation and/or other materials provided with the distribution.
     17   1.1   thorpej  * 3. All advertising materials mentioning features or use of this software
     18   1.1   thorpej  *    must display the following acknowledgement:
     19   1.1   thorpej  *      This product includes software developed for the NetBSD Project by
     20   1.1   thorpej  *      Wasabi Systems, Inc.
     21   1.1   thorpej  * 4. The name of Wasabi Systems, Inc. may not be used to endorse
     22   1.1   thorpej  *    or promote products derived from this software without specific prior
     23   1.1   thorpej  *    written permission.
     24   1.1   thorpej  *
     25   1.1   thorpej  * THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
     26   1.1   thorpej  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
     27   1.1   thorpej  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     28   1.1   thorpej  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
     29   1.1   thorpej  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
     30   1.1   thorpej  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
     31   1.1   thorpej  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
     32   1.1   thorpej  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
     33   1.1   thorpej  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     34   1.1   thorpej  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     35   1.1   thorpej  * POSSIBILITY OF SUCH DAMAGE.
     36   1.1   thorpej  */
     37   1.1   thorpej 
     38   1.1   thorpej #ifndef _DEV_I2C_I2CVAR_H_
     39   1.1   thorpej #define	_DEV_I2C_I2CVAR_H_
     40   1.1   thorpej 
     41  1.14   thorpej #include <sys/device.h>
     42  1.19   thorpej #include <sys/mutex.h>
     43   1.1   thorpej #include <dev/i2c/i2c_io.h>
     44   1.9  jmcneill #include <prop/proplib.h>
     45   1.1   thorpej 
     46   1.1   thorpej /* Flags passed to i2c routines. */
     47  1.21   thorpej #define	I2C_F_WRITE	0		/* new transfer is a write */
     48  1.21   thorpej #define	I2C_F_READ	__BIT(0)	/* new transfer is a read */
     49  1.21   thorpej #define	I2C_F_LAST	__BIT(1)	/* last byte of read */
     50  1.21   thorpej #define	I2C_F_STOP	__BIT(2)	/* send stop after byte */
     51  1.21   thorpej #define	I2C_F_POLL	__BIT(3)	/* poll, don't sleep */
     52  1.21   thorpej #define	I2C_F_PEC	__BIT(4)	/* smbus packet error checking */
     53  1.21   thorpej #define	I2C_F_SPEED	__BITS(28,31)	/* I2C transfer speed selector */
     54  1.21   thorpej 
     55  1.21   thorpej #define	I2C_SPEED_SM		0	/* standard mode (100Kb/s) */
     56  1.21   thorpej #define	I2C_SPEED_FM		1	/* fast mode (400Kb/s) */
     57  1.21   thorpej #define	I2C_SPEED_FMPLUS	2	/* fast mode+ (1Mb/s) */
     58  1.21   thorpej #define	I2C_SPEED_HS		3	/* high speed (3.4Mb/s) */
     59   1.1   thorpej 
     60  1.13   thorpej /* i2c bus instance properties */
     61  1.13   thorpej #define	I2C_PROP_INDIRECT_PROBE_STRATEGY	\
     62  1.13   thorpej 				"i2c-indirect-probe-strategy"
     63  1.13   thorpej #define	I2C_PROBE_STRATEGY_QUICK_WRITE		\
     64  1.13   thorpej 				"smbus-quick-write"
     65  1.13   thorpej #define	I2C_PROBE_STRATEGY_RECEIVE_BYTE		\
     66  1.13   thorpej 				"smbus-receive-byte"
     67  1.13   thorpej #define	I2C_PROBE_STRATEGY_NONE			\
     68  1.13   thorpej 				"none"
     69  1.13   thorpej 
     70  1.20   thorpej #define	I2C_PROP_INDIRECT_DEVICE_PERMITLIST	\
     71  1.20   thorpej 				"i2c-indirect-device-permitlist"
     72  1.13   thorpej 	/* value is a prop_array of prop_strings */
     73  1.13   thorpej 
     74   1.1   thorpej /*
     75   1.1   thorpej  * This structure provides the interface between the i2c framework
     76   1.1   thorpej  * and the underlying i2c controller.
     77   1.1   thorpej  *
     78   1.1   thorpej  * Note that this structure is designed specifically to allow us
     79   1.1   thorpej  * to either use the autoconfiguration framework or not.  This
     80   1.1   thorpej  * allows a driver for a board with a private i2c bus use generic
     81   1.1   thorpej  * i2c client drivers for chips that might be on that board.
     82   1.1   thorpej  */
     83   1.1   thorpej typedef struct i2c_controller {
     84   1.1   thorpej 	void	*ic_cookie;		/* controller private */
     85   1.1   thorpej 
     86   1.1   thorpej 	/*
     87  1.32   thorpej 	 * Multi-channel i2c controllers and i2c muxes allow
     88  1.32   thorpej 	 * for multiple busses to be driven by a single block
     89  1.32   thorpej 	 * of controller logic.  Each of these busses is
     90  1.32   thorpej 	 * represented by a logical controller with its own
     91  1.32   thorpej 	 * i2c_tag_t.  By default, each i2c_tag_t is initialized
     92  1.32   thorpej 	 * indicating a single-bus controller, but multi-channel
     93  1.32   thorpej 	 * controllers and muxes should initialize this field to
     94  1.32   thorpej 	 * indicate which logical bus number this i2c_tag_t is
     95  1.32   thorpej 	 * associated with.
     96  1.32   thorpej 	 */
     97  1.32   thorpej 	int	ic_channel;
     98  1.32   thorpej 
     99  1.32   thorpej 	/*
    100   1.1   thorpej 	 * These provide synchronization in the presence of
    101   1.1   thorpej 	 * multiple users of the i2c bus.  When a device
    102   1.1   thorpej 	 * driver wishes to perform transfers on the i2c
    103   1.1   thorpej 	 * bus, the driver should acquire the bus.  When
    104   1.1   thorpej 	 * the driver is finished, it should release the
    105   1.1   thorpej 	 * bus.
    106   1.1   thorpej 	 *
    107  1.19   thorpej 	 * The main synchronization logic is handled by the
    108  1.19   thorpej 	 * generic i2c layer, but optional hooks to back-end
    109  1.19   thorpej 	 * drivers are provided in case additional processing
    110  1.19   thorpej 	 * is needed (e.g. enabling the i2c controller).
    111   1.1   thorpej 	 */
    112  1.19   thorpej 	kmutex_t ic_bus_lock;
    113   1.1   thorpej 	int	(*ic_acquire_bus)(void *, int);
    114   1.1   thorpej 	void	(*ic_release_bus)(void *, int);
    115   1.1   thorpej 
    116   1.1   thorpej 	/*
    117   1.1   thorpej 	 * The preferred API for clients of the i2c interface
    118   1.1   thorpej 	 * is the scripted API.  This handles i2c controllers
    119   1.1   thorpej 	 * that do not provide raw access to the i2c signals.
    120   1.1   thorpej 	 */
    121   1.1   thorpej 	int	(*ic_exec)(void *, i2c_op_t, i2c_addr_t, const void *, size_t,
    122   1.1   thorpej 		    void *, size_t, int);
    123   1.1   thorpej 
    124   1.1   thorpej 	int	(*ic_send_start)(void *, int);
    125   1.1   thorpej 	int	(*ic_send_stop)(void *, int);
    126   1.1   thorpej 	int	(*ic_initiate_xfer)(void *, i2c_addr_t, int);
    127   1.1   thorpej 	int	(*ic_read_byte)(void *, uint8_t *, int);
    128   1.1   thorpej 	int	(*ic_write_byte)(void *, uint8_t, int);
    129   1.5  jmcneill 
    130  1.32   thorpej 	/* For future expansion; do not remove. */
    131  1.26  riastrad 	struct i2c_tag_private	*ic_tag_private;
    132   1.1   thorpej } *i2c_tag_t;
    133   1.1   thorpej 
    134  1.32   thorpej #define	I2C_CHANNEL_DEFAULT	-1
    135  1.32   thorpej 
    136  1.32   thorpej static inline int
    137  1.32   thorpej i2c_tag_channel(i2c_tag_t tag)
    138  1.32   thorpej {
    139  1.32   thorpej 	return tag->ic_channel == I2C_CHANNEL_DEFAULT ? 0
    140  1.32   thorpej 						      : tag->ic_channel;
    141  1.32   thorpej }
    142  1.32   thorpej 
    143   1.1   thorpej /* Used to attach the i2c framework to the controller. */
    144   1.1   thorpej struct i2cbus_attach_args {
    145   1.1   thorpej 	i2c_tag_t iba_tag;		/* the controller */
    146   1.1   thorpej };
    147   1.1   thorpej 
    148   1.1   thorpej /* Used to attach devices on the i2c bus. */
    149   1.1   thorpej struct i2c_attach_args {
    150   1.1   thorpej 	i2c_tag_t	ia_tag;		/* our controller */
    151   1.1   thorpej 	i2c_addr_t	ia_addr;	/* address of device */
    152  1.32   thorpej 
    153   1.7    martin 	/* only set if using direct config */
    154   1.7    martin 	const char *	ia_name;	/* name of the device */
    155  1.32   thorpej 	const char *	ia_clist;	/* compatible strlist */
    156  1.32   thorpej 	size_t		ia_clist_size;	/* size of compatible strlist */
    157  1.32   thorpej 	devhandle_t	ia_devhandle;	/* device handle for the device */
    158   1.1   thorpej };
    159   1.1   thorpej 
    160   1.1   thorpej /*
    161   1.1   thorpej  * API presented to i2c controllers.
    162   1.1   thorpej  */
    163   1.1   thorpej int	iicbus_print(void *, const char *);
    164  1.19   thorpej void	iic_tag_init(i2c_tag_t);
    165  1.19   thorpej void	iic_tag_fini(i2c_tag_t);
    166  1.14   thorpej 
    167  1.31   thorpej int	iic_acquire_bus_lock(kmutex_t *, int);
    168  1.31   thorpej void	iic_release_bus_lock(kmutex_t *);
    169  1.31   thorpej 
    170  1.27   thorpej static inline device_t
    171  1.28   thorpej iicbus_attach_with_devhandle(device_t dev, i2c_tag_t tag, devhandle_t devhandle)
    172  1.27   thorpej {
    173  1.27   thorpej 	struct i2cbus_attach_args iba = {
    174  1.27   thorpej 		.iba_tag = tag,
    175  1.27   thorpej 	};
    176  1.27   thorpej 	return config_found(dev, &iba, iicbus_print,
    177  1.27   thorpej 	    CFARGS(.iattr = "i2cbus",
    178  1.28   thorpej 		   .devhandle = devhandle));
    179  1.28   thorpej }
    180  1.28   thorpej 
    181  1.28   thorpej static inline device_t
    182  1.28   thorpej iicbus_attach(device_t dev, i2c_tag_t tag)
    183  1.28   thorpej {
    184  1.28   thorpej 	return iicbus_attach_with_devhandle(dev, tag, device_handle(dev));
    185  1.27   thorpej }
    186  1.27   thorpej 
    187  1.14   thorpej /*
    188  1.14   thorpej  * API presented to i2c devices.
    189  1.14   thorpej  */
    190  1.16   thorpej int	iic_compatible_match(const struct i2c_attach_args *,
    191  1.22   thorpej 			     const struct device_compatible_entry *);
    192  1.15   thorpej bool	iic_use_direct_match(const struct i2c_attach_args *, const cfdata_t,
    193  1.15   thorpej 			     const struct device_compatible_entry *, int *);
    194  1.22   thorpej const struct device_compatible_entry *
    195  1.22   thorpej 	iic_compatible_lookup(const struct i2c_attach_args *,
    196  1.22   thorpej 			      const struct device_compatible_entry *);
    197   1.1   thorpej 
    198  1.13   thorpej /*
    199  1.13   thorpej  * Constants to indicate the quality of a match made by a driver's
    200  1.25    andvar  * match routine, from lowest to highest:
    201  1.13   thorpej  *
    202  1.13   thorpej  *	-- Address only; no other checks were made.
    203  1.13   thorpej  *
    204  1.13   thorpej  *	-- Address + device probed and recognized.
    205  1.13   thorpej  *
    206  1.13   thorpej  *	-- Direct-config match by "compatible" string.
    207  1.13   thorpej  *
    208  1.13   thorpej  *	-- Direct-config match by specific driver name.
    209  1.13   thorpej  */
    210  1.13   thorpej #define	I2C_MATCH_ADDRESS_ONLY		1
    211  1.13   thorpej #define	I2C_MATCH_ADDRESS_AND_PROBE	2
    212  1.13   thorpej #define	I2C_MATCH_DIRECT_COMPATIBLE	10
    213  1.14   thorpej #define	I2C_MATCH_DIRECT_COMPATIBLE_MAX	99
    214  1.14   thorpej #define	I2C_MATCH_DIRECT_SPECIFIC	100
    215  1.13   thorpej 
    216   1.1   thorpej #ifdef _I2C_PRIVATE
    217   1.1   thorpej /*
    218   1.1   thorpej  * Macros used internally by the i2c framework.
    219   1.1   thorpej  */
    220   1.1   thorpej #define	iic_send_start(ic, flags)					\
    221   1.1   thorpej 	(*(ic)->ic_send_start)((ic)->ic_cookie, (flags))
    222   1.1   thorpej #define	iic_send_stop(ic, flags)					\
    223   1.1   thorpej 	(*(ic)->ic_send_stop)((ic)->ic_cookie, (flags))
    224   1.1   thorpej #define	iic_initiate_xfer(ic, addr, flags)				\
    225   1.1   thorpej 	(*(ic)->ic_initiate_xfer)((ic)->ic_cookie, (addr), (flags))
    226   1.1   thorpej 
    227   1.1   thorpej #define	iic_read_byte(ic, bytep, flags)					\
    228   1.1   thorpej 	(*(ic)->ic_read_byte)((ic)->ic_cookie, (bytep), (flags))
    229   1.1   thorpej #define	iic_write_byte(ic, byte, flags)					\
    230   1.1   thorpej 	(*(ic)->ic_write_byte)((ic)->ic_cookie, (byte), (flags))
    231   1.1   thorpej #endif /* _I2C_PRIVATE */
    232   1.1   thorpej 
    233   1.1   thorpej /*
    234   1.1   thorpej  * Simplified API for clients of the i2c framework.  Definitions
    235   1.1   thorpej  * in <dev/i2c/i2c_io.h>.
    236   1.1   thorpej  */
    237  1.18   thorpej int	iic_acquire_bus(i2c_tag_t, int);
    238  1.18   thorpej void	iic_release_bus(i2c_tag_t, int);
    239   1.1   thorpej int	iic_exec(i2c_tag_t, i2c_op_t, i2c_addr_t, const void *,
    240   1.1   thorpej 	    size_t, void *, size_t, int);
    241   1.1   thorpej 
    242   1.1   thorpej int	iic_smbus_write_byte(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t, int);
    243   1.3  jmcneill int	iic_smbus_write_word(i2c_tag_t, i2c_addr_t, uint8_t, uint16_t, int);
    244   1.1   thorpej int	iic_smbus_read_byte(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t *, int);
    245   1.3  jmcneill int	iic_smbus_read_word(i2c_tag_t, i2c_addr_t, uint8_t, uint16_t *, int);
    246   1.1   thorpej int	iic_smbus_receive_byte(i2c_tag_t, i2c_addr_t, uint8_t *, int);
    247   1.3  jmcneill int	iic_smbus_send_byte(i2c_tag_t, i2c_addr_t, uint8_t, int);
    248   1.3  jmcneill int	iic_smbus_quick_read(i2c_tag_t, i2c_addr_t, int);
    249   1.3  jmcneill int	iic_smbus_quick_write(i2c_tag_t, i2c_addr_t, int);
    250   1.3  jmcneill int	iic_smbus_block_read(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t *,
    251   1.3  jmcneill 	    size_t, int);
    252   1.3  jmcneill int	iic_smbus_block_write(i2c_tag_t, i2c_addr_t, uint8_t, uint8_t *,
    253   1.3  jmcneill 	    size_t, int);
    254   1.1   thorpej 
    255   1.1   thorpej #endif /* _DEV_I2C_I2CVAR_H_ */
    256