/* * remote_buf.h - Remotely accessible, circular buffer definition. * * Authors : * Alain Greiner (2016,2017,2018,2019,2020) * * Copyright (c) UPMC Sorbonne Universites * * This file is part of ALMOS-MKH. * * ALMOS-MHH is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by * the Free Software Foundation; version 2.0 of the License. * * ALMOS-MKH is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with ALMOS-MKH; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef _REMOTE_BUFFER_H_ #define _REMOTE_BUFFER_H_ #include #include /************************************************************************************ * This structure and the associated access functions define a remotely accessible, * kernel buffer, handled as a single-reader & single-writer FIFO. * Each buffer slot contains one byte, and the number of slots is dynamically * defined by an argument of the "remote_buf_create()" function. * The "put()" and "get()" access functions defined below move another buffer, * (can be in kernel or in user space) to/from this circular kernel buffer. * This structure is NOT protected by a lock, as the only shared variable is the * "sts" variable, that is updated by hal_remote_atomic_add() access primitives. * It is used by to implement the socket receive buffer. * - the "ptw" field defines the first empty slot (for write). * - the "ptr" field defines the first non empty slot (for read). * - the "sts" field defines the total number of non empty slots. ***********************************************************************************/ typedef struct remote_buf_s { uint32_t size; /*! number of slots in data buffer */ uint32_t ptw; /*! first empty slot index */ uint32_t ptr; /*! first non-empty slot index */ uint32_t sts; /*! current number of non empty slots */ uint8_t * data; /*! local pointer on local data buffer */ } remote_buf_t; /************************************************************************************ * This function initializes a remote_buf descriptor identified by the * argument. It allocates memory for the data, as defined by the argument, * and initializes the buffer as empty. It must be called by a local thread. ************************************************************************************ * @ buf_xp : [in] extended pointer on buffer descriptor. * @ size : [in] number of bytes in buffer. * @ return 0 if success / return -1 if failure (no memory). ***********************************************************************************/ error_t remote_buf_create( xptr_t buf_xp, uint32_t size ); /************************************************************************************ * This function releases memory allocated for the data buffer of a remote-buf * descriptor identified by the argument. * It must be called by a local thread. ************************************************************************************ * @ buf_xp : [in] extended pointer on buffer descriptor. ***********************************************************************************/ void remote_buf_destroy( xptr_t buf_xp ); /************************************************************************************ * This function initialises as empty a buffer identified by the argument. * It can be called by a thread runing in any cluster. ************************************************************************************ * @ buf_xp : [in] extended pointer on remote buffer descriptor. ***********************************************************************************/ void remote_buf_reset( xptr_t buf_xp ); /************************************************************************************ * This function moves from a remote_buf_t identified by the * argument to an user buffer identified by the argument. * It uses the hal_copy_to_uspace() function, and updates "sts" and "ptr". * The calling function is supposed to previously check the buffer status. * It can be called by a thread runing in any cluster. ************************************************************************************ * @ buf_xp : [in] extended pointer pointer on remote buffer descriptor. * @ u_buf : [in] pointer on destination user buffer in user space. * @ nbytes : [in] number of bytes to move. * @ return 0 if success / return -1 if not enough bytes in buffer. ***********************************************************************************/ error_t remote_buf_get_to_user( xptr_t buf_xp, uint8_t * u_buf, uint32_t nbytes ); /************************************************************************************ * This function moves from a remote_buf_t identified by the * argument to a local kernel buffer identified by the argument. * It uses an hal_remote_memcpy() function, and updates the "sts" and "ptr" fields. * The calling function is supposed to previously check the buffer status. * It can be called by a thread runing in any cluster. ************************************************************************************ * @ buf_xp : [in] extended pointer pointer on remote buffer descriptor. * @ k_buf : [in] local pointer on local destination kernel buffer. * @ nbytes : [in] number of bytes to move. * @ return 0 if success / return -1 if not enough bytes in buffer. ***********************************************************************************/ error_t remote_buf_get_to_kernel( xptr_t buf_xp, uint8_t * k_buf, uint32_t nbytes ); /************************************************************************************ * This function moves from an user buffer identified by the * argument to a remote_buf_t identified by the argument. * It uses the hal_copy_from_uspace() function, and updates "sts" and "ptw".. * The calling function is supposed to previously check the buffer status. * It can be called by a thread runing in any cluster. ************************************************************************************ * @ buf_xp : [in] extended pointer pointer on remote buffer descriptor. * @ u_buf : [in] pointer on source user buffer in user space. * @ nbytes : [in] number of bytes to move. * @ return 0 if success / return -1 if not enough bytes in buffer. ***********************************************************************************/ error_t remote_buf_put_from_user( xptr_t buf_xp, uint8_t * u_buf, uint32_t nbytes ); /************************************************************************************ * This function moves from a local kernel buffer identified by the * argument to a remote_buf_t identified by the argument. * It uses an hal_remote_memcpy() function, and updates the "sts" and "ptw" fields. * The calling function is supposed to previously check the buffer status. * It can be called by a thread runing in any cluster. ************************************************************************************ * @ buf_xp : [in] extended pointer pointer on remote buffer descriptor. * @ k_buf : [in] local pointer on local source kernel buffer. * @ nbytes : [in] number of bytes to move. * @ return 0 if success / return -1 if not enough bytes in buffer. ***********************************************************************************/ error_t remote_buf_put_from_kernel( xptr_t buf_xp, uint8_t * k_buf, uint32_t nbytes ); /************************************************************************************ * This function returns the current number of bytes stored in buffer. ************************************************************************************ * @ buf_xp : [in] extended pointer pointer on remote buffer descriptor. * @ return current number of bytes in buffer. ***********************************************************************************/ uint32_t remote_buf_status( xptr_t buf_xp ); #endif /* _REMOTE_BUFFER_H_ */