jupyter/TraceWhisperer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to Debug Tracing for Side-Channel Analysis\n",
    "\n",
    "This notebook shows some of the things you can do with \"TraceWhisperer\".\n",
    "\n",
    "TraceWhisperer pairs Arm trace debug with ChipWhisperer.\n",
    "\n",
    "If you have a ChipWhisperer Husky, then TraceWhisperer is included.\n",
    "\n",
    "If you have a CW-lite or CW-pro, then you'll need a CW610 (PhyWhisperer) for trace collection.\n",
    "\n",
    "Or, if you have a CW305 FPGA target board, then we have a target bitfile which co-locates the TraceWhisperer functionality direwctly on the target FPGA.\n",
    "\n",
    "If you're not using the CW305 target, then supported targets are:\n",
    "* CW308 multi-target board with the MK82F target\n",
    "* CW308 with an STM32 target\n",
    "* CW312 with the SAM4S target\n",
    "* CWLITEARM\n",
    "\n",
    "It should be possible to use any other target with an exposed trace interface, but the above targets will work as-is.\n",
    "\n",
    "Our SAM4S is partially supported: while you can use TraceWhisperer with it, its Arm core does not have an ETM (embedded trace macrocell) unit, which means it cannot emit the PC address match packets that are used in this notebook (instead, we'll have it generate periodic PC sample packets, which isn't quite as interesting).\n",
    "\n",
    "This notebook tries to highlight some of the many things that can be done with trace, and so it is not meant to be run \"straight through\". Read the instructions carefully!\n",
    "\n",
    "Set the following defines as per your setup, but note that the CW305 platform only supports the parallel trace interface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#TRACE_PLATFORM = 'CW610' # AKA PhyWhisperer\n",
    "#TRACE_PLATFORM = 'CW305' # CW305 FPGA target board\n",
    "TRACE_PLATFORM = 'Husky'\n",
    "\n",
    "#PLATFORM = 'CW305'\n",
    "#PLATFORM = 'CWLITEARM'\n",
    "PLATFORM = 'CW308_STM32F3'\n",
    "#PLATFORM = 'CW308_K82F'\n",
    "#PLATFORM = 'CW308_SAM4S'\n",
    "\n",
    "#TRACE_INTERFACE = 'parallel'\n",
    "TRACE_INTERFACE = 'swo'\n",
    "\n",
    "#RAW_CAPTURE = True\n",
    "RAW_CAPTURE = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import chipwhisperer as cw"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# platform setup:\n",
    "if TRACE_PLATFORM == 'Husky':\n",
    "    SCOPETYPE = 'OPENADC'\n",
    "    %run \"Helper_Scripts/Setup_Generic.ipynb\"\n",
    "    scope.trace.target = target\n",
    "    trace = scope.trace\n",
    "    # TODO! set scope.clock\n",
    "\n",
    "elif TRACE_PLATFORM == 'CW610':\n",
    "    from chipwhisperer.capture.trace.TraceWhisperer import TraceWhisperer\n",
    "    SCOPETYPE = 'OPENADC'\n",
    "    %run \"Helper_Scripts/Setup_Generic.ipynb\"\n",
    "    trace = TraceWhisperer(target, scope, force_bitfile=True)\n",
    "    scope.clock.adc_src = \"clkgen_x4\"\n",
    "\n",
    "else:\n",
    "    from chipwhisperer.capture.trace.TraceWhisperer import TraceWhisperer\n",
    "    %run \"Helper_Scripts/Setup_CW305_DST.ipynb\"\n",
    "    trace = TraceWhisperer(target, scope)\n",
    "    \n",
    "if TRACE_PLATFORM == 'Husky':\n",
    "    scope.adc.samples = 31000\n",
    "else:\n",
    "    scope.adc.samples = 24400\n",
    "\n",
    "trace.enabled = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if TRACE_PLATFORM == 'CW305':\n",
    "    scope.gain.setGain(30)\n",
    "elif TRACE_PLATFORM == 'Husky':\n",
    "    scope.gain.db = 12\n",
    "elif PLATFORM == 'CW308_K82F':\n",
    "    scope.gain.setGain(20)\n",
    "elif PLATFORM == 'CW308_STM32F3':\n",
    "    scope.gain.setGain(25)\n",
    "elif PLATFORM == 'CWLITEARM':\n",
    "    scope.gain.setGain(25)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Program STM32 target:\n",
    "\n",
    "If you're using the K82 target, you'll need an external programmer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if (PLATFORM == 'CW308_STM32F3') or (PLATFORM == 'CWLITEARM'):\n",
    "    fw_path = '../../cw_develop/hardware/victims/firmware/simpleserial-trace/simpleserial-trace-CW308_STM32F3.hex'\n",
    "    prog = cw.programmers.STM32FProgrammer\n",
    "    cw.program_target(scope, prog, fw_path)\n",
    "elif PLATFORM == 'CW308_SAM4S':\n",
    "    fw_path = '../../cw_develop/hardware/victims/firmware/simpleserial-trace/simpleserial-trace-CW308_SAM4S.hex'\n",
    "    prog = cw.programmers.SAM4SProgrammer\n",
    "    cw.program_target(scope, prog, fw_path)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# required after programming some targets:\n",
    "def target_reset():\n",
    "    if TRACE_PLATFORM == 'CW610' or TRACE_PLATFORM == 'Husky':\n",
    "        scope.io.nrst = 'low'\n",
    "        time.sleep(0.05)\n",
    "        scope.io.nrst = 'high'\n",
    "        time.sleep(0.05)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "target_reset()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# target info and buildtimes:\n",
    "print(trace.phywhisperer_name())\n",
    "print(trace.get_fw_buildtime())\n",
    "if TRACE_PLATFORM == 'Husky':\n",
    "    print(scope.fpga_buildtime)\n",
    "else:\n",
    "    print(trace.fpga_buildtime)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if PLATFORM != 'CW305':\n",
    "    assert 'ChipWhisperer simpleserial-trace, compiled' in trace.get_fw_buildtime(), \"Looks like you have the wrong firmware, please compile and program the firmware in this directory of your ChipWhisperer installation: hardware/victims/firmware/simpleserial-trace\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set the trace operation mode.\n",
    "\n",
    "Arm processor can output trace data on a parallel trace port or on a serial SWO pin.\n",
    "\n",
    "Parallel trace mode operation is pretty straightforward. SWO is a bit more complicated to set up.\n",
    "\n",
    "First, Arm processors which support JTAG and SWD come out of reset in JTAG mode. In order to get trace data out of the SWO pin, we need to switch it over to SWD mode.\n",
    "\n",
    "The `jtag_to_swd()` call below runs a special sequence on the TMS and TCK pins to do this switchover. However, different processors (such as the STM32) may have *additional* requirements to enable the SWO pin. The `simpleserial-trace` firmware handles this for the STM32. Other targets may have their own requirements. One sure-fire way to get a target into SWD mode is to use an external debugger. In that case, do not call `jtag_to_swd()`, as this could result in contention on the TMS/TCK pins.\n",
    "\n",
    "Unless you're on the CW305 platform, you'll need some jumper cables.\n",
    "\n",
    "For parallel trace, you need to connect the target's trace pins to the PhyWhisperer D[4:7] and CK pins.\n",
    "\n",
    "For SWO trace, you need to connect the target's TMS/TCK/TDO pins to the PhyWhisperer D0/D1/D2 pins.\n",
    "\n",
    "If you wish to use the target clock (recommended!), you must connect it to HS2 on the 20-pin connector.\n",
    "\n",
    "If you wish to use the target trigger, you must connect it to PC on the 20-pin connector."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is the setup for parallel trace mode.\n",
    "\n",
    "Trace data can be captured with either the trace clock or the target clock. There are no advantages or disadvantages to either, so use whichever is available.\n",
    "On Husky and CW610, since the trace data and clock come from an external device, there is a possibility of mis-sampling. With our K82 target, sampling with the target clock works well, while sampling with the target-generated trace clock may require phase adjustments for proper sampling. The `trace_clock_alignment.ipynb` notebook explains how to do this.\n",
    "\n",
    "On the CW305, the target clock must be used (the reasons are technical and have to do with the internal DDR trace data bus; using the target clock avoids this). However, trace data and clock on the CW305 are internal to the FPGA, so there is no risk of missampling in this case."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if TRACE_INTERFACE == 'parallel':\n",
    "    trace.clock.fe_clock_src = 'target_clock'\n",
    "    #trace.clock.fe_clock_src = 'trace_clock'\n",
    "    assert trace.clock.fe_clock_alive, \"Hmm, the clock you chose doesn't seem to be active.\"\n",
    "    trace.trace_mode = 'parallel'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For SWO mode, the target clock is the best choice; if it's not available, you can use the USB clock, but since this is not synchronous to the target clock, the timing of your trace measurements will have more jitter.\n",
    "\n",
    "SWO setup is a bit more complicated, and you need to understand a bit of how SWO data can be generated.\n",
    "\n",
    "The target's `TPI.ACPR` register determines the length of an SWO data bit: (`TPI.ACPR` + 1) target clock cycles. A value of zero gives the highest bandwidth. Positive integers are also allowed.\n",
    "\n",
    "In general, 0 is the better choice for what we do with trace, but if you run into problems with recovering the trace data, try a higher value.\n",
    "\n",
    "This covers the SWO trace generation side. On the recovery side, we need a clock which is some multiple of the SWO baud rate. We use the clock chosen by `trace.clock.fe_clk_src`; we multiply this by some integer, then set `trace.swo_div` to tell the FPGA how many clocks cycles there are per SWO bit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if TRACE_INTERFACE == 'swo':\n",
    "    assert TRACE_PLATFORM == 'CW610' or TRACE_PLATFORM == 'Husky', \"Not supported :-(\"\n",
    "    trace.clock.fe_clock_src = 'target_clock'\n",
    "    #trace.clock.fe_clock_src = 'usb_clock'\n",
    "    assert trace.clock.fe_clock_alive, \"Hmm, the clock you chose doesn't seem to be active.\"\n",
    "    trace.trace_mode = 'SWO'\n",
    "    trace.jtag_to_swd() # switch target into SWO mode\n",
    "\n",
    "    # Now the complicated bit:\n",
    "    acpr = 0\n",
    "    trigger_freq_mul = 8\n",
    "    trace.clock.swo_clock_freq = scope.clock.clkgen_freq * trigger_freq_mul\n",
    "    trace.target_registers.TPI_ACPR = acpr\n",
    "    trace.swo_div = trigger_freq_mul * (acpr + 1)\n",
    "    assert trace.clock.swo_clock_locked, \"Trigger/UART clock not locked\"\n",
    "    if TRACE_PLATFORM == 'Husky':\n",
    "        assert scope.userio.status & 0x4, \"SWO line not high\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Check that the target is alive.\n",
    "If `get_fw_buildtime()` produces no output, the target may have become unresponsive after the above changes; it may simply require a reset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(trace.get_fw_buildtime())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Disable sync frames for SWO:\n",
    "\n",
    "By default, periodic sync frames are emitted every 16 million clock cycles. If you're bringing up an SWO target for the first time, this is helpful to confirm that the link is \"alive\".\n",
    "However these sync frames will delay the trace events that we care about if they occur during our trace capture, so it's best to disable them.\n",
    "\n",
    "Sync frames on the parallel trace port cannot be disabled."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if TRACE_INTERFACE == 'swo':\n",
    "    trace.target_registers.DWT_CTRL = 0x40000021"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Trigger trace capture from target FW:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#trace.use_soft_trigger()\n",
    "trace.capture.trigger_source = 'firmware trigger'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What to capture:\n",
    "There are two trace capture modes:\n",
    "1. Raw mode captures the complete raw trace data.\n",
    "2. Non-raw mode captures only matching rule IDs. To use this, set up some pattern match rules (see below); only the ID of the matching rule will be captured."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if RAW_CAPTURE:\n",
    "    trace.capture.raw = True\n",
    "    trace.capture.rules_enabled = []\n",
    "\n",
    "else:\n",
    "    trace.capture.raw = False\n",
    "\n",
    "    if PLATFORM == 'CW308_SAM4S':\n",
    "        # match on periodic PC sampling trace packet:\n",
    "        trace.set_pattern_match(0, [3, 23])\n",
    "    else:\n",
    "        # match on any PC match (isync) trace packet:\n",
    "        trace.set_pattern_match(0, [3, 8, 32])\n",
    "\n",
    "    # enable matching rule:\n",
    "    trace.capture.rules_enabled = [0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### If we set a pattern match rule, it can be used to trigger trace capture. Alternatively, trace capture is initiated by the target FW's soft trigger:\n",
    "\n",
    "Be aware that the pattern match is not a stable trigger source; expect jitter up to 6 clock cycles. See the DesignStartTrace [README](https://github.com/newaetech/DesignStartTrace/blob/master/README.md) for more information on jitter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "trace.capture.trigger_source = 'firmware trigger'\n",
    "#trace.capture.trigger_source = 0 # match using pattern rule #0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How long to capture for:\n",
    "By default, trace data is captured while the target's trigger line is high. This is probably what you want to do (unless your target doesn't drive the trigger line, e.g. you're using a trace pattern match as the trigger).\n",
    "\n",
    "Alternatively, you can manually specify how many cycles or events the capture should last."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "trace.capture.mode = 'while_trig'\n",
    "#trace.capture.mode = 'count_writes'\n",
    "#trace.capture.count = 500"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set PC addresses to match on:\n",
    "Let's use the start of the `SubBytes()` and `AddRoundKey()` functions.\n",
    "\n",
    "This will set the target's `DWT.COMP0`, `DWT.COMP1`, and `ETM.TEEVR` registers.\n",
    "\n",
    "If you recompile, adjust accordingly.\n",
    "\n",
    "Unfortunately, this doesn't work on the SAM4S target because it doesn't have an ETM, which is required to emit the PC address match packets that we are using here. Instead, we'll get periodic PC samples (see below). Remember that this is just one example and that there are many other things you can do with trace!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if TRACE_PLATFORM == 'CW305':\n",
    "    trace.set_isync_matches(addr0=0x3bc0, addr1=0x3aa8, match='both')\n",
    "elif PLATFORM == 'CWLITEARM' or PLATFORM == 'CW308_STM32F3':\n",
    "    trace.set_isync_matches(addr0=0x080018c4, addr1=0x0800188c, match='both')\n",
    "elif PLATFORM == 'CW308_K82F':\n",
    "    trace.set_isync_matches(addr0=0x3ef0, addr1=0x3eb8, match='both')\n",
    "elif PLATFORM == 'CW308_SAM4S':\n",
    "    print('Warning: SAM4S cannot output address match packets 😢')\n",
    "else:\n",
    "    raise ValueError('Unsupported platform')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Enable or disable periodic PC sampling:\n",
    "\n",
    "This can also be done directly via the `DWT.CTRL` register; by using this method, PC sampling is turned on at trigger time to ensure that the capture doesn't start in the middle of a trace frame, which would prevent automatic parsing.\n",
    "\n",
    "In this demo we leave it off so that we can focus on the PC match packets, except for the SAM4S (which doesn't support PC match packets)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if PLATFORM == 'CW308_SAM4S':\n",
    "    trace.set_periodic_pc_sampling(enable=1, cyctap=1)\n",
    "else:\n",
    "    trace.set_periodic_pc_sampling(enable=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Capture power and debug trace:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if TRACE_PLATFORM == 'CW610':\n",
    "    print(\"*** Don't forget the jumper cable from CW308 GPIO4/TRIG pin to PhyWhisperer PC pin on side connector! ***\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sstarget = trace._ss"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# force resynchronization, ensure we are sync'd:\n",
    "if TRACE_INTERFACE == 'parallel':\n",
    "    trace.resync()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In SWO mode, trace data can be clocked by either the target clock or the 96MHz USB clock. You should use the target clock unless it's not available, so that the collected trace data is synchronous with the target clock.\n",
    "\n",
    "In parallel mode, there is additionally the option of using the trace clock. This can lead to missampling of the trace data, which may be observed post-capture when trying to parse the trace data, or even here with `trace.resync()` failing (synchronization is done by identifying known periodic sync frames that are continuously emitted by the parallel trace port).\n",
    "\n",
    "If this happens, look at the `trace_clock_realignment.ipynb` notebook to learn how you can phase-shift the trace clock to resolve this problem."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# arm trace sniffer:\n",
    "trace.arm_trace()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from tqdm.notebook import tnrange\n",
    "import numpy as np\n",
    "\n",
    "ktp = cw.ktp.Basic()\n",
    "\n",
    "powertraces = []\n",
    "num_traces = 1\n",
    "\n",
    "for i in tnrange(num_traces, desc='Capturing traces'):\n",
    "    key, text = ktp.next()  # manual creation of a key, text pair can be substituted here\n",
    "    powertrace = cw.capture_trace(scope, sstarget, text, key)\n",
    "    if powertrace is None:\n",
    "        continue\n",
    "    powertraces.append(powertrace)\n",
    "\n",
    "#Convert traces to numpy arrays\n",
    "trace_array = np.asarray([trace.wave for trace in powertraces])  # if you prefer to work with numpy array for number crunching\n",
    "textin_array = np.asarray([trace.textin for trace in powertraces])\n",
    "known_keys = np.asarray([trace.key for trace in powertraces])  # for fixed key, these keys are all the same"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Read the raw trace data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "raw = trace.read_capture_data()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### If we captured raw data, parse out raw 'frames' from it:\n",
    "This will *not* work if you used `trace.fpga_write(trace.REG_CAPTURE_RAW, [0])`!\n",
    "\n",
    "When using the parallel trace port, the sync frames are used as frame delimiters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "if RAW_CAPTURE:\n",
    "    if TRACE_INTERFACE == 'parallel':\n",
    "        frames = trace.get_raw_trace_packets(raw, removesyncs=True, verbose=True)\n",
    "    else:\n",
    "        frames = trace.get_raw_trace_packets(raw, removesyncs=False, verbose=True)\n",
    "        \n",
    "else:\n",
    "    times = trace.get_rule_match_times(raw, rawtimes=False, verbose=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For rule-based capture, we can get more information about the capture:\n",
    "\n",
    "- `trace.capture.matched_pattern_data` shows the actual trace data which last matched one of the match rules\n",
    "- `trace.capture.matched_pattern_counts` shows how many times each rule was matched"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if not RAW_CAPTURE:\n",
    "    print(trace.capture.matched_pattern_data)\n",
    "    print(trace.capture.matched_pattern_counts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Parse the raw trace data with Orbuculum:\n",
    "For the case where `REG_CAPTURE_RAW = 1` only.\n",
    "\n",
    "Orbuculum allows you to make sense out of the cryptic TPIU-encoded trace data. It can be installed from: https://github.com/orbcode/orbuculum"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# first, write out the raw trace data to a file:\n",
    "trace.write_raw_capture(frames, 'raw.bin')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# change the path to where the orbuculum executable resides on your own system:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "# Use this for orbuculum version 1.13 or earlier:\n",
    "#/home/jpnewae/git/orbuculum/ofiles/orbuculum -t -f raw.bin -P -e\n",
    "\n",
    "# Use this as of commit 7374cec2f1a1f72e586cb5941123c5a859b0e7bb:\n",
    "/home/jpnewae/git/orbuculum/build/orbfifo -t 1 -E -P  --input-file raw.bin\n",
    "cat hwevent\n",
    "wc hwevent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Refer to Orbuculum documentation for more information, but for the example shown here you'll get two types of entries out of Orbuculum:\n",
    "1. Starts with '2': periodic PC sample; last field is the PC value\n",
    "2. Starts with '8': Isync match; last field is the PC value\n",
    "\n",
    "The middle field is the timestamp inferred by Orbuculum, which is inaccurate here since TraceWhisperer strips out most of the sync frames for storage efficiency and records its own timestamps instead."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Plotting Example\n",
    "For the code below, go back above and re-run a trace capture with non-raw capture mode, using one or two PC addresses that are of interest to you.\n",
    "Skip over the Orbuculum cells since we aren't capturing raw trace packets.\n",
    "\n",
    "The default PC match values, for the target executable in the repository, are the start of the `SubBytes()` and `MixColumns()` functions.\n",
    "\n",
    "The code below overlays black vertical lines on top of the power trace, for each rule match event.\n",
    "\n",
    "Note that 18 matches are obtained (not 20) because the last round uses a different code path.\n",
    "\n",
    "In order to overlay the power and debug trace data, we must match their timescales. `multiplier` expresses the ratio of the power trace sampling rate to the debug trace sampling rate. First, we account for the x1 or x4 power trace sampling rate.\n",
    "\n",
    "Then, we account for the debug trace sampling rate. In parallel trace mode this is straightforward -- the debug trace rate is equal to the target processor speed.\n",
    "\n",
    "In SWO mode, there is another factor to account for: the debug trace sampling rate and target clock rate can be different.\n",
    "\n",
    "See https://github.com/newaetech/DesignStartTrace/blob/master/hardware/tracewhisperer/clocks.md for details on what's happening here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if scope._is_husky:\n",
    "    multiplier = scope.clock.adc_mul\n",
    "elif scope.clock.adc_src == 'clkgen_x4' or scope.clock.adc_src == 'extclk_x4':\n",
    "    multiplier = 4\n",
    "else:\n",
    "    multiplier = 1\n",
    "\n",
    "if TRACE_INTERFACE == 'swo':\n",
    "    #multiplier /= trace.swo_target_clock_ratio\n",
    "    #multiplier //= (trace.clock.fe_freq / scope.clock.clkgen_freq)\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from bokeh.plotting import figure, show\n",
    "from bokeh.io import output_notebook\n",
    "from bokeh.resources import INLINE\n",
    "from bokeh.models import Span\n",
    "\n",
    "output_notebook(INLINE)\n",
    "p = figure(plot_width=1200)\n",
    "\n",
    "xrange = range(len(powertraces[0].wave))\n",
    "p.line(xrange, powertraces[0].wave, line_color=\"red\")\n",
    "\n",
    "vlines = []\n",
    "for t in times:\n",
    "    vlines.append(Span(location=t[0]*multiplier, dimension='height', line_color='black', line_width=2))\n",
    "p.renderers.extend(vlines)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Next steps:\n",
    "\n",
    "1. The [pc_sample_annotate.ipynb](pc_sample_annotate.ipynb) notebook shows an example of something else you can do with trace that's pretty neat: annotating a power waveform with the functions being executed.\n",
    "2. The [trace_clock_alignment.ipynb](trace_clock_alignment.ipynb) notebook shows how the trace capture clock can be shifted to properly sample parallel trace data.\n",
    "3. The [uecc.ipynb](https://github.com/newaetech/chipwhisperer-jupyter/blob/master/demos/uecc.ipynb) notebook shows how trace can be used to help execute a side-channel attack on a software ECC target."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python (venv37)",
   "language": "python",
   "name": "venv37"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}