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 << 11)
43 #define WLS_TF_LTE (1 << 10)
44 #define WLS_TF_SYN (1 << 9)
45 #define WLS_TF_FIN (1 << 8)
46 #define WLS_FLAGS_MASK (0xFF00)
48 /** First block in Scatter/Gather sequence of blocks */
49 #define WLS_SG_FIRST (WLS_TF_SCATTER_GATHER | WLS_TF_SYN)
50 /** Next block in Scatter/Gather sequence of blocks */
51 #define WLS_SG_NEXT (WLS_TF_SCATTER_GATHER)
52 /** Last block in Scatter/Gather sequence of blocks */
53 #define WLS_SG_LAST (WLS_TF_SCATTER_GATHER | WLS_TF_FIN)
55 //-------------------------------------------------------------------------------------------
58 * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
59 * @param[in] mode - mode of operation (Master or Slave)
60 * @param[in] nWlsMacMemorySize - Pointer with size of Memory blocks managed by MAC
61 * @param[in] nWlsPhyMemorySize - Pointer with size of Memory blocks managed by L1 (SRS Channel Estimates)
63 * @return pointer to WLS handle
66 * Function opens the WLS interface and registers as instance in the kernel space driver.
67 * Control section of shared memory is mapped to application memory.
68 * pointer (handle) of WLS interface is returned for future use by WLS functions
71 //-------------------------------------------------------------------------------------------
72 void* WLS_Open(const char *ifacename, unsigned int mode, uint64_t *nWlsMacMemorySize, uint64_t *nWlsPhyMemorySize);
74 uint32_t WLS_SetMode(void* h, unsigned int mode);
75 //-------------------------------------------------------------------------------------------
78 * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
79 * @param[in] modef - mode of operation (Master or Slave)
81 * @return pointer to second WLS handle while first WLS_handle is returned to the argument handle1 location
84 * Function opens the WLS interface and registers two instances in the kernel space driver.
85 * Control section of shared memory is mapped to application memory.
86 * pointer (handle) of WLS interface is returned for future use by WLS functions
89 //-------------------------------------------------------------------------------------------
90 void* WLS_Open_Dual(const char *ifacename, unsigned int mode, uint64_t *nWlsMacMemorySize, uint64_t *nWlsPhyMemorySize, void** handle1);
92 //-------------------------------------------------------------------------------------------
95 * @param[in] h - handle of WLS interface to close
97 * @return 0 - in case of success
100 * Function closes the WLS interface and deregisters as instance in the kernel space driver.
101 * Control section of shared memory is unmapped form user space application
104 //-------------------------------------------------------------------------------------------
105 int WLS_Close(void* h);
107 //-------------------------------------------------------------------------------------------
110 * @param[in] h - handle of second WLS interface within same app to close
112 * @return 0 - in case of success
115 * Function closes a second WLS interface open from a same process and deregisters as instance in the kernel space driver.
116 * Control section of shared memory is unmapped form user space application
119 //-------------------------------------------------------------------------------------------
120 int WLS_Close1(void* h);
121 //-------------------------------------------------------------------------------------------
124 * @param[in] h - handle of WLS interface to check status
126 * @return 1 - in case of success
129 * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
130 * (one to one connection is established)
133 //-------------------------------------------------------------------------------------------
134 int WLS_Ready(void* h);
136 //-------------------------------------------------------------------------------------------
139 * @param[in] h - handle of second WLS interface within the same app to check status
141 * @return 1 - in case of success
144 * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
145 * (one to one connection is established)
148 //-------------------------------------------------------------------------------------------
149 int WLS_Ready1(void* h);
150 //-------------------------------------------------------------------------------------------
153 * @param[in] h - handle of WLS interface
154 * @param[in] size - size of memory block to allocate
156 * @return void* - pointer to allocated memory block or NULL if no memory available
159 * Function allocates memory block for data exchange shared memory. Memory block is backed
163 //-------------------------------------------------------------------------------------------
164 void* WLS_Alloc(void* h, uint64_t size);
166 //-------------------------------------------------------------------------------------------
169 * @param[in] h - handle of WLS interface
170 * @param[in] pMsg - pointer to WLS memory
172 * @return 0 - if operation is successful
175 * Function frees memory block for data exchange shared memory. Memory block is backed
179 //-------------------------------------------------------------------------------------------
180 int WLS_Free(void* h, void* pMsg);
182 //-------------------------------------------------------------------------------------------
185 * @param[in] h - handle of WLS interface
186 * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
187 * pointer should belong to WLS memory allocated via WLS_Alloc()
188 * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
189 * @param[in] MsgTypeID - application specific identifier of message type
190 * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
192 * @return 0 - if successful
196 * Function puts memory block (or group of blocks) allocated from WLS memory into interface
197 * for transfer to remote peer.
200 //-------------------------------------------------------------------------------------------
201 int WLS_Put(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
203 //-------------------------------------------------------------------------------------------
206 * @param[in] h - handle of second WLS interface within same app
207 * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
208 * pointer should belong to WLS memory allocated via WLS_Alloc()
209 * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
210 * @param[in] MsgTypeID - application specific identifier of message type
211 * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
213 * @return 0 - if successful
217 * Function puts memory block (or group of blocks) allocated from WLS memory into interface
218 * for transfer to remote peer.
221 //-------------------------------------------------------------------------------------------
222 int WLS_Put1(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
223 //-------------------------------------------------------------------------------------------
226 * @param[in] h - handle of WLS interface
228 * @return number of blocks available
231 * Function checks if there are memory blocks with data from remote peer and returns number of blocks
232 * available for "get" operation
235 //-------------------------------------------------------------------------------------------
236 int WLS_Check(void* h);
238 //-------------------------------------------------------------------------------------------
241 * @param[in] h - handle of second WLS interface within same app
243 * @return number of blocks available
246 * Function checks if there are memory blocks with data from remote peer and returns number of blocks
247 * available for "get" operation
250 //-------------------------------------------------------------------------------------------
251 int WLS_Check1(void* h);
253 //-------------------------------------------------------------------------------------------
256 * @param[in] h - handle of WLS interface
257 * @param[in] *MsgSize - pointer to set size of memory block
258 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
259 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
261 * @return pointer to memory block (physical address) with data received from remote peer
265 * Function gets memory block from interface received from remote peer. Function is non-blocking
266 * operation and returns NULL if no blocks available
269 //-------------------------------------------------------------------------------------------
270 unsigned long long WLS_Get(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
273 //-------------------------------------------------------------------------------------------
276 * @param[in] h - handle of second WLS interface within same app
277 * @param[in] *MsgSize - pointer to set size of memory block
278 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
279 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
281 * @return pointer to memory block (physical address) with data received from remote peer
285 * Function gets memory block from interface received from remote peer. Function is non-blocking
286 * operation and returns NULL if no blocks available
289 //-------------------------------------------------------------------------------------------
290 unsigned long long WLS_Get1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
292 //-------------------------------------------------------------------------------------------
295 * @param[in] h - handle of WLS interface
297 * @return number of blocks available for get
300 * Function waits for new memory block from remote peer. Function is blocking call and returns number
301 * of blocks received.
304 //-------------------------------------------------------------------------------------------
305 int WLS_Wait(void* h);
307 //-------------------------------------------------------------------------------------------
310 * @param[in] h - handle second of WLS interface within same app
312 * @return number of blocks available for get
315 * Function waits for new memory block from remote peer. Function is blocking call and returns number
316 * of blocks received.
319 //-------------------------------------------------------------------------------------------
320 int WLS_Wait1(void* h);
322 //-------------------------------------------------------------------------------------------
325 * @param[in] h - handle of WLS interface
327 * @return 0 - if successful
330 * Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
333 //-------------------------------------------------------------------------------------------
334 int WLS_WakeUp(void* h);
336 //-------------------------------------------------------------------------------------------
339 * @param[in] h - handle of second WLS interface within same app
341 * @return 0 - if successful
344 * Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
347 //-------------------------------------------------------------------------------------------
348 int WLS_WakeUp1(void* h);
349 //-------------------------------------------------------------------------------------------
352 * @param[in] h - handle of WLS interface
353 * @param[in] *MsgSize - pointer to set size of memory block
354 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
355 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
357 * @return pointer to memory block (physical address) with data received from remote peer
361 * Function gets memory block from interface received from remote peer. Function is blocking
362 * operation and waits till next memory block from remote peer.
365 //-------------------------------------------------------------------------------------------
366 unsigned long long WLS_WGet(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
368 //-------------------------------------------------------------------------------------------
371 * @param[in] h - handle of second WLS interface within the same app
372 * @param[in] *MsgSize - pointer to set size of memory block
373 * @param[in] *MsgTypeID - pointer to application specific identifier of message type
374 * @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
376 * @return pointer to memory block (physical address) with data received from remote peer
380 * Function gets memory block from interface received from remote peer. Function is blocking
381 * operation and waits till next memory block from remote peer.
384 //-------------------------------------------------------------------------------------------
385 unsigned long long WLS_WGet1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
387 //-------------------------------------------------------------------------------------------
390 * @param[in] h - handle of WLS interface
391 * @param[in] pMsg - virtual address of WLS memory block.
393 * @return physical address of WLS memory block
397 * Function converts virtual address (VA) to physical address (PA)
400 //-------------------------------------------------------------------------------------------
401 unsigned long long WLS_VA2PA(void* h, void* pMsg);
403 //-------------------------------------------------------------------------------------------
406 * @param[in] h - handle of WLS interface
407 * @param[in] pMsg - physical address of WLS memory block.
409 * @return virtual address of WLS memory block
413 * Function converts physical address (PA) to virtual address (VA)
416 //-------------------------------------------------------------------------------------------
417 void* WLS_PA2VA(void* h, unsigned long long pMsg);
419 //-------------------------------------------------------------------------------------------
422 * @param[in] h - handle of WLS interface
423 * @param[in] pMsg - physical address of WLS memory block.
425 * @return 0 - if successful
429 * Function is used by master to provide memory blocks to slave for next slave to master transfer
433 //-------------------------------------------------------------------------------------------
434 int WLS_EnqueueBlock(void* h, unsigned long long pMsg);
436 //-------------------------------------------------------------------------------------------
439 * @param[in] h -- handle of second WLS interface within the same app
440 * @param[in] pMsg - physical address of WLS memory block.
442 * @return 0 - if successful
446 * Function is used by master to provide memory blocks to slave for next slave to master transfer
450 //-------------------------------------------------------------------------------------------
451 int WLS_EnqueueBlock1(void* h, unsigned long long pMsg);
454 //-------------------------------------------------------------------------------------------
457 * @param[in] h - handle of WLS interface
459 * @return 0 - pointer (physical address) of WLS memory block
463 * Function is used by master and slave to get block from master to slave queue of available memory
467 //-------------------------------------------------------------------------------------------
468 unsigned long long WLS_DequeueBlock(void* h);
470 //-------------------------------------------------------------------------------------------
473 * @param[in] h - handle of WLS interface
475 * @return number of blocks in slave to master queue
478 * Function returns number of current available block provided by master for new transfer
479 * of data from slave.
482 //-------------------------------------------------------------------------------------------
483 int WLS_NumBlocks(void* h);