source: icGREP/icgrep-devel/icgrep/kernels/interface.h @ 5434

Last change on this file since 5434 was 5434, checked in by cameron, 2 years ago

getLinearlyWritableItems/Blocks includes buffer space plus overflow blocks; more processing rate functions

File size: 8.1 KB
Line 
1/*
2 *  Copyright (c) 2016 International Characters.
3 *  This software is licensed to the public under the Open Software License 3.0.
4 */
5
6#ifndef KERNEL_INTERFACE_H
7#define KERNEL_INTERFACE_H
8
9#include <llvm/IR/Constants.h>
10#include <string>
11#include <vector>
12
13namespace IDISA { class IDISA_Builder; }
14
15// Processing rate attributes are required for all stream set bindings for a kernel.
16// These attributes describe the number of items that are processed or produced as
17// a ratio in comparison to the principal input stream set (or the principal output
18// stream set if there is no input.
19//
20// The default ratio is FixedRatio(1) which means that there is one item processed or
21// produced for every item of the principal input or output stream.
22// FixedRatio(m, n) means that for every group of n items of the principal stream,
23// there are m items in the output stream (rounding up).
24//
25// Kernels which produce a variable number of items use MaxRatio(n), for a maximum
26// of n items produced or consumed per principal input or output item.  MaxRatio(m, n)
27// means there are at most m items for every n items of the principal stream.
28//
29// RoundUpToMultiple(n) means that number of items produced is the same as the
30// number of input items, rounded up to an exact multiple of n.
31//
32
33struct ProcessingRate  {
34    enum class ProcessingRateKind : uint8_t { FixedRatio, RoundUp, Add1, MaxRatio, Unknown };
35    ProcessingRateKind getKind() const {return mKind;}
36    bool isFixedRatio() const {return mKind == ProcessingRateKind::FixedRatio;}
37    bool isMaxRatio() const {return mKind == ProcessingRateKind::MaxRatio;}
38    bool isExact() const {return (mKind == ProcessingRateKind::FixedRatio)||(mKind == ProcessingRateKind::RoundUp)||(mKind == ProcessingRateKind::Add1) ;}
39    bool isUnknownRate() const { return mKind == ProcessingRateKind::Unknown; }
40    llvm::Value * CreateRatioCalculation(IDISA::IDISA_Builder * b, llvm::Value * principalInputItems, llvm::Value * doFinal = nullptr) const;
41    llvm::Value * CreateMaxReferenceItemsCalculation(IDISA::IDISA_Builder * b, llvm::Value * outputItems, llvm::Value * doFinal = nullptr) const;
42    friend ProcessingRate FixedRatio(unsigned strmItemsPer, unsigned perPrincipalInputItems, std::string && referenceStreamSet);
43    friend ProcessingRate MaxRatio(unsigned strmItemsPer, unsigned perPrincipalInputItems, std::string && referenceStreamSet);
44    friend ProcessingRate RoundUpToMultiple(unsigned itemMultiple, std::string && referenceStreamSet);
45    friend ProcessingRate Add1(std::string && referenceStreamSet);
46    friend ProcessingRate UnknownRate();
47    uint16_t getRatioNumerator() const { return mRatioNumerator;}
48    uint16_t getRatioDenominator() const { return mRatioDenominator;}
49    std::string referenceStreamSet() const { return mReferenceStreamSet;}
50protected:
51    ProcessingRate(ProcessingRateKind k, unsigned numerator, unsigned denominator, std::string && referenceStreamSet)
52    : mKind(k), mRatioNumerator(numerator), mRatioDenominator(denominator), mReferenceStreamSet(referenceStreamSet) {}
53private:
54    const ProcessingRateKind mKind;
55    const uint16_t mRatioNumerator;
56    const uint16_t mRatioDenominator;
57    const std::string mReferenceStreamSet;
58}; 
59
60ProcessingRate FixedRatio(unsigned strmItemsPer, unsigned perPrincipalInputItems = 1, std::string && referenceStreamSet = "");
61ProcessingRate MaxRatio(unsigned strmItemsPer, unsigned perPrincipalInputItems = 1, std::string && referenceStreamSet = "");
62ProcessingRate RoundUpToMultiple(unsigned itemMultiple, std::string &&referenceStreamSet = "");
63ProcessingRate Add1(std::string && referenceStreamSet = "");
64ProcessingRate UnknownRate();
65
66struct Binding {
67    Binding(llvm::Type * type, const std::string & name, ProcessingRate r = FixedRatio(1))
68    : type(type), name(name), rate(r) { }
69    llvm::Type * const        type;
70    const std::string         name;
71    const ProcessingRate      rate;
72};
73
74class KernelInterface {
75public:
76    /*
77     
78     This class defines the methods to be used to generate the code 
79     necessary for declaring, allocating, calling and synchronizing
80     kernels.   The methods to be used for constructing kernels are defined
81     within the KernelBuilder class of kernel.h
82     
83     */
84   
85    const std::string & getName() const { return mKernelName; }
86
87    void setName(std::string newName) { mKernelName = newName; }
88       
89    virtual bool isCachable() const = 0;
90
91    virtual std::string makeSignature() = 0;
92
93    const std::vector<Binding> & getStreamInputs() const { return mStreamSetInputs; }
94
95    const std::vector<Binding> & getStreamOutputs() const { return mStreamSetOutputs; }
96
97    const std::vector<Binding> & getScalarInputs() const { return mScalarInputs; }
98
99    const std::vector<Binding> & getScalarOutputs() const { return mScalarOutputs; }
100       
101    // Add ExternalLinkage method declarations for the kernel to a given client module.
102    void addKernelDeclarations();
103
104    virtual void linkExternalMethods() = 0;
105
106    virtual llvm::Value * createInstance() = 0;
107
108    virtual void initializeInstance() = 0;
109
110    virtual void finalizeInstance() = 0;
111
112    void setInitialArguments(std::vector<llvm::Value *> args);
113
114    llvm::Value * getInstance() const {
115        return mKernelInstance;
116    }
117
118    unsigned getLookAhead() const {
119        return mLookAheadPositions;
120    }
121   
122    virtual llvm::Value * getProducedItemCount(const std::string & name, llvm::Value * doFinal = nullptr) const = 0;
123
124    virtual void setProducedItemCount(const std::string & name, llvm::Value * value) const = 0;
125
126    virtual llvm::Value * getProcessedItemCount(const std::string & name) const = 0;
127
128    virtual void setProcessedItemCount(const std::string & name, llvm::Value * value) const = 0;
129
130    virtual llvm::Value * getConsumedItemCount(const std::string & name) const = 0;
131
132    virtual void setConsumedItemCount(const std::string & name, llvm::Value * value) const = 0;
133
134    virtual llvm::Value * getTerminationSignal() const = 0;
135
136    virtual void setTerminationSignal() const = 0;
137   
138    void setLookAhead(unsigned lookAheadPositions) {
139        mLookAheadPositions = lookAheadPositions;
140    }
141
142    IDISA::IDISA_Builder * getBuilder() const {
143        return iBuilder;
144    }
145
146    void setBuilder(IDISA::IDISA_Builder * const builder) {
147        iBuilder = builder;
148    }
149
150protected:
151
152    llvm::Function * getInitFunction(llvm::Module * const module) const;
153
154    llvm::Function * getDoSegmentFunction(llvm::Module * const module) const;
155
156    llvm::Function * getTerminateFunction(llvm::Module * const module) const;
157
158    KernelInterface(IDISA::IDISA_Builder * const builder,
159                    std::string kernelName,
160                    std::vector<Binding> && stream_inputs,
161                    std::vector<Binding> && stream_outputs,
162                    std::vector<Binding> && scalar_inputs,
163                    std::vector<Binding> && scalar_outputs,
164                    std::vector<Binding> && internal_scalars)
165    : iBuilder(builder)
166    , mKernelInstance(nullptr)
167    , mKernelStateType(nullptr)
168    , mLookAheadPositions(0)
169    , mKernelName(kernelName)
170    , mStreamSetInputs(stream_inputs)
171    , mStreamSetOutputs(stream_outputs)
172    , mScalarInputs(scalar_inputs)
173    , mScalarOutputs(scalar_outputs)
174    , mInternalScalars(internal_scalars)
175    {
176
177    }
178   
179    void setInstance(llvm::Value * const instance) {
180        assert ("kernel instance cannot be null!" && instance);
181        assert ("kernel instance must point to a valid kernel state type!" && (instance->getType()->getPointerElementType() == mKernelStateType));
182        mKernelInstance = instance;
183    }
184
185protected:
186   
187    IDISA::IDISA_Builder *          iBuilder;
188    llvm::Value *                   mKernelInstance;
189    llvm::StructType *              mKernelStateType;
190    unsigned                        mLookAheadPositions;
191    std::string                     mKernelName;
192    std::vector<llvm::Value *>      mInitialArguments;
193    std::vector<Binding>            mStreamSetInputs;
194    std::vector<Binding>            mStreamSetOutputs;
195    std::vector<Binding>            mScalarInputs;
196    std::vector<Binding>            mScalarOutputs;
197    std::vector<Binding>            mInternalScalars;
198};
199
200#endif
Note: See TracBrowser for help on using the repository browser.