X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?p=o-du%2Fphy.git;a=blobdiff_plain;f=wls_lib%2Fwls_lib.h;fp=wls_lib%2Fwls_lib.h;h=e38ea43f2a45631e93477a26de1bc2705d68edef;hp=0000000000000000000000000000000000000000;hb=9d66fca5c45c8b3e0d6eab6d51a90c8e9d2614dc;hpb=2fbf70096f64af622da983e88c5a64e90ad9bdbd diff --git a/wls_lib/wls_lib.h b/wls_lib/wls_lib.h new file mode 100644 index 0000000..e38ea43 --- /dev/null +++ b/wls_lib/wls_lib.h @@ -0,0 +1,482 @@ +/****************************************************************************** +* +* 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_