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, NULL, "min_threads", 2, "max_threads", 8, NULL);
 135  *
 136  * // Accelerate cipher
 137  * SilcCipher acc_cipher;
 138  *
 139  * acc_cipher = silc_acc_cipher(SILC_SOFTACC, cipher);
 140  * silc_cipher_set_key(acc_cipher, key, key_len, TRUE);
 141  * silc_cipher_set_iv(acc_cipher, iv);
 142  *
 143  * // Encrypt with the accelerated cipher
 144  * silc_cipher_encrypt(acc_cipher, src, dst, len, NULL);
 145  *
 146  * // Free accelerated cipher
 147  * silc_cipher_free(acc_cipher);
 148  *
 149  * // Free the original associated cipher
 150  * silc_cipher_free(cipher);
 151  *
 152  ***/
 153
 154 #ifndef SOFTACC_H
 155 #define SOFTACC_H
 156
 157 /****s* silcacc/softacc
 158  *
 159  * NAME
 160  *
 161  *    silc_softacc
 162  *
 163  * DESCRIPTION
 164  *
 165  *    The software accelerator context.  It can be used when initializing
 166  *    the accelerator.  It may be used directly with the SILC Accelerator
 167  *    Interface after initialization also.
 168  *
 169  *    Softare accelerator need not be registered with silc_acc_register
 170  *    because it is registered automatically in SILC Crypto Toolkit, however
 171  *    it must be initialized.
 172  *
 173  *    The software accelerator must be initialized once per application.  If
 174  *    it is initialized again it will be uninitialized first automatically
 175  *    and then re-initialized.  When it is not needed anymore (usually when
 176  *    the program is ended) it must be uninitialized by calling the
 177  *    silc_acc_uninit.
 178  *
 179  * EXAMPLE
 180  *
 181  *    // Initialize the software accelerator.
 182  *    silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL);
 183  *
 184  ***/
 185 extern DLLAPI const SilcAcceleratorStruct silc_softacc;
 186
 187 /****d* silcacc/SILC_SOFTACC
 188  *
 189  * NAME
 190  *
 191  *    #define SILC_SOFTACC (SilcAccelerator)&softacc
 192  *
 193  * DESCRIPTION
 194  *
 195  *    Softacc context macro that can be used with silc_acc_init.
 196  *
 197  ***/
 198 #define SILC_SOFTACC (SilcAccelerator)&silc_softacc
 199
 200 /****d* silcacc/SILC_SOFTACC_NAME
 201  *
 202  * NAME
 203  *
 204  *    #define SILC_SOFTACC_NAME "softacc"
 205  *
 206  * DESCRIPTION
 207  *
 208  *    The name of the software accelerator.
 209  *
 210  ***/
 211 #define SILC_SOFTACC_NAME "softacc"
 212
 213 #endif /* SOFTACC_H */