lib/silcacc/softacc.h

   1 /*
   2
   3   softacc.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2007 - 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcacc/Software Accelerator
  21  *
  22  * DESCRIPTION
  23  *
  24  * Software accelerator is a thread-pool system where computationally
  25  * expensive operations are executed in multiple threads for the purpose of
  26  * off-loading and balancing the computations across multiple cores and
  27  * processors.
  28  *
  29  * Software accelerator need not be registered with silc_acc_register
  30  * because it is registered automatically in SILC Crypto Toolkit, however
  31  * it must be initialized with silc_acc_init.
  32  *
  33  * ACCELERATORS
  34  *
  35  * Public key and private key accelerator:
  36  *
  37  * The software accelerator can accelerate public keys and private keys.
  38  * The public key and private key operations are executed in threads to
  39  * enhance the overall performance of the program and machine when multiple
  40  * public key and private key operations need to be executed at the same
  41  * time.  This can significantly improve performance, especially in server
  42  * applications.
  43  *
  44  * The accelerated public key and private key can be used with normal
  45  * SILC PKCS API.  Internally however the software accelerator is used.
  46  * The SilcSchedule must be given as argument to silc_acc_init if the
  47  * softacc is used to accelerate public keys and private keys.
  48  *
  49  * Ciphers:
  50  *
  51  * The software accelerator can accelerate ciphers.  The only supported
  52  * encryption mode is Counter Mode (CTR).  Ciphers with other encryption
  53  * modes cannot be accelerated.  The CTR mode is accelerated by pre-computing
  54  * the CTR key stream in threads.  This can significantly enhance both
  55  * encryption and decryption performance.
  56  *
  57  * The accelerated cipher can be used with normal SILC Cipher API.
  58  * Internally however the software accelerator is used.  Currently only
  59  * one limitation exist with accelerated ciphers and SILC Cipher API;  The
  60  * optional IV argument in silc_cipher_encrypt and silc_cipher_decrypt
  61  * cannot be used.  The IV must be set with silc_cipher_set_iv prior to
  62  * encrypting and decrypting.  Usually, this is not an issue for programmer.
  63  *
  64  * PERFORMANCE
  65  *
  66  * Ciphers:
  67  *
  68  * The AES is especially optimized in softacc.  Other ciphers can be used
  69  * as well, but their performance does not match that of the AES.
  70  *
  71  * On dual-core machine the default settings should give very good peak
  72  * performance.  In 2008, AES-128 was measured 2.0 Gbit/sec with default
  73  * settings.
  74  *
  75  * On 4-core and 8-core machines the default settings will not give the
  76  * best performance.  To get the best performance out, one must commit
  77  * system resources (RAM) for softacc.  In 2008, AES-128 was measured 5.68
  78  * Gbit/sec with cipher_blocks=65536 and cipher_streams=32 on 4-core
  79  * machine (Xeon 5160 3GHz) and 9.08 Gbit/sec with cipher_blocks=65536 and
  80  * cipher_streams=64 on 8-core machine (Xeon E5345 2.33GHz).  With default
  81  * settings you can expect 1-3 Gbit/sec reduction in peak performance.
  82  *
  83  * OPTIONS
  84  *
  85  * The following options can affect the behavior of the softacc and can be
  86  * given as argument to the silc_acc_init when initializing the softacc.
  87  *
  88  * "min_threads"
  89  *
  90  *  The minimum amount of threads that the softacc will always run.  If
  91  *  this isn't given the default number is 0 (does not start any threads
  92  *  when initialized).
  93  *
  94  * "max_threads"
  95  *
  96  *  The maximum amount of threads the software accelerator can use.  If
  97  *  you are using the softacc only for accelerating public key and private
  98  *  key operations this number should be the number of CPU cores in your
  99  *  machine.  If you are using it also for accelerating ciphers this number
 100  *  may need to be fairly large.  Each acclerated cipher will reserve
 101  *  "cipher_threads" many threads from the softacc.  Always leave some
 102  *  threads free for the public key and private key acceleration to work.
 103  *  If this option is not given the default number is 4.
 104  *
 105  * "cipher_threads"
 106  *
 107  *  The number of threads each accelerated cipher will use.  Note that,
 108  *  each accelerated cipher will reserve this many threads from the softacc.
 109  *  The "max_threads" will determine the final maximum number of threads
 110  *  the softacc can use.  If the "max_threads" limit is reached no more
 111  *  ciphers can be accelerated (also note that if this happens, public key
 112  *  and private key acceleration does not work anymore).  The threads are
 113  *  reserved as long as the cipher is accelerated.  If this option is not
 114  *  given the default number is 2.
 115  *
 116  * "cipher_blocks"
 117  *
 118  *  The number of cipher blocks the softacc will pre-compute.  Each cipher
 119  *  block consumes 16 or 8 bytes of memory, depending on the size of the
 120  *  actual cipher block size.  This value can be used to tweak the
 121  *  performance of the softacc.  If this option is not given the default
 122  *  number is 4096.  The number must be multiple of 16.
 123  *
 124  * "cipher_streams"
 125  *
 126  *  The number of pre-computation streams each accelerated cipher will use.
 127  *  Each stream will use "cipher_blocks" many blocks in the stream.  This
 128  *  number can be used to tweak the performance of the softacc.  If this
 129  *  option is not given the default number is 2 * "cipher_threads".
 130  *
 131  * EXAMPLE
 132  *
 133  * // Initialize the software accelerator.
 134  * silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL);
 135  *
 136  ***/
 137
 138 #ifndef SOFTACC_H
 139 #define SOFTACC_H
 140
 141 /****s* silcacc/softacc
 142  *
 143  * NAME
 144  *
 145  *    SILC_SOFTACC
 146  *
 147  * DESCRIPTION
 148  *
 149  *    The software accelerator context.  It can be used when initializing
 150  *    the accelerator.  It may be used directly with the SILC Accelerator
 151  *    Interface after initialization also.
 152  *
 153  *    Softare accelerator need not be registered with silc_acc_register
 154  *    because it is registered automatically in SILC Crypto Toolkit, however
 155  *    it must be initialized.
 156  *
 157  *    The software accelerator must be initialized once per application.  If
 158  *    it is initialized again it will be uninitialized first automatically
 159  *    and then re-initialized.  When it is not needed anymore (usually when
 160  *    the program is ended) it must be uninitialized by calling the
 161  *    silc_acc_uninit.
 162  *
 163  * EXAMPLE
 164  *
 165  *    // Initialize the software accelerator.
 166  *    silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL);
 167  *
 168  ***/
 169 extern DLLAPI const SilcAcceleratorStruct softacc;
 170
 171 /****d* silcacc/SILC_SOFTACC
 172  *
 173  * NAME
 174  *
 175  *    #define SILC_SOFTACC (SilcAccelerator)&softacc
 176  *
 177  * DESCRIPTION
 178  *
 179  *    The name of the software accelerator.
 180  *
 181  ***/
 182 #define SILC_SOFTACC (SilcAccelerator)&softacc
 183
 184 /****d* silcacc/SILC_SOFTACC_NAME
 185  *
 186  * NAME
 187  *
 188  *    #define SILC_SOFTACC_NAME "softacc"
 189  *
 190  * DESCRIPTION
 191  *
 192  *    The name of the software accelerator.
 193  *
 194  ***/
 195 #define SILC_SOFTACC_NAME "softacc"
 196
 197 #endif /* SOFTACC_H */