From bfb3939c51d51c0de794da14f33c13e36d2e4f3d Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Sat, 9 Jan 2021 13:43:05 +0100 Subject: 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 Signed-off-by: Wolfram Sang --- include/uapi/linux/i2c.h | 91 +++++++++++++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 36 deletions(-) (limited to 'include/uapi/linux') diff --git a/include/uapi/linux/i2c.h b/include/uapi/linux/i2c.h index f71a1751cacf..8d2f59f53324 100644 --- a/include/uapi/linux/i2c.h +++ b/include/uapi/linux/i2c.h @@ -32,18 +32,41 @@ /** * struct i2c_msg - an I2C transaction segment beginning with START - * @addr: Slave address, either seven or ten bits. When this is a ten - * bit address, I2C_M_TEN must be set in @flags and the adapter - * must support I2C_FUNC_10BIT_ADDR. - * @flags: I2C_M_RD is handled by all adapters. No other flags may be - * provided unless the adapter exported the relevant I2C_FUNC_* - * flags through i2c_check_functionality(). - * @len: Number of data bytes in @buf being read from or written to the - * I2C slave address. For read transactions where I2C_M_RECV_LEN - * is set, the caller guarantees that this buffer can hold up to - * 32 bytes in addition to the initial length byte sent by the - * slave (plus, if used, the SMBus PEC); and this value will be - * incremented by the number of block data bytes received. + * + * @addr: Slave address, either 7 or 10 bits. When this is a 10 bit address, + * %I2C_M_TEN must be set in @flags and the adapter must support + * %I2C_FUNC_10BIT_ADDR. + * + * @flags: + * Supported by all adapters: + * %I2C_M_RD: read data (from slave to master). Guaranteed to be 0x0001! + * + * Optional: + * %I2C_M_DMA_SAFE: the buffer of this message is DMA safe. Makes only sense + * in kernelspace, because userspace buffers are copied anyway + * + * Only if I2C_FUNC_10BIT_ADDR is set: + * %I2C_M_TEN: this is a 10 bit chip address + * + * Only if I2C_FUNC_SMBUS_READ_BLOCK_DATA is set: + * %I2C_M_RECV_LEN: message length will be first received byte + * + * Only if I2C_FUNC_NOSTART is set: + * %I2C_M_NOSTART: skip repeated start sequence + + * Only if I2C_FUNC_PROTOCOL_MANGLING is set: + * %I2C_M_NO_RD_ACK: in a read message, master ACK/NACK bit is skipped + * %I2C_M_IGNORE_NAK: treat NACK from client as ACK + * %I2C_M_REV_DIR_ADDR: toggles the Rd/Wr bit + * %I2C_M_STOP: force a STOP condition after the message + * + * @len: Number of data bytes in @buf being read from or written to the I2C + * slave address. For read transactions where %I2C_M_RECV_LEN is set, the + * caller guarantees that this buffer can hold up to %I2C_SMBUS_BLOCK_MAX + * bytes in addition to the initial length byte sent by the slave (plus, + * if used, the SMBus PEC); and this value will be incremented by the number + * of block data bytes received. + * * @buf: The buffer into which data is read, or from which it's written. * * An i2c_msg is the low level representation of one segment of an I2C @@ -60,40 +83,36 @@ * group, it is followed by a STOP. Otherwise it is followed by the next * @i2c_msg transaction segment, beginning with a (repeated) START. * - * Alternatively, when the adapter supports I2C_FUNC_PROTOCOL_MANGLING then + * Alternatively, when the adapter supports %I2C_FUNC_PROTOCOL_MANGLING then * passing certain @flags may have changed those standard protocol behaviors. * Those flags are only for use with broken/nonconforming slaves, and with - * adapters which are known to support the specific mangling options they - * need (one or more of IGNORE_NAK, NO_RD_ACK, NOSTART, and REV_DIR_ADDR). + * adapters which are known to support the specific mangling options they need. */ struct i2c_msg { - __u16 addr; /* slave address */ + __u16 addr; __u16 flags; -#define I2C_M_RD 0x0001 /* read data, from slave to master */ - /* I2C_M_RD is guaranteed to be 0x0001! */ -#define I2C_M_TEN 0x0010 /* this is a ten bit chip address */ -#define I2C_M_DMA_SAFE 0x0200 /* the buffer of this message is DMA safe */ - /* makes only sense in kernelspace */ - /* userspace buffers are copied anyway */ -#define I2C_M_RECV_LEN 0x0400 /* length will be first received byte */ -#define I2C_M_NO_RD_ACK 0x0800 /* if I2C_FUNC_PROTOCOL_MANGLING */ -#define I2C_M_IGNORE_NAK 0x1000 /* if I2C_FUNC_PROTOCOL_MANGLING */ -#define I2C_M_REV_DIR_ADDR 0x2000 /* if I2C_FUNC_PROTOCOL_MANGLING */ -#define I2C_M_NOSTART 0x4000 /* if I2C_FUNC_NOSTART */ -#define I2C_M_STOP 0x8000 /* if I2C_FUNC_PROTOCOL_MANGLING */ - __u16 len; /* msg length */ - __u8 *buf; /* pointer to msg data */ +#define I2C_M_RD 0x0001 /* guaranteed to be 0x0001! */ +#define I2C_M_TEN 0x0010 /* use only if I2C_FUNC_10BIT_ADDR */ +#define I2C_M_DMA_SAFE 0x0200 /* use only in kernel space */ +#define I2C_M_RECV_LEN 0x0400 /* use only if I2C_FUNC_SMBUS_READ_BLOCK_DATA */ +#define I2C_M_NO_RD_ACK 0x0800 /* use only if I2C_FUNC_PROTOCOL_MANGLING */ +#define I2C_M_IGNORE_NAK 0x1000 /* use only if I2C_FUNC_PROTOCOL_MANGLING */ +#define I2C_M_REV_DIR_ADDR 0x2000 /* use only if I2C_FUNC_PROTOCOL_MANGLING */ +#define I2C_M_NOSTART 0x4000 /* use only if I2C_FUNC_NOSTART */ +#define I2C_M_STOP 0x8000 /* use only if I2C_FUNC_PROTOCOL_MANGLING */ + __u16 len; + __u8 *buf; }; /* To determine what functionality is present */ #define I2C_FUNC_I2C 0x00000001 -#define I2C_FUNC_10BIT_ADDR 0x00000002 -#define I2C_FUNC_PROTOCOL_MANGLING 0x00000004 /* I2C_M_IGNORE_NAK etc. */ +#define I2C_FUNC_10BIT_ADDR 0x00000002 /* required for I2C_M_TEN */ +#define I2C_FUNC_PROTOCOL_MANGLING 0x00000004 /* required for I2C_M_IGNORE_NAK etc. */ #define I2C_FUNC_SMBUS_PEC 0x00000008 -#define I2C_FUNC_NOSTART 0x00000010 /* I2C_M_NOSTART */ +#define I2C_FUNC_NOSTART 0x00000010 /* required for I2C_M_NOSTART */ #define I2C_FUNC_SLAVE 0x00000020 -#define I2C_FUNC_SMBUS_BLOCK_PROC_CALL 0x00008000 /* SMBus 2.0 */ +#define I2C_FUNC_SMBUS_BLOCK_PROC_CALL 0x00008000 /* SMBus 2.0 or later */ #define I2C_FUNC_SMBUS_QUICK 0x00010000 #define I2C_FUNC_SMBUS_READ_BYTE 0x00020000 #define I2C_FUNC_SMBUS_WRITE_BYTE 0x00040000 @@ -102,11 +121,11 @@ struct i2c_msg { #define I2C_FUNC_SMBUS_READ_WORD_DATA 0x00200000 #define I2C_FUNC_SMBUS_WRITE_WORD_DATA 0x00400000 #define I2C_FUNC_SMBUS_PROC_CALL 0x00800000 -#define I2C_FUNC_SMBUS_READ_BLOCK_DATA 0x01000000 +#define I2C_FUNC_SMBUS_READ_BLOCK_DATA 0x01000000 /* required for I2C_M_RECV_LEN */ #define I2C_FUNC_SMBUS_WRITE_BLOCK_DATA 0x02000000 #define I2C_FUNC_SMBUS_READ_I2C_BLOCK 0x04000000 /* I2C-like block xfer */ #define I2C_FUNC_SMBUS_WRITE_I2C_BLOCK 0x08000000 /* w/ 1-byte reg. addr. */ -#define I2C_FUNC_SMBUS_HOST_NOTIFY 0x10000000 +#define I2C_FUNC_SMBUS_HOST_NOTIFY 0x10000000 /* SMBus 2.0 or later */ #define I2C_FUNC_SMBUS_BYTE (I2C_FUNC_SMBUS_READ_BYTE | \ I2C_FUNC_SMBUS_WRITE_BYTE) -- cgit v1.2.3-59-g8ed1b From deb0d3351b0cb7233206317ca1774bda312de28e Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Sat, 9 Jan 2021 13:43:06 +0100 Subject: i2c: remove licence boilerplate from main UAPI header Remove boilerplate because we now have the SPDX header. Signed-off-by: Wolfram Sang Signed-off-by: Wolfram Sang --- include/uapi/linux/i2c.h | 32 +++++++------------------------- 1 file changed, 7 insertions(+), 25 deletions(-) (limited to 'include/uapi/linux') diff --git a/include/uapi/linux/i2c.h b/include/uapi/linux/i2c.h index 8d2f59f53324..7786551eb177 100644 --- a/include/uapi/linux/i2c.h +++ b/include/uapi/linux/i2c.h @@ -1,29 +1,11 @@ /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */ -/* ------------------------------------------------------------------------- */ -/* */ -/* i2c.h - definitions for the i2c-bus interface */ -/* */ -/* ------------------------------------------------------------------------- */ -/* Copyright (C) 1995-2000 Simon G. Vogl - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, - MA 02110-1301 USA. */ -/* ------------------------------------------------------------------------- */ - -/* With some changes from Kyösti Mälkki and - Frodo Looijaard */ +/* + * i2c.h - definitions for the I2C bus interface + * + * Copyright (C) 1995-2000 Simon G. Vogl + * With some changes from Kyösti Mälkki and + * Frodo Looijaard + */ #ifndef _UAPI_LINUX_I2C_H #define _UAPI_LINUX_I2C_H -- cgit v1.2.3-59-g8ed1b From 1713d66cae8acdf3d34bafe09598fec9d1fb4793 Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Sat, 9 Jan 2021 13:43:07 +0100 Subject: i2c: remove licence boilerplate from i2c-dev UAPI header Remove boilerplate because we now have the SPDX header. Signed-off-by: Wolfram Sang Signed-off-by: Wolfram Sang --- include/uapi/linux/i2c-dev.h | 25 +++++-------------------- 1 file changed, 5 insertions(+), 20 deletions(-) (limited to 'include/uapi/linux') diff --git a/include/uapi/linux/i2c-dev.h b/include/uapi/linux/i2c-dev.h index 85f8047afcf2..1c4cec4ddd84 100644 --- a/include/uapi/linux/i2c-dev.h +++ b/include/uapi/linux/i2c-dev.h @@ -1,25 +1,10 @@ /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */ /* - i2c-dev.h - i2c-bus driver, char device interface - - Copyright (C) 1995-97 Simon G. Vogl - Copyright (C) 1998-99 Frodo Looijaard - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, - MA 02110-1301 USA. -*/ + * i2c-dev.h - I2C bus char device interface + * + * Copyright (C) 1995-97 Simon G. Vogl + * Copyright (C) 1998-99 Frodo Looijaard + */ #ifndef _UAPI_LINUX_I2C_DEV_H #define _UAPI_LINUX_I2C_DEV_H -- cgit v1.2.3-59-g8ed1b From 21500aa84024b3fc541197b2041d80538539740d Mon Sep 17 00:00:00 2001 From: Wolfram Sang Date: Sat, 9 Jan 2021 13:43:09 +0100 Subject: i2c: uapi: add macro to describe support for all SMBus transfers Some I2C bus master drivers which support I2C_M_RECV_LEN do not set the functionality bits of the now supported SMBus transfers. Add a convenience macro to make this very simple. Signed-off-by: Wolfram Sang Signed-off-by: Wolfram Sang --- include/uapi/linux/i2c.h | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'include/uapi/linux') diff --git a/include/uapi/linux/i2c.h b/include/uapi/linux/i2c.h index 7786551eb177..92326ebde350 100644 --- a/include/uapi/linux/i2c.h +++ b/include/uapi/linux/i2c.h @@ -129,6 +129,11 @@ struct i2c_msg { I2C_FUNC_SMBUS_I2C_BLOCK | \ I2C_FUNC_SMBUS_PEC) +/* if I2C_M_RECV_LEN is also supported */ +#define I2C_FUNC_SMBUS_EMUL_ALL (I2C_FUNC_SMBUS_EMUL | \ + I2C_FUNC_SMBUS_READ_BLOCK_DATA | \ + I2C_FUNC_SMBUS_BLOCK_PROC_CALL) + /* * Data for SMBus Messages */ -- cgit v1.2.3-59-g8ed1b