X-Git-Url: http://git.silcnet.org/gitweb/?p=crypto.git;a=blobdiff_plain;f=lib%2Fsilcacc%2Fsoftacc.h;fp=lib%2Fsilcacc%2Fsoftacc.h;h=1439321bc797d0df4bb4883635eb00d0b4a15775;hp=a359736e3223cb670fc6397891d9c27887c79d7d;hb=80dc2a39c614ea1376a2e19ebe2460af11c9afee;hpb=9f20f0382b6229eca740925a73f96294f6dcedc6 diff --git a/lib/silcacc/softacc.h b/lib/silcacc/softacc.h index a359736e..1439321b 100644 --- a/lib/silcacc/softacc.h +++ b/lib/silcacc/softacc.h @@ -4,7 +4,7 @@ Author: Pekka Riikonen - Copyright (C) 2007 Pekka Riikonen + Copyright (C) 2007 - 2008 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -17,21 +17,181 @@ */ +/****h* silcacc/Software Accelerator + * + * DESCRIPTION + * + * Software accelerator is a thread-pool system where computationally + * expensive operations are executed in multiple threads for the purpose of + * off-loading and balancing the computations across multiple cores and + * processors. + * + * Software accelerator need not be registered with silc_acc_register + * because it is registered automatically in SILC Crypto Toolkit, however + * it must be initialized with silc_acc_init. + * + * ACCELERATORS + * + * Public key and private key accelerator: + * + * The software accelerator can accelerate public keys and private keys. + * The public key and private key operations are executed in threads to + * enhance the overall performance of the program and machine when multiple + * public key and private key operations need to be executed at the same + * time. This can significantly improve performance, especially in server + * applications. + * + * The accelerated public key and private key can be used with normal + * SILC PKCS API. Internally however the software accelerator is used. + * The SilcSchedule must be given as argument to silc_acc_init if the + * softacc is used to accelerate public keys and private keys. + * + * Ciphers: + * + * The software accelerator can accelerate ciphers. The only supported + * encryption mode is Counter Mode (CTR). Ciphers with other encryption + * modes cannot be accelerated. The CTR mode is accelerated by pre-computing + * the CTR key stream in threads. This can significantly enhance both + * encryption and decryption performance. + * + * The accelerated cipher can be used with normal SILC Cipher API. + * Internally however the software accelerator is used. Currently only + * one limitation exist with accelerated ciphers and SILC Cipher API; The + * optional IV argument in silc_cipher_encrypt and silc_cipher_decrypt + * cannot be used. The IV must be set with silc_cipher_set_iv prior to + * encrypting and decrypting. Usually, this is not an issue for programmer. + * + * PERFORMANCE + * + * Ciphers: + * + * The AES is especially optimized in softacc. Other ciphers can be used + * as well, but their performance does not match that of the AES. + * + * On dual-core machine the default settings should give very good peak + * performance. In 2008, AES-128 was measured 2.0 Gbit/sec with default + * settings. + * + * On 4-core and 8-core machines the default settings will not give the + * best performance. To get the best performance out, one must commit + * system resources (RAM) for softacc. In 2008, AES-128 was measured 5.68 + * Gbit/sec with cipher_blocks=65536 and cipher_streams=32 on 4-core + * machine (Xeon 5160 3GHz) and 9.08 Gbit/sec with cipher_blocks=65536 and + * cipher_streams=64 on 8-core machine (Xeon E5345 2.33GHz). With default + * settings you can expect 1-3 Gbit/sec reduction in peak performance. + * + * OPTIONS + * + * The following options can affect the behavior of the softacc and can be + * given as argument to the silc_acc_init when initializing the softacc. + * + * "min_threads" + * + * The minimum amount of threads that the softacc will always run. If + * this isn't given the default number is 0 (does not start any threads + * when initialized). + * + * "max_threads" + * + * The maximum amount of threads the software accelerator can use. If + * you are using the softacc only for accelerating public key and private + * key operations this number should be the number of CPU cores in your + * machine. If you are using it also for accelerating ciphers this number + * may need to be fairly large. Each acclerated cipher will reserve + * "cipher_threads" many threads from the softacc. Always leave some + * threads free for the public key and private key acceleration to work. + * If this option is not given the default number is 4. + * + * "cipher_threads" + * + * The number of threads each accelerated cipher will use. Note that, + * each accelerated cipher will reserve this many threads from the softacc. + * The "max_threads" will determine the final maximum number of threads + * the softacc can use. If the "max_threads" limit is reached no more + * ciphers can be accelerated (also note that if this happens, public key + * and private key acceleration does not work anymore). The threads are + * reserved as long as the cipher is accelerated. If this option is not + * given the default number is 2. + * + * "cipher_blocks" + * + * The number of cipher blocks the softacc will pre-compute. Each cipher + * block consumes 16 or 8 bytes of memory, depending on the size of the + * actual cipher block size. This value can be used to tweak the + * performance of the softacc. If this option is not given the default + * number is 4096. The number must be multiple of 16. + * + * "cipher_streams" + * + * The number of pre-computation streams each accelerated cipher will use. + * Each stream will use "cipher_blocks" many blocks in the stream. This + * number can be used to tweak the performance of the softacc. If this + * option is not given the default number is 2 * "cipher_threads". + * + * EXAMPLE + * + * // Initialize the software accelerator. + * silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL); + * + ***/ + #ifndef SOFTACC_H #define SOFTACC_H -/* The software accelerator */ +/****s* silcacc/softacc + * + * NAME + * + * SILC_SOFTACC + * + * DESCRIPTION + * + * The software accelerator context. It can be used when initializing + * the accelerator. It may be used directly with the SILC Accelerator + * Interface after initialization also. + * + * Softare accelerator need not be registered with silc_acc_register + * because it is registered automatically in SILC Crypto Toolkit, however + * it must be initialized. + * + * The software accelerator must be initialized once per application. If + * it is initialized again it will be uninitialized first automatically + * and then re-initialized. When it is not needed anymore (usually when + * the program is ended) it must be uninitialized by calling the + * silc_acc_uninit. + * + * EXAMPLE + * + * // Initialize the software accelerator. + * silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL); + * + ***/ extern DLLAPI const SilcAcceleratorStruct softacc; -SilcBool silc_softacc_init(SilcSchedule schedule, va_list va); -SilcBool silc_softacc_uninit(void); -SILC_PKCS_ALG_IMPORT_PUBLIC_KEY(silc_softacc_acc_public_key); -SILC_PKCS_ALG_PUBLIC_KEY_FREE(silc_softacc_free_public_key); -SILC_PKCS_ALG_IMPORT_PRIVATE_KEY(silc_softacc_acc_private_key); -SILC_PKCS_ALG_PRIVATE_KEY_FREE(silc_softacc_free_private_key); -SILC_PKCS_ALG_ENCRYPT(silc_softacc_encrypt); -SILC_PKCS_ALG_DECRYPT(silc_softacc_decrypt); -SILC_PKCS_ALG_SIGN(silc_softacc_sign); -SILC_PKCS_ALG_VERIFY(silc_softacc_verify); +/****d* silcacc/SILC_SOFTACC + * + * NAME + * + * #define SILC_SOFTACC (SilcAccelerator)&softacc + * + * DESCRIPTION + * + * The name of the software accelerator. + * + ***/ +#define SILC_SOFTACC (SilcAccelerator)&softacc + +/****d* silcacc/SILC_SOFTACC_NAME + * + * NAME + * + * #define SILC_SOFTACC_NAME "softacc" + * + * DESCRIPTION + * + * The name of the software accelerator. + * + ***/ +#define SILC_SOFTACC_NAME "softacc" #endif /* SOFTACC_H */