diff --git a/report/sprints/sprint4.tex b/report/sprints/sprint4.tex index e80a1163..0a941be9 100644 --- a/report/sprints/sprint4.tex +++ b/report/sprints/sprint4.tex @@ -62,11 +62,11 @@ \subsection{Back Log} \textbf{Impl.} & & \textbf{47} & \textbf{24} \\ US56 & FR2-E: Guess \gls{dissector} from \gls{packet} size & 5 & 3 \\ US40 & FR3-A mod: Support \gls{include} of system \glspl{header} & 8 & 3 \\ - US41 & FR3-D mod: Ignore \#pragma directives & 2 & 1 \\ + US41 & FR3 mod: Ignore \#pragma directives & 2 & 1 \\ US42 & FR3-A mod: Find include dependencies which are not explicitly set & 16 & 11 \\ US47 & FR4-B mod: Custom \Gls{lua} files support inside a .cnf file & 4 & 1 \\ US49 & FR4-D mod: Multiple message ID's for one \gls{dissector} & 2 & 1 \\ - US52 & FR4-H:Automatic generation of placeholder configuration & 1 & 0.5\\ + US53 & FR4-H:Automatic generation of placeholder configuration & 1 & 0.5\\ US51 & FR4-I: Support specifying the size of unknown struct members & 4 & 1 \\ US43 & FR6-E: Support C \#defines and --Include from CLI & 1 & 1 \\ US54 & FR6-F: Only generate dissectors for structs with valid ID & 4 & 1.5 \\ @@ -94,7 +94,7 @@ \subsection{Back Log} US44 & Update command line interface document & 1 & 1 \\ US48 & Update user documentation for custom \Gls{lua} & 1 & 1.5 \\ US50 & Update user documentation for message ID & 1 & 1 \\ - US53 & User documentation for \gls{struct} size configuration & 1 & 1 \\ + US52 & User documentation for \gls{struct} size configuration & 1 & 1 \\ US55 & User documentation for generating only \gls{struct} with valid ID or dependencies & 1 & 1 \\ US36 & Which platforms that the \gls{utility} supports & 2 & 1 \\ US58 & How to define new platforms to support & 1 & 3.5 \\ @@ -261,27 +261,27 @@ \subsection{User Stories} Result & The administrator is now able to make the \gls{utility} generate system dependent \glspl{dissector} for \glspl{header} with system dependent includes. \\ \midrule ID & US41 \\ - Requirement & FR3-D: Ignoring \#pragma directives \\ + Requirement & FR3 modification: Ignoring \#pragma directives \\ What & The \gls{utility} needs to be able to support \gls{header} files with the \#pragma directive without necessarily having to support the functionality of the directive\\ How & Before feeding the \gls{header} files to the \gls{parser}, the \gls{utility} needs to be able to run a pass through all of the \glspl{header} that are to be parsed and remove all of the \#pragma directives encountered in those \gls{header} files.\\ Result & The user will be able to create \glspl{dissector} for \gls{header} files with the \#pragma directive instead of having the \gls{utility} be forced to skip them. \\ \midrule ID & US42 \\ - Requirement & FR3-E: Find missing includes \\ + Requirement & FR3-A modification: Find include dependencies which are not explicitly set \\ What & It should be possible to generate \gls{dissector} from \gls{header}-files, that have definitions in \gls{header}-files that are not included with a \gls{preprocessor} directive in the \gls{header}-file. \\ How & The cparser module has to be able to detect when an exception is raised in the \gls{pycparser} \gls{library}, if an exception is raised, cparser has to search through the \gls{header}-files to find the declaration that the \gls{pycparser} \gls{library} failed on, and include this \gls{header} file. The cparser module will have to do this procedure until the \gls{dissector} is correctly parsed in the \gls{pycparser} \gls{library}. \\ Result & The \gls{utility} shall be able to generate \glspl{dissector} for these \gls{header}-files \\ \midrule ID & US43 \\ - Requirement & FR6-E: Support \Gls{c} \glspl{define} from \gls{cli} \\ + Requirement & FR6-E: Support C \#defines and --Include from CLI \\ What & The administrator wants to pass \Gls{c} \gls{define} directives from the command-line to the \gls{preprocessor}. \\ How & When CSjark is executed, it takes the arguments given in the command-line interface and store them in the config module. The \gls{define} directives must be added to the \gls{preprocessor} arguments before the \gls{header}-file is parsed in the \gls{pycparser} \gls{library}. \\ Result & The \gls{utility} supports \Gls{c} \gls{define} directives passed from the \gls{cli}. \\ \midrule ID & US44 \\ - User doc & FR6-E: Support \Gls{c} \glspl{define} from \gls{cli} \\ + User doc & FR6-E: Support C \#defines and --Include from CLI \\ What & The user wants to understand how the \gls{utility} will handle \Gls{c} \glspl{define} and what \glspl{define} that are possible to pass to the \gls{cli}. \\ How & The user finds the correct section in the user documentation, describing the command-line interface and how \Gls{c} \glspl{define} are handled. \\ Result & The user understands how to use \Gls{c} \glspl{define} with the \gls{utility}. \\ @@ -297,27 +297,27 @@ \subsection{User Stories} Header & Value \\ \midrule ID & US45 \\ - Requirement & FR7-A: Use Doxygen comments for ''Description'' \\ + Requirement & FR7-A: Find struct descriptions from Doxygen comments \\ What & The \gls{utility} will read Doxygen comments for a \gls{struct} and use that to specify the description field for the proto object in the \gls{dissector}. \\ How & The \gls{utility} will search the \gls{header} files for Doxygen comments before giving the file to the \gls{preprocessor}. It will note what \gls{struct} the comment corresponds to and add it to the config module. The \gls{dissector} module will look up in the config module for each \gls{struct} and use the description field there if it has been found. \\ Result & The \glspl{dissector} now requires less manual configuration because it is able to use some of the text from the \gls{header} files. \\ \midrule ID & US46 \\ - Requirement & FR7-B: Read \gls{int}-\gls{enum} config from \gls{header} files \\ + Requirement & FR7-B: Find configuration of \#define enums from header files \\ What & The \gls{utility} will read \gls{define} statements that define the allowed values and the names corresponding to those values for integers that are to be treated like enums, so that the user will not have to configure them manually.\\ How & The \gls{utility} will search the \gls{header} files for define statements that corresponds to a \gls{member} that is configured to be handled as an \gls{enum}. The statements needs to follow some configurable format. These statements are then used to auto generate a configuration file for the \gls{int} \gls{member} used to make an \gls{enum} field for the \gls{int} \gls{member} when parsing the \gls{header} file.\\ Result & The \gls{utility} now requires less manual configurations to make \glspl{dissector} interpret certain \glspl{integer} as \glspl{enum}. \\ \midrule ID & US47 \\ - Requirement & Fetch offset in custom \Gls{lua} configuration \\ + Requirement & FR4-B modification: Fetch offset in custom \Gls{lua} configuration \\ What & The administrator should be able to add configuration in the conformance file, so it is possible to add custom \Gls{lua} code with correct offset values. \\ How & The conformance file must support a variable for offset, and a way to use this. The config module have to read this variable, so it can be used in the \gls{dissector} module to generate a field in the \gls{dissector} that uses the correct offset. \\ Result & The \Gls{lua} \gls{dissector} is generated with correct offset for the custom \Gls{lua} code. \\ \midrule ID & US48 \\ - User doc & Fetch offset in custom \Gls{lua} configuration \\ + User doc & FR4-B modification: Fetch offset in custom \Gls{lua} configuration \\ What & The administrator shall learn how to use offset values in custom \Gls{lua} configuration. \\ How & The administrator reads the section in the user documentation, about how to use custom \Gls{lua} in the \gls{utility}. \\ Result & The user will understand how to add offset values in the conformance file. \\ @@ -346,25 +346,25 @@ \subsection{User Stories} Result & The administrator is able to specify and use multiple message ID’s for a specific \gls{struct}. \\ \midrule ID & US51 \\ - Requirement & FR4-I: Allow configuration to specify the size of unknown \gls{struct} \glspl{member} \\ + Requirement & FR4-I: Support specifying the size of unknown struct members \\ What & The administrator should be able specify in the configuration, how big (in bytes) the \gls{struct} \gls{member} is without having the \gls{member} itself defined. Note: This is also a workaround for \glspl{struct} that are not parse-able.\\ How & The configuration should contain an optional attribute for each \gls{struct} \gls{member} which specifies the size of the \gls{member}. If this \gls{member} is a nested \gls{struct}, and this \gls{struct} is not defined, the size has to be specified. Otherwise the user should be informed about that.\\ Result & The \Gls{lua} \gls{dissector} can be used with \Gls{c} \gls{header} that includes unspecified \gls{struct} \gls{member}. This \gls{member} was only defined by its size, so it could be displayed as raw data in \Gls{wireshark}. \\ \midrule ID & US52 \\ - User doc & FR4-I: Allow configuration to specify the size of unknown \gls{struct} \glspl{member} \\ + User doc & FR4-I: Support specifying the size of unknown struct members \\ What & The administrator should be able to find out how to specify in the configuration, how big (in bytes) the \gls{struct} \gls{member} is without having the \gls{member} itself defined. \\ How & The administrator reads the configuration section in the user documentation, about how to specify the size of the \gls{struct} \glspl{member}. \\ Result & The user is able to specify the size of unknown \gls{struct} \gls{member}. \\ \midrule ID & US53 \\ - User doc & Auto generate configuration files for \glspl{struct} with no corresponding configuration file \\ + Requirement & FR4-H:Automatic generation of placeholder configuration \\ What & The \gls{utility} will generate template configuration files if it encounters \glspl{struct} with no corresponding configuration file. This is to make it easier to make such a configuration file. \\ How & The cparser module checks if an encountered \gls{struct} has a corresponding configuration in the config module. If not, the \gls{utility} writes a template file for this \gls{struct}. \\ Result & The user will now be able to use the auto generated template file to write the configuration for a \gls{struct} instead of having to start from scratch. \\ \midrule ID & US54 \\ - Requirement & Only generate \glspl{dissector} for \glspl{struct} that have a valid ID and their dependencies \\ + Requirement & FR6-F: Only generate dissectors for structs with valid ID \\ What & The \gls{utility} should only generate \glspl{dissector} for \glspl{struct} that have a configuration file with a valid ID and their dependencies. \\ How & When the \gls{utility} discovers a \gls{struct} definition inside a \gls{header} file it should check if there exists a configuration file for that \gls{struct} and if it has a valid ID. If not then the \gls{utility} should skip that \gls{struct} and continue with the \gls{header} file. If a \gls{struct} with a valid configuration file and ID has a \gls{member} that is not defined in the current \gls{header} @@ -383,13 +383,13 @@ \subsection{User Stories} Header & Value \\ \midrule ID & US55 \\ - User doc & Only generate \glspl{dissector} for \glspl{struct} that have a valid ID and their dependencies \\ + User doc & FR6-F: Only generate dissectors for structs with valid ID \\ What & The administrator should be able to specify in the configuration which \glspl{struct} should have \glspl{dissector} created for them. \\ How & The administrator reads the configuration section in the \gls{utility}’s user documentation that specifies how to specify which \glspl{struct} should have a \gls{dissector} generated for them. \\ Result & The user will be able to specify which \glspl{struct} the \gls{utility} will generate \glspl{dissector} for. \\ \midrule ID & US56 \\ - Requirement & Guess \gls{dissector} by \gls{packet} size \\ + Requirement & FR2-E: Guess \gls{dissector} from \gls{packet} size \\ What & The \gls{utility} should be able to generate a \Gls{lua} file that runs with \Gls{wireshark} and guesses the \gls{dissector} that is to be used for a \gls{packet}, if it has a message ID that does not match any pre-existing \gls{dissector}.\\ How & The luastructs.lua file that is generated by the \gls{utility} should contain a dictionary of all \glspl{dissector}, sorted by the size of the \glspl{struct} that they are associated with. When a \gls{packet} with an unrecognized message ID is discovered by \Gls{wireshark}, the code in the luastructs. \Gls{lua} file should try to match the unidentified \gls{packet} with a \gls{dissector} @@ -398,7 +398,7 @@ \subsection{User Stories} This \gls{packet} should also be displayed with a warning. \\ \midrule ID & US57 \\ - Requirement & Display if \gls{struct} \gls{member} contains uninitialized memory \\ + Requirement & FR2-F: Display if struct member contains uninitialized memory \\ What & The \glspl{dissector} generated by the \gls{utility} should be able to identify \gls{struct} \glspl{member} that might possibly have uninitialized memory set as their values. These \glspl{member} and their values should be displayed with a warning in \Gls{wireshark} to indicate that the values might have been uninitialized. \\ How & If the \Gls{c}-code that uses \gls{header} files isn’t using memset to set the initial values of different variables a \gls{parser} might decide to fill uninitialized variables with some kind of patterned garbage data.