libsigrok
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
datastore.c
Go to the documentation of this file.
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 "sigrok.h"
25 #include "sigrok-internal.h"
26 
27 static gpointer new_chunk(struct sr_datastore **ds);
28 
29 /**
30  * Create a new datastore with the specified unit size.
31  *
32  * The unit size is fixed once the datastore is created, and cannot be
33  * changed later on, neither can data be added to the datastore with
34  * different unit sizes later.
35  *
36  * It is the caller's responsibility to free the allocated memory of the
37  * datastore via the sr_datastore_destroy() function, if no longer needed.
38  *
39  * TODO: Unitsize should probably be unsigned int or uint32_t or similar.
40  * TODO: This function should have a 'chunksize' parameter, and
41  * struct sr_datastore a 'chunksize' field.
42  *
43  * @param unitsize The unit size (>= 1) to be used for this datastore.
44  * @param ds Pointer to a variable which will hold the newly created
45  * datastore structure.
46  *
47  * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
48  * or SR_ERR_ARG upon invalid arguments. If something other than SR_OK
49  * is returned, the value of 'ds' is undefined.
50  */
51 SR_API int sr_datastore_new(int unitsize, struct sr_datastore **ds)
52 {
53  if (!ds) {
54  sr_err("ds: %s: ds was NULL", __func__);
55  return SR_ERR_ARG;
56  }
57 
58  if (unitsize <= 0) {
59  sr_err("ds: %s: unitsize was %d, but it must be >= 1",
60  __func__, unitsize);
61  return SR_ERR_ARG;
62  }
63 
64  if (!(*ds = g_try_malloc(sizeof(struct sr_datastore)))) {
65  sr_err("ds: %s: ds malloc failed", __func__);
66  return SR_ERR_MALLOC;
67  }
68 
69  (*ds)->ds_unitsize = unitsize;
70  (*ds)->num_units = 0;
71  (*ds)->chunklist = NULL;
72 
73  return SR_OK;
74 }
75 
76 /**
77  * Destroy the specified datastore and free the memory used by it.
78  *
79  * This will free the memory used by the data in the datastore's 'chunklist',
80  * by the chunklist data structure itself, and by the datastore struct.
81  *
82  * @param ds The datastore to destroy.
83  *
84  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
85  */
87 {
88  GSList *chunk;
89 
90  if (!ds) {
91  sr_err("ds: %s: ds was NULL", __func__);
92  return SR_ERR_ARG;
93  }
94 
95  for (chunk = ds->chunklist; chunk; chunk = chunk->next)
96  g_free(chunk->data);
97  g_slist_free(ds->chunklist);
98  g_free(ds);
99  ds = NULL;
100 
101  return SR_OK;
102 }
103 
104 /**
105  * Append some data to the specified datastore.
106  *
107  * TODO: More elaborate function description.
108  *
109  * TODO: This function should use the (not yet available) 'chunksize' field
110  * of struct sr_datastore (instead of hardcoding DATASTORE_CHUNKSIZE).
111  * TODO: in_unitsize and probelist are unused?
112  * TODO: A few of the parameters can be const.
113  * TODO: Ideally, 'ds' should be unmodified upon errors.
114  *
115  * @param ds Pointer to the datastore which shall receive the data.
116  * Must not be NULL.
117  * @param data Pointer to the memory buffer containing the data to add.
118  * Must not be NULL. TODO: Data format?
119  * @param length Length of the data to add (in number of bytes).
120  * TODO: Should 0 be allowed as length?
121  * @param in_unitsize The unit size (>= 1) of the input data.
122  * @param probelist Pointer to a list of integers (probe numbers). The probe
123  * numbers in this list are 1-based, i.e. the first probe
124  * is expected to be numbered 1 (not 0!). Must not be NULL.
125  *
126  * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
127  * or SR_ERR_ARG upon invalid arguments. If something other than SR_OK
128  * is returned, the value/state of 'ds' is undefined.
129  */
130 SR_API int sr_datastore_put(struct sr_datastore *ds, void *data,
131  unsigned int length, int in_unitsize, const int *probelist)
132 {
133  unsigned int stored;
134  int capacity, size, num_chunks, chunk_bytes_free, chunk_offset;
135  gpointer chunk;
136 
137  if (!ds) {
138  sr_err("ds: %s: ds was NULL", __func__);
139  return SR_ERR_ARG;
140  }
141 
142  /* Unitsize must not be 0, we'll divide by 0 otherwise. */
143  if (ds->ds_unitsize == 0) {
144  sr_err("ds: %s: ds->ds_unitsize was 0", __func__);
145  return SR_ERR_ARG;
146  }
147 
148  if (!data) {
149  sr_err("ds: %s: data was NULL", __func__);
150  return SR_ERR_ARG;
151  }
152 
153  if (in_unitsize < 1) {
154  sr_err("ds: %s: in_unitsize was %d, but it must be >= 1",
155  __func__, in_unitsize);
156  return SR_ERR_ARG;
157  }
158 
159  if (!probelist) {
160  sr_err("ds: %s: probelist was NULL", __func__);
161  return SR_ERR_ARG;
162  }
163 
164  /* Get the last chunk in the list, or create a new one if needed. */
165  if (ds->chunklist == NULL) {
166  if (!(chunk = new_chunk(&ds))) {
167  sr_err("ds: %s: couldn't allocate new chunk", __func__);
168  return SR_ERR_MALLOC;
169  }
170  } else {
171  chunk = g_slist_last(ds->chunklist)->data;
172  }
173 
174  /* Get/calculate number of chunks, free space, etc. */
175  num_chunks = g_slist_length(ds->chunklist);
176  capacity = (num_chunks * DATASTORE_CHUNKSIZE);
177  chunk_bytes_free = capacity - (ds->ds_unitsize * ds->num_units);
178  chunk_offset = capacity - (DATASTORE_CHUNKSIZE * (num_chunks - 1))
179  - chunk_bytes_free;
180 
181  stored = 0;
182  while (stored < length) {
183  /* No more free space left, allocate a new chunk. */
184  if (chunk_bytes_free == 0) {
185  if (!(chunk = new_chunk(&ds))) {
186  sr_err("ds: %s: couldn't allocate new chunk",
187  __func__);
188  return SR_ERR_MALLOC;
189  }
190  chunk_bytes_free = DATASTORE_CHUNKSIZE;
191  chunk_offset = 0;
192  }
193 
194  if (length - stored > (unsigned int)chunk_bytes_free)
195  size = chunk_bytes_free;
196  else
197  /* Last part, won't fill up this chunk. */
198  size = length - stored;
199 
200  memcpy(chunk + chunk_offset, data + stored, size);
201  chunk_bytes_free -= size;
202  stored += size;
203  }
204 
205  ds->num_units += stored / ds->ds_unitsize;
206 
207  return SR_OK;
208 }
209 
210 /**
211  * Allocate a new memory chunk, append it to the datastore's chunklist.
212  *
213  * The newly allocated chunk is added to the datastore's chunklist by this
214  * function, and the return value additionally points to the new chunk.
215  *
216  * The allocated memory is guaranteed to be cleared.
217  *
218  * TODO: This function should use the datastore's 'chunksize' field instead
219  * of hardcoding DATASTORE_CHUNKSIZE.
220  * TODO: Return int, so we can return SR_OK / SR_ERR_ARG / SR_ERR_MALLOC?
221  *
222  * @param ds Pointer to a variable which holds the datastore structure.
223  * Must not be NULL. The contents of 'ds' are modified in-place.
224  *
225  * @return Pointer to the newly allocated chunk, or NULL upon failure.
226  */
227 static gpointer new_chunk(struct sr_datastore **ds)
228 {
229  gpointer chunk;
230 
231  /* Note: Caller checked that ds != NULL. */
232 
233  chunk = g_try_malloc0(DATASTORE_CHUNKSIZE * (*ds)->ds_unitsize);
234  if (!chunk) {
235  sr_err("ds: %s: chunk malloc failed", __func__);
236  return NULL; /* TODO: SR_ERR_MALLOC later? */
237  }
238 
239  (*ds)->chunklist = g_slist_append((*ds)->chunklist, chunk);
240 
241  return chunk; /* TODO: SR_OK later? */
242 }