// Copyright 2018 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.device.mock;

using zx;

/// A record of the invocation of a hook
type HookInvocation = struct {
    /// Process that the hook was invoked in
    process_koid zx.Koid;
    /// Thread that the hook was invoked on
    thread_koid zx.Koid;
    /// An opaque identifier identifying a specific device
    device_id uint64;
};

/// Marker struct for unbind reply action
type UnbindReplyAction = struct {
    /// Value that will be echoed back in the completion message
    action_id uint64;
};

/// Marker struct for suspend reply action
type SuspendReplyAction = struct {
    /// Value that will be echoed back in the completion message
    action_id uint64;
};

/// Marker struct for resume reply action
type ResumeReplyAction = struct {
    /// Value that will be echoed back in the completion message
    action_id uint64;
};

const MAX_PROPERTIES_LEN uint32 = 32;
const MAX_NAME_LEN uint32 = 32;

/// Request to add a new child device
type AddDeviceAction = resource struct {
    /// Value that will be echoed back in the completion message
    action_id uint64;

    /// If true, will let the device go through the bind protocol.
    /// Otherwise, will just create another mock device and skip binding.
    do_bind bool;

    /// If creating a mock device, the service the new device will listen to.
    controller client_end:<MockDevice, optional>;

    /// The name that should be given to the new device.  Used by devfs and
    /// debug messages.
    name string:MAX_NAME_LEN;

    /// The properties to attach the newly created device
    properties vector<uint64>:MAX_PROPERTIES_LEN;

    /// The expected return status from device_add()
    expect_status zx.Status;
};

/// What a hook should do.
type Action = strict resource union {
    /// Return this status.
    1: return_status zx.Status;

    /// Create a new thread with a processing loop.
    2: create_thread server_end:MockDeviceThread;

    /// Invoke device_async_remove() on our device.
    3: async_remove_device bool;

    /// Signal that the unbind has completed.
    4: unbind_reply UnbindReplyAction;

    /// Create a new child device
    5: add_device AddDeviceAction;

    /// Signal that the suspend has completed.
    6: suspend_reply SuspendReplyAction;

    // Signal that the suspend has completed.
    7: resume_reply ResumeReplyAction;
};

const MAX_ACTIONS uint32 = 10;

/// Interface for controlling a mock device.  The test suite will implement this interface.
/// Any method that returns a list of actions is interpreted as requesting the corresponding hook
/// to perform that list of actions in order.
closed protocol MockDevice {
    /// `record.device_id` corresponds to the parent here.
    strict Bind(struct {
        record HookInvocation;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });

    strict Release(struct {
        record HookInvocation;
    });
    strict GetProtocol(struct {
        record HookInvocation;
        protocol_id uint32;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });
    strict Unbind(struct {
        record HookInvocation;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });
    strict Suspend(struct {
        record HookInvocation;
        requested_state uint8;
        enable_wake bool;
        suspend_reason uint8;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });
    strict Resume(struct {
        record HookInvocation;
        requested_state uint32;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });

    strict Message(struct {
        record HookInvocation;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });
    strict Rxrpc(struct {
        record HookInvocation;
    }) -> (resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });

    /// Notification that the requested action was done
    strict AddDeviceDone(struct {
        action_id uint64;
    });
    strict UnbindReplyDone(struct {
        action_id uint64;
    });
    strict SuspendReplyDone(struct {
        action_id uint64;
    });
    strict ResumeReplyDone(struct {
        action_id uint64;
    });
};

/// Interface for requesting a mock device thread do something.  The mock device implements
/// this interface.  Closing the interface causes the thread to exit.
closed protocol MockDeviceThread {
    /// Perform the actions in the given list.  Threads may not create other threads.
    strict PerformActions(resource struct {
        actions vector<Action>:MAX_ACTIONS;
    });

    /// Notification that the requested action was done
    strict -> AddDeviceDone(struct {
        action_id uint64;
    });
    strict -> UnbindReplyDone(struct {
        action_id uint64;
    });
    strict -> SuspendReplyDone(struct {
        action_id uint64;
    });
    strict -> ResumeReplyDone(struct {
        action_id uint64;
    });
};