ethdev: document rte_eth_dev_reset return codes
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
@@ -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
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
@@ -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
Quoted 9 lines · On 19/10/2017 14:48, [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.
Signed-off-by Luca Boccassi <[email protected]>--- lib/librte_ether/rte_ethdev.h | 8 ++++++++ 1 file changed, 8 insertions(+)
Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code
In reply to [email protected]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
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
Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code
In reply to Remy Horton19/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?
Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code
In reply to Luca BoccassiOn 19/10/2017 17:14, Luca Boccassi wrote:
[..]
Quoted 7 lines
We've adapted and used these patches with the early
rte_eth_dev_resetfor 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.
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
@@ -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
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
@@ -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
Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code
In reply to Thomas MonjalonQuoted 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
Re: [PATCH 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code
In reply to Remy HortonQuoted 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
24/10/2017 13:03, [email protected]:
Quoted 6 lines
From: Luca Boccassi <[email protected]>
This new function returns 0 on success and various error codes on different failures. Attempt to document them.
Signed-off-by Luca Boccassi <[email protected]>
Suggested title: "ethdev: document error codes of reset"
Re: [PATCH v2 2/2] ethdev: pre-emptively document rte_eth_dev_reset error code
In reply to [email protected]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
-EAGAINto 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.
Signed-off-by Luca Boccassi <[email protected]>
Suggested title: "ethdev: document new error code for reset"
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
@@ -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
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
@@ -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
Quoted 11 lines · Thomas Monjalon
24/10/2017 13:03, [email protected]:
Quoted 6 lines
From: Luca Boccassi <[email protected]>
This new function returns 0 on success and various error codes on different failures. Attempt to document them.
Signed-off-by Luca Boccassi <[email protected]>Suggested title: "ethdev: document error codes of reset"
Acked-by Thomas Monjalon <[email protected]>
Ok, see v3.
Signature · 2 lines
Kind regards, Luca Boccassi
Re: [PATCH v3 1/2] ethdev: document error codes of reset
In reply to [email protected]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.
Signed-off-by Luca Boccassi <[email protected]>Acked-by Thomas Monjalon <[email protected]>
Series applied to dpdk-next-net/master, thanks.
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.
Signed-off-by Luca Boccassi <[email protected]>Acked-by Thomas Monjalon <[email protected]>Series applied to dpdk-next-net/master, thanks.
Thanks!
Will it make it into 17.11-rc2?
Signature · 2 lines
Kind regards, Luca Boccassi
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
Signed-off-by Luca Boccassi <[email protected]>Acked-by Thomas Monjalon <[email protected]>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.