// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.media;

using zx;

@discoverable
closed protocol ProfileProvider {
    /// Register a thread as a media thread. This notifies the media subsystem that this thread
    /// should have an elevated scheduling profile applied to it in order to meet audio or video
    /// deadlines.
    ///
    /// `name` is the name of a system scheduling role to apply to the thread given by
    /// `thread_handle` -- different products may customize the underlying scheduling strategy based
    /// on the requested role. `period` is the suggested interval to be scheduled at. `period` may
    /// be zero if the thread has no preferred scheduling interval. `capacity` is the proportion of
    /// the scheduling interval the thread needs to be running to achieve good performance or to
    /// meet the scheduling deadline defined by `period`. `capacity` may be zero if the workload has
    /// no firm runtime requirements. Note that `capacity` should be a good faith estimate based on
    /// the worst case runtime the thread requires each period.  Excessive capacity requests may
    /// be rejected or result in scaling back the performance of other threads to fit resource
    /// limits.
    ///
    /// Capacity, max runtime, and period have the following relationship:
    ///
    ///   capacity = max runtime / period
    ///
    /// Where:
    ///
    ///   0 <= max runtime <= period    and    0 <= capacity <= 1
    ///
    /// For heterogeneous systems, the capacity should be planned / measured against the highest
    /// performance processor(s) in the system. The system will automatically adjust the effective
    /// capacity to account for slower processors and operating points and will avoid processors and
    /// operating points that are too slow to meet the requested scheduling parameters (provided
    /// they are reasonable).
    ///
    /// Returns the period and capacity (actually maximum runtime) that was applied, either of which
    /// may be zero to indicate not applicable.
    strict RegisterHandlerWithCapacity(resource struct {
        thread_handle zx.Handle:THREAD;
        name string:64;
        period zx.Duration;
        capacity float32;
    }) -> (struct {
        period zx.Duration;
        capacity zx.Duration;
    });

    /// Reset a thread's scheduling profile to the default.
    strict UnregisterHandler(resource struct {
        thread_handle zx.Handle:THREAD;
        name string:64;
    }) -> ();

    /// Register a memory range as being used for media processing. This notifies the media
    /// subsystem that this memory should have an elevated memory profile applied to it in order to
    /// meet audio or video deadlines.
    ///
    /// `name` is the name of a system memory role to apply to the memory given by
    /// `vmar_handle` -- different products may customize the underlying memory strategy based
    /// on the requested role.
    @available(added=15)
    strict RegisterMemoryRange(resource struct {
        vmar_handle zx.Handle:VMAR;
        name string:64;
    }) -> ();

    /// Reset a memory range's memory profile.
    @available(added=15)
    strict UnregisterMemoryRange(resource struct {
        vmar_handle zx.Handle:VMAR;
    }) -> ();
};