1/*
2 * Copyright (c) 2015,2017-2018 ARM Limited
3 * All rights reserved
4 *
5 * The license below extends only to copyright in the software and shall
6 * not be construed as granting a license to any other intellectual
7 * property including but not limited to intellectual property relating
8 * to a hardware implementation of the functionality of the software
9 * licensed hereunder.  You may use the software subject to the license
10 * terms below provided that you ensure that this notice is replicated
11 * unmodified and in its entirety in all distributions of the software,
12 * modified or unmodified, in source code or in binary form.
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions are
16 * met: redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer;
18 * redistributions in binary form must reproduce the above copyright
19 * notice, this list of conditions and the following disclaimer in the
20 * documentation and/or other materials provided with the distribution;
21 * neither the name of the copyright holders nor the names of its
22 * contributors may be used to endorse or promote products derived from
23 * this software without specific prior written permission.
24 *
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 *
37 * Authors: Andreas Sandberg
38 */
39
40#ifndef __BASE_CIRCLEBUF_HH__
41#define __BASE_CIRCLEBUF_HH__
42
43#include <algorithm>
44#include <cassert>
45#include <vector>
46
47#include "base/circular_queue.hh"
48#include "base/logging.hh"
49#include "sim/serialize.hh"
50
51/**
52 * Circular buffer backed by a vector though a CircularQueue.
53 *
54 * The data in the cricular buffer is stored in a standard
55 * vector.
56 *
57 */
58template<typename T>
59class CircleBuf : public CircularQueue<T>
60{
61  public:
62    explicit CircleBuf(size_t size)
63        : CircularQueue<T>(size) {}
64    using CircularQueue<T>::empty;
65    using CircularQueue<T>::size;
66    using CircularQueue<T>::capacity;
67    using CircularQueue<T>::begin;
68    using CircularQueue<T>::end;
69    using CircularQueue<T>::pop_front;
70    using CircularQueue<T>::advance_tail;
71
72    /**
73     * Copy buffer contents without advancing the read pointer
74     *
75     * @param out Output iterator/pointer
76     * @param len Number of elements to copy
77     */
78    template <class OutputIterator>
79    void peek(OutputIterator out, size_t len) const {
80        peek(out, 0, len);
81    }
82
83    /**
84     * Copy buffer contents without advancing the read pointer
85     *
86     * @param out Output iterator/pointer
87     * @param offset Offset into the ring buffer
88     * @param len Number of elements to copy
89     */
90    template <class OutputIterator>
91    void peek(OutputIterator out, off_t offset, size_t len) const {
92        panic_if(offset + len > size(),
93                 "Trying to read past end of circular buffer.\n");
94
95        std::copy(begin() + offset, begin() + offset + len, out);
96    }
97
98    /**
99     * Copy buffer contents and advance the read pointer
100     *
101     * @param out Output iterator/pointer
102     * @param len Number of elements to read
103     */
104    template <class OutputIterator>
105    void read(OutputIterator out, size_t len) {
106        peek(out, len);
107        pop_front(len);
108    }
109
110    /**
111     * Add elements to the end of the ring buffers and advance.
112     *
113     * @param in Input iterator/pointer
114     * @param len Number of elements to read
115     */
116    template <class InputIterator>
117    void write(InputIterator in, size_t len) {
118        // Writes that are larger than the backing store are allowed,
119        // but only the last part of the buffer will be written.
120        if (len > capacity()) {
121            in += len - capacity();
122            len = capacity();
123        }
124
125        std::copy(in, in + len, end());
126        advance_tail(len);
127    }
128};
129
130/**
131 * Simple FIFO implementation backed by a circular buffer.
132 *
133 * This class provides the same basic functionallity as the circular
134 * buffer with the folling differences:
135 * <ul>
136 *    <li>Writes are checked to ensure that overflows can't happen.
137 *    <li>Unserialization ensures that the data in the checkpoint fits
138 *        in the buffer.
139 * </ul>
140 */
141template<typename T>
142class Fifo
143{
144  public:
145    typedef T value_type;
146
147  public:
148    Fifo(size_t size)
149        : buf(size) {}
150
151    bool empty() const { return buf.empty(); }
152    size_t size() const { return buf.size(); }
153    size_t capacity() const { return buf.capacity(); }
154
155    void flush() { buf.flush(); }
156
157    template <class OutputIterator>
158    void peek(OutputIterator out, size_t len) const { buf.peek(out, len); }
159    template <class OutputIterator>
160    void read(OutputIterator out, size_t len) { buf.read(out, len); }
161
162    template <class InputIterator>
163    void write(InputIterator in, size_t len) {
164        panic_if(size() + len > capacity(),
165                 "Trying to overfill FIFO buffer.\n");
166        buf.write(in, len);
167    }
168
169  private:
170    CircleBuf<value_type> buf;
171};
172
173
174template <typename T>
175void
176arrayParamOut(CheckpointOut &cp, const std::string &name,
177              const CircleBuf<T> &param)
178{
179    std::vector<T> temp(param.size());
180    param.peek(temp.begin(), temp.size());
181    arrayParamOut(cp, name, temp);
182}
183
184template <typename T>
185void
186arrayParamIn(CheckpointIn &cp, const std::string &name,
187             CircleBuf<T> &param)
188{
189    std::vector<T> temp;
190    arrayParamIn(cp, name, temp);
191
192    param.flush();
193    param.write(temp.cbegin(), temp.size());
194}
195
196template <typename T>
197void
198arrayParamOut(CheckpointOut &cp, const std::string &name,
199              const Fifo<T> &param)
200{
201    std::vector<T> temp(param.size());
202    param.peek(temp.begin(), temp.size());
203    arrayParamOut(cp, name, temp);
204}
205
206template <typename T>
207void
208arrayParamIn(CheckpointIn &cp, const std::string &name,
209             Fifo<T> &param)
210{
211    std::vector<T> temp;
212    arrayParamIn(cp, name, temp);
213
214    fatal_if(param.capacity() < temp.size(),
215             "Trying to unserialize data into too small FIFO\n");
216
217    param.flush();
218    param.write(temp.cbegin(), temp.size());
219}
220
221#endif // __BASE_CIRCLEBUF_HH__
222