Line data Source code
1 : /**
2 : * @file cfdnn_format.c
3 : * @brief Reader and writer for the portable `.cfdnn` weight format.
4 : *
5 : * Modelled directly on lib/src/io/checkpoint.c, which already solved this
6 : * problem for `.cfdchk`: a latching I/O helper, explicit little-endian
7 : * fixed-width encoding (never a raw struct fwrite), an endianness marker, a
8 : * table-less CRC32, and a format version that REJECTS unknown values rather
9 : * than guessing.
10 : *
11 : * The one deliberate deviation is that reads can come from a memory image as
12 : * well as a file, so cfd_nn_model_load() and cfd_nn_model_load_memory() share
13 : * every line of parsing code. That is what lets the test suite embed a golden
14 : * model as a C array instead of shipping a data file under tests/.
15 : *
16 : * There is no JSON sidecar. Everything metadata would carry lives in the same
17 : * byte stream under the same CRC -- a second file could disagree with the
18 : * first, and the checksum would not catch it. It would also require the
19 : * project's first third-party parser, or a hand-rolled one hardened against
20 : * hostile input, for no benefit.
21 : */
22 :
23 : #include "cfdnn_internal.h"
24 :
25 : #include "cfd/core/cfd_status.h"
26 : #include "cfd/core/cfd_version.h"
27 : #include "cfd/core/memory.h"
28 :
29 : #include <stdio.h>
30 : #include <string.h>
31 :
32 : _Static_assert(sizeof(float) == 4, "cfdnn requires IEEE-754 binary32 float");
33 :
34 : /* ==========================================================================
35 : * Format constants
36 : * ========================================================================== */
37 :
38 : static const uint8_t NN_MAGIC[8] = {'C', 'F', 'D', 'N', 'N', 0, 0, 0};
39 :
40 : #define NN_ENDIAN_MARKER 0x01020304u /* decoded LE; foreign-endian files differ */
41 : #define NN_FLAG_CHECKSUM 0x0001u /* flags bit0: trailing CRC32 present */
42 : #define NN_FLAG_KNOWN NN_FLAG_CHECKSUM /* every other bit is unassigned */
43 : #define NN_DTYPE_F32 1u
44 : #define NN_DTYPE_F64 2u /* reserved; rejected by this reader */
45 : #define NN_LAYOUT_ROW_MAJOR 0u /* the only layout the kernels index */
46 :
47 : /* ==========================================================================
48 : * CRC32 (IEEE 802.3, reflected, poly 0xEDB88320) -- table-less and stateless
49 : * so it is thread-safe with no static initialization. Lifted from
50 : * checkpoint.c; the ten lines are duplicated deliberately to keep io/ and nn/
51 : * independent of each other.
52 : * ========================================================================== */
53 :
54 5969 : static uint32_t nn_crc32_update(uint32_t crc, const void* data, size_t n) {
55 5969 : const uint8_t* p = (const uint8_t*)data;
56 28192 : for (size_t i = 0; i < n; i++) {
57 22223 : crc ^= p[i];
58 200007 : for (int k = 0; k < 8; k++) {
59 177784 : crc = (crc >> 1) ^ (0xEDB88320u & (0u - (crc & 1u)));
60 : }
61 : }
62 5969 : return crc;
63 : }
64 :
65 : /* ==========================================================================
66 : * Latching little-endian I/O helper (file or memory)
67 : * ========================================================================== */
68 :
69 : typedef struct {
70 : FILE* fp; /* NULL when reading from memory */
71 : const uint8_t* mem; /* memory image, or NULL */
72 : size_t mem_size;
73 : size_t mem_pos;
74 : cfd_status_t status; /* first error latches; later ops become no-ops */
75 : uint32_t crc;
76 : } nn_io;
77 :
78 1355 : static void nn_write_bytes(nn_io* io, const void* p, size_t n) {
79 1355 : if (io->status != CFD_SUCCESS) {
80 : return;
81 : }
82 1355 : if (n && fwrite(p, 1, n, io->fp) != n) {
83 0 : io->status = CFD_ERROR_IO;
84 0 : return;
85 : }
86 2710 : io->crc = nn_crc32_update(io->crc, p, n);
87 : }
88 :
89 5135 : static void nn_read_bytes(nn_io* io, void* p, size_t n) {
90 5135 : if (io->status != CFD_SUCCESS) {
91 : return;
92 : }
93 4730 : if (n == 0) {
94 : return;
95 : }
96 4730 : if (io->mem) {
97 3991 : if (io->mem_pos + n > io->mem_size) {
98 116 : io->status = CFD_ERROR_IO; /* truncated image */
99 116 : return;
100 : }
101 3875 : memcpy(p, io->mem + io->mem_pos, n);
102 3875 : io->mem_pos += n;
103 1478 : } else if (fread(p, 1, n, io->fp) != n) {
104 0 : io->status = CFD_ERROR_IO; /* truncated file */
105 0 : return;
106 : }
107 9228 : io->crc = nn_crc32_update(io->crc, p, n);
108 : }
109 :
110 : /* --- fixed-width writers (explicit little-endian) --- */
111 :
112 66 : static void put_u8(nn_io* io, uint8_t v) {
113 66 : nn_write_bytes(io, &v, 1);
114 : }
115 :
116 237 : static void put_u16(nn_io* io, uint16_t v) {
117 237 : uint8_t b[2] = {(uint8_t)(v & 0xFFu), (uint8_t)((v >> 8) & 0xFFu)};
118 237 : nn_write_bytes(io, b, sizeof(b));
119 : }
120 :
121 986 : static void put_u32(nn_io* io, uint32_t v) {
122 986 : uint8_t b[4];
123 4930 : for (int i = 0; i < 4; i++) {
124 3944 : b[i] = (uint8_t)((v >> (8 * i)) & 0xFFu);
125 : }
126 986 : nn_write_bytes(io, b, sizeof(b));
127 986 : }
128 :
129 611 : static void put_f32(nn_io* io, float v) {
130 611 : uint32_t bits;
131 611 : memcpy(&bits, &v, sizeof(bits)); /* IEEE-754 bit pattern, alias-safe */
132 611 : put_u32(io, bits);
133 : }
134 :
135 33 : static void put_string(nn_io* io, const char* s) {
136 33 : size_t n = s ? strlen(s) : 0;
137 33 : if (n > CFD_NN_MAX_STRING) {
138 : /* Refused, not truncated: the reader rejects this length, so a clamp
139 : * here would report success and hand back a different name on load. */
140 0 : io->status = CFD_ERROR_INVALID;
141 0 : return;
142 : }
143 33 : put_u32(io, (uint32_t)n);
144 33 : nn_write_bytes(io, s, n);
145 : }
146 :
147 : /* --- fixed-width readers --- */
148 :
149 308 : static uint8_t get_u8(nn_io* io) {
150 308 : uint8_t v = 0;
151 308 : nn_read_bytes(io, &v, 1);
152 308 : return v;
153 : }
154 :
155 974 : static uint16_t get_u16(nn_io* io) {
156 974 : uint8_t b[2] = {0};
157 974 : nn_read_bytes(io, b, sizeof(b));
158 974 : return (uint16_t)((uint16_t)b[0] | ((uint16_t)b[1] << 8));
159 : }
160 :
161 3599 : static uint32_t get_u32(nn_io* io) {
162 3599 : uint8_t b[4] = {0};
163 3599 : nn_read_bytes(io, b, sizeof(b));
164 3599 : uint32_t v = 0;
165 17995 : for (int i = 0; i < 4; i++) {
166 14396 : v |= ((uint32_t)b[i]) << (8 * i);
167 : }
168 3599 : return v;
169 : }
170 :
171 2306 : static float get_f32(nn_io* io) {
172 4612 : uint32_t bits = get_u32(io);
173 2306 : float v;
174 2306 : memcpy(&v, &bits, sizeof(v));
175 2306 : return v;
176 : }
177 :
178 : /* Raw 32-bit read that does NOT fold into the running CRC -- used for the
179 : * trailing checksum itself, which cannot cover its own bytes. */
180 31 : static uint32_t get_u32_raw(nn_io* io) {
181 31 : uint32_t saved = io->crc;
182 62 : uint32_t v = get_u32(io);
183 31 : io->crc = saved;
184 31 : return v;
185 : }
186 :
187 33 : static void put_u32_raw(nn_io* io, uint32_t v) {
188 33 : uint32_t saved = io->crc;
189 33 : put_u32(io, v);
190 33 : io->crc = saved;
191 : }
192 :
193 : /* ==========================================================================
194 : * Writer
195 : * ========================================================================== */
196 :
197 : /** Shape validation shared by writer and reader, so an invalid model cannot be
198 : * produced in the first place. */
199 35 : static cfd_status_t validate_layers(const cfd_nn_layer_desc_t* layers, size_t n) {
200 35 : if (!layers || n == 0 || n > CFD_NN_MAX_LAYERS) {
201 : return CFD_ERROR_INVALID;
202 : }
203 72 : for (size_t i = 0; i < n; i++) {
204 39 : const cfd_nn_layer_desc_t* l = &layers[i];
205 39 : if (l->kind != CFD_NN_LAYER_DENSE) {
206 : return CFD_ERROR_INVALID;
207 : }
208 39 : if (l->activation < CFD_NN_ACT_IDENTITY || l->activation > CFD_NN_ACT_SOFTPLUS) {
209 : return CFD_ERROR_INVALID;
210 : }
211 39 : if (l->in_features == 0 || l->out_features == 0 ||
212 38 : l->in_features > CFD_NN_MAX_FEATURES || l->out_features > CFD_NN_MAX_FEATURES) {
213 : return CFD_ERROR_INVALID;
214 : }
215 38 : uint64_t wc = (uint64_t)l->in_features * (uint64_t)l->out_features;
216 38 : if (wc > CFD_NN_MAX_WEIGHTS || !l->weights) {
217 : return CFD_ERROR_INVALID;
218 : }
219 : /* Layer i's input width must equal layer i-1's output width. */
220 38 : if (i > 0 && l->in_features != layers[i - 1].out_features) {
221 : return CFD_ERROR_INVALID;
222 : }
223 : }
224 : return CFD_SUCCESS;
225 : }
226 :
227 36 : cfd_status_t cfd_nn_model_write(const char* path, const cfd_nn_model_desc_t* desc) {
228 : /* Checked before the file is created, so an overlong name leaves no
229 : * half-written model behind. */
230 36 : if (!path || !desc || (desc->name && strlen(desc->name) > CFD_NN_MAX_STRING)) {
231 : return CFD_ERROR_INVALID;
232 : }
233 35 : cfd_status_t vs = validate_layers(desc->layers, desc->layer_count);
234 35 : if (vs != CFD_SUCCESS) {
235 : return vs;
236 : }
237 :
238 33 : FILE* fp = fopen(path, "wb");
239 33 : if (!fp) {
240 : return CFD_ERROR_IO;
241 : }
242 33 : nn_io io = {fp, NULL, 0, 0, CFD_SUCCESS, 0xFFFFFFFFu};
243 :
244 33 : nn_write_bytes(&io, NN_MAGIC, sizeof(NN_MAGIC));
245 33 : put_u32(&io, CFD_NN_FORMAT_VERSION);
246 33 : put_u32(&io, NN_ENDIAN_MARKER);
247 33 : put_u16(&io, (uint16_t)CFD_VERSION_MAJOR);
248 33 : put_u16(&io, (uint16_t)CFD_VERSION_MINOR);
249 33 : put_u16(&io, (uint16_t)CFD_VERSION_PATCH);
250 33 : put_u16(&io, NN_FLAG_CHECKSUM);
251 33 : put_u8(&io, (uint8_t)NN_DTYPE_F32);
252 33 : put_u8(&io, 0);
253 33 : put_u16(&io, 0);
254 33 : put_u32(&io, (uint32_t)desc->layer_count);
255 33 : put_u32(&io, 0);
256 33 : put_u32(&io, 0);
257 33 : put_string(&io, desc->name);
258 :
259 69 : for (size_t i = 0; i < desc->layer_count; i++) {
260 36 : const cfd_nn_layer_desc_t* l = &desc->layers[i];
261 36 : size_t wc = l->in_features * l->out_features;
262 36 : put_u16(&io, (uint16_t)l->kind);
263 36 : put_u16(&io, (uint16_t)l->activation);
264 36 : put_f32(&io, l->act_param);
265 36 : put_u32(&io, (uint32_t)l->in_features);
266 36 : put_u32(&io, (uint32_t)l->out_features);
267 36 : put_u32(&io, (uint32_t)wc);
268 508 : for (size_t k = 0; k < wc; k++) {
269 472 : put_f32(&io, l->weights[k]);
270 : }
271 36 : put_u32(&io, l->bias ? (uint32_t)l->out_features : 0u);
272 36 : if (l->bias) {
273 138 : for (size_t k = 0; k < l->out_features; k++) {
274 103 : put_f32(&io, l->bias[k]);
275 : }
276 : }
277 : }
278 :
279 33 : put_u32_raw(&io, io.crc ^ 0xFFFFFFFFu);
280 :
281 33 : cfd_status_t st = io.status;
282 33 : if (fclose(fp) != 0 && st == CFD_SUCCESS) {
283 0 : st = CFD_ERROR_IO;
284 : }
285 : return st;
286 : }
287 :
288 : /* ==========================================================================
289 : * Reader
290 : * ========================================================================== */
291 :
292 105 : static void model_free(cfd_nn_model_t* m) {
293 105 : if (!m) {
294 : return;
295 : }
296 104 : cfd_free(m->name);
297 104 : cfd_free(m->blob);
298 104 : cfd_free(m->layers);
299 104 : cfd_free(m);
300 : }
301 :
302 155 : cfd_status_t cfd_nn_load_impl(const char* path, const void* bytes, size_t size,
303 : cfd_nn_model_t** out_model) {
304 155 : if (!out_model) {
305 : return CFD_ERROR_INVALID;
306 : }
307 155 : *out_model = NULL;
308 :
309 155 : FILE* fp = NULL;
310 155 : if (path) {
311 33 : fp = fopen(path, "rb");
312 33 : if (!fp) {
313 : return CFD_ERROR_IO;
314 : }
315 122 : } else if (!bytes) {
316 : return CFD_ERROR_INVALID;
317 : }
318 :
319 154 : nn_io io = {fp, (const uint8_t*)bytes, size, 0, CFD_SUCCESS, 0xFFFFFFFFu};
320 :
321 154 : uint8_t magic[8] = {0};
322 154 : nn_read_bytes(&io, magic, sizeof(magic));
323 154 : if (io.status == CFD_SUCCESS && memcmp(magic, NN_MAGIC, sizeof(magic)) != 0) {
324 1 : io.status = CFD_ERROR_INVALID;
325 : }
326 :
327 154 : uint32_t version = get_u32(&io);
328 154 : uint32_t endian = get_u32(&io);
329 154 : (void)get_u16(&io); /* lib major */
330 154 : (void)get_u16(&io); /* lib minor */
331 154 : (void)get_u16(&io); /* lib patch */
332 154 : uint16_t flags = get_u16(&io);
333 154 : uint8_t dtype = get_u8(&io);
334 154 : uint8_t layout = get_u8(&io);
335 154 : uint32_t rsv = get_u16(&io);
336 154 : uint32_t layer_count = get_u32(&io);
337 154 : rsv |= get_u32(&io);
338 154 : rsv |= get_u32(&io);
339 :
340 154 : if (io.status == CFD_SUCCESS) {
341 : /* Reject unknown, never guess -- the checkpoint.c rule, applied to
342 : * version, byte order, precision, flag bits, tensor layout and the
343 : * reserved words alike. */
344 114 : if (version != CFD_NN_FORMAT_VERSION || endian != NN_ENDIAN_MARKER ||
345 110 : dtype != NN_DTYPE_F32 || (flags & (uint16_t)~NN_FLAG_KNOWN) != 0 ||
346 109 : layout != NN_LAYOUT_ROW_MAJOR || rsv != 0) {
347 : /* Unassigned flag bits, a foreign tensor layout and a nonzero
348 : * reserved word each mean the file carries something this build
349 : * does not implement; accepting it would index the weights as
350 : * row-major anyway and predict silently wrong numbers. */
351 9 : io.status = CFD_ERROR_UNSUPPORTED;
352 105 : } else if (layer_count == 0 || layer_count > CFD_NN_MAX_LAYERS) {
353 1 : io.status = CFD_ERROR_INVALID; /* cap checked before any allocation */
354 : }
355 : }
356 154 : if (io.status != CFD_SUCCESS) {
357 50 : if (fp) {
358 11 : fclose(fp);
359 : }
360 50 : return io.status;
361 : }
362 :
363 104 : cfd_nn_model_t* m = (cfd_nn_model_t*)cfd_calloc(1, sizeof(*m));
364 104 : if (!m) {
365 0 : if (fp) {
366 0 : fclose(fp);
367 : }
368 0 : return CFD_ERROR_NOMEM;
369 : }
370 104 : m->layer_count = layer_count;
371 104 : m->layers = (cfd_nn_layer_t*)cfd_calloc(layer_count, sizeof(cfd_nn_layer_t));
372 104 : if (!m->layers) {
373 0 : model_free(m);
374 0 : if (fp) {
375 0 : fclose(fp);
376 : }
377 0 : return CFD_ERROR_NOMEM;
378 : }
379 :
380 : /* Model name. */
381 104 : uint32_t name_len = get_u32(&io);
382 104 : if (io.status == CFD_SUCCESS && name_len > CFD_NN_MAX_STRING) {
383 0 : io.status = CFD_ERROR_INVALID;
384 : }
385 104 : if (io.status == CFD_SUCCESS) {
386 100 : m->name = (char*)cfd_calloc(name_len + 1, 1);
387 100 : if (!m->name) {
388 0 : io.status = CFD_ERROR_NOMEM;
389 : } else {
390 100 : nn_read_bytes(&io, m->name, name_len);
391 : }
392 : }
393 :
394 : /* Two passes would need a seek, which the memory path would have to
395 : * emulate; instead layers are read straight into a growing blob whose
396 : * final size is known only at the end, so each layer's slice is recorded
397 : * as an offset and resolved to a pointer afterwards. */
398 104 : size_t* offsets = NULL;
399 104 : size_t* bias_offs = NULL;
400 104 : size_t blob_used = 0;
401 104 : size_t blob_cap = 0;
402 104 : float* blob = NULL;
403 :
404 104 : if (io.status == CFD_SUCCESS) {
405 91 : offsets = (size_t*)cfd_calloc(layer_count, sizeof(size_t));
406 91 : bias_offs = (size_t*)cfd_calloc(layer_count, sizeof(size_t));
407 91 : if (!offsets || !bias_offs) {
408 0 : io.status = CFD_ERROR_NOMEM;
409 : }
410 : }
411 :
412 158 : for (uint32_t i = 0; i < layer_count && io.status == CFD_SUCCESS; i++) {
413 102 : uint16_t kind = get_u16(&io);
414 102 : uint16_t act = get_u16(&io);
415 102 : float prm = get_f32(&io);
416 102 : uint32_t nin = get_u32(&io);
417 102 : uint32_t nout = get_u32(&io);
418 102 : uint32_t wc = get_u32(&io);
419 :
420 102 : if (io.status != CFD_SUCCESS) {
421 : break;
422 : }
423 82 : if (kind != (uint16_t)CFD_NN_LAYER_DENSE || act > (uint16_t)CFD_NN_ACT_SOFTPLUS) {
424 0 : io.status = CFD_ERROR_INVALID;
425 0 : break;
426 : }
427 82 : if (nin == 0 || nout == 0 || nin > CFD_NN_MAX_FEATURES || nout > CFD_NN_MAX_FEATURES) {
428 0 : io.status = CFD_ERROR_INVALID;
429 0 : break;
430 : }
431 82 : if ((uint64_t)wc != (uint64_t)nin * (uint64_t)nout || wc > CFD_NN_MAX_WEIGHTS) {
432 0 : io.status = CFD_ERROR_INVALID;
433 0 : break;
434 : }
435 82 : if (i > 0 && nin != (uint32_t)m->layers[i - 1].out_features) {
436 0 : io.status = CFD_ERROR_INVALID; /* shape mismatch between layers */
437 0 : break;
438 : }
439 :
440 : /* Grow the blob to hold weights (+ bias, read just below). */
441 82 : size_t need = blob_used + wc + nout;
442 82 : if (need > blob_cap) {
443 71 : size_t ncap = blob_cap ? blob_cap * 2 : 1024;
444 71 : while (ncap < need) {
445 0 : ncap *= 2;
446 : }
447 71 : float* nb = (float*)cfd_malloc(ncap * sizeof(float));
448 71 : if (!nb) {
449 0 : io.status = CFD_ERROR_NOMEM;
450 0 : break;
451 : }
452 71 : if (blob) {
453 0 : memcpy(nb, blob, blob_used * sizeof(float));
454 0 : cfd_free(blob);
455 : }
456 : blob = nb;
457 : blob_cap = ncap;
458 : }
459 :
460 82 : offsets[i] = blob_used;
461 2035 : for (uint32_t k = 0; k < wc; k++) {
462 1953 : blob[blob_used + k] = get_f32(&io);
463 : }
464 82 : blob_used += wc;
465 :
466 82 : uint32_t bc = get_u32(&io);
467 82 : if (io.status != CFD_SUCCESS) {
468 : break;
469 : }
470 54 : if (bc != 0 && bc != nout) {
471 0 : io.status = CFD_ERROR_INVALID;
472 0 : break;
473 : }
474 54 : if (bc) {
475 53 : bias_offs[i] = blob_used + 1; /* +1 so 0 means "no bias" */
476 304 : for (uint32_t k = 0; k < bc; k++) {
477 251 : blob[blob_used + k] = get_f32(&io);
478 : }
479 53 : blob_used += bc;
480 : }
481 :
482 54 : m->layers[i].activation = (cfd_nn_activation_t)act;
483 54 : m->layers[i].act_param = prm;
484 54 : m->layers[i].in_features = nin;
485 54 : m->layers[i].out_features = nout;
486 54 : if (nin > m->widest) {
487 43 : m->widest = nin;
488 : }
489 54 : if (nout > m->widest) {
490 29 : m->widest = nout;
491 : }
492 : }
493 :
494 : /* Trailing CRC. */
495 104 : if (io.status == CFD_SUCCESS && (flags & NN_FLAG_CHECKSUM)) {
496 31 : uint32_t expect = io.crc ^ 0xFFFFFFFFu;
497 31 : uint32_t stored = get_u32_raw(&io);
498 31 : if (io.status == CFD_SUCCESS && stored != expect) {
499 1 : io.status = CFD_ERROR_IO; /* truncation or bit-rot */
500 : }
501 : }
502 :
503 104 : if (io.status == CFD_SUCCESS) {
504 63 : for (uint32_t i = 0; i < layer_count; i++) {
505 37 : m->layers[i].weights = blob + offsets[i];
506 37 : m->layers[i].bias = bias_offs[i] ? blob + (bias_offs[i] - 1) : NULL;
507 : }
508 26 : m->blob = blob;
509 26 : m->inputs = m->layers[0].in_features;
510 26 : m->outputs = m->layers[layer_count - 1].out_features;
511 : }
512 :
513 104 : cfd_free(offsets);
514 104 : cfd_free(bias_offs);
515 104 : if (fp) {
516 21 : fclose(fp);
517 : }
518 :
519 104 : if (io.status != CFD_SUCCESS) {
520 78 : cfd_free(blob);
521 78 : m->blob = NULL;
522 78 : model_free(m);
523 78 : return io.status;
524 : }
525 :
526 26 : *out_model = m;
527 26 : return CFD_SUCCESS;
528 : }
529 :
530 27 : void cfd_nn_model_destroy(cfd_nn_model_t* model) {
531 27 : model_free(model);
532 27 : }
|