StackSizeDefs.hpp

// Copyright (c) 2020 Graphcore Ltd. All rights reserved.
 
#ifndef poplar_StackSizeDefs_hpp
#define poplar_StackSizeDefs_hpp
 
#ifdef __IPU__
 
// Definitions needed for stack usage computation, for Assembly and C++
// codelets.
 
// The format for ELF stack size info used in assembly code is the same as the
// one used by clang when the `-fstack-size-section` options is used:
// A section named `.stack_sizes.<NAME>` is added to the ELF file, containing a
// 'reference' to the function or section (so, the function symbol label or
// section name), followed by the stack size encoded in ULEB128 format.
// Note that using a 'reference' to the function/section implies that an
// additional relocation section will be automatically added by the assembler,
// named `.rela.stack_sizes.<NAME>`; this is needed to resolve the
// 'reference' at link time.
// `<NAME>` will be the name of the function or the section, as specified below.
//
// On top of the above clang standard format, we add an extra 'custom'
// convention for assembly codelets:
//
// The 'stack size' value stored as defined above, considered as a 32 bit
// unsigned value, will have its most significant bit used as a flag:
//
//       31 30 29 28              ...           1  0
//      +--+--------------------- // ---------------+
//      |TU|      Stack Size Proper (30 bits)       |
//      +--+--------------------- // ---------------+
//
//  TU (Total Usage) flag: When set, this specifies that the stack size
//                         defined in the rest of the value is the total
//                         stack usage for this function and all its callees
//                         (no need to traverse this function callgraph
//                         tree to compute it). When not set, the stack size
//                         is just the 'own' stack size for this function.
//
// The convention for the flag above is chosen to be reasonably
// compatible with the default clang format for the .stack_sizes sections
// (as stack sizes will always fit in less than 20 bits).
//
//
// We also add some extra custom information in the ELF, also for the stack
// usage computation:
//
// 1. We use bit 30 (mask 0x40000000) of the section header flag word (sh_flags)
//    to indicate that the section contains worker code. This is needed only for
//    worker code that is not part of an explicit worker vertex, so is not
//    needed for `__runCodelet_XXXXX` functions, and functions called directly
//    by them.
//
// 2. In case function pointers are used, the programmer should add (using a
//    macro defined here) a special section named `.func_ptrs_def.FUNCTION_NAME`
//    that contains:
//       * A reference to the caller function
//       * One or more references to the function(s) called via pointers
//    Use of function pointers is to be discouraged because use of this macro
//    offers very poor maintainability (and it is non-standard).
//
// 3. C/C++ functions have their ('own') stack size information added by popc.
//    But we also add a 'last resort' way to override this and specify the
//    stack "total usage" for a C++ function, by adding a section named:
//      `.stack_sizes.override.FUNCTION_NAME`
//    using the C/C++ DEF_STACK_USAGE macro below. This section has the same
//    format as described above (with the 'TU' flag set) and will be used by
//    poplar to override the `.stack_sizes` section introduced by popc.
//    This can be used for recursive functions, or function pointer use (in
//    alternative to option 2. above)
//    This involves determining 'manually' the max stack usage for the specific
//    chain of functions and all their callees.
//    Use of recursive function is discouraged because use of this macro
//    offers very poor maintainability (and it is non-standard).
 
// Mask for the 'TU' flag defined above.
#define TOTAL_STACK_USAGE 0x80000000
 
// Section header flag that indicates that a section contains code that will
// be run in a worker context.
// This is to be used in the `.section` directive (for assembly function):
//
//   .section .text.MyFunctionName, FUNCTION_IS_WORKER
//
// Note that this is not needed for explicit worker vertices entry
// points (so, __runCodelet_XXXXX) and functions called directly by them.
// It is required only for worker code that is run from supervisor vertices
// but is not part of a worker vertex.
#define FUNCTION_IS_WORKER "0x40000000"
 
#if __ASSEMBLER__
 
// clang-format off
 
  // The two macros below take a parameter named `FUNC_OR_SECTION` which can be
  // a label (the entry point of the assembly function), or the name of the
  // section containing the code for the function.
  // Each assembly function is required in general to be placed in a separate
  // section with a unique name (to allow unused code elimination) so in this
  // case there will not be ambiguity.
  // In case a section contains multiple assembly functions, the macros can
  // still be used, specifying the section name as the `FUNC_OR_SECTION`
  // parameter and making sure that the value specified for the stack size is
  // valid for the totality of the functions contained in the section.
 
  // Note that these two assembly macros define a section themselves, so for
  // clarity, it is better to place them OUTSIDE any other section definitions.
 
  // See the assembly codelets in runtime/codelets for examples of use.
 
 
  // ====================================================================
  // Used to specify the stack size used by a function.
  //
  // SIZE            : size in bytes of the stack used by `FUNC_OR_SECTION`
  //                   *only*, so not including the stack used by any other
  //                   function called by `FUNC_OR_SECTION` itself.
  //                   Must be an absolute expression.
  //
  // FUNC_OR_SECTION : name of the function (so, its label) or section name
  // ======================================================================
  .macro DEF_STACK_SIZE_OWN  SIZE:req FUNC_OR_SECTION:req
    .section .stack_sizes.\FUNC_OR_SECTION, "", @progbits
    .dc.l \FUNC_OR_SECTION
    .uleb128 \SIZE
    .previous
  .endm
 
  // ====================================================================
  // Used to specify the *TOTAL* stack usage of a function.
  // This includes any function that might be called by `FUNC_OR_SECTION`.
  // See comment above for the third parameter.
  // Used to specify the stack size used by a function.
  //
  // SIZE            : size in bytes of the *total* stack usage of
  //                   `FUNC_OR_SECTION`, which includes any function that
  //                   might be called by `FUNC_OR_SECTION`.
  //                   Must be an absolute expression.
  //
  // FUNC_OR_SECTION : name of the function (so, its label) or section name
  // ======================================================================
  .macro DEF_STACK_USAGE  SIZE:req  FUNC_OR_SECTION:req
    .section .stack_sizes.\FUNC_OR_SECTION, "", @progbits
    .dc.l \FUNC_OR_SECTION
    .uleb128 \SIZE+TOTAL_STACK_USAGE
    .previous
  .endm
 
  // ====================================================================
  // Macro to declare that a function might call other functions via
  // function pointers.
  //
  //  CALLER_FUNC : the name (label) of the function that calls other
  //                functions via function pointers, so uses `br $mX`
  //                to call some further code (not just returning from
  //                a call).
  //
  //  CALLED_FUNCS : a comma separated list of function names (labels)
  //                 specifying which functions are called via function
  //                 pointers by CALLER_FUNC.
  // ====================================================================
  .macro DEF_FUNC_CALL_PTRS  CALLER_FUNC:req CALLED_FUNCS:vararg
    .section .func_ptrs_def.\CALLER_FUNC, "", @progbits
    .dc.l \CALLER_FUNC
    .dc.l \CALLED_FUNCS
    .previous
  .endm
 
// clang-format on
#else
 
// Used by the DEF_STACK_USAGE macro below, for stringification of the `size`
// parameter.
#define DEF_STACK_USAGE_HELPER(size, funcname)                                 \
  __asm__(".section .stack_sizes.override." #funcname ",\"\",@progbits\n"      \
          ".dc.l " #funcname "\n"                                              \
          ".uleb128 " #size "\n")
 
#define DEF_STACK_USAGE(size, funcname)                                        \
  DEF_STACK_USAGE_HELPER((size) + 0x80000000, funcname)
 
#define DEF_FUNC_CALL_PTRS(caller_func, called_func_list)                      \
  __asm__(".section .func_ptrs_def." caller_func ",\"\",@progbits\n"           \
          ".dc.l " caller_func "\n"                                            \
          ".dc.l " called_func_list "\n")
 
#define DEF_FUNCTION_AS_WORKER(funcname)                                       \
  __asm__(".section .text." funcname ", \"" FUNCTION_IS_WORKER "\"")
 
#endif // #if __ASSEMBLER__
#endif // #ifdef __IPU__
#endif // poplar_StackSizeDefs_hpp