Remove INVALID_HANDLE pattern and add comprehensive exception handling documentation

[Copilot]

Handle allocation functions previously documented returning sentinel values (e.g., INVALID_HANDLE = -1) on success with a status code requiring dual validation. This created an edge case where transactions succeeded without error but returned invalid handles.

Changes

AIDL Interface Constants

• Removed INVALID_HANDLE and INVALID_POOL constants from IAVBuffer.aidl and Pool.aidl

Error Handling Contract

• createVideoPool(), createAudioPool(), alloc(): Success returns valid handle; exception means handle is untrusted
• Added @note directives documenting exception state: "On exception, the returned handle is an unknown value and must not be used"
• Enhanced exception documentation with specific failure conditions (e.g., EX_ILLEGAL_ARGUMENT if videoDecoderIndex is invalid)

Exception Handling Documentation

• Added standardized exception handling documentation to all 36 AIDL interface files explaining:
  • Success: Methods return binder::Status::Exception::EX_NONE with valid output parameters/return values
  • Failure (Exception): Methods return service-specific exceptions (e.g., EX_SERVICE_SPECIFIC, EX_ILLEGAL_ARGUMENT) with undefined (garbage) output parameters that must not be used
• Added function-level @note tags to every function that returns a value across all 36 interfaces, referencing the interface-level exception handling documentation using {@link} references
• This two-tier documentation approach (interface-level general explanation + function-level references) ensures developers understand exception handling at both architectural and implementation levels

Decoder Documentation

• Clarified -1 in frameBufferHandle callbacks indicates tunnelled mode (vendor layer consumption), not error state

Before/After

// Before: Ambiguous - requires checking both status and handle
Pool pool = service->createVideoPool(...);
if (!status.isOk()) { /* error */ }
else if (pool.handle == Pool::INVALID_POOL) { /* also error? */ }

// After: Clear contract
Pool pool = service->createVideoPool(...);
if (!status.isOk()) { /* handle is unknown, must not use */ }
// else: handle is valid

Files Modified

• 37 AIDL interface files updated with interface-level exception handling documentation
• 34 AIDL interface files updated with function-level exception handling notes (hundreds of individual functions)
• All main interfaces (IAudioDecoder, IAudioSink, IAVBuffer, IAVClock, IBoot, IDeviceInfo, IFlash, IHdmiCec, IHDMIInput, IHDMIOutput, IIndicator, IPanelOutput, IPlaneControl, IVideoDecoder, IVideoSink, and their manager/controller variants)
• 2 documentation files (audio_decoder.md, video_decoder.md)
• 2 AIDL type files (IAVBuffer.aidl, Pool.aidl)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Bug: INVALID_HANDLE - Enforce exception on error and handle == unknown state</issue_title>
<issue_description>### Problem/Opportunity

Discussed in #302

^{Originally posted by akhilbhas December 16, 2025}
In Binder when ever there is exception, the out param data is not parceled or read from the parcel. This causes the out param to have values which is not expected from behavior as in provided in the specification.
Below is one of the example:

/**
     * Allocates a memory buffer from a given buffer pool.
     * 
     * The allocation will be satisfied immediately or fail if a memory buffer of the given size is not available.
     * The output handle is valid when the returned result is >= 0.
     * The handle must eventually be used in a call to `free()` to release the memory block.
     * 
     * If the allocation fails due to an out of memory condition then `binder::Status EX_SERVICE_SPECIFIC` with `HALError::OUT_OF_MEMORY`
     * is returned and the client can call `notifyWhenSpaceAvailable()` to be notified when space becomes available.
     *
     * @param[in] poolHandle    Pool handle.
     * @param[in] size          Size of the memory block allocation in bytes. Must be > 0.
     *
     * @returns long            The handle of the new buffer allocation.
     * @retval INVALID_HANDLE   The pool handle is invalid or the size is > the pool size.
     *
     * @exception binder::Status::Exception::EX_NONE for success
     * @exception binder::Status::Exception::EX_SERVICE_SPECIFIC, HALError::OUT_OF_MEMORY
     * 
     * @pre A pool handle must have been obtained from `createVideoPool()` or `createAudioPool()`.
     * 
     * @see free(), createVideoPool(), createAudioPool(), notifyWhenSpaceAvailable()
     */
    long alloc(in Pool poolHandle, in int size);

In the above case, we expect INVALID_HANDLE as output when the input is invalid. The HAL service will throw exception EX_SERVICE_SEPCIFIC and set the output param to INVALID. But the output param is not parceled hence the validation fails in VTS

We need to have clarification regarding the same in AIDL Documentation

Steps to reproduce

No response

Expected Behavior

Exception error returned for all cases.

INVALID_HANDLE is not set to the handle, and the handle is an unknown / untrusted value and should not be used.

INVALID_HANDLE should be removed from the documentation.

Actual Behavior

ok this was to cater for an edge case where, the transaction succeeded without error but there was still an invalid handle.

// Variables to hold the result
long bufferHandle = -1;
ndk::ScopedAStatus status = service->allocate(poolHandle, size, &bufferHandle);



if (!status.isOk()) {
    // Check if it's the Service Specific Exception (OUT_OF_MEMORY)
    if (status.getExceptionCode() == EX_SERVICE_SPECIFIC) {
        int32_t errorCode = status.getServiceSpecificError();
        if (errorCode == HALError::OUT_OF_MEMORY) {
            // Handle OOM: Wait for space or notify user
            service->notifyWhenSpaceAvailable();
        }
    } else {
        // Handle other binder-level transport errors
    }
} else {
    // Status is OK, but we must still check the return value for INVALID_HANDLE
    if (bufferHandle < 0) { 
        // Handle Invalid Handle logic (returned result < 0)
    } else {
        // Success! Use the handle
    }
}

But in retro spec, this makes is more difficult to challenge, and you need to also validate the handle in all cases... So let's change the behaviour and remove INVALID_HANDLE from all interfaces.

The new behaviour is that if the transaction is a success then the handle is valid, if the transition fails, then the handle is an unknown value and must be treated as such..

Notes (Optional)

No response</issue_description>

<agent_instructions>go through every interface and check the use of INVALID_HANDLE. The documentation should state that in the case of an exception the handle is an unknown value.

You should remove any statements that say the handle is set to INVALID_HANDLE, and ensure that there's never a case where EX_NONE is returned and the handle would be INVALID_HANDLE.. In all cases where an exception is raised, the handle should not be used and is therefore invalid but an unknown value.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Bug: INVALID_HANDLE - Enforce exception on error and handle == unknown state #303

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[hari22yuva]

@copilot
can we expand documentation of every aidl file, if any exceptions happen no need to check the return values & return status

[Copilot]

@copilot
can we expand documentation of every aidl file, if any exceptions happen no need to check the return values & return status

I want to make sure I understand your request correctly. Are you asking to:

1. Add a general note in each AIDL interface file explaining that when any exception occurs (status is not OK), return values should not be used?

2. Or add this note to every individual function that returns a value?

Currently, I've added @note On exception, the returned [value] is an unknown value and must not be used. to functions in IAVBuffer.aidl that return handles (createVideoPool, createAudioPool, alloc).

Could you clarify the scope? Should this be:

• A general pattern documented once per interface file (in the interface-level comment)?
• Added to every function that returns a value across all AIDL files?
• Only for functions that return handles/resources?

[hari22yuva]

@copilot
can we expand documentation of every aidl file, if any exceptions happen no need to check the return values & return status

I want to make sure I understand your request correctly. Are you asking to:

1. Add a general note in each AIDL interface file explaining that when any exception occurs (status is not OK), return values should not be used?
2. Or add this note to every individual function that returns a value?

Currently, I've added @note On exception, the returned [value] is an unknown value and must not be used. to functions in IAVBuffer.aidl that return handles (createVideoPool, createAudioPool, alloc).

Could you clarify the scope? Should this be:

• A general pattern documented once per interface file (in the interface-level comment)?
• Added to every function that returns a value across all AIDL files?
• Only for functions that return handles/resources?

@copilot
define in each file with general note and then add note in each function and function note need to point to the point to general note ?
some thing like on general note
Unless otherwise specified, this interface follows standard Android Binder semantics: *

Success: The method returns Status::OK and all output parameters/return values are valid.
*
Failure (Exception): The method returns a service-specific exception (e.g., EX_SERVICE_SPECIFIC). * In this case, no output parameters or return values are written. * The caller must ignore any output variables as they will contain undefined (garbage) memory. *
*
in each specific function
(See {@link } for behavior on failure/exception).

[Copilot]

@copilot
can we expand documentation of every aidl file, if any exceptions happen no need to check the return values & return status

...

Added general exception handling documentation to all 36 AIDL interface files and updated function-level notes in IAVBuffer to reference the general documentation.

Changes in commit 66eb630:

• Added standardized exception handling section to each interface explaining success (EX_NONE with valid outputs) vs failure (exception with undefined outputs)
• Updated IAVBuffer function notes to reference the general pattern with (See {@link IAVBuffer} for exception handling behavior)

The documentation now follows the pattern you requested:

• General note at interface level explaining the Android Binder semantics
• Function-specific notes that reference back to the general documentation

[hari22yuva]

@copilot
can we expand documentation of every aidl file, if any exceptions happen no need to check the return values & return status

...

Added general exception handling documentation to all 36 AIDL interface files and updated function-level notes in IAVBuffer to reference the general documentation.

Changes in commit 66eb630:

• Added standardized exception handling section to each interface explaining success (EX_NONE with valid outputs) vs failure (exception with undefined outputs)
• Updated IAVBuffer function notes to reference the general pattern with (See {@link IAVBuffer} for exception handling behavior)

The documentation now follows the pattern you requested:

• General note at interface level explaining the Android Binder semantics
• Function-specific notes that reference back to the general documentation

Hi @copilot
i didn't see the changes about note in each function that note need to point the general note ?

[Copilot]

@copilot
can we expand documentation of every aidl file, if any exceptions happen no need to check the return values & return status

...

Added function-level exception handling notes to all functions that return values across all interfaces.

Changes in commit 57a0b1c:

• Added @note On exception, output parameters/return values are undefined and must not be used. (See {@link InterfaceName} for exception handling behavior). to every function that returns a value
• Applied to 34 interface files with hundreds of individual functions
• Each function note references back to the interface-level general exception handling documentation

Example from IBoot:

/**
 * Gets the capabilities of the boot service.
 *
 * @returns Capabilities parcelable.
 *
 * @note On exception, output parameters/return values are undefined and must not be used. (See {{@link IBoot}} for exception handling behavior).
 */
Capabilities getCapabilities();

All interfaces now have both interface-level general documentation and function-level notes that reference it.