source: trunk/kernel/libk/remote_fifo.h @ 51

Last change on this file since 51 was 14, checked in by alain, 7 years ago

Bugs fix.

File size: 5.9 KB
Line 
1/*
2 * remote_fifo.h - kernel generic SRMW FIFO
3 *
4 * Authors : Mohamed Lamine Karaoui / Alain Greiner (2016)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MHH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _REMOTE_FIFO_H_
25#define _REMOTE_FIFO_H_
26
27#include <kernel_config.h>
28#include <hal_types.h>
29#include <errno.h>
30#include <hal_remote.h>
31
32/************************************************************************************
33 * This structure defines a generic, single reader, multiple writers
34 * remote FIFO, that is used by the RPCs for inter cluster communications.
35 * The accesses are implemented using a lock-free algorithm, as it
36 * uses a ticket based mechanism to handle concurrent access between
37 * the multiple writers.
38 * Each FIF0 slot can contain one full cache line, even if RPCs store only
39 * an extended pointer on the RPC descriptor in each slot.
40 * In case of FIFO full, the writer deschedule without blocking, to retry later.
41 *
42 * WARNING : the number of slots is statically defined by the global
43 * configuration parameter CONFIG_REMOTE_FIFO_SLOTS for all fifos, requiring
44 * CACHE_LINE_SIZE * CONFIG_REMOTE_FIFO_SLOTS bytes for each FIFO...
45 ***********************************************************************************/
46typedef struct remote_fifo_s
47{
48        volatile uint32_t  wr_id;                            /*! write slot index      */
49        volatile uint32_t  rd_id;                            /*! read  slot index      */
50    volatile bool_t    valid[CONFIG_REMOTE_FIFO_SLOTS];  /*! empty slot if false   */
51        cacheline_t        data[CONFIG_REMOTE_FIFO_SLOTS];   /*! fifo slot content     */
52}
53remote_fifo_t;
54
55/************************************************************************************
56 * This function initializes the local FIFO as empty.
57 * It can only initialise a local FIFO.
58 ************************************************************************************
59 * @ fifo    : pointer to the local fifo.
60 ***********************************************************************************/
61void local_fifo_init( remote_fifo_t * fifo );
62
63/************************************************************************************
64 * This non blocking function tries to get one item from the local fifo.
65 * The reader must get exclusive access before calling this function. 
66 * The read slot index is incremented.
67 ************************************************************************************
68 * @ fifo    : pointer to the local fifo.
69 * @ item    : pointer on destination buffer for extracted item.
70 * @ size    : actual number of bytes in one item.
71 * @ return  0 on success, EAGAIN if the buffer is empty.
72 ***********************************************************************************/
73error_t local_fifo_get_item( remote_fifo_t * fifo, 
74                             void          * item,
75                             uint32_t        size );
76
77/************************************************************************************
78 * This blocking function puts one item to a remote fifo identified
79 * by an extended pointer.
80 * This function gets a write ticket using a remote_atomic_increment on the
81 * write slot index and waits until the slot is empty, using a descheduling
82 * policy (without blocking).
83 ************************************************************************************
84 * @ fifo    : extended pointer to the fifo in remote cluster.
85 * @ item    : pointer on a local buffer containing the item to be stored.
86 * @ size    : actual number of bytes in one item.
87 * @ first   : return value (true if first item registered in remote fifo)
88 * @ return  0 on success / EBUSY if a contention has been detected.
89 ***********************************************************************************/
90error_t remote_fifo_put_item( xptr_t     fifo,
91                              void     * item,
92                              uint32_t   size,
93                              bool_t   * first );
94
95/************************************************************************************
96 * Query if local fifo is empty
97 ************************************************************************************
98 * @ fifo    : pointer to the fifo.
99 * @ return true if the fifo is empty, false otherwise.
100 ***********************************************************************************/
101bool_t local_fifo_is_empty( remote_fifo_t * fifo );
102
103/************************************************************************************
104 * Query if remote fifo is full
105 ************************************************************************************
106 * @ fifo    : pointer to the fifo in remote cluster.
107 * @ cxy         : remote cluster index.
108 * @ return true if the fifo is full, false otherwise.
109 ***********************************************************************************/
110bool_t remote_fifo_is_full( xptr_t fifo );
111
112/************************************************************************************
113 * Query number ot items in remote fifo.
114 ************************************************************************************
115 * @ fifo     : pointer to the fifo in remote cluster.
116 * @ cxy          : remote cluster index.
117 * @ return  number of items.
118 ***********************************************************************************/
119uint32_t remote_fifo_items( xptr_t fifo );
120
121
122#endif  /* _REMOTE_FIFO_H_ */
Note: See TracBrowser for help on using the repository browser.