1 /****************************************************************************** 2 * 3 * Copyright (C) 1997-2015 by Dimitri van Heesch. 4 * 5 * Permission to use, copy, modify, and distribute this software and its 6 * documentation under the terms of the GNU General Public License is hereby 7 * granted. No representations are made about the suitability of this software 8 * for any purpose. It is provided "as is" without express or implied warranty. 9 * See the GNU General Public License for more details. 10 * 11 * Documents produced by Doxygen are derivative works derived from the 12 * input used in their production; they are not affected by this license. 13 * 14 */ 15 16 #ifndef VHDLDOCGEN_H 17 #define VHDLDOCGEN_H 18 19 /** 20 * This class implements functions for parsing and generating 21 * vhdl documents 22 */ 23 24 #include "qcstring.h" 25 #include "layout.h" 26 #include "arguments.h" 27 #include "entry.h" 28 29 class Entry; 30 class ClassDef; 31 class MemberList; 32 class MemberDef; 33 class MemberDefMutable; 34 class OutputList; 35 class Definition; 36 class GroupDef; 37 class FileDef; 38 class NamespaceDef; 39 class TextStream; 40 struct Argument; 41 42 struct VhdlConfNode 43 { VhdlConfNodeVhdlConfNode44 VhdlConfNode(const QCString &a,const QCString &b,const QCString &config,const QCString &cs,bool leaf) 45 { 46 arch=a; // architecture e.g. for iobuffer 47 arch=arch.lower(); 48 binding=b; // binding e.g. use entity work.xxx(bev) 49 binding=binding.lower(); 50 confVhdl=config; // configuration foo is bar 51 compSpec=cs; 52 isInlineConf=false; // primary configuration? 53 isLeaf=leaf; 54 }; 55 56 QCString confVhdl; 57 QCString arch; 58 QCString binding; 59 QCString compSpec; 60 int level = 0; 61 bool isLeaf = false; 62 bool isInlineConf = false; 63 64 }; 65 66 67 /** Class for generating documentation specific for VHDL */ 68 class VhdlDocGen 69 { 70 public: 71 72 enum VhdlClasses // Overlays: Protection 73 { 74 ENTITYCLASS, // Overlays: Public 75 PACKBODYCLASS, // Overlays: Protected 76 ARCHITECTURECLASS, // Overlays: Private 77 PACKAGECLASS // Overlays: Package 78 }; 79 80 enum VhdlKeyWords 81 { 82 LIBRARY=1, 83 ENTITY, 84 PACKAGE_BODY, 85 ARCHITECTURE, 86 PACKAGE, 87 ATTRIBUTE, 88 SIGNAL, 89 COMPONENT, 90 CONSTANT, 91 TYPE, 92 SUBTYPE, 93 FUNCTION, 94 RECORD, 95 PROCEDURE, 96 USE, 97 PROCESS, 98 PORT, 99 UNITS, 100 GENERIC, 101 INSTANTIATION, 102 GROUP, 103 VFILE, 104 SHAREDVARIABLE, 105 CONFIG, 106 ALIAS, 107 MISCELLANEOUS, 108 UCF_CONST 109 }; 110 111 VhdlDocGen(); 112 virtual ~VhdlDocGen(); 113 static void init(); 114 static QCString convertFileNameToClassName(QCString name); 115 // --- used by vhdlscanner.l ----------- 116 117 static bool isSubClass(ClassDef* cd,ClassDef *scd, bool followInstances,int level); 118 119 static QCString getIndexWord(const QCString &,int index); 120 static bool deleteCharRev(QCString &s,char c); 121 static void deleteAllChars(QCString &s,char c); 122 static void parseFuncProto(const QCString &text, 123 QCString& name, 124 QCString& ret, 125 bool doc=false); 126 // ----------------------------------- 127 128 static void computeVhdlComponentRelations(); 129 130 static const char* findKeyWord(const QCString& word); 131 132 static ClassDef* getPackageName(const QCString& name); 133 static const MemberDef* findMember(const QCString& className, 134 const QCString& memName); 135 static void findAllPackages(ClassDef*); 136 static const MemberDef* findMemberDef(ClassDef* cd, 137 const QCString& key, 138 MemberListType type); 139 static ClassDef *getClass(const QCString &name); 140 static const MemberDef* findFunction(const QCString& name, 141 const QCString& package); 142 static QCString getClassTitle(const ClassDef*); 143 static void writeInlineClassLink(const ClassDef*, 144 OutputList &ol); 145 static void writeTagFile(MemberDefMutable *mdef,TextStream &tagFile); 146 147 static bool isConstraint(const MemberDef *mdef); 148 static bool isConfig(const MemberDef *mdef); 149 static bool isAlias(const MemberDef *mdef); 150 static bool isLibrary(const MemberDef *mdef); 151 static bool isGeneric(const MemberDef *mdef); 152 static bool isPort(const MemberDef *mdef); 153 static bool isComponent(const MemberDef *mdef); 154 static bool isPackage(const MemberDef *mdef); 155 static bool isEntity(const MemberDef *mdef); 156 static bool isConstant(const MemberDef *mdef); 157 static bool isVType(const MemberDef *mdef); 158 static bool isSubType(const MemberDef *mdef); 159 static bool isVhdlFunction(const MemberDef *mdef); 160 static bool isProcess(const MemberDef *mdef); 161 static bool isSignal(const MemberDef *mdef); 162 static bool isAttribute(const MemberDef *mdef); 163 static bool isSignals(const MemberDef *mdef); 164 static bool isProcedure(const MemberDef *mdef); 165 static bool isRecord(const MemberDef *mdef); 166 static bool isArchitecture(const MemberDef *mdef); 167 static bool isUnit(const MemberDef *mdef); 168 static bool isPackageBody(const MemberDef *mdef); 169 static bool isVariable(const MemberDef *mdef); 170 static bool isFile(const MemberDef *mdef); 171 static bool isGroup(const MemberDef *mdef); 172 static bool isCompInst(const MemberDef *mdef); 173 static bool isMisc(const MemberDef *mdef); 174 175 //----------------------------------------------------- 176 177 static void prepareComment(QCString&); 178 static void formatString(const QCString&,OutputList& ol,const MemberDef*); 179 180 static void writeFormatString(const QCString&,OutputList& ol,const MemberDef*); 181 static void writeFunctionProto(OutputList& ol,const ArgumentList &al,const MemberDef*); 182 static void writeProcessProto(OutputList& ol,const ArgumentList &al,const MemberDef*); 183 static void writeProcedureProto(OutputList& ol, const ArgumentList &al,const MemberDef*); 184 static bool writeFuncProcDocu(const MemberDef *mdef, OutputList& ol,const ArgumentList &al,bool type=false); 185 static void writeRecordProto(const MemberDef *mdef, OutputList& ol,const ArgumentList &al); 186 187 static bool writeVHDLTypeDocumentation(const MemberDef* mdef, const Definition* d, OutputList &ol); 188 189 static void writeVhdlDeclarations(const MemberList*,OutputList&,const GroupDef*,const ClassDef*,const FileDef*,const NamespaceDef*); 190 191 static void writeVHDLDeclaration(const MemberDefMutable* mdef,OutputList &ol, 192 const ClassDef *cd,const NamespaceDef *nd,const FileDef *fd,const GroupDef *gd, 193 bool inGroup); 194 195 static void writePlainVHDLDeclarations(const MemberList* ml,OutputList &ol, 196 const ClassDef *cd,const NamespaceDef *nd,const FileDef *fd,const GroupDef *gd, 197 uint64_t specifier); 198 199 static void writeVHDLDeclarations(const MemberList* ml,OutputList &ol, 200 const ClassDef *cd,const NamespaceDef *nd,const FileDef *fd,const GroupDef *gd, 201 const QCString &title,const QCString &subtitle,bool showEnumValues,int type); 202 203 static bool writeClassType(const ClassDef *,OutputList &ol ,QCString & cname); 204 205 static QCString convertArgumentListToString(const ArgumentList &al,bool f); 206 static QCString getProcessNumber(); 207 static QCString getRecordNumber(); 208 209 static QCString getClassName(const ClassDef*); 210 static bool isNumber(const std::string& s); 211 static QCString getProtectionName(int prot); 212 213 static void parseUCF(const char* input,Entry* entity,const QCString &f,bool vendor); 214 215 static const ClassDef* findArchitecture(const ClassDef *cd); 216 217 static void correctMemberProperties(MemberDefMutable *md); 218 219 static void writeSource(const MemberDefMutable *mdef,OutputList& ol,const QCString & cname); 220 221 static QCString parseForConfig(QCString & entity,QCString & arch); 222 static QCString parseForBinding(QCString & entity,QCString & arch); 223 static void addBaseClass(ClassDef* cd,ClassDef *ent); 224 static ClassDef* findVhdlClass(const QCString &className ); 225 226 static void writeOverview(OutputList &ol); 227 static void writeOverview(); 228 229 // flowcharts 230 static void createFlowChart(const MemberDef*); 231 //static void addFlowImage(const TextStream &,const QCString &); 232 233 static void setFlowMember( const MemberDef *flowMember); 234 static const MemberDef *getFlowMember(); 235 isVhdlClass(const Entry * cu)236 static bool isVhdlClass (const Entry *cu) 237 { 238 return cu->spec==VhdlDocGen::ENTITY || 239 cu->spec==VhdlDocGen::PACKAGE || 240 cu->spec==VhdlDocGen::ARCHITECTURE || 241 cu->spec==VhdlDocGen::PACKAGE_BODY; 242 } 243 244 static void resetCodeVhdlParserState(); 245 246 private: 247 static void findAllArchitectures(std::vector<QCString>& ql,const ClassDef *cd); 248 static bool compareArgList(const ArgumentList &,const ArgumentList &); 249 static void writeVhdlLink(const ClassDef* cdd ,OutputList& ol,QCString& type,QCString& name,QCString& beh); 250 static void writeStringLink(const MemberDef *mdef,QCString mem,OutputList& ol); 251 static void writeRecUnitDocu( const MemberDef *md, OutputList& ol,QCString largs); 252 static void writeRecordUnit(QCString & largs,QCString & ltype,OutputList& ol,const MemberDefMutable *mdef); 253 }; 254 255 //------------------------------------------------------------------------------------------------------------------- 256 //-------------- VHDL Flowcharts ------------------------------------------------------------------------------- 257 //------------------------------------------------------------------------------------------------------------------- 258 259 260 //#define DEBUGFLOW 261 262 class FlowChart 263 { 264 public: 265 enum nodeTypes { 266 IF_NO = 1<<1, 267 ELSIF_NO = 1<<2, 268 ELSE_NO = 1<<3, 269 CASE_NO = 1<<4, 270 WHEN_NO = 1<<5, 271 EXIT_NO = 1<<6, 272 END_NO = 1<<7, 273 TEXT_NO = 1<<8, 274 START_NO = 1<<9, 275 ENDIF_NO = 1<<10, 276 FOR_NO = 1<<11, 277 WHILE_NO = 1<<12, 278 END_LOOP = 1<<13, 279 END_CASE = 1<<14, 280 VARIABLE_NO = 1<<15, 281 RETURN_NO = 1<<16, 282 LOOP_NO = 1<<17, 283 NEXT_NO = 1<<18, 284 EMPTY_NO = 1<<19, 285 COMMENT_NO = 1<<20, 286 BEGIN_NO = 1<<21 287 }; 288 289 //---------- create svg ------------------------------------------------------------- 290 static void createSVG(); 291 static void startDot(TextStream &t); 292 static void endDot(TextStream &t); 293 static void codify(TextStream &t,const QCString &str); 294 static void writeShape(TextStream &t,const FlowChart &fl); 295 static void writeEdge(TextStream &t,int fl_from,int fl_to,int i,bool bFrom=FALSE,bool bTo=FALSE); 296 static void writeEdge(TextStream &t,const FlowChart &fl_from,const FlowChart &fl_to,int i); 297 static void writeFlowLinks(TextStream &t); 298 299 static QCString getNodeName(int n); 300 static void colTextNodes(); 301 302 static size_t getNextIfLink(const FlowChart&,size_t); 303 static size_t getNextNode(size_t index,int stamp); 304 static size_t findNode(size_t index,int stamp,int type); 305 static size_t findNode(size_t index,int type); 306 static size_t findNextLoop(size_t j,int stamp); 307 static size_t findPrevLoop(size_t j,int stamp,bool endif=FALSE); 308 static size_t findLabel(size_t j,const QCString &); 309 static void delFlowList(); 310 static const char* getNodeType(int c); 311 312 static void addFlowChart(int type,const QCString &text,const QCString &exp,const QCString &label=QCString()); 313 static void moveToPrevLevel(); 314 static int getTimeStamp(); 315 static void writeFlowChart(); 316 static void alignFuncProc(QCString & q,const ArgumentList &al,bool isFunc); 317 static QCString convertNameToFileName(); 318 static void printNode(const FlowChart& n); 319 static void printFlowTree(); 320 static void buildCommentNodes(TextStream &t); 321 static void alignCommentNode(TextStream &t,QCString com); 322 323 static void printUmlTree(); 324 static QCString printPlantUmlNode(const FlowChart &flo,bool,bool); 325 326 FlowChart(int typ,const QCString &t,const QCString &ex,const QCString &label=QCString()); 327 ~FlowChart(); 328 329 private: 330 int id = 0; 331 int stamp = 0; 332 int type = 0; 333 334 int line = 0; 335 336 QCString label; 337 QCString text; 338 QCString exp; 339 }; 340 341 extern std::vector<FlowChart> flowList; 342 343 #endif 344