I have searched the netdev archives and have not found any RFC like
this.
This proposal is to add selective diag/test modes to ethtool with
minimal
overhead/bloat. Please provide feedback on the proposal. This proposed
selective test mode is being requested more and more from our Linux
users,
so I will put my head on the chopping block to get this ironed out once
and for all.
START OF RFC
Contents
========
Overview
Ethtool Changes
- New Command Line Options
- Query Option
- Selective Option
- Backwards Compatibility
- Selective Option Reporting Format
Driver Changes
- ETH_SS_TEST Command
- Structure Mapping
- New Structures
- Sample Driver Code
Overview
########################################################################
########
There is a need to selectively run one or more specific NIC diagnostic
tests more than once without the overhead of running the entire set.
There have been hardware issues in the past that were exposed only after
repeatedly running the same diagnostic test a thousand or more times.
This could only be achieved using other operating systems that allowed a
finer granularity of control over the diagnostics.
Adding a selective mode to the driver does not add bloat since the
online/offline modes can be consolidated from the driver's standpoint.
The ethtool application can continue to provide the online/offline
modes via the selective mode for backwards compatibility with existing
applications that use the ethtool utility. For a period of time drivers
could
support the selective mode in addition to online and offline modes to
give
applications that use the ethtool interface directly time to transition.
A
sample code segment is provide later in this document showing how little
code is needed in the driver to implement this proposed ethtool
selective
test mode.
The goals are:
1) Provide the ability to select one or more online or offline
tests to be run
2) Provide the ability to run each test a user selected number
of times
3) Provide the ability to run the entire number of tests without
regard
to success or failure
This document is based on ethtool version 3.
Ethtool Changes
########################################################################
########
This section outlines the ethtool application changes needed to support
the proposed selective mode.
New Command Line Options
------------------------
Two new options are needed, query and selective.
The current test mode options are:
ethtool -t DEVNAME [online|(offline)]
The proposed test mode options are:
ethtool -t DEVNAME [online|(offline)|query|[selective [runall] N
N...]]
Query Option
------------
The query option returns the test string set in the following
format (as supplied by the driver):
register test (offline)
nvram test (online)
eeprom test (offline)
link test (online)
Selective Option
----------------
The selective option runs the selected tests the specified number of
times. The first selective option N value corresponds to the number of
times
to run the first test in the query list, the second N value specifies
how many
times to run the second test, and so on. All selective option N values
default
to zero, so passing "selective 10" runs the first test ten times.
Running
"ethtool -t ethX selective" completes with success if the driver
supports
the selective mode, giving applications a way to determine if the mode
is
supported prior to attempting to run selective tests.
The runall argument causes the specified number of test cycles to be run
regardless of test pass or failure. To run the second and third test
four and
eight times respectively without regard to test pass/failure,
"selective runall 0 4 8" is used.
The data member of the ethtool_test structure is used to pass the
specific
number of times to run each test and the stop on failure flag. Even
though
the runall option applies to all tests, having a bit associated with
each
test lays the foundation for ignoring failures on some tests and not on
others at some point in the future. The runall option is only set if the
count for the specific test is non-zero.
Backwards Compatibility
-----------------------
The ethtool application simulates the current online and offline
functionality if a driver supports the selective mode. To simulate
the online functionality:
if driver supports selective test mode
query online tests
run each online test once
(equivalent to "selective 0 1 0 1" for the above query example)
report results in online test run format
else
run online test using online cmd
report results
endif
This allows online and offline diagnostics support with a driver that
just
supports the selective mode. This maintains backwards compatibility with
applications that use the online/offline ethtool tests.
Selective Option Reporting Format
---------------------------------
The selective option reports the test in the following format:
<query_string><ws><(online|offline)>:<ws><pass_count/fail_count>
where
ws is white space, one or more spaces or tabs.
query_string is the text string reported by the query option, which
includes
the online/offline designator.
For example:
register test (offline): 0/0
nvram test (online): 8/2
eeprom test (offline): 0/0
link test (online): 5/0
In the above test run only the online tests were executed, the nvram
test
ran ten times and failed twice, while the link test ran five times and
was successful every time.
Selective test mode support is determined by running
"ethtool -t ethX selective". If a driver supports the selective mode,
the
following is returned (based on the example above).
register test (offline): 0/0
nvram test (online): 0/0
eeprom test (offline): 0/0
link test (online): 0/0
One may wonder why the query option is needed given that the tests can
be
determined as outlined above. The query option allows applications to
determine if the adapter supports some type of diagnostics before
attempting
to run them. Drivers supporting diagnostics already support the query
option
via the ETH_SS_TEST command, only the ethtool application need to change
to
add this support.
Driver Changes
########################################################################
########
ETH_SS_TEST Command
-------------------
If a driver supports the selective mode, it must report the diagnostics
string sets (ETH_SS_TEST) in the following format:
<test name><ws><(online)|(offline)>
For example:
register test (offline)
nvram test (online)
eeprom test (offline)
link test (online)
The "online" designator means the test is run without interrupting
traffic,
while "offline" means the adapter must be taken down resulting in
network
connectivity lose for the specific adapter. A test must either be online
or
offline, it can't be both.
Structure Mapping
-----------------
The ethtool_test->data member is mapped to ethtool_selective_test_in to
acquire the input parameters for each test, and mapped to
ethtool_selective_test_out for returning the test pass/fail count.
If a test fails and the runall flag is not set for the given test, the
next
specified test is run. If the runall bit is set, the failure count is
incremented and the test re-run if the test has not been run the user
specified number of times.
New Structures
--------------
This section provides sample structures and changes to existing ones.
enum ethtool_test_flags {
ETH_TEST_FL_OFFLINE = (1 << 0), /* online / offline */
ETH_TEST_FL_FAILED = (1 << 1), /* test passed / failed */
ETH_TEST_FL_SELECTIVE = (1 << 2), /* selective mode */
};
enum ethtool_selective_test_flags {
/* run a given test the specified number of times, even if failures
occur */
ETH_SEL_TEST_FL_RUNALL = (1 << 0)
};
struct ethtool_selective_test_in {
u32 count; /* number of times to run test */
u8 flags; /* ethtool_selective_test_flags */
u8 reserved[3];
};
struct ethtool_selective_test_out {
u32 passed; /* number of times this test passed */
u32 failed; /* number of times this test failed */
};
Sample Driver Code
------------------
This section provides sample driver code implementing the selective test
mode.
int (*selective_test[])() =
{
®ister_test, // 1, register test
&nvram_test, // 2, nvram test
&eeprom_test, // 3, eeprom test
&link_test, // 4, link test
};
#define NUM_TESTS (sizeof(selective_test)/(sizeof(selective_test[0])))
static int mydvr_run_diags(struct net_device *dev, void *uaddr)
{
struct ethtool_selective_test_in test_in;
struct ethtool_selective_test_out *test_out;
:
:
for (i=0; i<NUM_TESTS; i++) {
if (!tests->data[i])
continue; // skip this test
memcpy(&test_in, &tests->data[i], sizeof(test_in));
tests->data[i] = 0;
test_out = (struct ethtool_selective_test_out*) &tests->data[i];
while (test_in.count--) {
if ((*(selective_test[i]))(dev)) {
test_out->failed++;
if (!(test_in.flags & ETH_SEL_TEST_FL_RUNALL))
break;
} else {
test_out->passed++;
}
}
if (test_out->failed)
tests->flags |= ETH_TEST_FL_FAILED;
}
:
:
}
END OF RFC
Signed-off-by: Tony Cureington <[EMAIL PROTECTED]>
-
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
