Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@fboemer
fboemer committed Apr 5, 2021
1 parent 3a9e551 commit 24f7ffb
Show file tree
Hide file tree
Showing 5 changed files with 126 additions and 29 deletions.
6 changes: 6 additions & 0 deletions CHANGES.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Changes

## 1.0.1
- Remove intel- prefix from headers and library name
- Fix CMake variables from 3rd party libraries from leaking
- Fix warnings when HEXL_DEBUG=ON
38 changes: 30 additions & 8 deletions docs/doxygen/html/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ <h1><a class="anchor" id="autotoc_md1"></a>
<li><a href="#benchmarking-intel-hexl">Benchmarking Intel HEXL</a></li>
<li><a href="#using-intel-hexl">Using Intel HEXL</a></li>
<li><a href="#debugging">Debugging</a></li>
<li><a href="#thread-safety">Thread-safety</a></li>
<li><a href="#threading">Threading</a></li>
</ul>
</li>
<li><a href="#documentation">Documentation</a><ul>
Expand All @@ -100,6 +100,11 @@ <h1><a class="anchor" id="autotoc_md1"></a>
</li>
<li><a href="#contributing">Contributing</a><ul>
<li><a href="#repository-layout">Repository layout</a></li>
<li><a href="#intel-hexl-publication">Intel HEXL Publication</a></li>
<li><a href="#citing-intel-hexl">Citing Intel HEXL</a><ul>
<li><a href="#version-10">Version 1.0</a></li>
</ul>
</li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -160,6 +165,8 @@ <h2><a class="anchor" id="autotoc_md5"></a>
<td class="markdownTableBodyNone">HEXL_SHARED_LIB </td><td class="markdownTableBodyNone">ON / OFF (default OFF) </td><td class="markdownTableBodyNone">Set to ON to enable building shared library </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone">HEXL_TESTING </td><td class="markdownTableBodyNone">ON / OFF (default ON) </td><td class="markdownTableBodyNone">Set to ON to enable building of unit-tests </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone">HEXL_TREAT_WARNING_AS_ERROR </td><td class="markdownTableBodyNone">ON / OFF (default OFF) </td><td class="markdownTableBodyNone">Set to ON to treat all warnings as error </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md6"></a>
Compiling Intel HEXL</h2>
Expand All @@ -186,19 +193,19 @@ <h1><a class="anchor" id="autotoc_md10"></a>
<p>For optimal performance, Intel HEXL does not perform input validation. In many cases the time required for the validation would be longer than the execution of the function itself. To debug Intel HEXL, configure and build Intel HEXL with <code>-DHEXL_DEBUG=ON</code> (see <a href="#compile-time-options">Compile-time options</a>). This will generate a debug version of the library, e.g. <code>libhexl_debug.a</code>, that can be used to debug the execution.</p>
<p><b>Note</b>, enabling <code>HEXL_DEBUG=ON</code> will result in a significant runtime overhead. </p>
<h1><a class="anchor" id="autotoc_md11"></a>
Thread-safety</h1>
Threading</h1>
<p>Intel HEXL is single-threaded and thread-safe.</p>
<h1><a class="anchor" id="autotoc_md12"></a>
Documentation</h1>
<p>See <a href="https://intel.github.io/hexl">https://intel.github.io/hexl</a> for Doxygen documentation.</p>
<p>Intel HEXL supports documentation via Doxygen and sphinx. To build documentation, first install <code>doxygen</code> and <code>graphviz</code>, e.g. </p><div class="fragment"><div class="line">sudo apt-get install doxygen graphviz</div>
</div><!-- fragment --><p>Then, configure Intel HEXL with <code>-DHEXL_DOCS=ON</code> (see <a href="#compile-time-options">Compile-time options</a>). </p>
<h3><a class="anchor" id="autotoc_md13"></a>
Doxygen</h3>
<h2><a class="anchor" id="autotoc_md13"></a>
Doxygen</h2>
<p>To build Doxygen documentation, after configuring Intel HEXL with <code>-DHEXL_DOCS=ON</code>, run </p><div class="fragment"><div class="line">cmake --build build --target doxygen</div>
</div><!-- fragment --><p>To view the generated Doxygen documentation, open the generated <code>build/docs/doxygen/html/index.html</code> file in a web browser.</p>
<h3><a class="anchor" id="autotoc_md14"></a>
Sphinx</h3>
<h2><a class="anchor" id="autotoc_md14"></a>
Sphinx</h2>
<p>To build the sphinx documentation, install <code>sphinx</code> and required dependencies <code>breathe, m2r2</code>, e.g. </p><div class="fragment"><div class="line">sudo apt-get install python3-sphinx</div>
<div class="line">pip3 install breathe m2r2</div>
</div><!-- fragment --><p>Then, after configuring Intel HEXL with <code>-DHEXL_DOCS=ON</code>, run </p><div class="fragment"><div class="line">cmake --build build --target docs</div>
Expand All @@ -211,8 +218,23 @@ <h1><a class="anchor" id="autotoc_md15"></a>
</div><!-- fragment --><p>and make sure pre-commit checks and all unit tests pass.</p>
<h2><a class="anchor" id="autotoc_md16"></a>
Repository layout</h2>
<p>Public headers reside in the <code>hexl/include</code> folder. Private headers, e.g. those containing Intel(R) AVX-512 code should not be put in this folder. </p>
</div></div><!-- PageDoc -->
<p>Public headers reside in the <code>hexl/include</code> folder. Private headers, e.g. those containing Intel(R) AVX-512 code should not be put in this folder.</p>
<h2><a class="anchor" id="autotoc_md17"></a>
Intel HEXL Publication</h2>
<p>Find published paper at <a href="https://arxiv.org/abs/2103.16400">https://arxiv.org/abs/2103.16400</a>.</p>
<h2><a class="anchor" id="autotoc_md18"></a>
Citing Intel HEXL</h2>
<p>To cite Intel HEXL, please use the following BibTeX entry.</p>
<h3><a class="anchor" id="autotoc_md19"></a>
Version 1.0</h3>
<div class="fragment"><div class="line">@misc{IntelHEXL,</div>
<div class="line"> title = {{I}ntel {HEXL} (release 1.0)},</div>
<div class="line"> howpublished = {\url{https://arxiv.org/abs/2103.16400}},</div>
<div class="line"> month = mar,</div>
<div class="line"> year = 2021,</div>
<div class="line"> key = {Intel HEXL}</div>
<div class="line">}</div>
</div><!-- fragment --> </div></div><!-- PageDoc -->
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Expand Down
29 changes: 24 additions & 5 deletions docs/doxygen/latex/index.tex
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
\item \href{\#benchmarking-intel-hexl}{\texttt{ Benchmarking Intel H\+E\+XL}}
\item \href{\#using-intel-hexl}{\texttt{ Using Intel H\+E\+XL}}
\item \href{\#debugging}{\texttt{ Debugging}}
\item \href{\#thread-safety}{\texttt{ Thread-\/safety}}
\item \href{\#threading}{\texttt{ Threading}}
\end{DoxyItemize}
\item \href{\#documentation}{\texttt{ Documentation}}
\begin{DoxyItemize}
Expand All @@ -25,6 +25,11 @@
\item \href{\#contributing}{\texttt{ Contributing}}
\begin{DoxyItemize}
\item \href{\#repository-layout}{\texttt{ Repository layout}}
\item \href{\#intel-hexl-publication}{\texttt{ Intel H\+E\+XL Publication}}
\item \href{\#citing-intel-hexl}{\texttt{ Citing Intel H\+E\+XL}}
\begin{DoxyItemize}
\item \href{\#version-10}{\texttt{ Version 1.\+0}}
\end{DoxyItemize}
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{index_autotoc_md2}{}\doxysection{Introduction}\label{index_autotoc_md2}
Many cryptographic applications, particularly homomorphic encryption (HE), rely on integer polynomial arithmetic in a finite field. HE, which enables computation on encrypted data, typically uses polynomials with degree {\ttfamily N} a power of two roughly in the range {\ttfamily N=\mbox{[}2$^\wedge$\{10\}, 2$^\wedge$\{17\}\mbox{]}}. The coefficients of these polynomials are in a finite field with a word-\/sized primes, {\ttfamily p}, up to {\ttfamily p}$\sim$62 bits. More precisely, the polynomials live in the ring {\ttfamily Z\+\_\+p\mbox{[}X\mbox{]}/(X$^\wedge$N + 1)}. That is, when adding or multiplying two polynomials, each coefficient of the result is reduced by the prime modulus {\ttfamily p}. When multiplying two polynomials, the resulting polynomials of degree {\ttfamily 2N} is additionally reduced by taking the remainder when dividing by {\ttfamily X$^\wedge$\+N+1}.
Expand Down Expand Up @@ -90,6 +95,7 @@
H\+E\+X\+L\+\_\+\+E\+X\+P\+O\+RT &ON / O\+FF (default O\+FF) &Set to ON to enable export of Intel H\+E\+XL for use in 3rd-\/party project \\\cline{1-3}
H\+E\+X\+L\+\_\+\+S\+H\+A\+R\+E\+D\+\_\+\+L\+IB &ON / O\+FF (default O\+FF) &Set to ON to enable building shared library \\\cline{1-3}
H\+E\+X\+L\+\_\+\+T\+E\+S\+T\+I\+NG &ON / O\+FF (default ON) &Set to ON to enable building of unit-\/tests \\\cline{1-3}
H\+E\+X\+L\+\_\+\+T\+R\+E\+A\+T\+\_\+\+W\+A\+R\+N\+I\+N\+G\+\_\+\+A\+S\+\_\+\+E\+R\+R\+OR &ON / O\+FF (default O\+FF) &Set to ON to treat all warnings as error \\\cline{1-3}
\end{longtabu}
\hypertarget{index_autotoc_md6}{}\doxysubsection{Compiling Intel H\+E\+XL}\label{index_autotoc_md6}
The instructions to build Intel H\+E\+XL are common between Linux, Mac\+OS, and Windows.
Expand Down Expand Up @@ -142,7 +148,7 @@
The {\ttfamily example} folder has an example of using Intel H\+E\+XL in a third-\/party project.\hypertarget{index_autotoc_md10}{}\doxysection{Debugging}\label{index_autotoc_md10}
For optimal performance, Intel H\+E\+XL does not perform input validation. In many cases the time required for the validation would be longer than the execution of the function itself. To debug Intel H\+E\+XL, configure and build Intel H\+E\+XL with {\ttfamily -\/D\+H\+E\+X\+L\+\_\+\+D\+E\+B\+UG=ON} (see \href{\#compile-time-options}{\texttt{ Compile-\/time options}}). This will generate a debug version of the library, e.\+g. {\ttfamily libhexl\+\_\+debug.\+a}, that can be used to debug the execution.

{\bfseries{Note}}, enabling {\ttfamily H\+E\+X\+L\+\_\+\+D\+E\+B\+UG=ON} will result in a significant runtime overhead. \hypertarget{index_autotoc_md11}{}\doxysection{Thread-\/safety}\label{index_autotoc_md11}
{\bfseries{Note}}, enabling {\ttfamily H\+E\+X\+L\+\_\+\+D\+E\+B\+UG=ON} will result in a significant runtime overhead. \hypertarget{index_autotoc_md11}{}\doxysection{Threading}\label{index_autotoc_md11}
Intel H\+E\+XL is single-\/threaded and thread-\/safe.\hypertarget{index_autotoc_md12}{}\doxysection{Documentation}\label{index_autotoc_md12}
See \href{https://intel.github.io/hexl}{\texttt{ https\+://intel.\+github.\+io/hexl}} for Doxygen documentation.

Expand All @@ -152,14 +158,14 @@
\end{DoxyCode}


Then, configure Intel H\+E\+XL with {\ttfamily -\/D\+H\+E\+X\+L\+\_\+\+D\+O\+CS=ON} (see \href{\#compile-time-options}{\texttt{ Compile-\/time options}}). \hypertarget{index_autotoc_md13}{}\doxysubsubsection{Doxygen}\label{index_autotoc_md13}
Then, configure Intel H\+E\+XL with {\ttfamily -\/D\+H\+E\+X\+L\+\_\+\+D\+O\+CS=ON} (see \href{\#compile-time-options}{\texttt{ Compile-\/time options}}). \hypertarget{index_autotoc_md13}{}\doxysubsection{Doxygen}\label{index_autotoc_md13}
To build Doxygen documentation, after configuring Intel H\+E\+XL with {\ttfamily -\/D\+H\+E\+X\+L\+\_\+\+D\+O\+CS=ON}, run
\begin{DoxyCode}{0}
\DoxyCodeLine{cmake -\/-\/build build -\/-\/target doxygen}
\end{DoxyCode}


To view the generated Doxygen documentation, open the generated {\ttfamily build/docs/doxygen/html/index.\+html} file in a web browser.\hypertarget{index_autotoc_md14}{}\doxysubsubsection{Sphinx}\label{index_autotoc_md14}
To view the generated Doxygen documentation, open the generated {\ttfamily build/docs/doxygen/html/index.\+html} file in a web browser.\hypertarget{index_autotoc_md14}{}\doxysubsection{Sphinx}\label{index_autotoc_md14}
To build the sphinx documentation, install {\ttfamily sphinx} and required dependencies {\ttfamily breathe, m2r2}, e.\+g.
\begin{DoxyCode}{0}
\DoxyCodeLine{sudo apt-\/get install python3-\/sphinx}
Expand All @@ -185,4 +191,17 @@


and make sure pre-\/commit checks and all unit tests pass.\hypertarget{index_autotoc_md16}{}\doxysubsection{Repository layout}\label{index_autotoc_md16}
Public headers reside in the {\ttfamily hexl/include} folder. Private headers, e.\+g. those containing Intel(\+R) A\+V\+X-\/512 code should not be put in this folder.
Public headers reside in the {\ttfamily hexl/include} folder. Private headers, e.\+g. those containing Intel(\+R) A\+V\+X-\/512 code should not be put in this folder.\hypertarget{index_autotoc_md17}{}\doxysubsection{Intel H\+E\+X\+L Publication}\label{index_autotoc_md17}
Find published paper at \href{https://arxiv.org/abs/2103.16400}{\texttt{ https\+://arxiv.\+org/abs/2103.\+16400}}.\hypertarget{index_autotoc_md18}{}\doxysubsection{Citing Intel H\+E\+XL}\label{index_autotoc_md18}
To cite Intel H\+E\+XL, please use the following Bib\+TeX entry.\hypertarget{index_autotoc_md19}{}\doxysubsubsection{Version 1.\+0}\label{index_autotoc_md19}

\begin{DoxyCode}{0}
\DoxyCodeLine{@misc\{IntelHEXL,}
\DoxyCodeLine{ title = \{\{I\}ntel \{HEXL\} (release 1.0)\},}
\DoxyCodeLine{ howpublished = \{\(\backslash\)url\{https://arxiv.org/abs/2103.16400\}\},}
\DoxyCodeLine{ month = mar,}
\DoxyCodeLine{ year = 2021,}
\DoxyCodeLine{ key = \{Intel HEXL\}}
\DoxyCodeLine{\}}
\end{DoxyCode}

Loading

0 comments on commit 24f7ffb

Please sign in to comment.