--- /dev/null
+/******************************************************************************
+*
+* Copyright (c) 2019 Intel.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*
+*******************************************************************************/
+
+#ifndef _WLS_LIB_H_
+#define _WLS_LIB_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** WLS driver client operates as slave in terms of management of shared memory */
+#define WLS_SLAVE_CLIENT 0
+/** WLS driver client operates as master in terms of management of shared memory */
+#define WLS_MASTER_CLIENT 1
+/** WLS Open Dual Options */
+#define WLS_SEC_NA 0
+#define WLS_SEC_MASTER 1
+/** WLS Open Dual enabled */
+#define WLS_SINGLE_MODE 0
+#define WLS_DUAL_MODE 1
+
+
+/* definitions PUT/GET Flags */
+#define WLS_TF_SCATTER_GATHER (1 << 15)
+#define WLS_TF_URLLC (1 << 10)
+#define WLS_TF_SYN (1 << 9)
+#define WLS_TF_FIN (1 << 8)
+#define WLS_FLAGS_MASK (0xFF00)
+
+/** First block in Scatter/Gather sequence of blocks */
+#define WLS_SG_FIRST (WLS_TF_SCATTER_GATHER | WLS_TF_SYN)
+/** Next block in Scatter/Gather sequence of blocks */
+#define WLS_SG_NEXT (WLS_TF_SCATTER_GATHER)
+/** Last block in Scatter/Gather sequence of blocks */
+#define WLS_SG_LAST (WLS_TF_SCATTER_GATHER | WLS_TF_FIN)
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
+ * @param[in] modef - mode of operation (Master or Slave)
+ *
+ * @return pointer to WLS handle
+ *
+ * @description
+ * Function opens the WLS interface and registers as instance in the kernel space driver.
+ * Control section of shared memory is mapped to application memory.
+ * pointer (handle) of WLS interface is returned for future use by WLS functions
+ *
+**/
+//-------------------------------------------------------------------------------------------
+void* WLS_Open(const char *ifacename, unsigned int mode, unsigned long long nWlsMemorySize);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] ifacename - pointer to string with device driver name (/dev/wls)
+ * @param[in] modef - mode of operation (Master or Slave)
+ *
+ * @return pointer to second WLS handle while first WLS_handle is returned to the argument handle1 location
+ *
+ * @description
+ * Function opens the WLS interface and registers two instances in the kernel space driver.
+ * Control section of shared memory is mapped to application memory.
+ * pointer (handle) of WLS interface is returned for future use by WLS functions
+ *
+**/
+//-------------------------------------------------------------------------------------------
+void* WLS_Open_Dual(const char *ifacename, unsigned int mode, unsigned long long nWlsMemorySize, void** handle1);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of WLS interface to close
+ *
+ * @return 0 - in case of success
+ *
+ * @description
+ * Function closes the WLS interface and deregisters as instance in the kernel space driver.
+ * Control section of shared memory is unmapped form user space application
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Close(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of second WLS interface within same app to close
+ *
+ * @return 0 - in case of success
+ *
+ * @description
+ * Function closes a second WLS interface open from a same process and deregisters as instance in the kernel space driver.
+ * Control section of shared memory is unmapped form user space application
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Close1(void* h);
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of WLS interface to check status
+ *
+ * @return 1 - in case of success
+ *
+ * @description
+ * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
+ * (one to one connection is established)
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Ready(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of second WLS interface within the same app to check status
+ *
+ * @return 1 - in case of success
+ *
+ * @description
+ * Function checks state of remote peer of WLS interface and returns 1 if remote peer is available
+ * (one to one connection is established)
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Ready1(void* h);
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of WLS interface
+ * @param[in] size - size of memory block to allocate
+ *
+ * @return void* - pointer to allocated memory block or NULL if no memory available
+ *
+ * @description
+ * Function allocates memory block for data exchange shared memory. Memory block is backed
+ * by huge pages.
+ *
+**/
+//-------------------------------------------------------------------------------------------
+void* WLS_Alloc(void* h, unsigned int size);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+* @param[in] pMsg - pointer to WLS memory
+*
+* @return 0 - if operation is successful
+*
+* @description
+* Function frees memory block for data exchange shared memory. Memory block is backed
+* by huge pages
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Free(void* h, void* pMsg);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of WLS interface
+ * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
+ * pointer should belong to WLS memory allocated via WLS_Alloc()
+ * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
+ * @param[in] MsgTypeID - application specific identifier of message type
+ * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
+ *
+ * @return 0 - if successful
+ * -1 - if error
+ *
+ * @description
+ * Function puts memory block (or group of blocks) allocated from WLS memory into interface
+ * for transfer to remote peer.
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Put(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of second WLS interface within same app
+ * @param[in] pMsg - pointer to memory block (physical address) with data to be transfered to remote peer.
+ * pointer should belong to WLS memory allocated via WLS_Alloc()
+ * @param[in] MsgSize - size of memory block to send (should be less than 2 MB)
+ * @param[in] MsgTypeID - application specific identifier of message type
+ * @param[in] Flags - Scatter/Gather flag if memory block has multiple chunks
+ *
+ * @return 0 - if successful
+ * -1 - if error
+ *
+ * @description
+ * Function puts memory block (or group of blocks) allocated from WLS memory into interface
+ * for transfer to remote peer.
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Put1(void* h, unsigned long long pMsg, unsigned int MsgSize, unsigned short MsgTypeID, unsigned short Flags);
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of WLS interface
+ *
+ * @return number of blocks available
+ *
+ * @description
+ * Function checks if there are memory blocks with data from remote peer and returns number of blocks
+ * available for "get" operation
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Check(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+ *
+ * @param[in] h - handle of second WLS interface within same app
+ *
+ * @return number of blocks available
+ *
+ * @description
+ * Function checks if there are memory blocks with data from remote peer and returns number of blocks
+ * available for "get" operation
+ *
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Check1(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+* @param[in] *MsgSize - pointer to set size of memory block
+* @param[in] *MsgTypeID - pointer to application specific identifier of message type
+* @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
+*
+* @return pointer to memory block (physical address) with data received from remote peer
+* NULL - if error
+*
+* @description
+* Function gets memory block from interface received from remote peer. Function is non-blocking
+* operation and returns NULL if no blocks available
+*
+**/
+//-------------------------------------------------------------------------------------------
+unsigned long long WLS_Get(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
+
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of second WLS interface within same app
+* @param[in] *MsgSize - pointer to set size of memory block
+* @param[in] *MsgTypeID - pointer to application specific identifier of message type
+* @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
+*
+* @return pointer to memory block (physical address) with data received from remote peer
+* NULL - if error
+*
+* @description
+* Function gets memory block from interface received from remote peer. Function is non-blocking
+* operation and returns NULL if no blocks available
+*
+**/
+//-------------------------------------------------------------------------------------------
+unsigned long long WLS_Get1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+*
+* @return number of blocks available for get
+*
+* @description
+* Function waits for new memory block from remote peer. Function is blocking call and returns number
+* of blocks received.
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Wait(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle second of WLS interface within same app
+*
+* @return number of blocks available for get
+*
+* @description
+* Function waits for new memory block from remote peer. Function is blocking call and returns number
+* of blocks received.
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_Wait1(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+*
+* @return 0 - if successful
+*
+* @description
+* Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_WakeUp(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of second WLS interface within same app
+*
+* @return 0 - if successful
+*
+* @description
+* Function performs "wakeup" notification to remote peer to unblock "wait" operations pending
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_WakeUp1(void* h);
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+* @param[in] *MsgSize - pointer to set size of memory block
+* @param[in] *MsgTypeID - pointer to application specific identifier of message type
+* @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
+*
+* @return pointer to memory block (physical address) with data received from remote peer
+* NULL - if error
+*
+* @description
+* Function gets memory block from interface received from remote peer. Function is blocking
+* operation and waits till next memory block from remote peer.
+*
+**/
+//-------------------------------------------------------------------------------------------
+unsigned long long WLS_WGet(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of second WLS interface within the same app
+* @param[in] *MsgSize - pointer to set size of memory block
+* @param[in] *MsgTypeID - pointer to application specific identifier of message type
+* @param[in] *Flags - pointer to Scatter/Gather flag if memory block has multiple chunks
+*
+* @return pointer to memory block (physical address) with data received from remote peer
+* NULL - if error
+*
+* @description
+* Function gets memory block from interface received from remote peer. Function is blocking
+* operation and waits till next memory block from remote peer.
+*
+**/
+//-------------------------------------------------------------------------------------------
+unsigned long long WLS_WGet1(void* h, unsigned int *MsgSize, unsigned short *MsgTypeID, unsigned short *Flags);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+* @param[in] pMsg - virtual address of WLS memory block.
+*
+* @return physical address of WLS memory block
+* NULL - if error
+*
+* @description
+* Function converts virtual address (VA) to physical address (PA)
+*
+**/
+//-------------------------------------------------------------------------------------------
+unsigned long long WLS_VA2PA(void* h, void* pMsg);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+* @param[in] pMsg - physical address of WLS memory block.
+*
+* @return virtual address of WLS memory block
+* NULL - if error
+*
+* @description
+* Function converts physical address (PA) to virtual address (VA)
+*
+**/
+//-------------------------------------------------------------------------------------------
+void* WLS_PA2VA(void* h, unsigned long long pMsg);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+* @param[in] pMsg - physical address of WLS memory block.
+*
+* @return 0 - if successful
+* -1 - if error
+*
+* @description
+* Function is used by master to provide memory blocks to slave for next slave to master transfer
+* of data.
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_EnqueueBlock(void* h, unsigned long long pMsg);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h -- handle of second WLS interface within the same app
+* @param[in] pMsg - physical address of WLS memory block.
+*
+* @return 0 - if successful
+* -1 - if error
+*
+* @description
+* Function is used by master to provide memory blocks to slave for next slave to master transfer
+* of data.
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_EnqueueBlock1(void* h, unsigned long long pMsg);
+
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+*
+* @return 0 - pointer (physical address) of WLS memory block
+* NULL - if error
+*
+* @description
+* Function is used by master and slave to get block from master to slave queue of available memory
+* blocks.
+*
+**/
+//-------------------------------------------------------------------------------------------
+unsigned long long WLS_DequeueBlock(void* h);
+
+//-------------------------------------------------------------------------------------------
+/** @ingroup wls_mod
+*
+* @param[in] h - handle of WLS interface
+*
+* @return number of blocks in slave to master queue
+*
+* @description
+* Function returns number of current available block provided by master for new transfer
+* of data from slave.
+*
+**/
+//-------------------------------------------------------------------------------------------
+int WLS_NumBlocks(void* h);
+
+#ifdef __cplusplus
+}
+#endif
+#endif //_WLS_LIB_H_
Code Review / o-du / phy.git / blobdiff