1 /******************************************************************************
3 * Copyright (c) 2019 Intel.
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
17 *******************************************************************************/
26 /** WLS driver client operates as slave in terms of management of shared memory */
27 #define WLS_SLAVE_CLIENT 0
28 /** WLS driver client operates as master in terms of management of shared memory */
29 #define WLS_MASTER_CLIENT 1
30 /** WLS Open Dual Options */
32 #define WLS_SEC_MASTER 1
33 /** WLS Open Dual enabled */
34 #define WLS_SINGLE_MODE 0
35 #define WLS_DUAL_MODE 1
38 /* definitions PUT/GET Flags */
39 #define WLS_TF_SCATTER_GATHER (1 << 15)
40 #define WLS_TF_URLLC (1 << 10)
41 #define WLS_TF_SYN (1 << 9)
42 #define WLS_TF_FIN (1 << 8)
43 #define WLS_FLAGS_MASK (0xFF00)
45 /** First block in Scatter/Gather sequence of blocks */
46 #define WLS_SG_FIRST (WLS_TF_SCATTER_GATHER | WLS_TF_SYN)
47 /** Next block in Scatter/Gather sequence of blocks */
48 #define WLS_SG_NEXT (WLS_TF_SCATTER_GATHER)
49 /** Last block in Scatter/Gather sequence of blocks */
50 #define WLS_SG_LAST (WLS_TF_SCATTER_GATHER | WLS_TF_FIN)
52 //-------------------------------------------------------------------------------------------
55 * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
56 * @param[in] modef - mode of operation (Master or Slave)
58 * @return pointer to WLS handle
61 * Function opens the WLS interface and registers as instance in the kernel space driver.
62 * Control section of shared memory is mapped to application memory.
63 * pointer (handle) of WLS interface is returned for future use by WLS functions
66 //-------------------------------------------------------------------------------------------
67 void* WLS_Open(const char *ifacename, unsigned int mode, unsigned long long nWlsMemorySize);
69 //-------------------------------------------------------------------------------------------
72 * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
73 * @param[in] modef - mode of operation (Master or Slave)
75 * @return pointer to second WLS handle while first WLS_handle is returned to the argument handle1 location
78 * Function opens the WLS interface and registers two instances in the kernel space driver.
79 * Control section of shared memory is mapped to application memory.
80 * pointer (handle) of WLS interface is returned for future use by WLS functions
83 //-------------------------------------------------------------------------------------------
84 void* WLS_Open_Dual(const char *ifacename, unsigned int mode, unsigned long long nWlsMemorySize, void** handle1);
86 //-------------------------------------------------------------------------------------------
89 * @param[in] h - handle of WLS interface to close
91 * @return 0 - in case of success
94 * Function closes the WLS interface and deregisters as instance in the kernel space driver.
95 * Control section of shared memory is unmapped form user space application
98 //-------------------------------------------------------------------------------------------
99 int WLS_Close(void* h);
101 //-------------------------------------------------------------------------------------------
104 * @param[in] h - handle of second WLS interface within same app to close
106 * @return 0 - in case of success
109 * Function closes a second WLS interface open from a same process and deregisters as instance in the kernel space driver.
110 * Control section of shared memory is unmapped form user space application
113 //-------------------------------------------------------------------------------------------
114 int WLS_Close1(void* h);
115 //-------------------------------------------------------------------------------------------
118 * @param[in] h - handle of WLS interface to check status
120 * @return 1 - in case of success
123 * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
124 * (one to one connection is established)
127 //-------------------------------------------------------------------------------------------
128 int WLS_Ready(void* h);
130 //-------------------------------------------------------------------------------------------
133 * @param[in] h - handle of second WLS interface within the same app to check status
135 * @return 1 - in case of success
138 * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
139 * (one to one connection is established)
142 //-------------------------------------------------------------------------------------------
143 int WLS_Ready1(void* h);
144 //-------------------------------------------------------------------------------------------
147 * @param[in] h - handle of WLS interface
148 * @param[in] size - size of memory block to allocate
150 * @return void* - pointer to allocated memory block or NULL if no memory available
153 * Function allocates memory block for data exchange shared memory. Memory block is backed
157 //-------------------------------------------------------------------------------------------
158 void* WLS_Alloc(void* h, unsigned int size);
160 //-------------------------------------------------------------------------------------------
163 * @param[in] h - handle of WLS interface
164 * @param[in] pMsg - pointer to WLS memory
166 * @return 0 - if operation is successful
169 * Function frees memory block for data exchange shared memory. Memory block is backed
173 //-------------------------------------------------------------------------------------------
174 int WLS_Free(void* h, void* pMsg);
176 //-------------------------------------------------------------------------------------------
179 * @param[in] h - handle of WLS interface
180 * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
181 * pointer should belong to WLS memory allocated via WLS_Alloc()
182 * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
183 * @param[in] MsgTypeID - application specific identifier of message type
184 * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
186 * @return 0 - if successful
190 * Function puts memory block (or group of blocks) allocated from WLS memory into interface
191 * for transfer to remote peer.
194 //-------------------------------------------------------------------------------------------
195 int WLS_Put(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
197 //-------------------------------------------------------------------------------------------
200 * @param[in] h - handle of second WLS interface within same app
201 * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
202 * pointer should belong to WLS memory allocated via WLS_Alloc()
203 * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
204 * @param[in] MsgTypeID - application specific identifier of message type
205 * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
207 * @return 0 - if successful
211 * Function puts memory block (or group of blocks) allocated from WLS memory into interface
212 * for transfer to remote peer.
215 //-------------------------------------------------------------------------------------------
216 int WLS_Put1(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
217 //-------------------------------------------------------------------------------------------
220 * @param[in] h - handle of WLS interface
222 * @return number of blocks available
225 * Function checks if there are memory blocks with data from remote peer and returns number of blocks
226 * available for "get" operation
229 //-------------------------------------------------------------------------------------------
230 int WLS_Check(void* h);
232 //-------------------------------------------------------------------------------------------
235 * @param[in] h - handle of second WLS interface within same app
237 * @return number of blocks available
240 * Function checks if there are memory blocks with data from remote peer and returns number of blocks
241 * available for "get" operation
244 //-------------------------------------------------------------------------------------------
245 int WLS_Check1(void* h);
247 //-------------------------------------------------------------------------------------------
250 * @param[in] h - handle of WLS interface
251 * @param[in] *MsgSize - pointer to set size of memory block
252 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
253 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
255 * @return pointer to memory block (physical address) with data received from remote peer
259 * Function gets memory block from interface received from remote peer. Function is non-blocking
260 * operation and returns NULL if no blocks available
263 //-------------------------------------------------------------------------------------------
264 unsigned long long WLS_Get(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
267 //-------------------------------------------------------------------------------------------
270 * @param[in] h - handle of second WLS interface within same app
271 * @param[in] *MsgSize - pointer to set size of memory block
272 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
273 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
275 * @return pointer to memory block (physical address) with data received from remote peer
279 * Function gets memory block from interface received from remote peer. Function is non-blocking
280 * operation and returns NULL if no blocks available
283 //-------------------------------------------------------------------------------------------
284 unsigned long long WLS_Get1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
286 //-------------------------------------------------------------------------------------------
289 * @param[in] h - handle of WLS interface
291 * @return number of blocks available for get
294 * Function waits for new memory block from remote peer. Function is blocking call and returns number
295 * of blocks received.
298 //-------------------------------------------------------------------------------------------
299 int WLS_Wait(void* h);
301 //-------------------------------------------------------------------------------------------
304 * @param[in] h - handle second of WLS interface within same app
306 * @return number of blocks available for get
309 * Function waits for new memory block from remote peer. Function is blocking call and returns number
310 * of blocks received.
313 //-------------------------------------------------------------------------------------------
314 int WLS_Wait1(void* h);
316 //-------------------------------------------------------------------------------------------
319 * @param[in] h - handle of WLS interface
321 * @return 0 - if successful
324 * Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
327 //-------------------------------------------------------------------------------------------
328 int WLS_WakeUp(void* h);
330 //-------------------------------------------------------------------------------------------
333 * @param[in] h - handle of second WLS interface within same app
335 * @return 0 - if successful
338 * Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
341 //-------------------------------------------------------------------------------------------
342 int WLS_WakeUp1(void* h);
343 //-------------------------------------------------------------------------------------------
346 * @param[in] h - handle of WLS interface
347 * @param[in] *MsgSize - pointer to set size of memory block
348 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
349 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
351 * @return pointer to memory block (physical address) with data received from remote peer
355 * Function gets memory block from interface received from remote peer. Function is blocking
356 * operation and waits till next memory block from remote peer.
359 //-------------------------------------------------------------------------------------------
360 unsigned long long WLS_WGet(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
362 //-------------------------------------------------------------------------------------------
365 * @param[in] h - handle of second WLS interface within the same app
366 * @param[in] *MsgSize - pointer to set size of memory block
367 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
368 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
370 * @return pointer to memory block (physical address) with data received from remote peer
374 * Function gets memory block from interface received from remote peer. Function is blocking
375 * operation and waits till next memory block from remote peer.
378 //-------------------------------------------------------------------------------------------
379 unsigned long long WLS_WGet1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
381 //-------------------------------------------------------------------------------------------
384 * @param[in] h - handle of WLS interface
385 * @param[in] pMsg - virtual address of WLS memory block.
387 * @return physical address of WLS memory block
391 * Function converts virtual address (VA) to physical address (PA)
394 //-------------------------------------------------------------------------------------------
395 unsigned long long WLS_VA2PA(void* h, void* pMsg);
397 //-------------------------------------------------------------------------------------------
400 * @param[in] h - handle of WLS interface
401 * @param[in] pMsg - physical address of WLS memory block.
403 * @return virtual address of WLS memory block
407 * Function converts physical address (PA) to virtual address (VA)
410 //-------------------------------------------------------------------------------------------
411 void* WLS_PA2VA(void* h, unsigned long long pMsg);
413 //-------------------------------------------------------------------------------------------
416 * @param[in] h - handle of WLS interface
417 * @param[in] pMsg - physical address of WLS memory block.
419 * @return 0 - if successful
423 * Function is used by master to provide memory blocks to slave for next slave to master transfer
427 //-------------------------------------------------------------------------------------------
428 int WLS_EnqueueBlock(void* h, unsigned long long pMsg);
430 //-------------------------------------------------------------------------------------------
433 * @param[in] h -- handle of second WLS interface within the same app
434 * @param[in] pMsg - physical address of WLS memory block.
436 * @return 0 - if successful
440 * Function is used by master to provide memory blocks to slave for next slave to master transfer
444 //-------------------------------------------------------------------------------------------
445 int WLS_EnqueueBlock1(void* h, unsigned long long pMsg);
448 //-------------------------------------------------------------------------------------------
451 * @param[in] h - handle of WLS interface
453 * @return 0 - pointer (physical address) of WLS memory block
457 * Function is used by master and slave to get block from master to slave queue of available memory
461 //-------------------------------------------------------------------------------------------
462 unsigned long long WLS_DequeueBlock(void* h);
464 //-------------------------------------------------------------------------------------------
467 * @param[in] h - handle of WLS interface
469 * @return number of blocks in slave to master queue
472 * Function returns number of current available block provided by master for new transfer
473 * of data from slave.
476 //-------------------------------------------------------------------------------------------
477 int WLS_NumBlocks(void* h);