formats/ctf/ctf.c

   1 /*
   2  * BabelTrace - Common Trace Format (CTF)
   3  *
   4  * Format registration.
   5  *
   6  * Copyright 2010, 2011 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   7  *
   8  * Permission is hereby granted, free of charge, to any person obtaining a copy
   9  * of this software and associated documentation files (the "Software"), to deal
  10  * in the Software without restriction, including without limitation the rights
  11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  12  * copies of the Software, and to permit persons to whom the Software is
  13  * furnished to do so, subject to the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included in
  16  * all copies or substantial portions of the Software.
  17  */
  18
  19 #include <babeltrace/format.h>
  20 #include <babeltrace/ctf/types.h>
  21 #include <babeltrace/ctf/metadata.h>
  22 #include <babeltrace/babeltrace.h>
  23 #include <inttypes.h>
  24 #include <uuid/uuid.h>
  25 #include <sys/mman.h>
  26 #include <errno.h>
  27 #include <sys/types.h>
  28 #include <sys/stat.h>
  29 #include <fcntl.h>
  30 #include <dirent.h>
  31 #include <glib.h>
  32 #include <unistd.h>
  33 #include <stdlib.h>
  34
  35 #include "metadata/ctf-scanner.h"
  36 #include "metadata/ctf-parser.h"
  37 #include "metadata/ctf-ast.h"
  38
  39 /*
  40  * We currently simply map a page to read the packet header and packet
  41  * context to get the packet length and content length. (in bits)
  42  */
  43 #define MAX_PACKET_HEADER_LEN   (getpagesize() * CHAR_BIT)
  44 #define WRITE_PACKET_LEN        (getpagesize() * 8 * CHAR_BIT)
  45 #define UUID_LEN 16     /* uuid by value len */
  46
  47 extern int yydebug;
  48
  49 struct trace_descriptor {
  50         struct ctf_trace ctf_trace;
  51 };
  52
  53 struct trace_descriptor *ctf_open_trace(const char *path, int flags);
  54 void ctf_close_trace(struct trace_descriptor *descriptor);
  55
  56 static struct format ctf_format = {
  57         .uint_read = ctf_uint_read,
  58         .int_read = ctf_int_read,
  59         .uint_write = ctf_uint_write,
  60         .int_write = ctf_int_write,
  61         .double_read = ctf_double_read,
  62         .double_write = ctf_double_write,
  63         .ldouble_read = ctf_ldouble_read,
  64         .ldouble_write = ctf_ldouble_write,
  65         .float_copy = ctf_float_copy,
  66         .string_copy = ctf_string_copy,
  67         .string_read = ctf_string_read,
  68         .string_write = ctf_string_write,
  69         .string_free_temp = ctf_string_free_temp,
  70         .enum_read = ctf_enum_read,
  71         .enum_write = ctf_enum_write,
  72         .struct_begin = ctf_struct_begin,
  73         .struct_end = ctf_struct_end,
  74         .variant_begin = ctf_variant_begin,
  75         .variant_end = ctf_variant_end,
  76         .array_begin = ctf_array_begin,
  77         .array_end = ctf_array_end,
  78         .sequence_begin = ctf_sequence_begin,
  79         .sequence_end = ctf_sequence_end,
  80         .open_trace = ctf_open_trace,
  81         .close_trace = ctf_close_trace,
  82 };
  83
  84 void init_pos(struct stream_pos *pos, int fd)
  85 {
  86         pos->fd = fd;
  87         pos->mmap_offset = 0;
  88         pos->packet_size = 0;
  89         pos->content_size = 0;
  90         pos->content_size_loc = NULL;
  91         pos->base = NULL;
  92         pos->offset = 0;
  93         pos->dummy = false;
  94         pos->packet_index = g_array_new(FALSE, TRUE,
  95                                         sizeof(struct packet_index));
  96         pos->cur_index = 0;
  97         if (fd >= 0) {
  98                 int flags = fcntl(fd, F_GETFL, 0);
  99
 100                 switch (flags & O_ACCMODE) {
 101                 case O_RDONLY:
 102                         pos->prot = PROT_READ;
 103                         pos->flags = MAP_PRIVATE;
 104                         break;
 105                 case O_WRONLY:
 106                 case O_RDWR:
 107                         pos->prot = PROT_WRITE; /* Write has priority */
 108                         pos->flags = MAP_SHARED;
 109                         move_pos_slow(pos, 0);  /* position for write */
 110                         break;
 111                 default:
 112                         assert(0);
 113                 }
 114
 115         }
 116 }
 117
 118 void fini_pos(struct stream_pos *pos)
 119 {
 120         int ret;
 121
 122         if (pos->prot == PROT_WRITE && pos->content_size_loc)
 123                 *pos->content_size_loc = pos->offset;
 124         if (pos->base) {
 125                 /* unmap old base */
 126                 ret = munmap(pos->base, pos->packet_size / CHAR_BIT);
 127                 if (ret) {
 128                         fprintf(stdout, "Unable to unmap old base: %s.\n",
 129                                 strerror(errno));
 130                         assert(0);
 131                 }
 132         }
 133         (void) g_array_free(pos->packet_index, TRUE);
 134 }
 135
 136 void move_pos_slow(struct stream_pos *pos, size_t offset)
 137 {
 138         int ret;
 139         off_t off;
 140         struct packet_index *index;
 141
 142
 143         if (pos->prot == PROT_WRITE && pos->content_size_loc)
 144                 *pos->content_size_loc = pos->offset;
 145
 146         if (pos->base) {
 147                 /* unmap old base */
 148                 ret = munmap(pos->base, pos->packet_size / CHAR_BIT);
 149                 if (ret) {
 150                         fprintf(stdout, "Unable to unmap old base: %s.\n",
 151                                 strerror(errno));
 152                         assert(0);
 153                 }
 154         }
 155
 156         /*
 157          * The caller should never ask for move_pos across packets,
 158          * except to get exactly at the beginning of the next packet.
 159          */
 160         if (pos->prot == PROT_WRITE) {
 161                 /* The writer will add padding */
 162                 assert(pos->offset + offset == pos->packet_size);
 163
 164                 /*
 165                  * Don't increment for initial stream move (only condition where
 166                  * pos->offset can be 0.
 167                  */
 168                 if (pos->offset)
 169                         pos->mmap_offset += WRITE_PACKET_LEN / CHAR_BIT;
 170                 pos->content_size = -1U;        /* Unknown at this point */
 171                 pos->packet_size = WRITE_PACKET_LEN;
 172                 off = posix_fallocate(pos->fd, pos->mmap_offset, pos->packet_size / CHAR_BIT);
 173                 assert(off >= 0);
 174         } else {
 175                 /* The reader will expect us to skip padding */
 176                 assert(pos->offset + offset == pos->content_size);
 177
 178                 /*
 179                  * Don't increment for initial stream move (only condition where
 180                  * pos->offset can be 0).
 181                  */
 182                 if (pos->offset)
 183                         ++pos->cur_index;
 184                 index = &g_array_index(pos->packet_index, struct packet_index,
 185                                        pos->cur_index);
 186                 pos->mmap_offset = index->offset;
 187
 188                 /* Lookup context/packet size in index */
 189                 pos->content_size = index->content_size;
 190                 pos->packet_size = index->packet_size;
 191         }
 192         /* map new base. Need mapping length from header. */
 193         pos->base = mmap(NULL, pos->packet_size / CHAR_BIT, pos->prot,
 194                          pos->flags, pos->fd, pos->mmap_offset);
 195         pos->offset = 0;
 196 }
 197
 198 /*
 199  * TODO: for now, we treat the metadata file as a simple text file
 200  * (without any header nor packets nor padding).
 201  */
 202 static
 203 int ctf_open_trace_metadata_read(struct trace_descriptor *td)
 204 {
 205         struct ctf_scanner *scanner;
 206         FILE *fp;
 207         int ret = 0;
 208
 209         td->ctf_trace.metadata.pos.fd = openat(td->ctf_trace.dirfd,
 210                         "metadata", O_RDONLY);
 211         if (td->ctf_trace.metadata.pos.fd < 0) {
 212                 fprintf(stdout, "Unable to open metadata.\n");
 213                 return td->ctf_trace.metadata.pos.fd;
 214         }
 215
 216         if (babeltrace_debug)
 217                 yydebug = 1;
 218
 219         fp = fdopen(td->ctf_trace.metadata.pos.fd, "r");
 220         if (!fp) {
 221                 fprintf(stdout, "Unable to open metadata stream.\n");
 222                 ret = -errno;
 223                 goto end_stream;
 224         }
 225
 226         scanner = ctf_scanner_alloc(fp);
 227         if (!scanner) {
 228                 fprintf(stdout, "Error allocating scanner\n");
 229                 ret = -ENOMEM;
 230                 goto end_scanner_alloc;
 231         }
 232         ret = ctf_scanner_append_ast(scanner);
 233         if (ret) {
 234                 fprintf(stdout, "Error creating AST\n");
 235                 goto end;
 236         }
 237
 238         if (babeltrace_debug) {
 239                 ret = ctf_visitor_print_xml(stdout, 0, &scanner->ast->root);
 240                 if (ret) {
 241                         fprintf(stdout, "Error visiting AST for XML output\n");
 242                         goto end;
 243                 }
 244         }
 245
 246         ret = ctf_visitor_semantic_check(stdout, 0, &scanner->ast->root);
 247         if (ret) {
 248                 fprintf(stdout, "Error in CTF semantic validation %d\n", ret);
 249                 goto end;
 250         }
 251         ret = ctf_visitor_construct_metadata(stdout, 0, &scanner->ast->root,
 252                         &td->ctf_trace, BYTE_ORDER);
 253         if (ret) {
 254                 fprintf(stdout, "Error in CTF metadata constructor %d\n", ret);
 255                 goto end;
 256         }
 257 end:
 258         ctf_scanner_free(scanner);
 259 end_scanner_alloc:
 260         fclose(fp);
 261 end_stream:
 262         close(td->ctf_trace.metadata.pos.fd);
 263         return ret;
 264 }
 265
 266
 267 static
 268 int create_stream_packet_index(struct trace_descriptor *td,
 269                                struct ctf_file_stream *file_stream)
 270 {
 271         struct ctf_stream *stream;
 272         int len_index;
 273         struct stream_pos *pos;
 274         struct stat filestats;
 275         struct packet_index packet_index;
 276         int first_packet = 1;
 277         int ret;
 278
 279         pos = &file_stream->pos;
 280
 281         ret = fstat(pos->fd, &filestats);
 282         if (ret < 0)
 283                 return ret;
 284
 285         for (pos->mmap_offset = 0; pos->mmap_offset < filestats.st_size; ) {
 286                 uint64_t stream_id = 0;
 287
 288                 if (pos->base) {
 289                         /* unmap old base */
 290                         ret = munmap(pos->base, pos->packet_size / CHAR_BIT);
 291                         if (ret) {
 292                                 fprintf(stdout, "Unable to unmap old base: %s.\n",
 293                                         strerror(errno));
 294                                 return ret;
 295                         }
 296                         pos->base = NULL;
 297                 }
 298                 /* map new base. Need mapping length from header. */
 299                 pos->base = mmap(NULL, MAX_PACKET_HEADER_LEN / CHAR_BIT, PROT_READ,
 300                                  MAP_PRIVATE, pos->fd, pos->mmap_offset);
 301                 pos->content_size = MAX_PACKET_HEADER_LEN;      /* Unknown at this point */
 302                 pos->packet_size = MAX_PACKET_HEADER_LEN;       /* Unknown at this point */
 303                 pos->offset = 0;        /* Position of the packet header */
 304
 305                 packet_index.offset = pos->mmap_offset;
 306                 packet_index.content_size = 0;
 307                 packet_index.packet_size = 0;
 308
 309                 /* read and check header, set stream id (and check) */
 310                 if (td->ctf_trace.packet_header) {
 311                         /* Read packet header */
 312                         td->ctf_trace.packet_header->p.declaration->copy(NULL, NULL,
 313                                 pos, &ctf_format, &td->ctf_trace.packet_header->p);
 314
 315                         len_index = struct_declaration_lookup_field_index(td->ctf_trace.packet_header->declaration, g_quark_from_static_string("magic"));
 316                         if (len_index >= 0) {
 317                                 struct definition_integer *defint;
 318                                 struct field *field;
 319
 320                                 field = struct_definition_get_field_from_index(td->ctf_trace.packet_header, len_index);
 321                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 322                                 defint = container_of(field->definition, struct definition_integer, p);
 323                                 assert(defint->declaration->signedness == FALSE);
 324                                 if (defint->value._unsigned != CTF_MAGIC) {
 325                                         fprintf(stdout, "[error] Invalid magic number %" PRIX64 " at packet %u (file offset %zd).\n",
 326                                                         defint->value._unsigned,
 327                                                         file_stream->pos.packet_index->len,
 328                                                         (ssize_t) pos->mmap_offset);
 329                                         return -EINVAL;
 330                                 }
 331                         }
 332
 333                         /* check uuid */
 334                         len_index = struct_declaration_lookup_field_index(td->ctf_trace.packet_header->declaration, g_quark_from_static_string("trace_uuid"));
 335                         if (len_index >= 0) {
 336                                 struct definition_array *defarray;
 337                                 struct field *field;
 338                                 uint64_t i;
 339                                 uint8_t uuidval[UUID_LEN];
 340
 341                                 field = struct_definition_get_field_from_index(td->ctf_trace.packet_header, len_index);
 342                                 assert(field->definition->declaration->id == CTF_TYPE_ARRAY);
 343                                 defarray = container_of(field->definition, struct definition_array, p);
 344                                 assert(array_len(defarray) == UUID_LEN);
 345                                 assert(defarray->declaration->elem->id == CTF_TYPE_INTEGER);
 346
 347                                 for (i = 0; i < UUID_LEN; i++) {
 348                                         struct definition *elem;
 349                                         struct definition_integer *defint;
 350
 351                                         elem = array_index(defarray, i);
 352                                         assert(elem);
 353                                         defint = container_of(elem, struct definition_integer, p);
 354                                         uuidval[i] = defint->value._unsigned;
 355                                 }
 356                                 ret = uuid_compare(td->ctf_trace.uuid, uuidval);
 357                                 if (ret) {
 358                                         fprintf(stdout, "[error] Unique Universal Identifiers do not match.\n");
 359                                         return -EINVAL;
 360                                 }
 361                         }
 362
 363
 364                         len_index = struct_declaration_lookup_field_index(td->ctf_trace.packet_header->declaration, g_quark_from_static_string("stream_id"));
 365                         if (len_index >= 0) {
 366                                 struct definition_integer *defint;
 367                                 struct field *field;
 368
 369                                 field = struct_definition_get_field_from_index(td->ctf_trace.packet_header, len_index);
 370                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 371                                 defint = container_of(field->definition, struct definition_integer, p);
 372                                 assert(defint->declaration->signedness == FALSE);
 373                                 stream_id = defint->value._unsigned;
 374                         }
 375                 }
 376
 377                 if (!first_packet && file_stream->stream_id != stream_id) {
 378                         fprintf(stdout, "[error] Stream ID is changing within a stream.\n");
 379                         return -EINVAL;
 380                 }
 381                 if (first_packet) {
 382                         file_stream->stream_id = stream_id;
 383                         if (stream_id >= td->ctf_trace.streams->len) {
 384                                 fprintf(stdout, "[error] Stream %" PRIu64 " is not declared in metadata.\n", stream_id);
 385                                 return -EINVAL;
 386                         }
 387                         stream = g_ptr_array_index(td->ctf_trace.streams, stream_id);
 388                         if (!stream) {
 389                                 fprintf(stdout, "[error] Stream %" PRIu64 " is not declared in metadata.\n", stream_id);
 390                                 return -EINVAL;
 391                         }
 392                         file_stream->stream = stream;
 393                 }
 394                 first_packet = 0;
 395
 396                 if (stream->packet_context) {
 397                         /* Read packet context */
 398                         stream->packet_context->p.declaration->copy(NULL, NULL,
 399                                         pos, &ctf_format, &stream->packet_context->p);
 400
 401                         /* read content size from header */
 402                         len_index = struct_declaration_lookup_field_index(stream->packet_context->declaration, g_quark_from_static_string("content_size"));
 403                         if (len_index >= 0) {
 404                                 struct definition_integer *defint;
 405                                 struct field *field;
 406
 407                                 field = struct_definition_get_field_from_index(stream->packet_context, len_index);
 408                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 409                                 defint = container_of(field->definition, struct definition_integer, p);
 410                                 assert(defint->declaration->signedness == FALSE);
 411                                 packet_index.content_size = defint->value._unsigned;
 412                         } else {
 413                                 /* Use file size for packet size */
 414                                 packet_index.content_size = filestats.st_size * CHAR_BIT;
 415                         }
 416
 417                         /* read packet size from header */
 418                         len_index = struct_declaration_lookup_field_index(stream->packet_context->declaration, g_quark_from_static_string("packet_size"));
 419                         if (len_index >= 0) {
 420                                 struct definition_integer *defint;
 421                                 struct field *field;
 422
 423                                 field = struct_definition_get_field_from_index(stream->packet_context, len_index);
 424                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 425                                 defint = container_of(field->definition, struct definition_integer, p);
 426                                 assert(defint->declaration->signedness == FALSE);
 427                                 packet_index.packet_size = defint->value._unsigned;
 428                         } else {
 429                                 /* Use content size if non-zero, else file size */
 430                                 packet_index.packet_size = packet_index.content_size ? : filestats.st_size * CHAR_BIT;
 431                         }
 432                 } else {
 433                         /* Use file size for packet size */
 434                         packet_index.content_size = filestats.st_size * CHAR_BIT;
 435                         /* Use content size if non-zero, else file size */
 436                         packet_index.packet_size = packet_index.content_size ? : filestats.st_size * CHAR_BIT;
 437                 }
 438
 439                 /* add index to packet array */
 440                 g_array_append_val(file_stream->pos.packet_index, packet_index);
 441
 442                 pos->mmap_offset += packet_index.packet_size / CHAR_BIT;
 443         }
 444
 445         return 0;
 446 }
 447
 448 /*
 449  * Note: many file streams can inherit from the same stream class
 450  * description (metadata).
 451  */
 452 static
 453 int ctf_open_file_stream_read(struct trace_descriptor *td, const char *path, int flags)
 454 {
 455         int ret;
 456         struct ctf_file_stream *file_stream;
 457
 458         ret = openat(td->ctf_trace.dirfd, path, flags);
 459         if (ret < 0)
 460                 goto error;
 461         file_stream = g_new0(struct ctf_file_stream, 1);
 462         init_pos(&file_stream->pos, ret);
 463         ret = create_stream_packet_index(td, file_stream);
 464         if (ret)
 465                 goto error_index;
 466         /* Add stream file to stream class */
 467         g_ptr_array_add(file_stream->stream->files, file_stream);
 468         return 0;
 469
 470 error_index:
 471         fini_pos(&file_stream->pos);
 472         close(file_stream->pos.fd);
 473         g_free(file_stream);
 474 error:
 475         return ret;
 476 }
 477
 478 static
 479 int ctf_open_trace_read(struct trace_descriptor *td, const char *path, int flags)
 480 {
 481         int ret;
 482         struct dirent *dirent;
 483         struct dirent *diriter;
 484         size_t dirent_len;
 485
 486         td->ctf_trace.flags = flags;
 487
 488         /* Open trace directory */
 489         td->ctf_trace.dir = opendir(path);
 490         if (!td->ctf_trace.dir) {
 491                 fprintf(stdout, "[error] Unable to open trace directory.\n");
 492                 ret = -ENOENT;
 493                 goto error;
 494         }
 495
 496         td->ctf_trace.dirfd = open(path, 0);
 497         if (td->ctf_trace.dirfd < 0) {
 498                 fprintf(stdout, "[error] Unable to open trace directory file descriptor.\n");
 499                 ret = -ENOENT;
 500                 goto error_dirfd;
 501         }
 502
 503         td->ctf_trace.streams = g_ptr_array_new();
 504
 505         /*
 506          * Keep the metadata file separate.
 507          */
 508
 509         ret = ctf_open_trace_metadata_read(td);
 510         if (ret) {
 511                 goto error_metadata;
 512         }
 513
 514         /*
 515          * Open each stream: for each file, try to open, check magic
 516          * number, and get the stream ID to add to the right location in
 517          * the stream array.
 518          */
 519
 520         dirent_len = offsetof(struct dirent, d_name) +
 521                         fpathconf(td->ctf_trace.dirfd, _PC_NAME_MAX) + 1;
 522
 523         dirent = malloc(dirent_len);
 524
 525         for (;;) {
 526                 ret = readdir_r(td->ctf_trace.dir, dirent, &diriter);
 527                 if (ret) {
 528                         fprintf(stdout, "[error] Readdir error.\n");
 529                         goto readdir_error;
 530                 }
 531                 if (!diriter)
 532                         break;
 533                 if (!strcmp(diriter->d_name, ".")
 534                                 || !strcmp(diriter->d_name, "..")
 535                                 || !strcmp(diriter->d_name, "metadata"))
 536                         continue;
 537                 ret = ctf_open_file_stream_read(td, diriter->d_name, flags);
 538                 if (ret) {
 539                         fprintf(stdout, "[error] Open file stream error.\n");
 540                         goto readdir_error;
 541                 }
 542         }
 543
 544         free(dirent);
 545         return 0;
 546
 547 readdir_error:
 548         free(dirent);
 549 error_metadata:
 550         g_ptr_array_free(td->ctf_trace.streams, TRUE);
 551         close(td->ctf_trace.dirfd);
 552 error_dirfd:
 553         closedir(td->ctf_trace.dir);
 554 error:
 555         return ret;
 556 }
 557
 558 static
 559 int ctf_open_trace_write(struct trace_descriptor *td, const char *path, int flags)
 560 {
 561         int ret;
 562
 563         ret = mkdir(path, S_IRWXU|S_IRWXG);
 564         if (ret)
 565                 return ret;
 566
 567         /* Open trace directory */
 568         td->ctf_trace.dir = opendir(path);
 569         if (!td->ctf_trace.dir) {
 570                 fprintf(stdout, "Unable to open trace directory.\n");
 571                 ret = -ENOENT;
 572                 goto error;
 573         }
 574
 575
 576         return 0;
 577
 578 error:
 579         return ret;
 580 }
 581
 582 struct trace_descriptor *ctf_open_trace(const char *path, int flags)
 583 {
 584         struct trace_descriptor *td;
 585         int ret;
 586
 587         td = g_new0(struct trace_descriptor, 1);
 588
 589         switch (flags & O_ACCMODE) {
 590         case O_RDONLY:
 591                 ret = ctf_open_trace_read(td, path, flags);
 592                 if (ret)
 593                         goto error;
 594                 break;
 595         case O_WRONLY:
 596                 ret = ctf_open_trace_write(td, path, flags);
 597                 if (ret)
 598                         goto error;
 599                 break;
 600         default:
 601                 fprintf(stdout, "Incorrect open flags.\n");
 602                 goto error;
 603         }
 604
 605         return td;
 606 error:
 607         g_free(td);
 608         return NULL;
 609 }
 610
 611 static
 612 void ctf_close_file_stream(struct ctf_file_stream *file_stream)
 613 {
 614         fini_pos(&file_stream->pos);
 615         close(file_stream->pos.fd);
 616 }
 617
 618 void ctf_close_trace(struct trace_descriptor *td)
 619 {
 620         int i;
 621
 622         if (td->ctf_trace.streams) {
 623                 for (i = 0; i < td->ctf_trace.streams->len; i++) {
 624                         struct ctf_stream *stream;
 625                         int j;
 626
 627                         stream = g_ptr_array_index(td->ctf_trace.streams, i);
 628                         for (j = 0; j < stream->files->len; j++) {
 629                                 struct ctf_file_stream *file_stream;
 630                                 file_stream = g_ptr_array_index(td->ctf_trace.streams, j);
 631                                 ctf_close_file_stream(file_stream);
 632                         }
 633
 634                 }
 635                 g_ptr_array_free(td->ctf_trace.streams, TRUE);
 636         }
 637         closedir(td->ctf_trace.dir);
 638         g_free(td);
 639 }
 640
 641 void __attribute__((constructor)) ctf_init(void)
 642 {
 643         int ret;
 644
 645         ctf_format.name = g_quark_from_static_string("ctf");
 646         ret = bt_register_format(&ctf_format);
 647         assert(!ret);
 648 }
 649
 650 /* TODO: finalize */