sgi-gru: add statistics to the GRU context management functions
[linux-2.6.git] / 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_ */