/*
 * 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/vdo-releases/aluminum/src/c++/vdo/kernel/bufferPool.h#1 $
 */
#ifndef BUFFERPOOL_H
#define BUFFERPOOL_H

/*
 * We need bug.h because in 3.10, kernel.h (indirectly) defines
 * ARRAY_SIZE as a macro which (indirectly and conditionally) uses
 * BUILD_BUG_ON_ZERO, which is defined in bug.h, which is *not*
 * included. In earlier versions like 3.2 it Just Worked.
 */
#include <linux/bug.h>
#include <linux/kernel.h>
#include <linux/types.h>

typedef struct bufferPool BufferPool;

typedef int BufferAllocateFunction(void *poolData, void **dataPtr);
typedef void BufferFreeFunction(void *poolData, void *data);
typedef void BufferDumpFunction(void *poolData, void *data);

/**
 * Creates a generic pool of buffer data. The elements in the pool are
 * allocated up front and placed on a free list, which manages the
 * reuse of the individual buffers in the pool.
 *
 * @param [in]  poolName         Name of the pool
 * @param [in]  size             The number of elements to create for this pool
 * @param [in]  allocateFunction The function to call to create the actual data
 *                               for each element
 * @param [in]  freeFunction     The function to call to free the actual data
 *                               for each element
 * @param [in]  dumpFunction     The function to call to dump the actual data
 *                               for each element into the log
 * @param [in]  poolData         A pointer to the pool's associated data
 * @param [out] poolPtr          A pointer to hold the pool that was created
 *
 * @return a success or error code
 */
int makeBufferPool(const char              *poolName,
                   unsigned int             size,
                   BufferAllocateFunction  *allocateFunction,
                   BufferFreeFunction      *freeFunction,
                   BufferDumpFunction      *dumpFunction,
                   void                    *poolData,
                   BufferPool             **poolPtr)
  __attribute__((warn_unused_result));

/**
 * Free a buffer pool and null out the reference to it. This will free
 * all the elements of the pool as well.
 *
 * @param [in]  poolPtr   The reference to the pool to free
 **/
void freeBufferPool(BufferPool **poolPtr);

/**
 * Dump a buffer pool to the log.
 *
 * @param [in] pool          The buffer pool to allocate from
 * @param [in] dumpElements  True for complete output, or false for a
 *                           one-line summary
 **/
void dumpBufferPool(BufferPool *pool, bool dumpElements);

/**
 * Acquires a free buffer from the free list of the pool and
 * returns it's associated data.
 *
 * @param [in]  pool      The buffer pool to allocate from
 * @param [out] dataPtr   A pointer to hold the buffer data
 *
 * @return a success or error code
 */
int allocBufferFromPool(BufferPool *pool, void **dataPtr)
  __attribute__((warn_unused_result));

/**
 * Returns a buffer to the free list of a pool
 *
 * @param [in] pool   The buffer pool to return the buffer to
 * @param [in] data   The buffer data to return
 */
void freeBufferToPool(BufferPool *pool, void *data);

/**
 * Returns a set of buffers to the free list of a pool
 *
 * @param [in] pool   The buffer pool to return the buffer to
 * @param [in] data   The buffer data to return
 * @param [in] count  Number of entries in the data array
 */
void freeBuffersToPool(BufferPool *pool, void **data, int count);

/**
 * Control structure for freeing (releasing back to the pool) pointers
 * in batches.
 *
 * Since the objects stored in a buffer pool are completely opaque,
 * some external data structure is needed to manage a collection of
 * them. This is a simple helper for doing that, since we're freeing
 * batches of objects in a couple different places. Within the pool
 * itself there's a pair of linked lists, but getting at them requires
 * the locking that we're trying to minimize.
 *
 * We collect pointers until the array is full or until there are no
 * more available, and we call freeBuffersToPool to release a batch
 * all at once.
 **/
typedef struct freeBufferPointers {
  BufferPool *pool;
  int         index;
  void       *pointers[30]; // size is arbitrary
} FreeBufferPointers;

/**
 * Initialize the control structure for batching buffer pointers to be
 * released to their pool.
 *
 * @param [out] fbp   The (caller-allocated) control structure
 * @param [in]  pool  The buffer pool to return objects to.
 **/
static inline void initFreeBufferPointers(FreeBufferPointers *fbp,
                                          BufferPool         *pool)
{
  fbp->index = 0;
  fbp->pool  = pool;
}

/**
 * Release any buffers left in the collection.
 *
 * @param [in]  fbp  The control structure
 **/
static inline void freeBufferPointers(FreeBufferPointers *fbp)
{
  freeBuffersToPool(fbp->pool, fbp->pointers, fbp->index);
  fbp->index = 0;
}

/**
 * Add another buffer pointer to the collection, and if we're full,
 * release the whole batch to the pool.
 *
 * @param [in]  fbp      The control structure
 * @param [in]  pointer  The buffer pointer to release
 **/
static inline void addFreeBufferPointer(FreeBufferPointers *fbp,
                                        void               *pointer)
{
  fbp->pointers[fbp->index] = pointer;
  fbp->index++;
  if (fbp->index == ARRAY_SIZE(fbp->pointers)) {
    freeBufferPointers(fbp);
  }
}

#endif /* BUFFERPOOL_H */