|WARNING| [6/6] eventdev/dma: promote adapter API to stable

[dpdklab at iol.unh.edu]

Test-Label: ai-code-review
Test-Status: WARNING
https://dpdk.org/patch/168941

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-09-02

# DPDK Patch Review

## Overall Assessment

This is a patch series promoting several eventdev adapter APIs from experimental to stable status. The patches are well-structured, and the core changes are appropriate. However, there are documentation issues and one correctness concern that need to be addressed.

---

## Patch 1: eventdev/eth_rx: promote adapter API to stable

### Errors

None.

### Warnings

**1. Incomplete release notes structure**

The release notes entry lacks proper formatting. DPDK release notes should use bullet points with consistent indentation, not a bare colon-list format.

Current:
```
* eventdev: Promoted the following API from experimental to stable:

  * Rx adapter: ``rte_event_eth_rx_adapter_create_ext_with_params``,
```

Suggested:
```
* eventdev: Promoted the following APIs from experimental to stable:

  * Rx adapter:

    * ``rte_event_eth_rx_adapter_create_ext_with_params``
    * ``rte_event_eth_rx_adapter_runtime_params_init``
    * ``rte_event_eth_rx_adapter_runtime_params_set``
    * ``rte_event_eth_rx_adapter_runtime_params_get``
```

**2. Export macro version parameter removed**

The export macro change from `RTE_EXPORT_EXPERIMENTAL_SYMBOL(name, version)` to `RTE_EXPORT_SYMBOL(name)` is correct for promotion to stable, but the original version numbers (23.11, 23.03) document when these APIs were introduced. While the version parameter is not required for stable symbols, it may have been useful historical information. This is acceptable as the git history preserves this information, but worth noting.

---

## Patch 2: eventdev/eth_tx: promote adapter runtime params to stable

### Errors

None.

### Warnings

Same release notes formatting concern as Patch 1. The nested list should be properly indented and use bullet points consistently.

---

## Patch 3: eventdev/crypto: promote adapter runtime params to stable

### Errors

None.

### Warnings

Same release notes formatting concern.

---

## Patch 4: eventdev/timer: promote remaining ticks get to stable

### Errors

None.

### Warnings

Same release notes formatting concern - should be a bulleted sub-list, not a bare item.

---

## Patch 5: eventdev: promote link profile API to stable

### Errors

None.

### Warnings

Same release notes formatting concern.

---

## Patch 6: eventdev/dma: promote adapter API to stable

### Errors

**1. Overly broad release notes entry**

The release notes entry "DMA adapter: ``rte_event_dma_adapter_*`` and ``rte_event_dma_adapter_caps_get``" uses a wildcard pattern that is not sufficiently specific. Release notes should list individual function names to clearly document what changed.

The patch promotes 15 specific functions (all in `rte_event_dma_adapter.c`):
- `rte_event_dma_adapter_create_ext`
- `rte_event_dma_adapter_create`
- `rte_event_dma_adapter_free`
- `rte_event_dma_adapter_event_port_get`
- `rte_event_dma_adapter_vchan_add`
- `rte_event_dma_adapter_vchan_del`
- `rte_event_dma_adapter_service_id_get`
- `rte_event_dma_adapter_start`
- `rte_event_dma_adapter_stop`
- `rte_event_dma_adapter_runtime_params_init`
- `rte_event_dma_adapter_runtime_params_set`
- `rte_event_dma_adapter_runtime_params_get`
- `rte_event_dma_adapter_stats_get`
- `rte_event_dma_adapter_stats_reset`
- `rte_event_dma_adapter_enqueue`

Plus one function from `rte_eventdev.c`:
- `rte_event_dma_adapter_caps_get`

All 16 functions should be explicitly listed, or the note should state "entire rte_event_dma_adapter API" if that's the intent.

Suggested replacement:
```
  * DMA adapter: promoted entire ``rte_event_dma_adapter_*`` API to stable
    (``rte_event_dma_adapter_create_ext``, ``rte_event_dma_adapter_create``,
    ``rte_event_dma_adapter_free``, ``rte_event_dma_adapter_event_port_get``,
    ``rte_event_dma_adapter_vchan_add``, ``rte_event_dma_adapter_vchan_del``,
    ``rte_event_dma_adapter_service_id_get``, ``rte_event_dma_adapter_start``,
    ``rte_event_dma_adapter_stop``, ``rte_event_dma_adapter_runtime_params_init``,
    ``rte_event_dma_adapter_runtime_params_set``,
    ``rte_event_dma_adapter_runtime_params_get``, ``rte_event_dma_adapter_stats_get``,
    ``rte_event_dma_adapter_stats_reset``, ``rte_event_dma_adapter_enqueue``, and
    ``rte_event_dma_adapter_caps_get``)
```

### Warnings

**1. Documentation block removal loses context**

The patch removes the file-level experimental warning block from `rte_event_dma_adapter.h`:
```c
- * @warning
- * @b EXPERIMENTAL:
- * All functions in this file may be changed or removed without prior notice.
```

While correct (the functions are now stable), this removal could be accompanied by a note that the entire adapter API is now considered stable. Consider replacing the warning with a brief introductory sentence confirming the API status.

**2. Missing context about adapter stability milestone**

The DMA adapter is the newest of the adapters being promoted (introduced in v23.11). The commit message could mention that this makes it the first adapter to go from introduction to stable promotion in under 3 years, demonstrating the maturity of the adapter framework. This is not required but would provide useful context.

---

## Cross-Patch Observations

### Warnings

**1. Release notes consolidation**

The series makes 6 separate release notes additions, one per patch. These could be consolidated into a single "eventdev" section with subsections for each adapter type. This would improve readability of the final release notes.

Suggested consolidated format:
```rst
* eventdev: Promoted the following APIs from experimental to stable:

  * Rx adapter:

    * ``rte_event_eth_rx_adapter_create_ext_with_params``
    * ``rte_event_eth_rx_adapter_runtime_params_init``
    * ``rte_event_eth_rx_adapter_runtime_params_set``
    * ``rte_event_eth_rx_adapter_runtime_params_get``

  * Tx adapter:

    * ``rte_event_eth_tx_adapter_runtime_params_init``
    * ``rte_event_eth_tx_adapter_runtime_params_set``
    * ``rte_event_eth_tx_adapter_runtime_params_get``

  * Crypto adapter:

    * ``rte_event_crypto_adapter_runtime_params_init``
    * ``rte_event_crypto_adapter_runtime_params_set``
    * ``rte_event_crypto_adapter_runtime_params_get``

  * Timer adapter:

    * ``rte_event_timer_remaining_ticks_get``

  * Link profiles:

    * ``rte_event_port_profile_links_set``
    * ``rte_event_port_profile_unlink``
    * ``rte_event_port_profile_links_get``

  * DMA adapter: promoted entire API to stable (16 functions)
```

**2. Consistency in removal of experimental markers**

All patches correctly remove `__rte_experimental` from headers and change `RTE_EXPORT_EXPERIMENTAL_SYMBOL` to `RTE_EXPORT_SYMBOL` in source files. This is the correct approach and is consistently applied throughout the series.

---

## Summary

**Must Fix (Errors):**
- Patch 6: Release notes entry for DMA adapter is too vague - list all functions explicitly or clearly state "entire API"

**Should Fix (Warnings):**
- All patches: Improve release notes formatting with proper bullet structure and indentation
- Patch 6: Consider replacing the removed experimental warning with a brief stability confirmation statement

**Correctness:** The code changes themselves are correct. All symbol exports are properly updated, header annotations removed appropriately, and the changes match the stated intent. No correctness bugs, resource leaks, or race conditions identified.

**Process Compliance:** Patches compile independently, are focused on single logical changes, and include appropriate maintainer Cc's. The series follows DPDK conventions for API promotion.