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 *ctf_open_trace(const char *path, int flags);
  50 void ctf_close_trace(struct trace_descriptor *descriptor);
  51
  52 static
  53 rw_dispatch read_dispatch_table[] = {
  54         [ CTF_TYPE_INTEGER ] = ctf_integer_read,
  55         [ CTF_TYPE_FLOAT ] = ctf_float_read,
  56         [ CTF_TYPE_ENUM ] = ctf_enum_read,
  57         [ CTF_TYPE_STRING ] = ctf_string_read,
  58         [ CTF_TYPE_STRUCT ] = ctf_struct_rw,
  59         [ CTF_TYPE_VARIANT ] = ctf_variant_rw,
  60         [ CTF_TYPE_ARRAY ] = ctf_array_rw,
  61         [ CTF_TYPE_SEQUENCE ] = ctf_sequence_rw,
  62 };
  63
  64 static
  65 rw_dispatch write_dispatch_table[] = {
  66         [ CTF_TYPE_INTEGER ] = ctf_integer_write,
  67         [ CTF_TYPE_FLOAT ] = ctf_float_write,
  68         [ CTF_TYPE_ENUM ] = ctf_enum_write,
  69         [ CTF_TYPE_STRING ] = ctf_string_write,
  70         [ CTF_TYPE_STRUCT ] = ctf_struct_rw,
  71         [ CTF_TYPE_VARIANT ] = ctf_variant_rw,
  72         [ CTF_TYPE_ARRAY ] = ctf_array_rw,
  73         [ CTF_TYPE_SEQUENCE ] = ctf_sequence_rw,
  74 };
  75
  76 static
  77 struct format ctf_format = {
  78         .open_trace = ctf_open_trace,
  79         .close_trace = ctf_close_trace,
  80 };
  81
  82 void ctf_init_pos(struct ctf_stream_pos *pos, int fd, int open_flags)
  83 {
  84         pos->fd = fd;
  85         pos->mmap_offset = 0;
  86         pos->packet_size = 0;
  87         pos->content_size = 0;
  88         pos->content_size_loc = NULL;
  89         pos->base = NULL;
  90         pos->offset = 0;
  91         pos->dummy = false;
  92         pos->cur_index = 0;
  93         if (fd >= 0)
  94                 pos->packet_index = g_array_new(FALSE, TRUE,
  95                                                 sizeof(struct packet_index));
  96         else
  97                 pos->packet_index = NULL;
  98         switch (open_flags & O_ACCMODE) {
  99         case O_RDONLY:
 100                 pos->prot = PROT_READ;
 101                 pos->flags = MAP_PRIVATE;
 102                 pos->parent.rw_table = read_dispatch_table;
 103                 break;
 104         case O_WRONLY:
 105         case O_RDWR:
 106                 pos->prot = PROT_WRITE; /* Write has priority */
 107                 pos->flags = MAP_SHARED;
 108                 pos->parent.rw_table = write_dispatch_table;
 109                 if (fd >= 0)
 110                         ctf_move_pos_slow(pos, 0);      /* position for write */
 111                 break;
 112         default:
 113                 assert(0);
 114         }
 115 }
 116
 117 void ctf_fini_pos(struct ctf_stream_pos *pos)
 118 {
 119         int ret;
 120
 121         if (pos->prot == PROT_WRITE && pos->content_size_loc)
 122                 *pos->content_size_loc = pos->offset;
 123         if (pos->base) {
 124                 /* unmap old base */
 125                 ret = munmap(pos->base, pos->packet_size / CHAR_BIT);
 126                 if (ret) {
 127                         fprintf(stdout, "[error] Unable to unmap old base: %s.\n",
 128                                 strerror(errno));
 129                         assert(0);
 130                 }
 131         }
 132         (void) g_array_free(pos->packet_index, TRUE);
 133 }
 134
 135 void ctf_move_pos_slow(struct ctf_stream_pos *pos, size_t offset)
 136 {
 137         int ret;
 138         off_t off;
 139         struct packet_index *index;
 140
 141
 142         if (pos->prot == PROT_WRITE && pos->content_size_loc)
 143                 *pos->content_size_loc = pos->offset;
 144
 145         if (pos->base) {
 146                 /* unmap old base */
 147                 ret = munmap(pos->base, pos->packet_size / CHAR_BIT);
 148                 if (ret) {
 149                         fprintf(stdout, "[error] Unable to unmap old base: %s.\n",
 150                                 strerror(errno));
 151                         assert(0);
 152                 }
 153         }
 154
 155         /*
 156          * The caller should never ask for ctf_move_pos across packets,
 157          * except to get exactly at the beginning of the next packet.
 158          */
 159         if (pos->prot == PROT_WRITE) {
 160                 /* The writer will add padding */
 161                 assert(pos->offset + offset == pos->packet_size);
 162
 163                 /*
 164                  * Don't increment for initial stream move (only condition where
 165                  * pos->offset can be 0.
 166                  */
 167                 if (pos->offset)
 168                         pos->mmap_offset += WRITE_PACKET_LEN / CHAR_BIT;
 169                 pos->content_size = -1U;        /* Unknown at this point */
 170                 pos->packet_size = WRITE_PACKET_LEN;
 171                 off = posix_fallocate(pos->fd, pos->mmap_offset, pos->packet_size / CHAR_BIT);
 172                 assert(off >= 0);
 173         } else {
 174                 /* The reader will expect us to skip padding */
 175                 assert(pos->offset + offset == pos->content_size);
 176
 177                 /*
 178                  * Don't increment for initial stream move (only condition where
 179                  * pos->offset can be 0).
 180                  */
 181                 if (pos->offset)
 182                         ++pos->cur_index;
 183                 index = &g_array_index(pos->packet_index, struct packet_index,
 184                                        pos->cur_index);
 185                 pos->mmap_offset = index->offset;
 186
 187                 /* Lookup context/packet size in index */
 188                 pos->content_size = index->content_size;
 189                 pos->packet_size = index->packet_size;
 190         }
 191         /* map new base. Need mapping length from header. */
 192         pos->base = mmap(NULL, pos->packet_size / CHAR_BIT, pos->prot,
 193                          pos->flags, pos->fd, pos->mmap_offset);
 194         pos->offset = 0;
 195 }
 196
 197 /*
 198  * TODO: for now, we treat the metadata file as a simple text file
 199  * (without any header nor packets nor padding).
 200  */
 201 static
 202 int ctf_open_trace_metadata_read(struct ctf_trace *td)
 203 {
 204         struct ctf_scanner *scanner;
 205         FILE *fp;
 206         int ret = 0;
 207
 208         td->metadata.pos.fd = openat(td->dirfd, "metadata", O_RDONLY);
 209         if (td->metadata.pos.fd < 0) {
 210                 fprintf(stdout, "Unable to open metadata.\n");
 211                 return td->metadata.pos.fd;
 212         }
 213
 214         if (babeltrace_debug)
 215                 yydebug = 1;
 216
 217         fp = fdopen(td->metadata.pos.fd, "r");
 218         if (!fp) {
 219                 fprintf(stdout, "[error] Unable to open metadata stream.\n");
 220                 ret = -errno;
 221                 goto end_stream;
 222         }
 223
 224         scanner = ctf_scanner_alloc(fp);
 225         if (!scanner) {
 226                 fprintf(stdout, "[error] Error allocating scanner\n");
 227                 ret = -ENOMEM;
 228                 goto end_scanner_alloc;
 229         }
 230         ret = ctf_scanner_append_ast(scanner);
 231         if (ret) {
 232                 fprintf(stdout, "[error] Error creating AST\n");
 233                 goto end;
 234         }
 235
 236         if (babeltrace_debug) {
 237                 ret = ctf_visitor_print_xml(stdout, 0, &scanner->ast->root);
 238                 if (ret) {
 239                         fprintf(stdout, "[error] Error visiting AST for XML output\n");
 240                         goto end;
 241                 }
 242         }
 243
 244         ret = ctf_visitor_semantic_check(stdout, 0, &scanner->ast->root);
 245         if (ret) {
 246                 fprintf(stdout, "[error] Error in CTF semantic validation %d\n", ret);
 247                 goto end;
 248         }
 249         ret = ctf_visitor_construct_metadata(stdout, 0, &scanner->ast->root,
 250                         td, BYTE_ORDER);
 251         if (ret) {
 252                 fprintf(stdout, "[error] Error in CTF metadata constructor %d\n", ret);
 253                 goto end;
 254         }
 255 end:
 256         ctf_scanner_free(scanner);
 257 end_scanner_alloc:
 258         fclose(fp);
 259 end_stream:
 260         close(td->metadata.pos.fd);
 261         return ret;
 262 }
 263
 264
 265 static
 266 int create_stream_packet_index(struct ctf_trace *td,
 267                                struct ctf_file_stream *file_stream)
 268 {
 269         struct ctf_stream *stream;
 270         int len_index;
 271         struct ctf_stream_pos *pos;
 272         struct stat filestats;
 273         struct packet_index packet_index;
 274         int first_packet = 1;
 275         int ret;
 276
 277         pos = &file_stream->pos;
 278
 279         ret = fstat(pos->fd, &filestats);
 280         if (ret < 0)
 281                 return ret;
 282
 283         for (pos->mmap_offset = 0; pos->mmap_offset < filestats.st_size; ) {
 284                 uint64_t stream_id = 0;
 285
 286                 if (pos->base) {
 287                         /* unmap old base */
 288                         ret = munmap(pos->base, pos->packet_size / CHAR_BIT);
 289                         if (ret) {
 290                                 fprintf(stdout, "[error] Unable to unmap old base: %s.\n",
 291                                         strerror(errno));
 292                                 return ret;
 293                         }
 294                         pos->base = NULL;
 295                 }
 296                 /* map new base. Need mapping length from header. */
 297                 pos->base = mmap(NULL, MAX_PACKET_HEADER_LEN / CHAR_BIT, PROT_READ,
 298                                  MAP_PRIVATE, pos->fd, pos->mmap_offset);
 299                 pos->content_size = MAX_PACKET_HEADER_LEN;      /* Unknown at this point */
 300                 pos->packet_size = MAX_PACKET_HEADER_LEN;       /* Unknown at this point */
 301                 pos->offset = 0;        /* Position of the packet header */
 302
 303                 packet_index.offset = pos->mmap_offset;
 304                 packet_index.content_size = 0;
 305                 packet_index.packet_size = 0;
 306
 307                 /* read and check header, set stream id (and check) */
 308                 if (td->packet_header) {
 309                         /* Read packet header */
 310                         generic_rw(&pos->parent, &td->packet_header->p);
 311
 312                         len_index = struct_declaration_lookup_field_index(td->packet_header->declaration, g_quark_from_static_string("magic"));
 313                         if (len_index >= 0) {
 314                                 struct definition_integer *defint;
 315                                 struct field *field;
 316
 317                                 field = struct_definition_get_field_from_index(td->packet_header, len_index);
 318                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 319                                 defint = container_of(field->definition, struct definition_integer, p);
 320                                 assert(defint->declaration->signedness == FALSE);
 321                                 if (defint->value._unsigned != CTF_MAGIC) {
 322                                         fprintf(stdout, "[error] Invalid magic number %" PRIX64 " at packet %u (file offset %zd).\n",
 323                                                         defint->value._unsigned,
 324                                                         file_stream->pos.packet_index->len,
 325                                                         (ssize_t) pos->mmap_offset);
 326                                         return -EINVAL;
 327                                 }
 328                         }
 329
 330                         /* check uuid */
 331                         len_index = struct_declaration_lookup_field_index(td->packet_header->declaration, g_quark_from_static_string("trace_uuid"));
 332                         if (len_index >= 0) {
 333                                 struct definition_array *defarray;
 334                                 struct field *field;
 335                                 uint64_t i;
 336                                 uint8_t uuidval[UUID_LEN];
 337
 338                                 field = struct_definition_get_field_from_index(td->packet_header, len_index);
 339                                 assert(field->definition->declaration->id == CTF_TYPE_ARRAY);
 340                                 defarray = container_of(field->definition, struct definition_array, p);
 341                                 assert(array_len(defarray) == UUID_LEN);
 342                                 assert(defarray->declaration->elem->id == CTF_TYPE_INTEGER);
 343
 344                                 for (i = 0; i < UUID_LEN; i++) {
 345                                         struct definition *elem;
 346                                         struct definition_integer *defint;
 347
 348                                         elem = array_index(defarray, i);
 349                                         assert(elem);
 350                                         defint = container_of(elem, struct definition_integer, p);
 351                                         uuidval[i] = defint->value._unsigned;
 352                                 }
 353                                 ret = uuid_compare(td->uuid, uuidval);
 354                                 if (ret) {
 355                                         fprintf(stdout, "[error] Unique Universal Identifiers do not match.\n");
 356                                         return -EINVAL;
 357                                 }
 358                         }
 359
 360
 361                         len_index = struct_declaration_lookup_field_index(td->packet_header->declaration, g_quark_from_static_string("stream_id"));
 362                         if (len_index >= 0) {
 363                                 struct definition_integer *defint;
 364                                 struct field *field;
 365
 366                                 field = struct_definition_get_field_from_index(td->packet_header, len_index);
 367                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 368                                 defint = container_of(field->definition, struct definition_integer, p);
 369                                 assert(defint->declaration->signedness == FALSE);
 370                                 stream_id = defint->value._unsigned;
 371                         }
 372                 }
 373
 374                 if (!first_packet && file_stream->stream_id != stream_id) {
 375                         fprintf(stdout, "[error] Stream ID is changing within a stream.\n");
 376                         return -EINVAL;
 377                 }
 378                 if (first_packet) {
 379                         file_stream->stream_id = stream_id;
 380                         if (stream_id >= td->streams->len) {
 381                                 fprintf(stdout, "[error] Stream %" PRIu64 " is not declared in metadata.\n", stream_id);
 382                                 return -EINVAL;
 383                         }
 384                         stream = g_ptr_array_index(td->streams, stream_id);
 385                         if (!stream) {
 386                                 fprintf(stdout, "[error] Stream %" PRIu64 " is not declared in metadata.\n", stream_id);
 387                                 return -EINVAL;
 388                         }
 389                         file_stream->stream = stream;
 390                 }
 391                 first_packet = 0;
 392
 393                 if (stream->packet_context) {
 394                         /* Read packet context */
 395                         generic_rw(&pos->parent, &stream->packet_context->p);
 396
 397                         /* read content size from header */
 398                         len_index = struct_declaration_lookup_field_index(stream->packet_context->declaration, g_quark_from_static_string("content_size"));
 399                         if (len_index >= 0) {
 400                                 struct definition_integer *defint;
 401                                 struct field *field;
 402
 403                                 field = struct_definition_get_field_from_index(stream->packet_context, len_index);
 404                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 405                                 defint = container_of(field->definition, struct definition_integer, p);
 406                                 assert(defint->declaration->signedness == FALSE);
 407                                 packet_index.content_size = defint->value._unsigned;
 408                         } else {
 409                                 /* Use file size for packet size */
 410                                 packet_index.content_size = filestats.st_size * CHAR_BIT;
 411                         }
 412
 413                         /* read packet size from header */
 414                         len_index = struct_declaration_lookup_field_index(stream->packet_context->declaration, g_quark_from_static_string("packet_size"));
 415                         if (len_index >= 0) {
 416                                 struct definition_integer *defint;
 417                                 struct field *field;
 418
 419                                 field = struct_definition_get_field_from_index(stream->packet_context, len_index);
 420                                 assert(field->definition->declaration->id == CTF_TYPE_INTEGER);
 421                                 defint = container_of(field->definition, struct definition_integer, p);
 422                                 assert(defint->declaration->signedness == FALSE);
 423                                 packet_index.packet_size = defint->value._unsigned;
 424                         } else {
 425                                 /* Use content size if non-zero, else file size */
 426                                 packet_index.packet_size = packet_index.content_size ? : filestats.st_size * CHAR_BIT;
 427                         }
 428                 } else {
 429                         /* Use file size for packet size */
 430                         packet_index.content_size = filestats.st_size * CHAR_BIT;
 431                         /* Use content size if non-zero, else file size */
 432                         packet_index.packet_size = packet_index.content_size ? : filestats.st_size * CHAR_BIT;
 433                 }
 434
 435                 /* add index to packet array */
 436                 g_array_append_val(file_stream->pos.packet_index, packet_index);
 437
 438                 pos->mmap_offset += packet_index.packet_size / CHAR_BIT;
 439         }
 440
 441         return 0;
 442 }
 443
 444 /*
 445  * Note: many file streams can inherit from the same stream class
 446  * description (metadata).
 447  */
 448 static
 449 int ctf_open_file_stream_read(struct ctf_trace *td, const char *path, int flags)
 450 {
 451         int ret;
 452         struct ctf_file_stream *file_stream;
 453
 454         ret = openat(td->dirfd, path, flags);
 455         if (ret < 0)
 456                 goto error;
 457         file_stream = g_new0(struct ctf_file_stream, 1);
 458         ctf_init_pos(&file_stream->pos, ret, flags);
 459         ret = create_stream_packet_index(td, file_stream);
 460         if (ret)
 461                 goto error_index;
 462         /* Add stream file to stream class */
 463         g_ptr_array_add(file_stream->stream->files, file_stream);
 464         return 0;
 465
 466 error_index:
 467         ctf_fini_pos(&file_stream->pos);
 468         close(file_stream->pos.fd);
 469         g_free(file_stream);
 470 error:
 471         return ret;
 472 }
 473
 474 static
 475 int ctf_open_trace_read(struct ctf_trace *td, const char *path, int flags)
 476 {
 477         int ret;
 478         struct dirent *dirent;
 479         struct dirent *diriter;
 480         size_t dirent_len;
 481
 482         td->flags = flags;
 483
 484         /* Open trace directory */
 485         td->dir = opendir(path);
 486         if (!td->dir) {
 487                 fprintf(stdout, "[error] Unable to open trace directory.\n");
 488                 ret = -ENOENT;
 489                 goto error;
 490         }
 491
 492         td->dirfd = open(path, 0);
 493         if (td->dirfd < 0) {
 494                 fprintf(stdout, "[error] Unable to open trace directory file descriptor.\n");
 495                 ret = -ENOENT;
 496                 goto error_dirfd;
 497         }
 498
 499         td->streams = g_ptr_array_new();
 500
 501         /*
 502          * Keep the metadata file separate.
 503          */
 504
 505         ret = ctf_open_trace_metadata_read(td);
 506         if (ret) {
 507                 goto error_metadata;
 508         }
 509
 510         /*
 511          * Open each stream: for each file, try to open, check magic
 512          * number, and get the stream ID to add to the right location in
 513          * the stream array.
 514          */
 515
 516         dirent_len = offsetof(struct dirent, d_name) +
 517                         fpathconf(td->dirfd, _PC_NAME_MAX) + 1;
 518
 519         dirent = malloc(dirent_len);
 520
 521         for (;;) {
 522                 ret = readdir_r(td->dir, dirent, &diriter);
 523                 if (ret) {
 524                         fprintf(stdout, "[error] Readdir error.\n");
 525                         goto readdir_error;
 526                 }
 527                 if (!diriter)
 528                         break;
 529                 if (!strcmp(diriter->d_name, ".")
 530                                 || !strcmp(diriter->d_name, "..")
 531                                 || !strcmp(diriter->d_name, "metadata"))
 532                         continue;
 533                 ret = ctf_open_file_stream_read(td, diriter->d_name, flags);
 534                 if (ret) {
 535                         fprintf(stdout, "[error] Open file stream error.\n");
 536                         goto readdir_error;
 537                 }
 538         }
 539
 540         free(dirent);
 541         return 0;
 542
 543 readdir_error:
 544         free(dirent);
 545 error_metadata:
 546         g_ptr_array_free(td->streams, TRUE);
 547         close(td->dirfd);
 548 error_dirfd:
 549         closedir(td->dir);
 550 error:
 551         return ret;
 552 }
 553
 554 static
 555 int ctf_open_trace_write(struct ctf_trace *td, const char *path, int flags)
 556 {
 557         int ret;
 558
 559         ret = mkdir(path, S_IRWXU|S_IRWXG);
 560         if (ret)
 561                 return ret;
 562
 563         /* Open trace directory */
 564         td->dir = opendir(path);
 565         if (!td->dir) {
 566                 fprintf(stdout, "[error] Unable to open trace directory.\n");
 567                 ret = -ENOENT;
 568                 goto error;
 569         }
 570
 571
 572         return 0;
 573
 574 error:
 575         return ret;
 576 }
 577
 578 struct trace_descriptor *ctf_open_trace(const char *path, int flags)
 579 {
 580         struct ctf_trace *td;
 581         int ret;
 582
 583         td = g_new0(struct ctf_trace, 1);
 584
 585         switch (flags & O_ACCMODE) {
 586         case O_RDONLY:
 587                 ret = ctf_open_trace_read(td, path, flags);
 588                 if (ret)
 589                         goto error;
 590                 break;
 591         case O_WRONLY:
 592                 fprintf(stdout, "[error] Opening CTF traces for output is not supported yet.\n");
 593                 goto error;
 594 #if 0
 595                 ret = ctf_open_trace_write(td, path, flags);
 596                 if (ret)
 597                         goto error;
 598 #endif //0
 599                 break;
 600         default:
 601                 fprintf(stdout, "[error] Incorrect open flags.\n");
 602                 goto error;
 603         }
 604
 605         return &td->parent;
 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         ctf_fini_pos(&file_stream->pos);
 615         close(file_stream->pos.fd);
 616 }
 617
 618 void ctf_close_trace(struct trace_descriptor *tdp)
 619 {
 620         struct ctf_trace *td = container_of(tdp, struct ctf_trace, parent);
 621         int i;
 622
 623         if (td->streams) {
 624                 for (i = 0; i < td->streams->len; i++) {
 625                         struct ctf_stream *stream;
 626                         int j;
 627                         stream = g_ptr_array_index(td->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(stream->files, j);
 631                                 ctf_close_file_stream(file_stream);
 632                         }
 633
 634                 }
 635                 g_ptr_array_free(td->streams, TRUE);
 636         }
 637         closedir(td->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 */