Add usage notes to notebooks.

Author: jpcrypt

jupyter/CW340_AES_test.ipynb

@@ -1,5 +1,16 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Basic HW AES CPA attack.\n",
+    "\n",
+    "**IMPORTANT NOTES!**\n",
+    "- **VCCIOB jumper (JP9)** must be in **top position (3.3V)**, which is different from the other test notebook;\n",
+    "- **nPOR jumper (JP5)** must be in **bottom position (1-3)**."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -15,7 +26,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "#bsfile = '../fpga/vivado/cw341.runs/impl_1/cw341_top.bit'\n",
     "bsfile = '../fpga/vivado/cw341.runs/impl_20pin/cw341_top.bit'"
    ]
   },
@@ -72,14 +82,13 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "attachments": {},
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "scope.clock.adc_mul = 4\n",
-    "scope.clock.clkgen_freq = 40e6\n",
-    "scope.clock.clkgen_src = 'extclk'"
+    "**Once the `husky_clock_fix` branch is merged** (i.e. issues [490](https://github.com/newaetech/chipwhisperer/issues/490), [499](https://github.com/newaetech/chipwhisperer/issues/501) and [501](https://github.com/newaetech/chipwhisperer/issues/501) are closed), 4x sampling works well, and `CLOCKS_FIXED` can be set to `True`.\n",
+    "\n",
+    "Otherwise, we crank up to 20x sampling (`CLOCKS_FIXED = False`) to better catch the leakage."
    ]
   },
   {
@@ -88,29 +97,27 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "CLOCKS_FIXED = False\n",
+    "\n",
+    "if CLOCKS_FIXED:\n",
+    "    scope.clock.adc_mul = 4\n",
+    "    scope.clock.clkgen_freq = 10e6\n",
+    "    scope.clock.clkgen_src = 'extclk'\n",
+    "    scope.clock.adc_phase = 15\n",
+    "    scope.adc.samples = 60\n",
+    "else:\n",
+    "    scope.clock.adc_mul = 20\n",
+    "    scope.clock.clkgen_freq = 10e6\n",
+    "    scope.clock.clkgen_src = 'extclk'\n",
+    "    scope.clock.adc_phase = 0\n",
+    "    scope.adc.samples = 300\n",
+    "\n",
+    "scope.adc.presamples = 0\n",
+    "scope.gain.db = 32\n",
+    "\n",
     "assert scope.clock.adc_locked"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "scope.adc.samples = 60\n",
-    "scope.adc.presamples = 0"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# set gain accordingly:\n",
-    "scope.gain.db = 40"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -137,7 +144,7 @@
     "traces = []\n",
     "textin = []\n",
     "keys = []\n",
-    "N = 5000  # Number of traces\n",
+    "N = 10000  # Number of traces\n",
     "\n",
     "# initialize cipher to verify DUT result:\n",
     "key, text = ktp.next()\n",
@@ -223,7 +230,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "np.average(attack_results.pge)"
+    "avg_pge = np.average(attack_results.pge)\n",
+    "if CLOCKS_FIXED:\n",
+    "    MAX_PGE = 10\n",
+    "else:\n",
+    "    MAX_PGE = 50\n",
+    "assert avg_pge < MAX_PGE, 'Average PGE is %d' % avg_pge"
    ]
   },
   {
@@ -243,9 +255,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python (venv39)",
    "language": "python",
-   "name": "python3"
+   "name": "venv39"
   },
   "language_info": {
    "codemirror_mode": {

jupyter/CW340_test.ipynb

@@ -1,12 +1,14 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "import chipwhisperer as cw"
+    "# Basic tests.\n",
+    "\n",
+    "**IMPORTANT NOTES!**\n",
+    "- **VCCIOB jumper (JP9)** must be in **middle position (1.8V)**, which is different from the AES test notebook;\n",
+    "- **nPOR jumper (JP5)** must be in **bottom position (1-3)**."
    ]
   },
   {
@@ -15,7 +17,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!pwd"
+    "import chipwhisperer as cw"
    ]
   },
   {
@@ -435,7 +437,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Test Hyperrams:"
+    "# Test Hyperrams:\n",
+    "\n",
+    "The hyperram controller is quite sensitive to the clock frequency. If the controller gets stuck, try a slightly different (higher or lower) frequency, e.g. 35 MHz or 45 MHz."
    ]
   },
   {
@@ -630,9 +634,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python (venv39)",
    "language": "python",
-   "name": "python3"
+   "name": "venv39"
   },
   "language_info": {
    "codemirror_mode": {