1 /******************************************************************************
3 * Copyright (c) 2021 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 *******************************************************************************/
28 /** WLS driver client operates as slave in terms of management of shared memory */
29 #define WLS_SLAVE_CLIENT 0
30 /** WLS driver client operates as master in terms of management of shared memory */
31 #define WLS_MASTER_CLIENT 1
32 /** WLS Open Dual Options */
34 #define WLS_SEC_MASTER 1
35 /** WLS Open Dual enabled */
36 #define WLS_SINGLE_MODE 0
37 #define WLS_DUAL_MODE 1
40 /* definitions PUT/GET Flags */
41 #define WLS_TF_SCATTER_GATHER (1 << 15)
42 #define WLS_TF_URLLC (1 << 10)
43 #define WLS_TF_SYN (1 << 9)
44 #define WLS_TF_FIN (1 << 8)
45 #define WLS_FLAGS_MASK (0xFF00)
47 /** First block in Scatter/Gather sequence of blocks */
48 #define WLS_SG_FIRST (WLS_TF_SCATTER_GATHER | WLS_TF_SYN)
49 /** Next block in Scatter/Gather sequence of blocks */
50 #define WLS_SG_NEXT (WLS_TF_SCATTER_GATHER)
51 /** Last block in Scatter/Gather sequence of blocks */
52 #define WLS_SG_LAST (WLS_TF_SCATTER_GATHER | WLS_TF_FIN)
54 //-------------------------------------------------------------------------------------------
57 * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
58 * @param[in] mode - mode of operation (Master or Slave)
59 * @param[in] nWlsMacMemorySize - Pointer with size of Memory blocks managed by MAC
60 * @param[in] nWlsPhyMemorySize - Pointer with size of Memory blocks managed by L1 (SRS Channel Estimates)
62 * @return pointer to WLS handle
65 * Function opens the WLS interface and registers as instance in the kernel space driver.
66 * Control section of shared memory is mapped to application memory.
67 * pointer (handle) of WLS interface is returned for future use by WLS functions
70 //-------------------------------------------------------------------------------------------
71 void* WLS_Open(const char *ifacename, unsigned int mode, uint64_t *nWlsMacMemorySize, uint64_t *nWlsPhyMemorySize);
73 uint32_t WLS_SetMode(void* h, unsigned int mode);
74 //-------------------------------------------------------------------------------------------
77 * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
78 * @param[in] modef - mode of operation (Master or Slave)
80 * @return pointer to second WLS handle while first WLS_handle is returned to the argument handle1 location
83 * Function opens the WLS interface and registers two instances in the kernel space driver.
84 * Control section of shared memory is mapped to application memory.
85 * pointer (handle) of WLS interface is returned for future use by WLS functions
88 //-------------------------------------------------------------------------------------------
89 void* WLS_Open_Dual(const char *ifacename, unsigned int mode, uint64_t *nWlsMacMemorySize, uint64_t *nWlsPhyMemorySize, void** handle1);
91 //-------------------------------------------------------------------------------------------
94 * @param[in] h - handle of WLS interface to close
96 * @return 0 - in case of success
99 * Function closes the WLS interface and deregisters as instance in the kernel space driver.
100 * Control section of shared memory is unmapped form user space application
103 //-------------------------------------------------------------------------------------------
104 int WLS_Close(void* h);
106 //-------------------------------------------------------------------------------------------
109 * @param[in] h - handle of second WLS interface within same app to close
111 * @return 0 - in case of success
114 * Function closes a second WLS interface open from a same process and deregisters as instance in the kernel space driver.
115 * Control section of shared memory is unmapped form user space application
118 //-------------------------------------------------------------------------------------------
119 int WLS_Close1(void* h);
120 //-------------------------------------------------------------------------------------------
123 * @param[in] h - handle of WLS interface to check status
125 * @return 1 - in case of success
128 * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
129 * (one to one connection is established)
132 //-------------------------------------------------------------------------------------------
133 int WLS_Ready(void* h);
135 //-------------------------------------------------------------------------------------------
138 * @param[in] h - handle of second WLS interface within the same app to check status
140 * @return 1 - in case of success
143 * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
144 * (one to one connection is established)
147 //-------------------------------------------------------------------------------------------
148 int WLS_Ready1(void* h);
149 //-------------------------------------------------------------------------------------------
152 * @param[in] h - handle of WLS interface
153 * @param[in] size - size of memory block to allocate
155 * @return void* - pointer to allocated memory block or NULL if no memory available
158 * Function allocates memory block for data exchange shared memory. Memory block is backed
162 //-------------------------------------------------------------------------------------------
163 void* WLS_Alloc(void* h, uint64_t size);
165 //-------------------------------------------------------------------------------------------
168 * @param[in] h - handle of WLS interface
169 * @param[in] pMsg - pointer to WLS memory
171 * @return 0 - if operation is successful
174 * Function frees memory block for data exchange shared memory. Memory block is backed
178 //-------------------------------------------------------------------------------------------
179 int WLS_Free(void* h, void* pMsg);
181 //-------------------------------------------------------------------------------------------
184 * @param[in] h - handle of WLS interface
185 * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
186 * pointer should belong to WLS memory allocated via WLS_Alloc()
187 * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
188 * @param[in] MsgTypeID - application specific identifier of message type
189 * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
191 * @return 0 - if successful
195 * Function puts memory block (or group of blocks) allocated from WLS memory into interface
196 * for transfer to remote peer.
199 //-------------------------------------------------------------------------------------------
200 int WLS_Put(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
202 //-------------------------------------------------------------------------------------------
205 * @param[in] h - handle of second WLS interface within same app
206 * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
207 * pointer should belong to WLS memory allocated via WLS_Alloc()
208 * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
209 * @param[in] MsgTypeID - application specific identifier of message type
210 * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
212 * @return 0 - if successful
216 * Function puts memory block (or group of blocks) allocated from WLS memory into interface
217 * for transfer to remote peer.
220 //-------------------------------------------------------------------------------------------
221 int WLS_Put1(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
222 //-------------------------------------------------------------------------------------------
225 * @param[in] h - handle of WLS interface
227 * @return number of blocks available
230 * Function checks if there are memory blocks with data from remote peer and returns number of blocks
231 * available for "get" operation
234 //-------------------------------------------------------------------------------------------
235 int WLS_Check(void* h);
237 //-------------------------------------------------------------------------------------------
240 * @param[in] h - handle of second WLS interface within same app
242 * @return number of blocks available
245 * Function checks if there are memory blocks with data from remote peer and returns number of blocks
246 * available for "get" operation
249 //-------------------------------------------------------------------------------------------
250 int WLS_Check1(void* h);
252 //-------------------------------------------------------------------------------------------
255 * @param[in] h - handle of WLS interface
256 * @param[in] *MsgSize - pointer to set size of memory block
257 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
258 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
260 * @return pointer to memory block (physical address) with data received from remote peer
264 * Function gets memory block from interface received from remote peer. Function is non-blocking
265 * operation and returns NULL if no blocks available
268 //-------------------------------------------------------------------------------------------
269 unsigned long long WLS_Get(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
272 //-------------------------------------------------------------------------------------------
275 * @param[in] h - handle of second WLS interface within same app
276 * @param[in] *MsgSize - pointer to set size of memory block
277 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
278 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
280 * @return pointer to memory block (physical address) with data received from remote peer
284 * Function gets memory block from interface received from remote peer. Function is non-blocking
285 * operation and returns NULL if no blocks available
288 //-------------------------------------------------------------------------------------------
289 unsigned long long WLS_Get1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
291 //-------------------------------------------------------------------------------------------
294 * @param[in] h - handle of WLS interface
296 * @return number of blocks available for get
299 * Function waits for new memory block from remote peer. Function is blocking call and returns number
300 * of blocks received.
303 //-------------------------------------------------------------------------------------------
304 int WLS_Wait(void* h);
306 //-------------------------------------------------------------------------------------------
309 * @param[in] h - handle second of WLS interface within same app
311 * @return number of blocks available for get
314 * Function waits for new memory block from remote peer. Function is blocking call and returns number
315 * of blocks received.
318 //-------------------------------------------------------------------------------------------
319 int WLS_Wait1(void* h);
321 //-------------------------------------------------------------------------------------------
324 * @param[in] h - handle of WLS interface
326 * @return 0 - if successful
329 * Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
332 //-------------------------------------------------------------------------------------------
333 int WLS_WakeUp(void* h);
335 //-------------------------------------------------------------------------------------------
338 * @param[in] h - handle of second WLS interface within same app
340 * @return 0 - if successful
343 * Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
346 //-------------------------------------------------------------------------------------------
347 int WLS_WakeUp1(void* h);
348 //-------------------------------------------------------------------------------------------
351 * @param[in] h - handle of WLS interface
352 * @param[in] *MsgSize - pointer to set size of memory block
353 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
354 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
356 * @return pointer to memory block (physical address) with data received from remote peer
360 * Function gets memory block from interface received from remote peer. Function is blocking
361 * operation and waits till next memory block from remote peer.
364 //-------------------------------------------------------------------------------------------
365 unsigned long long WLS_WGet(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
367 //-------------------------------------------------------------------------------------------
370 * @param[in] h - handle of second WLS interface within the same app
371 * @param[in] *MsgSize - pointer to set size of memory block
372 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
373 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
375 * @return pointer to memory block (physical address) with data received from remote peer
379 * Function gets memory block from interface received from remote peer. Function is blocking
380 * operation and waits till next memory block from remote peer.
383 //-------------------------------------------------------------------------------------------
384 unsigned long long WLS_WGet1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
386 //-------------------------------------------------------------------------------------------
389 * @param[in] h - handle of WLS interface
390 * @param[in] pMsg - virtual address of WLS memory block.
392 * @return physical address of WLS memory block
396 * Function converts virtual address (VA) to physical address (PA)
399 //-------------------------------------------------------------------------------------------
400 unsigned long long WLS_VA2PA(void* h, void* pMsg);
402 //-------------------------------------------------------------------------------------------
405 * @param[in] h - handle of WLS interface
406 * @param[in] pMsg - physical address of WLS memory block.
408 * @return virtual address of WLS memory block
412 * Function converts physical address (PA) to virtual address (VA)
415 //-------------------------------------------------------------------------------------------
416 void* WLS_PA2VA(void* h, unsigned long long pMsg);
418 //-------------------------------------------------------------------------------------------
421 * @param[in] h - handle of WLS interface
422 * @param[in] pMsg - physical address of WLS memory block.
424 * @return 0 - if successful
428 * Function is used by master to provide memory blocks to slave for next slave to master transfer
432 //-------------------------------------------------------------------------------------------
433 int WLS_EnqueueBlock(void* h, unsigned long long pMsg);
435 //-------------------------------------------------------------------------------------------
438 * @param[in] h -- handle of second WLS interface within the same app
439 * @param[in] pMsg - physical address of WLS memory block.
441 * @return 0 - if successful
445 * Function is used by master to provide memory blocks to slave for next slave to master transfer
449 //-------------------------------------------------------------------------------------------
450 int WLS_EnqueueBlock1(void* h, unsigned long long pMsg);
453 //-------------------------------------------------------------------------------------------
456 * @param[in] h - handle of WLS interface
458 * @return 0 - pointer (physical address) of WLS memory block
462 * Function is used by master and slave to get block from master to slave queue of available memory
466 //-------------------------------------------------------------------------------------------
467 unsigned long long WLS_DequeueBlock(void* h);
469 //-------------------------------------------------------------------------------------------
472 * @param[in] h - handle of WLS interface
474 * @return number of blocks in slave to master queue
477 * Function returns number of current available block provided by master for new transfer
478 * of data from slave.
481 //-------------------------------------------------------------------------------------------
482 int WLS_NumBlocks(void* h);