// 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.

library ddk.protocol.pwm;

using zx;

struct PwmConfig {
   bool polarity;
   uint32 period_ns;
   /// duty_cycle range: [0.0, 100.0]
   float32 duty_cycle;
   /// TODO(fxbug.dev/41256): Vendor extensions
   /// mode_config should be mode specific parameters. The first parameter should always be mode.
   /// For example, a PWM supporting regular mode and 2 timer mode should have:
   ///   struct mode_config_regular {};
   ///
   ///   struct mode_config_two_timer {
   ///     uint32_t period_ns2;
   ///     float duty_cycle2;
   ///     uint8_t timer1;
   ///     uint8_t timer2;
   ///   };
   ///
   ///   struct mode_config {
   ///     uint32_t mode;
   ///     union {
   ///       struct mode_config_regular regular;
   ///       struct mode_config_two_timer two_timer;
   ///     };
   ///   };
   vector<voidptr>? mode_config;
};

[Layout = "ddk-protocol"]
protocol Pwm {
    /// Gets the current config of the PWM.
    /// @Returns : |s| : ZX_OK if success.
    /// @Returns : |config| : current config of PWM.
    GetConfig() -> (zx.status s, PwmConfig config);

    /// Sets the configurations of the PWM
    /// |config| : Configurations.
    /// @Returns : |s| : ZX_OK if success.
    SetConfig(PwmConfig config) -> (zx.status s);

    /// Enables the PWM.
    /// @Returns : |s| : ZX_OK if success.
    Enable() -> (zx.status s);

    /// Disables the PWM.
    /// @Returns : |s| : ZX_OK  if success.
    Disable() -> (zx.status s);
};

[Layout = "ddk-protocol"]
protocol PwmImpl {
    /// Gets the current config of the PWM.
    /// |idx| : Index of requested PWM.
    /// @Returns: |s| : ZX_OK if success.
    /// @Returns : |config| : current config of PWM.
    GetConfig(uint32 idx) -> (zx.status s, PwmConfig config);

    /// Sets the configurations of the PWM.
    /// |idx| : Index of requested PWM.
    /// |config| : Configurations.
    /// @Returns : |s| : ZX_OK if success.
    SetConfig(uint32 idx, PwmConfig config) -> (zx.status s);

    /// Enables the PWM.
    /// |idx| : Index of requested PWM.
    /// @Returns : |s| : ZX_OK if success.
    Enable(uint32 idx) -> (zx.status s);

    /// Disables the PWM.
    /// |idx| : Index of requested PWM.
    /// @Returns : |s| : ZX_OK  if success.
    Disable(uint32 idx) -> (zx.status s);
};