Merge branch 'matteo_branch' into 'master'

Adding chapter "how to add a graphical component in TTool" in .doc/dev_infrastructure/dev_infrastucture.tex

See merge request !40

doc/dev_infrastructure/ttool_development_infrastructure.tex

@@ -44,7 +44,7 @@
 \large
 \centering
 \begin{adjustbox}{width=\textwidth}
-\begin{tabular}{ |p{1.6cm}|p{6.0cm}|p{4.2cm}|p{4.2cm}| }
+\begin{tabular}{ |p{1.6cm}|p{6.0cm}|p{4.4cm}|p{4.2cm}| }
 \hhline{----}
  & \textbf{Document Manager} & \textbf{Contributors}  & \textbf{Checked by}  \\ 
 \hhline{----}
@@ -53,7 +53,7 @@
 \hhline{--~~}
 \textbf{Contact} & dominique.blouin@telecom-paristech.fr &  &  \\ 
 \hhline{--~~}
-\textbf{Date} & \today &  &  \\ 
+\textbf{Date} & \today & Matteo BERTOLINO &  \\ 
 \hline
 \end{tabular}
 \end{adjustbox}
@@ -892,4 +892,126 @@ TODO
 \section{Installing}
 TODO
 
+\section{Adding a graphic component}
+This section addresses the adding of a specific graphical component (i.e., the FPGA), that is part of the set of \textit{computational units} such as CPUs, but the steps listed are valid for any kind of graphical component like memories or communication systems. Remember to git add each new file that you create! Remember also to change properly the \texttt{import} at the beginning of a class if necessary. Adding a new component requires a serie of steps listed ad follows: 
+
+\paragraph{Deployment diagram:} The complete list of diagrams is located in \texttt{.src/ui} directory. In order to add a graphical component we are interested in \textit{TML Deployment Diagrams} that are in \texttt{.tmldd} subdirectory. Since FPGAs' models have lots of analogies with CPUs' models, we duplicated the class TMLArchiCPUNode.java naming it TMLArchiFPGANode.java. The main changes to do in this new class are: 
+\begin{itemize}
+\item Change the \texttt{String stereotype} value
+\item Modify the list of attributes adding or removing items: for example, we do not need the parameter \textit{number of cores} to describe the FPGA, so we removed \texttt{private int nbOfCores = HwCPU.DEFAULT\_NB\_OF\_CORES;}
+\item On the other hand we need for a parameter that expresses the \textit{capacity} of the FPGA in terms of area, so we added 
+\texttt{private int capacity = HwCPU.DEFAULT\_CAPACITY;}
+\item Let's change the graphic parameters as you wish: the connecting points, the fact to make the diagrams editable, etc
+\item Handle the lines like \texttt{if (dialog.getNbOfCores().length() != 0)} according with your previous modifications on the perameters' list. You can notice the usage of the \texttt{tmp} variable to recover the values in the case that the user closes the window.
+\item The method \texttt{public int getType()} return an unique ID, defined in \texttt{TGComponentManager.java}. Change the method, then open the new class and add the new id with an associated number (e.g., \texttt{public static final int TMLARCHI\_FPGANODE = 1116;}). You have to choose an available number!
+\item Modify the \texttt{protected String translateExtraParam()} method useful to save in xml the attributes whose default value was changed.
+\texttt{sb.append("<attributes capacity=\"" + capacity + "\" byteDataSize=\"" + byteDataSize + "\" ");}
+\item Modify the \texttt{getAttribute()} methods according to the new parameters. These methods are useful for the action \textit{Show/Hide element attributes} triggered by an icon in the architectural diagram.
+\item In \texttt{TGComponentManager.java} you have also to add the new value that the \texttt{tgc} variable (that represents the graphical component) can take: \begin{verbatim}
+ case TMLARCHI_FPGANODE:
+                tgc = new TMLArchiFPGANode(x, y, tdp.getMinX(),
+                      tdp.getMaxX(), tdp.getMinY(), tdp.getMaxY(),
+                      false, null, tdp);
+                break;
+\end{verbatim}
+
+and 
+
+\begin{verbatim}
+else if (tgc instanceof TMLArchiFPGANode) {
+            return TMLARCHI_FPGANODE;
+\end{verbatim}
+\end{itemize}
+
+\paragraph{Icon:} 
+\begin{itemize}
+\item icons are stored in \texttt{.src/main/resources/ui/util}. You can easily use GIMP to create one of them, modifying an existing one to be sure to fit the proper dimensions.   
+\item The class \texttt{.src/main/java/ui/util/IconManager.java} is responsible to charge the icons. Let's assign a number to our icon. The convention is: an odd number for the \textit{big} sized icons, an even number for the \textit{small} sized icon. So, we assigned number 1120 to our new fpga icon: \texttt{private static String icon1120 = "tmlfpganode.gif";}
+\item Next to the \texttt{//TDD} comment, create an object icon: \texttt{public static ImageIcon imgic1120;}
+\item Associate the icon object to the previously defined string value: \texttt{imgic1120 = getIcon(icon1120);} 
+\end{itemize}
+
+\paragraph{Associate an action to the icon: } The actions' list is contained in the file \texttt{.src/main/java/ui/TGUIAction.java}.
+\begin{itemize}
+\item The first step is to associate a unique number to the action that we aim to create. Let's search in the code for the parameter \texttt{public static final int NB\_ACTION = 474;}. All the actions are in a table named \texttt{private static final TAction [] actions = new TAction[NB\_ACTION];}. So, the number associated to our action should be equal to the number present in \texttt{NB\_ACTION}. Moreover, we need to reserve one more space for the action in the table, so we increment \texttt{NB\_ACTION} by one. In this case, \texttt{public static final int NB\_ACTION = 475;}.
+\item Declare the action: taking inspiration from \texttt{public static final int TMLARCHI\_CPUNODE = 218;}, similarly we create \texttt{public static final int TMLARCHI\_FPGANODE = 474;}
+\item Then, add the action to the table, with the previously defined icon and a short description: 
+\begin{verbatim}
+actions[TMLARCHI_FPGANODE] = new TAction("add-tmlarchi-fpganode", 
+       "Add a FPGA node", IconManager.imgic1120, 
+       IconManager.imgic1120, "FPGA node", "Add a fpga node to the 
+       currently opened DIPLODOCUS architecture diagram", 0);
+\end{verbatim}
+
+\item Finally, it is necessary to create the graphic component of such ID when this action on a FPGA node is triggered. To do that, open \texttt{.src/main/java/ui/ActionPerformer.java} and search for the string \texttt{CPUNode}. Then, similarly add \begin{verbatim}
+else if (command.equals(mgui.actions[TGUIAction.TMLARCHI_FPGANODE]
+		.getActionCommand())) {
+            mgui.actionOnButton(TGComponentManager.COMPONENT, 
+            TGComponentManager.TMLARCHI_FPGANODE);
+\end{verbatim}
+
+\end{itemize}
+
+\paragraph{Show/Hide the icon: } the icon is not still present in the GUI. 
+\begin{itemize}
+\item Open \texttt{.src/main/java/ui/tmldd/TMLArchiDiagramToolBar.java}
+\item Set the icon as active: 
+\begin{verbatim}
+  protected void setActive(boolean b) {
+     //[...]
+     mgui.actions[TGUIAction.TMLARCHI_CPUNODE].setEnabled(b);
+     mgui.actions[TGUIAction.TMLARCHI_FPGANODE].setEnabled(b);
+     mgui.actions[TGUIAction.TMLARCHI_HWANODE].setEnabled(b);		
+     //[...]
+	}		
+		\end{verbatim}
+Notice that the order is important! For example, we aim to place the FPGA icon before the HWACC icon and after the CPU node. Let's notice also that in order to add the icon we do not manipulate the icon object, but the action!  
+\item Since the implementation of the FPGA block is not still ready when we realized the graphical block, we aim to hide the icon and make it available only running TTool/DIPLODOCUS with the flag \texttt{-experimental}. So, within the same class we can add the condition:
+\begin{verbatim}
+if (mgui.isExperimentalOn()) {
+            button = this.add(mgui.actions[TGUIAction.
+                     TMLARCHI_FPGANODE]);
+            button.addMouseListener(mgui.mouseHandler);
+        }
+\end{verbatim}
+\item Finally, we need to define the behavior of the method \texttt{isExperimentalOn()}. To do that, let's go in the class (\texttt{.src/main/java/ui/MainGUI.java}) and add it: 
+\begin{verbatim}
+    public boolean isExperimentalOn() {
+        return experimentalOn;
+    }
+\end{verbatim}
+\end{itemize}
+
+\paragraph{Towards TML: step 1} All the \textit{hardware FPGA} blocks have the parameter defined in a virtual component that does not take into account it graphical items but it is expressed in an intermediate language, TML. 
+
+\begin{itemize}
+\item Let's have a look to \texttt{src/main/java/tmltranslator/HwCPU.java} and copy/paste it renaming the file \texttt{src/main/java/tmltranslator/HwFPGA.java} (don't forget to change the imports, as usual).
+\item Modify the class according with your previous operations. In particular, the list of attributes shall be coherent with the attributes already declared, so in our case we removed stuff related to the number of cores and we added those to represent the FPGA like the capacity. Then set their default value. Modify \texttt{toXML()} (useful for the plugin) and \texttt{getType()} methods as well. 
+\item Some attributes seems miss, like \texttt{EXECI} and \texttt{EXECC}. Let's check to the father class \texttt{HwExecutionNode.java}, in the same package.
+\end{itemize}
+
+\paragraph{Dialog box: } then, we already defined almost all the graphical stuff like connectors, name displayed, etc. When we click on the component, a dialog box appears. We can use it to assign a value to the declared attributes, or to check their default value. The classes that handle the dialog box are usually in \texttt{.src/main/java/ui/window}. Some complex components have these classes in their own subdirectories. 
+\begin{itemize}
+\item Let's have a look to \texttt{JDialogCPUNode.java}, copy/paste it, git add and modify the import
+\item Let's modify properly this new JDialog class. For example, we modified the JText fields and the getters in accordance to the declared parameters, we modified the constructor and we removed the stuff in which we're not interested on. The latter includes the things related to the MEC (useful for the code generation), tracemode, the useless grids, everything after the getters. 
+\end{itemize}
+
+\paragraph{Towards TML: step 2} To translate graphical TML modeling to  "tmlmodeling" we rely on the class \texttt{.src/main/java/ui/GTMLModeling.java}. Exactly as \texttt{HwCPU cpu;} and \texttt{TMLArchiCPUNode node} we declared \texttt{HwFPGA fpga;} and \texttt{TMLArchiFPGANode fpgaNode}. Then, getting inspiration by the code that concerns the first two variables, add the equivalent code for FPGA.
+
+\paragraph{Save and Re-read TML: } 
+\begin{itemize}
+\item Open \texttt{./tmltranslator/TMLArchiTextSpecification.java}.
+\item Modify the string \texttt{private String keywords[] = {"NODE", "CPU", "FPGA", "SET", "BUS", "LINK", "BRIDGE", "MEMORY", "MASTERCLOCKFREQUENCY", "DMA"};} adding the FPGA information.
+\item Exactly how \texttt{private String cpuparameters[]}, declare \texttt{private String fpgaparameters[] = {"capacity", "byteDataSize", "mappingPenalty", "goIdleTime", "maxConsecutiveIdleCycles", "reconfigurationTime", "execiTime", "execcTime"};}. 
+\item In the method \texttt{public String makeNodes(TMLArchitecture tmla)} let's declare \texttt{HwFPGA fpga;} variable, then have a look to \texttt{if (node instanceof HwCPU)} and handle the corresponding FPGA case.
+\item To re-read, in \texttt{public int analyseInstruction(String \_line, int \_lineNb, String[] \_split)} have a look to \begin{verbatim}
+if (_split[1].equals("CPU")) {
+                HwCPU cpu = new HwCPU(_split[2]);
+                tmla.addHwNode(cpu);
+            }
+\end{verbatim}
+and do the same for FPGA
+\item Finally, in the same method, have a look to the case \texttt{if (node instanceof HwCPU)} and do the same for FPGA. To make the comparison easier, capitalize the name of the FPGA's parameters. 
+\end{itemize}   
+
 \end{document}