target/linux/generic/files/crypto/ocf/README

   1 ###########################
   2 README - ocf-linux-20100530
   3 ###########################
   4
   5 This README provides instructions for getting ocf-linux compiled and
   6 operating in a generic linux environment.  Other information on the project
   7 can be found at the home page:
   8
   9     http://ocf-linux.sourceforge.net/
  10
  11 Embedded systems and applications requiring userspace acceleration will need
  12 to patch the kernel source to get full OCF support.  See "Adding OCF to
  13 linux source" below.  Otherwise the "OCF Quickstart" that follows is the
  14 easiest way to get started.
  15
  16 If your goal is to accelerate Openswan on Ubuntu or CentOS,  you may find
  17 that the required binaries are already available on openswan.org:
  18
  19     ftp://ftp.openswan.org/ocf/
  20     ftp://ftp.openswan.org/openswan/binaries/ubuntu/
  21
  22 #####################################################
  23 OCF Quickstart for Ubuntu/Others (including Openswan)
  24 #####################################################
  25
  26 This section provides instructions on how to quickly add kernel only support
  27 for OCF to a GNU/Linux system.  It is only suitable for in-kernel use such as
  28 Openswan MAST/KLIPS.
  29
  30 If the target is an embedded system, or, userspace acceleration of
  31 applications such as OpenVPN and OpenSSL, the section below titled
  32 "Adding OCF to linux source" is more appropriate.
  33
  34 Before building kernel only support for OCF ensure that the appropriate
  35 linux-headers package is installed:
  36
  37     cd ocf
  38     make ocf_modules
  39     sudo make ocf_install
  40     OCF_DIR=`pwd`            # remember where OCF sources were built
  41
  42 At this point the ocf, cryptosoft, ocfnull, hifn7751 and ocf-bench modules
  43 should have been built and installed.  The OCF installation can be tested
  44 with the following commands:
  45
  46     modprobe ocf
  47     modprobe cryptosoft
  48     modprobe ocf-bench
  49     dmesg | tail -5
  50
  51 The final modprobe of ocf-bench will fail,  this is intentional as ocf-bench
  52 is a short lived module that tests in-kernel performance of OCF.  If
  53 everything worked correctly the "dmesg | tail -5" should include a line
  54 like:
  55
  56     [  583.128741] OCF: 45133 requests of 1488 bytes in 251 jiffies (535.122 Mbps)
  57
  58 This shows the in-kernel performance of OCF using the cryptosoft driver.
  59 For addition driver load options,  see "How to load the OCF modules" below.
  60
  61 If the intention is to run an OCF accelerated Openswan (KLIPS/MAST) then use
  62 these steps to compile openswan downloaded from openswan.org (2.6.34 or later).
  63
  64     tar xf openswan-2.6.34.tar.gz
  65     cd openswan-2.6.34
  66     make programs
  67     make KERNELSRC=/lib/modules/`uname -r`/build \
  68         KBUILD_EXTRA_SYMBOLS=$OCF_DIR/Module.symvers \
  69         MODULE_DEF_INCLUDE=`pwd`/packaging/ocf/config-all.hmodules \
  70         MODULE_DEFCONFIG=`pwd`/packaging/ocf/defconfig \
  71         module
  72     sudo make KERNELSRC=/lib/modules/`uname -r`/build \
  73         KBUILD_EXTRA_SYMBOLS=$OCF_DIR/Module.symvers \
  74         MODULE_DEF_INCLUDE=`pwd`/packaging/ocf/config-all.hmodules \
  75         MODULE_DEFCONFIG=`pwd`/packaging/ocf/defconfig \
  76         install minstall
  77
  78 The rest of this document is only required for more complex build
  79 requirements.
  80
  81 ##########################
  82 Adding OCF to linux source
  83 ##########################
  84
  85 It is recommended that OCF be built as modules as it increases the
  86 flexibility and ease of debugging the system.
  87
  88 Ensure that the system has /dev/crypto for userspace access to OCF:
  89
  90     mknod /dev/crypto c 10 70
  91
  92 Generate the kernel patches and apply the appropriate one.
  93
  94     cd ocf
  95     make patch
  96
  97 This will provide three files:
  98
  99     linux-2.4.*-ocf.patch
 100     linux-2.6.*-ocf.patch
 101     ocf-linux-base.patch
 102
 103 If either of the first two patches applies to the targets kernel,  then one
 104 of the following as required:
 105
 106     cd linux-2.X.Y; patch -p1 < linux-2.4.*-ocf.patch
 107     cd linux-2.6.Y; patch -p1 < linux-2.6.*-ocf.patch
 108
 109 Otherwise,  locate the appropriate kernel patch in the patches directory and
 110 apply that as well as the ocf-linux-base.patch using '-p1'.
 111
 112 When using a linux-2.4 system on a non-x86 platform,  the following may be
 113 required to build cryptosoft:
 114
 115     cp linux-2.X.x/include/asm-i386/kmap_types.h linux-2.X.x/include/asm-YYY
 116
 117 When using cryptosoft, for simplicity, enable all the crypto support in the
 118 kernel except for the test driver.  Likewise for the OCF options.  Do not
 119 enable OCF crypto drivers for HW that is not present (for example the ixp4xx
 120 driver will not compile on non-Xscale systems).
 121
 122 Make sure that cryptodev.h from the ocf directory is installed as
 123 crypto/cryptodev.h in an include directory that is used for building
 124 applications for the target platform.  For example on a host system that
 125 might be:
 126
 127     /usr/include/crypto/cryptodev.h
 128
 129 Patch the openssl-0.9.8r code the openssl-0.9.8r.patch from the patches
 130 directory.  There are many older patch versions in the patches directory
 131 if required.
 132
 133 The openssl patches provide the following functionality:
 134
 135     * enables --with-cryptodev for non BSD systems
 136     * adds -cpu option to openssl speed for calculating CPU load under linux
 137     * fixes null pointer in openssl speed multi thread output.
 138     * fixes test keys to work with linux crypto's more stringent key checking.
 139     * adds MD5/SHA acceleration (Ronen Shitrit), only enabled with the
 140       --with-cryptodev-digests option
 141     * fixes bug in engine code caching.
 142
 143 Build the crypto-tools directory for the target to obtain a userspace
 144 testing tool call cryptotest.
 145
 146 ###########################
 147 How to load the OCF modules
 148 ###########################
 149
 150 First insert the base modules (cryptodev is optional,  it is only used
 151 for userspace acceleration):
 152
 153     modprobe ocf
 154     modprobe cryptodev
 155
 156 Load the software OCF driver with:
 157
 158     modprobe cryptosoft
 159
 160 and zero or more of the OCF HW drivers with:
 161
 162     modprobe safe
 163     modprobe hifn7751
 164     modprobe ixp4xx
 165     ...
 166
 167 All the drivers take a debug option to enable verbose debug so that
 168 OCF operation may be observed via "dmesg" or the console.  For debug
 169 load the modules as:
 170
 171     modprobe ocf crypto_debug=1
 172     modprobe cryptodev cryptodev_debug=1
 173     modprobe cryptosoft swcr_debug=1
 174
 175 More than one OCF crypto driver may be loaded but then there is no
 176 guarantee as to which will be used (other than a preference for HW
 177 drivers over SW drivers by most applications).
 178
 179 It is also possible to enable debug at run time on linux-2.6 systems
 180 with the following:
 181
 182     echo 1 > /sys/module/ocf/parameters/crypto_debug
 183     echo 1 > /sys/module/cryptodev/parameters/cryptodev_debug
 184     echo 1 > /sys/module/cryptosoft/parameters/swcr_debug
 185     echo 1 > /sys/module/hifn7751/parameters/hifn_debug
 186     echo 1 > /sys/module/safe/parameters/safe_debug
 187     echo 1 > /sys/module/ixp4xx/parameters/ixp_debug
 188     ...
 189
 190 The ocf-bench driver accepts the following parameters:
 191
 192     request_q_len - Maximum number of outstanding requests to OCF
 193     request_num   - run for at least this many requests
 194     request_size  - size of each request (multiple of 16 bytes recommended)
 195     request_batch - enable OCF request batching
 196     request_cbimm - enable OCF immediate callback on completion
 197
 198 For example:
 199
 200     modprobe ocf-bench request_size=1024 request_cbimm=0
 201
 202 #######################
 203 Testing the OCF support
 204 #######################
 205
 206 run "cryptotest",  it should do a short test for a couple of
 207 des packets.  If it does everything is working.
 208
 209 If this works,  then ssh will use the driver when invoked as:
 210
 211     ssh -c 3des username@host
 212
 213 to see for sure that it is operating, enable debug as defined above.
 214
 215 To get a better idea of performance run:
 216
 217     cryptotest 100 4096
 218
 219 There are more options to cryptotest,  see the help.
 220
 221 It is also possible to use openssl to test the speed of the crypto
 222 drivers.
 223
 224     openssl speed -evp des -engine cryptodev -elapsed
 225     openssl speed -evp des3 -engine cryptodev -elapsed
 226     openssl speed -evp aes128 -engine cryptodev -elapsed
 227
 228 and multiple threads (10) with:
 229
 230     openssl speed -evp des -engine cryptodev -elapsed -multi 10
 231     openssl speed -evp des3 -engine cryptodev -elapsed -multi 10
 232     openssl speed -evp aes128 -engine cryptodev -elapsed -multi 10
 233
 234 for public key testing you can try:
 235
 236     cryptokeytest
 237     openssl speed -engine cryptodev rsa -elapsed
 238     openssl speed -engine cryptodev dsa -elapsed
 239
 240
 241 #############################
 242 #
 243 # David McCullough
 244 # david_mccullough@mcafee.com
 245 #
 246 #############################