[linux-block.git] / Documentation / i2c / i2c-stub.rst

========
i2c-stub
========

Description
===========

This module is a very simple fake I2C/SMBus driver.  It implements six
types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
word data, (r/w) I2C block data, and (r/w) SMBus block data.

You need to provide chip addresses as a module parameter when loading this
driver, which will then only react to SMBus commands to these addresses.

No hardware is needed nor associated with this module.  It will accept write
quick commands to the specified addresses; it will respond to the other
commands (also to the specified addresses) by reading from or writing to
arrays in memory.  It will also spam the kernel logs for every command it
handles.

A pointer register with auto-increment is implemented for all byte
operations.  This allows for continuous byte reads like those supported by
EEPROMs, among others.

SMBus block command support is disabled by default, and must be enabled
explicitly by setting the respective bits (0x03000000) in the functionality
module parameter.

SMBus block commands must be written to configure an SMBus command for
SMBus block operations. Writes can be partial. Block read commands always
return the number of bytes selected with the largest write so far.

The typical use-case is like this:

	1. load this module
	2. use i2cset (from the i2c-tools project) to pre-load some data
	3. load the target chip driver module
	4. observe its behavior in the kernel log

There's a script named i2c-stub-from-dump in the i2c-tools package which
can load register values automatically from a chip dump.

Parameters
==========

int chip_addr[10]:
	The SMBus addresses to emulate chips at.

unsigned long functionality:
	Functionality override, to disable some commands. See I2C_FUNC_*
	constants in <linux/i2c.h> for the suitable values. For example,
	value 0x1f0000 would only enable the quick, byte and byte data
	commands.

u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
	Optional bank settings. They tell which bits in which register
	select the active bank, as well as the range of banked registers.

Caveats
=======

If your target driver polls some byte or word waiting for it to change, the
stub could lock it up.  Use i2cset to unlock it.

If you spam it hard enough, printk can be lossy.  This module really wants
something like relayfs.
Commit	Line	Data
ccf988b6 MCC	1	========
	2	i2c-stub
	3	========
1da177e4	4
ccf988b6 MCC	5	Description
ccf988b6 MCC	6	===========
1da177e4	7
6f16b75a	8	This module is a very simple fake I2C/SMBus driver. It implements six
47103178	9	types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
6f16b75a	10	word data, (r/w) I2C block data, and (r/w) SMBus block data.
1da177e4	11
9d90c1fd JD	12	You need to provide chip addresses as a module parameter when loading this
9d90c1fd JD	13	driver, which will then only react to SMBus commands to these addresses.
7a8d29ce	14
1da177e4	15	No hardware is needed nor associated with this module. It will accept write
9d90c1fd JD	16	quick commands to the specified addresses; it will respond to the other
	17	commands (also to the specified addresses) by reading from or writing to
	18	arrays in memory. It will also spam the kernel logs for every command it
	19	handles.
1da177e4 LT	20
	21	A pointer register with auto-increment is implemented for all byte
	22	operations. This allows for continuous byte reads like those supported by
	23	EEPROMs, among others.
	24
6f16b75a GR	25	SMBus block command support is disabled by default, and must be enabled
	26	explicitly by setting the respective bits (0x03000000) in the functionality
	27	module parameter.
	28
	29	SMBus block commands must be written to configure an SMBus command for
	30	SMBus block operations. Writes can be partial. Block read commands always
	31	return the number of bytes selected with the largest write so far.
	32
1da177e4	33	The typical use-case is like this:
ccf988b6	34
1da177e4	35	1. load this module
6471b689 JD	36	2. use i2cset (from the i2c-tools project) to pre-load some data
6471b689 JD	37	3. load the target chip driver module
1da177e4 LT	38	4. observe its behavior in the kernel log
1da177e4 LT	39
b3af547e JD	40	There's a script named i2c-stub-from-dump in the i2c-tools package which
	41	can load register values automatically from a chip dump.
	42
ccf988b6 MCC	43	Parameters
ccf988b6 MCC	44	==========
7a8d29ce	45
9d90c1fd JD	46	int chip_addr[10]:
9d90c1fd JD	47	The SMBus addresses to emulate chips at.
7a8d29ce	48
38f41f28 JD	49	unsigned long functionality:
	50	Functionality override, to disable some commands. See I2C_FUNC_*
	51	constants in <linux/i2c.h> for the suitable values. For example,
	52	value 0x1f0000 would only enable the quick, byte and byte data
	53	commands.
	54
ccf988b6	55	u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
2408c17f JD	56	Optional bank settings. They tell which bits in which register
	57	select the active bank, as well as the range of banked registers.
	58
ccf988b6 MCC	59	Caveats
ccf988b6 MCC	60	=======
1da177e4	61
1da177e4 LT	62	If your target driver polls some byte or word waiting for it to change, the
	63	stub could lock it up. Use i2cset to unlock it.
	64
1da177e4 LT	65	If you spam it hard enough, printk can be lossy. This module really wants
1da177e4 LT	66	something like relayfs.