API Reference¶
Here we provide documentation for important classes and methods.
Basys3Ctrl Class (controller)¶
-
class
fobos.
Basys3Ctrl
(self, port, baudRate=115200, dummy=False)¶ Class to interface with Basys3 controller.
Parameters: - port (str) – The serial port where the Basys3 board is connected(e.g /dev/ttyUSB1).
- baudRate (int) – Baud rate. Default is 115200.
- dummy (bool) – When set to true, no communication with Basys3 is done. This is to test the software only. Default is False.
-
processData
(self, data, outLen)¶ Sends data to FOBOS hardware for processing, e.g. encryption
Parameters: data (str) – The data to be processed. This is a hexadecimal string. Rtype (str, str): Returns: (Status (“00000000” OK | “20000000” TIMOUT) , Result from DUT (i.e. ciphertext))
-
setOutLen
(self, outLen)¶ set DUT Expected Output Length (result length) in bytes.
Parameters: outLen (int) – The number of output bytes to be returned by the DUT (e.g 16 for AES-128). Rtype int: Returns: Status.
-
setTriggerWait
(self, trigWait)¶ Set number of trigger wait cycles
Parameters: int (trigWait) – The number of DUT cycles after di_ready goes to 0 to issue the trigger. Return type: int Returns: Status
-
setTriggerMode
(self, trigType)¶ -
Set trigger mode.
param int: trigType. Possible values (TRG_NORM = 0 | TRG_FULL = 1 | TRG_NORM_CLK = 2 | TRG_FULL_CLK = 3) rtype: int return: Status -
setTimeToReset
(self, dutCycles)¶ set number of clock cycles after di_ready goes to 0 to reset the DUT.
Parameters: dutCycles (int) – The number of DUT cycles to reset the DUT. Return type: int Returns: Status.
-
-
setTimeout
(self, seconds)¶ set number of seconds to stop waiting for DUT result.
Parameters: seconds (in) – Time in seconds. Range 1-40 seconds. Return type: int Returns: Status
-
enableTestMode
(self)¶ Enable test mode. When this mode is enabled, the controller sends test-vectors to its internal dummy DUT.
Return type: int Returns: Status
-
disableTestMode
(self)¶ Disable test mode. In this mode the ctrl board uses the real DUT. This is the default mode.
Return type: int Returns: Status
-
forceReset
(self)¶ Reset DUT and clear current communication with DUT.
Return type: int Returns: Status
-
releaseReset
(self)¶ Release DUT reset signal
Return type: int Returns: Status
-
setDUTClk
(self, clkFreqMhz)¶ Set DUT clock frequency generated by the control board. Range is between 0.4 MHz - 100 MHz.
Parameters: clkFreqMhz (float) – The DUT clock frequency in Mhz. Return type: int Returns: Status
Scope (Picoscope Class)¶
-
class
Picoscope
(self, sampleResolution=8, preTriggerSamples=0, postTriggerSamples=1000)¶ A class to interface with the Picoscope oscilloscope.
-
__init__
(self, sampleResolution=8, preTriggerSamples=0, postTriggerSamples=1000)¶ Open oscilloscope
Parameters: - sampleResolution (int) – The number of bits used to represent each sample. Possible values 8, 12, 14, 15 and 16.
- preTriggerSamples (int) – The number of samples before the trigger to return to the user.
- postTriggerSamples (int) – The number of samples after the trigger to return to the user.
-
setChannel
(self, channelName='CHANNEL_A', coupling='DC', rangemv='1V')¶ Configure voltage range and coupling for a channel.
Parameters: - channelName (str) – The name of the oscilloscope channel (CHANNEL_A | CHANNELB).
- coupling (str) – Select DC/AC coupling (DC | AC)
- rangemv (str) – The voltage range for the selected channel (10mV|20mV|50mV|100mV|200mV|500mV|1V|2V|5V|10V|20V)
-
setSamplingInterval
(self, samplingIntervalns)¶ Sets the sampling interval (time between samples T) in nano seconds. Sampling rate = 1/T.
Parameters: samplingInterval (int) – Sampling interval (time between samples T) in nano seconds. Sampling rate = 1/T.
-
setTrigger
(self, channelName= 'CHANNEL_A', thresholdmv = 500, direction = 'RISING_EDGE', autoTriggerDelay = 2000)¶ Configure trigger channel.
Parameters: - channelName (str) – The channel to use as a trigger channel (CHANNEL_A | CHANNELB | EXTERNAL).
- thresholdmv (int) – The minimum level of voltage to assert a trigger.
- direction (str) – The trigger signal direction (RISING_EDGE| FALLING_EDGE).
- autoTriggerDelay (int) – Time in milliseconds after which auto trigger occurs (i.e start storing data even if no valid trigger received).
-
setDataBuffers
()¶ Allocates memory buffers to store oscilloscope data.
-
ProjectManager Class¶
-
class
ProjectManager
¶ A class to facilitate organizing and saving results files/data files in automatically created directories. For example, when new capture is performed a directory named attempt-[number] will be created in the capture directory.
-
setWorkSpaceDir
(self, workSpaceDir)¶ Sets the directory where all data will be saved.
Parameters: workSpaceDir (str) – Workspace directory path.
-
setProjName
()¶ Sets the project name.
Parameters: projectName (str) – Project name. A directory will be created in the workspace with the project name.
-
getProjDir
()¶ Gets the project directory path.
Returns: Full project directory path.
-
getCaptureDir
()¶ Creates and returns the path of a new directory created in worksapce/projectName/capture/ the folder will be named attempt-(number) for uniqueness.
-
Nexy3DUT Class¶
-
class
Nexys3DUT
¶ A class to program Digilent Nexy3 DUT. This class requires that Digilent Adept command line tools (djtgcfg command) is installed.
-
setBitFile
(bitFile)¶ Sets the bit file name used to program the DUT FPGA.
Parameters: bitFile (str) – Full path of the .bit file to program the FPGA.
-
program
()¶ Programs the FPGA using the bit file specified using he setBitFile method.
-
CPA Class¶
-
class
CPA
¶ A class to perform Correlation Power Analysis.
-
doCPA
(self, measuredPower, hypotheticalPower, numTraces, analysisDir, MTDStride)¶ Perform CPA.
Parameters: - measuredPower (numpy_array) – The power measure using the oscilloscope.
- hypotheticalPower (numpy_array) – The hypotheticalPower estimated using the power model.
- numTraces (int) – Number of traces in to be analyzed.
- analysisDir (str) – Full path of the directory to store analysis results.
- MTDStride (int) – The number of traces to add in each step when plotting the MTD graph.
-
DataGenerator Class¶
-
class
DataGenerator
¶ A class to generate FOBOS-ready test vectors.
-
randTVFile
(self, pdiLen, sdiLen, rdiLen, outLen, fileName, numTVs)¶ Generate a FOBOS-ready test-vector file.
Parameters: - pdiLen (int) – The lenght of PDI data (e.g plaintext) in bytes.
- sdiLen (int) – The lenght of SDI data (e.g secret key) in bytes.
- rdiLen (int) – The lenght of RDI data (random data) in bytes.
- outLen (int) – The lenght of expected output (e.g ciphertext) in bytes.
- fileName (str) – The name of the file to store the testvectors.
-
randTestVector
(self, pdiLen, sdiLen, rdiLen, outLen)¶ Generate a single FOBOS-ready test-vector.
Parameters: - pdiLen (int) – The lenght of PDI data (e.g plaintext) in bytes.
- sdiLen (int) – The lenght of SDI data (e.g secret key) in bytes.
- rdiLen (int) – The lenght of RDI data (random data) in bytes.
- outLen (int) – The lenght of expected output (e.g ciphertext) in bytes.
-