[catacomb] / math / mpx-mul4-test.c

/* -*-c-*-
 *
 * Testing optimized 128-bit multipliers
 *
 * (c) 2017 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * Catacomb is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Header files ------------------------------------------------------*/

#include "config.h"

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <mLib/macros.h>
#include <mLib/report.h>
#include <mLib/testrig.h>

#include "dispatch.h"
#include "mp.h"
#include "mpmont.h"
#include "mptext.h"

/*----- CPU feature detection ---------------------------------------------*/

#if CPUFAM_X86
#  define VARIANT _x86_sse2
#  define REPR_32
static int cpu_features_p(void) { return (cpu_feature_p(CPUFEAT_X86_SSE2)); }
#endif

#if CPUFAM_AMD64
#  define VARIANT _amd64_sse2
#  define REPR_32
static int cpu_features_p(void) { return (cpu_feature_p(CPUFEAT_X86_SSE2)); }
#endif

#ifndef VARIANT
#  error "Unsupported CPU family."
#endif

#ifdef REPR_32
#  define NWBY 4
#  define NDBY 8
#  define LDW LOAD32
#  define LDD LOAD64
#  define STW STORE32
#  define STD STORE64
typedef struct { mpw w[4]; } p128;
typedef struct { mpw w[8]; } x128;
typedef struct { mpd w[6]; } carry;
#endif

/*----- Test operation table ----------------------------------------------*/

#define TESTOPS(_)							\
	 /*  a     c      u     x     v     y    z'    y'     c' */	\
  _(dmul4, NIL,  CARRY, P128, P128, P128, P128, P128, NIL,  CARRY)	\
  _(dmla4, P128, CARRY, P128, P128, P128, P128, P128, NIL,  CARRY)	\
  _(mul4,  NIL,	 CARRY, NIL,  P128, NIL,  P128, P128, NIL,  CARRY)	\
  _(mla4,  P128, CARRY, NIL,  P128, NIL,  P128, P128, NIL,  CARRY)	\
  _(mmul4, NIL,	 NIL,	P128, P128, P128, P128, P128, X128, CARRY)	\
  _(mmla4, P128, NIL,	P128, P128, P128, P128, P128, X128, CARRY)	\
  _(mont4, P128, NIL,	NIL,  P128, NIL,  P128, P128, X128, CARRY)

/*----- Assembler test interface ------------------------------------------*/

#define EMPTY

#define PARAM(v, ty) ty *v,
#define PARAM_NIL(v, q)
#define PARAM_P128(v, q) PARAM(v, q p128)
#define PARAM_X128(v, q) PARAM(v, q x128)
#define PARAM_CARRY(v, q) PARAM(v, q carry)

#define DECLSTUB(fn, tya, tyc, tyu, tyx, tyv, tyy, tyzz, tyyy, tycc)	\
  extern void test_##fn(PARAM_##tyzz(zz, EMPTY) PARAM_##tycc(cc, EMPTY)	\
			PARAM_##tyyy(yy, EMPTY)				\
			PARAM_##tyu(u, const) PARAM_##tyx(x, const)	\
			PARAM_##tyv(v, const) PARAM_##tyy(y, const)	\
			unsigned n, unsigned long long *cyv);
TESTOPS(DECLSTUB)

/*----- Conversion functions ----------------------------------------------*/

#define DEFTYPE(ty, ld, st, nby)					\
									\
  static void cvt_##ty(const char *buf, dstr *d)			\
  {									\
    dstr dd = DSTR_INIT;						\
    int i;								\
    ty *x;								\
    const octet *p;							\
									\
    type_hex.cvt(buf, &dd);						\
    if (dd.len != N(x->w)*nby) die(1, "invalid length for " #ty);	\
    dstr_ensure(d, sizeof(*x)); d->len = sizeof(*x);			\
    x = (ty *)d->buf; p = (const octet *)dd.buf;			\
    for (i = 0; i < N(x->w); i++) { x->w[i] = ld(p); p += nby; }	\
    dstr_destroy(&dd);							\
  }									\
									\
  static void dump_##ty(dstr *d, FILE *fp)				\
  {									\
    dstr dd = DSTR_INIT;						\
    int i;								\
    const ty *x = (const ty *)d->buf;					\
    octet *p;								\
									\
    dstr_ensure(&dd, N(x->w)*nby); p = (octet *)dd.buf;			\
    for (i = 0; i < N(x->w); i++) { st(p, x->w[i]); p += nby; }		\
    dd.len = N(x->w)*nby;						\
    type_hex.dump(&dd, fp);						\
    dstr_destroy(&dd);							\
  }									\
									\
  static int eq_##ty(const ty *x, const ty *y)				\
  {									\
    int i;								\
									\
    for (i = 0; i < N(x->w); i++)					\
      if (x->w[i] != y->w[i]) return (0);				\
    return (1);								\
  }									\
									\
  static const struct test_type type_##ty = { cvt_##ty, dump_##ty };

DEFTYPE(p128, LDW, STW, NWBY)
DEFTYPE(x128, LDW, STW, NWBY)
DEFTYPE(carry, LDD, STD, NDBY)

/*----- Test functions ----------------------------------------------------*/

#define DECL_IN(v, ty) \
  dstr *d_##v = dp++; const ty *v = (const ty *)d_##v->buf;
#define DECL_IN_NIL(v)
#define DECL_IN_P128(v) DECL_IN(v, p128)
#define DECL_IN_X128(v) DECL_IN(v, x128)
#define DECL_IN_CARRY(v) DECL_IN(v, carry)

#define DECL_OUT(v, ty) \
  dstr dd_##v = DSTR_INIT, *d_##v = &dd_##v; ty *v;
#define DECL_OUT_NIL(v)
#define DECL_OUT_P128(v) DECL_OUT(v, p128)
#define DECL_OUT_X128(v) DECL_OUT(v, x128)
#define DECL_OUT_CARRY(v) DECL_OUT(v, carry)

#define INIT_OUT(v, ty) \
  dstr_ensure(d_##v, sizeof(ty)); v = (ty *)d_##v->buf;
#define INIT_OUT_NIL(v)
#define INIT_OUT_P128(v) INIT_OUT(v, p128)
#define INIT_OUT_X128(v) INIT_OUT(v, x128)
#define INIT_OUT_CARRY(v) INIT_OUT(v, carry)

#define ARG(v) , v
#define ARG_NIL(v)
#define ARG_P128(v) ARG(v)
#define ARG_X128(v) ARG(v)
#define ARG_CARRY(v) ARG(v)

#define CHECK(v, vv, ty) if (!eq_##ty(v, vv)) ok = 0;
#define CHECK_NIL(v, vv)
#define CHECK_P128(v, vv) CHECK(v, vv, p128)
#define CHECK_X128(v, vv) CHECK(v, vv, x128)
#define CHECK_CARRY(v, vv) CHECK(v, vv, carry)

#define DUMP(v, ty) \
  fprintf(stderr, "\n\t%-6s = ", #v); dump_##ty(d_##v, stderr);
#define DUMP_NIL(v)
#define DUMP_P128(v) DUMP(v, p128)
#define DUMP_X128(v) DUMP(v, x128)
#define DUMP_CARRY(v) DUMP(v, carry)

#define COPY(v, vv, ty) *v = *vv;
#define COPY_NIL(v, vv)
#define COPY_P128(v, vv) COPY(v, vv, p128)
#define COPY_X128(v, vv) COPY(v, vv, x128)
#define COPY_CARRY(v, vv) COPY(v, vv, carry)

#define FREE_OUT(v, ty) dstr_destroy(d_##v);
#define FREE_OUT_NIL(v)
#define FREE_OUT_P128(v) FREE_OUT(v, p128)
#define FREE_OUT_X128(v) FREE_OUT(v, x128)
#define FREE_OUT_CARRY(v) FREE_OUT(v, carry)

#define DEFTESTFN(fn, tya, tyc, tyu, tyx, tyv, tyy, tyzz, tyyy, tycc)	\
									\
  static int v##fn(dstr dv[])						\
  {									\
    dstr *dp = dv;							\
    DECL_IN_##tya(a)							\
    DECL_IN_##tyc(c)							\
    DECL_IN_##tyu(u)							\
    DECL_IN_##tyx(x)							\
    DECL_IN_##tyv(v)							\
    DECL_IN_##tyy(y)							\
    DECL_IN_##tyzz(zz_exp)						\
    DECL_IN_##tyyy(yy_exp)						\
    DECL_IN_##tycc(cc_exp)						\
    DECL_OUT_##tyzz(zz_out)						\
    DECL_OUT_##tyyy(yy_out)						\
    DECL_OUT_##tycc(cc_out)						\
    unsigned long long cyv[1];						\
    int ok = 1;								\
									\
    INIT_OUT_##tyzz(zz_out)						\
    INIT_OUT_##tyyy(yy_out)						\
    INIT_OUT_##tycc(cc_out)						\
									\
    COPY_##tya(zz_out, a);						\
    COPY_##tyc(cc_out, c);						\
    test_##fn(zz_out ARG_##tycc(cc_out) ARG_##tyyy(yy_out)		\
	      ARG_##tyu(u) ARG_##tyx(x) ARG_##tyv(v) ARG_##tyy(y),	\
	      1, cyv);							\
    CHECK_##tyzz(zz_exp, zz_out)					\
    CHECK_##tyyy(yy_exp, yy_out)					\
    CHECK_##tycc(cc_exp, cc_out)					\
									\
    if (!ok) {								\
      fputs(#fn " failed", stderr);					\
      DUMP_##tya(a)							\
      DUMP_##tyc(c)							\
      DUMP_##tyu(u)							\
      DUMP_##tyx(x)							\
      DUMP_##tyv(v)							\
      DUMP_##tyy(y)							\
      DUMP_##tyzz(zz_exp)						\
      DUMP_##tyzz(zz_out)						\
      DUMP_##tyyy(yy_exp)						\
      DUMP_##tyyy(yy_out)						\
      DUMP_##tycc(cc_exp)						\
      DUMP_##tycc(cc_out)						\
      fputc('\n', stderr);						\
    }									\
									\
    FREE_OUT_##tyzz(zz_out);						\
    FREE_OUT_##tyyy(yy_out);						\
    FREE_OUT_##tycc(cc_out);						\
									\
    return (ok);							\
  }

TESTOPS(DEFTESTFN)

/*----- Main code ---------------------------------------------------------*/

#define NIL
#define P128 &type_p128,
#define X128 &type_x128,
#define CARRY &type_carry,

static test_chunk tests[] = {
#define DEFCHUNK(fn, tya, tyc, tyu, tyx, tyv, tyy, tyzz, tyyy, tycc)	\
  { #fn, v##fn, { tya tyc tyu tyx tyv tyy tyzz tyyy tycc } },
  TESTOPS(DEFCHUNK)
#undef DEFCHUNK
  { 0, 0, { 0 } }
};

int main(int argc, char *argv[])
{
  sub_init();
  if (!cpu_features_p())
    { fprintf(stderr, "required cpu feature not available\n"); exit(77); }
  test_run(argc, argv, tests, SRCDIR "/t/mpx-mul4");
  return (0);
}

/*----- That's all, folks -------------------------------------------------*/
Commit	Line	Data
7ba379a6 MW	1	/* --c--
	2	*
	3	* Testing optimized 128-bit multipliers
	4	*
	5	* (c) 2017 Straylight/Edgeware
	6	*/
	7
	8	/----- Licensing notice --------------------------------------------------
	9	*
	10	* This file is part of Catacomb.
	11	*
	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.
	16	*
	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.
	21	*
	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,
	25	* MA 02111-1307, USA.
	26	*/
	27
	28	/----- Header files ------------------------------------------------------/
	29
	30	#include "config.h"
	31
	32	#include <assert.h>
	33	#include <stdio.h>
	34	#include <stdlib.h>
	35	#include <string.h>
	36
	37	#include <mLib/macros.h>
	38	#include <mLib/report.h>
	39	#include <mLib/testrig.h>
	40
	41	#include "dispatch.h"
	42	#include "mp.h"
	43	#include "mpmont.h"
	44	#include "mptext.h"
	45
	46	/----- CPU feature detection ---------------------------------------------/
	47
	48	#if CPUFAM_X86
	49	# define VARIANT _x86_sse2
	50	# define REPR_32
	51	static int cpu_features_p(void) { return (cpu_feature_p(CPUFEAT_X86_SSE2)); }
	52	#endif
	53
	54	#if CPUFAM_AMD64
	55	# define VARIANT _amd64_sse2
	56	# define REPR_32
	57	static int cpu_features_p(void) { return (cpu_feature_p(CPUFEAT_X86_SSE2)); }
	58	#endif
	59
	60	#ifndef VARIANT
	61	# error "Unsupported CPU family."
	62	#endif
	63
	64	#ifdef REPR_32
65	# define NWBY 4
66	# define NDBY 8
67	# define LDW LOAD32
68	# define LDD LOAD64
69	# define STW STORE32
70	# define STD STORE64
71	typedef struct { mpw w[4]; } p128;
72	typedef struct { mpw w[8]; } x128;
73	typedef struct { mpd w[6]; } carry;
74	#endif
75
76	/----- Test operation table ----------------------------------------------/
77
78	#define TESTOPS(_) \
79	/* a c u x v y z' y' c' */ \
80	_(dmul4, NIL, CARRY, P128, P128, P128, P128, P128, NIL, CARRY) \
81	_(dmla4, P128, CARRY, P128, P128, P128, P128, P128, NIL, CARRY) \
82	_(mul4, NIL, CARRY, NIL, P128, NIL, P128, P128, NIL, CARRY) \
83	_(mla4, P128, CARRY, NIL, P128, NIL, P128, P128, NIL, CARRY) \
84	_(mmul4, NIL, NIL, P128, P128, P128, P128, P128, X128, CARRY) \
85	_(mmla4, P128, NIL, P128, P128, P128, P128, P128, X128, CARRY) \
86	_(mont4, P128, NIL, NIL, P128, NIL, P128, P128, X128, CARRY)
87
88	/----- Assembler test interface ------------------------------------------/
89
90	#define EMPTY
91
92	#define PARAM(v, ty) ty *v,
93	#define PARAM_NIL(v, q)
94	#define PARAM_P128(v, q) PARAM(v, q p128)
95	#define PARAM_X128(v, q) PARAM(v, q x128)
96	#define PARAM_CARRY(v, q) PARAM(v, q carry)
97
98	#define DECLSTUB(fn, tya, tyc, tyu, tyx, tyv, tyy, tyzz, tyyy, tycc) \
99	extern void test_##fn(PARAM_##tyzz(zz, EMPTY) PARAM_##tycc(cc, EMPTY) \
100	PARAM_##tyyy(yy, EMPTY) \
101	PARAM_##tyu(u, const) PARAM_##tyx(x, const) \
102	PARAM_##tyv(v, const) PARAM_##tyy(y, const) \
103	unsigned n, unsigned long long *cyv);
104	TESTOPS(DECLSTUB)
105
106	/----- Conversion functions ----------------------------------------------/
107
108	#define DEFTYPE(ty, ld, st, nby) \
109	\
110	static void cvt_##ty(const char buf, dstr d) \
111	{ \
112	dstr dd = DSTR_INIT; \
113	int i; \
114	ty *x; \
115	const octet *p; \
116	\
117	type_hex.cvt(buf, &dd); \
118	if (dd.len != N(x->w)*nby) die(1, "invalid length for " #ty); \
b00264d9	119	dstr_ensure(d, sizeof(x)); d->len = sizeof(x); \
7ba379a6 MW	120	x = (ty )d->buf; p = (const octet )dd.buf; \
	121	for (i = 0; i < N(x->w); i++) { x->w[i] = ld(p); p += nby; } \
	122	dstr_destroy(&dd); \
	123	} \
	124	\
	125	static void dump_##ty(dstr d, FILE fp) \
	126	{ \
	127	dstr dd = DSTR_INIT; \
	128	int i; \
	129	const ty x = (const ty )d->buf; \
	130	octet *p; \
	131	\
	132	dstr_ensure(&dd, N(x->w)nby); p = (octet )dd.buf; \
	133	for (i = 0; i < N(x->w); i++) { st(p, x->w[i]); p += nby; } \
	134	dd.len = N(x->w)*nby; \
	135	type_hex.dump(&dd, fp); \
	136	dstr_destroy(&dd); \
	137	} \
	138	\
	139	static int eq_##ty(const ty x, const ty y) \
	140	{ \
	141	int i; \
	142	\
	143	for (i = 0; i < N(x->w); i++) \
	144	if (x->w[i] != y->w[i]) return (0); \
	145	return (1); \
	146	} \
	147	\
	148	static const struct test_type type_##ty = { cvt_##ty, dump_##ty };
	149
	150	DEFTYPE(p128, LDW, STW, NWBY)
	151	DEFTYPE(x128, LDW, STW, NWBY)
	152	DEFTYPE(carry, LDD, STD, NDBY)
	153
	154	/----- Test functions ----------------------------------------------------/
	155
	156	#define DECL_IN(v, ty) \
	157	dstr d_##v = dp++; const ty v = (const ty *)d_##v->buf;
	158	#define DECL_IN_NIL(v)
	159	#define DECL_IN_P128(v) DECL_IN(v, p128)
	160	#define DECL_IN_X128(v) DECL_IN(v, x128)
	161	#define DECL_IN_CARRY(v) DECL_IN(v, carry)
	162
	163	#define DECL_OUT(v, ty) \
	164	dstr dd_##v = DSTR_INIT, d_##v = &dd_##v; ty v;
	165	#define DECL_OUT_NIL(v)
	166	#define DECL_OUT_P128(v) DECL_OUT(v, p128)
	167	#define DECL_OUT_X128(v) DECL_OUT(v, x128)
	168	#define DECL_OUT_CARRY(v) DECL_OUT(v, carry)
	169
	170	#define INIT_OUT(v, ty) \
	171	dstr_ensure(d_##v, sizeof(ty)); v = (ty *)d_##v->buf;
	172	#define INIT_OUT_NIL(v)
	173	#define INIT_OUT_P128(v) INIT_OUT(v, p128)
	174	#define INIT_OUT_X128(v) INIT_OUT(v, x128)
	175	#define INIT_OUT_CARRY(v) INIT_OUT(v, carry)
	176
	177	#define ARG(v) , v
	178	#define ARG_NIL(v)
	179	#define ARG_P128(v) ARG(v)
	180	#define ARG_X128(v) ARG(v)
	181	#define ARG_CARRY(v) ARG(v)
	182
	183	#define CHECK(v, vv, ty) if (!eq_##ty(v, vv)) ok = 0;
184	#define CHECK_NIL(v, vv)
185	#define CHECK_P128(v, vv) CHECK(v, vv, p128)
186	#define CHECK_X128(v, vv) CHECK(v, vv, x128)
187	#define CHECK_CARRY(v, vv) CHECK(v, vv, carry)
188
189	#define DUMP(v, ty) \
190	fprintf(stderr, "\n\t%-6s = ", #v); dump_##ty(d_##v, stderr);
191	#define DUMP_NIL(v)
192	#define DUMP_P128(v) DUMP(v, p128)
193	#define DUMP_X128(v) DUMP(v, x128)
194	#define DUMP_CARRY(v) DUMP(v, carry)
195
196	#define COPY(v, vv, ty) v = vv;
197	#define COPY_NIL(v, vv)
198	#define COPY_P128(v, vv) COPY(v, vv, p128)
199	#define COPY_X128(v, vv) COPY(v, vv, x128)
200	#define COPY_CARRY(v, vv) COPY(v, vv, carry)
201
202	#define FREE_OUT(v, ty) dstr_destroy(d_##v);
203	#define FREE_OUT_NIL(v)
204	#define FREE_OUT_P128(v) FREE_OUT(v, p128)
205	#define FREE_OUT_X128(v) FREE_OUT(v, x128)
206	#define FREE_OUT_CARRY(v) FREE_OUT(v, carry)
207
208	#define DEFTESTFN(fn, tya, tyc, tyu, tyx, tyv, tyy, tyzz, tyyy, tycc) \
209	\
210	static int v##fn(dstr dv[]) \
211	{ \
212	dstr *dp = dv; \
213	DECL_IN_##tya(a) \
214	DECL_IN_##tyc(c) \
215	DECL_IN_##tyu(u) \
216	DECL_IN_##tyx(x) \
217	DECL_IN_##tyv(v) \
218	DECL_IN_##tyy(y) \
219	DECL_IN_##tyzz(zz_exp) \
220	DECL_IN_##tyyy(yy_exp) \
221	DECL_IN_##tycc(cc_exp) \
222	DECL_OUT_##tyzz(zz_out) \
223	DECL_OUT_##tyyy(yy_out) \
224	DECL_OUT_##tycc(cc_out) \
225	unsigned long long cyv[1]; \
226	int ok = 1; \
227	\
228	INIT_OUT_##tyzz(zz_out) \
229	INIT_OUT_##tyyy(yy_out) \
230	INIT_OUT_##tycc(cc_out) \
231	\
232	COPY_##tya(zz_out, a); \
233	COPY_##tyc(cc_out, c); \
234	test_##fn(zz_out ARG_##tycc(cc_out) ARG_##tyyy(yy_out) \
235	ARG_##tyu(u) ARG_##tyx(x) ARG_##tyv(v) ARG_##tyy(y), \
236	1, cyv); \
237	CHECK_##tyzz(zz_exp, zz_out) \
238	CHECK_##tyyy(yy_exp, yy_out) \
239	CHECK_##tycc(cc_exp, cc_out) \
240	\
241	if (!ok) { \
242	fputs(#fn " failed", stderr); \
243	DUMP_##tya(a) \
244	DUMP_##tyc(c) \
245	DUMP_##tyu(u) \
246	DUMP_##tyx(x) \
247	DUMP_##tyv(v) \
248	DUMP_##tyy(y) \
249	DUMP_##tyzz(zz_exp) \
250	DUMP_##tyzz(zz_out) \
251	DUMP_##tyyy(yy_exp) \
252	DUMP_##tyyy(yy_out) \
253	DUMP_##tycc(cc_exp) \
254	DUMP_##tycc(cc_out) \
255	fputc('\n', stderr); \
256	} \
257	\
258	FREE_OUT_##tyzz(zz_out); \
259	FREE_OUT_##tyyy(yy_out); \
260	FREE_OUT_##tycc(cc_out); \
261	\
262	return (ok); \
263	}
264
265	TESTOPS(DEFTESTFN)
266
267	/----- Main code ---------------------------------------------------------/
268
269	#define NIL
270	#define P128 &type_p128,
271	#define X128 &type_x128,
272	#define CARRY &type_carry,
273
274	static test_chunk tests[] = {
275	#define DEFCHUNK(fn, tya, tyc, tyu, tyx, tyv, tyy, tyzz, tyyy, tycc) \
276	{ #fn, v##fn, { tya tyc tyu tyx tyv tyy tyzz tyyy tycc } },
277	TESTOPS(DEFCHUNK)
278	#undef DEFCHUNK
279	{ 0, 0, { 0 } }
280	};
281
282	int main(int argc, char *argv[])
283	{
284	sub_init();
285	if (!cpu_features_p())
286	{ fprintf(stderr, "required cpu feature not available\n"); exit(77); }
1e8abdf5	287	test_run(argc, argv, tests, SRCDIR "/t/mpx-mul4");
7ba379a6 MW	288	return (0);
	289	}
	290
	291	/----- That's all, folks -------------------------------------------------/