hphp/hhbbc/representation.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-2014 Facebook, Inc. (http://www.facebook.com)     |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16 #ifndef incl_HHBBC_REPRESENTATION_H_
  17 #define incl_HHBBC_REPRESENTATION_H_
  18
  19 #include <list>
  20 #include <memory>
  21 #include <string>
  22 #include <tuple>
  23 #include <unordered_map>
  24 #include <utility>
  25 #include <vector>
  26
  27 #include <boost/variant.hpp>
  28
  29 #include "hphp/util/md5.h"
  30 #include "hphp/runtime/base/types.h"
  31 #include "hphp/runtime/base/user-attributes.h"
  32 #include "hphp/runtime/vm/preclass.h"
  33 #include "hphp/runtime/vm/type-alias.h"
  34 #include "hphp/runtime/vm/type-constraint.h"
  35
  36 #include "hphp/hhbbc/bc.h"
  37 #include "hphp/hhbbc/misc.h"
  38 #include "hphp/hhbbc/src-loc.h"
  39
  40 namespace HPHP { namespace HHBBC {
  41 namespace php {
  42
  43 //////////////////////////////////////////////////////////////////////
  44
  45 struct Func;
  46 struct ExnNode;
  47 struct Unit;
  48
  49 //////////////////////////////////////////////////////////////////////
  50
  51 struct SrcInfo {
  52   LineRange loc;
  53   SString docComment;
  54 };
  55
  56 //////////////////////////////////////////////////////////////////////
  57
  58 /*
  59  * A basic block in our factored control flow graph.
  60  *
  61  * Blocks terminate on control flow, except exceptional control flow.
  62  * We keep a set of "factored edges" representing all possible early
  63  * exits due to exceptional control flow.
  64  */
  65 struct Block {
  66   /*
  67    * Blocks in HHBC are each part of a bytecode "section".  The section
  68    * is either the "primary function body", or a fault funclet.  We
  69    * represent fault funclet sections with unique ids.
  70    *
  71    * Each section must be a contiguous region of bytecode, with the
  72    * primary function body first.  These ids are tracked just to
  73    * maintain this invariant at emit time.
  74    */
  75   enum class Section : uint32_t { Main = 0 };
  76   Section section;
  77
  78   /*
  79    * Blocks have unique ids within a given function.
  80    */
  81   uint32_t id;
  82
  83   /*
  84    * Instructions in the block.  Never empty guarantee.
  85    */
  86   std::vector<Bytecode> hhbcs;
  87
  88   /*
  89    * The pointer for this block's exception region, or nullptr if
  90    * there is none.
  91    */
  92   borrowed_ptr<ExnNode> exnNode;
  93
  94   /*
  95    * Edges coming out of blocks are repesented in three ways:
  96    *
  97    *  - fallthrough edges (the end of the block unconditionally jumps
  98    *    to the named block).  If fallthroughNS is true, this edge
  99    *    represents a no-surprise jump.
 100    *
 101    *  - Taken edges (these are encoded in the last instruction in hhbcs).
 102    *
 103    *  - factoredExits (these represent edges traversed for exceptions
 104    *    mid-block)
 105    *
 106    * For the idea behind the factored exit edge thing, see "Efficient
 107    * and Precise Modeling of Exceptions for the Analysis of Java
 108    * Programs" (http://dl.acm.org/citation.cfm?id=316171).
 109    */
 110   borrowed_ptr<Block> fallthrough;
 111   bool fallthroughNS = false;
 112   std::vector<borrowed_ptr<Block>> factoredExits;
 113 };
 114
 115 //////////////////////////////////////////////////////////////////////
 116
 117 /*
 118  * Exception regions.
 119  *
 120  * Each block in the program body can have a pointer to a node in the
 121  * exception handler tree.  This means they are in all the "exception
 122  * regions" for each node in the tree down to that node.  This
 123  * information is used to construct exception handling regions at emit
 124  * time.
 125  *
 126  * There are two types of regions; TryRegions and FaultRegions.  These
 127  * correspond to the two types of regions described in
 128  * bytecode.specification.  Note though that although it's not
 129  * specified there, in addition to a fault entry offset, fault regions
 130  * optionally list some information about iterators if the reason the
 131  * fault region is there is to free iterator variables.
 132  *
 133  * Exceptional control flow is also represented more explicitly with
 134  * factored exit edges (see php::Block).  This tree structure just
 135  * exists to get the EHEnts right.
 136  *
 137  * Note: blocks in fault funclets will have factored edges to the
 138  * blocks listed as handlers in any ExnNode that contained the
 139  * fault-protected region, since those control flow paths are
 140  * possible.  Generally they will have nullptr for their exnNode
 141  * pointers, however, although they may also have other EH-protected
 142  * regions inside of them (this currently occurs in the case of
 143  * php-level finally blocks cloned into fault funclets).
 144  */
 145
 146 struct FaultRegion { borrowed_ptr<Block> faultEntry;
 147                      Id iterId;
 148                      bool itRef; };
 149
 150 using CatchEnt     = std::pair<const StringData*,borrowed_ptr<Block>>;
 151 struct TryRegion   { std::vector<CatchEnt> catches; };
 152
 153 struct ExnNode {
 154   uint32_t id;
 155
 156   borrowed_ptr<ExnNode> parent;
 157   std::vector<std::unique_ptr<ExnNode>> children;
 158
 159   boost::variant<FaultRegion,TryRegion> info;
 160 };
 161
 162 //////////////////////////////////////////////////////////////////////
 163
 164 /*
 165  * Metadata about a parameter to a php function.
 166  */
 167 struct Param {
 168   /*
 169    * Default value for this parameter, or KindOfUninit if it has no
 170    * default value.
 171    */
 172   Cell defaultValue;
 173
 174   /*
 175    * Pointer to the block we'll enter for default-value initialization
 176    * of this parameter, or nullptr if this parameter had no default
 177    * value initializer.
 178    */
 179   borrowed_ptr<php::Block> dvEntryPoint;
 180
 181   /*
 182    * Information about the parameter's typehint, if any.
 183    *
 184    * NOTE: this is represented in the repo as a string type name and
 185    * some TypeConstraint::Flags.
 186    */
 187   TypeConstraint typeConstraint;
 188
 189   /*
 190    * User-visible version of the type constraint as a string.
 191    * Propagated for reflection.
 192    */
 193   SString userTypeConstraint;
 194
 195   /*
 196    * Evalable php code that will give the default argument.  This is
 197    * redundant with the dv initializer, but gets propagated through
 198    * for reflection.
 199    */
 200   SString phpCode;
 201
 202   /*
 203    * Each parameter of a func can have arbitrary user attributes.
 204    */
 205   UserAttributeMap userAttributes;
 206
 207   /*
 208    * The type of the arguments for builtin functions, or for HNI
 209    * functions with a native implementation.  folly::none for
 210    * non-builtins.
 211    */
 212   folly::Optional<DataType> builtinType;
 213
 214   /*
 215    * Whether this parameter is passed by reference.
 216    */
 217   bool byRef: 1;
 218
 219   /*
 220    * Whether this parameter is a variadic capture.
 221    */
 222   bool isVariadic: 1;
 223 };
 224
 225 /*
 226  * Metadata about a local variable in a function.  Name may be
 227  * nullptr, for unnamed locals.
 228  */
 229 struct Local {
 230   SString name;
 231   uint32_t id;
 232 };
 233
 234 /*
 235  * Metadata about function iterator variables.
 236  */
 237 struct Iter {
 238   uint32_t id;
 239 };
 240
 241 /*
 242  * Static local information.  For each static local, we need to keep
 243  * the php code around for reflection.
 244  */
 245 struct StaticLocalInfo {
 246   SString name;
 247   SString phpCode;
 248 };
 249
 250 /*
 251  * Extra information for function with a HNI native implementation.
 252  */
 253 struct NativeInfo {
 254   /*
 255    * Return type from the C++ implementation function, as an optional DataType;
 256    * folly::none stands for a Variant return.
 257    */
 258   folly::Optional<DataType> returnType;
 259 };
 260
 261 /*
 262  * Representation of a function, class method, or pseudomain function.
 263  */
 264 struct Func {
 265   /*
 266    * Basic information about the function.
 267    */
 268   SString name;
 269   SrcInfo srcInfo;
 270   Attr attrs;
 271
 272   /*
 273    * Which unit defined this function.  If it is a method, the cls
 274    * field will be set to the class that contains it.
 275    */
 276   borrowed_ptr<Unit> unit;
 277   borrowed_ptr<Class> cls;
 278
 279   /*
 280    * Parameters, locals, and iterators.
 281    *
 282    * There are at least as many locals as parameters (parameters are
 283    * also locals---the names of parameters are stored in the locals
 284    * vector).
 285    */
 286   std::vector<Param> params;
 287   std::vector<std::unique_ptr<Local>> locals;
 288   std::vector<std::unique_ptr<Iter>> iters;
 289   std::vector<StaticLocalInfo> staticLocals;
 290
 291   /*
 292    * Whether or not this function is a top-level function.  (Defined
 293    * outside of any other function body.)
 294    */
 295   bool top : 1;
 296
 297   /*
 298    * This is the generated function for a closure body.  I.e. this
 299    * function contains the code that should run when the closure is
 300    * invoked.
 301    */
 302   bool isClosureBody : 1;
 303
 304   /*
 305    * This is an async function.
 306    */
 307   bool isAsync : 1;
 308
 309   /*
 310    * This is a generator.
 311    */
 312   bool isGenerator : 1;
 313
 314   /*
 315    * This generator yields key value pairs.
 316    */
 317   bool isPairGenerator : 1;
 318
 319   /*
 320    * All owning pointers to blocks are in this vector, which has the
 321    * blocks in an unspecified order.  Blocks have borrowed pointers to
 322    * each other to represent control flow arcs.
 323    */
 324   std::vector<std::unique_ptr<Block>> blocks;
 325
 326   /*
 327    * Greatest block id in the function plus one.
 328    */
 329   uint32_t nextBlockId;
 330
 331   /*
 332    * Try and fault regions form a tree structure.  The tree is hanging
 333    * off the func here, with children pointers.  Each block that is
 334    * within a try or fault region has a pointer to the inner-most
 335    * ExnNode protecting it.
 336    */
 337   std::vector<std::unique_ptr<ExnNode>> exnNodes;
 338
 339   /*
 340    * Entry point blocks for default value initializers.
 341    *
 342    * Note that in PHP you can declare functions where some of the
 343    * earlier parameters have default values, and later ones don't.  In
 344    * this case we'll have nulls after the first non-null entry here.
 345    */
 346   std::vector<borrowed_ptr<Block>> dvEntries;
 347
 348   /*
 349    * Entry point to the function when the number of passed args is
 350    * equal to the number of parameters.
 351    */
 352   borrowed_ptr<Block> mainEntry;
 353
 354   /*
 355    * User attribute list.
 356    */
 357   UserAttributeMap userAttributes;
 358
 359   /*
 360    * User-visible return type specification as a string.  This is only
 361    * passed through to expose it to reflection.
 362    */
 363   SString returnUserType;
 364
 365   /*
 366    * Return type specified in the source code (ex. "function foo(): Bar").
 367    * HHVM checks if the a function's return value matches it's return type
 368    * constraint via the VerifyRetType* instructions.
 369    */
 370   TypeConstraint retTypeConstraint;
 371
 372   /*
 373    * If traits are being flattened by hphpc, we keep the original
 374    * filename of a function (the file that defined the trait) so
 375    * backtraces and things work correctly.  Otherwise this is nullptr.
 376    */
 377   SString originalFilename;
 378
 379   /*
 380    * For HNI-based extensions, additional information for functions
 381    * with a native-implementation is here.  If this isn't a function
 382    * with an HNI-based native implementation, this will be nullptr.
 383    */
 384   std::unique_ptr<NativeInfo> nativeInfo;
 385 };
 386
 387 //////////////////////////////////////////////////////////////////////
 388
 389 /*
 390  * A class property.
 391  *
 392  * Both static and instance properties use this structure.
 393  */
 394 struct Prop {
 395   SString name;
 396   Attr attrs;
 397   SString docComment;
 398
 399   /*
 400    * Properties can have string type constraints, which we need to
 401    * propagate through just for reflection purposes.
 402    */
 403   SString typeConstraint;
 404
 405   /*
 406    * The default value of the property, for properties with scalar
 407    * initializers.  May be KindOfUninit in some cases where the
 408    * property should not have an initial value (i.e. not even null).
 409    */
 410   Cell val;
 411 };
 412
 413 /*
 414  * A class constant.
 415  */
 416 struct Const {
 417   SString name;
 418
 419   // The class that defined this constant.
 420   borrowed_ptr<php::Class> cls;
 421
 422   /*
 423    * The value will be KindOfUninit if the class constant is defined
 424    * using an 86cinit method.
 425    *
 426    * The lack of a value represents an abstract class constant.
 427    */
 428   folly::Optional<Cell> val;
 429
 430   /*
 431    * We pass through eval'able php code and a string type constraint,
 432    * only for exposure to reflection.
 433    */
 434   SString phpCode;
 435   SString typeConstraint;
 436
 437   bool isTypeconst;
 438 };
 439
 440 /*
 441  * Representation of a php class declaration.
 442  */
 443 struct Class {
 444   /*
 445    * Basic information about the class.
 446    */
 447   SString name;
 448   SrcInfo srcInfo;
 449   Attr attrs;
 450
 451   /*
 452    * Which unit defined this class.
 453    */
 454   borrowed_ptr<Unit> unit;
 455
 456   /*
 457    * Hoistability of this class.  See the description in class.h
 458    * formation on hoistability.
 459    */
 460   PreClass::Hoistable hoistability;
 461
 462   /*
 463    * If this class represents a closure, this points to the class that
 464    * lexically contains the closure, if there was one.  If this class
 465    * doesn't represent a closure, this will be nullptr.
 466    *
 467    * The significance of this is that closures created lexically
 468    * inside of a class run as if they were part of that class context
 469    * (with regard to access checks, etc).
 470    */
 471   borrowed_ptr<php::Class> closureContextCls;
 472
 473   /*
 474    * Name of the parent class.
 475    */
 476   SString parentName;
 477
 478   /*
 479    * Names of inherited interfaces.
 480    */
 481   std::vector<LowStringPtr> interfaceNames;
 482
 483   /*
 484    * Names of used traits, number of declared (i.e., non-trait, non-inherited)
 485    * methods, trait alias/precedence rules (if any).
 486    *
 487    * This is using the exact structures from the runtime PreClass.  In
 488    * WholeProgram mode, we won't see these because traits will already be
 489    * flattened.
 490    */
 491   std::vector<LowStringPtr> usedTraitNames;
 492   std::vector<PreClass::ClassRequirement> requirements;
 493   std::vector<PreClass::TraitPrecRule> traitPrecRules;
 494   std::vector<PreClass::TraitAliasRule> traitAliasRules;
 495   int32_t numDeclMethods;
 496
 497   /*
 498    * Methods on the class.
 499    */
 500   std::vector<std::unique_ptr<php::Func>> methods;
 501
 502   /*
 503    * Properties defined on this class.
 504    */
 505   std::vector<Prop> properties;
 506
 507   /*
 508    * Constants defined on this class.
 509    */
 510   std::vector<Const> constants;
 511
 512   /*
 513    * User attributes for this class declaration.
 514    */
 515   UserAttributeMap userAttributes;
 516
 517   /*
 518    * The underlying base type, if this is an enum
 519    */
 520   TypeConstraint enumBaseTy;
 521 };
 522
 523 //////////////////////////////////////////////////////////////////////
 524
 525 using TypeAlias = ::HPHP::TypeAlias;
 526
 527 //////////////////////////////////////////////////////////////////////
 528
 529 /*
 530  * Representation of a php file (normal compilation unit).
 531  */
 532 struct Unit {
 533   MD5 md5;
 534   SString filename;
 535   int preloadPriority{0};
 536   std::unique_ptr<Func> pseudomain;
 537   std::vector<std::unique_ptr<Func>> funcs;
 538   std::vector<std::unique_ptr<Class>> classes;
 539   std::vector<std::unique_ptr<TypeAlias>> typeAliases;
 540 };
 541
 542 /*
 543  * A php Program is a set of compilation units.
 544  */
 545 struct Program {
 546   std::vector<std::unique_ptr<Unit>> units;
 547 };
 548
 549 //////////////////////////////////////////////////////////////////////
 550
 551 std::string show(const Func&);
 552 std::string show(const Class&);
 553 std::string show(const Unit&);
 554 std::string show(const Program&);
 555 std::string local_string(borrowed_ptr<const php::Local>);
 556
 557 //////////////////////////////////////////////////////////////////////
 558
 559 bool check(const Func&);
 560 bool check(const Class&);
 561 bool check(const Unit&);
 562 bool check(const Program&);
 563
 564 //////////////////////////////////////////////////////////////////////
 565
 566 }}}
 567
 568 #endif