ORC @

last updated:Feb 22 , 2002

Don't

• Reformat a file rendering it impossible to diff with previous versions
• Unnecessarily rename variables causing massive diff with previous versions
• Use of multiple inheritance. In general, use of inheritance and virtual functions are discouraged. 
• Use of exception handling
• Use of "state" variables globally that creates tacit assumption about phase ordering or dependency among optimizations
• Use of malloc/calloc typed memory routines directly. 
• Use of  new/delete directly
• Use of assert/abort/exit directly
• Use of int/char/... builtin types. They cause compilation model dependencies (ILP32, LP64, P64.. issues)

Data Type and Name

• All data types has been typedef'd to INT, INT16, CHAR, UCHAR, INT64, etc so that their sizes and signed-ness are explicit. Such declaration can be found in common/com/defs.h
• Although no explicit typedef/method is uniformly used to handle endian independently, the compiler has been ported in both endian hosts and targets. Watch out and avoid hidden endianness assumptions. E.g. use accessor functions for bit-masks that are endian dependant.
• Use "const" qualifier whenever possible.
• Class hierarchy must be a tree, not a graph. The root of the class hierarchy is the compilation unit a specific phase/optimization is dealing with. E.g. root of SWP hierarchy is T_SWpipe_CU.  !@checkme
• All private member name should start with '_'. 
• Classes that are derived from base classes defined in cxx_base.h should use the same suffix as defined in the base class. E.g. define XXX_LIST_NODE for classes derived from LIST_NODE.
• Use cg_defs.h (!@checkme) to define any data structure or variable global to cg
• Use cg_config.h (!@checkme) to define any configurable data structure size. This way, sizes can be changed easily and boundary conditions can be tested up front.
• Do not use typedef to define enum, struct.
• Do not use hard coded constants.
• enum should be used in place of #define constants. This brings better debuggability.
• The general guideline for variable and functions names are: 
  • class, constants, macros and types, use upper cases
  • function names, all lower case, except first character of each word
  • variable names use all lower cases
  • for all names, separate words by underscores
  • Exceptions: acronyms are always upper cases: e.g. Get_ST_info(xxx)

 Headers

• Try and keep unnecessary information out of the header files. The how (as opposed to the what), as well as details on any private member functions, belong in the appropriate source file.
• There should be one header file that goes with each .cxx file. Content of the header file will be the usual information pertinent to the source, typically name, input, output, side effect, algorithm overview etc. The same should hold for each class.
• All header files should be able to compile standalone. May be with the exception of header files that are included everywhere.
• Enclose header files with #ifndef xxx_INCLUDED/#define xxx_INCLUDED "xxx.h".
• Use forward declaration to avoid pulling in excess header files. If the inline function requires a full header file, this function should be moved to the corresponding .cxx  file.
• Always explicitly define private member access, assign and other frequently used methods of class members. If an inlined function is only referenced in one .cxx file, it should be kept in that .cxx file.
• Class member functions that are not member access functions should be grouped according to related functionality. For unrelated functions, those with included function bodies (inlined) should come first, followed by functions whose definition are outside the class.

Memory Usage

The compiler is designed to take advantage of  the fact that compilation has known phase ordering  so that entire chunks of memory can be totally freed upon completion of a specific phase. A memory pool push/pop mechanism is designed to manage memory usage on top of STL's segmented array.

• All memory allocation must use CXX_NEW, CXX_NEW_ARRAY or CXX_NEW_VARIANT. Use of malloc/calloc/free etc are prohibited.
• Do not use CXX_DELETE_ARRAY or CXX_DELETE_VARIANT to free memory either. CXX_DELETE is allowed, since the destructor gets called by CXX_DELETE. 
• If non-zeroing memory pool is desirable for your need, do not use any global memory pool defined in mempool.h
• Each optimization phase should use local memory pool. Global memory pool are meant for data structures that must stay through out the optimization phases.
• It is OK to create your own memory pool. When you do, the existing set up mechanism should be followed.

         MEM_POOL_Push(&your_local_pool);

        {

            some_type x(&your_local_pool);

            ...

        }

        MEM_POOL_Pop(&your_local_pool);

• The mempool package is built in with capability to use Purify. If change is needed to that package, keep that feature.
• The following are ways to handle mempool in the code generator:.

  1. The old C style way

  MEM_POOL_Push(&MEM_local_pool); MEM_POOL_Push(&MEM_local_nz_pool);

  the two different pools are passed to relevant routines that needs memory, later on, used like the following:

  loop_set = BB_SET_Create_Empty(PU_BB_Count + 2, pool);

  where pool is the parameter with actual being &MEM_local_pool

  There needs to be a finalize routine that pops the mempools.

  2. a little newer way, for local temp memory, this method can simply use alloca e.g.

  Local_Insn_Sched (void) {
  for (bb = REGION_First_BB; bb != NULL; bb = BB_next(bb)) {
          if (bb->Spilled() || !bb->Scheduled()) {
              MEM_POOL_Push(&MEM_local_pool);
              sched = CXX_NEW(LOCAL_SCHEDULER(bb), &MEM_local_pool);
              sched->Schedule();
              CXX_DELETE(LOCAL_SCHEDULER(bb), &MEM_local_pool);
              MEM_POOL_Pop(&MEM_local_pool);
          }
      }
  }

  3. a more sophistical way that works in cg phase also, taking the fb_cfg.h and fg_cfg.cxx as example

  class FB_CFG_MEM {
  protected:
      MEM_POOL _m;
      FB_CFG_MEM() {
          MEM_POOL_Initialize( &_m, "FB_CFG_MEM", true);
          MEM_POOL_Push( &_m );
      }
      ~FB_CFG_MEM() {
          MEM_POOL_Pop( &_m );
          MEM_POOL_Delete( &_m );
      }
  };
  FB_CFG: public FB_CFG_MEM {
      ...
      hashmap< LABEL_IDX, FB_NODEX, hash<LABEL_IDX>, equal_to<LABEL_IDX>,
      mempool_allocator< pair<LABEL_IDX, FBNODEX> > > _lblx_to_nx;
      deque< FB_EDGE_DELAYED, mempool_allocator<FB_EDGE_DELAYED> > _delayed_edges;
      FB_NODEX _curr_nx;
      ...
  };

  The FB_CFG graph is implemented as a deque of nodes and edges. Here, no mempool operation is exposed in the routines such as FB_CFG::New_Node, Add_edge. The constructors for the containers _nodes, _lblx_to_nx and _delayed_edges are explicitly called from the constructor of FB_CFG and the mempool _m is passed down there, making sure mempool is properly initialized, stacked and deleted upon exit.

  #1 is NOT desirable since there hides an assumed method of push and pop with a initialize routine and finalize routine, but no way to enforce implementers to do that in the right sequence. Currently, CG uses #1 or #2. The problem with #2 is when you "break" out of loop or "return" from a procedure, you have to insert MEM_POOL_pop at each exit paths. And people usually don't get it correct the first time, or forget to add the necessary insert when fix bugs.

  For #3,  If you look at CXX_MEM_POOL, it does the same thing as FB_CFG_MEM. So class FB_CFG could have been declared as class FB_CFG : public CXX_MEM_POOL {...};  Memory used by the containers (i.e., the deque and hashmap here)  is released by the containers themselves. In this example, itsimply tells the containers to use the specified mempool as memory allocator. Any object created by these containers will accquire memory from this mempool. And the memory will be released back to the mempool when these objects' destructors are called.

   

Class definition

• Declare but not define constructors for any class definition: default constructor, copy constructor and overloaded assignment operator, e.g.

class COMP_UNIT {
private:
  COMP_UNIT(void);
  COMP_UNIT(const COMP_UNIT&);
  COMP_UNIT& operator = (const COMP_UNIT);
   ...
};

• All constructor is responsible for initializing class members. If possible, initialize the class member with real value using overloaded constructor.
• Define copy method to do the object copy.
• Access functions should be used. The following the old style macro should not be used for new classes and data structures.

#define Set_XXX(y)    (XXX(y) != SOME_FLAG)

• Define member function 'Print' to dump out class contents. The last parameter in the Print function should be type FILE *. The default for this parameter is stderr. The idea is to be able to call from debugger as well as in traces. Please minimize the number of required arguments also.
• Define member function 'Validate' to validate correctness of the class setup. The last parameter of this function is the same as Print function.
• Care should be taken to decide which Print/Validate remains inside #define DEBUG. While it helps slightly with compact code for the compiler itself, its also helpful to be able to trace/print internal data structure/IL in production mode.
• Define graph dumping routines for the class also when applicable. Again, following the same convention as  the Print functions. We want the same routines callable from the debugger as well as used in traces.

Misc

• Layout function definition in callee to caller order.
• Verification/Printing functions not defined in header files should be group together and placed at the end of the file.
• Each optimization phase must be traceable before and after in that a dump of IL before and after the optimization can be controlled during compilation.
• Call Start_Timer/Stop_Timer before and after the optimization  to account for the time spent in that optimization.
• A number of utility routines: Is_True, FmtAssert, ErrMsg, DevWarn ... are to be used in place of assertion. Is_True will remain in production build. Others will go away in non-debug build. Also use Is_Trace utility for setting up the tracing.
• Global variable should be avoided as much as possible.
• All files must start with the line so that C++ mode is automatic for emacs users.

//-*-c++-*-

• All functions must be properly prototyped, with explicit return type.
• All switch statements must have a default statement.
• Use existing for_all_xxx for iteration control. Be careful when some of those data structures are READ ONLY. For new data structure and code, think STL and templates. You can find examples in common/com/symtab_util.h
• All statements must be enclosed with braces.
• Files that are shared among two different components, i.e. resides in two different directories, should reside in common directory. Interfaces to a different component should be through a package whose source resides in the common directory.