Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/2218412/?format=api
{ "id": 2218412, "url": "http://patchwork.ozlabs.org/api/patches/2218412/?format=api", "web_url": "http://patchwork.ozlabs.org/project/linux-pci/patch/20260401073022.215805-5-a-garg7@ti.com/", "project": { "id": 28, "url": "http://patchwork.ozlabs.org/api/projects/28/?format=api", "name": "Linux PCI development", "link_name": "linux-pci", "list_id": "linux-pci.vger.kernel.org", "list_email": "linux-pci@vger.kernel.org", "web_url": null, "scm_url": null, "webscm_url": null, "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20260401073022.215805-5-a-garg7@ti.com>", "list_archive_url": null, "date": "2026-04-01T07:30:22", "name": "[v2,4/4] Documentation: PCI: Add documentation for DOE endpoint support", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "3542946f0487c0a3445d593cf83b0d25dc2259f6", "submitter": { "id": 92467, "url": "http://patchwork.ozlabs.org/api/people/92467/?format=api", "name": "Aksh Garg", "email": "a-garg7@ti.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/linux-pci/patch/20260401073022.215805-5-a-garg7@ti.com/mbox/", "series": [ { "id": 498286, "url": "http://patchwork.ozlabs.org/api/series/498286/?format=api", "web_url": "http://patchwork.ozlabs.org/project/linux-pci/list/?series=498286", "date": "2026-04-01T07:30:19", "name": "PCI: Add DOE support for endpoint", "version": 2, "mbox": "http://patchwork.ozlabs.org/series/498286/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/2218412/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/2218412/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "\n <linux-pci+bounces-51649-incoming=patchwork.ozlabs.org@vger.kernel.org>", "X-Original-To": [ "incoming@patchwork.ozlabs.org", "linux-pci@vger.kernel.org" ], "Delivered-To": "patchwork-incoming@legolas.ozlabs.org", "Authentication-Results": [ "legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=ti.com header.i=@ti.com header.a=rsa-sha256\n header.s=selector1 header.b=FrNRs5CK;\n\tdkim-atps=neutral", "legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=vger.kernel.org\n (client-ip=2600:3c09:e001:a7::12fc:5321; helo=sto.lore.kernel.org;\n envelope-from=linux-pci+bounces-51649-incoming=patchwork.ozlabs.org@vger.kernel.org;\n receiver=patchwork.ozlabs.org)", "smtp.subspace.kernel.org;\n\tdkim=pass (1024-bit key) header.d=ti.com header.i=@ti.com header.b=\"FrNRs5CK\"", "smtp.subspace.kernel.org;\n arc=fail smtp.client-ip=52.101.201.26", "smtp.subspace.kernel.org;\n dmarc=pass (p=quarantine dis=none) header.from=ti.com", "smtp.subspace.kernel.org;\n spf=pass smtp.mailfrom=ti.com" ], "Received": [ "from sto.lore.kernel.org (sto.lore.kernel.org\n [IPv6:2600:3c09:e001:a7::12fc:5321])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4flxhk0s5mz1yGH\n\tfor <incoming@patchwork.ozlabs.org>; Wed, 01 Apr 2026 18:39:50 +1100 (AEDT)", "from smtp.subspace.kernel.org (conduit.subspace.kernel.org\n [100.90.174.1])\n\tby sto.lore.kernel.org (Postfix) with ESMTP id 5C891306F62F\n\tfor <incoming@patchwork.ozlabs.org>; Wed, 1 Apr 2026 07:32:59 +0000 (UTC)", "from localhost.localdomain (localhost.localdomain [127.0.0.1])\n\tby smtp.subspace.kernel.org (Postfix) with ESMTP id 4269839A073;\n\tWed, 1 Apr 2026 07:30:55 +0000 (UTC)", "from PH7PR06CU001.outbound.protection.outlook.com\n (mail-westus3azon11010026.outbound.protection.outlook.com [52.101.201.26])\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby smtp.subspace.kernel.org (Postfix) with ESMTPS id B44D5397E9E;\n\tWed, 1 Apr 2026 07:30:52 +0000 (UTC)", "from BYAPR02CA0063.namprd02.prod.outlook.com (2603:10b6:a03:54::40)\n by DS0PR10MB6078.namprd10.prod.outlook.com (2603:10b6:8:ca::5) with Microsoft\n SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id\n 15.20.9745.28; Wed, 1 Apr 2026 07:30:49 +0000", "from CO1PEPF000075F1.namprd03.prod.outlook.com\n (2603:10b6:a03:54:cafe::19) by BYAPR02CA0063.outlook.office365.com\n (2603:10b6:a03:54::40) with Microsoft SMTP Server (version=TLS1_3,\n cipher=TLS_AES_256_GCM_SHA384) id 15.20.9745.29 via Frontend Transport; Wed,\n 1 Apr 2026 07:30:50 +0000", "from lewvzet200.ext.ti.com (198.47.23.194) by\n CO1PEPF000075F1.mail.protection.outlook.com (10.167.249.40) with Microsoft\n SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id\n 15.20.9745.21 via Frontend Transport; Wed, 1 Apr 2026 07:30:49 +0000", "from DLEE207.ent.ti.com (157.170.170.95) by lewvzet200.ext.ti.com\n (10.4.14.103) with Microsoft SMTP Server (version=TLS1_2,\n cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.2562.20; Wed, 1 Apr\n 2026 02:30:47 -0500", "from DLEE202.ent.ti.com (157.170.170.77) by DLEE207.ent.ti.com\n (157.170.170.95) with Microsoft SMTP Server (version=TLS1_2,\n cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.2562.20; Wed, 1 Apr\n 2026 02:30:47 -0500", "from lelvem-mr06.itg.ti.com (10.180.75.8) by DLEE202.ent.ti.com\n (157.170.170.77) with Microsoft SMTP Server (version=TLS1_2,\n cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.2562.20 via Frontend\n Transport; Wed, 1 Apr 2026 02:30:47 -0500", "from a0507033-hp.dhcp.ti.com (a0507033-hp.dhcp.ti.com\n [172.24.231.225])\n\tby lelvem-mr06.itg.ti.com (8.18.1/8.18.1) with ESMTP id 6317UN3T3832504;\n\tWed, 1 Apr 2026 02:30:43 -0500" ], "ARC-Seal": [ "i=2; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116;\n\tt=1775028655; cv=fail;\n b=b4EnU8rvRxwcwSJNRn0HyhgueU2UraJj/IInVyxWG7Qt3lZ1ekT4+wpqZxMO1J63Ywg15k/jBDavPgxfS5CELZJOhE4U9hoZYJmqzSxMP/mD+Jkk7WJidKdM1HyJwpewrrwgFAADoRQZq9dzX25qZs6YSNAY4uJ0QDeOwLl7JII=", "i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none;\n b=rW7sq83J6La+HXYzrHURVSxjwTcxh5oDtr6r/sf4J+DsFTryDPubSN+lZbE5BMzZFE50G7ZwLDU8d1oFl6AHZUckQ4UADS8Px5rSx/Zse/dgF5rzx5xPPwESIw3DWW5uN610He8N6Ubc0u9YEv7rGj7kGxohPF/zjwhjftrZS14eM74GjDDqjOlfSWlVEV4zakec4J970iWIfrkT6ft1A5DK9yq4rYZX4eDWvlzlJnlS29KgXtFr43YYFGy/i5hxXrRVvklbEwy21/i8tGNevak+MlOJB6H0ZhDhSqpiVPSu+LXliwsoqflO3AOH46m92QTJgzgKTm+e4IoKu0SvVA==" ], "ARC-Message-Signature": [ "i=2; a=rsa-sha256; d=subspace.kernel.org;\n\ts=arc-20240116; t=1775028655; c=relaxed/simple;\n\tbh=n3mSuPTxG7RpZyPt2jFJiYIKdb+tlzjKhmB04SSGMSI=;\n\th=From:To:CC:Subject:Date:Message-ID:In-Reply-To:References:\n\t MIME-Version:Content-Type;\n b=cc7Ywqk4L7aCEUZENijKGdcXFzI9WRGuvnL7q6HsZK7wtu/MUUZOeZdF3FzffNxGH5sRabGtlbIxa4UIBgec5euq1SRoLY6IABWXCyDTUBucj5LimivIVom2jogOaJTQQmiAJHdO/OcojAMC4r35M+//BDPNAr6TzQ9s/pvH+4w=", "i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com;\n s=arcselector10001;\n h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;\n bh=JjpNCIGW+5eeZlYd0i8dzEEOmb+0Z81fHNYsUKvTnZQ=;\n b=YBFi8tOH5+jOl4IZNvnetZH8VkgyHdNzt+5odRUL/zi8ZbszqHAJUaY2B0M5PeXv48zTzDLf6I26TVS0WEIEGZOTz0DtZWgNdHePNp73raA9GqD2JD35JxIN/A7Z5RbbEp9bKNEqEDQTvcef+G9IRn1ownc+nK3l3/JLZ7u4HFDwMDyJB2vFW6aXlYYon8lUrRTIsQNuetdErxUJ0x94rS/tiTu3eF4llUb2Hd/QjgoDvkzjX/t+owPrhI3i68U/2cFZwOt2g2jtdow+whtIz+oAGzD+gt/+EXmB4E8ISHXCjM+ezHjOMVdo7ZdK2VzJ7zpjkmXR2KHPTPpRQPmsdg==" ], "ARC-Authentication-Results": [ "i=2; smtp.subspace.kernel.org;\n dmarc=pass (p=quarantine dis=none) header.from=ti.com;\n spf=pass smtp.mailfrom=ti.com;\n dkim=pass (1024-bit key) header.d=ti.com header.i=@ti.com header.b=FrNRs5CK;\n arc=fail smtp.client-ip=52.101.201.26", "i=1; mx.microsoft.com 1; spf=pass (sender ip is\n 198.47.23.194) smtp.rcpttodomain=vger.kernel.org smtp.mailfrom=ti.com;\n dmarc=pass (p=quarantine sp=none pct=100) action=none header.from=ti.com;\n dkim=none (message not signed); arc=none (0)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=ti.com; s=selector1;\n h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck;\n bh=JjpNCIGW+5eeZlYd0i8dzEEOmb+0Z81fHNYsUKvTnZQ=;\n b=FrNRs5CKIQCipiE4VSmxUgvj6Y4/xmSuzK08pA/PH64jO1iDpeWt3TbU6H2LH2j5MixQC/arIQvIIhFtfMifhIovL/63fx4JpIf0tSESFxRvv3OrfEMThOASDk+4jJAFhB8/zIoQnhDTddu648lryKuQMV9dOwyPVt93GxMAtV0=", "X-MS-Exchange-Authentication-Results": "spf=pass (sender IP is 198.47.23.194)\n smtp.mailfrom=ti.com; dkim=none (message not signed) header.d=none;dmarc=pass\n action=none header.from=ti.com;", "Received-SPF": "Pass (protection.outlook.com: domain of ti.com designates\n 198.47.23.194 as permitted sender) receiver=protection.outlook.com;\n client-ip=198.47.23.194; helo=lewvzet200.ext.ti.com; pr=C", "From": "Aksh Garg <a-garg7@ti.com>", "To": "<linux-pci@vger.kernel.org>, <linux-doc@vger.kernel.org>,\n\t<mani@kernel.org>, <kwilczynski@kernel.org>, <bhelgaas@google.com>,\n\t<corbet@lwn.net>, <kishon@kernel.org>, <skhan@linuxfoundation.org>,\n\t<lukas@wunner.de>, <cassel@kernel.org>, <alistair@alistair23.me>", "CC": "<linux-arm-kernel@lists.infradead.org>, <linux-kernel@vger.kernel.org>,\n\t<s-vadapalli@ti.com>, <danishanwar@ti.com>, <srk@ti.com>, <a-garg7@ti.com>", "Subject": "[PATCH v2 4/4] Documentation: PCI: Add documentation for DOE endpoint\n support", "Date": "Wed, 1 Apr 2026 13:00:22 +0530", "Message-ID": "<20260401073022.215805-5-a-garg7@ti.com>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20260401073022.215805-1-a-garg7@ti.com>", "References": "<20260401073022.215805-1-a-garg7@ti.com>", "Precedence": "bulk", "X-Mailing-List": "linux-pci@vger.kernel.org", "List-Id": "<linux-pci.vger.kernel.org>", "List-Subscribe": "<mailto:linux-pci+subscribe@vger.kernel.org>", "List-Unsubscribe": "<mailto:linux-pci+unsubscribe@vger.kernel.org>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=\"UTF-8\"", "Content-Transfer-Encoding": "8bit", "X-C2ProcessedOrg": "333ef613-75bf-4e12-a4b1-8e3623f5dcea", "X-EOPAttributedMessage": "0", "X-MS-PublicTrafficType": "Email", "X-MS-TrafficTypeDiagnostic": "CO1PEPF000075F1:EE_|DS0PR10MB6078:EE_", "X-MS-Office365-Filtering-Correlation-Id": "00aa032d-c486-4fcc-8aed-08de8fc098c9", "X-MS-Exchange-SenderADCheck": "1", "X-MS-Exchange-AntiSpam-Relay": "0", "X-Microsoft-Antispam": "\n\tBCL:0;ARA:13230040|82310400026|1800799024|36860700016|376014|7416014|921020|22082099003|18002099003|56012099003;", "X-Microsoft-Antispam-Message-Info": "\n\tiKosfNV6v/7y1xUkJwPTOMa3ke3l6mPrbEwBsePXuoS3OL+UeqzY+1cJR9VxyOTnoEe6SqGmWCTGDDZzwB0U4YDuX1o7rKGjiejIT5CA0PTW7RRqIRR0Kaqwk27s+CZ6u6Mk+FDLNncuoNR2jU90iPmF+/Nisxp9v46DGqIC3pnOX5Wh2LJ9Yw++cL0CswD/7u+5foxN7v5FgeFYkE48ne1tgaJw57wWaT/MFlpGJ+lFw/UiLGQfC1Lq+TFdQIMobYs8VbqYoX0G76bAb7L8zKa0gUhdOXQK80FpYxC3vY2SmjBydrclnel69F8kXd3MbsvocVYFflK32v3e91dqgH+G00nlUEr/ahYdld4XkV6/RU+cdp6mQ3t0wTmrTi23hSXa1FAheF3ZUAba5dILipdAfWxEG+nW56k1XYQVjgog3n/wBAQE322KCaFFideRA0RKPmp0Jm2YCEwxY7NrskZO24lm/sNYOWPH4USJvDt9CSJ0So0R2c1Vify3PXZB19CQwPWZStVpRoe6NaIN9a7vmxpEZqGbbfsFyhH0uic/4TBTNj3/Tf2AZxG3z1K0wuXoPG727O49gqRx37hLZpxylUtGBxMx9QUHRBc4/SLOR4V6saZ69N1fqoaOfPgqPfY/gApDufFV78q7gkfa/d0sCjry1LTY+vonvDkjSvGEHEx7oBNrNm0V1k9EmAY7iRGL4aIynFIE5k+n9w90Ghn6IEx4jh7ySGGtqrbwG1HPsKzyKwzW5PJfl3hf96gxVP755Adyc4iOMbAg5l+hEjgTsGivn6gveYyhVEYUvBQcZTxTn61Q3KdvyPlri8naWW90iPNDi55/PPgDF/6OPg==", "X-Forefront-Antispam-Report": "\n\tCIP:198.47.23.194;CTRY:US;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:lewvzet200.ext.ti.com;PTR:InfoDomainNonexistent;CAT:NONE;SFS:(13230040)(82310400026)(1800799024)(36860700016)(376014)(7416014)(921020)(22082099003)(18002099003)(56012099003);DIR:OUT;SFP:1101;", "X-MS-Exchange-AntiSpam-MessageData-ChunkCount": "1", "X-MS-Exchange-AntiSpam-MessageData-0": "\n\tREHBLYleCkFi//ho229oNCJl9tNWh02h64jvoIb2lTZpTkCkeT4czfmH5qSUrKS34Kbjrw1+OrcLz+NudbqIuRFaes6OMAjD/acdmjEiIWUn6gQqfMEgts58a9Yq/Lfai1ftaAIFUupFARS84Dobw9aD31ER1Az7azVKO+2pxoR8fYdmmvvRB48Jgo3eX+Ht3Ch+pMDQzvW2s6noh8rFyn88n+85D11ZhAmTTmqOfJqhkzS6vhX4/rxsgjMSUHpOmPUkFi2q2LUDMlzA0UswbS06u6oAgduQKOStdzJMpbiru0C7oziTE2gDI5XCo89ESFNpCuU0WfjvUymZJYAz4HcCtF8rFGSAkJUjh2F4rGU1GrwKNM5LHQQZip3rsha7XdxT0qduvsTxkT8wYp0yXE/rEW5LeLxS0Q3Fzk3kZs6WXEN1JfP3ED3sMXqpNK/8", "X-OriginatorOrg": "ti.com", "X-MS-Exchange-CrossTenant-OriginalArrivalTime": "01 Apr 2026 07:30:49.1758\n (UTC)", "X-MS-Exchange-CrossTenant-Network-Message-Id": "\n 00aa032d-c486-4fcc-8aed-08de8fc098c9", "X-MS-Exchange-CrossTenant-Id": "e5b49634-450b-4709-8abb-1e2b19b982b7", "X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp": "\n TenantId=e5b49634-450b-4709-8abb-1e2b19b982b7;Ip=[198.47.23.194];Helo=[lewvzet200.ext.ti.com]", "X-MS-Exchange-CrossTenant-AuthSource": "\n\tCO1PEPF000075F1.namprd03.prod.outlook.com", "X-MS-Exchange-CrossTenant-AuthAs": "Anonymous", "X-MS-Exchange-CrossTenant-FromEntityHeader": "HybridOnPrem", "X-MS-Exchange-Transport-CrossTenantHeadersStamped": "DS0PR10MB6078" }, "content": "Document the architecture and implementation details for the Data Object\nExchange (DOE) framework for PCIe Endpoint devices.\n\nCo-developed-by: Siddharth Vadapalli <s-vadapalli@ti.com>\nSigned-off-by: Siddharth Vadapalli <s-vadapalli@ti.com>\nSigned-off-by: Aksh Garg <a-garg7@ti.com>\n---\n\nChanges since v1:\n- Squashed the patches [1] and [2], and moved the documentation file\n to Documentation/PCI/endpoint/pci-endpoint-doe.rst to match the existing\n naming scheme, as suggested by Niklas Cassel\n- Updated the documentation as per the design and implementaion changes\n made to previous patches in this series:\n * Updated for static protocol array instead of dynamic registration\n * Documented asynchronous callback model\n * Updated request/response flow with new callback signature\n * Updated memory ownership: DOE core frees request, driver frees response\n * Updated initialization and cleanup sections for new APIs\n\nv1: [1] https://lore.kernel.org/all/20260213123603.420941-2-a-garg7@ti.com/\n [2] https://lore.kernel.org/all/20260213123603.420941-5-a-garg7@ti.com/\n\n Documentation/PCI/endpoint/index.rst | 1 +\n .../PCI/endpoint/pci-endpoint-doe.rst | 318 ++++++++++++++++++\n 2 files changed, 319 insertions(+)\n create mode 100644 Documentation/PCI/endpoint/pci-endpoint-doe.rst", "diff": "diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst\nindex dd1f62e731c9..7c03d5abd2ef 100644\n--- a/Documentation/PCI/endpoint/index.rst\n+++ b/Documentation/PCI/endpoint/index.rst\n@@ -9,6 +9,7 @@ PCI Endpoint Framework\n \n pci-endpoint\n pci-endpoint-cfs\n+ pci-endpoint-doe\n pci-test-function\n pci-test-howto\n pci-ntb-function\ndiff --git a/Documentation/PCI/endpoint/pci-endpoint-doe.rst b/Documentation/PCI/endpoint/pci-endpoint-doe.rst\nnew file mode 100644\nindex 000000000000..03b7a69516f3\n--- /dev/null\n+++ b/Documentation/PCI/endpoint/pci-endpoint-doe.rst\n@@ -0,0 +1,318 @@\n+.. SPDX-License-Identifier: GPL-2.0-only or MIT\n+\n+.. include:: <isonum.txt>\n+\n+=============================================\n+Data Object Exchange (DOE) for PCIe Endpoint\n+=============================================\n+\n+:Copyright: |copy| 2026 Texas Instruments Incorporated\n+:Author: Aksh Garg <a-garg7@ti.com>\n+:Co-Author: Siddharth Vadapalli <s-vadapalli@ti.com>\n+\n+Overview\n+========\n+\n+DOE (Data Object Exchange) is a standard PCIe extended capability feature\n+introduced in the Data Object Exchange (DOE) ECN for PCIe r5.0. It is an optional\n+mechanism for system firmware/software running on root complex (host) to perform\n+:ref:`data object <data-object-term>` exchanges with an endpoint function. Each\n+data object is uniquely identified by the Vendor ID of the vendor publishing the\n+data object definition and a Data Object Type value assigned by that vendor.\n+\n+Think of DOE as a sophisticated mailbox system built into PCIe. The root complex\n+can send structured requests to the endpoint device through DOE mailboxes, and\n+the endpoint device responds with appropriate data. DOE mailboxes are implemented\n+as PCIe Extended Capabilities in endpoint devices, allowing multiple mailboxes\n+per function, each potentially supporting different data object protocols.\n+\n+The DOE support for root complex devices has already been implemented in\n+``drivers/pci/doe.c``.\n+\n+How DOE Works\n+=============\n+\n+The DOE mailbox operates through a simple request-response model:\n+\n+1. **Host sends request**: The root complex writes a data object (vendor ID, type,\n+ and payload) to the DOE write mailbox register (one DWORD at a time) of the\n+ endpoint function's config space and sets the GO bit in the DOE Status register\n+ to indicate that a request is ready for processing.\n+2. **Endpoint processes**: The endpoint function reads the request from DOE write\n+ mailbox register, sets the BUSY bit in the DOE Status register, identifies the\n+ protocol of the data object, and executes the appropriate handler.\n+3. **Endpoint responds**: The endpoint function writes the response data object to the\n+ DOE read mailbox register (one DWORD at a time), and sets the READY bit in the DOE\n+ Status register to indicate that the response is ready. If an error occurs during\n+ request processing (such as unsupported protocol or handler failure), the endpoint\n+ sets the ERROR bit in the DOE Status register instead of the READY bit.\n+4. **Host reads response**: The root complex retrieves the response data from the DOE read\n+ mailbox register once the READY bit is set in the DOE Status register, and then writes\n+ any value to this register to indicate a successful read. If the ERROR bit was set,\n+ the root complex discards the response and performs error handling as needed.\n+\n+Each mailbox operates independently and can handle one transaction at a time. The\n+DOE specification supports data objects of size up to 256KB (2\\ :sup:`18` dwords).\n+\n+For complete DOE capability details, refer to `PCI Express Base Specification Revision 7.0,\n+Section 6.30 - Data Object Exchange (DOE)`.\n+\n+Key Terminologies\n+=================\n+\n+.. _data-object-term:\n+\n+**Data Object**\n+ A structured, vendor-defined, or standard-defined message exchanged between\n+ root complex and endpoint function via DOE capability registers in configuration\n+ space of the function.\n+\n+**Mailbox**\n+ A DOE capability on the endpoint device, where each physical function can have\n+ multiple mailboxes.\n+\n+**Protocol**\n+ A specific type of DOE communication data object identified by a Vendor ID and Type.\n+\n+**Handler**\n+ A function that processes DOE requests of a specific protocol and generates responses.\n+\n+Architecture of DOE Implementation for Endpoint\n+===============================================\n+\n+.. code-block:: text\n+\n+ +------------------+\n+ | |\n+ | Root Complex |\n+ | |\n+ +--------^---------+\n+ |\n+ | Config space access\n+ | over PCIe link\n+ |\n+ +----------v-----------+\n+ | |\n+ | PCIe Controller |\n+ | as Endpoint |\n+ | |\n+ | +-----------------+ |\n+ | | DOE Mailbox | |\n+ | +-------^---------+ |\n+ +----------|-----------+\n+ +-----------|---------------------------------------------------------------+\n+ | | +--------------------+ |\n+ | +---------v--------+ Allocate | +--------------+ | |\n+ | | |-------------------------------->| Request | | |\n+ | | EP Controller | +--->| Buffer | | |\n+ | | Driver | Free | | +--------------+ | |\n+ | | |--------------------------+ | | | |\n+ | +--------^---------+ | | | | |\n+ | | | | | | |\n+ | | | | | | |\n+ | | pci_ep_doe_process_request() | | | | |\n+ | | | | | | |\n+ | +--------v---------+ Free | | | | |\n+ | | |----------------------------+ | DDR | |\n+ | | DOE EP Core |<----+ | | | |\n+ | | (doe-ep.c) | | Discovery | | | |\n+ | | |-----+ Protocol Handler | | | |\n+ | +--------^---------+ | | | |\n+ | | | | | |\n+ | | protocol_handler() | | | |\n+ | | | | | |\n+ | +--------v---------+ | | | |\n+ | | | | | +--------------+ | |\n+ | | Protocol Handler | +----->| Response | | |\n+ | | Module |-------------------------------->| Buffer | | |\n+ | | (CMA/SPDM/Other) | Allocate | +--------------+ | |\n+ | | | | | |\n+ | +------------------+ | | |\n+ | +--------------------+ |\n+ +---------------------------------------------------------------------------+\n+\n+Initialization and Cleanup\n+--------------------------\n+\n+**Framework Initialization and DOE Setup**\n+\n+The EPC core provides the ``pci_epc_doe_setup(epc)`` API for centralized DOE\n+mailbox discovery and registration. The controller driver calls this API during\n+its probe sequence if DOE is supported.\n+\n+This API performs the following steps:\n+\n+1. Calls ``pci_ep_doe_init(epc)``, which initializes the xarray data structure\n+ (a resizable array data structure defined in linux) named ``doe_mbs`` that\n+ stores metadata of DOE mailboxes for the controller in ``struct pci_epc``.\n+2. Discovers all DOE capabilities in the endpoint function's configuration space\n+ for each function. For each discovered DOE capability, calls\n+ ``pci_ep_doe_add_mailbox(epc, func_no, cap_offset)`` to register the mailbox.\n+\n+Each DOE mailbox structure created by ``pci_ep_doe_add_mailbox()`` gets an\n+ordered workqueue allocated for processing DOE requests sequentially for that\n+mailbox, enabling concurrent request handling across different mailboxes. Each\n+mailbox is uniquely identified by the combination of physical function number\n+and capability offset for that controller.\n+\n+**Cleanup**\n+\n+The EPC core provides the ``pci_epc_doe_destroy(epc)`` API for centralized DOE\n+cleanup. The controller driver calls this API during its remove sequence\n+if DOE is supported.\n+\n+This API calls ``pci_ep_doe_destroy(epc)``, which destroys all registered\n+mailboxes, cancels any pending tasks, flushes and destroys the workqueues,\n+and frees all memory allocated to the mailboxes.\n+\n+Protocol Handler Support\n+------------------------\n+\n+Protocol implementations (such as CMA, SPDM, or vendor-specific protocols) are\n+supported through a static array of protocol handlers.\n+\n+When a new DOE protocol library is introduced, its handler function is added to\n+the static ``pci_doe_protocols`` array in ``drivers/pci/endpoint/pci-ep-doe.c``.\n+The discovery protocol (VID = 0x0001 (PCI-SIG vendor ID), Type = 0x00 (discovery\n+protocol)) is included in this static array and handled internally by the\n+DOE EP core.\n+\n+Request Handling\n+----------------\n+\n+The complete flow of a DOE request from the root complex to the response:\n+\n+**Step 1: Root Complex → EP Controller Driver**\n+\n+The root complex writes a DOE request (Vendor ID, Type, and Payload) to the\n+DOE write mailbox register in the endpoint function's configuration space and sets\n+the GO bit in the DOE Control register, indicating that the request is ready for\n+processing.\n+\n+**Step 2: EP Controller Driver → DOE EP Core**\n+\n+The controller driver reads the request header to determine the data object\n+length. Based on this length field, it allocates a request buffer in memory\n+(DDR) of the appropriate size. The driver then reads the complete request\n+payload from the DOE write mailbox register and converts the data from\n+little-endian format (the format followed in the PCIe transactions over the\n+link) to CPU-native format using ``le32_to_cpu()``. The driver defines a\n+completion callback function with signature ``void (*complete)(u8 func_no,\n+u16 cap_offset, int status, u16 vendor, u8 type, void *response_pl,\n+size_t response_pl_sz)`` to be invoked when the request processing completes.\n+The driver then calls ``pci_ep_doe_process_request(epc, func_no, cap_offset,\n+vendor, type, request, request_sz, complete)`` to hand off the request to the\n+DOE EP core. This function returns immediately after queuing the work\n+(without blocking), and the driver sets the BUSY bit in the DOE Status register.\n+\n+**Step 3: DOE EP Core Processing**\n+\n+The DOE EP core creates a task structure and submits it to the mailbox's ordered\n+workqueue. This ensures that requests for each mailbox are processed\n+sequentially, one at a time, as required by the DOE specification. It looks up\n+the protocol handler based on the Vendor ID and Type from the request header,\n+and executes the handler function.\n+\n+**Step 4: Protocol Handler Execution**\n+\n+The workqueue executes the task by calling the registered protocol handler:\n+``handler(request, request_sz, &response, &response_sz)``. The handler processes\n+the request, allocates a response buffer in memory (DDR), builds the response\n+data, and returns the response pointer and size. For the discovery protocol,\n+the DOE EP core handles this directly without invoking an external handler.\n+\n+**Step 5: DOE EP Core → EP Controller Driver**\n+\n+After the protocol handler completes, the DOE EP core frees the request buffer,\n+and invokes the completion callback provided by the controller driver asynchronously.\n+The callback receives the function number, capability offset (to identify the mailbox),\n+status code indicating the result of request processing, vendor ID and type of the data\n+object, the response buffer, and its size.\n+\n+**Step 6: EP Controller Driver → Root Complex**\n+\n+The controller driver converts the response from CPU-native format to\n+little-endian format using ``cpu_to_le32()``, writes the response to DOE read\n+mailbox register, and sets the READY bit in the DOE Status register. The root\n+complex then reads the response from the read mailbox register. Finally, the controller\n+driver frees the response buffer (which the handler allocated).\n+\n+Asynchronous Request Processing\n+-------------------------------\n+\n+The DOE-EP framework implements asynchronous request processing because an\n+endpoint function can have multiple instances of DOE mailboxes, and requests may\n+be interleaved across these mailboxes. Request processing of one mailbox should\n+not result in blocking request processing of other mailboxes. Hence, requests\n+on each mailbox need to be handled in parallel for optimization.\n+\n+For the EP controller driver to handle requests on multiple mailboxes in\n+parallel, ``pci_ep_doe_process_request()`` must be asynchronous. The function\n+returns immediately after submitting the request to the mailbox's workqueue,\n+without waiting for the request to complete. A completion callback provided by\n+the controller driver is invoked asynchronously when request processing\n+finishes. This asynchronous design enables concurrent processing of requests\n+across different mailboxes.\n+\n+Abort Handling\n+--------------\n+\n+The DOE specification allows the root complex to abort ongoing DOE operations\n+by setting the ABORT bit in the DOE Control register.\n+\n+**Trigger**\n+\n+When the root complex sets the ABORT bit, the EP controller driver detects this\n+condition (typically in an interrupt handler or register polling routine). The\n+action taken depends on the timing of the abort:\n+\n+- **ABORT during request transfer**: If the ABORT bit is set while the root complex\n+ is still transferring the request to the mailbox registers, the controller driver\n+ discards the request and no call to ``pci_ep_doe_abort()`` is needed.\n+\n+- **ABORT after request submission**: If the ABORT bit is set after the request\n+ has been fully received and submitted to the DOE EP core via\n+ ``pci_ep_doe_process_request()``, the controller driver must call\n+ ``pci_ep_doe_abort(epc, func_no, cap_offset)`` for the affected mailbox to\n+ perform abort sequence in the DOE EP core.\n+\n+**Abort Sequence**\n+\n+The abort function performs the following actions:\n+\n+1. Sets the CANCEL flag on the mailbox to prevent queued requests from starting\n+2. Flushes the workqueue to wait for any currently executing handler to complete\n+ (handlers cannot be interrupted mid-execution)\n+3. Clears the CANCEL flag to allow the mailbox to accept new requests\n+\n+Queued requests that have not started execution will be aborted with an error\n+status. The currently executing request will complete normally, and the controller\n+will reject the response if it arrives after the abort sequence has been triggered.\n+\n+.. note::\n+ Independent of when the ABORT bit is triggered, the controller driver must\n+ clear the ERROR, BUSY, and READY bits in the DOE Status register after\n+ completing the abort operation to reset the mailbox to an idle state.\n+\n+Error Handling\n+--------------\n+\n+Errors can occur during DOE request processing for various reasons, such as\n+unsupported protocols, handler failures, or memory allocation failures.\n+\n+**Error Detection**\n+\n+When an error occurs during DOE request processing, the DOE EP core propagates this error\n+back to the controller driver either through the ``pci_ep_doe_process_request()`` return value,\n+or the status code passed to the completion callback.\n+\n+**Error Response**\n+\n+When the controller driver receives an error code, it sets the ERROR bit in the DOE Status\n+register instead of writing a response to the read mailbox register, and frees the buffers.\n+\n+API Reference\n+=============\n+\n+.. kernel-doc:: drivers/pci/endpoint/pci-ep-doe.c\n+ :export:\n", "prefixes": [ "v2", "4/4" ] }