discovery.tex

\chapter{Parameters and Discovery}

This document defines a number of parameters for describing aspects of the encoder such as the 
widths of buses, the presence or absence of optional features and the size of resources, as 
listed in Tables~\ref{tab:iparameters} and ~\ref{tab:dparameters}.

Depending on the implementation, some parameters may be inherently fixed whilst others
may be passed in to the design by some means.

\begin{table}[h]
    \centering
    \caption{Parameters to the encoder - instruction trace}
    \label{tab:iparameters}
    \begin{tabulary}{\textwidth}{|l|l|p{100mm}|}
        \hline
        \textbf{Parameter name} & \textbf{Range} & \textbf{Description} \\
        \hline
        \textit{arch\_p} & & The architecture specification version with which the encoder is compliant (0 for initial version). \\
        \hline
        \textit{blocks\_p} & & Number of times \textbf{iretire}, \textbf{itype} etc. are replicated\\
        \hline
        \textit{bpred\_size\_p} & & Number of entries in the branch predictor is 2\textsuperscript{\textbf{bpred\_size\_p}}. 
                                    Minimum number of entries is 2, so a value of 0 indicates that there is no branch predictor implemented.\\
        \hline
        \textit{cache\_size\_p} & & Number of entries in the jump target cache is 2\textsuperscript{\textbf{cache\_size\_p}}. 
                                    Minimum number of entries is 2, so a value of 0 indicates that there is no jump target cache implemented.\\
        \hline
        \textit{call\_counter\_size\_p} &  & Number of bits in the nested call counter is 2\textsuperscript{\textbf{call\_counter\_size\_p}}.
                                    Minimum number of entries is 2, so a value of 0 indicates that there is no implicit return call counter implemented.\\
        \hline
        \textit{ctype\_width\_p} & & Width of the \textbf{ctype} bus\\
        \hline
        \textit{context\_width\_p} &  & Width of \textbf{context} bus \\
        \hline
        \textit{time\_width\_p} &  & Width of \textbf{time} bus \\
        \hline
        \textit{ecause\_width\_p} &  & Width of \textbf{exception cause} bus \\
        \hline
        \textit{ecause\_choice\_p} & & Number of bits of exception cause to match using multiple choice \\
        \hline
        \textit{f0s\_width\_p} & & Width of the \textbf{subformat} field in format 0 \textit{te\_inst} packets (see section~\ref{sec:f0s}). \\
        \hline
        \textit{filter\_context\_p} & 0 or 1 & Filtering on context supported when 1 \\
        \hline
        \textit{filter\_time\_p} & 0 or 1 & Filtering on time supported when 1 \\
        \hline
        \textit{filter\_excint\_p} & & Filtering on exception cause or interrupt supported when non\_zero.  Number of nested exceptions supported is 2\textsuperscript{filter\_excint\_p} \\
        \hline
        \textit{filter\_privilege\_p} & 0 or 1 & Filtering on privilege supported when 1 \\
        \hline
        \textit{filter\_tval\_p} & 0 or 1 & Filtering on trap value supported when 1 (provided \textit{filter\_excint\_p} is non-zero) \\
        \hline
        \textit{iaddress\_lsb\_p} & & LSB of instruction \textbf{address} bus to trace.  1 is compressed instructions are supported, 2 otherwise\\
        \hline
        \textit{iaddress\_width\_p} & & Width of instruction \textbf{address} bus. This is the same as \textit{DXLEN}\\
        \hline
        \textit{iretire\_width\_p} & & Width of the \textbf{iretire} bus\\
        \hline
        \textit{ilastsize\_width\_p} & & Width of the \textbf{ilastsize} bus\\
        \hline
        \textit{itype\_width\_p} & & Width of the \textbf{itype} bus\\
        \hline
        \textit{nocontext\_p} & 0 or 1 & Exclude context from \textit{te\_inst} packets if 1 \\
        \hline
        \textit{notime\_p} & 0 or 1 & Exclude time from \textit{te\_inst} packets if 1 \\
        \hline
        \textit{privilege\_width\_p} & & Width of \textbf{privilege} bus \\
        \hline
        \textit{retires\_p} &  & Maximum number of instructions that can be retired per block \\
        \hline
        \textit{return\_stack\_size\_p} &  & Number of entries in the return address stack is 2\textsuperscript{\textbf{return\_stack\_size\_p}}.
                                    Minimum number of entries is 2, so a value of 0 indicates that there is no implicit return stack implemented.\\
        \hline
        \textit{sijump\_p} & 0 or 1 & \textbf{sijump} is used to identify sequentially inferable jumps\\
        \hline
        \textit{impdef\_width\_p} & & Width of \textbf{implementation-defined input} bus \\
        \hline
    \end{tabulary}
\end{table}

\FloatBarrier

\begin{table}[h]
    \centering
    \caption{Parameters to the encoder - data trace}
    \label{tab:dparameters}
    \begin{tabulary}{\textwidth}{|l|l|p{100mm}|}
        \hline
        \textbf{Parameter name} & \textbf{Range} & \textbf{Description} \\
        \hline
        \textit{daddress\_width\_p} & & Width of the \textbf{daddress} bus\\
        \hline
        \textit{dblock\_width\_p} & & Width of the \textbf{dblock} bus\\
        \hline
        \textit{data\_width\_p}   & & Width of the \textbf{data} bus\\
        \hline
        \textit{dsize\_width\_p}  & & Width of the \textbf{dsize} bus\\
        \hline
        \textit{dtype\_width\_p}  & & Width of the \textbf{dtype} bus\\
        \hline
        \textit{iaddr\_lsbs\_width\_p} & & Width of the \textbf{iaddr\_lsbs} bus\\
        \hline
        \textit{lrid\_width\_p}  & & Width of the \textbf{lrid} bus\\
        \hline
        \textit{lresp\_width\_p} & & Width of the \textbf{lresp} bus\\
        \hline
        \textit{ldata\_width\_p} & & Width of the \textbf{ldata} bus\\
        \hline
        \textit{sdata\_width\_p} & & Width of the \textbf{sdata} bus\\
        \hline
    \end{tabulary}
\end{table}

\section {Discovery of encoder parameters} \label{sec:disco}

To operate correctly, the decoder must be able to determine some of the encoder's parameters 
at runtime, in the form of discoverable attributes.  These parameters must be discoverable by the 
decoder, or else be fixed at the default value (in other words, if an encoder does not make a 
particular parameter discoverable, it must implement only the default value of that parameter, 
which the decoder will also use).  Table \ref{tab:requiredAttributes} lists the required 
discoverable attributes for instruction trace.

To access the discoverable attributes, some external entity, for example a debugger or a 
supervisory hart, must request it from the encoder. The encoder will
provide the discovery information in one or more different formats.  
The preferred format is a packet which is sent over the trace infrastructure.
Another format would be allowing the external entity to read the
values from some register or memory mapped space maintained by the encoder.
Section~\ref{sec:ipxact} gives an example of how this may be accomplished.

\begin{table}[!h]
    \centering
    \caption{Required instruction trace attributes}
    \label{tab:requiredAttributes}
    \begin{tabulary}{\textwidth}{|l|l|p{80mm}|}
        \hline
        \textbf{Name} & \textbf{Default} & \textbf{Parameter mapping} \\
        \hline
        \textit{arch} & 0 & \textit{arch\_p} \\
        \hline
        \textit{bpred\_size} & 0 & \textit{bpred\_size\_p}  \\
        \hline
        \textit{cache\_size} & 0 & \textit{cache\_size\_p} \\
        \hline
        \textit{call\_counter\_size} & 0 & \textit{call\_counter\_size\_p} \\
        \hline
        \textit{context\_width} & 0 & \textit{context\_width\_p} - 1 \\
        \hline
        \textit{time\_width} & 0 & \textit{time\_width\_p} - 1 \\
        \hline
        \textit{ecause\_width} & 3 & \textit{ecause\_width\_p} - 1 \\
        \hline
        \textit{f0s\_width} & 0 & \textit{f0s\_width\_p} \\
        \hline
        \textit{iaddress\_lsb} & 0 & \textit{iaddress\_lsb\_p} - 1 \\
        \hline
        \textit{iaddress\_width} & 31 & \textit{iaddress\_width\_p} - 1 \\
        \hline
        \textit{nocontext} & 1 & \textit{nocontext} \\
        \hline
        \textit{notime} & 1 & \textit{notime} \\
        \hline
        \textit{privilege\_width} & 1 & \textit{privilege\_width\_p} - 1 \\
        \hline
        \textit{return\_stack\_size} & 0 & \textit{return\_stack\_size\_p} \\
        \hline
        \textit{sijump} & 0 & \textit{sijump\_p} \\
        \hline
    \end{tabulary}
\end{table}

For ease of use it is further recommended that all of the encoder's parameters be mapped to 
discoverable attributes, even if not directly required by the decoder.  In particular, 
attributes related to filtering capabilities.  Table \ref{tab:optionalAttributes} lists the attributes
associated with the filtering recommendations discussed in Chapter~\ref{ch:filtering},  
Table \ref{tab:otherAttributes} lists attributes related to other instruction trace
parameters mentioned in this document, and Table \ref{tab:dataAttributes} lists 
attributes related to data trace.

\begin{table}[!h]
    \centering
    \caption{Optional filtering attributes}
    \label{tab:optionalAttributes}
    \begin{tabulary}{\textwidth}{|l|l|p{80mm}|}
        \hline
        \textbf{Name} & \textbf{Default} & \textbf{Parameter mapping} \\
        \hline
         \textit{comparators} & 0 & \textit{comparators\_p} - 1\\
        \hline
        \textit{filters} & 0 & \textit{filters\_p} - 1\\
        \hline
        \textit{ecause\_choice} & 5 & \textit{ecause\_choice\_p}\\
        \hline
        \textit{filter\_context} & 1 & \textit{filter\_context\_p}\\
        \hline
        \textit{filter\_time} & 1 & \textit{filter\_time\_p}\\
        \hline
        \textit{filter\_excint} & 1 & \textit{filter\_excint\_p}\\
        \hline
        \textit{filter\_privilege} & 1 & \textit{filter\_privilege\-p}\\
        \hline
        \textit{filter\_tval} & 1 & \textit{filter\_tval\_p}\\
        \hline
    \end{tabulary}
\end{table}

\begin{table}[!h]
    \centering
    \caption{Other recommended attributes}
    \label{tab:otherAttributes}
    \begin{tabulary}{\textwidth}{|l|l|p{80mm}|}
        \hline
        \textbf{Name} & \textbf{Default} & \textbf{Description} \\
        \hline
        \textit{ctype\_width} & 0 & \textit{ctype\_width\_p} - 1\\
        \hline
        \textit{ilastsize\_width} & 0 & \textit{ilastsize\_width\_p} - 1\\
        \hline
        \textit{itype\_width} & 3 & \textit{itype\_width\_p} - 1\\
        \hline
        \textit{iretire\_width} & 1 & \textit{iretire\_width\_p} - 1\\
        \hline
        \textit{retires} & 0 & \textit{retires\_p} - 1\\
        \hline
        \textit{impdef\_width} & 0 & \textit{impdef\_width\_p} - 1\\
        \hline
    \end{tabulary}
\end{table}

\begin{table}[!h]
    \centering
    \caption{Data trace attributes}
    \label{tab:dataAttributes}
    \begin{tabulary}{\textwidth}{|l|l|p{80mm}|}
        \hline
        \textbf{Name} & \textbf{Default} & \textbf{Description} \\
        \hline
        \textit{daddress\_width} & 31 & \textit{daddress\_width\_p} - 1\\
        \hline
        \textit{dblock\_width} & 0 & \textit{dblock\_width\_p} - 1\\
        \hline
        \textit{data\_width} & 31 & \textit{data\_width\_p} - 1\\
        \hline
        \textit{dsize\_width} & 2 & \textit{dsize\_width\_p} - 1\\
        \hline
        \textit{dtype\_width} & 0 & \textit{dtype\_width\_p} - 1\\
        \hline
        \textit{iaddr\_lsbs\_width} & 0 & \textit{iaddr\_lsbs\_width\_p} - 1\\
        \hline
        \textit{lrid\_width}  & 0  & \textit{lrid\_width\_p} - 1\\
        \hline
        \textit{lresp\_width} & 0  & \textit{lresp\_width\_p} - 1\\
        \hline
        \textit{ldata\_width} & 31 & \textit{ldata\_width\_p} - 1\\
        \hline
        \textit{sdata\_width} & 31 & \textit{sdata\_width\_p} - 1\\
        \hline
    \end{tabulary}
\end{table}

\FloatBarrier
\section{Example ipxact description} \label{sec:ipxact}

This section provides an example of discovery information represented in
the ipxact form.

\begin{alltt}
<?xml version="1.0" encoding="UTF-8"?>
<ipxact:component 
   xmlns:ipxact="http://www.accellera.org/XMLSchema/IPXACT/1685-2014"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:schemaLocation="http://www.accellera.org/XMLSchema/IPXACT/1685-2014 
                       http://www.accellera.org/XMLSchema/IPXACT/1685-2014/index.xsd">
   <ipxact:vendor>Siemens</ipxact:vendor>
   <ipxact:library>TraceEncoder</ipxact:library>
   <ipxact:name>TraceEncoder</ipxact:name>
   <ipxact:version>0.8</ipxact:version>
   <ipxact:memoryMaps>
      <ipxact:memoryMap>
         <ipxact:name>Trace Encoder Register Map</ipxact:name>
         <ipxact:addressBlock>
            <ipxact:name>>Trace Encoder Register Address Block</ipxact:name>
            <ipxact:baseAddress>0</ipxact:baseAddress>
            <ipxact:range>128</ipxact:range>
            <ipxact:width>64</ipxact:width>

            <ipxact:register>
               <ipxact:name>discovery_info_0</ipxact:name>
               <ipxact:addressOffset>'h0</ipxact:addressOffset>
               <ipxact:size>64</ipxact:size>
               <ipxact:access>read-only</ipxact:access>
               <ipxact:field>
                  <ipxact:name>version</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>0</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>minor_revision</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>4</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>arch</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>8</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>bpred_size</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>12</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>cache_size</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>16</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>call_counter_size</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>20</ipxact:bitOffset>
                  <ipxact:bitWidth>3</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>comparators</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>23</ipxact:bitOffset>
                  <ipxact:bitWidth>3</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>context_type_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>26</ipxact:bitOffset>
                  <ipxact:bitWidth>5</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>context_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>31</ipxact:bitOffset>
                  <ipxact:bitWidth>5</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>ecause_choice</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>36</ipxact:bitOffset>
                  <ipxact:bitWidth>3</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>ecause_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>39</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>filters</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>43</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>filter_context</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>47</ipxact:bitOffset>
                  <ipxact:bitWidth>1</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>filter_excint</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>48</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>filter_privilege</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>52</ipxact:bitOffset>
                  <ipxact:bitWidth>1</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>filter_tval</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>53</ipxact:bitOffset>
                  <ipxact:bitWidth>1</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>filter_impdef</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>54</ipxact:bitOffset>
                  <ipxact:bitWidth>1</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>f0s_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>55</ipxact:bitOffset>
                  <ipxact:bitWidth>2</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>iaddress_lsb</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>57</ipxact:bitOffset>
                  <ipxact:bitWidth>2</ipxact:bitWidth>
               </ipxact:field>
            </ipxact:register>


            <ipxact:register>
               <ipxact:name>discovery_info_1</ipxact:name>
               <ipxact:addressOffset>'h4</ipxact:addressOffset>
               <ipxact:size>64</ipxact:size>
               <ipxact:access>read-only</ipxact:access>
               <ipxact:field>
                  <ipxact:name>iaddress_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>0</ipxact:bitOffset>
                  <ipxact:bitWidth>7</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>ilastsize_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>7</ipxact:bitOffset>
                  <ipxact:bitWidth>7</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>itype_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>14</ipxact:bitOffset>
                  <ipxact:bitWidth>7</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>iretire_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>21</ipxact:bitOffset>
                  <ipxact:bitWidth>7</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>nocontext</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>28</ipxact:bitOffset>
                  <ipxact:bitWidth>1</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>privilege_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>29</ipxact:bitOffset>
                  <ipxact:bitWidth>2</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>retires</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>31</ipxact:bitOffset>
                  <ipxact:bitWidth>3</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>return_stack_size</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>34</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>sijump</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>38</ipxact:bitOffset>
                  <ipxact:bitWidth>1</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>taken_branches</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>39</ipxact:bitOffset>
                  <ipxact:bitWidth>4</ipxact:bitWidth>
               </ipxact:field>
               <ipxact:field>
                  <ipxact:name>impdef_width</ipxact:name>
                  <ipxact:description>text</ipxact:description>
                  <ipxact:bitOffset>43</ipxact:bitOffset>
                  <ipxact:bitWidth>5</ipxact:bitWidth>
               </ipxact:field>
            </ipxact:register>

         </ipxact:addressBlock>
         <ipxact:addressUnitBits>8</ipxact:addressUnitBits>
      </ipxact:memoryMap>
   </ipxact:memoryMaps>
</ipxact:component>
\end{alltt}