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

   1 /*
   2     Copyright (c) 2014-2015 Intel Corporation.  All Rights Reserved.
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8       * Redistributions of source code must retain the above copyright
   9         notice, this list of conditions and the following disclaimer.
  10       * Redistributions in binary form must reproduce the above copyright
  11         notice, this list of conditions and the following disclaimer in the
  12         documentation and/or other materials provided with the distribution.
  13       * Neither the name of Intel Corporation nor the names of its
  14         contributors may be used to endorse or promote products derived
  15         from this software without specific prior written permission.
  16
  17     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21     HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 */
  29
  30
  31 #ifndef _ORSL_LITE_H_
  32 #define _ORSL_LITE_H_
  33
  34 #ifndef TARGET_WINNT
  35 #include <sched.h>
  36 #else
  37 #define cpu_set_t int
  38 #endif
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /** Type of a ORSLBusySet */
  45 typedef enum ORSLBusySetType {
  46     BUSY_SET_EMPTY = 0,     /**< Empty set */
  47     BUSY_SET_PARTIAL = 1,   /**< Non-empty set that omits some threads */
  48     BUSY_SET_FULL = 2       /**< A set that includes all threads on the card */
  49 } BusySetType;
  50
  51 /** ORSLBusySet encapsulation */
  52 typedef struct ORSLBusySet {
  53     BusySetType type;   /**< Set type */
  54 #ifdef __linux__
  55     cpu_set_t cpu_set;  /**< CPU mask (unused for BUSY_SET_EMPTY and
  56                            BUSY_SET_PARTIAL sets) represented by the standard
  57                            Linux CPU set type -- cpu_set_t. Threads are numbered
  58                            starting from 0. The maximal possible thread number
  59                            is system-specific. See CPU_SET(3) family of macros
  60                            for more details. Unused in ORSL Lite. */
  61 #endif
  62 } ORSLBusySet;
  63
  64 /** Client tag */
  65 typedef char* ORSLTag;
  66
  67 /** Maximal length of tag in characters */
  68 #define ORSL_MAX_TAG_LEN 128
  69
  70 /** Maximal number of cards that can be managed by ORSL */
  71 #define ORSL_MAX_CARDS 32
  72
  73 /** Reserves computational resources on a set of cards. Blocks.
  74  *
  75  * If any of the resources cannot be reserved, this function will block until
  76  * they become available. Reservation can be recursive if performed by the
  77  * same tag. A recursively reserved resource must be released the same number
  78  * of times it was reserved.
  79  *
  80  * @see ORSLTryReserve
  81  *
  82  * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
  83  *                    or > ORSL_MAX_CARDS.
  84  *
  85  * @param[in]  inds   Indices of the cards: an integer array with n elements.
  86  *                    Cannot be NULL if n > 0. Valid card indices are from 0
  87  *                    to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
  88  *
  89  * @param[in]  bsets  Requested resources on each of the card. Cannot be NULL
  90  *                    if n > 0.
  91  *
  92  * @param[in]  tag    ORSLTag of the calling client. Cannot be NULL. Length
  93  *                    must not exeed ORSL_MAX_TAG_LEN.
  94  *
  95  * @returns    0      if the resources were successfully reserved
  96  *
  97  * @returns    EINVAL if any of the arguments is invalid
  98  *
  99  * @returns    EAGAIN limit of recursive reservations reached
 100  *                    (not in ORSL Lite)
 101  *
 102  * @returns    ENOSYS (in ORSL Lite) if type of any of the busy sets is
 103  *                    equal to BUSY_SET_PARTIAL
 104  */
 105 int ORSLReserve(const int n, const int *__restrict inds,
 106                 const ORSLBusySet *__restrict bsets,
 107                 const ORSLTag __restrict tag);
 108
 109 /** Reserves computational resources on a set of cards. Does not block.
 110  *
 111  * If any of the resources cannot be reserved, this function will return
 112  * immediately. Reservation can be recursive if performed by the same tag.
 113  * A recursively reserved resource must be released the same number of times
 114  * it was reserved.
 115  *
 116  * @see ORSLReserve
 117  *
 118  * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 119  *                    or > ORSL_MAX_CARDS.
 120  *
 121  * @param[in]  inds     Indices of the cards: an integer array with n elements.
 122  *                      Cannot be NULL if n > 0. Valid card indices are from 0
 123  *                      to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 124  *
 125  * @param[inout] bsets  Requested resources on each of the card. Cannot be
 126  *                      NULL if n > 0.
 127  *
 128  * @param[in]    tag    ORSLTag of the calling client. Cannot be NULL. Length
 129  *                      must not exceed ORSL_MAX_TAG_LEN.
 130  *
 131  * @returns      0      if the resources were successfully reserved
 132  *
 133  * @returns      EBUSY  if some of the requested resources are busy
 134  *
 135  * @returns      EINVAL if any of the arguments is invalid
 136  *
 137  * @returns      EAGAIN limit of recursive reservations reached
 138  *                      (not in ORSL Lite)
 139  *
 140  * @returns      ENOSYS (in ORSL Lite) if type of any of the busy sets is
 141  *                      equal to BUSY_SET_PARTIAL
 142  */
 143 int ORSLTryReserve(const int n, const int *__restrict inds,
 144                    const ORSLBusySet *__restrict bsets,
 145                    const ORSLTag __restrict tag);
 146
 147 /** Granularify of partial reservation */
 148 typedef enum ORSLPartialGranularity {
 149     GRAN_CARD = 0, /**< Card granularity */
 150     GRAN_THREAD = 1 /**< Thread granularity */
 151 } ORSLPartialGranularity;
 152
 153 /** Requests reservation of some of computational resources on a set of cards.
 154  * Does not block. Updates user-provided bsets to indicate which resources
 155  * were reserved.
 156  *
 157  * If any of the resources cannot be reserved, this function will update busy
 158  * sets provided by the caller to reflect what resources were actually
 159  * reserved. This function supports two granularity modes: 'card' and
 160  * 'thread'.  When granularity is set to 'card', a failure to reserve a thread
 161  * on the card will imply that reservation has failed for the whole card. When
 162  * granularity is set to 'thread', reservation on a card will be considered
 163  * successful as long as at least one thread on the card was successfully
 164  * reserved. Reservation can be recursive if performed by the same tag. A
 165  * recursively reserved resource must be released the same number of times it
 166  * was reserved.
 167  *
 168  * @param[in]  gran   Reservation granularity
 169  *
 170  * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 171  *                    or > ORSL_MAX_CARDS.
 172  *
 173  * @param[in]  inds   Indices of the cards: an integer array with n elements.
 174  *                    Cannot be NULL if n > 0. Valid card indices are from 0
 175  *                    to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 176  *
 177  * @param[in]  bsets  Requested resources on each of the card. Cannot be NULL
 178  *                    if n > 0.
 179  *
 180  * @param[in]  tag    ORSLTag of the calling client. Cannot be NULL. Length
 181  *                    must not exceed ORSL_MAX_TAG_LEN.
 182  *
 183  * @returns    0      if at least some of the resources were successfully
 184  *                    reserved
 185  *
 186  * @returns    EBUSY  if all of the requested resources are busy
 187  *
 188  * @returns    EINVAL if any of the arguments is invalid
 189  *
 190  * @returns    EAGAIN limit of recursive reservations reached
 191  *                    (not in ORSL Lite)
 192  *
 193  * @returns    ENOSYS (in ORSL Lite) if type of any of the busy sets is
 194  *                    equal to BUSY_SET_PARTIAL
 195  */
 196 int ORSLReservePartial(const ORSLPartialGranularity gran, const int n,
 197                        const int *__restrict inds,
 198                        ORSLBusySet *__restrict bsets,
 199                        const ORSLTag __restrict tag);
 200
 201 /** Releases previously reserved computational resources on a set of cards.
 202  *
 203  * This function will fail if any of the resources to be released were not
 204  * reserved by the calling client.
 205  *
 206  * @see ORSLReserve
 207  * @see ORSLTryReserve
 208  * @see ORSLReservePartial
 209  *
 210  * @param[in]  n      Number of cards to reserve resources on. Cannot be < 0
 211  *                    or > ORSL_MAX_CARDS.
 212  *
 213  * @param[in]  inds   Indices of the cards: an integer array with n elements.
 214  *                    Cannot be NULL if n > 0. Valid card indices are from 0
 215  *                    to ORSL_MAX_CARDS-1. Cannot contain duplicate elements.
 216  *
 217  * @param[in]  bsets  Requested resources on each of the card. Cannot be NULL
 218  *                    if n > 0.
 219  *
 220  * @param[in]  tag    ORSLTag of the calling client. Cannot be NULL. Length
 221  *                    must not exceed ORSL_MAX_TAG_LEN.
 222  *
 223  * @returns    0      if the resources were successfully released
 224  *
 225  * @returns    EINVAL if any of the arguments is invalid
 226  *
 227  * @returns    EPERM  the calling client did not reserve some of the
 228  *                    resources it is trying to release.
 229  *
 230  * @returns    ENOSYS (in ORSL Lite) if type of any of the busy sets is
 231  *                    equal to BUSY_SET_PARTIAL
 232  */
 233 int ORSLRelease(const int n, const int *__restrict inds,
 234                 const ORSLBusySet *__restrict bsets,
 235                 const ORSLTag __restrict tag);
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif