source: trunk/kernel/libk/remote_buf.h @ 666

Last change on this file since 666 was 666, checked in by alain, 4 years ago

Cosmetic.
File size: 8.9 KB
Line 
1/*
2 * remote_buf.h -  Remotely accessible, circular buffer definition.
3 *
4 * Authors :
5 *           Alain Greiner (2016,2017,2018,2019,2020)
6 *
7 * Copyright (c) UPMC Sorbonne Universites
8 *
9 * This file is part of ALMOS-MKH.
10 *
11 * ALMOS-MHH is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; version 2.0 of the License.
14 *
15 * ALMOS-MKH is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 * General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23 */
24
25#ifndef _REMOTE_BUFFER_H_
26#define _REMOTE_BUFFER_H_
27
28#include <kernel_config.h>
29#include <hal_kernel_types.h>
30
31/************************************************************************************
32 * This structure and the associated access functions define a remotely accessible,
33 * kernel buffer, handled as a single-reader & single-writer FIFO.
34 * This kernel buffer is implementes as an array of bytes, whose size is
35 * dynamically defined by an argument of the "remote_buf_init()" function.
36 * The "put()" and "get()" functions defined below move the content of another
37 * buffer (can be in kernel or in user space) to/from this circular kernel buffer.
38 * This structure is NOT protected by a lock, as the only shared variable is the
39 * "sts" variable, that is updated by the hal_remote_atomic_add() primitive.
40 * It is used to implement the three socket buffers (rx_buf / r2tq / crqq).
41 * - the "ptw" field defines the first empty slot (for write).
42 * - the "ptr" field defines the first non empty slot (for read).
43 * - the "sts" field defines the total number of non empty slots.
44 ***********************************************************************************/
45
46typedef struct remote_buf_s
47{
48    uint32_t   size;    /*! number of slots in data buffer                         */
49        uint32_t   ptw;     /*! first empty slot index                                 */
50        uint32_t   ptr;     /*! first non-empty slot index                             */
51    uint32_t   sts;     /*! current number of non empty slots                      */
52        uint8_t  * data;    /*! local pointer on local data buffer                     */
53}
54remote_buf_t;
55
56/************************************************************************************
57 * This function initializes a remote_buf descriptor identified by the <buf_xp>
58 * argument. It allocates memory for the data, as defined by the <size> argument,
59 * and initializes the buffer as empty. It must be called by a local thread.
60 * No memory is allocated if <size> value is 0.
61 ************************************************************************************
62 * @ buf_xp    : [in] extended pointer on buffer descriptor.
63 * @ size      : [in] number of bytes in buffer / no memory allocated when null.
64 * @ return  0 if success / return -1 if memory failure.
65 ***********************************************************************************/
66error_t remote_buf_init( xptr_t   buf_xp,
67                         uint32_t size );
68
69/************************************************************************************
70 * This function releases memory allocated for the data buffer of a remote-buf
71 * descriptor identified by the <buf_xp> argument.
72 * It must be called by a local thread.
73 ************************************************************************************
74 * @ buf_xp      : [in] extended pointer on buffer descriptor.
75 ***********************************************************************************/
76void remote_buf_destroy( xptr_t buf_xp );
77
78/************************************************************************************
79 * This function initialises as empty a buffer identified by the <buf_xp> argument.
80 * It can be called by a thread runing in any cluster.
81 ************************************************************************************
82 * @ buf_xp    : [in] extended pointer on remote buffer descriptor.
83 ***********************************************************************************/
84void remote_buf_reset( xptr_t buf_xp );
85
86/************************************************************************************
87 * This function moves <nbytes> from a remote_buf_t identified by the <buf_xp>
88 * argument to an user buffer identified by the <u_buf> argument.
89 * It uses the hal_copy_to_uspace() function, and updates "sts" and "ptr".
90 * The calling function is supposed to previously check the buffer status.
91 * It can be called by a thread runing in any cluster.
92 ************************************************************************************
93 * @ buf_xp    : [in] extended pointer pointer on remote buffer descriptor.
94 * @ u_buf     : [in] pointer on destination user buffer in user space.
95 * @ nbytes    : [in] number of bytes to move.
96 * @ return 0 if success / return -1 if not enough bytes in buffer.
97 ***********************************************************************************/
98error_t remote_buf_get_to_user( xptr_t    buf_xp,
99                                uint8_t * u_buf,
100                                uint32_t  nbytes );
101
102/************************************************************************************
103 * This function moves <nbytes> from a remote_buf_t identified by the <buf_xp>
104 * argument to a local kernel buffer identified by the <k_buf> argument.
105 * It uses an hal_remote_memcpy() function, and updates the "sts" and "ptr" fields.
106 * The calling function is supposed to previously check the buffer status.
107 * It can be called by a thread runing in any cluster.
108 ************************************************************************************
109 * @ buf_xp    : [in] extended pointer pointer on remote buffer descriptor.
110 * @ k_buf     : [in] local pointer on local destination kernel buffer.
111 * @ nbytes    : [in] number of bytes to move.
112 * @ return 0 if success / return -1 if not enough bytes in buffer.
113 ***********************************************************************************/
114error_t remote_buf_get_to_kernel( xptr_t    buf_xp,
115                                  uint8_t * k_buf,
116                                  uint32_t  nbytes );
117
118/************************************************************************************
119 * This function moves <nbytes> from an user buffer identified by the <u_buf>
120 * argument to a remote_buf_t identified by the <buf_xp> argument.
121 * It uses the hal_copy_from_uspace() function, and updates "sts" and "ptw"..
122 * The calling function is supposed to previously check the buffer status.
123 * It can be called by a thread runing in any cluster.
124 ************************************************************************************
125 * @ buf_xp    : [in] extended pointer pointer on remote buffer descriptor.
126 * @ u_buf     : [in] pointer on source user buffer in user space.
127 * @ nbytes    : [in] number of bytes to move.
128 * @ return 0 if success / return -1 if not enough bytes in buffer.
129 ***********************************************************************************/
130error_t remote_buf_put_from_user( xptr_t    buf_xp,
131                                  uint8_t * u_buf,
132                                  uint32_t  nbytes );
133
134/************************************************************************************
135 * This function moves <nbytes> from a local kernel buffer identified by the <k_buf>
136 * argument to a remote_buf_t identified by the <buf_xp> argument.
137 * It uses an hal_remote_memcpy() function, and updates the "sts" and "ptw" fields.
138 * The calling function is supposed to previously check the buffer status.
139 * It can be called by a thread runing in any cluster.
140 ************************************************************************************
141 * @ buf_xp    : [in] extended pointer pointer on remote buffer descriptor.
142 * @ k_buf     : [in] local pointer on local source kernel buffer.
143 * @ nbytes    : [in] number of bytes to move.
144 * @ return 0 if success / return -1 if not enough bytes in buffer.
145 ***********************************************************************************/
146error_t remote_buf_put_from_kernel( xptr_t    buf_xp,
147                                    uint8_t * k_buf,
148                                    uint32_t  nbytes );
149
150/************************************************************************************
151 * This function returns the current number of bytes stored in buffer.
152 ************************************************************************************
153 * @ buf_xp    : [in] extended pointer pointer on remote buffer descriptor.
154 * @ return current number of bytes in buffer.
155 ***********************************************************************************/
156uint32_t remote_buf_status( xptr_t  buf_xp );
157
158#endif  /* _REMOTE_BUFFER_H_ */
Note: See TracBrowser for help on using the repository browser.