From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wm1-f43.google.com (mail-wm1-f43.google.com [209.85.128.43]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0EDEB35E93A for ; Wed, 4 Mar 2026 16:00:50 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.43 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772640053; cv=none; b=Dc8HOSDNQQqPWGMtSLowi/HI23Bsopyef2IYvNy8iVbUOggHy+FlJ4fEjGcz/F/nM4IXJSoDdpILSL8qIHuPktiY6ZCGI7NLA2q1eSm6Oq2Ic7B+ZaLwjViKPkzHtxdrntiMD6JBhf6YGaus+AdgSaIGmhdhZhkU2TnQgytjiAc= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1772640053; c=relaxed/simple; bh=suAlp0+6vIiTYE/DszDuVSfJ/B/GhkXRhq5R0j4plyk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=ew0/62GLzXQIgEOsTYAo7vMPn1UokBHWl142pew/b+nSM6on7tTIz2BXR9hjb61aTkr17mT5ZjXMJd6ciarHK0U67MetNVlDzKhhsEsNVL1FKfKrz8f9VVKT1rSVJbluAEeXd7ZJyBNDkN7l2Xz5K2ErZCtUCkmT3SC3H8xWXng= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=resnulli.us; spf=none smtp.mailfrom=resnulli.us; dkim=pass (2048-bit key) header.d=resnulli-us.20230601.gappssmtp.com header.i=@resnulli-us.20230601.gappssmtp.com header.b=3dJzgiFT; arc=none smtp.client-ip=209.85.128.43 Authentication-Results: smtp.subspace.kernel.org; dmarc=none (p=none dis=none) header.from=resnulli.us Authentication-Results: smtp.subspace.kernel.org; spf=none smtp.mailfrom=resnulli.us Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=resnulli-us.20230601.gappssmtp.com header.i=@resnulli-us.20230601.gappssmtp.com header.b="3dJzgiFT" Received: by mail-wm1-f43.google.com with SMTP id 5b1f17b1804b1-4836f4cbe0bso59326235e9.3 for ; Wed, 04 Mar 2026 08:00:50 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=resnulli-us.20230601.gappssmtp.com; s=20230601; t=1772640049; x=1773244849; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=T3g0UTN2sEfKe2VfEgfWZcWamkZLOLTyGyEUUMk8B8w=; b=3dJzgiFToOxO+iz1yiW9nfsncciLnIlxgjjvboNOdkglu8CyhtZ9MO7v4Bh4FIgsfU MrzNoTeAvvm3WypyqQDUxai1rBbx5zEgAyYSAUWqdfM+vqy/Ek5qrOnT5ZXumpikCGuc hiR+rjO8FsnIliBbBDujSAidq9HJlaSIxUWZQPYkImNoxHusJaSMOp/cwAPWkq7+J5oO hQPyphCOlAwKP3qLXwp5rdAiTr+iKzXSR1JeHBCZggOf4XejQt1rITdMSiKgw7OQggM0 duVGj/3Nvtae+W/DyqmouReOq8M+baixXfq6Fd0yxMVabI2h4iXe0f3BVx/6KIyB0aAa pxSg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1772640049; x=1773244849; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=T3g0UTN2sEfKe2VfEgfWZcWamkZLOLTyGyEUUMk8B8w=; b=rI0N8L8w2csJUbWBXUM9lqH2Lt2hxQ4u0TRu5D8CplvC6nwzjKL6JQldnRi7r9avL9 mIZx+ff2Bhw2+LZW1NGyWsyyjhMB731pVeph+tnsY8s9Dbr7uOeYPdfHgRtJ1QUZhg/i S2N2EoBE8KJBvkUjvH1rmUC4J1xFCO13U6IkeQuaHW7lq5SGUSeApkcjYfKtavbI15w+ r1Rfs29oogOYSgprWOlJ12xg8qXqYZnxw9CPHGGCrsWbRHI+GPh6hzyLVCwqnGerCqFn DvREjj7SRV99NjTu8dfzT/E9sjrKEr8dKknB8T8LhnBjKOC9HSTzLUbQaYeM/XnnZR8M lFzw== X-Gm-Message-State: AOJu0YxVOBI0Q384NijWpy2u7Dws5DoeB7iUMe0URqC19VTMBpFTnukv UL08o5q061aaib3fapdL8yGJYhZjDGhUZUWdOQ24xowAR1fo29BMIkSiwWIDWtCsd5xWyBomyPN qp+ARL8Q= X-Gm-Gg: ATEYQzw9T7lM23+a+t7Y5vc9gdHvLQulHdHcN7hiA6okm/Q+RGttRVgu3qf9IAhlTZF 0FHahBU4g2yf++JpVIitLMnAKpmuOQHdB7AP+qB7FLqDl8gq/RfEO2AOUwCZ0JnybfDt8xFBFR7 Wq/gqWcUm77x7nZYxLlKgKHwCdYrm/2TrLTFSxx2pELVDzdhfXB6mqWDrbhNUfjpD4/NeJLpMh8 icv6nK26e2kZdrqYVfCnxIhZGKCRiHA4DavuoxTbsOGK+ZCrFu5zKXnVKe8v4ycuNI9o8HD1U6D YMRYu72IuFG/Q7AFxmJoipCNmiWXUThIAPSz4HDRr9NmQOz+ygPAWTIj7DK+Ho8kD536qS7szSk YmsTCQARSUPzkPQ3b7I7Leo16ILdmrGEVDzaEehrlZMIuZOaXNDVGKGkZpffzh9tHkfnl3n6L6w VVotRV8SI4wULKj+B3HmC+CyxXNIepMofS5ImJlVUCK46p6wrxSUnJU6rV X-Received: by 2002:a05:600c:529b:b0:47a:7fdd:2906 with SMTP id 5b1f17b1804b1-485198668eemr42237935e9.12.1772640049317; Wed, 04 Mar 2026 08:00:49 -0800 (PST) Received: from localhost (46-13-72-179.customers.tmcz.cz. [46.13.72.179]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-485188914ddsm74604335e9.12.2026.03.04.08.00.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 04 Mar 2026 08:00:48 -0800 (PST) From: Jiri Pirko To: netdev@vger.kernel.org Cc: davem@davemloft.net, edumazet@google.com, kuba@kernel.org, pabeni@redhat.com, horms@kernel.org, donald.hunter@gmail.com, corbet@lwn.net, skhan@linuxfoundation.org, saeedm@nvidia.com, leon@kernel.org, tariqt@nvidia.com, mbloch@nvidia.com, przemyslaw.kitszel@intel.com, mschmidt@redhat.com, andrew+netdev@lunn.ch, rostedt@goodmis.org, mhiramat@kernel.org, mathieu.desnoyers@efficios.com, chuck.lever@oracle.com, matttbe@kernel.org, cjubran@nvidia.com, daniel.zahka@gmail.com, linux-doc@vger.kernel.org, linux-rdma@vger.kernel.org, linux-trace-kernel@vger.kernel.org Subject: [PATCH net-next v3 12/13] documentation: networking: add shared devlink documentation Date: Wed, 4 Mar 2026 17:00:21 +0100 Message-ID: <20260304160022.6114-13-jiri@resnulli.us> X-Mailer: git-send-email 2.51.1 In-Reply-To: <20260304160022.6114-1-jiri@resnulli.us> References: <20260304160022.6114-1-jiri@resnulli.us> Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: Jiri Pirko Document shared devlink instances for multiple PFs on the same chip. Signed-off-by: Jiri Pirko --- v2->v3: - describing 2 models of use os shared device, with and without per-PF instances v1->v2: - fixed number of "="'s --- .../networking/devlink/devlink-shared.rst | 97 +++++++++++++++++++ Documentation/networking/devlink/index.rst | 1 + 2 files changed, 98 insertions(+) create mode 100644 Documentation/networking/devlink/devlink-shared.rst diff --git a/Documentation/networking/devlink/devlink-shared.rst b/Documentation/networking/devlink/devlink-shared.rst new file mode 100644 index 000000000000..16bf6a7d25d9 --- /dev/null +++ b/Documentation/networking/devlink/devlink-shared.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Devlink Shared Instances +======================== + +Overview +======== + +Shared devlink instances allow multiple physical functions (PFs) on the same +chip to share a devlink instance for chip-wide operations. + +Multiple PFs may reside on the same physical chip, running a single firmware. +Some of the resources and configurations may be shared among these PFs. The +shared devlink instance provides an object to pin configuration knobs on. + +There are two possible usage models: + +1. The shared devlink instance is used alongside individual PF devlink + instances, providing chip-wide configuration in addition to per-PF + configuration. +2. The shared devlink instance is the only devlink instance, without + per-PF instances. + +It is up to the driver to decide which usage model to use. + +The shared devlink instance is not backed by any struct *device*. + +Implementation +============== + +Architecture +------------ + +The implementation uses: + +* **Chip identification**: PFs are grouped by chip using a driver-specific identifier +* **Shared instance management**: Global list of shared instances with reference counting + +API Functions +------------- + +The following functions are provided for managing shared devlink instances: + +* ``devlink_shd_get()``: Get or create a shared devlink instance identified by a string ID +* ``devlink_shd_put()``: Release a reference on a shared devlink instance +* ``devlink_shd_get_priv()``: Get private data from shared devlink instance + +Initialization Flow +------------------- + +1. **PF calls shared devlink init** during driver probe +2. **Chip identification** using driver-specific method to determine device identity +3. **Get or create shared instance** using ``devlink_shd_get()``: + + * The function looks up existing instance by identifier + * If none exists, creates new instance: + - Allocates and registers devlink instance + - Adds to global shared instances list + - Increments reference count + +4. **Set nested devlink instance** for the PF devlink instance using + ``devl_nested_devlink_set()`` before registering the PF devlink instance + +Cleanup Flow +------------ + +1. **Cleanup** when PF is removed +2. **Call** ``devlink_shd_put()`` to release reference (decrements reference count) +3. **Shared instance is automatically destroyed** when the last PF removes (reference count reaches zero) + +Chip Identification +------------------- + +PFs belonging to the same chip are identified using a driver-specific method. +The driver is free to choose any identifier that is suitable for determining +whether two PFs are part of the same device. Examples include: + +* **PCI VPD serial numbers**: Extract from PCI VPD +* **Device tree properties**: Read chip identifier from device tree +* **Other hardware-specific identifiers**: Any unique identifier that groups PFs by chip + +Locking +------- + +A global mutex (``shd_mutex``) protects the shared instances list during registration/deregistration. + +Similarly to other nested devlink instance relationships, devlink lock of +the shared instance should be always taken after the devlink lock of PF. + +Reference Counting +------------------ + +Each shared devlink instance maintains a reference count (``refcount_t refcount``). +The reference count is incremented when ``devlink_shd_get()`` is called and decremented +when ``devlink_shd_put()`` is called. When the reference count reaches zero, the shared +instance is automatically destroyed. diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst index 35b12a2bfeba..f7ba7dcf477d 100644 --- a/Documentation/networking/devlink/index.rst +++ b/Documentation/networking/devlink/index.rst @@ -68,6 +68,7 @@ general. devlink-resource devlink-selftests devlink-trap + devlink-shared Driver-specific documentation ----------------------------- -- 2.51.1