Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

net: ena: Add PHC documentation

Provide the relevant information and guidelines
about the feature support in the ENA driver.

Signed-off-by: Amit Bernstein <amitbern@amazon.com>
Signed-off-by: David Arinzon <darinzon@amazon.com>
Link: https://patch.msgid.link/20250617110545.5659-10-darinzon@amazon.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>

authored by

David Arinzon and committed by
Jakub Kicinski
c9223021 e14521e9

+93
+93
Documentation/networking/device_drivers/ethernet/amazon/ena.rst
··· 224 224 than RX copybreak bytes is received, it is copied into a new memory 225 225 buffer and the RX descriptor is returned to HW. 226 226 227 + .. _`PHC`: 228 + 229 + PTP Hardware Clock (PHC) 230 + ======================== 231 + .. _`ptp-userspace-api`: https://docs.kernel.org/driver-api/ptp.html#ptp-hardware-clock-user-space-api 232 + .. _`testptp`: https://elixir.bootlin.com/linux/latest/source/tools/testing/selftests/ptp/testptp.c 233 + 234 + ENA Linux driver supports PTP hardware clock providing timestamp reference to achieve nanosecond resolution. 235 + 236 + **PHC support** 237 + 238 + PHC depends on the PTP module, which needs to be either loaded as a module or compiled into the kernel. 239 + 240 + Verify if the PTP module is present: 241 + 242 + .. code-block:: shell 243 + 244 + grep -w '^CONFIG_PTP_1588_CLOCK=[ym]' /boot/config-`uname -r` 245 + 246 + - If no output is provided, the ENA driver cannot be loaded with PHC support. 247 + 248 + **PHC activation** 249 + 250 + The feature is turned off by default, in order to turn the feature on, the ENA driver 251 + can be loaded in the following way: 252 + 253 + - devlink: 254 + 255 + .. code-block:: shell 256 + 257 + sudo devlink dev param set pci/<domain:bus:slot.function> name enable_phc value true cmode driverinit 258 + sudo devlink dev reload pci/<domain:bus:slot.function> 259 + # for example: 260 + sudo devlink dev param set pci/0000:00:06.0 name enable_phc value true cmode driverinit 261 + sudo devlink dev reload pci/0000:00:06.0 262 + 263 + All available PTP clock sources can be tracked here: 264 + 265 + .. code-block:: shell 266 + 267 + ls /sys/class/ptp 268 + 269 + PHC support and capabilities can be verified using ethtool: 270 + 271 + .. code-block:: shell 272 + 273 + ethtool -T <interface> 274 + 275 + **PHC timestamp** 276 + 277 + To retrieve PHC timestamp, use `ptp-userspace-api`_, usage example using `testptp`_: 278 + 279 + .. code-block:: shell 280 + 281 + testptp -d /dev/ptp$(ethtool -T <interface> | awk '/PTP Hardware Clock:/ {print $NF}') -k 1 282 + 283 + PHC get time requests should be within reasonable bounds, 284 + avoid excessive utilization to ensure optimal performance and efficiency. 285 + The ENA device restricts the frequency of PHC get time requests to a maximum 286 + of 125 requests per second. If this limit is surpassed, the get time request 287 + will fail, leading to an increment in the phc_err_ts statistic. 288 + 289 + **PHC statistics** 290 + 291 + PHC can be monitored using debugfs (if mounted): 292 + 293 + .. code-block:: shell 294 + 295 + sudo cat /sys/kernel/debug/<domain:bus:slot.function>/phc_stats 296 + 297 + # for example: 298 + sudo cat /sys/kernel/debug/0000:00:06.0/phc_stats 299 + 300 + PHC errors must remain below 1% of all PHC requests to maintain the desired level of accuracy and reliability 301 + 302 + ================= ====================================================== 303 + **phc_cnt** | Number of successful retrieved timestamps (below expire timeout). 304 + **phc_exp** | Number of expired retrieved timestamps (above expire timeout). 305 + **phc_skp** | Number of skipped get time attempts (during block period). 306 + **phc_err_dv** | Number of failed get time attempts due to device errors (entering into block state). 307 + **phc_err_ts** | Number of failed get time attempts due to timestamp errors (entering into block state), 308 + | This occurs if driver exceeded the request limit or device received an invalid timestamp. 309 + ================= ====================================================== 310 + 311 + PHC timeouts: 312 + 313 + ================= ====================================================== 314 + **expire** | Max time for a valid timestamp retrieval, passing this threshold will fail 315 + | the get time request and block new requests until block timeout. 316 + **block** | Blocking period starts once get time request expires or fails, 317 + | all get time requests during block period will be skipped. 318 + ================= ====================================================== 319 + 227 320 Statistics 228 321 ========== 229 322