sdk/fidl/fuchsia.hardware.clock/clock.fidl

// Copyright 2019 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.
@available(added=22)
library fuchsia.hardware.clock;

using zx;

/// Maximum length of the clock name.
@available(added=NEXT)
const MAX_CLOCK_NAME_LEN uint32 = 256;

/// Used for driver-to-driver communication.
@discoverable
open protocol Clock {

    /// Enables (ungates) this clock.
    /// Drivers *must* call enable on all clocks they depend upon.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `Enable`.
    /// Returns `ZX_ERR_TIMED_OUT` if an operation timed out (for instance, a PLL was unable to lock).
    /// Returns `ZX_ERR_INTERNAL` if the operation failed for any other reason.
    flexible Enable() -> () error zx.Status;

    /// Disables (gates) this clock.
    /// Drivers should call this method to indicate to the clock subsystem that
    /// a particular clock signal is no longer necessary.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `Disable`
    /// Returns `ZX_ERR_INTERNAL` if the operation failed for any other reason.
    flexible Disable() -> () error zx.Status;

    /// Returns `true` if a given clock is running.
    /// May query the hardware or return a cached value.
    /// IsEnabled shall not alter the state of the clock tree in any way.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `IsEnabled`.
    flexible IsEnabled() -> (struct {
        enabled bool;
    }) error zx.Status;

    /// Attempt to set the rate of the clock provider.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `SetRate`
    /// Returns `ZX_ERR_INVALID_ARGS` if the requested rate is not one that is reported as supported by `QuerySupportedRate`.
    /// Returns `ZX_ERR_TIMED_OUT` if an operation timed out (for instance, a PLL was unable to lock).
    /// Returns `ZX_ERR_INTERNAL` if the operation failed for any other reason.
    flexible SetRate(struct {
        hz uint64;
    }) -> () error zx.Status;

    /// Query the hardware for the highest supported rate that does not
    /// exceed hz_in.
    /// `QuerySupportedRate` shall not alter the state of the clock tree in any way.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `QuerySupportedRate`.
    /// Returns `ZX_ERR_OUT_OF_RANGE` if a suitable rate could not be found.
    flexible QuerySupportedRate(struct {
        hz_in uint64;
    }) -> (struct {
        hz_out uint64;
    }) error zx.Status;

    /// Returns the current rate that a given clock is running at.
    /// GetRate shall not alter the state of the clock tree in any way.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `GetRate `.
    flexible GetRate() -> (struct {
        hz uint64;
    }) error zx.Status;

    /// Sets the input of this clock by index. I.e. by selecting a mux.
    /// This clock has N inputs defined 0 through N-1, which are valid arguemts
    /// as the index to SetInput.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `SetInput`
    /// Returns `ZX_ERR_OUT_OF_RANGE` if `idx` is outside of the range supplied by `GetNumInputs`.
    /// Returns `ZX_ERR_INTERNAL` if the operation failed for any other reason.
    flexible SetInput(struct {
        idx uint32;
    }) -> () error zx.Status;

    /// Returns the number of inputs this clock has.
    /// Any value between 0 and UINT32_MAX is a valid return for this method.
    /// A Root Oscillator may return 0 for instance, if it has no inputs.
    /// GetNumInputs shall not alter the state of the clock tree in any way.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `GetNumInputs`.
    flexible GetNumInputs() -> (struct {
        n uint32;
    }) error zx.Status;

    /// Returns the index of the current input of this clock.
    /// GetInput shall not alter the state of the clock tree in any way.
    /// Returns `ZX_ERR_NOT_SUPPORTED` if this clock type does not support `GetInput`.
    flexible GetInput() -> (struct {
        index uint32;
    }) error zx.Status;

    /// Returns the static properties of a clock.
    @available(added=NEXT)
    flexible GetProperties() -> (struct {
        /// The platform-specific number of this clock, set as a bind property on the driver node.
        id uint32;
        /// The human-readable name of this clock. Either provided by the implementation, or the
        /// device tree.
        name string:MAX_CLOCK_NAME_LEN;
    });
};

service Service {
    clock client_end:Clock;
};
@available(added=NEXT)
service DebugService {
    device client_end:Clock;
};