NetBSD Problem Report #58576

From www@netbsd.org  Sat Aug 10 22:32:01 2024
Return-Path: <www@netbsd.org>
Received: from mail.netbsd.org (mail.netbsd.org [199.233.217.200])
	(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
	 key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256
	 client-signature RSA-PSS (2048 bits) client-digest SHA256)
	(Client CN "mail.NetBSD.org", Issuer "mail.NetBSD.org CA" (not verified))
	by mollari.NetBSD.org (Postfix) with ESMTPS id AD4A71A9242
	for <gnats-bugs@gnats.NetBSD.org>; Sat, 10 Aug 2024 22:32:01 +0000 (UTC)
Message-Id: <20240810223200.4990F1A9243@mollari.NetBSD.org>
Date: Sat, 10 Aug 2024 22:32:00 +0000 (UTC)
From: campbell+netbsd@mumble.net
Reply-To: campbell+netbsd@mumble.net
To: gnats-bugs@NetBSD.org
Subject: ifnet driver model is undocumented
X-Send-Pr-Version: www-1.0

>Number:         58576
>Category:       kern
>Synopsis:       ifnet driver model is undocumented
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sat Aug 10 22:35:00 +0000 2024
>Originator:     Taylor R Campbell
>Release:        current, 10, 9, ...
>Organization:
The ifnetbsd(9) Foundation
>Environment:
>Description:
The driver model for network interfaces is undocumented and non-obvious.
>How-To-Repeat:
$ man ifnet
man: no entry for ifnet in the manual.

>Fix:
Yes, please!

Here's a sketch that should be put into an ifnet(9) man page, similar to the usbnet(9) model we have (https://man.NetBSD.org/usbnet.9):

1. (under IFNET_LOCK) if_init:
   (a) resets hardware, while nothing else is touching registers
   (b) programs multicast filter
   (c) starts Tx/Rx and tick for mii/watchdog
   (d) sets IFF_RUNNING

2. concurrently:
   - (mii lock) periodic mii ticks or (with IFNET_LOCK too) ifmedia ioctls
   - (tx lock) Tx submissions
   - (rx lock) Rx notifications
   - (multicast filter lock) SIOCADDMULTI/SIOCDELMULTI
   - (ic lock) 802.11 state machine notifications
   - (IFNET_LOCK) maybe other ioctls (some of which return ENETRESET
     to cause an if_stop/init cycle in thread context)

3. (under IFNET_LOCK) if_stop:
   (a) clears IFF_RUNNING
   (b) halts Tx/Rx/tick and waits for completion
   (c) disables concurrent multicast updates
   (d) calls mii_down to wait for concurrent mii activity to quiesce
   (e) resets hardware, now that nothing is touching registers any more

The man page should also document all of the public struct ifnet::if_* members, like what the difference between if_start and if_init is (totally unrelated!), and what the difference between if_output and if_transmit is, and how if_percpuq works and where you're supposed to call bpf_mtap or if_deferred_start_init, and so on.

NetBSD Home
NetBSD PR Database Search

(Contact us) $NetBSD: query-full-pr,v 1.47 2022/09/11 19:34:41 kim Exp $
$NetBSD: gnats_config.sh,v 1.9 2014/08/02 14:16:04 spz Exp $
Copyright © 1994-2024 The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.