wls_lib/wls_lib.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2021 Intel.
   4 *
   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
   8 *
   9 *       http://www.apache.org/licenses/LICENSE-2.0
  10 *
  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.
  16 *
  17 *******************************************************************************/
  18
  19 #ifndef _WLS_LIB_H_
  20 #define _WLS_LIB_H_
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 #include <stdint.h>
  27
  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 */
  33 #define WLS_SEC_NA     0
  34 #define WLS_SEC_MASTER 1
  35 /** WLS Open Dual enabled */
  36 #define WLS_SINGLE_MODE 0
  37 #define WLS_DUAL_MODE   1
  38
  39
  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)
  47
  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)
  54
  55 //-------------------------------------------------------------------------------------------
  56 /** @ingroup wls_mod
  57  *
  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)
  62  *
  63  *  @return  pointer to WLS handle
  64  *
  65  *  @description
  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
  69  *
  70 **/
  71 //-------------------------------------------------------------------------------------------
  72 void* WLS_Open(const char *ifacename, unsigned int mode, uint64_t *nWlsMacMemorySize, uint64_t *nWlsPhyMemorySize);
  73
  74 uint32_t WLS_SetMode(void* h, unsigned int mode);
  75 //-------------------------------------------------------------------------------------------
  76 /** @ingroup wls_mod
  77  *
  78  *  @param[in]   ifacename - pointer to string with device driver name (/dev/wls)
  79  *  @param[in]   modef     - mode of operation (Master or Slave)
  80  *
  81  *  @return  pointer to second WLS handle while first WLS_handle is returned to the argument handle1 location
  82  *
  83  *  @description
  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
  87  *
  88 **/
  89 //-------------------------------------------------------------------------------------------
  90 void* WLS_Open_Dual(const char *ifacename, unsigned int mode, uint64_t *nWlsMacMemorySize, uint64_t *nWlsPhyMemorySize, void** handle1);
  91
  92 //-------------------------------------------------------------------------------------------
  93 /** @ingroup wls_mod
  94  *
  95  *  @param[in]   h - handle of WLS interface to close
  96  *
  97  *  @return  0 - in case of success
  98  *
  99  *  @description
 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
 102  *
 103 **/
 104 //-------------------------------------------------------------------------------------------
 105 int WLS_Close(void* h);
 106
 107 //-------------------------------------------------------------------------------------------
 108 /** @ingroup wls_mod
 109  *
 110  *  @param[in]   h - handle of second WLS interface within same app to close
 111  *
 112  *  @return  0 - in case of success
 113  *
 114  *  @description
 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
 117  *
 118 **/
 119 //-------------------------------------------------------------------------------------------
 120 int WLS_Close1(void* h);
 121 //-------------------------------------------------------------------------------------------
 122 /** @ingroup wls_mod
 123  *
 124  *  @param[in]   h - handle of WLS interface to check status
 125  *
 126  *  @return  1 - in case of success
 127  *
 128  *  @description
 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)
 131  *
 132 **/
 133 //-------------------------------------------------------------------------------------------
 134 int WLS_Ready(void* h);
 135
 136 //-------------------------------------------------------------------------------------------
 137 /** @ingroup wls_mod
 138  *
 139  *  @param[in]   h - handle of second WLS interface within the same app to check status
 140  *
 141  *  @return  1 - in case of success
 142  *
 143  *  @description
 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)
 146  *
 147 **/
 148 //-------------------------------------------------------------------------------------------
 149 int WLS_Ready1(void* h);
 150 //-------------------------------------------------------------------------------------------
 151 /** @ingroup wls_mod
 152  *
 153  *  @param[in]   h    - handle of WLS interface
 154  *  @param[in]   size - size of memory block to allocate
 155  *
 156  *  @return  void*    - pointer to allocated memory block or NULL if no memory available
 157  *
 158  *  @description
 159  *  Function allocates memory block for data exchange shared memory. Memory block is backed
 160  *  by huge pages.
 161  *
 162 **/
 163 //-------------------------------------------------------------------------------------------
 164 void* WLS_Alloc(void* h, uint64_t size);
 165
 166 //-------------------------------------------------------------------------------------------
 167 /** @ingroup wls_mod
 168 *
 169 *  @param[in]   h    - handle of WLS interface
 170 *  @param[in]   pMsg - pointer to WLS memory
 171 *
 172 *  @return  0 - if operation is successful
 173 *
 174 *  @description
 175 *  Function frees memory block for data exchange shared memory. Memory block is backed
 176 *  by huge pages
 177 *
 178 **/
 179 //-------------------------------------------------------------------------------------------
 180 int WLS_Free(void* h, void* pMsg);
 181
 182 //-------------------------------------------------------------------------------------------
 183 /** @ingroup wls_mod
 184  *
 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
 191  *
 192  *  @return  0 - if successful
 193  *          -1 - if error
 194  *
 195  *  @description
 196  *  Function puts memory block (or group of blocks) allocated from WLS memory into interface
 197  *  for transfer to remote peer.
 198  *
 199 **/
 200 //-------------------------------------------------------------------------------------------
 201 int WLS_Put(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
 202
 203 //-------------------------------------------------------------------------------------------
 204 /** @ingroup wls_mod
 205  *
 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
 212  *
 213  *  @return  0 - if successful
 214  *          -1 - if error
 215  *
 216  *  @description
 217  *  Function puts memory block (or group of blocks) allocated from WLS memory into interface
 218  *  for transfer to remote peer.
 219  *
 220 **/
 221 //-------------------------------------------------------------------------------------------
 222 int WLS_Put1(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
 223 //-------------------------------------------------------------------------------------------
 224 /** @ingroup wls_mod
 225  *
 226  *  @param[in]   h    - handle of WLS interface
 227  *
 228  *  @return  number of blocks available
 229  *
 230  *  @description
 231  *  Function checks if there are memory blocks with data from remote peer and returns number of blocks
 232  *  available for "get" operation
 233  *
 234 **/
 235 //-------------------------------------------------------------------------------------------
 236 int WLS_Check(void* h);
 237
 238 //-------------------------------------------------------------------------------------------
 239 /** @ingroup wls_mod
 240  *
 241  *  @param[in]   h    - handle of second WLS interface within same app
 242  *
 243  *  @return  number of blocks available
 244  *
 245  *  @description
 246  *  Function checks if there are memory blocks with data from remote peer and returns number of blocks
 247  *  available for "get" operation
 248  *
 249 **/
 250 //-------------------------------------------------------------------------------------------
 251 int WLS_Check1(void* h);
 252
 253 //-------------------------------------------------------------------------------------------
 254 /** @ingroup wls_mod
 255 *
 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
 260 *
 261 *  @return  pointer to memory block (physical address) with data received from remote peer
 262 *           NULL -  if error
 263 *
 264 *  @description
 265 *  Function gets memory block from interface received from remote peer. Function is non-blocking
 266 *  operation and returns NULL if no blocks available
 267 *
 268 **/
 269 //-------------------------------------------------------------------------------------------
 270 unsigned long long WLS_Get(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 271
 272
 273 //-------------------------------------------------------------------------------------------
 274 /** @ingroup wls_mod
 275 *
 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
 280 *
 281 *  @return  pointer to memory block (physical address) with data received from remote peer
 282 *           NULL -  if error
 283 *
 284 *  @description
 285 *  Function gets memory block from interface received from remote peer. Function is non-blocking
 286 *  operation and returns NULL if no blocks available
 287 *
 288 **/
 289 //-------------------------------------------------------------------------------------------
 290 unsigned long long WLS_Get1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 291
 292 //-------------------------------------------------------------------------------------------
 293 /** @ingroup wls_mod
 294 *
 295 *  @param[in]   h    - handle of WLS interface
 296 *
 297 *  @return  number of blocks available for get
 298 *
 299 *  @description
 300 *  Function waits for new memory block from remote peer. Function is blocking call and returns number
 301 *  of blocks received.
 302 *
 303 **/
 304 //-------------------------------------------------------------------------------------------
 305 int WLS_Wait(void* h);
 306
 307 //-------------------------------------------------------------------------------------------
 308 /** @ingroup wls_mod
 309 *
 310 *  @param[in]   h    - handle second of WLS interface within same app
 311 *
 312 *  @return  number of blocks available for get
 313 *
 314 *  @description
 315 *  Function waits for new memory block from remote peer. Function is blocking call and returns number
 316 *  of blocks received.
 317 *
 318 **/
 319 //-------------------------------------------------------------------------------------------
 320 int WLS_Wait1(void* h);
 321
 322 //-------------------------------------------------------------------------------------------
 323 /** @ingroup wls_mod
 324 *
 325 *  @param[in]   h    - handle of WLS interface
 326 *
 327 *  @return  0 - if successful
 328 *
 329 *  @description
 330 *  Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
 331 *
 332 **/
 333 //-------------------------------------------------------------------------------------------
 334 int WLS_WakeUp(void* h);
 335
 336 //-------------------------------------------------------------------------------------------
 337 /** @ingroup wls_mod
 338 *
 339 *  @param[in]   h    - handle of second  WLS interface within same app
 340 *
 341 *  @return  0 - if successful
 342 *
 343 *  @description
 344 *  Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
 345 *
 346 **/
 347 //-------------------------------------------------------------------------------------------
 348 int WLS_WakeUp1(void* h);
 349 //-------------------------------------------------------------------------------------------
 350 /** @ingroup wls_mod
 351 *
 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
 356 *
 357 *  @return  pointer to memory block (physical address) with data received from remote peer
 358 *           NULL -  if error
 359 *
 360 *  @description
 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.
 363 *
 364 **/
 365 //-------------------------------------------------------------------------------------------
 366 unsigned long long WLS_WGet(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 367
 368 //-------------------------------------------------------------------------------------------
 369 /** @ingroup wls_mod
 370 *
 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
 375 *
 376 *  @return  pointer to memory block (physical address) with data received from remote peer
 377 *           NULL -  if error
 378 *
 379 *  @description
 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.
 382 *
 383 **/
 384 //-------------------------------------------------------------------------------------------
 385 unsigned long long WLS_WGet1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 386
 387 //-------------------------------------------------------------------------------------------
 388 /** @ingroup wls_mod
 389 *
 390 *  @param[in]   h    - handle of WLS interface
 391 *  @param[in]   pMsg - virtual address of WLS memory block.
 392 *
 393 *  @return  physical address of WLS memory block
 394 *           NULL - if error
 395 *
 396 *  @description
 397 *  Function converts virtual address (VA) to physical address (PA)
 398 *
 399 **/
 400 //-------------------------------------------------------------------------------------------
 401 unsigned long long WLS_VA2PA(void* h, void* pMsg);
 402
 403 //-------------------------------------------------------------------------------------------
 404 /** @ingroup wls_mod
 405 *
 406 *  @param[in]   h    - handle of WLS interface
 407 *  @param[in]   pMsg - physical address of WLS memory block.
 408 *
 409 *  @return  virtual address of WLS memory block
 410 *           NULL - if error
 411 *
 412 *  @description
 413 *  Function converts physical address (PA) to virtual address (VA)
 414 *
 415 **/
 416 //-------------------------------------------------------------------------------------------
 417 void* WLS_PA2VA(void* h, unsigned long long pMsg);
 418
 419 //-------------------------------------------------------------------------------------------
 420 /** @ingroup wls_mod
 421 *
 422 *  @param[in]   h    - handle of WLS interface
 423 *  @param[in]   pMsg - physical address of WLS memory block.
 424 *
 425 *  @return  0 - if successful
 426 *          -1 - if error
 427 *
 428 *  @description
 429 *  Function is used by master to provide memory blocks to slave for next slave to master transfer
 430 *  of data.
 431 *
 432 **/
 433 //-------------------------------------------------------------------------------------------
 434 int WLS_EnqueueBlock(void* h, unsigned long long pMsg);
 435
 436 //-------------------------------------------------------------------------------------------
 437 /** @ingroup wls_mod
 438 *
 439 *  @param[in]   h    -- handle of second WLS interface within the same app
 440 *  @param[in]   pMsg - physical address of WLS memory block.
 441 *
 442 *  @return  0 - if successful
 443 *          -1 - if error
 444 *
 445 *  @description
 446 *  Function is used by master to provide memory blocks to slave for next slave to master transfer
 447 *  of data.
 448 *
 449 **/
 450 //-------------------------------------------------------------------------------------------
 451 int WLS_EnqueueBlock1(void* h, unsigned long long pMsg);
 452
 453
 454 //-------------------------------------------------------------------------------------------
 455 /** @ingroup wls_mod
 456 *
 457 *  @param[in]   h    - handle of WLS interface
 458 *
 459 *  @return  0   - pointer (physical address) of WLS memory block
 460 *          NULL - if error
 461 *
 462 *  @description
 463 *  Function is used by master and slave to get block from master to slave queue of available memory
 464 *  blocks.
 465 *
 466 **/
 467 //-------------------------------------------------------------------------------------------
 468 unsigned long long WLS_DequeueBlock(void* h);
 469
 470 //-------------------------------------------------------------------------------------------
 471 /** @ingroup wls_mod
 472 *
 473 *  @param[in]   h    - handle of WLS interface
 474 *
 475 *  @return  number of blocks in slave to master queue
 476 *
 477 *  @description
 478 *  Function returns number of current available block provided by master for new transfer
 479 *  of data from slave.
 480 *
 481 **/
 482 //-------------------------------------------------------------------------------------------
 483 int WLS_NumBlocks(void* h);
 484
 485 #ifdef __cplusplus
 486 }
 487 #endif
 488 #endif //_WLS_LIB_H_