tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
i2c: refactor documentation of struct i2c_msg
The information about 'i2c_msg' was spread between kdoc and comments.
Move all the explanations to kdoc and duplicate only the requirements
for the flags in the comments. Also, add some redundancy and fix some
typos while here.
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
Signed-off-by: Wolfram Sang <wsa@kernel.org>
authored by
Wolfram Sang
and committed by
Wolfram Sang
bfb3939c
1059b2bc
+55
-36
+55
-36
include/uapi/linux/i2c.h
+55
-36
include/uapi/linux/i2c.h
···
32
32
33
33
/**
34
34
* struct i2c_msg - an I2C transaction segment beginning with START
35
-
* @addr: Slave address, either seven or ten bits. When this is a ten
36
-
* bit address, I2C_M_TEN must be set in @flags and the adapter
37
-
* must support I2C_FUNC_10BIT_ADDR.
38
-
* @flags: I2C_M_RD is handled by all adapters. No other flags may be
39
-
* provided unless the adapter exported the relevant I2C_FUNC_*
40
-
* flags through i2c_check_functionality().
41
-
* @len: Number of data bytes in @buf being read from or written to the
42
-
* I2C slave address. For read transactions where I2C_M_RECV_LEN
43
-
* is set, the caller guarantees that this buffer can hold up to
44
-
* 32 bytes in addition to the initial length byte sent by the
45
-
* slave (plus, if used, the SMBus PEC); and this value will be
46
-
* incremented by the number of block data bytes received.
35
+
*
36
+
* @addr: Slave address, either 7 or 10 bits. When this is a 10 bit address,
37
+
* %I2C_M_TEN must be set in @flags and the adapter must support
38
+
* %I2C_FUNC_10BIT_ADDR.
39
+
*
40
+
* @flags:
41
+
* Supported by all adapters:
42
+
* %I2C_M_RD: read data (from slave to master). Guaranteed to be 0x0001!
43
+
*
44
+
* Optional:
45
+
* %I2C_M_DMA_SAFE: the buffer of this message is DMA safe. Makes only sense
46
+
* in kernelspace, because userspace buffers are copied anyway
47
+
*
48
+
* Only if I2C_FUNC_10BIT_ADDR is set:
49
+
* %I2C_M_TEN: this is a 10 bit chip address
50
+
*
51
+
* Only if I2C_FUNC_SMBUS_READ_BLOCK_DATA is set:
52
+
* %I2C_M_RECV_LEN: message length will be first received byte
53
+
*
54
+
* Only if I2C_FUNC_NOSTART is set:
55
+
* %I2C_M_NOSTART: skip repeated start sequence
56
+
57
+
* Only if I2C_FUNC_PROTOCOL_MANGLING is set:
58
+
* %I2C_M_NO_RD_ACK: in a read message, master ACK/NACK bit is skipped
59
+
* %I2C_M_IGNORE_NAK: treat NACK from client as ACK
60
+
* %I2C_M_REV_DIR_ADDR: toggles the Rd/Wr bit
61
+
* %I2C_M_STOP: force a STOP condition after the message
62
+
*
63
+
* @len: Number of data bytes in @buf being read from or written to the I2C
64
+
* slave address. For read transactions where %I2C_M_RECV_LEN is set, the
65
+
* caller guarantees that this buffer can hold up to %I2C_SMBUS_BLOCK_MAX
66
+
* bytes in addition to the initial length byte sent by the slave (plus,
67
+
* if used, the SMBus PEC); and this value will be incremented by the number
68
+
* of block data bytes received.
69
+
*
47
70
* @buf: The buffer into which data is read, or from which it's written.
48
71
*
49
72
* An i2c_msg is the low level representation of one segment of an I2C
···
83
60
* group, it is followed by a STOP. Otherwise it is followed by the next
84
61
* @i2c_msg transaction segment, beginning with a (repeated) START.
85
62
*
86
-
* Alternatively, when the adapter supports I2C_FUNC_PROTOCOL_MANGLING then
63
+
* Alternatively, when the adapter supports %I2C_FUNC_PROTOCOL_MANGLING then
87
64
* passing certain @flags may have changed those standard protocol behaviors.
88
65
* Those flags are only for use with broken/nonconforming slaves, and with
89
-
* adapters which are known to support the specific mangling options they
90
-
* need (one or more of IGNORE_NAK, NO_RD_ACK, NOSTART, and REV_DIR_ADDR).
66
+
* adapters which are known to support the specific mangling options they need.
91
67
*/
92
68
struct i2c_msg {
93
-
__u16 addr; /* slave address */
69
+
__u16 addr;
94
70
__u16 flags;
95
-
#define I2C_M_RD 0x0001 /* read data, from slave to master */
96
-
/* I2C_M_RD is guaranteed to be 0x0001! */
97
-
#define I2C_M_TEN 0x0010 /* this is a ten bit chip address */
98
-
#define I2C_M_DMA_SAFE 0x0200 /* the buffer of this message is DMA safe */
99
-
/* makes only sense in kernelspace */
100
-
/* userspace buffers are copied anyway */
101
-
#define I2C_M_RECV_LEN 0x0400 /* length will be first received byte */
102
-
#define I2C_M_NO_RD_ACK 0x0800 /* if I2C_FUNC_PROTOCOL_MANGLING */
103
-
#define I2C_M_IGNORE_NAK 0x1000 /* if I2C_FUNC_PROTOCOL_MANGLING */
104
-
#define I2C_M_REV_DIR_ADDR 0x2000 /* if I2C_FUNC_PROTOCOL_MANGLING */
105
-
#define I2C_M_NOSTART 0x4000 /* if I2C_FUNC_NOSTART */
106
-
#define I2C_M_STOP 0x8000 /* if I2C_FUNC_PROTOCOL_MANGLING */
107
-
__u16 len; /* msg length */
108
-
__u8 *buf; /* pointer to msg data */
71
+
#define I2C_M_RD 0x0001 /* guaranteed to be 0x0001! */
72
+
#define I2C_M_TEN 0x0010 /* use only if I2C_FUNC_10BIT_ADDR */
73
+
#define I2C_M_DMA_SAFE 0x0200 /* use only in kernel space */
74
+
#define I2C_M_RECV_LEN 0x0400 /* use only if I2C_FUNC_SMBUS_READ_BLOCK_DATA */
75
+
#define I2C_M_NO_RD_ACK 0x0800 /* use only if I2C_FUNC_PROTOCOL_MANGLING */
76
+
#define I2C_M_IGNORE_NAK 0x1000 /* use only if I2C_FUNC_PROTOCOL_MANGLING */
77
+
#define I2C_M_REV_DIR_ADDR 0x2000 /* use only if I2C_FUNC_PROTOCOL_MANGLING */
78
+
#define I2C_M_NOSTART 0x4000 /* use only if I2C_FUNC_NOSTART */
79
+
#define I2C_M_STOP 0x8000 /* use only if I2C_FUNC_PROTOCOL_MANGLING */
80
+
__u16 len;
81
+
__u8 *buf;
109
82
};
110
83
111
84
/* To determine what functionality is present */
112
85
113
86
#define I2C_FUNC_I2C 0x00000001
114
-
#define I2C_FUNC_10BIT_ADDR 0x00000002
115
-
#define I2C_FUNC_PROTOCOL_MANGLING 0x00000004 /* I2C_M_IGNORE_NAK etc. */
87
+
#define I2C_FUNC_10BIT_ADDR 0x00000002 /* required for I2C_M_TEN */
88
+
#define I2C_FUNC_PROTOCOL_MANGLING 0x00000004 /* required for I2C_M_IGNORE_NAK etc. */
116
89
#define I2C_FUNC_SMBUS_PEC 0x00000008
117
-
#define I2C_FUNC_NOSTART 0x00000010 /* I2C_M_NOSTART */
90
+
#define I2C_FUNC_NOSTART 0x00000010 /* required for I2C_M_NOSTART */
118
91
#define I2C_FUNC_SLAVE 0x00000020
119
-
#define I2C_FUNC_SMBUS_BLOCK_PROC_CALL 0x00008000 /* SMBus 2.0 */
92
+
#define I2C_FUNC_SMBUS_BLOCK_PROC_CALL 0x00008000 /* SMBus 2.0 or later */
120
93
#define I2C_FUNC_SMBUS_QUICK 0x00010000
121
94
#define I2C_FUNC_SMBUS_READ_BYTE 0x00020000
122
95
#define I2C_FUNC_SMBUS_WRITE_BYTE 0x00040000
···
121
102
#define I2C_FUNC_SMBUS_READ_WORD_DATA 0x00200000
122
103
#define I2C_FUNC_SMBUS_WRITE_WORD_DATA 0x00400000
123
104
#define I2C_FUNC_SMBUS_PROC_CALL 0x00800000
124
-
#define I2C_FUNC_SMBUS_READ_BLOCK_DATA 0x01000000
105
+
#define I2C_FUNC_SMBUS_READ_BLOCK_DATA 0x01000000 /* required for I2C_M_RECV_LEN */
125
106
#define I2C_FUNC_SMBUS_WRITE_BLOCK_DATA 0x02000000
126
107
#define I2C_FUNC_SMBUS_READ_I2C_BLOCK 0x04000000 /* I2C-like block xfer */
127
108
#define I2C_FUNC_SMBUS_WRITE_I2C_BLOCK 0x08000000 /* w/ 1-byte reg. addr. */
128
-
#define I2C_FUNC_SMBUS_HOST_NOTIFY 0x10000000
109
+
#define I2C_FUNC_SMBUS_HOST_NOTIFY 0x10000000 /* SMBus 2.0 or later */
129
110
130
111
#define I2C_FUNC_SMBUS_BYTE (I2C_FUNC_SMBUS_READ_BYTE | \
131
112
I2C_FUNC_SMBUS_WRITE_BYTE)