drivers/misc/sgi-gru/grukservices.h

   1
   2 /*
   3  *  Copyright (c) 2008 Silicon Graphics, Inc.  All Rights Reserved.
   4  *
   5  *  This program is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation; either version 2 of the License, or
   8  *  (at your option) any later version.
   9  *
  10  *  This program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with this program; if not, write to the Free Software
  17  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  18  */
  19 #ifndef __GRU_KSERVICES_H_
  20 #define __GRU_KSERVICES_H_
  21
  22
  23 /*
  24  * Message queues using the GRU to send/receive messages.
  25  *
  26  * These function allow the user to create a message queue for
  27  * sending/receiving 1 or 2 cacheline messages using the GRU.
  28  *
  29  * Processes SENDING messages will use a kernel CBR/DSR to send
  30  * the message. This is transparent to the caller.
  31  *
  32  * The receiver does not use any GRU resources.
  33  *
  34  * The functions support:
  35  *      - single receiver
  36  *      - multiple senders
  37  *      - cross partition message
  38  *
  39  * Missing features ZZZ:
  40  *      - user options for dealing with timeouts, queue full, etc.
  41  *      - gru_create_message_queue() needs interrupt vector info
  42  */
  43
  44 /*
  45  * Initialize a user allocated chunk of memory to be used as
  46  * a message queue. The caller must ensure that the queue is
  47  * in contiguous physical memory and is cacheline aligned.
  48  *
  49  * Message queue size is the total number of bytes allocated
  50  * to the queue including a 2 cacheline header that is used
  51  * to manage the queue.
  52  *
  53  *  Input:
  54  *      p       pointer to user allocated memory.
  55  *      bytes   size of message queue in bytes
  56  *
  57  *  Errors:
  58  *      0       OK
  59  *      >0      error
  60  */
  61 extern int gru_create_message_queue(void *p, unsigned int bytes);
  62
  63 /*
  64  * Send a message to a message queue.
  65  *
  66  * Note: The message queue transport mechanism uses the first 32
  67  * bits of the message. Users should avoid using these bits.
  68  *
  69  *
  70  *   Input:
  71  *      xmq     message queue - must be a UV global physical address
  72  *      mesg    pointer to message. Must be 64-bit aligned
  73  *      bytes   size of message in bytes
  74  *
  75  *   Output:
  76  *      0       message sent
  77  *     >0       Send failure - see error codes below
  78  *
  79  */
  80 extern int gru_send_message_gpa(unsigned long mq_gpa, void *mesg,
  81                                                 unsigned int bytes);
  82
  83 /* Status values for gru_send_message() */
  84 #define MQE_OK                  0       /* message sent successfully */
  85 #define MQE_CONGESTION          1       /* temporary congestion, try again */
  86 #define MQE_QUEUE_FULL          2       /* queue is full */
  87 #define MQE_UNEXPECTED_CB_ERR   3       /* unexpected CB error */
  88 #define MQE_PAGE_OVERFLOW       10      /* BUG - queue overflowed a page */
  89 #define MQE_BUG_NO_RESOURCES    11      /* BUG - could not alloc GRU cb/dsr */
  90
  91 /*
  92  * Advance the receive pointer for the message queue to the next message.
  93  * Note: current API requires messages to be gotten & freed in order. Future
  94  * API extensions may allow for out-of-order freeing.
  95  *
  96  *   Input
  97  *      mq      message queue
  98  *      mesq    message being freed
  99  */
 100 extern void gru_free_message(void *mq, void *mesq);
 101
 102 /*
 103  * Get next message from message queue. Returns pointer to
 104  * message OR NULL if no message present.
 105  * User must call gru_free_message() after message is processed
 106  * in order to move the queue pointers to next message.
 107  *
 108  *   Input
 109  *      mq      message queue
 110  *
 111  *   Output:
 112  *      p       pointer to message
 113  *      NULL    no message available
 114  */
 115 extern void *gru_get_next_message(void *mq);
 116
 117
 118 /*
 119  * Copy data using the GRU. Source or destination can be located in a remote
 120  * partition.
 121  *
 122  *    Input:
 123  *      dest_gpa        destination global physical address
 124  *      src_gpa         source global physical address
 125  *      bytes           number of bytes to copy
 126  *
 127  *    Output:
 128  *      0               OK
 129  *      >0              error
 130  */
 131 extern int gru_copy_gpa(unsigned long dest_gpa, unsigned long src_gpa,
 132                                                         unsigned int bytes);
 133
 134 #endif          /* __GRU_KSERVICES_H_ */