Skip to contentSkip to conversation

spi: clarify what driver can do with message->status

PATCH In review Andy Shevchenko 2 participants 7 messages Feb 24, 2015 – Feb 26, 2015 6 messages not in the archive SPI

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 spi: clarify what driver can do with message->status

Currently it's unclear from the documentation if an actual driver may or may not override the message->status field. It seems there is no other way to indicate an error when transfer is failed, e.g. when gets overrun or underrun interrupt. The patch states this clearly in the comments near to field definition.

---
 include/linux/spi/spi.h | 3 +++
 1 file changed, 3 insertions(+)
include/linux/spi/spi.h +3 -0
index ed9489d..92cff9a 100644
@@ -680,6 +680,9 @@ struct spi_message {
 	void			*context;
 	unsigned		frame_length;
 	unsigned		actual_length;
+
+	/* The actual driver may set this field to indicate an error, e.g. -EIO
+	 * for failed transfer. */
 	int			status;
 
 	/* for optional use by whatever driver currently owns the
Signature · 6 lines
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 1424772249-9676-1-git-send-email-andriy.shevchenko-VuQAYsv1563Yd54FQh9/[email protected]

#2 lore raw

include/linux/spi/spi.h struct spi_message { · line 686

Quoted 10 lines · Andy Shevchenko

Currently it's unclear from the documentation if an actual driver may or may not override the message->status field. It seems there is no other way to indicate an error when transfer is failed, e.g. when gets overrun or underrun interrupt. The patch states this clearly in the comments near to field definition.

include/linux/spi/spi.h +3 -0
+
+	/* The actual driver may set this field to indicate an error, e.g. -EIO
+	 * for failed transfer. */
 	int			status;

Let's take a step back here: what documentation are you looking at which says anything else about status?

I'd also expect this to go with the other kerneldoc for the field.

A message that is not in the archive (sent off-list or not yet received): 20150224132411.GF6236-bheZrs9scGb3/WHNxyQH9YN0K6Il/[email protected]

#4 lore raw
Quoted 7 lines · Mark Brown
Quoted 5 lines · Andy Shevchenko

Currently it's unclear from the documentation if an actual driver may or may not override the message->status field. It seems there is no other way to indicate an error when transfer is failed, e.g. when gets overrun or underrun interrupt. The patch states this clearly in the comments near to field definition.

Quoted 7 lines

include/linux/spi/spi.h struct spi_message { · line 686

Quoted 4 lines
include/linux/spi/spi.h +3 -0
+
+	/* The actual driver may set this field to indicate an error, e.g. -EIO
+	 * for failed transfer. */
 	int			status;

Let's take a step back here: what documentation are you looking at which says anything else about status?

The description of this field above, namely " * @status: zero for success, else negative errno".

Quoted 1 line

I'd also expect this to go with the other kerneldoc for the field.

Any place that suits better.

Signature · 7 lines
Andy Shevchenko <[email protected]>
Intel Finland Oy

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 1424784807.14897.24.camel-VuQAYsv1563Yd54FQh9/[email protected]

#6 lore raw
Quoted 11 lines · Andy Shevchenko
Quoted 6 lines · Mark Brown

include/linux/spi/spi.h struct spi_message { · line 686

Quoted 3 lines
include/linux/spi/spi.h +2 -0
+	/* The actual driver may set this field to indicate an error, e.g. -EIO
+	 * for failed transfer. */
 	int			status;

Let's take a step back here: what documentation are you looking at which says anything else about status?

The description of this field above, namely " * @status: zero for success, else negative errno".

...which suggests that anything detecting an error should report it via status, no?

Quoted 3 lines
Quoted 1 line

I'd also expect this to go with the other kerneldoc for the field.

Any place that suits better.

Well, see above...

A message that is not in the archive (sent off-list or not yet received): 20150224141706.GK6236-bheZrs9scGb3/WHNxyQH9YN0K6Il/[email protected]

#8 lore raw
Quoted 10 lines · Mark Brown
Quoted 8 lines · Andy Shevchenko
Quoted 6 lines · Mark Brown

Review

Quoted 3 lines
(quoted diff) +2 -0
+	/* The actual driver may set this field to indicate an error, e.g. -EIO
+	 * for failed transfer. */
 	int			status;

Let's take a step back here: what documentation are you looking at which says anything else about status?

Quoted 5 lines
Quoted 2 lines

The description of this field above, namely " * @status: zero for success, else negative errno".

...which suggests that anything detecting an error should report it via status, no?

Unclear. I dived into spi.c to understand if I could override or not. There are two fields status and state, the latter is dedicated for an actual driver usage, and that is clear. Many (old) drivers are using state as a storage for custom status. Newer drivers, that are using SPI core, mostly don't care about error handling at all (at least I didn't find an existing example of the message->status usage).

Quoted 5 lines
Quoted 3 lines
Quoted 1 line

I'd also expect this to go with the other kerneldoc for the field.

Any place that suits better.

Well, see above...

Regarding my above comment can we extend the description of the field then?

Signature · 7 lines
Andy Shevchenko <[email protected]>
Intel Finland Oy

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): 1424788527.14897.27.camel-VuQAYsv1563Yd54FQh9/[email protected]

#10 lore raw
Quoted 11 lines · Andy Shevchenko
Quoted 2 lines · Mark Brown

...which suggests that anything detecting an error should report it via status, no?

Unclear. I dived into spi.c to understand if I could override or not. There are two fields status and state, the latter is dedicated for an actual driver usage, and that is clear. Many (old) drivers are using state as a storage for custom status. Newer drivers, that are using SPI core, mostly don't care about error handling at all (at least I didn't find an existing example of the message->status usage).

This isn't something specific to modern drivers, the status field has been there since forever and is still widely used. Almost all error detection for SPI controllers (especially that's likely to trigger and therefore have a practical effect) is timeouts and that's been factored out into the core for the more modern drivers.

Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
Quoted 1 line

I'd also expect this to go with the other kerneldoc for the field.

Any place that suits better.

Well, see above...

Regarding my above comment can we extend the description of the field then?

Let's see what a patch looks like. I am wary of documentation that's too verbose since it can cause people to glaze over when reading it.

A message that is not in the archive (sent off-list or not yet received): 20150226024812.GK6236-bheZrs9scGb3/WHNxyQH9YN0K6Il/[email protected]

#12 lore raw
Quoted 5 lines · Mark Brown
Quoted 4 lines · Andy Shevchenko
Quoted 2 lines · Mark Brown

...which suggests that anything detecting an error should report it via status, no?

…

Quoted 5 lines
Quoted 2 lines

Regarding my above comment can we extend the description of the field then?

Let's see what a patch looks like. I am wary of documentation that's too verbose since it can cause people to glaze over when reading it.

I asked Mika's opinion and he wasn't confused by current description. Hence, let's discontinuing this effort.

Signature · 7 lines
Andy Shevchenko <[email protected]>
Intel Finland Oy

--
To unsubscribe from this list: send the line "unsubscribe linux-spi" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html