1 // Copyright 2017-2019 VMware, Inc.
2 // SPDX-License-Identifier: BSD-2-Clause
3 //
4 // The BSD-2 license (the License) set forth below applies to all parts of the
5 // Cascade project.  You may not use this file except in compliance with the
6 // License.
7 //
8 // BSD-2 License
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are met:
12 //
13 // 1. Redistributions of source code must retain the above copyright notice, this
14 // list of conditions and the following disclaimer.
15 //
16 // 2. Redistributions in binary form must reproduce the above copyright notice,
17 // this list of conditions and the following disclaimer in the documentation
18 // and/or other materials provided with the distribution.
19 //
20 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND
21 // ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
22 // WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 // DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24 // FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 // DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26 // SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27 // CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 // OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 
31 #ifndef CASCADE_SRC_VERILOG_ANALYZE_RESOLVE_H
32 #define CASCADE_SRC_VERILOG_ANALYZE_RESOLVE_H
33 
34 #include <string>
35 #include "common/vector.h"
36 #include "verilog/ast/visitors/editor.h"
37 
38 namespace cascade {
39 
40 // This class is used to associate variable uses with their declarations in the
41 // AST. This class attaches decorations to the AST to reduce the overhead of
42 // repeated invocations and relies on up-to-date scope decorations (see
43 // navigate.h). If the decorations associated with a scope are invalidated or
44 // if the variables within a scope are transformed in any way, this class must
45 // invalidate the resolution decorations for any variables that refer to that
46 // scope before it will work correctly.
47 
48 class Resolve {
49   public:
50     // Typedefs:
51     typedef typename Vector<const Expression*>::const_iterator use_iterator;
52 
53     // Cache Maintenance:
54     //
55     // Removes dependency references for this node and all of the nodes below
56     // it in the AST.
57     void invalidate(const Node* n);
58 
59     // Resolution:
60     //
61     // Returns a pointer to the declaration of this variable. Returns nullptr
62     // on failure.
63     const Identifier* get_resolution(const Identifier* id);
64     // Returns the fully-qualified name of this variable. For example, eg
65     // get_full_id(x) might return root.f[0].x. The caller of this method
66     // takes responsibility for the resulting memory.
67     Identifier* get_full_id(const Identifier* id);
68     // Convenience method. Converts an id to a full id, transforms it to a
69     // string and deletes the intermediate memory.
70     std::string get_readable_full_id(const Identifier* id);
71     // Returns a pointer to the ModuleDeclaration that this identifier appears
72     // in. Returns nullptr on failure. For example, for variables that are not
73     // part of the AST.
74     const ModuleDeclaration* get_parent(const Identifier* id);
75     // Returns a pointer to the ModuleDeclaration that this identifier was
76     // declared in. Equivalent to calling get_origin(get_resolution(id)).
77     const ModuleDeclaration* get_origin(const Identifier* id);
78 
79     // Variable Properties:
80     //
81     // Returns true if this variable contains a slicing subscript. This method
82     // is undefined for identifiers which cannot be resolved.
83     bool is_slice(const Identifier* id);
84     // Returns true for any variable which does not resolve to itself (ie a
85     // reference) or a variable which is part of a scalar declaration.
86     bool is_scalar(const Identifier* id);
87     // Returns false for any variable which does not resolve to itself (ie a
88     // reference) or true for a variable which is part of an array
89     // declaration.
90     bool is_array(const Identifier* id);
91 
92     // Iterators Interface:
93     //
94     // Iterators over the set of expressions that refer to this variable.  For
95     // example, the expression i+1 uses the value of i. Invoking this method on
96     // a variable which cannot be resolved is undefined.
97     use_iterator use_begin(const Identifier* id);
98     use_iterator use_end(const Identifier* id);
99 
100   private:
101     // Cached accessor helpers:
102     const Identifier* cache_resolution(const Identifier* id);
103     void cache_uses(const Declaration* d);
104 
105     // Examines every declaration below this node and inserts an empty use set
106     struct InitCacheUses : Editor {
107       ~InitCacheUses() override = default;
108       void edit(CaseGenerateConstruct* cgc) override;
109       void edit(IfGenerateConstruct* igc) override;
110       void edit(LoopGenerateConstruct* lgc) override;
111       void edit(GenvarDeclaration* gd) override;
112       void edit(LocalparamDeclaration* ld) override;
113       void edit(NetDeclaration* nd) override;
114       void edit(ParameterDeclaration* pd) override;
115       void edit(RegDeclaration* rd) override;
116       void edit(ModuleInstantiation* mi) override;
117     };
118     // Populates use sets
119     struct CacheUses : Editor {
120       ~CacheUses() override = default;
121       void edit(Attributes* as) override;
122       void edit(Identifier* i) override;
123       void edit(CaseGenerateConstruct* cgc) override;
124       void edit(IfGenerateConstruct* igc) override;
125       void edit(LoopGenerateConstruct* lgc) override;
126       void edit(GenvarDeclaration* gd) override;
127       void edit(LocalparamDeclaration* ld) override;
128       void edit(NetDeclaration* nd) override;
129       void edit(ParameterDeclaration* pd) override;
130       void edit(RegDeclaration* rd) override;
131       void edit(ModuleInstantiation* mi) override;
132     };
133     // Invalidation cache information:
134     struct Invalidate : Editor {
135       ~Invalidate() override = default;
136       void edit(Attributes* as) override;
137       void edit(Identifier* id) override;
138       void edit(CaseGenerateConstruct* cgc) override;
139       void edit(IfGenerateConstruct* igc) override;
140       void edit(LoopGenerateConstruct* lgc) override;
141       void edit(GenvarDeclaration* gd) override;
142       void edit(LocalparamDeclaration* ld) override;
143       void edit(NetDeclaration* nd) override;
144       void edit(ParameterDeclaration* pd) override;
145       void edit(RegDeclaration* rd) override;
146       void edit(ModuleInstantiation* mi) override;
147     };
148 };
149 
150 } // namespace cascade
151 
152 #endif
153