wls_lib/wls_lib.h

   1 /******************************************************************************
   2 *
   3 *   Copyright (c) 2019 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 /** 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 */
  31 #define WLS_SEC_NA     0
  32 #define WLS_SEC_MASTER 1
  33 /** WLS Open Dual enabled */
  34 #define WLS_SINGLE_MODE 0
  35 #define WLS_DUAL_MODE   1
  36
  37
  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)
  44
  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)
  51
  52 //-------------------------------------------------------------------------------------------
  53 /** @ingroup wls_mod
  54  *
  55  *  @param[in]   ifacename - pointer to string with device driver name (/dev/wls)
  56  *  @param[in]   modef     - mode of operation (Master or Slave)
  57  *
  58  *  @return  pointer to WLS handle
  59  *
  60  *  @description
  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
  64  *
  65 **/
  66 //-------------------------------------------------------------------------------------------
  67 void* WLS_Open(const char *ifacename, unsigned int mode, unsigned long long nWlsMemorySize);
  68
  69 //-------------------------------------------------------------------------------------------
  70 /** @ingroup wls_mod
  71  *
  72  *  @param[in]   ifacename - pointer to string with device driver name (/dev/wls)
  73  *  @param[in]   modef     - mode of operation (Master or Slave)
  74  *
  75  *  @return  pointer to second WLS handle while first WLS_handle is returned to the argument handle1 location
  76  *
  77  *  @description
  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
  81  *
  82 **/
  83 //-------------------------------------------------------------------------------------------
  84 void* WLS_Open_Dual(const char *ifacename, unsigned int mode, unsigned long long nWlsMemorySize, void** handle1);
  85
  86 //-------------------------------------------------------------------------------------------
  87 /** @ingroup wls_mod
  88  *
  89  *  @param[in]   h - handle of WLS interface to close
  90  *
  91  *  @return  0 - in case of success
  92  *
  93  *  @description
  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
  96  *
  97 **/
  98 //-------------------------------------------------------------------------------------------
  99 int WLS_Close(void* h);
 100
 101 //-------------------------------------------------------------------------------------------
 102 /** @ingroup wls_mod
 103  *
 104  *  @param[in]   h - handle of second WLS interface within same app to close
 105  *
 106  *  @return  0 - in case of success
 107  *
 108  *  @description
 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
 111  *
 112 **/
 113 //-------------------------------------------------------------------------------------------
 114 int WLS_Close1(void* h);
 115 //-------------------------------------------------------------------------------------------
 116 /** @ingroup wls_mod
 117  *
 118  *  @param[in]   h - handle of WLS interface to check status
 119  *
 120  *  @return  1 - in case of success
 121  *
 122  *  @description
 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)
 125  *
 126 **/
 127 //-------------------------------------------------------------------------------------------
 128 int WLS_Ready(void* h);
 129
 130 //-------------------------------------------------------------------------------------------
 131 /** @ingroup wls_mod
 132  *
 133  *  @param[in]   h - handle of second WLS interface within the same app to check status
 134  *
 135  *  @return  1 - in case of success
 136  *
 137  *  @description
 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)
 140  *
 141 **/
 142 //-------------------------------------------------------------------------------------------
 143 int WLS_Ready1(void* h);
 144 //-------------------------------------------------------------------------------------------
 145 /** @ingroup wls_mod
 146  *
 147  *  @param[in]   h    - handle of WLS interface
 148  *  @param[in]   size - size of memory block to allocate
 149  *
 150  *  @return  void*    - pointer to allocated memory block or NULL if no memory available
 151  *
 152  *  @description
 153  *  Function allocates memory block for data exchange shared memory. Memory block is backed
 154  *  by huge pages.
 155  *
 156 **/
 157 //-------------------------------------------------------------------------------------------
 158 void* WLS_Alloc(void* h, unsigned int size);
 159
 160 //-------------------------------------------------------------------------------------------
 161 /** @ingroup wls_mod
 162 *
 163 *  @param[in]   h    - handle of WLS interface
 164 *  @param[in]   pMsg - pointer to WLS memory
 165 *
 166 *  @return  0 - if operation is successful
 167 *
 168 *  @description
 169 *  Function frees memory block for data exchange shared memory. Memory block is backed
 170 *  by huge pages
 171 *
 172 **/
 173 //-------------------------------------------------------------------------------------------
 174 int WLS_Free(void* h, void* pMsg);
 175
 176 //-------------------------------------------------------------------------------------------
 177 /** @ingroup wls_mod
 178  *
 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
 185  *
 186  *  @return  0 - if successful
 187  *          -1 - if error
 188  *
 189  *  @description
 190  *  Function puts memory block (or group of blocks) allocated from WLS memory into interface
 191  *  for transfer to remote peer.
 192  *
 193 **/
 194 //-------------------------------------------------------------------------------------------
 195 int WLS_Put(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
 196
 197 //-------------------------------------------------------------------------------------------
 198 /** @ingroup wls_mod
 199  *
 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
 206  *
 207  *  @return  0 - if successful
 208  *          -1 - if error
 209  *
 210  *  @description
 211  *  Function puts memory block (or group of blocks) allocated from WLS memory into interface
 212  *  for transfer to remote peer.
 213  *
 214 **/
 215 //-------------------------------------------------------------------------------------------
 216 int WLS_Put1(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
 217 //-------------------------------------------------------------------------------------------
 218 /** @ingroup wls_mod
 219  *
 220  *  @param[in]   h    - handle of WLS interface
 221  *
 222  *  @return  number of blocks available
 223  *
 224  *  @description
 225  *  Function checks if there are memory blocks with data from remote peer and returns number of blocks
 226  *  available for "get" operation
 227  *
 228 **/
 229 //-------------------------------------------------------------------------------------------
 230 int WLS_Check(void* h);
 231
 232 //-------------------------------------------------------------------------------------------
 233 /** @ingroup wls_mod
 234  *
 235  *  @param[in]   h    - handle of second WLS interface within same app
 236  *
 237  *  @return  number of blocks available
 238  *
 239  *  @description
 240  *  Function checks if there are memory blocks with data from remote peer and returns number of blocks
 241  *  available for "get" operation
 242  *
 243 **/
 244 //-------------------------------------------------------------------------------------------
 245 int WLS_Check1(void* h);
 246
 247 //-------------------------------------------------------------------------------------------
 248 /** @ingroup wls_mod
 249 *
 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
 254 *
 255 *  @return  pointer to memory block (physical address) with data received from remote peer
 256 *           NULL -  if error
 257 *
 258 *  @description
 259 *  Function gets memory block from interface received from remote peer. Function is non-blocking
 260 *  operation and returns NULL if no blocks available
 261 *
 262 **/
 263 //-------------------------------------------------------------------------------------------
 264 unsigned long long WLS_Get(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 265
 266
 267 //-------------------------------------------------------------------------------------------
 268 /** @ingroup wls_mod
 269 *
 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
 274 *
 275 *  @return  pointer to memory block (physical address) with data received from remote peer
 276 *           NULL -  if error
 277 *
 278 *  @description
 279 *  Function gets memory block from interface received from remote peer. Function is non-blocking
 280 *  operation and returns NULL if no blocks available
 281 *
 282 **/
 283 //-------------------------------------------------------------------------------------------
 284 unsigned long long WLS_Get1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 285
 286 //-------------------------------------------------------------------------------------------
 287 /** @ingroup wls_mod
 288 *
 289 *  @param[in]   h    - handle of WLS interface
 290 *
 291 *  @return  number of blocks available for get
 292 *
 293 *  @description
 294 *  Function waits for new memory block from remote peer. Function is blocking call and returns number
 295 *  of blocks received.
 296 *
 297 **/
 298 //-------------------------------------------------------------------------------------------
 299 int WLS_Wait(void* h);
 300
 301 //-------------------------------------------------------------------------------------------
 302 /** @ingroup wls_mod
 303 *
 304 *  @param[in]   h    - handle second of WLS interface within same app
 305 *
 306 *  @return  number of blocks available for get
 307 *
 308 *  @description
 309 *  Function waits for new memory block from remote peer. Function is blocking call and returns number
 310 *  of blocks received.
 311 *
 312 **/
 313 //-------------------------------------------------------------------------------------------
 314 int WLS_Wait1(void* h);
 315
 316 //-------------------------------------------------------------------------------------------
 317 /** @ingroup wls_mod
 318 *
 319 *  @param[in]   h    - handle of WLS interface
 320 *
 321 *  @return  0 - if successful
 322 *
 323 *  @description
 324 *  Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
 325 *
 326 **/
 327 //-------------------------------------------------------------------------------------------
 328 int WLS_WakeUp(void* h);
 329
 330 //-------------------------------------------------------------------------------------------
 331 /** @ingroup wls_mod
 332 *
 333 *  @param[in]   h    - handle of second  WLS interface within same app
 334 *
 335 *  @return  0 - if successful
 336 *
 337 *  @description
 338 *  Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
 339 *
 340 **/
 341 //-------------------------------------------------------------------------------------------
 342 int WLS_WakeUp1(void* h);
 343 //-------------------------------------------------------------------------------------------
 344 /** @ingroup wls_mod
 345 *
 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
 350 *
 351 *  @return  pointer to memory block (physical address) with data received from remote peer
 352 *           NULL -  if error
 353 *
 354 *  @description
 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.
 357 *
 358 **/
 359 //-------------------------------------------------------------------------------------------
 360 unsigned long long WLS_WGet(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 361
 362 //-------------------------------------------------------------------------------------------
 363 /** @ingroup wls_mod
 364 *
 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
 369 *
 370 *  @return  pointer to memory block (physical address) with data received from remote peer
 371 *           NULL -  if error
 372 *
 373 *  @description
 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.
 376 *
 377 **/
 378 //-------------------------------------------------------------------------------------------
 379 unsigned long long WLS_WGet1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
 380
 381 //-------------------------------------------------------------------------------------------
 382 /** @ingroup wls_mod
 383 *
 384 *  @param[in]   h    - handle of WLS interface
 385 *  @param[in]   pMsg - virtual address of WLS memory block.
 386 *
 387 *  @return  physical address of WLS memory block
 388 *           NULL - if error
 389 *
 390 *  @description
 391 *  Function converts virtual address (VA) to physical address (PA)
 392 *
 393 **/
 394 //-------------------------------------------------------------------------------------------
 395 unsigned long long WLS_VA2PA(void* h, void* pMsg);
 396
 397 //-------------------------------------------------------------------------------------------
 398 /** @ingroup wls_mod
 399 *
 400 *  @param[in]   h    - handle of WLS interface
 401 *  @param[in]   pMsg - physical address of WLS memory block.
 402 *
 403 *  @return  virtual address of WLS memory block
 404 *           NULL - if error
 405 *
 406 *  @description
 407 *  Function converts physical address (PA) to virtual address (VA)
 408 *
 409 **/
 410 //-------------------------------------------------------------------------------------------
 411 void* WLS_PA2VA(void* h, unsigned long long pMsg);
 412
 413 //-------------------------------------------------------------------------------------------
 414 /** @ingroup wls_mod
 415 *
 416 *  @param[in]   h    - handle of WLS interface
 417 *  @param[in]   pMsg - physical address of WLS memory block.
 418 *
 419 *  @return  0 - if successful
 420 *          -1 - if error
 421 *
 422 *  @description
 423 *  Function is used by master to provide memory blocks to slave for next slave to master transfer
 424 *  of data.
 425 *
 426 **/
 427 //-------------------------------------------------------------------------------------------
 428 int WLS_EnqueueBlock(void* h, unsigned long long pMsg);
 429
 430 //-------------------------------------------------------------------------------------------
 431 /** @ingroup wls_mod
 432 *
 433 *  @param[in]   h    -- handle of second WLS interface within the same app
 434 *  @param[in]   pMsg - physical address of WLS memory block.
 435 *
 436 *  @return  0 - if successful
 437 *          -1 - if error
 438 *
 439 *  @description
 440 *  Function is used by master to provide memory blocks to slave for next slave to master transfer
 441 *  of data.
 442 *
 443 **/
 444 //-------------------------------------------------------------------------------------------
 445 int WLS_EnqueueBlock1(void* h, unsigned long long pMsg);
 446
 447
 448 //-------------------------------------------------------------------------------------------
 449 /** @ingroup wls_mod
 450 *
 451 *  @param[in]   h    - handle of WLS interface
 452 *
 453 *  @return  0   - pointer (physical address) of WLS memory block
 454 *          NULL - if error
 455 *
 456 *  @description
 457 *  Function is used by master and slave to get block from master to slave queue of available memory
 458 *  blocks.
 459 *
 460 **/
 461 //-------------------------------------------------------------------------------------------
 462 unsigned long long WLS_DequeueBlock(void* h);
 463
 464 //-------------------------------------------------------------------------------------------
 465 /** @ingroup wls_mod
 466 *
 467 *  @param[in]   h    - handle of WLS interface
 468 *
 469 *  @return  number of blocks in slave to master queue
 470 *
 471 *  @description
 472 *  Function returns number of current available block provided by master for new transfer
 473 *  of data from slave.
 474 *
 475 **/
 476 //-------------------------------------------------------------------------------------------
 477 int WLS_NumBlocks(void* h);
 478
 479 #ifdef __cplusplus
 480 }
 481 #endif
 482 #endif //_WLS_LIB_H_