drm_gem_objects_lookup() allocates the output array and may acquire references on GEM objects before returning an error. In such cases the array can be partially populated and relies on zero-initialization to indicate which entries are valid.
This behavior is relied upon by existing callers, but is not documented and can be easily misunderstood as automatic cleanup on failure. Clarify the lifetime and error-handling semantics in the kerneldoc: callers must drop any non-NULL object references and free the array even when the function returns an error. This is a documentation-only change and does not alter existing behavior. Cc: Alex Deucher <[email protected]> Suggested-by: Christian König <[email protected]> Suggested-by: Tvrtko Ursulin <[email protected]> Signed-off-by: Srinivasan Shanmugam <[email protected]> Change-Id: I2d1bdf3f319d841cb548cedc7b699bab9efeeed9 --- drivers/gpu/drm/drm_gem.c | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/drivers/gpu/drm/drm_gem.c b/drivers/gpu/drm/drm_gem.c index a1a9c828938b..0f8013b9377e 100644 --- a/drivers/gpu/drm/drm_gem.c +++ b/drivers/gpu/drm/drm_gem.c @@ -775,10 +775,22 @@ static int objects_lookup(struct drm_file *filp, u32 *handle, int count, * For a single handle lookup, use drm_gem_object_lookup(). * * Returns: - * @objs filled in with GEM object pointers. Returned GEM objects need to be - * released with drm_gem_object_put(). -ENOENT is returned on a lookup - * failure. 0 is returned on success. - * + * On success, *@objs_out is set to an allocated array of @count pointers + * containing GEM objects. The caller must drop the references with + * drm_gem_object_put() and free the array with kvfree(). + * + * Error handling and lifetime: + * drm_gem_objects_lookup() may allocate *@objs_out and acquire references on + * some objects before returning an error (e.g. copy_from_user() failure or + * a missing handle part-way through the lookup). + * + * In that case *@objs_out may be non-NULL and partially populated. The array + * is allocated zeroed, so unfilled entries are NULL. The caller must: + * - drm_gem_object_put() any non-NULL entries in *@objs_out, and + * - kvfree() the array itself. + * + * Callers that want automatic cleanup on failure should use + * drm_gem_objects_lookup_safe(). */ int drm_gem_objects_lookup(struct drm_file *filp, void __user *bo_handles, int count, struct drm_gem_object ***objs_out) -- 2.34.1
