3 * Efficient reduction modulo nice primes
5 * (c) 2004 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
28 /*----- Header files ------------------------------------------------------*/
30 #include <mLib/darray.h>
31 #include <mLib/macros.h>
35 #include "mpreduce-exp.h"
37 /*----- Data structures ---------------------------------------------------*/
39 DA_DECL(instr_v, mpreduce_instr);
41 /*----- Theory ------------------------------------------------------------*
43 * We're given a modulus %$p = 2^n - d$%, where %$d < 2^n$%, and some %$x$%,
44 * and we want to compute %$x \bmod p$%. We work in base %$2^w$%, for some
45 * appropriate %$w$%. The important observation is that
46 * %$d \equiv 2^n \pmod p$%.
48 * Suppose %$x = x' + z 2^k$%, where %$k \ge n$%; then
49 * %$x \equiv x' + d z 2^{k-n} \pmod p$%. We can use this to trim the
50 * representation of %$x$%; each time, we reduce %$x$% by a multiple of
51 * %$2^{k-n} p$%. We can do this in two passes: firstly by taking whole
52 * words off the top, and then (if necessary) by trimming the top word.
53 * Finally, if %$p \le x < 2^n$% then %$0 \le x - p < p$% and we're done.
55 * A common trick, apparently, is to choose %$d$% such that it has a very
56 * sparse non-adjacent form, and, moreover, that this form is nicely aligned
57 * with common word sizes. (That is, write %$d = \sum_{0\le i<m} d_i 2^i$%,
58 * with %$d_i \in \{ -1, 0, +1 \}$% and most %$d_i = 0$%.) Then adding
59 * %$z d$% is a matter of adding and subtracting appropriately shifted copies
62 * Most libraries come with hardwired code for doing this for a few
63 * well-known values of %$p$%. We take a different approach, for two
66 * * Firstly, it privileges built-in numbers over user-selected ones, even
67 * if the latter have the right (or better) properties.
69 * * Secondly, writing appropriately optimized reduction functions when we
70 * don't know the exact characteristics of the target machine is rather
73 * Our solution, then, is to `compile' the value %$p$% at runtime, into a
74 * sequence of simple instructions for doing the reduction.
77 /*----- Main code ---------------------------------------------------------*/
79 /* --- @mpreduce_create@ --- *
81 * Arguments: @gfreduce *r@ = structure to fill in
82 * @mp *x@ = an integer
84 * Returns: Zero if successful; nonzero on failure. The current
85 * algorithm always succeeds when given positive @x@. Earlier
86 * versions used to fail on particular kinds of integers, but
87 * this is guaranteed not to happen any more.
89 * Use: Initializes a context structure for reduction.
92 int mpreduce_create(mpreduce *r, mp *p)
95 enum { Z = 0, Z1 = 2, X = 4, X0 = 6 };
102 /* --- Fill in the easy stuff --- */
113 /* --- Stash a new instruction --- */
115 #define INSTR(op_, argx_, argy_) do { \
117 DA(&iv)[DA_LEN(&iv)].op = (op_); \
118 DA(&iv)[DA_LEN(&iv)].argx = (argx_); \
119 DA(&iv)[DA_LEN(&iv)].argy = (argy_); \
123 /* --- Main loop --- *
125 * A simple state machine decomposes @p@ conveniently into positive and
126 * negative powers of 2.
128 * Here's the relevant theory. The important observation is that
129 * %$2^i = 2^{i+1} - 2^i$%, and hence
131 * * %$\sum_{a\le i<b} 2^i = 2^b - 2^a$%, and
133 * * %$2^c - 2^{b+1} + 2^b - 2^a = 2^c - 2^b - 2^a$%.
135 * The first of these gives us a way of combining a run of several one
136 * bits, and the second gives us a way of handling a single-bit
137 * interruption in such a run.
139 * We start with a number %$p = \sum_{0\le i<n} p_i 2^i$%, and scan
140 * right-to-left using a simple state-machine keeping (approximate) track
141 * of the two previous bits. The @Z@ states denote that we're in a string
142 * of zeros; @Z1@ means that we just saw a 1 bit after a sequence of zeros.
143 * Similarly, the @X@ states denote that we're in a string of ones; and
144 * @X0@ means that we just saw a zero bit after a sequence of ones. The
145 * state machine lets us delay decisions about what to do when we've seen a
146 * change to the status quo (a one after a run of zeros, or vice-versa)
147 * until we've seen the next bit, so we can tell whether this is an
148 * isolated bit or the start of a new sequence.
150 * More formally: we define two functions %$Z^b_i$% and %$X^b_i$% as
153 * * %$Z^0_i(S, 0) = S$%
154 * * %$Z^0_i(S, n) = Z^0_{i+1}(S, n)$%
155 * * %$Z^0_i(S, n + 2^i) = Z^1_{i+1}(S, n)$%
156 * * %$Z^1_i(S, n) = Z^0_{i+1}(S \cup \{ 2^{i-1} \}, n)$%
157 * * %$Z^1_i(S, n + 2^i) = X^1_{i+1}(S \cup \{ -2^{i-1} \}, n)$%
158 * * %$X^0_i(S, n) = Z^0_{i+1}(S, \{ 2^{i-1} \})$%
159 * * %$X^0_i(S, n + 2^i) = X^1_{i+1}(S \cup \{ -2^{i-1} \}, n)$%
160 * * %$X^1_i(S, n) = X^0_{i+1}(S, n)$%
161 * * %$X^1_i(S, n + 2^i) = X^1_{i+1}(S, n)$%
163 * The reader may verify (by induction on %$n$%) that the following
166 * * %$Z^0_0(\emptyset, n)$% is well-defined for all %$n \ge 0$%
167 * * %$\sum Z^b_i(S, n) = \sum S + n + b 2^{i-1}$%
168 * * %$\sum X^b_i(S, n) = \sum S + n + (b + 1) 2^{i-1}$%
170 * From these, of course, we can deduce %$\sum Z^0_0(\emptyset, n) = n$%.
172 * We apply the above recurrence to build a simple instruction sequence for
173 * adding an appropriate multiple of %$d$% to a given number. Suppose that
174 * %$2^{w(N-1)} \le 2^{n-1} \le p < 2^n \le 2^{wN}$%. The machine which
175 * interprets these instructions does so in the context of a
176 * single-precision multiplicand @z@ and a pointer @v@ to the
177 * %%\emph{most}%% significant word of an %$N + 1$%-word integer, and the
178 * instruction sequence should add %$z d$% to this integer.
180 * The available instructions are named @MPRI_{ADD,SUB}{,LSL}@; they add
181 * (or subtract) %$z$% (shifted left by some amount, in the @LSL@ variants)
182 * to some word earlier than @v@. The relevant quantities are encoded in
183 * the instruction's immediate operands.
186 bb = MPW_BITS - (d + 1)%MPW_BITS;
187 for (i = 0, mp_scan(&sc, p); i < d && mp_step(&sc); i++) {
188 switch (st | mp_bit(&sc)) {
189 case Z | 1: st = Z1; break;
190 case Z1 | 0: st = Z; op = MPRI_SUB; goto instr;
191 case Z1 | 1: st = X; op = MPRI_ADD; goto instr;
192 case X | 0: st = X0; break;
193 case X0 | 1: st = X; op = MPRI_ADD; goto instr;
194 case X0 | 0: st = Z; op = MPRI_SUB; goto instr;
196 w = (d - i)/MPW_BITS + 1;
197 b = (bb + i)%MPW_BITS;
198 INSTR(op | !!b, w, b);
202 /* --- Fix up wrong-sided decompositions --- *
204 * At this point, we haven't actually finished up the state machine
205 * properly. We stopped scanning just after bit %$n - 1$% -- the most
206 * significant one, which we know in advance must be set (since @x@ is
207 * strictly positive). Therefore we are either in state @X@ or @Z1@. In
208 * the former case, we have nothing to do. In the latter, there are two
209 * subcases to deal with. If there are no other instructions, then @x@ is
210 * a perfect power of two, and %$d = 0$%, so again there is nothing to do.
212 * In the remaining case, we have decomposed @x@ as %$2^{n-1} + d$%, for
213 * some positive %$d%, which is unfortunate: if we're asked to reduce
214 * %$2^n$%, say, we'll end up with %$-d$% (or would do, if we weren't
215 * sticking to unsigned arithmetic for good performance). So instead, we
216 * rewrite this as %$2^n - 2^{n-1} + d$% and everything will be good.
219 if (st == Z1 && DA_LEN(&iv)) {
221 b = (bb + d)%MPW_BITS;
222 INSTR(MPRI_ADD | !!b, w, b);
229 * Store the generated instruction sequence in our context structure. If
230 * %$p$%'s bit length %$n$% is a multiple of the word size %$w$% then
231 * there's nothing much else to do here. Otherwise, we have an additional
234 * The reduction operation has three phases. The first trims entire words
235 * from the argument, and the instruction sequence constructed above does
236 * this well; the second phase reduces an integer which has the same number
237 * of words as %$p$%, but strictly more bits. (The third phase is a single
238 * conditional subtraction of %$p$%, in case the argument is the same bit
239 * length as %$p$% but greater; this doesn't concern us here.) To handle
240 * the second phase, we create another copy of the instruction stream, with
241 * all of the target shifts adjusted upwards by %$s = n \bmod w$%.
243 * In this case, we are acting on an %$(N - 1)$%-word operand, and so
244 * (given the remarks above) must check that this is still valid, but a
245 * moment's reflection shows that this must be fine: the most distant
246 * target must be the bit %$s$% from the top of the least-significant word;
247 * but since we shift all of the targets up by %$s$%, this now addresses
248 * the bottom bit of the next most significant word, and there is no
256 r->iv = xmalloc(r->in * sizeof(mpreduce_instr));
257 memcpy(r->iv, DA(&iv), r->in * sizeof(mpreduce_instr));
259 r->iv = xmalloc(r->in * 2 * sizeof(mpreduce_instr));
260 for (i = 0; i < r->in; i++) {
261 r->iv[i] = DA(&iv)[i];
262 op = r->iv[i].op & ~1u;
271 r->iv[i + r->in].op = op;
272 r->iv[i + r->in].argx = w;
273 r->iv[i + r->in].argy = b;
281 /* --- @mpreduce_destroy@ --- *
283 * Arguments: @mpreduce *r@ = structure to free
287 * Use: Reclaims the resources from a reduction context.
290 void mpreduce_destroy(mpreduce *r)
293 if (r->iv) xfree(r->iv);
296 /* --- @mpreduce_dump@ --- *
298 * Arguments: @const mpreduce *r@ = structure to dump
299 * @FILE *fp@ = file to dump on
303 * Use: Dumps a reduction context.
306 void mpreduce_dump(const mpreduce *r, FILE *fp)
309 static const char *opname[] = { "add", "addshift", "sub", "subshift" };
311 fprintf(fp, "mod = "); mp_writefile(r->p, fp, 16);
312 fprintf(fp, "\n lim = %lu; s = %d\n", (unsigned long)r->lim, r->s);
313 for (i = 0; i < r->in; i++) {
314 assert(r->iv[i].op < N(opname));
315 fprintf(fp, " %s %lu %lu\n",
317 (unsigned long)r->iv[i].argx,
318 (unsigned long)r->iv[i].argy);
321 fprintf(fp, "tail end charlie\n");
322 for (i = r->in; i < 2 * r->in; i++) {
323 assert(r->iv[i].op < N(opname));
324 fprintf(fp, " %s %lu %lu\n",
326 (unsigned long)r->iv[i].argx,
327 (unsigned long)r->iv[i].argy);
332 /* --- @mpreduce_do@ --- *
334 * Arguments: @const mpreduce *r@ = reduction context
335 * @mp *d@ = destination
338 * Returns: Destination, @x@ reduced modulo the reduction poly.
341 static void run(const mpreduce_instr *i, const mpreduce_instr *il,
344 for (; i < il; i++) {
346 case MPRI_ADD: MPX_UADDN(v - i->argx, v + 1, z); break;
347 case MPRI_ADDLSL: mpx_uaddnlsl(v - i->argx, v + 1, z, i->argy); break;
348 case MPRI_SUB: MPX_USUBN(v - i->argx, v + 1, z); break;
349 case MPRI_SUBLSL: mpx_usubnlsl(v - i->argx, v + 1, z, i->argy); break;
356 mp *mpreduce_do(const mpreduce *r, mp *d, mp *x)
359 const mpreduce_instr *il;
362 /* --- If source is negative, divide --- */
365 mp_div(0, &d, x, r->p);
369 /* --- Try to reuse the source's space --- */
373 MP_DEST(x, MP_LEN(x), x->f);
375 /* --- Stage one: trim excess words from the most significant end --- */
378 if (MP_LEN(x) >= r->lim) {
385 run(r->iv, il, vl, z);
389 /* --- Stage two: trim excess bits from the most significant word --- */
392 while (*vl >> r->s) {
394 *vl &= ((1 << r->s) - 1);
395 run(r->iv + r->in, il + r->in, vl, z);
400 /* --- Stage three: conditional subtraction --- */
403 if (MP_CMP(x, >=, r->p))
404 x = mp_sub(x, x, r->p);
411 /* --- @mpreduce_exp@ --- *
413 * Arguments: @const mpreduce *mr@ = pointer to reduction context
414 * @mp *d@ = fake destination
418 * Returns: Result, %$a^e \bmod m$%.
421 mp *mpreduce_exp(const mpreduce *mr, mp *d, mp *a, mp *e)
424 mp *spare = (e->f & MP_BURN) ? MP_NEWSEC : MP_NEW;
432 a = mp_modinv(a, a, mr->p);
433 if (MP_LEN(e) < EXP_THRESH)
444 /*----- Test rig ----------------------------------------------------------*/
448 static int vreduce(dstr *v)
450 mp *d = *(mp **)v[0].buf;
451 mp *n = *(mp **)v[1].buf;
452 mp *r = *(mp **)v[2].buf;
457 mpreduce_create(&rr, d);
458 c = mpreduce_do(&rr, MP_NEW, n);
460 fprintf(stderr, "\n*** reduction failed\n*** ");
461 mpreduce_dump(&rr, stderr);
462 fprintf(stderr, "\n*** n = "); mp_writefile(n, stderr, 10);
463 fprintf(stderr, "\n*** r = "); mp_writefile(r, stderr, 10);
464 fprintf(stderr, "\n*** c = "); mp_writefile(c, stderr, 10);
465 fprintf(stderr, "\n");
468 mpreduce_destroy(&rr);
469 mp_drop(n); mp_drop(d); mp_drop(r); mp_drop(c);
470 assert(mparena_count(MPARENA_GLOBAL) == 0);
474 static int vmodexp(dstr *v)
476 mp *p = *(mp **)v[0].buf;
477 mp *g = *(mp **)v[1].buf;
478 mp *x = *(mp **)v[2].buf;
479 mp *r = *(mp **)v[3].buf;
484 mpreduce_create(&rr, p);
485 c = mpreduce_exp(&rr, MP_NEW, g, x);
487 fprintf(stderr, "\n*** modexp failed\n*** ");
488 fprintf(stderr, "\n*** p = "); mp_writefile(p, stderr, 10);
489 fprintf(stderr, "\n*** g = "); mp_writefile(g, stderr, 10);
490 fprintf(stderr, "\n*** x = "); mp_writefile(x, stderr, 10);
491 fprintf(stderr, "\n*** c = "); mp_writefile(c, stderr, 10);
492 fprintf(stderr, "\n*** r = "); mp_writefile(r, stderr, 10);
493 fprintf(stderr, "\n");
496 mpreduce_destroy(&rr);
497 mp_drop(p); mp_drop(g); mp_drop(r); mp_drop(x); mp_drop(c);
498 assert(mparena_count(MPARENA_GLOBAL) == 0);
502 static test_chunk defs[] = {
503 { "reduce", vreduce, { &type_mp, &type_mp, &type_mp, 0 } },
504 { "modexp", vmodexp, { &type_mp, &type_mp, &type_mp, &type_mp, 0 } },
508 int main(int argc, char *argv[])
510 test_run(argc, argv, defs, SRCDIR"/t/mpreduce");
516 /*----- That's all, folks -------------------------------------------------*/