Ignore:
Timestamp:
May 10, 2017, 1:47:23 PM (2 years ago)
Author:
cameron
Message:

Multiblock Kernels: initial check-in

File:
1 edited

Legend:

Unmodified
Added
Removed
  • icGREP/icgrep-devel/icgrep/kernels/kernel.h

    r5436 r5439  
    4040    static const std::string DO_BLOCK_SUFFIX;
    4141    static const std::string FINAL_BLOCK_SUFFIX;
     42    static const std::string MULTI_BLOCK_SUFFIX;
    4243    static const std::string LOGICAL_SEGMENT_NO_SCALAR;
    4344    static const std::string PROCESSED_ITEM_COUNT_SUFFIX;
     
    383384};
    384385
    385 
     386/*   
     387The Multi-Block Kernel Builder
     388------------------------------
     389
     390The Multi-Block Kernel Builder is designed to simplify the programming of
     391efficient kernels with possibly variable and/or nonaligned output, subject to
     392exact or MaxRatio processing constraints.   The following restrictions apply.
     393   
     394#.  The input consists of one or more stream sets, the first of which is
     395    known as the principal input stream set. 
     396   
     397#.  If there is more than one input stream set, the additional stream sets must
     398    have a processing rate defined with respect to the input stream set of one
     399    of the following types:  FixedRate, Add1 or RoundUp.    Note that stream sets
     400    declared without a processing rate attribute have the FixedRate(1) attribute
     401    by default and therefore satisfy this constraint.
     402   
     403#.  All output stream sets must be declared with processing rate attributes
     404    of one of the following types:
     405    *  FixedRate, Add1, Roundup, or MaxRatio with respect to the principal input stream set.
     406    *  FixedRate with respect to some other output stream set.
     407   
     408    When using the Multi-Block Kernel Builder to program a new type of kernel,
     409    the programmer must implement the generateDoMultiBlockMethod for normal
     410    multi-block processing according to the requirements below, as well as
     411    providing for special final block processing, if necessary.
     412           
     413#.  The doMultiBlockMethod will be called with the following parameters:
     414    * the number of items of the principal input stream to process (itemsToDo),
     415    * pointers to linear contiguous buffer areas for each of the input stream sets, and
     416    * pointers to linear contiguous output buffer areas for each of the output stream sets.
     417    * pointers are to the address of the first item of the first stream of the stream set.
     418
     419#.  The Multi-Block Kernel Builder will arrange that these input parameters may be
     420    processed under the following simplifying assumptions.
     421    * the number of itemsToDo will either be an exact multiple of the BlockSize,
     422      or, for processing the final block, a value less than BlockSize
     423    * all input buffers will be safe to access and have data available in
     424      accord with their processing rates based on the given number of itemsToDo
     425      of the principal input stream set; no further bounds checking is needed.
     426    * all output buffers will be safe to access and have space available
     427      for the given maximum output generation rates based on the given number
     428      of blocksToDo of the principal input stream set; no further bounds checking
     429      is needed.
     430    * for final block processing, all input buffers will be extended to be safely
     431      treated as containing data corresponding to a full block of the principal
     432      input stream set, with the actual data in each buffer padded with null values
     433      beyond the end of input.  Similarly, all output buffers will contain space
     434      sufficient for the maximum output that can be generated for a full block of
     435      input processing.
     436    * input and output pointers will be typed to allow convenient and logical access
     437      to corresponding streams based on their declared stream set type and processing rate.
     438    * for any input pointer p, a GEP instruction with a single int32 index i
     439      will produce a pointer to the buffer position corresponding to the ith block of the
     440      principal input stream set. 
     441    * for any output stream set declared with a Fixed or Add1 processing rate with respect
     442      to the principal input stream set, a GEP instruction with a single int32 index i
     443      will produce a pointer to the buffer position corresponding to the ith block of the
     444      principal input stream set.
     445                   
     446#.  Upon completion of multi-block processing, the Multi-Block Kernel Builder will arrange that
     447    processed and produced item counts are updated for all stream sets that have exact
     448    processing rate attributes.   Programmers are responsible for updating the producedItemCount
     449    of any stream set declared with a variable attribute (MaxRatio).
     450                           
     451#.  An important caveat is that buffer areas may change arbitrarily between
     452    calls to the doMultiBlockMethod.   In no case should a kernel store a
     453    buffer pointer in its internal state.   Furthermore a kernel must not make
     454    any assumptions about the accessibility of stream set data outside of the
     455    processing range outside of the block boundaries associated with the given itemsToDo.
     456*/
     457
     458class MultiBlockKernel : public Kernel {
     459protected:
     460
     461    MultiBlockKernel(std::string && kernelName,
     462                     std::vector<Binding> && stream_inputs,
     463                     std::vector<Binding> && stream_outputs,
     464                     std::vector<Binding> && scalar_parameters,
     465                     std::vector<Binding> && scalar_outputs,
     466                     std::vector<Binding> && internal_scalars);
     467
     468    // Each multi-block kernel subtype must provide its own logic for handling
     469    // doMultiBlock calls, subject to the requirements laid out above.
     470    // The generateMultiBlockLogic must be written to generate this logic, given
     471    // a created but empty function.  Upon entry to generateMultiBlockLogic,
     472    // the builder insertion point will be set to the entry block; upone
     473    // exit the RetVoid instruction will be added to complete the method.
     474    //
     475    virtual void generateMultiBlockLogic () = 0;
     476
     477    // Given a kernel subtype with an appropriate interface, the generateDoSegment
     478    // method of the multi-block kernel builder makes all the necessary arrangements
     479    // to translate doSegment calls into a minimal sequence of doMultiBlock calls.
     480    void generateDoSegmentMethod() override final;
     481};
     482   
     483   
    386484}
    387485#endif
Note: See TracChangeset for help on using the changeset viewer.