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