Start unification of libsigrok return codes.

We have SIGROK_OK for functions calls where no errors occured. All
error code names start with SIGROK_ERR and are globally unique,
negative values.

The value SIGROK_ERR is a generic/unspecified error code, all others,
such as SIGROK_ERR_MALLOC, refer to a specific error condition.

This commit renames the old SIGROK_NOK etc.

hardware/openbench-logic-sniffer/ols.c

@@ -107,7 +107,7 @@ int send_shortcommand(int fd, uint8_t command)
 	g_message("ols: sending cmd 0x%.2x", command);
 	buf[0] = command;
 	if(write(fd, buf, 1) != 1)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	return SIGROK_OK;
 }
@@ -124,7 +124,7 @@ int send_longcommand(int fd, uint8_t command, uint32_t data)
 	buf[3] = data & 0xff0000 >> 16;
 	buf[4] = data & 0xff000000 >> 24;
 	if(write(fd, buf, 5) != 5)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	return SIGROK_OK;
 }
@@ -160,7 +160,7 @@ static int configure_probes(GSList *probes)
 				if(stage > 3)
 				{
 					/* only supporting parallel mode, with up to 4 stages */
-					return SIGROK_NOK;
+					return SIGROK_ERR;
 				}
 			}
 		}
@@ -275,11 +275,11 @@ static int hw_opendev(int device_index)
 	struct sigrok_device_instance *sdi;
 
 	if(!(sdi = get_sigrok_device_instance(device_instances, device_index)))
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	sdi->serial->fd = open(sdi->serial->port, O_RDWR);
 	if(sdi->serial->fd == -1)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	sdi->status = ST_ACTIVE;
 
@@ -376,7 +376,7 @@ static int set_configuration_samplerate(struct sigrok_device_instance *sdi, uint
 	uint32_t divider;
 
 	if(samplerate < samplerates.low || samplerate > samplerates.high)
-		return SIGROK_ERR_BADVALUE;
+		return SIGROK_ERR_SAMPLERATE;
 
 	if(samplerate  > CLOCK_RATE) {
 		flag_reg |= FLAG_DEMUX;
@@ -391,7 +391,7 @@ static int set_configuration_samplerate(struct sigrok_device_instance *sdi, uint
 	g_message("setting samplerate to %"PRIu64" Hz (divider %u, demux %s)", samplerate, divider,
 			flag_reg & FLAG_DEMUX ? "on" : "off");
 	if(send_longcommand(sdi->serial->fd, CMD_SET_DIVIDER, divider) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	cur_samplerate = samplerate;
 
 	return SIGROK_OK;
@@ -405,10 +405,10 @@ static int hw_set_configuration(int device_index, int capability, void *value)
 	uint64_t *tmp_u64;
 
 	if(!(sdi = get_sigrok_device_instance(device_instances, device_index)))
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	if(sdi->status != ST_ACTIVE)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	if(capability == HWCAP_SAMPLERATE) {
 		tmp_u64 = value;
@@ -424,13 +424,13 @@ static int hw_set_configuration(int device_index, int capability, void *value)
 		capture_ratio = strtol(value, NULL, 10);
 		if(capture_ratio < 0 || capture_ratio > 100) {
 			capture_ratio = 0;
-			ret = SIGROK_NOK;
+			ret = SIGROK_ERR;
 		}
 		else
 			ret = SIGROK_OK;
 	}
 	else
-		ret = SIGROK_NOK;
+		ret = SIGROK_ERR;
 
 	return ret;
 }
@@ -526,19 +526,19 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 	uint32_t data;
 
 	if(!(sdi = get_sigrok_device_instance(device_instances, device_index)))
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	if(sdi->status != ST_ACTIVE)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	/* reset again */
 	if(send_longcommand(sdi->serial->fd, CMD_RESET, 0) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	/* send flag register */
 	data = flag_reg << 24;
 	if(send_longcommand(sdi->serial->fd, CMD_SET_FLAGS, data) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	/* send sample limit and pre/post-trigger capture ratio */
 	data = limit_samples / 4 << 16;
@@ -546,43 +546,43 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 		data |= (limit_samples - (limit_samples / 100 * capture_ratio)) / 4;
 	data = 0x00190019;
 	if(send_longcommand(sdi->serial->fd, CMD_CAPTURE_SIZE, data) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	/* trigger masks */
 	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_MASK_0, trigger_mask[0]) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_MASK_1, trigger_mask[1]) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_MASK_2, trigger_mask[2]) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_MASK_3, trigger_mask[3]) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 
 	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_VALUE_0, trigger_value[0]) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_VALUE_1, trigger_value[1]) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_VALUE_2, trigger_value[2]) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_VALUE_3, trigger_value[3]) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 
 	/* trigger configuration */
 	/* TODO: the start flag should only be on the last used stage I think... */
 	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_CONFIG_0, 0x00000008) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_CONFIG_1, 0x00000000) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_CONFIG_2, 0x00000000) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 //	if(send_longcommand(sdi->serial->fd, CMD_SET_TRIGGER_CONFIG_3, 0x00000000) != SIGROK_OK)
-//		return SIGROK_NOK;
+//		return SIGROK_ERR;
 
 	set_configuration_samplerate(sdi, cur_samplerate);
 
 	/* start acquisition on the device */
 	if(send_shortcommand(sdi->serial->fd, CMD_RUN) != SIGROK_OK)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	source_add(sdi->serial->fd, G_IO_IN, -1, receive_data, session_device_id);
 
@@ -590,7 +590,7 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 	packet = g_malloc(sizeof(struct datafeed_packet));
 	header = g_malloc(sizeof(struct datafeed_header));
 	if(!packet || !header)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	packet->type = DF_HEADER;
 	packet->length = sizeof(struct datafeed_header);
 	packet->payload = (unsigned char *) header;

hardware/saleae-logic/saleae-logic.c

@@ -352,7 +352,7 @@ static int configure_probes(GSList *probes)
 					trigger_value[stage] |= probe_bit;
 				stage++;
 				if(stage > NUM_TRIGGER_STAGES)
-					return SIGROK_NOK;
+					return SIGROK_ERR;
 			}
 		}
 	}
@@ -450,19 +450,19 @@ static int hw_opendev(int device_index)
 
 	if( !(sdi = sl_open_device(device_index)) ) {
 		g_warning("unable to open device");
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 
 	err = libusb_claim_interface(sdi->usb->devhdl, USB_INTERFACE);
 	if(err != 0) {
 		g_warning("Unable to claim interface: %d", err);
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 
 	if(cur_samplerate == 0) {
 		/* sample rate hasn't been set; default to the slowest it has */
-		if(hw_set_configuration(device_index, HWCAP_SAMPLERATE, &supported_samplerates[0]) == SIGROK_NOK)
+		if(hw_set_configuration(device_index, HWCAP_SAMPLERATE, &supported_samplerates[0]) == SIGROK_ERR)
-			return SIGROK_NOK;
+			return SIGROK_ERR;
 	}
 
 	return SIGROK_OK;
@@ -562,7 +562,7 @@ static int set_configuration_samplerate(struct sigrok_device_instance *sdi, uint
 			break;
 	}
 	if(supported_samplerates[i] == 0)
-		return SIGROK_ERR_BADVALUE;
+		return SIGROK_ERR_SAMPLERATE;
 
 	divider = (uint8_t) (48 / (float) (samplerate/1000000)) - 1;
 
@@ -572,7 +572,7 @@ static int set_configuration_samplerate(struct sigrok_device_instance *sdi, uint
 	ret = libusb_bulk_transfer(sdi->usb->devhdl, 1 | LIBUSB_ENDPOINT_OUT, buf, 2, &result, 500);
 	if(ret != 0) {
 		g_warning("failed to set samplerate: %d", ret);
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 	cur_samplerate = samplerate;
 
@@ -587,7 +587,7 @@ static int hw_set_configuration(int device_index, int capability, void *value)
 	uint64_t *tmp_u64;
 
 	if( !(sdi = get_sigrok_device_instance(device_instances, device_index)) )
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	if(capability == HWCAP_SAMPLERATE) {
 		tmp_u64 = value;
@@ -600,7 +600,7 @@ static int hw_set_configuration(int device_index, int capability, void *value)
 		ret = SIGROK_OK;
 	}
 	else
-		ret = SIGROK_NOK;
+		ret = SIGROK_ERR;
 
 	return ret;
 }
@@ -757,12 +757,12 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 	unsigned char *buf;
 
 	if( !(sdi = get_sigrok_device_instance(device_instances, device_index)))
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	packet = g_malloc(sizeof(struct datafeed_packet));
 	header = g_malloc(sizeof(struct datafeed_header));
 	if(!packet || !header)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	/* start with 2K transfer, subsequently increased to 4K */
 	size = 2048;
@@ -775,7 +775,7 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 			/* TODO: free them all */
 			libusb_free_transfer(transfer);
 			g_free(buf);
-			return SIGROK_NOK;
+			return SIGROK_ERR;
 		}
 		size = 4096;
 	}

hardware/zeroplus-logic-cube/zeroplus.c

@@ -242,7 +242,7 @@ static int configure_probes(GSList *probes)
 					trigger_value[stage] |= probe_bit;
 				stage++;
 				if(stage > NUM_TRIGGER_STAGES)
-					return SIGROK_NOK;
+					return SIGROK_ERR;
 			}
 		}
 	}
@@ -304,13 +304,13 @@ static int hw_opendev(int device_index)
 
 	if( !(sdi = zp_open_device(device_index)) ) {
 		g_warning("unable to open device");
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 
 	err = libusb_claim_interface(sdi->usb->devhdl, USB_INTERFACE);
 	if(err != 0) {
 		g_warning("Unable to claim interface: %d", err);
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 	analyzer_reset(sdi->usb->devhdl);
 	analyzer_initialize(sdi->usb->devhdl);
@@ -331,8 +331,8 @@ static int hw_opendev(int device_index)
 
 	if(cur_samplerate == 0) {
 		/* sample rate hasn't been set; default to the slowest it has */
-		if(hw_set_configuration(device_index, HWCAP_SAMPLERATE, &samplerates.low) == SIGROK_NOK)
+		if(hw_set_configuration(device_index, HWCAP_SAMPLERATE, &samplerates.low) == SIGROK_ERR)
-			return SIGROK_NOK;
+			return SIGROK_ERR;
 	}
 
 	return SIGROK_OK;
@@ -442,7 +442,7 @@ static int hw_set_configuration(int device_index, int capability, void *value)
 	uint64_t *tmp_u64;
 
 	if( !(sdi = get_sigrok_device_instance(device_instances, device_index)) )
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	switch (capability) {
 		case HWCAP_SAMPLERATE:
@@ -457,7 +457,7 @@ static int hw_set_configuration(int device_index, int capability, void *value)
 			return SIGROK_OK;
 
 		default:
-			return SIGROK_NOK;
+			return SIGROK_ERR;
 	}
 }
 
@@ -471,7 +471,7 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 	unsigned char *buf;
 
 	if( !(sdi = get_sigrok_device_instance(device_instances, device_index)))
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	analyzer_start(sdi->usb->devhdl);
 	g_message("Waiting for data");
@@ -493,7 +493,7 @@ static int hw_start_acquisition(int device_index, gpointer session_device_id)
 
 	buf = g_malloc(PACKET_SIZE);
 	if (!buf)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	analyzer_read_start(sdi->usb->devhdl);
 	/* send the incoming transfer to the session bus */
 	for(packet_num = 0; packet_num < (memory_size * 4 / PACKET_SIZE); packet_num++) {

output/output_vcd.c

@@ -57,6 +57,8 @@ static int init(struct output *o)
 	char sbuf[10], wbuf[1000];
 
 	ctx = malloc(sizeof(struct context));
+	if (ctx == NULL)
+		return SIGROK_ERR_MALLOC;
 	o->internal = ctx;
 	ctx->num_enabled_probes = 0;
 	for (l = o->device->probes; l; l = l->next) {
@@ -71,7 +73,10 @@ static int init(struct output *o)
 	/* TODO: Allow for configuration via o->param. */
 
 	ctx->header = calloc(1, MAX_HEADER_LEN + 1);
+	if (ctx->header == NULL)
+		return SIGROK_ERR_MALLOC;
 	num_probes = g_slist_length(o->device->probes);
+	/* TODO: Handle num_probes == 0, too many probes, etc. */
 	samplerate = *((uint64_t *) o->device->plugin->get_device_info(
 			o->device->plugin_index, DI_CUR_SAMPLERATE));
 
@@ -97,8 +102,11 @@ static int init(struct output *o)
 	b = snprintf(ctx->header, MAX_HEADER_LEN, vcd_header, "TODO: Date",
 		     PACKAGE_STRING, ctx->num_enabled_probes, num_probes,
 		     (char *)&sbuf, 1, "ns", PACKAGE, (char *)&wbuf);
+	/* TODO: Handle snprintf errors. */
 
 	ctx->prevbits = calloc(sizeof(int), num_probes);
+	if (ctx->prevbits == NULL)
+		return SIGROK_ERR_MALLOC;
 
 	return 0;
 }
@@ -117,6 +125,8 @@ static int event(struct output *o, int event_type, char **data_out,
 	case DF_END:
 		outlen = strlen("$dumpoff\n$end\n");
 		outbuf = malloc(outlen + 1);
+		if (outbuf == NULL)
+			return SIGROK_ERR_MALLOC;
 		snprintf(outbuf, outlen, "$dumpoff\n$end\n");
 		*data_out = outbuf;
 		*length_out = outlen;
@@ -139,6 +149,8 @@ static int data(struct output *o, char *data_in, uint64_t length_in,
 	ctx = o->internal;
 	outsize = strlen(ctx->header);
 	outbuf = calloc(1, outsize + 1 + 10000); // FIXME: Use realloc().
+	if (outbuf == NULL)
+		return SIGROK_ERR_MALLOC;
 	if (ctx->header) {
 		/* The header is still here, this must be the first packet. */
 		strncpy(outbuf, ctx->header, outsize);

session.c

@@ -223,27 +223,27 @@ int session_save(char *filename)
 	unlink(filename);
 
 	if( !(zipfile = zip_open(filename, ZIP_CREATE, &error)) )
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 
 	/* version */
 	version[0] = '1';
 	if( !(src = zip_source_buffer(zipfile, version, 1, 0)) )
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	if(zip_add(zipfile, "version", src) == -1) {
 		g_message("error saving version into zipfile: %s", zip_strerror(zipfile));
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 
 	/* metadata */
 	strcpy(metafile, "sigrok-meta-XXXXXX");
 	if( (tmpfile = g_mkstemp(metafile)) == -1)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	close(tmpfile);
 	make_metadata(metafile);
 	if( !(src = zip_source_file(zipfile, metafile, 0, -1)) )
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	if(zip_add(zipfile, "metadata", src) == -1)
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	unlink(metafile);
 
 	/* raw */
@@ -259,26 +259,18 @@ int session_save(char *filename)
 				bufcnt += DATASTORE_CHUNKSIZE;
 			}
 			if( !(src = zip_source_buffer(zipfile, buf, ds->num_units * ds->ds_unitsize, TRUE)) )
-				return SIGROK_NOK;
+				return SIGROK_ERR;
 			snprintf(rawname, 15, "raw-%d", devcnt);
 			if(zip_add(zipfile, rawname, src) == -1)
-				return SIGROK_NOK;
+				return SIGROK_ERR;
 		}
 		devcnt++;
 	}
 
 	if( (ret = zip_close(zipfile)) == -1) {
 		g_message("error saving zipfile: %s", zip_strerror(zipfile));
-		return SIGROK_NOK;
+		return SIGROK_ERR;
 	}
 
 	return SIGROK_OK;
 }
-
-
-
-
-
-
-
-

sigrok.h

@@ -27,11 +27,27 @@
 #include <glib.h>
 #include <libusb.h>
 
-/* Returned status/error codes */
+/*
-#define SIGROK_STATUS_DISABLED		0
+ * Status/error codes returned by libsigrok functions.
-#define SIGROK_OK			1
+ *
-#define SIGROK_NOK			2
+ * All possible return codes of libsigrok functions must be listed here.
-#define SIGROK_ERR_BADVALUE		20
+ * Functions should never return hardcoded numbers as status, but rather
+ * use these #defines instead. All error codes are negative numbers.
+ *
+ * The error codes are globally unique in libsigrok, i.e. if one of the
+ * libsigrok function returns a "malloc error" it must be exactly the same
+ * return value as used for all other functions to indicate "malloc error".
+ * There must be no functions which indicate two different errors via the
+ * same return code.
+ *
+ * Also, for compatibility reasons, no defined return codes are ever removed
+ * or reused for different #defines later. You can only add new #defines and
+ * return codes, but never remove or redefine existing ones.
+ */
+#define SIGROK_OK			0  /* No error */
+#define SIGROK_ERR			-1 /* Generic/unspecified error */
+#define SIGROK_ERR_MALLOC		-2 /* Malloc/calloc/realloc error */
+#define SIGROK_ERR_SAMPLERATE		-3 /* Incorrect samplerate */
 
 /* Handy little macros */
 #define KHZ(n) (n * 1000)