5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2007 - 2008 Pekka Riikonen
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.
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.
20 /****h* silcacc/Software Accelerator
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
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.
35 * Public key and private key accelerator:
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
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.
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.
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.
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.
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
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.
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.
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
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.
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.
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.
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".
133 * // Initialize the software accelerator.
134 * silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL);
141 /****s* silcacc/softacc
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.
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.
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
165 * // Initialize the software accelerator.
166 * silc_acc_init(SILC_SOFTACC, "min_threads", 2, "max_threads", 8, NULL);
169 extern DLLAPI const SilcAcceleratorStruct softacc;
171 /****d* silcacc/SILC_SOFTACC
175 * #define SILC_SOFTACC (SilcAccelerator)&softacc
179 * The name of the software accelerator.
182 #define SILC_SOFTACC (SilcAccelerator)&softacc
184 /****d* silcacc/SILC_SOFTACC_NAME
188 * #define SILC_SOFTACC_NAME "softacc"
192 * The name of the software accelerator.
195 #define SILC_SOFTACC_NAME "softacc"
197 #endif /* SOFTACC_H */