C29x PK Calculator User Guide

C29x PK Calculator User Guide Document Number: C29xPKCalcUG Rev 1, 12/2013

2 Freescale Semiconductor, Inc.

Contents Section number Title Page Chapter 1 Introduction Chapter 2 Hardware setup 2.1 C293 PCIe card switch settings...9 2.2 Verify device detection...10 2.2.1 On X86 host...10 2.2.2 On P4080 host...11 2.3 X86 IOAT DMA...12 2.3.1 BIOS changes...12 2.3.2 Kernel config changes...12 2.3.3 Verify IOAT DMA support...14 2.4 X86 disabling IOMMU hardware support...15 2.5 P4080 DMA support...16 Chapter 3 Build procedure 3.1 Prerequisites...17 3.2 X86 host...18 3.2.1 Compiling PowerPC toolchain...18 3.2.2 X86 PKC extended kernel compilation...18 3.2.3 Boot X86 machine with new kernel...19 3.2.4 Build All software components...19 3.2.4.1 Build firmware...20 3.2.4.2 Build driver...20 3.2.4.3 Build CLI app...20 3.2.5 Binaries location...21 3.2.6 Default install location...21 Freescale Semiconductor, Inc. 3

Section number Title Page 3.3 P4080 host...21 3.3.1 Build P4080 linux kernel...21 3.3.2 Build All software components...22 3.3.2.1 Build firmware...22 3.3.2.2 Build driver...22 3.3.2.3 Build CLI app...22 3.3.3 Location of the binaries...23 3.3.4 Build rootfs...23 3.3.5 Booting the P4080DS with the new kernel & rootfs image...23 Chapter 4 C29x host driver and firmware build configuration Chapter 5 Resource configuration Chapter 6 Load driver 6.1 For X86 host...29 6.2 For P4080 host...29 Chapter 7 Driver load time configurations Chapter 8 Pre-built binaries Chapter 9 Running the driver with openssl 9.1 Cryptodev Framework (CDF)...35 9.1.1 Procedure to compile and insert CryptoDev Framework...35 9.2 Openssl...35 9.2.1 Procedure to compile openssl...36 Chapter 10 Driver test framework 10.1 Script path...37 10.2 Supported tests...37 4 Freescale Semiconductor, Inc.

Section number Title Page 10.3 Usage...38 Chapter 11 CLI Chapter 12 Directory structure Freescale Semiconductor, Inc. 5

6 Freescale Semiconductor, Inc.

Chapter 1 Introduction This document explains the procedure to build, configure, and use different software components for the Freescale C29x crypto coprocessor device. Freescale Semiconductor, Inc. 7

8 Freescale Semiconductor, Inc.

Chapter 2 Hardware setup This section explains the hardware setup and configuration used. 2.1 C293 PCIe card switch settings This section explains the details applicable to the Freescale C293 PCIe development platform. These switch settings may not be valid for other version of cards. (For C291/ C292, refer to the corresponding schematic or hardware spec). It is assumed that the card has been delivered with proper default DIP switch settings. SW7 (Switch 7) settings need to be changed as per the instructions below for the software to work properly. Refer to the C29x PCIe Card Quick Start Guide for the details about the switch configurations. SW7[1-5] are set towards ON label of the switch for PCIx4 setting and agent mode. SW7[1] must be ON for the driver to work. This puts the core in boot hold off mode. The image below shows the SW7 setting on the board. Freescale Semiconductor, Inc. 9

Verify device detection Figure 2-1. SW7 setting 2.2 Verify device detection 2.2.1 On X86 host Run the lspci command on the host. A typical output shows the following device: 05:00.0 Power PC: Freescale Semiconductor Inc Device 0800 (rev 10) NOTE The BDF 05:00.0 may change based on the root port under which this device is connected in your setup. Run lspci -vvs <b:d:f> to check and validate the PCIe details of the C29x card. Following is an example output. Two BARs of 1M size must be detected, as shown in the highlighted text below: lspci -vvs 05:00.0 05:00.0 Power PC: Freescale Semiconductor Inc Device 0800 (rev 10) (prog-if 01) Control: I/O+ Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR- FastB2B- DisINTx+ Status: Cap+ 66MHz- UDF- FastB2B- ParErr- DEVSEL=fast >TAbort- <TAbort- <MAbort- >SERR- <PERR- INTx- Latency: 0, Cache Line Size: 64 bytes Interrupt: pin A routed to IRQ 90 Region 0: Memory at b1a00000 (32-bit, non-prefetchable) [size=1m] 10 Freescale Semiconductor, Inc.

Chapter 2 Hardware setup Region 1: Memory at b1900000 (32-bit, prefetchable) [size=1m] Capabilities: [44] Power Management version 3 Flags: PMEClk- DSI- D1+ D2+ AuxCurrent=0mA PME(D0+,D1+,D2+,D3hot+,D3cold-) Status: D0 NoSoftRst- PME-Enable- DSel=0 DScale=0 PME- Capabilities: [4c] Express (v2) Endpoint, MSI 00 DevCap:MaxPayload 256 bytes, PhantFunc 0, Latency L0s <64ns, L1 <1us ExtTag- AttnBtn- AttnInd- PwrInd- RBE+ FLReset- DevCtl:Report errors: Correctable- Non-Fatal- Fatal- Unsupported- RlxdOrd+ ExtTag- PhantFunc- AuxPwr- NoSnoop+ MaxPayload 256 bytes, MaxReadReq 512 bytes DevSta:CorrErr+ UncorrErr- FatalErr- UnsuppReq+ AuxPwr- TransPend- LnkCap:Port #0, Speed 5GT/s, Width x4, ASPM L0s, Latency L0 <2us, L1 unlimited ClockPM- Surprise- LLActRep- BwNot- LnkCtl:ASPM Disabled; RCB 64 bytes Disabled- Retrain- CommClk- ExtSynch- ClockPM- AutWidDis- BWInt- AutBWInt- LnkSta:Speed 5GT/s, Width x4, TrErr- Train- SlotClk- DLActive- BWMgmt- ABWMgmt- NOTE If the card cannot be detected, change the setting of switch 7[2:4] for different PCIe speed and PCIe width used, e.g. from 2.5GHz to 5GHz or vice versa. 2.2.2 On P4080 host On P4080, device detection may be verified from u-boot logs. The figure below shows the u-boot log and the highlighted portion indicates the device detection. Freescale Semiconductor, Inc. 11

X86 IOAT DMA Figure 2-2. u-boot log 2.3 X86 IOAT DMA This section explains the procedure to enable X86 IOAT DMA support. 2.3.1 BIOS changes Browse through tabs in BIOS to enable IOAT DMA support. NOTE Different BIOS has different setting for IOAT DMA, adjust the setting configuration according to your machine. The following setting is for ASUS Z9PE-D8 WS motherboard and Intel Xeon CPU E5-2620. Advanced->Chipset Configuration, CPU IIO Bridge Configuration, Intel(R) I/OAT [Enabled] 12 Freescale Semiconductor, Inc.

2.3.2 Kernel config changes Following options need to be changed in kernel configuration menu, browse through the configuration menu as shown below. Device Drivers --> DMA Engine support --> --- DMA Engine support [ ] DMA Engine debugging *** DMA Devices *** <M> Intel MID DMA support for Peripheral DMA controllers <M> Intel I/OAT DMA support <M> Timberdale FPGA DMA support <M> Intel EG20T PCH / OKI Semi IOH(ML7213/ML7223/ML7831) DMA support *** DMA Clients *** [ ] Network: TCP receive copy offload [ ] Async_tx: Offload support for the async_tx api < > DMA Test client The image below shows the config screen menu with the above mentioned changes. NOTE Use Arrow keys to navigate in the menu. Press <Enter> to select submenus, press <Y> to include, press <N> or press <spacebar> to clear a box or press <M> to modularize. Make sure that your settings match with the image below. Chapter 2 Hardware setup The image below shows the config screen menu with the above mentioned changes. Freescale Semiconductor, Inc. 13

X86 IOAT DMA Figure 2-3. Config screen menu NOTE These changes can be made when the updated kernel loads, it automatically shows this screen. NOTE When updating the kernel 3.8.13 from Ubuntu 12.04 kernel, see X86 PKC extended kernel compilation for details. 2.3.3 Verify IOAT DMA support This section explains how to verify if the IOAT (I/O Acceleration Technology) DMA is enabled and supported. 1. lsmod grep ioat, shows the following output: root@car:~# lsmod grep ioat ioatdma 42148 24 dca 14611 2 ioatdma,igb 2. cat /proc/interrupts This displays some ioat MSIx/MSI interrupts, count and irq number. This may vary for different hosts. 14 Freescale Semiconductor, Inc.

83: 0 3 PCI-MSI-edge ioat-msix 84: 3 0 PCI-MSI-edge ioat-msix 3. lspci command on Linux also lists the IOATDMA (Intel Quickdata) PCI devices. NOTE IOAT supports Intel Xeon 5K series chipsets and above, check your bios to ensure whether or not you have IOAT. Chapter 2 Hardware setup 2.4 X86 disabling IOMMU hardware support To support virtualization, IOMMU Hardware Support needs to be disabled in Linux config. If IOMMU Hardware Support is not disabled, you may not get any output from the test applications. NOTE During the kernel 3.8.13 compilation, you can see the Linux config menu, navigate to the Device Drivers to open its submenu, from there you can disable IOMMU Hardware Support. The image below shows the Linux config menu. Figure 2-4. Linux config menu Freescale Semiconductor, Inc. 15

P4080 DMA support NOTE When updating the kernel 3.8.13 from Ubuntu 12.04 kernel, see X86 PKC extended kernel compilation for details. 2.5 P4080 DMA support To enable P4080DMA support, changes need to be done in kernel configuration menu, which is displayed during the kernel compilation process. Browse through the config screen and make following changes: [*] Device Drivers ---> [*] DMA Engine support ---> [ ] DMA Engine debugging *** DMA Devices *** <*> Freescale Elo and Elo Plus DMA support < > Timberdale FPGA DMA support *** DMA Clients *** [ ] Network: TCP receive copy offload [ ] Async_tx: Offload support for the async_tx api < > DMA Test client Procedure to compile kernel is explained in below sections. 16 Freescale Semiconductor, Inc.

Chapter 3 Build procedure 3.1 Prerequisites Contact sales representative or your local Freescale office to get the C293 PCIe.ISO/.tar file for all the documents and source code of PKC. Mount the.iso or extract the.tar file into a working folder and make sure that nonroot user has R-W permission on the directory and all the files inside it. Download the QorIQ Linux SDK v1.4. Yocto Source ISO from www.freescale.com/sdk. NOTE The size of QorIQ Linux SDK v1.4 ISO file is more than 2GB. SDK & driver compilation is verified on Ubuntu 12.04. Install the same version to avoid any package dependency related errors. Both wget & update-grub utilities should be included in the Ubuntu 12.04 distribution. This is required for automated kernel requirement support inside the build. Machine on which the build is being issued should be connected to the Internet. For X86, kernel version 3.8.13 is downloaded from kernel.org, PKC patch is applied and then the kernel is compiled. These steps are automated with one make command in the build. For P4080, SDK compilation always downloads the required packages over the Internet. For Ubuntu and Debian hosts, reconfigure /bin/sh to point to bash. To see if you are running dash, run: ls -al /bin/sh To change your environment, run: sudo rm /bin/sh sudo ln -s /bin/bash /bin/sh Freescale Semiconductor, Inc. 17

X86 host Now run, ls -al /bin/sh to check whether it points to bash or not. Alternatively, you can add SHELL=/bin/bash in the makefile, to change the environment. 3.2 X86 host This section explains the build procedure for X86 machine. 3.2.1 Compiling PowerPC toolchain To compile PowerPC toolchain: 1. Download the SDK 1.4 ISO. 2. Mount the ISO image 3. Install SDK 1.4 from the ISO. 4. Agree to the EULA and give installation directory path. 5. From the SDK working directory, prepare the SDK with following commands: a. $. /scripts/host-prepare.sh NOTE You need to execute the above command once, after mounting and installation of SDK 1.4 on a freshly installed Ubuntu 12.04. b. $ source./fsl-setup-poky m p4080ds c. $ bitbake fsl-image-minimal NOTE SDK 1.4 should be installed on a Linux machine. Follow the SDK documentation to install SDK 1.4. Make sure that this installed SDK path is specified in config.mk file. The p4080ds machine is used because the makefile in C293 source directory points to the p4080ds build directory. 3.2.2 X86 PKC extended kernel compilation Standard kernel does not have PKC extensions, so a version of kernel needs to be downloaded, patched, and compiled. 18 Freescale Semiconductor, Inc.

This process is automated with the following single make command: Chapter 3 Build procedure $ make x86_kernel Following are some important points to note: During kernel installation, kernel config menu appears and from there select the required config options. For more information see Kernel config changes and X86 disabling IOMMU hardware support. Makefile downloads Linux kernel version 3.8.13 from kernel.org, patch it, and then compiles it. Make sure that linux 3.8.13 kernel does not already exist in the machine. Kernel source code is downloaded using the command wget. Ensure that wget is installed in the build host system. update-grub utility is used to update the grub.cfg file with the new kernel. Make sure that update-grub utility is installed in the build host system. As part of kernel compilation process, a menu config screen is displayed. IOAT DMA settings can be changed if the host has that capability. IOAT config related details are explained in Kernel config changes. 3.2.3 Boot X86 machine with new kernel After the kernel compilation is complete, the makefile itself updates the grub.cfg file. Reboot the machine and select the new kernel from the grub menu. Subsequent build process must be done once the system has been booted with this kernel. 3.2.4 Build All software components This section explains the procedure to build all the required software components with one command. NOTE Check if your board supports IOAT DMA or not. If it doesn t, set USE_HOST_DMA =n in your config.mk file. If it does, set USE_HOST_DMA =y in your config.mk file. This check is required, so that the drivers can be loaded during execution of tests, for more information see Load driver and Running the driver with openssl. $ make clean ARCH=x86: To clean the source Freescale Semiconductor, Inc. 19

X86 host $ make ARCH=x86: To build firmware, driver, CLI app. NOTE Non root user should grant execute permission of the above commands and write permission for related directories. Each component can be compiled individually, which is explained in below sub-sections. 3.2.4.1 Build firmware Update SDK_PATH in config.mk file as: SDK_PATH=<Absolute Path to SDK Build Directory> $ make c29x_fw_clean : To clean the firmware $ make c29x_fw : To compile the firmware NOTE Firmware is same for X86 & P4080, firmware built once can be used for both the hosts. Non-root user should grant execute permission of the above commands and write permission for related directories. 3.2.4.2 Build driver $ make c29x_driver_clean ARCH=x86 : To clean the host driver $ make c29x_driver ARCH=x86 : To compile the host driver NOTE Any user id may be used (root or non-root) to build the driver. If the host system is IOAT DMA capable and if driver has to use the DMA capability, then make sure in config.mk, set USE_HOST_DMA=y. 3.2.4.3 Build CLI app $ make c29x_cli_clean ARCH=x86 : To clean cli $ make c29x_cli ARCH=x86 : To build cli 20 Freescale Semiconductor, Inc.

Chapter 3 Build procedure 3.2.5 Binaries location The location of all the compiled binaries is as follows: <dir> :- Installation directory in which the source tar ball is extracted. Driver :- <dir>/bin_images/x86_rc/fsl_crypto_offload_drv.ko CLI :- <dir>/bin_images/x86_rc/c29x_cli Firmware :- <dir>/bin_images/c29x_ep/u-boot-sd.bin 3.2.6 Default install location make install copies all the following images from their above mentioned locations to /etc/ crypto/. If it is not present, this directory is created by the makefile. <dir>/crypto.cfg <dir>/bin_images/x86_rc/c29x-cli <dir>/bin_images/c29x_ep/u-boot-sd.bin By default, crypto.cfg has the default location of the binaries. If any change has been made to the default location, crypto.cfg must be updated accordingly. 3.3 P4080 host This section explains the build procedure for P4080 Host. 3.3.1 Build P4080 linux kernel P4080 linux kernel needs to be built only once, if a fresh SDK1.4 is used. This is because driver's standalone compilation needs pre-compiled kernel. Following is the command to compile kernel: $ make p4080_kernel_clean : To clean p4080 kernel $ make p4080_kernel : To compile p4080 kernel A menu config screen is displayed in the build process. DMA related changes may be selected. See P4080 DMA support for details. The compiled kernel image is in the standard SDK path:.../build_p4080ds_release/tmp/ deploy/images. P4080DS should boot with this image. Freescale Semiconductor, Inc. 21

P4080 host NOTE The kernel build command must be done from a non-root user id and the directory should have permission for this non-root user. 3.3.2 Build All software components $ make clean ARCH=ppc : To clean the source $ make ARCH=ppc : To build firmware, driver, CLI app. NOTE The build command must grant execute permission of the above commands and write permission for related directories. Each component may be compiled individually, as explained below. 3.3.2.1 Build firmware $ make c29x_fw_clean : To clean the firmware $ make c29x_fw : To compile the firmware NOTE Firmware is same for X86 & P4080, firmware built once can be used for both the hosts. Non-root user should grant execute permission of the above commands and write permission for related directories. 3.3.2.2 Build driver $ make c29x_driver_clean ARCH=ppc : To clean the host driver $ make c29x_driver ARCH=ppc: To compile the host driver NOTE Non-root user should grant execute permission of the above commands and write permission for related directories. If p4080ds host driver has to use the DMA capability, then make sure to give USE_HOST_DMA=y inside config.mk file. 22 Freescale Semiconductor, Inc.

3.3.2.3 Build CLI app $ make c29x_cli_clean ARCH=ppc : To clean cli $ make c29x_cli ARCH=ppc: To build cli Chapter 3 Build procedure 3.3.3 Location of the binaries The locations of all the compiled binaries are as follows: <dir> :- Installation directory in which the source tar ball is extracted. Driver :- <dir>/bin_images/p4080_rc/fsl_crypto_offload_drv.ko CLI :- <dir>/bin_images/p4080_rc/c29x_cli Firmware :- <dir>/bin_images/c29x_ep/u-boot-sd.bin These binaries may be copied using scp to the P4080DS host or can be built inside rootfs. For more information, see Build rootfs. 3.3.4 Build rootfs This step is required when compiling openssl package. Building rootfs also populates needed binaries and config files inside the rootfs. P4080DS may be booted up with this rootfs image. $ make p4080_rootfs The generated rootfs image can be flashed onto the P4080DS. Once the P4080DS is up, driver and firmware binaries can be found at: /etc/crypto/u-boot-sd.bin /etc/crypto/c29x_cli /etc/crypto/crypto.cfg /lib/modules/c2x0/fsl_crypto_offload_drv.ko /lib/modules/3.8.13-rt9-qoriq-sdk-v1.4/extra/cryptodev.ko 3.3.5 Booting the P4080DS with the new kernel & rootfs image Refer to Freescale document for the procedure to flash the images and to boot the P4080DS. Freescale Semiconductor, Inc. 23

P4080 host 24 Freescale Semiconductor, Inc.

Chapter 4 C29x host driver and firmware build configuration This section explains the build time configuration parameters..../config.mk file is in the install directory. This file specifies different parameters with which software needs to be built. The following table explains the various parameters. Table 4-1. Parameters Variable name Default Value Description SDK_PATH <empty> SDK1.4 Path on the system. Required to build u- boot, firmware, driver, kernel, rootfs. NOTE: This field must be provided. P4080_EP n Defines the type of end point, for P4080_EP this variable should be set to 'y'. This field is for legacy support where in P4080DS can be used as EP. C293_EP y Defines the type of end point, for C293_EP this variable should be set to 'y'. DEBUG_PRINT n Defines the print level. If set to 'y', debug level prints are enabled. INFO_PRINT n Defines the print level. If set to 'y', info level prints are enabled. ERROR_PRINT n Defines the print level. If set to 'y', error level prints are enabled. CONFIG_FSL_C2X0_HASH_OFFLOAD n To enable/disable hash offload support in driver. CONFIG_FSL_C2X0_SYMMETRIC_OFFLOAD n To enable/disable symmetric algorithms offload support in driver. RNG_OFFLOAD n To enable/disable RNG offload support in the driver. USE_HOST_DMA n Specifies whether host DMA to be used by driver. Should be enabled/disabled based on the capability of host. HIGH_PERF_MODE y To enable/disable high performance mode for driver and firmware. In high performance mode command ring support is disabled both from driver and firmware. VIRTIO_C2X0 n Specifies driver to work in Virtualization environment. All of the required support needs to be installed if this variable is made 'y'. Table continues on the next page... Freescale Semiconductor, Inc. 25

Table 4-1. Parameters (continued) Variable name Default Value Description ENHANCE_KERNEL_TEST n Enhance PKC kernel test performance by disabling kernel test schedule and restricting enqueue/ dequeue number of c29x_fw The image below shows the default config.mk file. Figure 4-1. Default config.mk file 26 Freescale Semiconductor, Inc.

Chapter 5 Resource configuration This section explains the configuration of different resources, which need to be created for driver-firmware to function properly. These configuration options are specified in /etc/crypto/crypto.cfg file in the build. The build has a default version of the file, which is explained below. This file contains the details about the firmware path and the ring pairs. Ring details are as follows: Ring: Ring is a circular queue that is used for job processing. There are two types of rings used in this driver. They are command ring and application ring. The command ring is used to send commands from the driver to the firmware. The command ring is disabled when HIGH_PERF_MODE flag is set in config.mk. The application rings are used to send crypto jobs from the driver to the firmware. Every ring contains the following details: Table 5-1. Ring details depth affinity priority order Ring size. Sec engine affinity. Relative priority of rings. Whether the ring processing is ordered or not. Ring details are application specific. Based on the requirements, user may change ring details before loading the driver module. User can create a maximum of 6 rings. If the ring configuration needs to be changed, the driver must be unloaded and reloaded for the new configuration to take effect. The default configuration file specifies the configuration for a single device - two ring pairs (one command ring and one application ring) to be created for that device (command ring with a size of 16 entries and the application ring with 1024 entries). /* Following configuration is for one device. * If more than one device is connected to the host, then * Please provide following config information per device. Freescale Semiconductor, Inc. 27

* Start and end of each section is clearly demarcated, * Please make sure same is followed if the config file * is changed (or) extended. */ /* Per device information Start*/ <device> /* Specifies the path of firmware to be loaded in this device. * Device will boot with this firmware image. Please note that firmware name * is constant, it can't be change. */ firmware:/etc/crypto/u-boot-sd.bin /* Specifies number of ring pairs to be created. */ rings:2 /* Per ring information Start */ <ring> /* Depth of each ring */ depth:16 /* SEC affinity of ring */ affinity:0 /* Relative priority of ring */ priority:1 /* Whether the ring is ordered (or) un-ordered */ order:0 <end> /* Per ring information End */ /* Same as above */ /* Per ring information Start */ <ring> depth:1024 affinity:0 priority:1 order:0 <end> /* Per ring information End */ <end> /* Per device information End */ 28 Freescale Semiconductor, Inc.

Chapter 6 Load driver 6.1 For X86 host Compile the driver, procedure is explained in X86 host. The driver uses the following default settings: Firmware binary at /etc/crypto/u-boot-sd.bin Configuration file at /etc/crypto/crypto.cfg To load driver with default settings: make install make insmod The user may override the default settings at driver load time using the command below: insmod <dir>/bin_images/x86_rc/fsl_crypto_offload_drv.ko dev_config_file=<path> 6.2 For P4080 host Compile the driver. Inside the P4080DS: insmod /lib/modules/c2x0/fsl_crypto_offload_drv.ko dev_config_file=<path> 1. dev_config_file = Path of configuration file with which driver boots up. See Resource configuration for the format and details of this file. 2. Driver as part of its load process downloads the specified firmware to the device and boots up the device. 3. Driver then performs handshake with firmware and creates the resources specified. 4. After all the operations are completed, following print can be seen in kernel logs root@p4080ds:~# dmesg tail [FSL-CRYPTO-OFFLOAD-DRV] DevId:1 DEVICE IS UP 5. Driver state can also be verified from sysfs entry root@p4080ds:~# cat /sys/fsl_crypto/fsl_crypto_1/state DRIVER READY Freescale Semiconductor, Inc. 29

For P4080 host 6. Driver is up now and can be used to send crypto operations. 30 Freescale Semiconductor, Inc.

Chapter 7 Driver load time configurations Following module parameters can be provided at the load time for driver: Parameter Default value Description Mandatory dev_config_file NULL Device configuration file. Specifies all the configurations for the device, see the above section for details. napi_poll_count 1 Specifies the higher limit of the count for which worker threads should be polling. wt_cpu_mask One thread per cpu Bit mask of CPUs on which worker threads needs to be scheduled. dma_channel_count 1 DMA channel count for driver to use N dma_channel_cpu_mask One channel for all CPUs Defines the distribution of channels to CPUs Y N N N Example: insmod fsl_crypto_offload_drv.ko dev_config_file=/etc/crypto/crypto.cfg napi_poll_count=10 wt_cpu_mask=0x3 dma_channel_count=8 dma_channel_cpu_mask=0xff,0xff,0xff,0xff,0xff,0xff,0xff, 0xff Freescale Semiconductor, Inc. 31

32 Freescale Semiconductor, Inc.

Chapter 8 Pre-built binaries Pre-built binaries which are verified are uploaded as part of the release. X86 Host binaries <dir>/bin_images/x86_rc/ C293 EP images <dir>/bin_images/c293_ep/ Freescale Semiconductor, Inc. 33

34 Freescale Semiconductor, Inc.

Chapter 9 Running the driver with openssl Driver provides the crypto-offload to userspace applications through KCAPI (Kernel Crypto API). Openssl is one such application. Driver registers its algorithm support to the kernel through KCAPI. 9.1 Cryptodev Framework (CDF) This is /dev/crypto interface for the application. This module needs to be compiled and inserted in the host. Standard CDF does not have PKC extensions; a version of CDF is extended for PKC and is maintained in the build. 9.1.1 Procedure to compile and insert CryptoDev Framework X86 Host $ cd <dir>/crypto_patches/x86_deps/cryptodev-linux-1.5_v-2 $ make $ insmod cryptodev.ko P4080 host CryptoDev Framework is built as part of rootfs build. For more information, see Build rootfs. After P4080DS is up with this rootfs, the Cryptodev module may loaded using the command : insmod /lib/modules/3.8.13-rt9-qoriq-sdk-v1.4/extra/cryptodev.ko Freescale Semiconductor, Inc. 35

Openssl 9.2 Openssl Standard openssl does not have PKC offload support in cryptodev engine (eng_cryptodev.c). A version of openssl is extended for PKC support and is maintained in the build. 9.2.1 Procedure to compile openssl X86 Host $ cd <dir>/crypto_patches/x86_deps/openssl-1.0.1c_v-2 $./config -DHAVE_CRYPTODEV $ make $ make install P4080 host Openssl is built as part of rootfs build. For more information, see Build rootfs. Now, openssl commands can be used for any crypto operation. 36 Freescale Semiconductor, Inc.

Chapter 10 Driver test framework Build supports driver test framework. This framework interacts directly with the driver through sysfs. 10.1 Script path <dir>/perf/c29x_driver_perf_profile.sh 10.2 Supported tests RSA_PUB_OP_1K RSA_PUB_OP_2K RSA_PUB_OP_4K RSA_PRV_OP_1K RSA_PRV_OP_2K RSA_PRV_OP_4K DSA_SIGN_TEST_1K DSA_SIGN_TEST_2K DSA_SIGN_TEST_4K DSA_VERIFY_TEST_1K DSA_VERIFY_TEST_2K DSA_VERIFY_TEST_4K DSA SIGN VERIFY TEST :- This test does the sign and verify both for 1K key. DSA_KEYGEN_TEST :- This test generates 1K keys, sign an image, verifies. ECDSA_KEYGEN_TEST :- This test generates 1K keys, sign an image, verifies. DH_KEYGEN_TEST ECDH_TEST ECDSA_VERIFY_TEST ECDSA_SIGN_TEST ECP_SIGN_TEST_256 Freescale Semiconductor, Inc. 37

Usage ECP_VERIFY_TEST_256 ECP_SIGN_TEST_384 ECP_VERIFY_TEST_384 ECP_SIGN_TEST_521 ECP_VERIFY_TEST_521 ECPBN_SIGN_TEST_283 ECPBN_VERIFY_TEST_283 ECPBN_SIGN_TEST_409 ECPBN_VERIFY_TEST_409 ECPBN_SIGN_TEST_571 ECPBN_VERIFY_TEST_571 DH_TEST_1K DH_TEST_2K DH_TEST_4K ECDH_KEYGEN_P256 ECDH_KEYGEN_P384 ECDH_KEYGEN_P521 ECDH_KEYGEN_B283 ECDH_KEYGEN_B409 ECDH_KEYGEN_B571 10.3 Usage $ bash c29x_driver_perf_profile.sh <test_name> [option] test_name: Supported test names are mentioned in Supported tests. Mandatory arguments for the test are as follows: Argument Value Description -m cpu mask Test threads are created on the CPUs masked by the value in above option. -t thread per cpu Number of threads per cpu. -s Test duration in seconds Test can be stopped anytime by ctrl + c. -r Test enqueue-dequeue count Test will enqueue this many number of requests and completes only after getting this many number of responses. Example : NOTE If -s & -r both are specified, then -s is selected by the test framework. 38 Freescale Semiconductor, Inc.

Chapter 10 Driver test framework $ bash c29x_driver_perf_profile.sh RSA_PUB_OP_1K -m 0xf -t 1 -s 10 $ bash c29x_driver_perf_profile.sh RSA_PUB_OP_1K -m 0xf -t 1 -r 100000 $ bash c29x_driver_perf_profile.sh --help -- help shows all the necessary help to run this test framework. ******** Result *********** Test Name : Host CPU Frequency : # job finished successfully : Per job in us : Total jobs in 1 sec : NOTE For P4080, this script is not a part of p4080 rootfs. Need to scp this script after P4080DS boots up. Since ppc kernel does not support floating point operations, ops/sec calculation is offloaded to a user space application program mini_calc. Source file is present at : <dir>/perf/min_calc/mini_calc.c This application needs to be cross compiled for P4080. The compiled ELF binary should be placed in the same directory where script is present inside P4080DS. Steps to run the script are same as explained above. Freescale Semiconductor, Inc. 39

Usage 40 Freescale Semiconductor, Inc.

Chapter 11 CLI Command line interface is provided on top of the driver to send control, debug and stat commands to firmware. CLI talks to driver through IOCTL. CLI support is disabled, if HIGH_PERF flag in config.mk is enabled. For more information, refer to C29x firmware build configuration. Refer to <dir>/docs/cli_readme.txt for help on CLI commands. Freescale Semiconductor, Inc. 41

42 Freescale Semiconductor, Inc.

Chapter 12 Directory structure. -- Makefile: Makefile with all the targets to build all the required software components. -- apps `-- cli: CLI implementation -- bin_images -- c29x_ep -- p4080_rc `-- x86_rc -- c29x-driver: Folder contains all the folders and files required for host driver -- Makefile -- algs: Folder contains all the algorithm implementation -- algs.c: Generic implementation required for all the algs. -- algs.h -- compat.h -- desc_cnstr.c -- desc_cnstr.h -- dh.c -- dh.h -- dsa.c -- dsa.h -- error.h -- hash.c -- hash.h -- rng.c -- rng.h -- rng_init.c -- rsa.c -- rsa.h -- sg_sw_sec4.h -- symdesc.h `-- symmetric.c -- crypto_dev -- algs_reg.c `-- algs_reg.h -- dcl: Folder contains the descriptor construction functions -- desc.h -- desc_constr.h `-- pkc_desc.h -- host_driver -- command.c -- command.h -- common.h -- crypto_ctx.h -- device.h -- dma.c -- dma.h -- fsl_c2x0_crypto_layer.c: Crypto driver implementation. -- fsl_c2x0_crypto_layer.h -- fsl_c2x0_driver.c: PCI driver implementation -- fsl_c2x0_driver.h -- fsl_c2x0_virtio.h -- ioctl.h -- memmgr.c: Memory management code for the device memory Freescale Semiconductor, Inc. 43

-- memmgr.h -- perf.c -- sysfs.c: Sysfs related interfaces `-- sysfs.h `-- test -- c29x-firmware: Folder contains firmware which works for C293 device -- c29x-virtio -- fe_driver -- qemu_be `-- virtio_c2x0_patches -- config.mk: Build time configuration parameters -- crypto.cfg: Device configuration file -- crypto_patches: Folder contains patches for Cryptodev, OpenSSL and CryptoAPI -- p4080_deps `-- x86_deps -- docs -- C29x-Crypto-Offload-User-Guide.pdf -- C29x_CLI_User_Guide.pdf -- P4080_perf_nos_with_cpu_utilization_using_mpstat.txt -- Release-Notes -- X86_perf_nos_with_cpu_utilization_using_mpstat.txt -- build_layout.txt `-- performance_capture.pdf -- perf: Folder contains the script for test framework -- c29x_driver_perf_profile.sh `-- mini_calc `-- mini_calc.c `-- sdk_build_patches: Folder contains all the patches taken by OC on SDK1.4. These are mostly bitbake related patches to enable compiling all the bitbake components from the MAKEFILE 44 Freescale Semiconductor, Inc.

Appendix A POR Configuration The C29x PCIe card has user selectable switches or registers, for evaluating different frequency and boot configuration for this device. The table below shows how POR configuration is done through switches. Switch POR configuration Table A-1. POR configuration through switches Signal name Default setting Signal meaning SW4[1] cfg_sys_pll[0] IFC_AD0 ON Rate between SW4[2] cfg_sys_pll[1] IFC_AD1 OFF SYSCLK input and CCB clock (platform SW4[3] cfg_sys_pll[2] IFC_AD2 ON clock) Settings SW4[1,2,3] ON ON ON (000): 4:1 SW4[1,2,3] ON ON OFF (001): 5:1 SW4[1,2,3] ON OFF ON (010): 6:1 Others are reserved. SYSCLK on this board is 66.67 MHz. SW4[4] cfg_sys_speed READY OFF 0: SYSCLK frequency is at or below 66 MHz. SW4[5] cfg_core_pll[0] IFC_AD3 OFF Ratio between the SW4[6] cfg_core_pll[1] IFC_AD4 ON e500 core clock and e500 CCB clock SW4[7] cfg_core_pll[2] IFC_AD5 ON SW4[8] cfg_core_speed IFC_AD6 ON Core speed configuration input SW5[1] SW_CFG_ROM_ LOC0 1: SYSCLK frequency is above 66 MHz. SW4[5,6,7] ON ON ON (000): reserved SW4[5,6,7] ON ON OFF (001): reserved SW4[5,6,7] ON OFF ON (010): 1:1 SW4[5,6,7] ON OFF OFF (011): 1.5:1 SW4[5,6,7] OFF ON ON (100): 2:1 SW4[5,6,7] OFF ON OFF (101): 2.5:1 SW4[5,6,7] OFF OFF ON (110): 3:1 SW4[5,6,7] OFF OFF OFF (111): 3.5:1 ON(0): Core clock frequency is greater than or equal to 600 MHz and less than 1001 MHz. OFF(1): Core clock frequency is greater than or equal to 1001 MHz and less than 1201 MHz. OFF Boot ROM location SW5[1:4] ON ON OFF ON (0010): 8b NAND (8k page size) Table continues on the next page... Freescale Semiconductor, Inc. 45

Switch SW5[2] SW5[3] SW5[4] POR configuration Table A-1. POR configuration through switches (continued) Signal name SW_CFG_ROM_ LOC1 SW_CFG_ROM_ LOC2 SW_CFG_ROM_ LOC3 OFF OFF OFF Default setting Signal meaning Settings SW5[1:4] ON OFF ON ON (0100): DDR controller SW5[1:4] ON OFF OFF ON (0110): SPI SW5[1:4] ON OFF OFF OFF (0111): SDHC (SD/MMC) SW5[1:4] OFF ON ON ON (1000): 8b NAND (512 page size) SW5[1:4] OFF ON ON OFF (1001): 8b NAND (2k page size) SW5[1:4] OFF ON OFF OFF (1011): 8b NOR SW5[1:4] OFF OFF ON ON (1100): 16b NAND (512 page size) SW5[1:4] OFF OFF ON OFF (1101): 16b NAND (2k page size) SW5[1:4] OFF OFF OFF OFF (1111): 16b NOR Others are reserved. SW5[5] VCORE_MGN ON ON(0): CPU will run at v1.0 core voltage SW5[6] BOOT_FLASH_S EL SW5[7] FBANK_SEL1 ON NOR boot section SW5[8] FBANK_SEL2 ON choose SW6[1] cfg_ddr_pll[0] SW_TSEC1_TXD 0 SW6[2] cfg_ddr_pll[1] SW_TSEC1_TXD 1 OFF(1): CPU will run at v1.05 core voltage ON CS0/1 select ON (0): CS0 is connected to NOR flash; CS1 is connect to NAND flash. ON ON SW6[3] cfg_ddr_pll[2] UART1_RTS_N ON Clock ratio between 100Mhz OSC clock input and DDR complex clock OFF (1): CS0 is connected to NAND flash; CS1 is connected to NOR flash. Set which section works as a boot section. SW6[1,2,3] ON ON ON (000): 8:1 SW6[1,2,3] ON ON OFF (001): 10:1 SW6[1,2,3] ON OFF ON (010): 12:1 SW6[1,2,3] ON OFF OFF (011): 13:1 SW6[1,2,3] OFF ON ON (100): 14:1 SW6[1,2,3] OFF ON OFF (101): 15:1 SW6[1,2,3] OFF OFF ON (110): 16:1 SW6[1,2,3] OFF OFF OFF (111): Reserved SW6[4] cfg_ddr_speed[0] 1588_CLK_OUT ON DDR complex speed cfg_ddr_speed[0]: SW6[5] cfg_ddr_speed[1] 1588_PULSE_O OFF configuration input ON (0): DDR data rate is less than 967 UT MHz. Table continues on the next page... 46 Freescale Semiconductor, Inc.

Table A-1. POR configuration through switches (continued) Appendix A POR Configuration Switch POR configuration Signal name Default setting Signal meaning SW6[6] cfg_plat_speed IFC_PAR1 OFF Platform speed configuration input SW6[7] cfg_boot_seq[0] IFC_A26 OFF Boot sequencer SW6[8] cfg_boot_seq[1] IFC_A19 OFF configuration options SW7[1] cfg_cpu_boot DMA_DDONE0_ N OFF CPU boot configuration inputs SW7[2] cfg_io_port[0] IFC_AD13 ON Different I/O ports SW7[3] cfg_io_port[1] IFC_AD14 ON active on the SerDes SW7[4] cfg_io_port[2] IFC_BCTL OFF Table continues on the next page... Settings OFF (1): DDR data rate is greater than or equal to 967 MHz. cfg_ddr_speed[1]: ON (0): When cfg_ddr_speed[0]=1 and cfg_ddr_pll=10 OFF (1): When cfg_ddr_speed[0]=0 and (cfg_ddr_pll=8 or cfg_ddr_pll=10 or cfg_ddr_pll>=12) or when cfg_ddr_speed[0]=1 and cfg_ddr_pll>=12 NA: When cfg_ddr_speed[0]=1 and cfg_ddr_pll=8 ON (0): Platform clock frequency is greater than or equal to 267 MHz and less than 320 MHz. OFF (1): Platform clock frequency is greater than or equal to 320 MHz and less than 401 MHz. SW6[7,8] ON OFF (01): Normal I 2 C addressing mode is used. Boot sequencer is enabled and loads configuration information from a ROM on the I 2 C1 interface. A valid ROM must be present. SW6[7,8] OFF ON (10): Extended I 2 C addressing mode is used. Boot sequencer is enabled and loads configuration information from a ROM on the I 2 C1 interface. A valid ROM must be present. SW6[7,8] OFF OFF (11): Boot sequencer is disabled. No I 2 C ROM is accessed. This is the default setting. ON (0): CPU boot hold off mode. The e500 core is prevented from booting until configured by an external master. OFF (1): The e500 core is allowed to boot without waiting for configuration by an external master. SW7[2:4] ON ON ON (000): PCIe-x4 (5 GHz) SW7[2:4] ON ON OFF (001): PCIe-x4 (2.5 GHz) SW7[2:4] ON OFF ON (010): PCIe-x2 (5 GHz) Freescale Semiconductor, Inc. 47

Switch POR configuration Table A-1. POR configuration through switches (continued) Signal name Default setting Signal meaning SW7[5] cfg_host_agt IFC_A23 ON Host/agent reset configuration input SW7[6] cfg_sb_dis HRESET_REQ_ N SW7[7] cfg_svr[0] SW_TSEC2_TXD 0 OFF OFF SW7[8] cfg_svr[1] CKSTP_OUT_N OFF SW8[1] cfg_gpinput[0] IFC_AVD ON General-purpose SW8[2] cfg_gpinput[1] IFC_WE_N ON POR configuration vector to be placed SW8[3] cfg_gpinput[2] IFC_CLE ON in GPPORCR SW8[4] cfg_gpinput[3] UART0_TXD ON SW8[5] cfg_eng_use[0] SW_EC_MDC OFF To be used in the SW8[6] cfg_eng_use[1] UART0_RTS_N ON future to control functionality. SW8[7] OFF Settings SW7[2:4] ON OFF OFF (000): PCIe-x2 (2.5 GHz) SW7[2:4] OFF ON ON (100): PCIe-x1 (5 GHz) SW7[2:4] OFF ON OFF (101): PCIe-x1 (2.5 GHz) SW7[2:4] OFF OFF ON (110): Reserved SW7[2:4] OFF OFF OFF (111): Disabled ON (0): Agent on PCI express interface OFF (1): Host/RC on PCI express interface ON(0): Secure boot enabled OFF(1):Secure boot disabled (POR) Used to check which processor is set, C291, C292, or C293. SW7[7:8]OFF OFF(11): C293 SW7[7:8]OFF OFF(10): C292 SW7[7:8]OFF OFF(01): C291 Software can then use this value to inform the operating system about initial system configuration. Typical interpretations include circuit board type, board ID number, or a list of available peripherals. SW8[5:6] OFF OFF (1:1): Default operation Others are reserved. SW8[8] TEST_SEL_N OFF PKCAL/SKMM mode ON (0): PKCAL mode OFF (1): SKMM mode The table below shows the POR configuration through registers. Table A-2. POR configuration through registers Register POR configuration Signal name Default setting Signal meaning R247 cfg_dram_type 1588_ALARM_OUT NC (1) Different voltage level from DDR3L Setting 0: DDR3L 1.35V, CKE low at reset 1: DDR3 1.5V, CKE low at reset Table continues on the next page... 48 Freescale Semiconductor, Inc.

Table A-2. POR configuration through registers (continued) Register POR configuration Signal name Default setting Signal meaning R248 cfg_ddr_pll_backup TSEC1_TXD3 NC (1) 0: Disabled 1: Enabled R249 cfg_ddr_half_full_mode TSEC2_TXD1 NC (1) 0: Half mode R250 cfg_ec1_prtc TSEC2_TXD3 NC (1) Ethernet interface mode R251 cfg_ec2_prtc TSEC1_TXD2 NC (1) Ethernet interface mode 1: Full mode 0: RMII 1: RGMII 0: RMII 1: RGMII Setting R265 cfg_ifc_pb[0] IFC_AD9 NC (1) Corresponding 000: Reserved R266 cfg_ifc_pb[1] IFC_AD10 4.7k (0) pages per block if 001: 2k pages per block NAND flash is R267 cfg_ifc_pb[2] IFC_AD11 NC (1) used for booting 010: 1k pages per block R273 cfg_ifc_ecc_mode[0] IFC_A25 NC (1) IFC ECC R274 cfg_ifc_ecc_mode[1] IFC_A27 NC (1) correction mode if NAND flash is used for booting R275 cfg_ifc_ecc_dec_en IFC_A21 4.7k (0) Enable IFC ECC checking on boot if NAND flash is used for booting R276 cfg_ifc_flash_mode IFC_A22 NC (1) Type of NOR/ NAND flash used for booting R277 cfg_ifc_adm_mode IFC_AD15 NC (1) Which address bits are multiplexed with IFC data if NOR flash is used for booting Table continues on the next page... Appendix A POR Configuration 000: 512 pages per block 100: 256 pages per block 101: 128 pages per block 110: 64 pages per block 111: 32 pages per block 00: 4b correction per 520 Byte sector 01: 8b correction per 520 Byte sector 10: 24b correction per 520 Byte sector 11: 40b correction per 520 Byte sector 0: ECC decoding disabled 1: ECC decoding enabled 0: For NOR, multiplexed NOR flash (AVD type); for NAND, bad block indicator is at page 0 and at last page of each block. 1: For NOR, normal asynchronous NOR flash; for NAND, bad block indicator is at page 0 and page 1 of each block. 0: Lower order address bits are multiplexed with data on IFC_AD[0:15] Freescale Semiconductor, Inc. 49

Table A-2. POR configuration through registers (continued) Register POR configuration Signal name Default setting Signal meaning Setting 1: Higher order address bits are multiplexed with data on IFC_AD[0:15] R278 cfg_ifc_te IFC_TE NC (1) IFC transciever enabled R279 cfg_srds_refclk IFC_AD12 NC (1) Input SerDes reference clock R493 cfg_srds_pll_timeout_e n ASLEEP NC (1) Enable SerDes PLL timeout R280 cfg_por_bist IFC_OE_N NC (1) R284 cfg_fuse_rd_en IFC_PAR0 NC (1) Enable security fuse read R286 cfg_test_port_mux_sel UART1_TXD NC (1) Test port MUX select 0: SerDes expects a 125 MHz reference clock frequency. 1: SerDes expects a 100 MHz reference clock frequency. This is the default value. 0: Disabled 1: Enabled 0: Disabled 1: Enabled 0: Not selected 1: Selected R287 cfg_test_port_dis IFC_WP_N NC (1) Disable test port 1: Disabled R289 cfg_60x TSEC2_TXD2 NC (1) R290 cfg_pcc_drowsy_en IFC_A20 4.7k (0) Enable PPC drowsy R425 cfg_sdram_drawsy_en IRQ_OUT_N 4.7k (0) Enable SDRAM drowsy 0: Enabled 0: Disabled 1: Enabled 0: Disabled 1: Enabled In the above tables, ON indicates 0 and OFF indicates 1. 50 Freescale Semiconductor, Inc.

Appendix B Revision history This table summarizes revisions to this document. Table B-1. Revision history Revision Date Description 1 12/2013 Updated document title from "C29x PCIe Crypto Offload User Guide" to "C29x PK Calculator User Guide". Updated document ID from "C29xCryptoOffloadUG" to "C29xPKCalcUG". In On X86 host, added a note about device detection. In Kernel config changes, added a note to explain how to navigate in the config menu. In Kernel config changes, added a note about updating the kernel 3.8.13 from Ubuntu 12.04 kernel. In Verify IOAT DMA support, modified the note to specify Intel Xeon 5K series instead of Xeon 5K series. In X86 disabling IOMMU hardware support, updated the introduction to specify If IOMMU Hardware Support is not disabled, you may not get any output from the test applications.. In X86 disabling IOMMU hardware support, added a note about how to reach Device Drivers menu to disable IOMMU Hardware Support. In Prerequisites, added a note "The size of QorIQ Linux SDK v1.4 ISO file is more than 2GB.". In Prerequisites, added an alternate method for changing the environment from dash to bash. In Compiling PowerPC toolchain, updated the steps to compile PowerPC toolchain. In X86 PKC extended kernel compilation, added During kernel installation, kernel config menu appears and from there select the required config options. For more information see Kernel config changes and X86 disabling IOMMU hardware support. under important points to note. In Build All software components, updated the note to specify This check is required, so that the drivers can be loaded during execution of tests, for more information see Load driver and Running the driver with openssl.. Updated Chapter title from "C29x firmware build configuration" to "C29x host driver and firmware build configuration". 0 10/2013 Initial public release. Freescale Semiconductor, Inc. 51

52 Freescale Semiconductor, Inc.

How to Reach Us: Home Page: freescale.com Web Support: freescale.com/support Information in this document is provided solely to enable system and software implementers to use Freescale products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits based on the information in this document. Freescale reserves the right to make changes without further notice to any products herein. Freescale makes no warranty, representation, or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. Typical parameters that may be provided in Freescale data sheets and/or specifications can and do vary in different applications, and actual performance may vary over time. All operating parameters, including typicals, must be validated for each customer application by customer's technical experts. Freescale does not convey any license under its patent rights nor the rights of others. Freescale sells products pursuant to standard terms and conditions of sale, which can be found at the following address: freescale.com/salestermsandconditions. Freescale, the Freescale logo, and QorIQ are trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. CoreNet is a trademark of Freescale Semiconductor, Inc. All other product or service names are the property of their respective owners. The Power Architecture and Power.org word marks and the Power and Power.org logos and related marks are trademarks and service marks licensed by Power.org. 2013 Freescale Semiconductor, Inc. Document Number C29xPKCalcUG Revision 1, 12/2013