libsigrok  0.2.0
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerator Macros Groups Pages
strutil.c
Go to the documentation of this file.
1 /*
2  * This file is part of the libsigrok project.
3  *
4  * Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
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 2 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, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 #include <stdint.h>
22 #include <stdlib.h>
23 #include <string.h>
24 #include "libsigrok.h"
25 #include "libsigrok-internal.h"
26 
27 /* Message logging helpers with subsystem-specific prefix string. */
28 #define LOG_PREFIX "strutil: "
29 #define sr_log(l, s, args...) sr_log(l, LOG_PREFIX s, ## args)
30 #define sr_spew(s, args...) sr_spew(LOG_PREFIX s, ## args)
31 #define sr_dbg(s, args...) sr_dbg(LOG_PREFIX s, ## args)
32 #define sr_info(s, args...) sr_info(LOG_PREFIX s, ## args)
33 #define sr_warn(s, args...) sr_warn(LOG_PREFIX s, ## args)
34 #define sr_err(s, args...) sr_err(LOG_PREFIX s, ## args)
35 
36 /**
37  * @file
38  *
39  * Helper functions for handling or converting libsigrok-related strings.
40  */
41 
42 /**
43  * @defgroup grp_strutil String utilities
44  *
45  * Helper functions for handling or converting libsigrok-related strings.
46  *
47  * @{
48  */
49 
50 /**
51  * Convert a numeric value value to its "natural" string representation.
52  * in SI units
53  *
54  * E.g. a value of 3000000, with units set to "W", would be converted
55  * to "3 MW", 20000 to "20 kW", 31500 would become "31.5 kW".
56  *
57  * @param x The value to convert.
58  * @param unit The unit to append to the string, or NULL if the string
59  * has no units.
60  *
61  * @return A g_try_malloc()ed string representation of the samplerate value,
62  * or NULL upon errors. The caller is responsible to g_free() the
63  * memory.
64  */
65 SR_API char *sr_si_string_u64(uint64_t x, const char *unit)
66 {
67  if (unit == NULL)
68  unit = "";
69 
70  if ((x >= SR_GHZ(1)) && (x % SR_GHZ(1) == 0)) {
71  return g_strdup_printf("%" PRIu64 " G%s", x / SR_GHZ(1), unit);
72  } else if ((x >= SR_GHZ(1)) && (x % SR_GHZ(1) != 0)) {
73  return g_strdup_printf("%" PRIu64 ".%" PRIu64 " G%s",
74  x / SR_GHZ(1), x % SR_GHZ(1), unit);
75  } else if ((x >= SR_MHZ(1)) && (x % SR_MHZ(1) == 0)) {
76  return g_strdup_printf("%" PRIu64 " M%s",
77  x / SR_MHZ(1), unit);
78  } else if ((x >= SR_MHZ(1)) && (x % SR_MHZ(1) != 0)) {
79  return g_strdup_printf("%" PRIu64 ".%" PRIu64 " M%s",
80  x / SR_MHZ(1), x % SR_MHZ(1), unit);
81  } else if ((x >= SR_KHZ(1)) && (x % SR_KHZ(1) == 0)) {
82  return g_strdup_printf("%" PRIu64 " k%s",
83  x / SR_KHZ(1), unit);
84  } else if ((x >= SR_KHZ(1)) && (x % SR_KHZ(1) != 0)) {
85  return g_strdup_printf("%" PRIu64 ".%" PRIu64 " k%s",
86  x / SR_KHZ(1), x % SR_KHZ(1), unit);
87  } else {
88  return g_strdup_printf("%" PRIu64 " %s", x, unit);
89  }
90 
91  sr_err("%s: Error creating SI units string.", __func__);
92  return NULL;
93 }
94 
95 /**
96  * Convert a numeric samplerate value to its "natural" string representation.
97  *
98  * E.g. a value of 3000000 would be converted to "3 MHz", 20000 to "20 kHz",
99  * 31500 would become "31.5 kHz".
100  *
101  * @param samplerate The samplerate in Hz.
102  *
103  * @return A g_try_malloc()ed string representation of the samplerate value,
104  * or NULL upon errors. The caller is responsible to g_free() the
105  * memory.
106  */
107 SR_API char *sr_samplerate_string(uint64_t samplerate)
108 {
109  return sr_si_string_u64(samplerate, "Hz");
110 }
111 
112 /**
113  * Convert a numeric frequency value to the "natural" string representation
114  * of its period.
115  *
116  * E.g. a value of 3000000 would be converted to "3 us", 20000 to "50 ms".
117  *
118  * @param frequency The frequency in Hz.
119  *
120  * @return A g_try_malloc()ed string representation of the frequency value,
121  * or NULL upon errors. The caller is responsible to g_free() the
122  * memory.
123  */
124 SR_API char *sr_period_string(uint64_t frequency)
125 {
126  char *o;
127  int r;
128 
129  /* Allocate enough for a uint64_t as string + " ms". */
130  if (!(o = g_try_malloc0(30 + 1))) {
131  sr_err("%s: o malloc failed", __func__);
132  return NULL;
133  }
134 
135  if (frequency >= SR_GHZ(1))
136  r = snprintf(o, 30, "%" PRIu64 " ns", frequency / 1000000000);
137  else if (frequency >= SR_MHZ(1))
138  r = snprintf(o, 30, "%" PRIu64 " us", frequency / 1000000);
139  else if (frequency >= SR_KHZ(1))
140  r = snprintf(o, 30, "%" PRIu64 " ms", frequency / 1000);
141  else
142  r = snprintf(o, 30, "%" PRIu64 " s", frequency);
143 
144  if (r < 0) {
145  /* Something went wrong... */
146  g_free(o);
147  return NULL;
148  }
149 
150  return o;
151 }
152 
153 /**
154  * Convert a numeric voltage value to the "natural" string representation
155  * of its voltage value. The voltage is specified as a rational number's
156  * numerator and denominator.
157  *
158  * E.g. a value of 300000 would be converted to "300mV", 2 to "2V".
159  *
160  * @param v_p The voltage numerator.
161  * @param v_q The voltage denominator.
162  *
163  * @return A g_try_malloc()ed string representation of the voltage value,
164  * or NULL upon errors. The caller is responsible to g_free() the
165  * memory.
166  */
167 SR_API char *sr_voltage_string(uint64_t v_p, uint64_t v_q)
168 {
169  int r;
170  char *o;
171 
172  if (!(o = g_try_malloc0(30 + 1))) {
173  sr_err("%s: o malloc failed", __func__);
174  return NULL;
175  }
176 
177  if (v_q == 1000)
178  r = snprintf(o, 30, "%" PRIu64 "mV", v_p);
179  else if (v_q == 1)
180  r = snprintf(o, 30, "%" PRIu64 "V", v_p);
181  else
182  r = snprintf(o, 30, "%gV", (float)v_p / (float)v_q);
183 
184  if (r < 0) {
185  /* Something went wrong... */
186  g_free(o);
187  return NULL;
188  }
189 
190  return o;
191 }
192 
193 /**
194  * Parse a trigger specification string.
195  *
196  * @param sdi The device instance for which the trigger specification is
197  * intended. Must not be NULL. Also, sdi->driver and
198  * sdi->driver->info_get must not be NULL.
199  * @param triggerstring The string containing the trigger specification for
200  * one or more probes of this device. Entries for multiple probes are
201  * comma-separated. Triggers are specified in the form key=value,
202  * where the key is a probe number (or probe name) and the value is
203  * the requested trigger type. Valid trigger types currently
204  * include 'r' (rising edge), 'f' (falling edge), 'c' (any pin value
205  * change), '0' (low value), or '1' (high value).
206  * Example: "1=r,sck=f,miso=0,7=c"
207  *
208  * @return Pointer to a list of trigger types (strings), or NULL upon errors.
209  * The pointer list (if non-NULL) has as many entries as the
210  * respective device has probes (all physically available probes,
211  * not just enabled ones). Entries of the list which don't have
212  * a trigger value set in 'triggerstring' are NULL, the other entries
213  * contain the respective trigger type which is requested for the
214  * respective probe (e.g. "r", "c", and so on).
215  */
216 SR_API char **sr_parse_triggerstring(const struct sr_dev_inst *sdi,
217  const char *triggerstring)
218 {
219  GSList *l;
220  GVariant *gvar;
221  struct sr_probe *probe;
222  int max_probes, probenum, i;
223  char **tokens, **triggerlist, *trigger, *tc;
224  const char *trigger_types;
225  gboolean error;
226 
227  max_probes = g_slist_length(sdi->probes);
228  error = FALSE;
229 
230  if (!(triggerlist = g_try_malloc0(max_probes * sizeof(char *)))) {
231  sr_err("%s: triggerlist malloc failed", __func__);
232  return NULL;
233  }
234 
235  if (sdi->driver->config_list(SR_CONF_TRIGGER_TYPE, &gvar, sdi) != SR_OK) {
236  sr_err("%s: Device doesn't support any triggers.", __func__);
237  return NULL;
238  }
239  trigger_types = g_variant_get_string(gvar, NULL);
240 
241  tokens = g_strsplit(triggerstring, ",", max_probes);
242  for (i = 0; tokens[i]; i++) {
243  probenum = -1;
244  for (l = sdi->probes; l; l = l->next) {
245  probe = (struct sr_probe *)l->data;
246  if (probe->enabled
247  && !strncmp(probe->name, tokens[i],
248  strlen(probe->name))) {
249  probenum = probe->index;
250  break;
251  }
252  }
253 
254  if (probenum < 0 || probenum >= max_probes) {
255  sr_err("Invalid probe.");
256  error = TRUE;
257  break;
258  }
259 
260  if ((trigger = strchr(tokens[i], '='))) {
261  for (tc = ++trigger; *tc; tc++) {
262  if (strchr(trigger_types, *tc) == NULL) {
263  sr_err("Unsupported trigger "
264  "type '%c'.", *tc);
265  error = TRUE;
266  break;
267  }
268  }
269  if (!error)
270  triggerlist[probenum] = g_strdup(trigger);
271  }
272  }
273  g_strfreev(tokens);
274  g_variant_unref(gvar);
275 
276  if (error) {
277  for (i = 0; i < max_probes; i++)
278  g_free(triggerlist[i]);
279  g_free(triggerlist);
280  triggerlist = NULL;
281  }
282 
283  return triggerlist;
284 }
285 
286 /**
287  * Convert a "natural" string representation of a size value to uint64_t.
288  *
289  * E.g. a value of "3k" or "3 K" would be converted to 3000, a value
290  * of "15M" would be converted to 15000000.
291  *
292  * Value representations other than decimal (such as hex or octal) are not
293  * supported. Only 'k' (kilo), 'm' (mega), 'g' (giga) suffixes are supported.
294  * Spaces (but not other whitespace) between value and suffix are allowed.
295  *
296  * @param sizestring A string containing a (decimal) size value.
297  * @param size Pointer to uint64_t which will contain the string's size value.
298  *
299  * @return SR_OK upon success, SR_ERR upon errors.
300  */
301 SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
302 {
303  int multiplier, done;
304  char *s;
305 
306  *size = strtoull(sizestring, &s, 10);
307  multiplier = 0;
308  done = FALSE;
309  while (s && *s && multiplier == 0 && !done) {
310  switch (*s) {
311  case ' ':
312  break;
313  case 'k':
314  case 'K':
315  multiplier = SR_KHZ(1);
316  break;
317  case 'm':
318  case 'M':
319  multiplier = SR_MHZ(1);
320  break;
321  case 'g':
322  case 'G':
323  multiplier = SR_GHZ(1);
324  break;
325  default:
326  done = TRUE;
327  s--;
328  }
329  s++;
330  }
331  if (multiplier > 0)
332  *size *= multiplier;
333 
334  if (*s && strcasecmp(s, "Hz"))
335  return SR_ERR;
336 
337  return SR_OK;
338 }
339 
340 /**
341  * Convert a "natural" string representation of a time value to an
342  * uint64_t value in milliseconds.
343  *
344  * E.g. a value of "3s" or "3 s" would be converted to 3000, a value
345  * of "15ms" would be converted to 15.
346  *
347  * Value representations other than decimal (such as hex or octal) are not
348  * supported. Only lower-case "s" and "ms" time suffixes are supported.
349  * Spaces (but not other whitespace) between value and suffix are allowed.
350  *
351  * @param timestring A string containing a (decimal) time value.
352  * @return The string's time value as uint64_t, in milliseconds.
353  *
354  * @todo Add support for "m" (minutes) and others.
355  * @todo Add support for picoseconds?
356  * @todo Allow both lower-case and upper-case? If no, document it.
357  */
358 SR_API uint64_t sr_parse_timestring(const char *timestring)
359 {
360  uint64_t time_msec;
361  char *s;
362 
363  /* TODO: Error handling, logging. */
364 
365  time_msec = strtoull(timestring, &s, 10);
366  if (time_msec == 0 && s == timestring)
367  return 0;
368 
369  if (s && *s) {
370  while (*s == ' ')
371  s++;
372  if (!strcmp(s, "s"))
373  time_msec *= 1000;
374  else if (!strcmp(s, "ms"))
375  ; /* redundant */
376  else
377  return 0;
378  }
379 
380  return time_msec;
381 }
382 
383 SR_API gboolean sr_parse_boolstring(const char *boolstr)
384 {
385  if (!boolstr)
386  return FALSE;
387 
388  if (!g_ascii_strncasecmp(boolstr, "true", 4) ||
389  !g_ascii_strncasecmp(boolstr, "yes", 3) ||
390  !g_ascii_strncasecmp(boolstr, "on", 2) ||
391  !g_ascii_strncasecmp(boolstr, "1", 1))
392  return TRUE;
393 
394  return FALSE;
395 }
396 
397 SR_API int sr_parse_period(const char *periodstr, uint64_t *p, uint64_t *q)
398 {
399  char *s;
400 
401  *p = strtoull(periodstr, &s, 10);
402  if (*p == 0 && s == periodstr)
403  /* No digits found. */
404  return SR_ERR_ARG;
405 
406  if (s && *s) {
407  while (*s == ' ')
408  s++;
409  if (!strcmp(s, "fs"))
410  *q = 1000000000000000ULL;
411  else if (!strcmp(s, "ps"))
412  *q = 1000000000000ULL;
413  else if (!strcmp(s, "ns"))
414  *q = 1000000000ULL;
415  else if (!strcmp(s, "us"))
416  *q = 1000000;
417  else if (!strcmp(s, "ms"))
418  *q = 1000;
419  else if (!strcmp(s, "s"))
420  *q = 1;
421  else
422  /* Must have a time suffix. */
423  return SR_ERR_ARG;
424  }
425 
426  return SR_OK;
427 }
428 
429 
430 SR_API int sr_parse_voltage(const char *voltstr, uint64_t *p, uint64_t *q)
431 {
432  char *s;
433 
434  *p = strtoull(voltstr, &s, 10);
435  if (*p == 0 && s == voltstr)
436  /* No digits found. */
437  return SR_ERR_ARG;
438 
439  if (s && *s) {
440  while (*s == ' ')
441  s++;
442  if (!strcasecmp(s, "mv"))
443  *q = 1000L;
444  else if (!strcasecmp(s, "v"))
445  *q = 1;
446  else
447  /* Must have a base suffix. */
448  return SR_ERR_ARG;
449  }
450 
451  return SR_OK;
452 }
453 
454 /** @} */