/*
 * Copyright (c) 2012, ETH Zurich.
 * All rights reserved.
 *
 * This file is distributed under the terms in the attached LICENSE file.
 * If you do not find this file, copies can be found by writing to:
 * ETH Zurich D-INFK, Universitaetstrasse 6, CH-8092 Zurich. Attn: Systems Group.
 */

/**
 * \brief interface between the XOMP master and workers
 */
interface xomp "Xeon Phi openMP interface" {

    /**
     * \brief sends a frame capability to the one of the local workers
     *        this cannot be used for remote workers!
     * 
     * \param [IN]  frame   frame capabilty
     * \param [IN]  addr    virtual address of the requested memory
     * \param [IN]  type    type of the memory
     * \param [OUT] msgerr  returns the outcome of the request
     */
    rpc add_memory(in cap frame,
                   in uint64 addr,
                   in uint8 type,
                   out errval msgerr); 
    
    
    /**
     * \brief asks the worker domain to update its local replicate or to 
     *        write its local changes back
     *
     * \param [IN]  addr        physical address of the frame to update
     * \param [IN]  offset      offset into the frame
     * \param [IN]  length      length of the region to update
     * \param [IN]  direction   direction of the memcpy operation
     * \param [IN]  state       state pointer 
     * \param [OUT] msg_err     outcome of the operation
     * \param [OUT] state       state pointer
     */
    rpc update_memory(in uint64 addr,
                      in uint64 offset,
                      in uint64 length,
                      in uint8  direction,
                      in uint64 state,
                      out errval msg_err,
                      out uint64 out_state);

    /**
     * \brief notifies the worker domain to obtain memory from the local
     *        gateway
     * 
     * \param [IN]  addr    virtual address of the requested memory
     * \param [IN]  type    type of the memory
     * \param [OUT] msgerr  returns the outcome of the request
     */
    rpc gw_req_memory(in uint64 addr,
                      in uint8 type,
                      out errval msgerr);

    /**
     * \brief sends a new task to a worker domain
     * 
     * \param [IN] fn       the function to be called
     * \param [IN] arg      arguments for the functions
     * \param [IN] tid      task id
     * \param [IN] flags    task flags
     */
    message do_work(uint64 fn,
                    uint64 arg,
                    uint64 tid,
                    uint64 flags);

    /**
     * \brief sends the done notification to the XOMP master domain
     * 
     * \param [IN] tid     task id
     * \param [IN] msgerr  returns the outcome of the task
     */
    message done_notify(uint64 tid,
                        errval msgerr);

    /**
     * \brief sends the done notification with argument to the XOMP master domain
     * 
     * \param [IN] tid     task id
     * \param [IN] arg     argument
     * \param [IN] msgerr  returns the outcome of the task
     */
    message done_with_arg(uint64 tid,
                          uint64 arg,
                          errval msgerr);
};