1/* SPDX-License-Identifier: GPL-2.0-or-later */
2
3/*
4 *  Copyright (c) 2008 Silicon Graphics, Inc.  All Rights Reserved.
5 */
6#ifndef __GRU_KSERVICES_H_
7#define __GRU_KSERVICES_H_
8
9
10/*
11 * Message queues using the GRU to send/receive messages.
12 *
13 * These function allow the user to create a message queue for
14 * sending/receiving 1 or 2 cacheline messages using the GRU.
15 *
16 * Processes SENDING messages will use a kernel CBR/DSR to send
17 * the message. This is transparent to the caller.
18 *
19 * The receiver does not use any GRU resources.
20 *
21 * The functions support:
22 * 	- single receiver
23 * 	- multiple senders
24 *	- cross partition message
25 *
26 * Missing features ZZZ:
27 * 	- user options for dealing with timeouts, queue full, etc.
28 * 	- gru_create_message_queue() needs interrupt vector info
29 */
30
31struct gru_message_queue_desc {
32	void		*mq;			/* message queue vaddress */
33	unsigned long	mq_gpa;			/* global address of mq */
34	int		qlines;			/* queue size in CL */
35	int		interrupt_vector;	/* interrupt vector */
36	int		interrupt_pnode;	/* pnode for interrupt */
37	int		interrupt_apicid;	/* lapicid for interrupt */
38};
39
40/*
41 * Initialize a user allocated chunk of memory to be used as
42 * a message queue. The caller must ensure that the queue is
43 * in contiguous physical memory and is cacheline aligned.
44 *
45 * Message queue size is the total number of bytes allocated
46 * to the queue including a 2 cacheline header that is used
47 * to manage the queue.
48 *
49 *  Input:
50 * 	mqd	pointer to message queue descriptor
51 * 	p	pointer to user allocated mesq memory.
52 * 	bytes	size of message queue in bytes
53 *      vector	interrupt vector (zero if no interrupts)
54 *      nasid	nasid of blade where interrupt is delivered
55 *      apicid	apicid of cpu for interrupt
56 *
57 *  Errors:
58 *  	0	OK
59 *  	>0	error
60 */
61extern int gru_create_message_queue(struct gru_message_queue_desc *mqd,
62		void *p, unsigned int bytes, int nasid, int vector, int apicid);
63
64/*
65 * Send a message to a message queue.
66 *
67 * Note: The message queue transport mechanism uses the first 32
68 * bits of the message. Users should avoid using these bits.
69 *
70 *
71 *   Input:
72 * 	mqd	pointer to message queue descriptor
73 * 	mesg	pointer to message. Must be 64-bit aligned
74 * 	bytes	size of message in bytes
75 *
76 *   Output:
77 *      0	message sent
78 *     >0	Send failure - see error codes below
79 *
80 */
81extern int gru_send_message_gpa(struct gru_message_queue_desc *mqd,
82			void *mesg, unsigned int bytes);
83
84/* Status values for gru_send_message() */
85#define MQE_OK			0	/* message sent successfully */
86#define MQE_CONGESTION		1	/* temporary congestion, try again */
87#define MQE_QUEUE_FULL		2	/* queue is full */
88#define MQE_UNEXPECTED_CB_ERR	3	/* unexpected CB error */
89#define MQE_PAGE_OVERFLOW	10	/* BUG - queue overflowed a page */
90#define MQE_BUG_NO_RESOURCES	11	/* BUG - could not alloc GRU cb/dsr */
91
92/*
93 * Advance the receive pointer for the message queue to the next message.
94 * Note: current API requires messages to be gotten & freed in order. Future
95 * API extensions may allow for out-of-order freeing.
96 *
97 *   Input
98 * 	mqd	pointer to message queue descriptor
99 * 	mesq	message being freed
100 */
101extern void gru_free_message(struct gru_message_queue_desc *mqd,
102			     void *mesq);
103
104/*
105 * Get next message from message queue. Returns pointer to
106 * message OR NULL if no message present.
107 * User must call gru_free_message() after message is processed
108 * in order to move the queue pointers to next message.
109 *
110 *   Input
111 * 	mqd	pointer to message queue descriptor
112 *
113 *   Output:
114 *	p	pointer to message
115 *	NULL	no message available
116 */
117extern void *gru_get_next_message(struct gru_message_queue_desc *mqd);
118
119
120/*
121 * Read a GRU global GPA. Source can be located in a remote partition.
122 *
123 *    Input:
124 *    	value		memory address where MMR value is returned
125 *    	gpa		source numalink physical address of GPA
126 *
127 *    Output:
128 *	0		OK
129 *	>0		error
130 */
131int gru_read_gpa(unsigned long *value, unsigned long gpa);
132
133
134/*
135 * Copy data using the GRU. Source or destination can be located in a remote
136 * partition.
137 *
138 *    Input:
139 *    	dest_gpa	destination global physical address
140 *    	src_gpa		source global physical address
141 *    	bytes		number of bytes to copy
142 *
143 *    Output:
144 *	0		OK
145 *	>0		error
146 */
147extern int gru_copy_gpa(unsigned long dest_gpa, unsigned long src_gpa,
148							unsigned int bytes);
149
150/*
151 * Reserve GRU resources to be used asynchronously.
152 *
153 * 	input:
154 * 		blade_id  - blade on which resources should be reserved
155 * 		cbrs	  - number of CBRs
156 * 		dsr_bytes - number of DSR bytes needed
157 * 		cmp	  - completion structure for waiting for
158 * 			    async completions
159 *	output:
160 *		handle to identify resource
161 *		(0 = no resources)
162 */
163extern unsigned long gru_reserve_async_resources(int blade_id, int cbrs, int dsr_bytes,
164				struct completion *cmp);
165
166/*
167 * Release async resources previously reserved.
168 *
169 *	input:
170 *		han - handle to identify resources
171 */
172extern void gru_release_async_resources(unsigned long han);
173
174/*
175 * Wait for async GRU instructions to complete.
176 *
177 *	input:
178 *		han - handle to identify resources
179 */
180extern void gru_wait_async_cbr(unsigned long han);
181
182/*
183 * Lock previous reserved async GRU resources
184 *
185 *	input:
186 *		han - handle to identify resources
187 *	output:
188 *		cb  - pointer to first CBR
189 *		dsr - pointer to first DSR
190 */
191extern void gru_lock_async_resource(unsigned long han,  void **cb, void **dsr);
192
193/*
194 * Unlock previous reserved async GRU resources
195 *
196 *	input:
197 *		han - handle to identify resources
198 */
199extern void gru_unlock_async_resource(unsigned long han);
200
201#endif 		/* __GRU_KSERVICES_H_ */
202