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

Last change on this file since 565 was 563, checked in by alain, 6 years ago

Complete restructuration of kernel spinlocks.

File size: 5.9 KB
Line 
1/*
2 * remote_fifo.h - Lock-less Single-Reader Multiple-Writers FIFO
3 *
4 * Authors : Mohamed Lamine Karaoui (2015)
5 *           Alain Greiner (2016,2017)
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_FIFO_H_
26#define _REMOTE_FIFO_H_
27
28#include <kernel_config.h>
29#include <hal_kernel_types.h>
30#include <printk.h>
31#include <errno.h>
32#include <hal_remote.h>
33
34/************************************************************************************
35 * This structure defines a generic, single reader, multiple writers FIFO,
36 * that is used for - RPC based - inter cluster communications.
37 * Each FIF0 slot can contain one 64 bits integer (or one extended pointer).
38 * The number of slots is defined by the CONFIG_REMOTE_FIFO_SLOTS parameter.
39 * - The write accesses are implemented using a lock-free algorithm, as it uses
40 *   a ticket based mechanism to handle concurrent access between multiple writers.
41 *   In case of FIFO full, the writer deschedule without blocking, to retry later.
42 * - The reader must take the try_lock implemented by the "owner" field, using
43 *   an atomic_add(). The TRDID is a good owner identifier, because all
44 *   RPC threads in a given cluster belong to the same kernel process,
45 *   and RPC threads cannot have local index LTID = 0.
46*
47 * WARNING : Each FIFO requires 12 + (12 * CONFIG_REMOTE_FIFO_SLOTS) bytes.
48 ***********************************************************************************/
49
50typedef struct remote_fifo_s
51{
52    uint32_t           owner;                            /*! owner thread trdid    */
53        volatile uint32_t  wr_id;                            /*! write slot index      */
54        volatile uint32_t  rd_id;                            /*! read  slot index      */
55    volatile uint32_t  valid[CONFIG_REMOTE_FIFO_SLOTS];  /*! empty slot if 0       */
56        uint64_t           data[CONFIG_REMOTE_FIFO_SLOTS];   /*! fifo slot content     */
57}
58remote_fifo_t;
59
60/************************************************************************************
61 * This function initializes the local FIFO as empty.
62 * It can only initialise a local FIFO.
63 ************************************************************************************
64 * @ fifo    : local pointer to the local fifo.
65 ***********************************************************************************/
66void remote_fifo_init( remote_fifo_t * fifo );
67
68/************************************************************************************
69 * This non blocking function tries to get one item from the local fifo.
70 * The reader must get exclusive access for read before calling this function. 
71 * The read slot index is incremented.
72 ************************************************************************************
73 * @ fifo    : local pointer to the local fifo.
74 * @ item    : [out] pointer on buffer for extracted item.
75 * @ return  0 on success, EAGAIN if the buffer is empty.
76 ***********************************************************************************/
77error_t remote_fifo_get_item( remote_fifo_t * fifo, 
78                              uint64_t      * item );
79
80/************************************************************************************
81 * This blocking function puts one item to a remote fifo identified
82 * by an extended pointer. It gets a write ticket on the slot to be written,
83 * using a remote_atomic_add() on the write slot index. Then, it waits until
84 * the slot is empty, using a descheduling policy without blocking if required.
85 * It implements a watchdog, returning when the item has been successfully
86 * registered, or after CONFIG_REMOTE_FIFO_MAX_ITERATIONS failures.   
87 ************************************************************************************
88 * @ fifo    : extended pointer to the remote fifo.
89 * @ item    : item to be stored.
90 * @ return  0 on success / EBUSY if a contention has been detected.
91 ***********************************************************************************/
92error_t remote_fifo_put_item( xptr_t     fifo,
93                              uint64_t   item );
94
95/************************************************************************************
96 * Query if local fifo is empty
97 ************************************************************************************
98 * @ fifo    : local pointer to the local fifo.
99 * @ return true if the fifo is empty, false otherwise.
100 ***********************************************************************************/
101bool_t remote_fifo_is_empty( remote_fifo_t * fifo );
102
103/************************************************************************************
104 * Query if remote fifo is full
105 ************************************************************************************
106 * @ fifo    : extended pointer to the remote fifo.
107 * @ return true if the fifo is full, false otherwise.
108 ***********************************************************************************/
109bool_t remote_fifo_is_full( xptr_t fifo );
110
111/************************************************************************************
112 * Query number ot items in remote fifo.
113 ************************************************************************************
114 * @ fifo     : extended pointer to the remote fifo.
115 * @ return  number of items.
116 ***********************************************************************************/
117uint32_t remote_fifo_items( xptr_t fifo );
118
119
120#endif  /* _REMOTE_FIFO_H_ */
Note: See TracBrowser for help on using the repository browser.