datastore.c

   1 /*
   2  * This file is part of the sigrok project.
   3  *
   4  * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
   5  *
   6  * This program is free software: you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation, either version 3 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #include <stdlib.h>
  21 #include <stdint.h>
  22 #include <string.h>
  23 #include <glib.h>
  24 #include "libsigrok.h"
  25 #include "libsigrok-internal.h"
  26
  27 /**
  28  * @defgroup grp_datastore Datastore
  29  *
  30  * Creating, using, or destroying libsigrok datastores.
  31  *
  32  * @{
  33  */
  34
  35 static gpointer new_chunk(struct sr_datastore **ds);
  36
  37 /**
  38  * Create a new datastore with the specified unit size.
  39  *
  40  * The unit size is fixed once the datastore is created, and cannot be
  41  * changed later on, neither can data be added to the datastore with
  42  * different unit sizes later.
  43  *
  44  * It is the caller's responsibility to free the allocated memory of the
  45  * datastore via the sr_datastore_destroy() function, if no longer needed.
  46  *
  47  * @todo Unitsize should probably be unsigned int or uint32_t or similar.
  48  * @todo This function should have a 'chunksize' parameter, and
  49  *       struct sr_datastore a 'chunksize' field.
  50  *
  51  * @param unitsize The unit size (>= 1) to be used for this datastore.
  52  * @param ds Pointer to a variable which will hold the newly created
  53  *           datastore structure.
  54  *
  55  * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
  56  *         or SR_ERR_ARG upon invalid arguments. If something other than SR_OK
  57  *         is returned, the value of 'ds' is undefined.
  58  */
  59 SR_API int sr_datastore_new(int unitsize, struct sr_datastore **ds)
  60 {
  61         if (!ds) {
  62                 sr_err("ds: %s: ds was NULL", __func__);
  63                 return SR_ERR_ARG;
  64         }
  65
  66         if (unitsize <= 0) {
  67                 sr_err("ds: %s: unitsize was %d, but it must be >= 1",
  68                        __func__, unitsize);
  69                 return SR_ERR_ARG;
  70         }
  71
  72         if (!(*ds = g_try_malloc(sizeof(struct sr_datastore)))) {
  73                 sr_err("ds: %s: ds malloc failed", __func__);
  74                 return SR_ERR_MALLOC;
  75         }
  76
  77         (*ds)->ds_unitsize = unitsize;
  78         (*ds)->num_units = 0;
  79         (*ds)->chunklist = NULL;
  80
  81         return SR_OK;
  82 }
  83
  84 /**
  85  * Destroy the specified datastore and free the memory used by it.
  86  *
  87  * This will free the memory used by the data in the datastore's 'chunklist',
  88  * by the chunklist data structure itself, and by the datastore struct.
  89  *
  90  * @param ds The datastore to destroy.
  91  *
  92  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
  93  */
  94 SR_API int sr_datastore_destroy(struct sr_datastore *ds)
  95 {
  96         GSList *chunk;
  97
  98         if (!ds) {
  99                 sr_err("ds: %s: ds was NULL", __func__);
 100                 return SR_ERR_ARG;
 101         }
 102
 103         for (chunk = ds->chunklist; chunk; chunk = chunk->next)
 104                 g_free(chunk->data);
 105         g_slist_free(ds->chunklist);
 106         g_free(ds);
 107         ds = NULL;
 108
 109         return SR_OK;
 110 }
 111
 112 /**
 113  * Append some data to the specified datastore.
 114  *
 115  * @todo More elaborate function description.
 116  * @todo This function should use the (not yet available) 'chunksize' field
 117  *       of struct sr_datastore (instead of hardcoding DATASTORE_CHUNKSIZE).
 118  * @todo in_unitsize and probelist are unused?
 119  * @todo A few of the parameters can be const.
 120  * @todo Ideally, 'ds' should be unmodified upon errors.
 121  * @todo Should 0 be allowed as length?
 122  * @todo Specify/document the data format of the 'data' parameter.
 123  *
 124  * @param ds Pointer to the datastore which shall receive the data.
 125  *           Must not be NULL.
 126  * @param data Pointer to the memory buffer containing the data to add.
 127  *             Must not be NULL.
 128  * @param length Length of the data to add (in number of bytes).
 129  * @param in_unitsize The unit size (>= 1) of the input data.
 130  * @param probelist Pointer to a list of integers (probe numbers). The probe
 131  *                  numbers in this list are 1-based, i.e. the first probe
 132  *                  is expected to be numbered 1 (not 0!). Must not be NULL.
 133  *
 134  * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
 135  *         or SR_ERR_ARG upon invalid arguments. If something other than SR_OK
 136  *         is returned, the value/state of 'ds' is undefined.
 137  */
 138 SR_API int sr_datastore_put(struct sr_datastore *ds, void *data,
 139                 unsigned int length, int in_unitsize, const int *probelist)
 140 {
 141         unsigned int stored;
 142         int capacity, size, num_chunks, chunk_bytes_free, chunk_offset;
 143         gpointer chunk;
 144
 145         if (!ds) {
 146                 sr_err("ds: %s: ds was NULL", __func__);
 147                 return SR_ERR_ARG;
 148         }
 149
 150         /* Unitsize must not be 0, we'll divide by 0 otherwise. */
 151         if (ds->ds_unitsize == 0) {
 152                 sr_err("ds: %s: ds->ds_unitsize was 0", __func__);
 153                 return SR_ERR_ARG;
 154         }
 155
 156         if (!data) {
 157                 sr_err("ds: %s: data was NULL", __func__);
 158                 return SR_ERR_ARG;
 159         }
 160
 161         if (in_unitsize < 1) {
 162                 sr_err("ds: %s: in_unitsize was %d, but it must be >= 1",
 163                        __func__, in_unitsize);
 164                 return SR_ERR_ARG;
 165         }
 166
 167         if (!probelist) {
 168                 sr_err("ds: %s: probelist was NULL", __func__);
 169                 return SR_ERR_ARG;
 170         }
 171
 172         /* Get the last chunk in the list, or create a new one if needed. */
 173         if (ds->chunklist == NULL) {
 174                 if (!(chunk = new_chunk(&ds))) {
 175                         sr_err("ds: %s: couldn't allocate new chunk", __func__);
 176                         return SR_ERR_MALLOC;
 177                 }
 178         } else {
 179                 chunk = g_slist_last(ds->chunklist)->data;
 180         }
 181
 182         /* Get/calculate number of chunks, free space, etc. */
 183         num_chunks = g_slist_length(ds->chunklist);
 184         capacity = (num_chunks * DATASTORE_CHUNKSIZE);
 185         chunk_bytes_free = capacity - (ds->ds_unitsize * ds->num_units);
 186         chunk_offset = capacity - (DATASTORE_CHUNKSIZE * (num_chunks - 1))
 187                        - chunk_bytes_free;
 188
 189         stored = 0;
 190         while (stored < length) {
 191                 /* No more free space left, allocate a new chunk. */
 192                 if (chunk_bytes_free == 0) {
 193                         if (!(chunk = new_chunk(&ds))) {
 194                                 sr_err("ds: %s: couldn't allocate new chunk",
 195                                        __func__);
 196                                 return SR_ERR_MALLOC;
 197                         }
 198                         chunk_bytes_free = DATASTORE_CHUNKSIZE;
 199                         chunk_offset = 0;
 200                 }
 201
 202                 if (length - stored > (unsigned int)chunk_bytes_free)
 203                         size = chunk_bytes_free;
 204                 else
 205                         /* Last part, won't fill up this chunk. */
 206                         size = length - stored;
 207
 208                 memcpy(chunk + chunk_offset, data + stored, size);
 209                 chunk_bytes_free -= size;
 210                 stored += size;
 211         }
 212
 213         ds->num_units += stored / ds->ds_unitsize;
 214
 215         return SR_OK;
 216 }
 217
 218 /**
 219  * Allocate a new memory chunk, append it to the datastore's chunklist.
 220  *
 221  * The newly allocated chunk is added to the datastore's chunklist by this
 222  * function, and the return value additionally points to the new chunk.
 223  *
 224  * The allocated memory is guaranteed to be cleared.
 225  *
 226  * @todo This function should use the datastore's 'chunksize' field instead
 227  *       of hardcoding DATASTORE_CHUNKSIZE.
 228  * @todo Return int, so we can return SR_OK / SR_ERR_ARG / SR_ERR_MALLOC?
 229  *
 230  * @param ds Pointer to a variable which holds the datastore structure.
 231  *           Must not be NULL. The contents of 'ds' are modified in-place.
 232  *
 233  * @return Pointer to the newly allocated chunk, or NULL upon failure.
 234  */
 235 static gpointer new_chunk(struct sr_datastore **ds)
 236 {
 237         gpointer chunk;
 238
 239         /* Note: Caller checked that ds != NULL. */
 240
 241         chunk = g_try_malloc0(DATASTORE_CHUNKSIZE * (*ds)->ds_unitsize);
 242         if (!chunk) {
 243                 sr_err("ds: %s: chunk malloc failed (ds_unitsize was %u)",
 244                        __func__, (*ds)->ds_unitsize);
 245                 return NULL; /* TODO: SR_ERR_MALLOC later? */
 246         }
 247
 248         (*ds)->chunklist = g_slist_append((*ds)->chunklist, chunk);
 249
 250         return chunk; /* TODO: SR_OK later? */
 251 }
 252
 253 /** @} */