grukservices.h

  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_ */