|WARNING| [RFC] crypto: add RSA-specific capability parameters

[dpdklab at iol.unh.edu]

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

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-07-31

# DPDK Patch Review

## Patch Summary
This patch adds RSA-specific capability parameters to the cryptodev API to report padding schemes and MGF1 hash algorithms separately from primary hash support.

---

## ERRORS

None found.

---

## WARNINGS

### 1. Missing experimental API tag and release notes

**Issue:** This patch adds a new public API field (`rsa_capa`) to an existing capability structure without marking it as experimental or updating release notes.

**Why it matters:** New API additions require `__rte_experimental` annotation and must be documented in the release notes per DPDK contribution guidelines.

**Suggested fix:**
- Since this adds a field to an existing union in a public structure, it technically extends the ABI
- Add a release notes entry in `doc/guides/rel_notes/release_26_07.rst` (or current release) under "New Features" section:
```rst
* **Added RSA-specific capability reporting.**

  Added ``rte_crypto_rsa_capa`` structure to report RSA modulus length,
  padding schemes, and MGF1 hash algorithms separately from primary digest
  support in asymmetric crypto capabilities.
```

### 2. Documentation should clarify backward compatibility

**Issue:** The new `rsa_capa` field is added to the union, but there's no documentation explaining how applications should handle PMDs that don't populate this field (older PMDs or PMDs that haven't been updated).

**Why it matters:** Applications need to know whether they can safely read this field or need to fall back to the generic `modlen` field for RSA.

**Suggested fix:** Add a note in the struct comment:
```c
/**
 * RSA transform capability parameters.
 *
 * Used when rte_cryptodev_asymmetric_xform_capability::xform_type is
 * RTE_CRYPTO_ASYM_XFORM_RSA. Advertises supported modulus lengths,
 * MGF1 hash algorithms, and padding schemes.
 *
 * Primary hash algorithms for RSA operations (e.g. OAEP, PSS) are
 * reported separately via hash_algos in
 * rte_cryptodev_asymmetric_xform_capability.
 *
 * Applications should check if rsa_capa.modlen min/max are non-zero
 * to determine if the PMD reports RSA-specific capabilities.
 * If zero, fall back to the generic modlen field.
 */
```

### 3. Inconsistent zero-value semantics

**Issue:** The comments use inconsistent language for zero values:
- `modlen`: "0 means no limit is imposed" / "PMD default applies"
- `pad_types`: "0 means padding capability is not reported"
- `mgf1_hash_algos`: "0 means MGF1 capability is not reported"

**Why it matters:** The modlen comment could be interpreted as "PMD supports any size" rather than "field not populated". This creates ambiguity for applications.

**Suggested fix:** Align the semantics - zero should consistently mean "not reported/not populated":
```c
struct rte_crypto_param_range modlen;
/**< Supported RSA modulus length range, in bits.
 * If min and max are both 0, RSA-specific modulus range is not
 * reported by this PMD and applications should use the generic
 * modlen field instead.
 */
```

---

## INFO

### 1. Consider adding usage example

The new structure would benefit from a brief usage example in the comment showing how applications should query these capabilities. This would clarify the relationship between the generic fields and the new RSA-specific fields.

Example addition to the struct comment:
```c
 * Example usage:
 *   if (cap->xform_type == RTE_CRYPTO_ASYM_XFORM_RSA) {
 *       if (cap->rsa_capa.modlen.min != 0) {
 *           // Use RSA-specific capabilities
 *           modlen_range = cap->rsa_capa.modlen;
 *           padding_support = cap->rsa_capa.pad_types;
 *       } else {
 *           // Fall back to generic modlen
 *           modlen_range = cap->modlen;
 *       }
 *   }
```

### 2. Double blank line

There are two consecutive blank lines after the `rte_crypto_rsa_capa` structure definition (lines 191-192 in the patch context). DPDK style typically uses single blank lines between definitions.

---

## SUMMARY

The patch is functionally sound with no correctness bugs identified. The main concerns are process-related:
- Missing release notes for the new API addition
- Documentation could be clearer about backward compatibility and zero-value semantics

The code style and structure are appropriate. The union approach allows ABI compatibility since the new field coexists with existing fields that apply to other transform types.