[Docs] Update Plugin EP docs (#27132)

### Description
<!-- Describe your changes. -->

Update plugin EP docs. Add a page on testing and move existing pages around.

### Motivation and Context
<!-- - Why is this change required? What problem does it solve?
- If it fixes an open issue, please link to the issue here. -->

Update documentation.

Author: edgchen1

docs/execution-providers/EP-Context-Design.md

@@ -479,7 +479,7 @@ return the `external_info` argument from the `output_model_onnx_initializer_hand
 - [C API functions](https://github.com/microsoft/onnxruntime/blob/879ec0392ad5128968440a4e5b5a0bb742494ae5/include/onnxruntime/core/session/onnxruntime_c_api.h#L7751-L7774)
 
 ### Usage example: cross-compilation with a plugin EP
-By default, ONNX Runtime only allows the use of [plugin EPs](./plugin-ep-libraries.md) that are compatible with real hardware devices discovered by ONNX Runtime.
+By default, ONNX Runtime only allows the use of [plugin EPs](./plugin-ep-libraries/) that are compatible with real hardware devices discovered by ONNX Runtime.
 To support the creation of compiled models targeted for hardware devices not present on the compiling machine (i.e., cross-compiling), a plugin EP may be allowed
 to create virtual hardware devices that an application can use to compile models.
 
@@ -645,7 +645,7 @@ OrtStatus* ORT_API_CALL EpFactoryVirtualGpu::GetSupportedDevicesImpl(OrtEpFactor
 - [Reference example plugin EP with virtual GPU](https://github.com/microsoft/onnxruntime/tree/main/onnxruntime/test/autoep/library/example_plugin_ep_virt_gpu)
 - [OrtEpApi::GetEnvConfigEntries C API function](https://github.com/microsoft/onnxruntime/blob/990ba5f0c3e0c8735fec8bf89dd11953224a9c03/include/onnxruntime/core/session/onnxruntime_ep_c_api.h#L1431-L1446)
 - [Ort::GetEnvConfigEntries C++ API function](https://github.com/microsoft/onnxruntime/blob/990ba5f0c3e0c8735fec8bf89dd11953224a9c03/include/onnxruntime/core/session/onnxruntime_cxx_api.h#L3531-L3532)
-- [Plugin EP library documentation](./plugin-ep-libraries.md)
+- [Plugin EP library documentation](./plugin-ep-libraries/)
 - [Additional Python usage examples in unit tests](https://github.com/microsoft/onnxruntime/blob/main/onnxruntime/test/python/onnxruntime_test_python_compile_api.py)
 - [Python ModelCompiler class](https://github.com/microsoft/onnxruntime/blob/a5ba2ba3998820dd8da111c90c420479aac7a11e/onnxruntime/python/onnxruntime_inference_collection.py#L680-L709)
 
@@ -694,6 +694,6 @@ ort.unregister_execution_provider_library(ep_lib_registration_name)
 ```
 
 #### References
-- [Plugin EP library documentation](./plugin-ep-libraries.md)
+- [Plugin EP library documentation](./plugin-ep-libraries/)
 - [Additional Python usage examples in unit tests](https://github.com/microsoft/onnxruntime/blob/main/onnxruntime/test/python/onnxruntime_test_python_compile_api.py)
 - [Python ModelCompiler class](https://github.com/microsoft/onnxruntime/blob/a5ba2ba3998820dd8da111c90c420479aac7a11e/onnxruntime/python/onnxruntime_inference_collection.py#L680-L709)

…ecution-providers/plugin-ep-libraries.md …in-ep-libraries/development-and-usage.mddocs/execution-providers/plugin-ep-libraries.md renamed to docs/execution-providers/plugin-ep-libraries/development-and-usage.md docs/execution-providers/plugin-ep-libraries.md renamed to docs/execution-providers/plugin-ep-libraries/development-and-usage.md

@@ -1,25 +1,23 @@
 ---
-title: Plugin EP libraries
-description: Plugin EP libraries
-parent: Execution Providers
-nav_order: 17
+title: Development and Usage
+description: Development and Usage
+grand_parent: Execution Providers
+parent: Plugin Execution Provider Libraries
+nav_order: 1
 redirect_from: /docs/reference/execution-providers/Plugin-EP-Libraries
 ---
 
-# Plugin Execution Provider Libraries
+# Plugin Execution Provider Library Development and Usage
 {: .no_toc }
 
+This page provides a reference for the APIs necessary to develop and use plugin EP libraries with ONNX Runtime.
+
 ## Contents
 {: .no_toc }
 
 * TOC placeholder
 {:toc}
 
-## Background
-An ONNX Runtime Execution Provider (EP) executes model operations on one or more hardware accelerators (e.g., GPU, NPU, etc.). ONNX Runtime provides a variety of built-in EPs, such as the default CPU EP. To enable further extensibility, ONNX Runtime supports user-defined plugin EP libraries that an application can register with ONNX Runtime for use in an ONNX Runtime inference session.<br/>
-
-This page provides a reference for the APIs necessary to develop and use plugin EP libraries with ONNX Runtime.
-
 ## Creating a plugin EP library
 A plugin EP is built as a dynamic/shared library that exports the functions `CreateEpFactories()` and `ReleaseEpFactory()`. ONNX Runtime calls `CreateEpFactories()` to obtain one or more instances of `OrtEpFactory`. An `OrtEpFactory` creates `OrtEp` instances and specifies the hardware devices supported by the EPs it creates.
 
@@ -45,7 +43,7 @@ The following table lists the **required** variables and functions that an imple
 
 <tr>
 <td>GetName</td>
-<td>Get the execution provider name.<br/><br/>The recommended convention for a plugin execution provider name is to have the name end with the suffix "PluginExecutionProvider". E.g., "ContosoAiPluginExecutionProvider".</td>
+<td>Get the execution provider name.<br/><br/>The recommended convention for an execution provider name is to have the name end with the suffix "ExecutionProvider". E.g., "ContosoAiExecutionProvider".</td>
 <td><a href="https://github.com/microsoft/onnxruntime/blob/16ae99ede405d3d6c59d7cce80c53f5f7055aeed/onnxruntime/test/autoep/library/ep.cc#L181">ExampleEp::GetNameImpl()</a></td>
 </tr>
 
@@ -330,7 +328,7 @@ For example, if a single factory instance supports both CPU and NPU, then the ca
   - ep_device_1: (factory_0, NPU)
 
 <br/>
-<p align="center"><img width="100%" src="../../images/plugin_ep_sd_lib_reg.png" alt="Sequence diagram showing registration and unregistration of a plugin EP library"/></p>
+<p align="center"><img width="100%" src="../../../images/plugin_ep_sd_lib_reg.png" alt="Sequence diagram showing registration and unregistration of a plugin EP library"/></p>
 
 ### Session creation with explicit OrtEpDevice(s)
 The application code below uses the API function [SessionOptionsAppendExecutionProvider_V2](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a285a5da8c9a63eff55dc48e4cf3b56f6) to add an EP from a library to an ONNX Runtime session.
@@ -374,7 +372,7 @@ env.UnregisterExecutionProviderLibrary(/*...*/);
 As shown in the following sequence diagram, ONNX Runtime calls `OrtEpFactory::CreateEp()` during session creation in order to create an instance of the plugin EP.
 
 <br/>
-<p align="center"><img width="100%" src="../../images/plugin_ep_sd_appendv2.png" alt="Sequence diagram showing session creation with explicit ep devices"/></p>
+<p align="center"><img width="100%" src="../../../images/plugin_ep_sd_appendv2.png" alt="Sequence diagram showing session creation with explicit ep devices"/></p>
 
 ### Session creation with automatic EP selection
 The application code below uses the API function [SessionOptionsSetEpSelectionPolicy](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a2ae116df2c6293e4094a6742a6c46f7e) to have ONNX Runtime automatically select an EP based on the user's policy (e.g., PREFER_NPU).
@@ -397,7 +395,7 @@ env.UnregisterExecutionProviderLibrary(/*...*/);
 ```
 
 <br/>
-<p align="center"><img width="100%" src="../../images/plugin_ep_sd_autoep.png" alt="Sequence diagram showing session creation with automatic EP selection"/></p>
+<p align="center"><img width="100%" src="../../../images/plugin_ep_sd_autoep.png" alt="Sequence diagram showing session creation with automatic EP selection"/></p>
 
 ## API reference
 API header files:

docs/execution-providers/plugin-ep-libraries/index.md

@@ -0,0 +1,11 @@
+---
+title: Plugin Execution Provider Libraries
+parent: Execution Providers
+has_children: true
+nav_order: 17
+---
+
+# Plugin Execution Provider Libraries
+An ONNX Runtime Execution Provider (EP) executes model operations on one or more hardware accelerators (e.g., GPU, NPU, etc.). ONNX Runtime provides a variety of built-in EPs, such as the default CPU EP. To enable further extensibility, ONNX Runtime supports user-defined plugin EP libraries that an application can register with ONNX Runtime for use in an ONNX Runtime inference session.
+
+This section provides a reference for plugin EP libraries.

…ecution-providers/plugin-ep-packaging.md …oviders/plugin-ep-libraries/packaging.mddocs/execution-providers/plugin-ep-packaging.md renamed to docs/execution-providers/plugin-ep-libraries/packaging.md docs/execution-providers/plugin-ep-packaging.md renamed to docs/execution-providers/plugin-ep-libraries/packaging.md

@@ -1,38 +1,33 @@
 ---
-title: Plugin Execution Provider Packaging Guidance
-description: Packaging guidance for plugin EP packages
-parent: Execution Providers
-nav_order: 18
-redirect_from: /docs/reference/execution-providers/Plugin-EP-Packaging
+title: Packaging Guidance
+description: Packaging Guidance
+grand_parent: Execution Providers
+parent: Plugin Execution Provider Libraries
+nav_order: 3
 ---
 
-# ONNX Runtime Plugin Execution Provider Packaging Guidance
+# Plugin Execution Provider Library Packaging Guidance
 {: .no_toc }
 
+This page provides guidance for ONNX Runtime plugin EP implementers to consider with regards to packaging for a plugin EP.
+
 ## Contents
 {: .no_toc }
 
 * TOC placeholder
 {:toc}
 
-## Overview
-
-This document aims to provide guidance for ONNX Runtime (ORT) plugin Execution Provider (EP) implementers to consider with regards to packaging for a plugin EP.
-
 ## General Guidance
 
 ### Usage
-
 Note: Generally, when referring to the ORT API, we will refer to the C API functions. Equivalents should exist for other language bindings that support plugin EP usage.
 
 #### Manual EP Library Registration
-
 Users are expected to call [`OrtApi::RegisterExecutionProviderLibrary()`](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a7c8ea74a2ee54d03052f3d7cd1e1335d) to register the plugin EP library. Then, they may either choose to use the auto EP selection mechanism or manually call [`OrtApi::SessionOptionsAppendExecutionProvider_V2()`](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a285a5da8c9a63eff55dc48e4cf3b56f6) to explicitly use the plugin EP.
 
 ### Structure
 
 #### Contents
-
 A plugin EP package should contain the plugin EP shared library file and any other files that need to be distributed with it.
 
 A plugin EP package should NOT contain the ORT shared library or other core ORT libraries (e.g., onnxruntime.dll or libonnxruntime.so). Users should obtain the ORT library separately, most likely via installing the separate ONNX Runtime package.
@@ -42,18 +37,16 @@ A plugin EP package should have no need to depend on the separate ONNX Runtime p
 #### Additional Information to Provide
 
 ##### Library Path
-
 There should be a way to get the package's plugin EP library path. The user will need the plugin EP library path to call `OrtApi::RegisterExecutionProviderLibrary()`.
 
 For example, the package may provide a helper function that returns the path to the plugin EP library. The recommended name for this helper function is "get library path".
 
 ##### EP name(s)
 There should be a way to get the plugin EP name(s) provided by the package. The user may require the plugin EP name(s) to select the appropriate `OrtEpDevice` instances to provide to `OrtApi::SessionOptionsAppendExecutionProvider_V2()`.
 
-For example, the plugin EP name(s) may be well-documented or made available with a helper function provided by the package. The recommended name for this helper function is "get EP name", or "get EP names" if there are multiple names.
+For example, the plugin EP name(s) may be well-documented or made available with a helper function provided by the package. The recommended name for a helper function returning all EP names is "get EP names". Additionally, if there is only one EP name, a helper function returning the single value named "get EP name" may be provided for convenience.
 
 #### Package Naming
-
 The name of the package should indicate that the package contains a plugin EP and be distinguishable from other ORT packages.
 
 For example, this may be done by using a special prefix or suffix.
@@ -63,79 +56,38 @@ For example, this may be done by using a special prefix or suffix.
 ### PyPI
 
 #### Package Naming
-
 The prefix "onnxruntime-ep" can be used to identify a plugin EP.
 
 The suggested package naming convention is "onnxruntime-ep-\<EP identifier\>".
 
 For example, "onnxruntime-ep-contoso-ai".
 
 #### Helper Functions
+The package should provide helper function `get_library_path()` to get the EP library path.
 
-As mentioned in the general guidance section, the package should provide helper function `get_library_path()` to get the EP library path. The package may provide helper function `get_ep_name()` or `get_ep_names()` to get the EP name(s).
-
-#### Usage example
-
-```python
-import onnxruntime as ort
-import onnxruntime_ep_contoso_ai as contoso_ep
-
-# Path to the plugin EP library
-ep_lib_path = contoso_ep.get_library_path()
-# Registration name can be anything the application chooses
-ep_registration_name = "contoso_ep_registration"
-
-# Register plugin EP library with ONNX Runtime
-ort.register_execution_provider_library(ep_registration_name, ep_lib_path)
+The package should provide helper function `get_ep_names()` to get the EP name(s).
 
-# Create ORT session with explicit OrtEpDevice(s)
+The package may provide helper function `get_ep_name()` to get the single EP name if there is just one.
 
-# Get EP name(s) from the plugin EP library
-ep_names = contoso_ep.get_ep_names()
-# For this example we'll use the first one
-ep_name = ep_names[0]
+#### Example
+Refer to the [example Python package setup](https://github.com/microsoft/onnxruntime-inference-examples/tree/main/plugin_execution_providers/basic/python) and its [example usage](https://github.com/microsoft/onnxruntime-inference-examples/blob/main/plugin_execution_providers/basic/python/example_usage/example_usage.py).
 
-# Select an OrtEpDevice
-# For this example, we'll use any OrtEpDevices matching our EP name
-all_ep_devices = ort.get_ep_devices()
-selected_ep_devices = [ep_device for ep_device in all_ep_devices if ep_device.ep_name == ep_name]
-
-assert len(selected_ep_devices) > 0
-
-sess_options = ort.SessionOptions()
-
-# EP-specific options
-ep_options = {}
-
-# Equivalent to the C API's SessionOptionsAppendExecutionProvider_V2 that appends the plugin EP to the session options
-sess_options.add_provider_for_devices(selected_ep_devices, ep_options)
-
-assert sess_options.has_providers() == True
-
-# Create ORT session with the plugin EP
-model_path = "/path/to/model.onnx"
-sess = ort.InferenceSession(model_path, sess_options=sess_options)
-
-# Use `sess`
-# ...
-
-del sess
-
-# Unregister the library using the same registration name specified earlier
-# Must only unregister a library after all sessions that use the library have been released
-ort.unregister_execution_provider_library(ep_registration_name)
-```
 
 ### NuGet
 
 #### Package Naming
-
 NuGet packages may use a reserved ID prefix.
 
-The suggested package naming convention is "\<Vendor prefix\>.ML.OnnxRuntime.\<EP identifier\>.EP".
+The suggested package naming convention is "\<Vendor prefix\>.ML.OnnxRuntime.EP.\<EP identifier\>".
 
-For example, "Contoso.ML.OnnxRuntime.ContosoAI.EP".
+For example, "Contoso.ML.OnnxRuntime.EP.ContosoAI".
 
 #### Helper Functions
+The package should provide helper function `GetLibraryPath()` to get the EP library path.
+
+The package should provide helper function `GetEpNames()` to get the EP name(s).
+
+The package may provide helper function `GetEpName()` to get the single EP name if there is just one.
 
-As mentioned in the general guidance section, the package should provide helper function `GetLibraryPath()` to get the EP library path. The package may provide helper function `GetEpName()` or `GetEpNames()` to get the EP name(s).
+#### Example
+Refer to the [example NuGet package setup](https://github.com/microsoft/onnxruntime-inference-examples/tree/main/plugin_execution_providers/basic/csharp) and its [example usage](https://github.com/microsoft/onnxruntime-inference-examples/blob/main/plugin_execution_providers/basic/csharp/SampleApp/Program.cs).

docs/execution-providers/plugin-ep-libraries/testing.md

@@ -0,0 +1,68 @@
+---
+title: Testing Guidance
+description: Testing Guidance
+grand_parent: Execution Providers
+parent: Plugin Execution Provider Libraries
+nav_order: 2
+---
+
+# Plugin Execution Provider Library Testing Guidance
+{: .no_toc }
+
+A plugin EP is responsible for ensuring that its implementation behaves correctly. This includes interacting with ONNX Runtime in the expected way as documented by the plugin EP API. It also includes the operator-level behavior as specified by the operator specification, e.g., from the ONNX standard.
+
+## Contents
+{: .no_toc }
+
+* TOC placeholder
+{:toc}
+
+## EP unit testing
+Plugin EP implementations are expected to have their own unit tests.
+
+### Operator-level testing utility provided by ONNX Runtime
+ONNX Runtime has existing unit tests that validate an EP's op implementation. These tests are located in the unit test program `onnxruntime_provider_test`. This program supports usage with a dynamically specified plugin EP.
+
+In particular, unit tests utilizing the `onnxruntime::test::OpTester` or `onnxruntime::test::ModelTester` classes can also be run with a plugin EP.
+
+Plugin EP implementers may use this test program to help test their plugin EP if desired. The rest of this section explains how to do this.
+
+#### Building
+Build the onnxruntime shared library and the `onnxruntime_provider_test` target from source.
+```
+cd <onnxruntime repo>
+# Note: On Windows, use build.bat instead of build.sh
+./build.sh --build_shared_lib --update --build --parallel --target onnxruntime_provider_test
+```
+
+The onnxruntime shared library and `onnxruntime_provider_test` will be available in the binary output directory.
+
+#### Running
+`onnxruntime_provider_test` supports the standard GoogleTest arguments. E.g., `--gtest_filter` can be used to run particular tests of interest.
+
+Importantly, it supports configuration of a dynamically specified plugin EP through the environment variable `ORT_UNIT_TEST_MAIN_DYNAMIC_PLUGIN_EP_CONFIG_JSON`. The configuration value should be specified as a JSON string.
+
+Here is an example value for `ORT_UNIT_TEST_MAIN_DYNAMIC_PLUGIN_EP_CONFIG_JSON`:
+```json
+{
+  "ep_library_registration_name": "example_plugin_ep",
+  "ep_library_path": "/path/to/libexample_plugin_ep.so",
+  "selected_ep_name": "example_plugin_ep",
+  "default_ep_options": { "ep_option_key": "ep_option_value" }
+}
+```
+
+`ep_library_registration_name` and `ep_library_path` are the same as the `registration_name` and `path` parameters passed in to [`OrtApi::RegisterExecutionProviderLibrary()`](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a7c8ea74a2ee54d03052f3d7cd1e1335d), respectively.
+
+`selected_ep_name` should be set to the plugin EP's name. All available `OrtEpDevice`s (returned by [`OrtApi::GetEpDevices()`](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a52107386ff1be870f55a0140e6add8dd)) matching that EP name will be used.
+
+As an alternative to `selected_ep_name`, `selected_ep_device_indices` may be set to a list of integers representing the indices into the available `OrtEpDevice`s list. This requires knowing what `OrtEpDevice`s are available.
+The available `OrtEpDevices` can be obtained with [`OrtApi::GetEpDevices()`](https://onnxruntime.ai/docs/api/c/struct_ort_api.html#a52107386ff1be870f55a0140e6add8dd).
+The `onnxruntime_perf_test` tool also provides the [`--list_ep_devices`](https://github.com/microsoft/onnxruntime/blob/f83d4d06e4283d53a10c54ce84da3455cfb4e21d/onnxruntime/test/perftest/command_args_parser.cc#L195) option, which may be used in conjunction with the [`--plugin_ep_libs`](https://github.com/microsoft/onnxruntime/blob/f83d4d06e4283d53a10c54ce84da3455cfb4e21d/onnxruntime/test/perftest/command_args_parser.cc#L186-L188) option to display them.
+
+Optionally, `default_ep_options` may be set to specify EP-specific options as string key value pairs.
+
+## EP integration testing and model testing
+There are a number of APIs that a plugin EP will implement to interact with ONNX Runtime. Although conformance tests at the EP API level were considered, they were not deemed to be that useful yet. Currently, it is expected that the integration with ONNX Runtime can be meaningfully tested using high level tests that run an entire model.
+
+Plugin EPs may vary significantly from one to another in terms of capability, whether it is optional feature support or operator support. Therefore, it is expected that plugin EPs will have a set of models that are most relevant to them and that these models can be used for testing.