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 struct gru_message_queue_desc {
  45         void            *mq;                    /* message queue vaddress */
  46         unsigned long   mq_gpa;                 /* global address of mq */
  47         int             qlines;                 /* queue size in CL */
  48         int             interrupt_vector;       /* interrupt vector */
  49         int             interrupt_pnode;        /* pnode for interrupt */
  50         int             interrupt_apicid;       /* lapicid for interrupt */
  51 };
  52
  53 /*
  54  * Initialize a user allocated chunk of memory to be used as
  55  * a message queue. The caller must ensure that the queue is
  56  * in contiguous physical memory and is cacheline aligned.
  57  *
  58  * Message queue size is the total number of bytes allocated
  59  * to the queue including a 2 cacheline header that is used
  60  * to manage the queue.
  61  *
  62  *  Input:
  63  *      mqd     pointer to message queue descriptor
  64  *      p       pointer to user allocated mesq memory.
  65  *      bytes   size of message queue in bytes
  66  *      vector  interrupt vector (zero if no interrupts)
  67  *      nasid   nasid of blade where interrupt is delivered
  68  *      apicid  apicid of cpu for interrupt
  69  *
  70  *  Errors:
  71  *      0       OK
  72  *      >0      error
  73  */
  74 extern int gru_create_message_queue(struct gru_message_queue_desc *mqd,
  75                 void *p, unsigned int bytes, int nasid, int vector, int apicid);
  76
  77 /*
  78  * Send a message to a message queue.
  79  *
  80  * Note: The message queue transport mechanism uses the first 32
  81  * bits of the message. Users should avoid using these bits.
  82  *
  83  *
  84  *   Input:
  85  *      mqd     pointer to message queue descriptor
  86  *      mesg    pointer to message. Must be 64-bit aligned
  87  *      bytes   size of message in bytes
  88  *
  89  *   Output:
  90  *      0       message sent
  91  *     >0       Send failure - see error codes below
  92  *
  93  */
  94 extern int gru_send_message_gpa(struct gru_message_queue_desc *mqd,
  95                         void *mesg, unsigned int bytes);
  96
  97 /* Status values for gru_send_message() */
  98 #define MQE_OK                  0       /* message sent successfully */
  99 #define MQE_CONGESTION          1       /* temporary congestion, try again */
 100 #define MQE_QUEUE_FULL          2       /* queue is full */
 101 #define MQE_UNEXPECTED_CB_ERR   3       /* unexpected CB error */
 102 #define MQE_PAGE_OVERFLOW       10      /* BUG - queue overflowed a page */
 103 #define MQE_BUG_NO_RESOURCES    11      /* BUG - could not alloc GRU cb/dsr */
 104
 105 /*
 106  * Advance the receive pointer for the message queue to the next message.
 107  * Note: current API requires messages to be gotten & freed in order. Future
 108  * API extensions may allow for out-of-order freeing.
 109  *
 110  *   Input
 111  *      mqd     pointer to message queue descriptor
 112  *      mesq    message being freed
 113  */
 114 extern void gru_free_message(struct gru_message_queue_desc *mqd,
 115                              void *mesq);
 116
 117 /*
 118  * Get next message from message queue. Returns pointer to
 119  * message OR NULL if no message present.
 120  * User must call gru_free_message() after message is processed
 121  * in order to move the queue pointers to next message.
 122  *
 123  *   Input
 124  *      mqd     pointer to message queue descriptor
 125  *
 126  *   Output:
 127  *      p       pointer to message
 128  *      NULL    no message available
 129  */
 130 extern void *gru_get_next_message(struct gru_message_queue_desc *mqd);
 131
 132
 133 /*
 134  * Copy data using the GRU. Source or destination can be located in a remote
 135  * partition.
 136  *
 137  *    Input:
 138  *      dest_gpa        destination global physical address
 139  *      src_gpa         source global physical address
 140  *      bytes           number of bytes to copy
 141  *
 142  *    Output:
 143  *      0               OK
 144  *      >0              error
 145  */
 146 extern int gru_copy_gpa(unsigned long dest_gpa, unsigned long src_gpa,
 147                                                         unsigned int bytes);
 148
 149 /*
 150  * Reserve GRU resources to be used asynchronously.
 151  *
 152  *      input:
 153  *              blade_id  - blade on which resources should be reserved
 154  *              cbrs      - number of CBRs
 155  *              dsr_bytes - number of DSR bytes needed
 156  *              cmp       - completion structure for waiting for
 157  *                          async completions
 158  *      output:
 159  *              handle to identify resource
 160  *              (0 = no resources)
 161  */
 162 extern unsigned long gru_reserve_async_resources(int blade_id, int cbrs, int dsr_bytes,
 163                                 struct completion *cmp);
 164
 165 /*
 166  * Release async resources previously reserved.
 167  *
 168  *      input:
 169  *              han - handle to identify resources
 170  */
 171 extern void gru_release_async_resources(unsigned long han);
 172
 173 /*
 174  * Wait for async GRU instructions to complete.
 175  *
 176  *      input:
 177  *              han - handle to identify resources
 178  */
 179 extern void gru_wait_async_cbr(unsigned long han);
 180
 181 /*
 182  * Lock previous reserved async GRU resources
 183  *
 184  *      input:
 185  *              han - handle to identify resources
 186  *      output:
 187  *              cb  - pointer to first CBR
 188  *              dsr - pointer to first DSR
 189  */
 190 extern void gru_lock_async_resource(unsigned long han,  void **cb, void **dsr);
 191
 192 /*
 193  * Unlock previous reserved async GRU resources
 194  *
 195  *      input:
 196  *              han - handle to identify resources
 197  */
 198 extern void gru_unlock_async_resource(unsigned long han);
 199
 200 #endif          /* __GRU_KSERVICES_H_ */