Skip to contentSkip to conversation

ethdev: document rte_eth_dev_reset return codes

PATCH Superseded [email protected] 5 participants 19 messages Oct 19, 2017 – Oct 25, 2017

lore
Share & tools
lore
#0 lore raw

PATCH 1/2 ethdev: document rte_eth_dev_reset return codes

From: Luca Boccassi <[email protected]>

This new function returns 0 on success and various error codes on different failures. Attempt to document them.

---
 lib/librte_ether/rte_ethdev.h | 8 ++++++++
 1 file changed, 8 insertions(+)
lib/librte_ether/rte_ethdev.h +8 -0
index aaf02b33d..9cdb9724a 100644
@@ -2262,6 +2262,14 @@ void rte_eth_dev_close(uint16_t port_id);
  *
  * @param port_id
  *   The port identifier of the Ethernet device.
+ *
+ * @return
+ *   - (0) if successful.
+ *   - (-EINVAL) if port identifier is invalid.
+ *   - (-ENOTSUP) if hardware doesn't support this function.
+ *   - (-EPERM) if not ran from the primary process.
+ *   - (-EIO) if re-initialisation failed.
+ *   - (-ENOMEM) if the reset failed due to OOM.
  */
 int rte_eth_dev_reset(uint16_t port_id);
 
Signature · 1 line
2.11.0
#1 lore raw

PATCH 2/2 ethdev: pre-emptively document rte_eth_dev_reset error code

From: Luca Boccassi <[email protected]>

When VF reset will be supported by drivers, the API will most likely have to return -EAGAIN to avoid blocking when the VF cannot be reset because the PF is down.
Document it immediately even if it's not yet supported, so that users and developers can already take into account about this use case, and thus avoid an API-incompatible change later on.

This is based on real-world production usage and customer escalations, using earlier patches from Intel.

---
 lib/librte_ether/rte_ethdev.h | 1 +
 1 file changed, 1 insertion(+)
lib/librte_ether/rte_ethdev.h +1 -0
index 9cdb9724a..126f42d3c 100644
@@ -2270,6 +2270,7 @@ void rte_eth_dev_close(uint16_t port_id);
  *   - (-EPERM) if not ran from the primary process.
  *   - (-EIO) if re-initialisation failed.
  *   - (-ENOMEM) if the reset failed due to OOM.
+ *   - (-EAGAIN) if PF is not up and the reset cannot proceed yet.
  */
 int rte_eth_dev_reset(uint16_t port_id);
 
Signature · 1 line
2.11.0
#2 lore raw

Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

Quoted 3 lines · On 19/10/2017 14:48, [email protected] wrote:

Document it immediately even if it's not yet supported, so that users and developers can already take into account about this use case, and thus avoid an API-incompatible change later on.

I'm not sure about documenting unimplemented features, as API docs ought to describe what the code currently does. Then again reason seems OK and I don't think there's hard guidelines on this..

Quoted 2 lines

This is based on real-world production usage and customer escalations, using earlier patches from Intel.

Can you give the patchwork link for these patches?

..Remy

#3 lore raw

Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

Quoted 7 lines · Remy Horton
Quoted 5 lines · On 19/10/2017 14:48, [email protected] wrote:

Document it immediately even if it's not yet supported, so that users
and developers can already take into account about this use case, and
thus avoid an API-incompatible change later on.

Quoted 5 lines

I'm not sure about documenting unimplemented features, as API docs ought
to describe what the code currently does. Then again reason seems OK and
I don't think there's hard guidelines on this..

Yeah I realised that, that's why it's a separate patch :-)

I'm just trying to avoid a foreseeable API breakage given we've been using this API in production.

OTOH there are a few cases where perhaps EAGAIN is already a possible error code to return - for example where the driver fails to initialise? For example there's an error path that just returns -1 in i40evf_dev_init

Quoted 8 lines
Quoted 3 lines

This is based on real-world production usage and customer escalations,
using earlier patches from Intel.

Can you give the patchwork link for these patches?

..Remy

Based on these ones:

http://dpdk.org/dev/patchwork/patch/14009/
http://dpdk.org/dev/patchwork/patch/14011/
http://dpdk.org/dev/patchwork/patch/14010/

I had sent some feedback, as especially the ixgbe one was a blocking call in case the PF was down, which is a deal breaker in most situations given the API will be called from the controller thread in most cases.

We've adapted and used these patches with the early rte_eth_dev_reset for a year in production now, and we had a customer who requested it since they were running into the problem it solves (PF flaps).

I have adapted them on the latest 17.11 tree and tested with X540 10gbit cards, and it seems to work as before. Should I send an RFC and CC all of you?

Incidentally, are there specific reasons why the VF functionality was dropped since the first patches were sent?

Signature · 2 lines
Kind regards,
Luca Boccassi
#4 lore raw

Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

On 19/10/2017 17:14, Luca Boccassi wrote:
[..]

Quoted 7 lines

We've adapted and used these patches with the early rte_eth_dev_reset for a year in production now, and we had a customer who requested it since they were running into the problem it solves (PF flaps).

I have adapted them on the latest 17.11 tree and tested with X540 10gbit cards, and it seems to work as before. Should I send an RFC and CC all of you?

Since it sounds stable, probably best to post the updated/rebased patch. Should get merged as long as nothing breaks.

Quoted 2 lines

Incidentally, are there specific reasons why the VF functionality was dropped since the first patches were sent?

I'm personally not sure, but the others should know.

#5 lore raw

Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

Quoted 8 lines · Remy Horton

On 19/10/2017 17:14, Luca Boccassi wrote:
[..]

Quoted 6 lines

We've adapted and used these patches with the early rte_eth_dev_reset
for a year in production now, and we had a customer who requested it
since they were running into the problem it solves (PF flaps).

Quoted 8 lines
Quoted 4 lines

I have adapted them on the latest 17.11 tree and tested with X540 10gbit cards, and it seems to work as before. Should I send an RFC and
CC all of you?

Since it sounds stable, probably best to post the updated/rebased patch.
Should get merged as long as nothing breaks.

I can send an RFC later today.

Quoted 6 lines
Quoted 4 lines

Incidentally, are there specific reasons why the VF functionality was
dropped since the first patches were sent?

I'm personally not sure, but the others should know.

Signature · 2 lines
Kind regards,
Luca Boccassi
#6 lore raw

Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

In reply to Remy Horton

19/10/2017 16:53, Remy Horton:

Quoted 9 lines · On 19/10/2017 14:48, [email protected] wrote:
Quoted 3 lines

Document it immediately even if it's not yet supported, so that users and developers can already take into account about this use case, and thus avoid an API-incompatible change later on.

I'm not sure about documenting unimplemented features, as API docs ought to describe what the code currently does. Then again reason seems OK and I don't think there's hard guidelines on this..

An API does not need to be implemented to describe its behaviour. We just have to agree about which behaviour we want to expect.

It seems this error code is reasonable.
But I am not sure you need to give the details about the cause of the error. The most important is to advise app writer to retry resetting later when the device is ready. Isn't it?

#7 lore raw

Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

Quoted 15 lines · Thomas Monjalon

19/10/2017 16:53, Remy Horton:

Quoted 8 lines · On 19/10/2017 14:48, [email protected] wrote:
Quoted 5 lines

Document it immediately even if it's not yet supported, so that users
and developers can already take into account about this use case, and
thus avoid an API-incompatible change later on.

Quoted 5 lines

I'm not sure about documenting unimplemented features, as API docs ought
to describe what the code currently does. Then again reason seems OK and
I don't think there's hard guidelines on this..

Quoted 7 lines

An API does not need to be implemented to describe its behaviour. We just have to agree about which behaviour we want to expect.

It seems this error code is reasonable.
But I am not sure you need to give the details about the cause of the error. The most important is to advise app writer to retry resetting later when the device is ready. Isn't it?

Sure, makes sense, see v2.

Signature · 2 lines
Kind regards,
Luca Boccassi
#9 lore raw

PATCH v2 1/2 ethdev: document rte_eth_dev_reset return codes

In reply to [email protected]

From: Luca Boccassi <[email protected]>

This new function returns 0 on success and various error codes on different failures. Attempt to document them.

---
 lib/librte_ether/rte_ethdev.h | 8 ++++++++
 1 file changed, 8 insertions(+)
lib/librte_ether/rte_ethdev.h +8 -0
index b773589d6..697f6b2e0 100644
@@ -2269,6 +2269,14 @@ void rte_eth_dev_close(uint16_t port_id);
  *
  * @param port_id
  *   The port identifier of the Ethernet device.
+ *
+ * @return
+ *   - (0) if successful.
+ *   - (-EINVAL) if port identifier is invalid.
+ *   - (-ENOTSUP) if hardware doesn't support this function.
+ *   - (-EPERM) if not ran from the primary process.
+ *   - (-EIO) if re-initialisation failed.
+ *   - (-ENOMEM) if the reset failed due to OOM.
  */
 int rte_eth_dev_reset(uint16_t port_id);
 
Signature · 1 line
2.11.0
#10 lore raw

PATCH v2 2/2 ethdev: pre-emptively document rte_eth_dev_reset error code

From: Luca Boccassi <[email protected]>

When VF reset will be supported by drivers, the API will most likely have to return -EAGAIN to avoid blocking when the VF cannot be reset because the PF is down.
Document it immediately even if it's not yet supported, so that users and developers can already take into account about this use case, and thus avoid an API-incompatible change later on.

This is based on real-world production usage and customer escalations, using earlier patches from Intel.

---
 lib/librte_ether/rte_ethdev.h | 1 +
 1 file changed, 1 insertion(+)
lib/librte_ether/rte_ethdev.h +1 -0
index 697f6b2e0..2a0129a2a 100644
@@ -2277,6 +2277,7 @@ void rte_eth_dev_close(uint16_t port_id);
  *   - (-EPERM) if not ran from the primary process.
  *   - (-EIO) if re-initialisation failed.
  *   - (-ENOMEM) if the reset failed due to OOM.
+ *   - (-EAGAIN) if the reset temporarily failed and should be retried later.
  */
 int rte_eth_dev_reset(uint16_t port_id);
 
Signature · 1 line
2.11.0
Acked-by on v2 2/2
#11 lore raw

Re: [PATCH v2 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code

24/10/2017 13:03, [email protected]:

Quoted 9 lines

From: Luca Boccassi <[email protected]>

When VF reset will be supported by drivers, the API will most likely have to return -EAGAIN to avoid blocking when the VF cannot be reset because the PF is down.
Document it immediately even if it's not yet supported, so that users and developers can already take into account about this use case, and thus avoid an API-incompatible change later on.

Quoted 4 lines

This is based on real-world production usage and customer escalations, using earlier patches from Intel.

Suggested title: "ethdev: document new error code for reset"

#14 lore raw

PATCH v3 1/2 ethdev: document error codes of reset

In reply to [email protected]

From: Luca Boccassi <[email protected]>

This new function returns 0 on success and various error codes on different failures. Attempt to document them.

---
 lib/librte_ether/rte_ethdev.h | 8 ++++++++
 1 file changed, 8 insertions(+)
lib/librte_ether/rte_ethdev.h +8 -0
index b773589d6..697f6b2e0 100644
@@ -2269,6 +2269,14 @@ void rte_eth_dev_close(uint16_t port_id);
  *
  * @param port_id
  *   The port identifier of the Ethernet device.
+ *
+ * @return
+ *   - (0) if successful.
+ *   - (-EINVAL) if port identifier is invalid.
+ *   - (-ENOTSUP) if hardware doesn't support this function.
+ *   - (-EPERM) if not ran from the primary process.
+ *   - (-EIO) if re-initialisation failed.
+ *   - (-ENOMEM) if the reset failed due to OOM.
  */
 int rte_eth_dev_reset(uint16_t port_id);
 
Signature · 1 line
2.11.0
#15 lore raw

PATCH v3 2/2 ethdev: document new error code for reset

From: Luca Boccassi <[email protected]>

When VF reset will be supported by drivers, the API will most likely have to return -EAGAIN to avoid blocking when the VF cannot be reset because the PF is down.
Document it immediately even if it's not yet supported, so that users and developers can already take into account about this use case, and thus avoid an API-incompatible change later on.

This is based on real-world production usage and customer escalations, using earlier patches from Intel.

---
 lib/librte_ether/rte_ethdev.h | 1 +
 1 file changed, 1 insertion(+)
lib/librte_ether/rte_ethdev.h +1 -0
index 697f6b2e0..2a0129a2a 100644
@@ -2277,6 +2277,7 @@ void rte_eth_dev_close(uint16_t port_id);
  *   - (-EPERM) if not ran from the primary process.
  *   - (-EIO) if re-initialisation failed.
  *   - (-ENOMEM) if the reset failed due to OOM.
+ *   - (-EAGAIN) if the reset temporarily failed and should be retried later.
  */
 int rte_eth_dev_reset(uint16_t port_id);
 
Signature · 1 line
2.11.0
#17 lore raw

Re: [PATCH v3 1/2] ethdev: document error codes of reset

Quoted 10 lines · Ferruh Yigit
Quoted 7 lines · On 10/24/2017 6:19 AM, [email protected] wrote:

From: Luca Boccassi <[email protected]>

This new function returns 0 on success and various error codes on different failures. Attempt to document them.

Series applied to dpdk-next-net/master, thanks.

Thanks!

Will it make it into 17.11-rc2?

Signature · 2 lines
Kind regards,
Luca Boccassi
#18 lore raw

Re: [PATCH v3 1/2] ethdev: document error codes of reset

Quoted 7 lines · Luca Boccassi
Quoted 6 lines · Ferruh Yigit
Quoted 5 lines · On 10/24/2017 6:19 AM, [email protected] wrote:

From: Luca Boccassi <[email protected]>

This new function returns 0 on success and various error codes on different failures. Attempt to document them.

Quoted 8 lines
Quoted 4 lines
Quoted 2 lines

Series applied to dpdk-next-net/master, thanks.

Thanks!

Will it make it into 17.11-rc2?

Most probably, next-net not pulled yet, it will be pulled for rc2. Unless has been removed while merged into main tree, will be in rc2.