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