Skip to contentSkip to conversation

docs: i2c: Fix return value of i2c_smbus_xxx functions

PATCH Superseded Lei YU 2 participants 5 messages Nov 19, 2019

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Lei YU

author
#0 lore raw

PATCH 1/1 docs: i2c: Fix return value of i2c_smbus_xxx functions

In i2c/dev-interface.rst it said

Quoted 1 line

All these transactions return -1 on failure

But actually the i2c_smbus_xxx functions return negative error numbers on failure, instead of -1.

Fix the document.

---
 Documentation/i2c/dev-interface.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/i2c/dev-interface.rst +2 -2
index 69c23a3..73b77c3 100644
@@ -163,8 +163,8 @@ for details) through the following functions::
   __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                    __u8 *values);
 
-All these transactions return -1 on failure; you can read errno to see
-what happened. The 'write' transactions return 0 on success; the
+All these transactions return negative value on failure; you can read errno to
+see what happened. The 'write' transactions return 0 on success; the
 'read' transactions return the read value, except for read_block, which
 returns the number of values read. The block buffers need not be longer
 than 32 bytes.
Signature · 1 line
2.7.4
#1 lore raw
Quoted 19 lines · Lei YU

In i2c/dev-interface.rst it said

Quoted 1 line

All these transactions return -1 on failure

But actually the i2c_smbus_xxx functions return negative error numbers on failure, instead of -1.

Fix the document.

---
 Documentation/i2c/dev-interface.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/i2c/dev-interface.rst +0 -0
index 69c23a3..73b77c3 100644

Documentation/i2c/dev-interface.rst for details) through the following functions:: · line 167

Quoted 7 lines
Documentation/i2c/dev-interface.rst +2 -2
@@ -163,8 +163,8 @@ for details) through the following functions::
   __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                    __u8 *values);
 
-All these transactions return -1 on failure; you can read errno to see
-what happened. The 'write' transactions return 0 on success; the
+All these transactions return negative value on failure; you can read errno to
+see what happened. The 'write' transactions return 0 on success; the

s/return negative/return a negative/

And the line is now too long compared to the rest of the text, so you need to rewrap the paragraph.

And why do you need to dig around in errno if the negative errno has already been returned?

Documentation/i2c/dev-interface.rst for details) through the following functions:: · line 170

Quoted 4 lines
Documentation/i2c/dev-interface.rst +0 -0
 'read' transactions return the read value, except for read_block, which
 returns the number of values read. The block buffers need not be longer
 than 32 bytes.

Hmm, unrelated, but should that perhaps be "must not" instead of "need not"?

Cheers,
Peter

#2 lore raw
Quoted 6 lines · Peter Rosin
Quoted 4 lines

'read' transactions return the read value, except for read_block, which returns the number of values read. The block buffers need not be longer than 32 bytes.

Hmm, unrelated, but should that perhaps be "must not" instead of "need not"?

Ahhh, hit 'send' and it all becomes crystal clear. The *read* buffers need not be larger than 32 bytes. Duh!

Cheers,
Peter

author
#3 lore raw
In reply to Peter Rosin
Quoted 24 lines · Peter Rosin
Quoted 22 lines · Lei YU

In i2c/dev-interface.rst it said

Quoted 1 line

All these transactions return -1 on failure

But actually the i2c_smbus_xxx functions return negative error numbers on failure, instead of -1.

Fix the document.

---
 Documentation/i2c/dev-interface.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/i2c/dev-interface.rst +0 -0
index 69c23a3..73b77c3 100644
@@ -163,8 +163,8 @@ for details) through the following functions::
   __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                    __u8 *values);
 
Quoted 6 lines

Documentation/i2c/dev-interface.rst for details) through the following functions:: · line 167

Quoted 4 lines
Documentation/i2c/dev-interface.rst +2 -2
-All these transactions return -1 on failure; you can read errno to see
-what happened. The 'write' transactions return 0 on success; the
+All these transactions return negative value on failure; you can read errno to
+see what happened. The 'write' transactions return 0 on success; the

s/return negative/return a negative/

Ack, will send v2 patch.

Quoted 3 lines

And the line is now too long compared to the rest of the text, so you need to rewrap the paragraph.

In this patch it's at column 78, that should be OK.
But after adding the "a" it will exceed and will rewrap in v2 patch.

Quoted 3 lines

And why do you need to dig around in errno if the negative errno has already been returned?

Yeah, good question, probably we could remove the following sentence?

Quoted 10 lines

Documentation/i2c/dev-interface.rst for details) through the following functions:: · line 170

Quoted 5 lines
Documentation/i2c/dev-interface.rst +0 -0
 'read' transactions return the read value, except for read_block, which
 returns the number of values read. The block buffers need not be longer
 than 32 bytes.

Hmm, unrelated, but should that perhaps be "must not" instead of "need not"?

Cheers,
Peter

#4 lore raw
Quoted 5 lines · Lei YU
Quoted 2 lines · Peter Rosin

And the line is now too long compared to the rest of the text, so you need to rewrap the paragraph.

In this patch it's at column 78, that should be OK.

No, that's not ok. If the rest
of the paragraph is wrapped at 72 (or something such), a single line breaking that pattern will be
disturbing to the reader. The
fact that you don't get some
checkpatch warning has nothing
to do with that.

Cheers,
Peter