gcc/liboffloadmic/runtime/orsl-lite/include/orsl-lite.h

/*
    Copyright (c) 2014-2016 Intel Corporation.  All Rights Reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

      * Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.
      * Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
      * Neither the name of Intel Corporation nor the names of its
        contributors may be used to endorse or promote products derived
        from this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/


#ifndef _ORSL_LITE_H_
#define _ORSL_LITE_H_

#ifndef TARGET_WINNT
#include <sched.h>
#else
#define cpu_set_t int
#endif

#ifdef __cplusplus
extern "C" {
#endif

/** Type of a ORSLBusySet */
typedef enum ORSLBusySetType {
    BUSY_SET_EMPTY = 0,     /**< Empty set */
    BUSY_SET_PARTIAL = 1,   /**< Non-empty set that omits some threads */
    BUSY_SET_FULL = 2       /**< A set that includes all threads on the card */
} BusySetType;

/** ORSLBusySet encapsulation */
typedef struct ORSLBusySet {
    BusySetType type;   /**< Set type */
#ifdef __linux__
    cpu_set_t cpu_set;  /**< CPU mask (unused for BUSY_SET_EMPTY and
                           BUSY_SET_PARTIAL sets) represented by the standard
                           Linux CPU set type -- cpu_set_t. Threads are numbered
                           starting from 0. The maximal possible thread number
                           is system-specific. See CPU_SET(3) family of macros
                           for more details. Unused in ORSL Lite. */
#endif
} ORSLBusySet;

/** Client tag */
typedef char* ORSLTag;

/** Maximal length of tag in characters */
#define ORSL_MAX_TAG_LEN 128

/** Maximal number of cards that can be managed by ORSL */
#define ORSL_MAX_CARDS 32

/** Reserves computational resources on a set of cards. Blocks.
 *
 * If any of the resources cannot be reserved, this function will block until
 * they become available. Reservation can be recursive if performed by the
 * same tag. A recursively reserved resource must be released the same number
 * of times it was reserved.
 *
 * @see ORSLTryReserve
 *
 * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 *                    or > ORSL_MAX_CARDS.
 *
 * @param[in]  inds   Indices of the cards: an integer array with n elements.
 *                    Cannot be NULL if n > 0. Valid card indices are from 0
 *                    to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 *
 * @param[in]  bsets  Requested resources on each of the card. Cannot be NULL
 *                    if n > 0.
 *
 * @param[in]  tag    ORSLTag of the calling client. Cannot be NULL. Length
 *                    must not exeed ORSL_MAX_TAG_LEN.
 *
 * @returns    0      if the resources were successfully reserved
 *
 * @returns    EINVAL if any of the arguments is invalid
 *
 * @returns    EAGAIN limit of recursive reservations reached
 *                    (not in ORSL Lite)
 *
 * @returns    ENOSYS (in ORSL Lite) if type of any of the busy sets is
 *                    equal to BUSY_SET_PARTIAL
 */
int ORSLReserve(const int n, const int *__restrict inds,
                const ORSLBusySet *__restrict bsets,
                const ORSLTag __restrict tag);

/** Reserves computational resources on a set of cards. Does not block.
 *
 * If any of the resources cannot be reserved, this function will return
 * immediately. Reservation can be recursive if performed by the same tag.
 * A recursively reserved resource must be released the same number of times
 * it was reserved.
 *
 * @see ORSLReserve
 *
 * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 *                    or > ORSL_MAX_CARDS.
 *
 * @param[in]  inds     Indices of the cards: an integer array with n elements.
 *                      Cannot be NULL if n > 0. Valid card indices are from 0
 *                      to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 *
 * @param[inout] bsets  Requested resources on each of the card. Cannot be
 *                      NULL if n > 0.
 *
 * @param[in]    tag    ORSLTag of the calling client. Cannot be NULL. Length
 *                      must not exceed ORSL_MAX_TAG_LEN.
 *
 * @returns      0      if the resources were successfully reserved
 *
 * @returns      EBUSY  if some of the requested resources are busy
 *
 * @returns      EINVAL if any of the arguments is invalid
 *
 * @returns      EAGAIN limit of recursive reservations reached
 *                      (not in ORSL Lite)
 *
 * @returns      ENOSYS (in ORSL Lite) if type of any of the busy sets is
 *                      equal to BUSY_SET_PARTIAL
 */
int ORSLTryReserve(const int n, const int *__restrict inds,
                   const ORSLBusySet *__restrict bsets,
                   const ORSLTag __restrict tag);

/** Granularify of partial reservation */
typedef enum ORSLPartialGranularity {
    GRAN_CARD = 0, /**< Card granularity */
    GRAN_THREAD = 1 /**< Thread granularity */
} ORSLPartialGranularity;

/** Requests reservation of some of computational resources on a set of cards.
 * Does not block. Updates user-provided bsets to indicate which resources
 * were reserved.
 *
 * If any of the resources cannot be reserved, this function will update busy
 * sets provided by the caller to reflect what resources were actually
 * reserved. This function supports two granularity modes: 'card' and
 * 'thread'.  When granularity is set to 'card', a failure to reserve a thread
 * on the card will imply that reservation has failed for the whole card. When
 * granularity is set to 'thread', reservation on a card will be considered
 * successful as long as at least one thread on the card was successfully
 * reserved. Reservation can be recursive if performed by the same tag. A
 * recursively reserved resource must be released the same number of times it
 * was reserved.
 *
 * @param[in]  gran   Reservation granularity
 *
 * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 *                    or > ORSL_MAX_CARDS.
 *
 * @param[in]  inds   Indices of the cards: an integer array with n elements.
 *                    Cannot be NULL if n > 0. Valid card indices are from 0
 *                    to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 *
 * @param[in]  bsets  Requested resources on each of the card. Cannot be NULL
 *                    if n > 0.
 *
 * @param[in]  tag    ORSLTag of the calling client. Cannot be NULL. Length
 *                    must not exceed ORSL_MAX_TAG_LEN.
 *
 * @returns    0      if at least some of the resources were successfully
 *                    reserved
 *
 * @returns    EBUSY  if all of the requested resources are busy
 *
 * @returns    EINVAL if any of the arguments is invalid
 *
 * @returns    EAGAIN limit of recursive reservations reached
 *                    (not in ORSL Lite)
 *
 * @returns    ENOSYS (in ORSL Lite) if type of any of the busy sets is
 *                    equal to BUSY_SET_PARTIAL
 */
int ORSLReservePartial(const ORSLPartialGranularity gran, const int n,
                       const int *__restrict inds,
                       ORSLBusySet *__restrict bsets,
                       const ORSLTag __restrict tag);

/** Releases previously reserved computational resources on a set of cards.
 *
 * This function will fail if any of the resources to be released were not
 * reserved by the calling client.
 *
 * @see ORSLReserve
 * @see ORSLTryReserve
 * @see ORSLReservePartial
 *
 * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 *                    or > ORSL_MAX_CARDS.
 *
 * @param[in]  inds   Indices of the cards: an integer array with n elements.
 *                    Cannot be NULL if n > 0. Valid card indices are from 0
 *                    to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 *
 * @param[in]  bsets  Requested resources on each of the card. Cannot be NULL
 *                    if n > 0.
 *
 * @param[in]  tag    ORSLTag of the calling client. Cannot be NULL. Length
 *                    must not exceed ORSL_MAX_TAG_LEN.
 *
 * @returns    0      if the resources were successfully released
 *
 * @returns    EINVAL if any of the arguments is invalid
 *
 * @returns    EPERM  the calling client did not reserve some of the
 *                    resources it is trying to release.
 *
 * @returns    ENOSYS (in ORSL Lite) if type of any of the busy sets is
 *                    equal to BUSY_SET_PARTIAL
 */
int ORSLRelease(const int n, const int *__restrict inds,
                const ORSLBusySet *__restrict bsets,
                const ORSLTag __restrict tag);

#ifdef __cplusplus
}
#endif

#endif