// Copyright 2022 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.starnix.binder;

using zx;
using fuchsia.posix;

const MAX_PATH_LENGTH uint64 = 4095;
const MAX_REQUEST_COUNT uint64 = 16;

alias Fd = int32;

/// The flags associated with an opened file.
type FileFlags = flexible bits : uint64 {
    // Permissions
    /// The owner can read the file.
    RIGHT_READABLE = 0b1;
    /// The owner can write to fhe file.
    RIGHT_WRITABLE = 0b10;
    // Skipping bits for exec and suid bits and for group and other mode if
    // they are needed in the future.

    // File type
    /// The file is a directory.
    DIRECTORY = 0b1000000000000;
};

/// The representation of an open file that can be transferred between the
/// binder device driver and the client.
type FileHandle = resource struct {
    /// The handle connecting to the file protocol. If not present, the file
    /// should behave as it is was a null file: all read must succeed with empty
    /// content and all write must succeed. See `fdio_fd_create_null()`.
    file zx.Handle:<optional>;

    /// The flags associated with the opened file.
    flags FileFlags;
};

/// Protocol that gives the binder driver access to the client process'
/// resources.
open protocol ProcessAccessor {
    /// Writes the contents of `content` to `address` in the process memory,
    /// using the vmo content size to determine the number of bytes to write.
    flexible WriteMemory(resource struct {
        address uint64;
        content zx.Handle:VMO;
    }) -> () error fuchsia.posix.Errno;

    /// Execute the given `request` and returns the associated `response`. Any
    /// failure will interrupt further processing and fail this operation and
    /// the associated errno will be then returned.
    /// The implementator of this protocol should handle these requests as best
    /// it can so that a failure doesn't have visible side-effects.
    flexible FileRequest(@generated_name("FileRequest") resource table {
        /// The list of file descriptor the client must close.
        1: close_requests vector<Fd>:MAX_REQUEST_COUNT;
        /// The list of file descriptor the client must duplicate and transfer to
        /// the binder driver.
        2: get_requests vector<Fd>:MAX_REQUEST_COUNT;
        /// The list of open file the client must add to its fd table, returning
        /// the new minted file descriptors.
        3: add_requests vector<FileHandle>:MAX_REQUEST_COUNT;
    }) -> (@generated_name("FileResponse") resource table {
        // (No ordinal 1 since there is no response for the close operation.)
        /// The list of open file retriever for the `get_requests`.
        2: get_responses vector<FileHandle>:MAX_REQUEST_COUNT;
        /// The list of file descriptors minted for the `add_requests`.
        3: add_responses vector<Fd>:MAX_REQUEST_COUNT;
    }) error fuchsia.posix.Errno;
};

/// Give access to the binder nodes.
@discoverable
open protocol DevBinder {
    /// Open the binder device node.
    flexible Open(resource table {
        /// The path to the binder device in the starnix process.
        /// Mandatory
        1: path vector<uint8>:MAX_PATH_LENGTH;

        /// The service giving the binder driver access to the resources of the client process.
        2: process_accessor client_end:ProcessAccessor;

        /// The handle to the process that will use the binder driver. It is
        /// used by the driver to read the data sent to the driver.
        /// Mandatory
        3: process zx.Handle:PROCESS;

        /// The request to the Binder protocol implementation.
        /// Mandatory
        4: binder server_end:Binder;
    });

    /// Close the binder device node, previously opened with `Open`. The handle
    /// is passed back to the service so that it can identify the device being
    /// closed.
    flexible Close(resource table {
        /// The Binder protocol opened previously.
        1: binder client_end:Binder;
    });
};

/// Protocol that allows Starnix to control binder servers and clients in other
/// Fuchsia components.
@discoverable
open protocol RemoteController {
    /// Called by the Starnix kernel when it requires the remote Fuchsia
    /// component to start servicing the binder protocol.
    flexible Start(resource table {
        1: dev_binder client_end:DevBinder;
        2: lutex_controller client_end:LutexController;
    });
};

/// Protocol that allows a Fuchsia component to interact with the Linux futexes
/// of a process running inside starnix.
@discoverable
open protocol LutexController {
    /// FUTEX_WAIT_BITSET command
    flexible WaitBitset(@generated_name("WaitBitsetRequest") resource table {
        /// The vmo containing the shared address of the futex.
        /// Mandatory
        1: vmo zx.Handle:VMO;
        /// The offset in the vmo where the shared address of the futex is.
        /// Mandatory
        2: offset uint64;
        /// The expected value of the futex.
        /// Mandatory
        3: value uint32;
        /// The bit mask.
        /// Optional. If not present, as mask with all bits present will be used.
        4: mask uint32;
        /// The deadline for the wait operation.
        /// Optional. If not present, the operation can block indefinitely.
        5: deadline zx.Time;
    }) -> () error fuchsia.posix.Errno;

    /// FUTEX_WAKE_BITSET command
    flexible WakeBitset(@generated_name("WakeBitsetRequest") resource table {
        /// The vmo containing the shared address of the futex.
        /// Mandatory
        1: vmo zx.Handle:VMO;
        /// The offset in the vmo where the shared address of the futex is.
        /// Mandatory
        2: offset uint64;
        /// Maximum number of waiter to wake.
        /// Mandatory
        3: count uint32;
        /// The bit mask.
        /// Optional. If not present, as mask with all bits present will be used.
        4: mask uint32;
    }) -> (@generated_name("WakeResponse") resource table {
        /// The number of waiters that were woken up.
        1: count uint64;
    }) error fuchsia.posix.Errno;
};

/// An opened connection to a binder driver.
open protocol Binder {
    /// Set the VMO to used as a share resource between the driver and the
    /// client. `mapped_address` is the address where the vmo is mapped in the
    /// client address space.
    flexible SetVmo(resource struct {
        vmo zx.Handle:VMO;
        mapped_address uint64;
    });
    flexible Ioctl(struct {
        tid zx.Koid;
        request uint32;
        parameter uint64;
    }) -> () error fuchsia.posix.Errno;
};