After some discussion with @mpg (but written in my own words here and with a bit of further analysis), it appears that a useful milestone is to unify the error code space, so this is what I am defining as the goal of this issue. Fully unifying the error codes is out of scope and can be discussed further in #8501.

By unifying the error code space, I mean that any code that expects a PSA error code can now receive and propagate an mbedtls error code, and vice versa. Already, in Mbed TLS 3.x, this was partly the case, in that:

• Both APIs define error codes as negative values between -32767 and -1, with 0 meaning success.
• No PSA error code has the same numerical value as an mbedtls error code.

What was missing from the unification is that some code specifically expects a low-level error code, which must be a specific kind of mbedtls error code, not an arbitrary error code. This affects two places in the code:

• Places where we add a high-level MBEDTLS_ERR_xxx to a low-level MBEDTLS_ERR_xxx (since Error codes: enforce add macro #9566, always using MBEDTLS_ERROR_ADD).
• The error.h interface, which caters for added error codes.

So the goal here is to get rid of error code additions, and remove the now-obsolete bits of mbedtls/error.h. (Also any other place where we document added error codes, but I can't find any!)

The following are out of scope:

• Unifying the status types. Legacy functions use int, whereas PSA functions use psa_status_t which is a synonym for int32_t. Even on platforms where these types have the same representation and range, they might be different formal types which can trigger compiler warnings when directly using a value of one type in a context that expects the other type. This can be resolved by adding a cast when needed.
• Unifying error codes, for example changing all MBEDTLS_ERR_xxx_OUT_OF_MEMORY to PSA_ERROR_OUT_OF_MEMORY. This can happen gradually over time.
• Actually having psa_xxx functions return MBEDTLS_ERR_xxx values and mbedtls_xxx functions return PSA_ERROR_xxx values, and getting rid of error space conversion functions. With this issue, we're making it possible, but not actually doing it.
• A unified strerror. Filed as technical debt: Handle PSA error codes in mbedtls_strerror #9925
• Simplifying error.c. Filed as technical debt: Simplify error.c without error addition #9927
• Large documentation updates to stop making the distinction between PSA and mbedtls errors. I'm not sure any are needed: we don't use MBEDTLS_ERR_xxx or tls error code or legacy error code in any public documentation except for the 3.0 and PSA transition guides.