epan/emem.c

   1 /* emem.c
   2  * Ethereal memory management and garbage collection functions
   3  * Ronnie Sahlberg 2005
   4  *
   5  * $Id$
   6  *
   7  * Ethereal - Network traffic analyzer
   8  * By Gerald Combs <gerald@ethereal.com>
   9  * Copyright 1998 Gerald Combs
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation; either version 2
  14  * of the License, or (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, write to the Free Software
  23  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  24  */
  25 #ifdef HAVE_CONFIG_H
  26 #include "config.h"
  27 #endif
  28
  29 #include <stdio.h>
  30 #include <stdlib.h>
  31 #include <string.h>
  32 #include <stdarg.h>
  33
  34 #include <time.h>
  35 #ifdef HAVE_SYS_TIME_H
  36 #include <sys/time.h>
  37 #endif
  38
  39 #ifdef HAVE_UNISTD_H
  40 #include <unistd.h>
  41 #endif
  42
  43 #ifdef _WIN32
  44 #include <windows.h>    /* VirtualAlloc, VirtualProtect */
  45 #include <process.h>    /* getpid */
  46 #endif
  47
  48 #include <glib.h>
  49 #include <proto.h>
  50 #include "emem.h"
  51 #include <wiretap/file_util.h>
  52
  53 /* Add guard pages at each end of our allocated memory */
  54 #if defined(HAVE_SYSCONF) && defined(HAVE_MMAP) && defined(HAVE_MPROTECT) && defined(HAVE_STDINT_H)
  55 #include <stdint.h>
  56 #include <sys/types.h>
  57 #include <sys/mman.h>
  58 #define USE_GUARD_PAGES 1
  59 #endif
  60
  61 /* When required, allocate more memory from the OS in this size chunks */
  62 #define EMEM_PACKET_CHUNK_SIZE 10485760
  63
  64 /* The maximum number of allocations per chunk */
  65 #define EMEM_ALLOCS_PER_CHUNK (EMEM_PACKET_CHUNK_SIZE / 512)
  66
  67 /*
  68  * Tools like Valgrind and ElectricFence don't work well with memchunks.
  69  * Uncomment the defines below to make {ep|se}_alloc() allocate each
  70  * object individually.
  71  */
  72 /* #define EP_DEBUG_FREE 1 */
  73 /* #define SE_DEBUG_FREE 1 */
  74
  75 #if GLIB_MAJOR_VERSION >= 2
  76 GRand   *rand_state = NULL;
  77 #endif
  78
  79 #define EMEM_CANARY_SIZE 8
  80 #define EMEM_CANARY_DATA_SIZE (EMEM_CANARY_SIZE * 2 - 1)
  81 guint8  ep_canary[EMEM_CANARY_DATA_SIZE], se_canary[EMEM_CANARY_DATA_SIZE];
  82
  83 typedef struct _emem_chunk_t {
  84         struct _emem_chunk_t *next;
  85         unsigned int    amount_free_init;
  86         unsigned int    amount_free;
  87         unsigned int    free_offset_init;
  88         unsigned int    free_offset;
  89         char *buf;
  90 #if ! defined(EP_DEBUG_FREE) && ! defined(SE_DEBUG_FREE)
  91         unsigned int    c_count;
  92         void            *canary[EMEM_ALLOCS_PER_CHUNK];
  93         guint8          cmp_len[EMEM_ALLOCS_PER_CHUNK];
  94 #endif
  95 } emem_chunk_t;
  96
  97 typedef struct _emem_header_t {
  98   emem_chunk_t *free_list;
  99   emem_chunk_t *used_list;
 100 } emem_header_t;
 101
 102 static emem_header_t ep_packet_mem;
 103 static emem_header_t se_packet_mem;
 104
 105 /*
 106  * Set a canary value to be placed between memchunks.
 107  */
 108
 109 void
 110 emem_canary(guint8 *canary) {
 111         int i;
 112
 113         /* First, use GLib's random function if we have it */
 114 #if GLIB_MAJOR_VERSION >= 2
 115         if (rand_state == NULL) {
 116                 rand_state = g_rand_new();
 117         }
 118         for (i = 0; i < EMEM_CANARY_DATA_SIZE; i ++) {
 119                 canary[i] = (guint8) g_rand_int(rand_state);
 120         }
 121         return;
 122 #else
 123         FILE *fp;
 124         size_t sz;
 125         /* Try /dev/urandom */
 126         if ((fp = eth_fopen("/dev/urandom", "r")) != NULL) {
 127                 sz = fread(canary, EMEM_CANARY_DATA_SIZE, 1, fp);
 128                 fclose(fp);
 129                 if (sz == EMEM_CANARY_SIZE) {
 130                         return;
 131                 }
 132         }
 133
 134         /* Our last resort */
 135         srandom(time(NULL) | getpid());
 136         for (i = 0; i < EMEM_CANARY_DATA_SIZE; i ++) {
 137                 canary[i] = (guint8) random();
 138         }
 139         return;
 140 #endif /* GLIB_MAJOR_VERSION >= 2 */
 141 }
 142
 143 /*
 144  * Given an allocation size, return the amount of padding needed for
 145  * the canary value.
 146  */
 147 static guint8
 148 emem_canary_pad (size_t allocation) {
 149         guint8 pad;
 150
 151         pad = EMEM_CANARY_SIZE - (allocation % EMEM_CANARY_SIZE);
 152         if (pad < EMEM_CANARY_SIZE)
 153                 pad += EMEM_CANARY_SIZE;
 154
 155         return pad;
 156 }
 157
 158 /* Initialize the packet-lifetime memory allocation pool.
 159  * This function should be called only once when Ethereal or Tethereal starts
 160  * up.
 161  */
 162 void
 163 ep_init_chunk(void)
 164 {
 165         ep_packet_mem.free_list=NULL;
 166         ep_packet_mem.used_list=NULL;
 167
 168         emem_canary(ep_canary);
 169 }
 170 /* Initialize the capture-lifetime memory allocation pool.
 171  * This function should be called only once when Ethereal or Tethereal starts
 172  * up.
 173  */
 174 void
 175 se_init_chunk(void)
 176 {
 177         se_packet_mem.free_list=NULL;
 178         se_packet_mem.used_list=NULL;
 179
 180         emem_canary(se_canary);
 181 }
 182
 183 static void
 184 emem_create_chunk(emem_chunk_t **free_list) {
 185 #if defined (_WIN32)
 186         SYSTEM_INFO sysinfo;
 187         int pagesize;
 188         BOOL ret;
 189         char *buf_end, *prot1, *prot2;
 190         DWORD oldprot;
 191 #elif defined(USE_GUARD_PAGES)
 192         intptr_t pagesize = sysconf(_SC_PAGESIZE);
 193         int ret;
 194         char *buf_end, *prot1, *prot2;
 195 #endif
 196         /* we dont have any free data, so we must allocate a new one */
 197         if(!*free_list){
 198                 emem_chunk_t *npc;
 199                 npc = g_malloc(sizeof(emem_chunk_t));
 200                 npc->next = NULL;
 201                 npc->c_count = 0;
 202                 *free_list = npc;
 203 #if defined (_WIN32)
 204                 /*
 205                  * MSDN documents VirtualAlloc/VirtualProtect at
 206                  * http://msdn.microsoft.com/library/en-us/memory/base/creating_guard_pages.asp
 207                  */
 208                 GetSystemInfo(&sysinfo);
 209                 pagesize = sysinfo.dwPageSize;
 210
 211                 /* XXX - is MEM_COMMIT|MEM_RESERVE correct? */
 212                 npc->buf = VirtualAlloc(NULL, EMEM_PACKET_CHUNK_SIZE,
 213                         MEM_COMMIT|MEM_RESERVE, PAGE_READWRITE);
 214                 g_assert(npc->buf != NULL);
 215                 buf_end = npc->buf + EMEM_PACKET_CHUNK_SIZE;
 216
 217                 /* Align our guard pages on page-sized boundaries */
 218                 prot1 = (char *) ((((int) npc->buf + pagesize - 1) / pagesize) * pagesize);
 219                 prot2 = (char *) ((((int) buf_end - (1 * pagesize)) / pagesize) * pagesize);
 220
 221                 ret = VirtualProtect(prot1, pagesize, PAGE_NOACCESS, &oldprot);
 222                 g_assert(ret == TRUE);
 223                 ret = VirtualProtect(prot2, pagesize, PAGE_NOACCESS, &oldprot);
 224                 g_assert(ret == TRUE);
 225
 226                 npc->amount_free_init = prot2 - prot1 - pagesize;
 227                 npc->amount_free = npc->amount_free_init;
 228                 npc->free_offset_init = (prot1 - npc->buf) + pagesize;
 229                 npc->free_offset = npc->free_offset_init;
 230
 231 #elif defined(USE_GUARD_PAGES)
 232                 npc->buf = mmap(NULL, EMEM_PACKET_CHUNK_SIZE,
 233                         PROT_READ|PROT_WRITE, MAP_ANON|MAP_PRIVATE, -1, 0);
 234                 g_assert(npc->buf != MAP_FAILED);
 235                 buf_end = npc->buf + EMEM_PACKET_CHUNK_SIZE;
 236
 237                 /* Align our guard pages on page-sized boundaries */
 238                 prot1 = (char *) ((((intptr_t) npc->buf + pagesize - 1) / pagesize) * pagesize);
 239                 prot2 = (char *) ((((intptr_t) buf_end - (1 * pagesize)) / pagesize) * pagesize);
 240                 ret = mprotect(prot1, pagesize, PROT_NONE);
 241                 g_assert(ret != -1);
 242                 ret = mprotect(prot2, pagesize, PROT_NONE);
 243                 g_assert(ret != -1);
 244
 245                 npc->amount_free_init = prot2 - prot1 - pagesize;
 246                 npc->amount_free = npc->amount_free_init;
 247                 npc->free_offset_init = (prot1 - npc->buf) + pagesize;
 248                 npc->free_offset = npc->free_offset_init;
 249
 250 #else /* Is there a draft in here? */
 251                 npc->amount_free_init = EMEM_PACKET_CHUNK_SIZE;
 252                 npc->amount_free = npc->amount_free_init;
 253                 npc->free_offset_init = 0;
 254                 npc->free_offset = npc->free_offset_init;
 255                 npc->buf = g_malloc(EMEM_PACKET_CHUNK_SIZE);
 256 #endif /* USE_GUARD_PAGES */
 257         }
 258 }
 259
 260 /* allocate 'size' amount of memory with an allocation lifetime until the
 261  * next packet.
 262  */
 263 void *
 264 ep_alloc(size_t size)
 265 {
 266         void *buf, *cptr;
 267         guint8 pad = emem_canary_pad(size);
 268         emem_chunk_t *free_list;
 269
 270 #ifndef EP_DEBUG_FREE
 271         /* Round up to an 8 byte boundary.  Make sure we have at least
 272          * 8 pad bytes for our canary.
 273          */
 274         size += pad;
 275
 276         /* make sure we dont try to allocate too much (arbitrary limit) */
 277         DISSECTOR_ASSERT(size<(EMEM_PACKET_CHUNK_SIZE>>2));
 278
 279         emem_create_chunk(&ep_packet_mem.free_list);
 280
 281         /* oops, we need to allocate more memory to serve this request
 282          * than we have free. move this node to the used list and try again
 283          */
 284         if(size>ep_packet_mem.free_list->amount_free || ep_packet_mem.free_list->c_count >= EMEM_ALLOCS_PER_CHUNK){
 285                 emem_chunk_t *npc;
 286                 npc=ep_packet_mem.free_list;
 287                 ep_packet_mem.free_list=ep_packet_mem.free_list->next;
 288                 npc->next=ep_packet_mem.used_list;
 289                 ep_packet_mem.used_list=npc;
 290         }
 291
 292         emem_create_chunk(&ep_packet_mem.free_list);
 293
 294         free_list = ep_packet_mem.free_list;
 295
 296         buf = free_list->buf + free_list->free_offset;
 297
 298         free_list->amount_free -= size;
 299         free_list->free_offset += size;
 300
 301         cptr = (char *)buf + size - pad;
 302         memcpy(cptr, &ep_canary, pad);
 303         free_list->canary[free_list->c_count] = cptr;
 304         free_list->cmp_len[free_list->c_count] = pad;
 305         free_list->c_count++;
 306
 307 #else /* EP_DEBUG_FREE */
 308         emem_chunk_t *npc;
 309
 310         npc=g_malloc(sizeof(emem_chunk_t));
 311         npc->next=ep_packet_mem.used_list;
 312         npc->amount_free=size;
 313         npc->free_offset=0;
 314         npc->buf=g_malloc(size);
 315         buf = npc->buf;
 316         ep_packet_mem.used_list=npc;
 317 #endif /* EP_DEBUG_FREE */
 318
 319         return buf;
 320 }
 321 /* allocate 'size' amount of memory with an allocation lifetime until the
 322  * next capture.
 323  */
 324 void *
 325 se_alloc(size_t size)
 326 {
 327         void *buf, *cptr;
 328         guint8 pad = emem_canary_pad(size);
 329         emem_chunk_t *free_list;
 330
 331 #ifndef SE_DEBUG_FREE
 332         /* Round up to an 8 byte boundary.  Make sure we have at least
 333          * 8 pad bytes for our canary.
 334          */
 335         size += pad;
 336
 337         /* make sure we dont try to allocate too much (arbitrary limit) */
 338         DISSECTOR_ASSERT(size<(EMEM_PACKET_CHUNK_SIZE>>2));
 339
 340         emem_create_chunk(&se_packet_mem.free_list);
 341
 342         /* oops, we need to allocate more memory to serve this request
 343          * than we have free. move this node to the used list and try again
 344          */
 345         if(size>se_packet_mem.free_list->amount_free || se_packet_mem.free_list->c_count >= EMEM_ALLOCS_PER_CHUNK){
 346                 emem_chunk_t *npc;
 347                 npc=se_packet_mem.free_list;
 348                 se_packet_mem.free_list=se_packet_mem.free_list->next;
 349                 npc->next=se_packet_mem.used_list;
 350                 se_packet_mem.used_list=npc;
 351         }
 352
 353         emem_create_chunk(&se_packet_mem.free_list);
 354
 355         free_list = se_packet_mem.free_list;
 356
 357         buf = free_list->buf + free_list->free_offset;
 358
 359         free_list->amount_free -= size;
 360         free_list->free_offset += size;
 361
 362         cptr = (char *)buf + size - pad;
 363         memcpy(cptr, &se_canary, pad);
 364         free_list->canary[free_list->c_count] = cptr;
 365         free_list->cmp_len[free_list->c_count] = pad;
 366         free_list->c_count++;
 367
 368 #else /* SE_DEBUG_FREE */
 369         emem_chunk_t *npc;
 370
 371         npc=g_malloc(sizeof(emem_chunk_t));
 372         npc->next=se_packet_mem.used_list;
 373         npc->amount_free=size;
 374         npc->free_offset=0;
 375         npc->buf=g_malloc(size);
 376         buf = npc->buf;
 377         se_packet_mem.used_list=npc;
 378 #endif /* SE_DEBUG_FREE */
 379
 380         return buf;
 381 }
 382
 383
 384 void* ep_alloc0(size_t size) {
 385         return memset(ep_alloc(size),'\0',size);
 386 }
 387
 388 gchar* ep_strdup(const gchar* src) {
 389         guint len = strlen(src);
 390         gchar* dst;
 391
 392         dst = strncpy(ep_alloc(len+1), src, len);
 393
 394         dst[len] = '\0';
 395
 396         return dst;
 397 }
 398
 399 gchar* ep_strndup(const gchar* src, size_t len) {
 400         gchar* dst = ep_alloc(len+1);
 401         guint i;
 402
 403         for (i = 0; src[i] && i < len; i++)
 404                 dst[i] = src[i];
 405
 406         dst[i] = '\0';
 407
 408         return dst;
 409 }
 410
 411 void* ep_memdup(const void* src, size_t len) {
 412         return memcpy(ep_alloc(len), src, len);
 413 }
 414
 415 gchar* ep_strdup_vprintf(const gchar* fmt, va_list ap) {
 416         va_list ap2;
 417         guint len;
 418         gchar* dst;
 419
 420         G_VA_COPY(ap2, ap);
 421
 422         len = g_printf_string_upper_bound(fmt, ap);
 423
 424         dst = ep_alloc(len+1);
 425         g_vsnprintf (dst, len, fmt, ap2);
 426         va_end(ap2);
 427
 428         return dst;
 429 }
 430
 431 gchar* ep_strdup_printf(const gchar* fmt, ...) {
 432         va_list ap;
 433         gchar* dst;
 434
 435         va_start(ap,fmt);
 436         dst = ep_strdup_vprintf(fmt, ap);
 437         va_end(ap);
 438         return dst;
 439 }
 440
 441 gchar** ep_strsplit(const gchar* string, const gchar* sep, int max_tokens) {
 442         gchar* splitted;
 443         gchar* s;
 444         guint tokens;
 445         guint str_len;
 446         guint sep_len;
 447         guint i;
 448         gchar** vec;
 449         enum { AT_START, IN_PAD, IN_TOKEN } state;
 450         guint curr_tok = 0;
 451
 452         if ( ! string
 453                  || ! sep
 454                  || ! sep[0])
 455                 return NULL;
 456
 457         s = splitted = ep_strdup(string);
 458         str_len = strlen(splitted);
 459         sep_len = strlen(sep);
 460
 461         if (max_tokens < 1) max_tokens = INT_MAX;
 462
 463         tokens = 1;
 464
 465
 466         while (tokens <= (guint)max_tokens && ( s = strstr(s,sep) )) {
 467                 tokens++;
 468
 469                 for(i=0; i < sep_len; i++ )
 470                         s[i] = '\0';
 471
 472                 s += sep_len;
 473
 474         }
 475
 476         vec = ep_alloc_array(gchar*,tokens+1);
 477         state = AT_START;
 478
 479         for (i=0; i< str_len; i++) {
 480                 switch(state) {
 481                         case AT_START:
 482                                 switch(splitted[i]) {
 483                                         case '\0':
 484                                                 state  = IN_PAD;
 485                                                 continue;
 486                                         default:
 487                                                 vec[curr_tok] = &(splitted[i]);
 488                                                 curr_tok++;
 489                                                 state = IN_TOKEN;
 490                                                 continue;
 491                                 }
 492                         case IN_TOKEN:
 493                                 switch(splitted[i]) {
 494                                         case '\0':
 495                                                 state = IN_PAD;
 496                                         default:
 497                                                 continue;
 498                                 }
 499                         case IN_PAD:
 500                                 switch(splitted[i]) {
 501                                         default:
 502                                                 vec[curr_tok] = &(splitted[i]);
 503                                                 curr_tok++;
 504                                                 state = IN_TOKEN;
 505                                         case '\0':
 506                                                 continue;
 507                                 }
 508                 }
 509         }
 510
 511         vec[curr_tok] = NULL;
 512
 513         return vec;
 514 }
 515
 516
 517
 518 void* se_alloc0(size_t size) {
 519         return memset(se_alloc(size),'\0',size);
 520 }
 521
 522 /* If str is NULL, just return the string "<NULL>" so that the callers dont
 523  * have to bother checking it.
 524  */
 525 gchar* se_strdup(const gchar* src) {
 526         guint len;
 527         gchar* dst;
 528
 529         if(!src){
 530                 return "<NULL>";
 531         }
 532
 533         len = strlen(src);
 534         dst = strncpy(se_alloc(len+1), src, len);
 535
 536         dst[len] = '\0';
 537
 538         return dst;
 539 }
 540
 541 gchar* se_strndup(const gchar* src, size_t len) {
 542         gchar* dst = se_alloc(len+1);
 543         guint i;
 544
 545         for (i = 0; src[i] && i < len; i++)
 546                 dst[i] = src[i];
 547
 548         dst[i] = '\0';
 549
 550         return dst;
 551 }
 552
 553 void* se_memdup(const void* src, size_t len) {
 554         return memcpy(se_alloc(len), src, len);
 555 }
 556
 557 gchar* se_strdup_vprintf(const gchar* fmt, va_list ap) {
 558         va_list ap2;
 559         guint len;
 560         gchar* dst;
 561
 562         G_VA_COPY(ap2, ap);
 563
 564         len = g_printf_string_upper_bound(fmt, ap);
 565
 566         dst = se_alloc(len+1);
 567         g_vsnprintf (dst, len, fmt, ap2);
 568         va_end(ap2);
 569
 570         return dst;
 571 }
 572
 573 gchar* se_strdup_printf(const gchar* fmt, ...) {
 574         va_list ap;
 575         gchar* dst;
 576
 577         va_start(ap,fmt);
 578         dst = se_strdup_vprintf(fmt, ap);
 579         va_end(ap);
 580         return dst;
 581 }
 582
 583 /* release all allocated memory back to the pool.
 584  */
 585 void
 586 ep_free_all(void)
 587 {
 588         emem_chunk_t *npc;
 589         guint i;
 590
 591         /* move all used chunks over to the free list */
 592         while(ep_packet_mem.used_list){
 593                 npc=ep_packet_mem.used_list;
 594                 ep_packet_mem.used_list=ep_packet_mem.used_list->next;
 595                 npc->next=ep_packet_mem.free_list;
 596                 ep_packet_mem.free_list=npc;
 597         }
 598
 599         /* clear them all out */
 600         npc = ep_packet_mem.free_list;
 601         while (npc != NULL) {
 602 #ifndef EP_DEBUG_FREE
 603                 for (i = 0; i < npc->c_count; i++) {
 604                         if (memcmp(npc->canary[i], &ep_canary, npc->cmp_len[i]) != 0)
 605                                 g_error("Per-packet memory corrupted.");
 606                 }
 607                 npc->c_count = 0;
 608                 npc->amount_free = npc->amount_free_init;
 609                 npc->free_offset = npc->free_offset_init;
 610                 npc = npc->next;
 611 #else /* EP_DEBUG_FREE */
 612                 emem_chunk_t *next = npc->next;
 613
 614                 g_free(npc->buf);
 615                 g_free(npc);
 616                 npc = next;
 617 #endif /* EP_DEBUG_FREE */
 618         }
 619
 620 #ifdef EP_DEBUG_FREE
 621         ep_init_chunk();
 622 #endif
 623 }
 624 /* release all allocated memory back to the pool.
 625  */
 626 void
 627 se_free_all(void)
 628 {
 629         emem_chunk_t *npc;
 630         guint i;
 631
 632         /* move all used chunks over to the free list */
 633         while(se_packet_mem.used_list){
 634                 npc=se_packet_mem.used_list;
 635                 se_packet_mem.used_list=se_packet_mem.used_list->next;
 636                 npc->next=se_packet_mem.free_list;
 637                 se_packet_mem.free_list=npc;
 638         }
 639
 640         /* clear them all out */
 641         npc = se_packet_mem.free_list;
 642         while (npc != NULL) {
 643 #ifndef SE_DEBUG_FREE
 644                 for (i = 0; i < npc->c_count; i++) {
 645                         if (memcmp(npc->canary[i], &se_canary, npc->cmp_len[i]) != 0)
 646                                 g_error("Per-session memory corrupted.");
 647                 }
 648                 npc->c_count = 0;
 649                 npc->amount_free = npc->amount_free_init;
 650                 npc->free_offset = npc->free_offset_init;
 651                 npc = npc->next;
 652 #else /* SE_DEBUG_FREE */
 653                 emem_chunk_t *next = npc->next;
 654
 655                 g_free(npc->buf);
 656                 g_free(npc);
 657                 npc = next;
 658 #endif /* SE_DEBUG_FREE */
 659         }
 660
 661 #ifdef SE_DEBUG_FREE
 662                 se_init_chunk();
 663 #endif
 664 }
 665
 666
 667 ep_stack_t ep_stack_new(void) {
 668     ep_stack_t s = ep_new(struct _ep_stack_frame_t*);
 669     *s = ep_new0(struct _ep_stack_frame_t);
 670     return s;
 671 }
 672
 673 /*  for ep_stack_t we'll keep the popped frames so we reuse them instead
 674 of allocating new ones.
 675 */
 676
 677
 678 void* ep_stack_push(ep_stack_t stack, void* data) {
 679     struct _ep_stack_frame_t* frame;
 680     struct _ep_stack_frame_t* head = (*stack);
 681
 682     if (head->above) {
 683         frame = head->above;
 684     } else {
 685        frame = ep_new(struct _ep_stack_frame_t);
 686        head->above = frame;
 687        frame->below = head;
 688        frame->above = NULL;
 689     }
 690
 691     frame->payload = data;
 692     (*stack) = frame;
 693
 694     return data;
 695 }
 696
 697 void* ep_stack_pop(ep_stack_t stack) {
 698
 699     if ((*stack)->below) {
 700         (*stack) = (*stack)->below;
 701         return (*stack)->above->payload;
 702     } else {
 703         return NULL;
 704     }
 705 }
 706