/*
 * Copyright (c) 2020 Red Hat, Inc.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA. 
 *
 * $Id: //eng/uds-releases/jasper/src/uds/memoryAlloc.h#2 $
 */

#ifndef MEMORY_ALLOC_H
#define MEMORY_ALLOC_H 1

#include <stdarg.h>

#include "compiler.h"
#include "cpu.h"
#include "memoryDefs.h"
#include "permassert.h"

/**
 * Allocate storage based on memory size and  alignment, logging an error if
 * the allocation fails. The memory will be zeroed.
 *
 * @param size   The size of an object
 * @param align  The required alignment
 * @param what   What is being allocated (for error logging)
 * @param ptr    A pointer to hold the allocated memory
 *
 * @return UDS_SUCCESS or an error code
 **/
int allocateMemory(size_t size, size_t align, const char *what, void *ptr)
  __attribute__((warn_unused_result));

/**
 * Free storage
 *
 * @param ptr  The memory to be freed
 **/
void freeMemory(void *ptr);

/**
 * Allocate storage based on element counts, sizes, and alignment.
 *
 * This is a generalized form of our allocation use case: It allocates
 * an array of objects, optionally preceded by one object of another
 * type (i.e., a struct with trailing variable-length array), with the
 * alignment indicated.
 *
 * Why is this inline?  The sizes and alignment will always be
 * constant, when invoked through the macros below, and often the
 * count will be a compile-time constant 1 or the number of extra
 * bytes will be a compile-time constant 0.  So at least some of the
 * arithmetic can usually be optimized away, and the run-time
 * selection between allocation functions always can.  In many cases,
 * it'll boil down to just a function call with a constant size.
 *
 * @param count   The number of objects to allocate
 * @param size    The size of an object
 * @param extra   The number of additional bytes to allocate
 * @param align   The required alignment
 * @param what    What is being allocated (for error logging)
 * @param ptr     A pointer to hold the allocated memory
 *
 * @return UDS_SUCCESS or an error code
 **/
static INLINE int doAllocation(size_t      count,
                               size_t      size,
                               size_t      extra,
                               size_t      align,
                               const char *what,
                               void       *ptr)
{
  size_t totalSize = count * size + extra;
  // Overflow check:
  if ((size > 0) && (count > ((SIZE_MAX - extra) / size))) {
    /*
     * This is kind of a hack: We rely on the fact that SIZE_MAX would
     * cover the entire address space (minus one byte) and thus the
     * system can never allocate that much and the call will always
     * fail.  So we can report an overflow as "out of memory" by asking
     * for "merely" SIZE_MAX bytes.
     */
    totalSize = SIZE_MAX;
  }

  return allocateMemory(totalSize, align, what, ptr);
}

/**
 * Reallocate dynamically allocated memory.  There are no alignment guarantees
 * for the reallocated memory.
 *
 * @param ptr      The memory to reallocate.
 * @param oldSize  The old size of the memory
 * @param size     The new size to allocate
 * @param what     What is being allocated (for error logging)
 * @param newPtr   A pointer to hold the reallocated pointer
 *
 * @return UDS_SUCCESS or an error code
 **/
int reallocateMemory(void       *ptr,
                     size_t      oldSize,
                     size_t      size,
                     const char *what,
                     void       *newPtr)
  __attribute__((warn_unused_result));

/**
 * Allocate one or more elements of the indicated type, logging an
 * error if the allocation fails. The memory will be zeroed.
 *
 * @param COUNT  The number of objects to allocate
 * @param TYPE   The type of objects to allocate.  This type determines the
 *               alignment of the allocated memory.
 * @param WHAT   What is being allocated (for error logging)
 * @param PTR    A pointer to hold the allocated memory
 *
 * @return UDS_SUCCESS or an error code
 **/
#define ALLOCATE(COUNT, TYPE, WHAT, PTR) \
  doAllocation(COUNT, sizeof(TYPE), 0, __alignof__(TYPE), WHAT, PTR)

/**
 * Allocate one object of an indicated type, followed by one or more
 * elements of a second type, logging an error if the allocation
 * fails. The memory will be zeroed.
 *
 * @param TYPE1  The type of the primary object to allocate.  This type
 *               determines the alignment of the allocated memory.
 * @param COUNT  The number of objects to allocate
 * @param TYPE2  The type of array objects to allocate
 * @param WHAT   What is being allocated (for error logging)
 * @param PTR    A pointer to hold the allocated memory
 *
 * @return UDS_SUCCESS or an error code
 **/
#define ALLOCATE_EXTENDED(TYPE1, COUNT, TYPE2, WHAT, PTR)             \
  __extension__ ({                                                    \
      TYPE1 **_ptr = (PTR);                                           \
      STATIC_ASSERT(__alignof__(TYPE1) >= __alignof__(TYPE2));        \
      int _result = doAllocation(COUNT, sizeof(TYPE2), sizeof(TYPE1), \
                                 __alignof__(TYPE1), WHAT, _ptr);     \
      _result;                                                        \
    })

/**
 * Free memory allocated with ALLOCATE().
 *
 * @param ptr    Pointer to the memory to free
 **/
static INLINE void FREE(void *ptr)
{
  freeMemory(ptr);
}

/**
 * Allocate memory starting on a cache line boundary, logging an error if the
 * allocation fails. The memory will be zeroed.
 *
 * @param size  The number of bytes to allocate
 * @param what  What is being allocated (for error logging)
 * @param ptr   A pointer to hold the allocated memory
 *
 * @return UDS_SUCCESS or an error code
 **/
__attribute__((warn_unused_result))
static INLINE int allocateCacheAligned(size_t      size,
                                       const char *what,
                                       void       *ptr)
{
  return allocateMemory(size, CACHE_LINE_BYTES, what, ptr);
}

/**
 * Duplicate a string.
 *
 * @param string    The string to duplicate
 * @param what      What is being allocated (for error logging)
 * @param newString A pointer to hold the duplicated string
 *
 * @return UDS_SUCCESS or an error code
 **/
int duplicateString(const char *string, const char *what, char **newString)
  __attribute__((warn_unused_result));

/**
 * Duplicate a buffer, logging an error if the allocation fails.
 *
 * @param ptr     The buffer to copy
 * @param size    The size of the buffer
 * @param what    What is being duplicated (for error logging)
 * @param dupPtr  A pointer to hold the allocated array
 *
 * @return UDS_SUCCESS or ENOMEM
 **/
int memdup(const void *ptr, size_t size, const char *what, void *dupPtr)
  __attribute__((warn_unused_result));

/**
 * Wrapper which permits freeing a const pointer.
 *
 * @param pointer  the pointer to be freed
 **/
static INLINE void freeConst(const void *pointer)
{
  union {
    const void *constP;
    void *notConst;
  } u = { .constP = pointer };
  FREE(u.notConst);
}

/**
 * Wrapper which permits freeing a volatile pointer.
 *
 * @param pointer  the pointer to be freed
 **/
static INLINE void freeVolatile(volatile void *pointer)
{
  union {
    volatile void *volP;
    void *notVol;
  } u = { .volP = pointer };
  FREE(u.notVol);
}

#endif /* MEMORY_ALLOC_H */