[libsigrok.git] / datastore.c

/*
 * This file is part of the sigrok project.
 *
 * Copyright (C) 2010-2012 Bert Vermeulen <bert@biot.com>
 *
 * 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 3 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, see <http://www.gnu.org/licenses/>.
 */

#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include <glib.h>
#include "libsigrok.h"
#include "libsigrok-internal.h"

/* Message logging helpers with driver-specific prefix string. */
#define DRIVER_LOG_DOMAIN "datastore: "
#define sr_log(l, s, args...) sr_log(l, DRIVER_LOG_DOMAIN s, ## args)
#define sr_spew(s, args...) sr_spew(DRIVER_LOG_DOMAIN s, ## args)
#define sr_dbg(s, args...) sr_dbg(DRIVER_LOG_DOMAIN s, ## args)
#define sr_info(s, args...) sr_info(DRIVER_LOG_DOMAIN s, ## args)
#define sr_warn(s, args...) sr_warn(DRIVER_LOG_DOMAIN s, ## args)
#define sr_err(s, args...) sr_err(DRIVER_LOG_DOMAIN s, ## args)

/**
 * @file
 *
 * Creating, using, or destroying libsigrok datastores.
 */

/**
 * @defgroup grp_datastore Datastore
 *
 * Creating, using, or destroying libsigrok datastores.
 *
 * @{
 */

static gpointer new_chunk(struct sr_datastore **ds);

/**
 * Create a new datastore with the specified unit size.
 *
 * The unit size is fixed once the datastore is created, and cannot be
 * changed later on, neither can data be added to the datastore with
 * different unit sizes later.
 *
 * It is the caller's responsibility to free the allocated memory of the
 * datastore via the sr_datastore_destroy() function, if no longer needed.
 *
 * @todo Unitsize should probably be unsigned int or uint32_t or similar.
 * @todo This function should have a 'chunksize' parameter, and
 *       struct sr_datastore a 'chunksize' field.
 *
 * @param unitsize The unit size (>= 1) to be used for this datastore.
 * @param ds Pointer to a variable which will hold the newly created
 *           datastore structure.
 *           
 * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
 *         or SR_ERR_ARG upon invalid arguments. If something other than SR_OK
 *         is returned, the value of 'ds' is undefined.
 */
SR_API int sr_datastore_new(int unitsize, struct sr_datastore **ds)
{
	if (!ds) {
		sr_err("%s: ds was NULL", __func__);
		return SR_ERR_ARG;
	}

	if (unitsize <= 0) {
		sr_err("%s: unitsize was %d, but it must be >= 1",
		       __func__, unitsize);
		return SR_ERR_ARG;
	}

	if (!(*ds = g_try_malloc(sizeof(struct sr_datastore)))) {
		sr_err("%s: ds malloc failed", __func__);
		return SR_ERR_MALLOC;
	}

	(*ds)->ds_unitsize = unitsize;
	(*ds)->num_units = 0;
	(*ds)->chunklist = NULL;

	return SR_OK;
}

/**
 * Destroy the specified datastore and free the memory used by it.
 *
 * This will free the memory used by the data in the datastore's 'chunklist',
 * by the chunklist data structure itself, and by the datastore struct.
 *
 * @param ds The datastore to destroy.
 *
 * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
 */
SR_API int sr_datastore_destroy(struct sr_datastore *ds)
{
	GSList *chunk;

	if (!ds) {
		sr_err("%s: ds was NULL", __func__);
		return SR_ERR_ARG;
	}

	for (chunk = ds->chunklist; chunk; chunk = chunk->next)
		g_free(chunk->data);
	g_slist_free(ds->chunklist);
	g_free(ds);
	ds = NULL;

	return SR_OK;
}

/**
 * Append some data to the specified datastore.
 *
 * @todo More elaborate function description.
 * @todo This function should use the (not yet available) 'chunksize' field
 *       of struct sr_datastore (instead of hardcoding DATASTORE_CHUNKSIZE).
 * @todo in_unitsize and probelist are unused?
 * @todo A few of the parameters can be const.
 * @todo Ideally, 'ds' should be unmodified upon errors.
 * @todo Should 0 be allowed as length?
 * @todo Specify/document the data format of the 'data' parameter.
 *
 * @param ds Pointer to the datastore which shall receive the data.
 *           Must not be NULL.
 * @param data Pointer to the memory buffer containing the data to add.
 *             Must not be NULL.
 * @param length Length of the data to add (in number of bytes).
 * @param in_unitsize The unit size (>= 1) of the input data.
 * @param probelist Pointer to a list of integers (probe numbers). The probe
 *                  numbers in this list are 1-based, i.e. the first probe
 *                  is expected to be numbered 1 (not 0!). Must not be NULL.
 *
 * @return SR_OK upon success, SR_ERR_MALLOC upon memory allocation errors,
 *         or SR_ERR_ARG upon invalid arguments. If something other than SR_OK
 *         is returned, the value/state of 'ds' is undefined.
 */
SR_API int sr_datastore_put(struct sr_datastore *ds, void *data,
		unsigned int length, int in_unitsize, const int *probelist)
{
	unsigned int stored;
	int capacity, size, num_chunks, chunk_bytes_free, chunk_offset;
	gpointer chunk;

	if (!ds) {
		sr_err("%s: ds was NULL", __func__);
		return SR_ERR_ARG;
	}

	/* Unitsize must not be 0, we'll divide by 0 otherwise. */
	if (ds->ds_unitsize == 0) {
		sr_err("%s: ds->ds_unitsize was 0", __func__);
		return SR_ERR_ARG;
	}

	if (!data) {
		sr_err("%s: data was NULL", __func__);
		return SR_ERR_ARG;
	}

	if (in_unitsize < 1) {
		sr_err("%s: in_unitsize was %d, but it must be >= 1",
		       __func__, in_unitsize);
		return SR_ERR_ARG;
	}

	if (!probelist) {
		sr_err("%s: probelist was NULL", __func__);
		return SR_ERR_ARG;
	}

	/* Get the last chunk in the list, or create a new one if needed. */
	if (ds->chunklist == NULL) {
		if (!(chunk = new_chunk(&ds))) {
			sr_err("%s: couldn't allocate new chunk", __func__);
			return SR_ERR_MALLOC;
		}
	} else {
		chunk = g_slist_last(ds->chunklist)->data;
	}

	/* Get/calculate number of chunks, free space, etc. */
	num_chunks = g_slist_length(ds->chunklist);
	capacity = (num_chunks * DATASTORE_CHUNKSIZE);
	chunk_bytes_free = capacity - (ds->ds_unitsize * ds->num_units);
	chunk_offset = capacity - (DATASTORE_CHUNKSIZE * (num_chunks - 1))
		       - chunk_bytes_free;

	stored = 0;
	while (stored < length) {
		/* No more free space left, allocate a new chunk. */
		if (chunk_bytes_free == 0) {
			if (!(chunk = new_chunk(&ds))) {
				sr_err("%s: couldn't allocate new chunk",
				       __func__);
				return SR_ERR_MALLOC;
			}
			chunk_bytes_free = DATASTORE_CHUNKSIZE;
			chunk_offset = 0;
		}

		if (length - stored > (unsigned int)chunk_bytes_free)
			size = chunk_bytes_free;
		else
			/* Last part, won't fill up this chunk. */
			size = length - stored;

		memcpy(chunk + chunk_offset, data + stored, size);
		chunk_bytes_free -= size;
		stored += size;
	}

	ds->num_units += stored / ds->ds_unitsize;

	return SR_OK;
}

/**
 * Allocate a new memory chunk, append it to the datastore's chunklist.
 *
 * The newly allocated chunk is added to the datastore's chunklist by this
 * function, and the return value additionally points to the new chunk.
 *
 * The allocated memory is guaranteed to be cleared.
 *
 * @todo This function should use the datastore's 'chunksize' field instead
 *       of hardcoding DATASTORE_CHUNKSIZE.
 * @todo Return int, so we can return SR_OK / SR_ERR_ARG / SR_ERR_MALLOC?
 *
 * @param ds Pointer to a variable which holds the datastore structure.
 *           Must not be NULL. The contents of 'ds' are modified in-place.
 *
 * @return Pointer to the newly allocated chunk, or NULL upon failure.
 */
static gpointer new_chunk(struct sr_datastore **ds)
{
	gpointer chunk;

	/* Note: Caller checked that ds != NULL. */

	chunk = g_try_malloc0(DATASTORE_CHUNKSIZE * (*ds)->ds_unitsize);
	if (!chunk) {
		sr_err("%s: chunk malloc failed (ds_unitsize was %u)",
		       __func__, (*ds)->ds_unitsize);
		return NULL; /* TODO: SR_ERR_MALLOC later? */
	}

	(*ds)->chunklist = g_slist_append((*ds)->chunklist, chunk);

	return chunk; /* TODO: SR_OK later? */
}

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