src/trigger.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2014 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 "libsigrok.h"
  21 #include "libsigrok-internal.h"
  22
  23 /* * @cond PRIVATE */
  24 #define LOG_PREFIX "trigger"
  25 /* * @endcond */
  26
  27 /**
  28  * @file
  29  *
  30  * Creating, using, or destroying triggers.
  31  */
  32
  33 /**
  34  * @defgroup grp_trigger Trigger handling
  35  *
  36  * Creating, using, or destroying triggers.
  37  *
  38  * @{
  39  */
  40
  41 /**
  42  * Create a new trigger.
  43  *
  44  * The caller is responsible to free the trigger (including all stages and
  45  * matches) using sr_trigger_free() once it is no longer needed.
  46  *
  47  * @param name The trigger name to use. Can be NULL.
  48  *
  49  * @return A newly allocated trigger.
  50  *
  51  * @since 0.4.0
  52  */
  53 SR_API struct sr_trigger *sr_trigger_new(const char *name)
  54 {
  55         struct sr_trigger *trig;
  56
  57         trig = g_malloc0(sizeof(struct sr_trigger));
  58         if (name)
  59                 trig->name = g_strdup(name);
  60
  61         return trig;
  62 }
  63
  64 /**
  65  * Free a previously allocated trigger.
  66  *
  67  * This will also free any trigger stages/matches in this trigger.
  68  *
  69  * @param trig The trigger to free. Must not be NULL.
  70  *
  71  * @since 0.4.0
  72  */
  73 SR_API void sr_trigger_free(struct sr_trigger *trig)
  74 {
  75         struct sr_trigger_stage *stage;
  76         GSList *l;
  77
  78         for (l = trig->stages; l; l = l->next) {
  79                 stage = l->data;
  80                 g_slist_free_full(stage->matches, g_free);
  81         }
  82         g_slist_free_full(trig->stages, g_free);
  83
  84         g_free(trig->name);
  85         g_free(trig);
  86 }
  87
  88 /**
  89  * Allocate a new trigger stage and add it to the specified trigger.
  90  *
  91  * The caller is responsible to free the trigger (including all stages and
  92  * matches) using sr_trigger_free() once it is no longer needed.
  93  *
  94  * @param trig The trigger to add a stage to. Must not be NULL.
  95  *
  96  * @return A newly allocated trigger stage (which has also been added to the
  97  *         list of stages of the specified trigger).
  98  *
  99  * @since 0.4.0
 100  */
 101 SR_API struct sr_trigger_stage *sr_trigger_stage_add(struct sr_trigger *trig)
 102 {
 103         struct sr_trigger_stage *stage;
 104
 105         stage = g_malloc0(sizeof(struct sr_trigger_stage));
 106         stage->stage = g_slist_length(trig->stages);
 107         trig->stages = g_slist_append(trig->stages, stage);
 108
 109         return stage;
 110 }
 111
 112 /**
 113  * Allocate a new trigger match and add it to the specified trigger stage.
 114  *
 115  * The caller is responsible to free the trigger (including all stages and
 116  * matches) using sr_trigger_free() once it is no longer needed.
 117  *
 118  * @param stage The trigger stage to add the match to. Must not be NULL.
 119  * @param ch The channel for this trigger match. Must not be NULL. Must be
 120  *           either of type SR_CHANNEL_LOGIC or SR_CHANNEL_ANALOG.
 121  * @param trigger_match The type of trigger match. Must be a valid trigger
 122  *                      type from enum sr_trigger_matches. The trigger type
 123  *                      must be valid for the respective channel type as well.
 124  * @param value Trigger value.
 125  *
 126  * @retval SR_OK Success.
 127  * @retval SR_ERR_ARG Invalid argument(s) were passed to this functions.
 128  *
 129  * @since 0.4.0
 130  */
 131 SR_API int sr_trigger_match_add(struct sr_trigger_stage *stage,
 132                 struct sr_channel *ch, int trigger_match, float value)
 133 {
 134         struct sr_trigger_match *match;
 135
 136         if (ch->type == SR_CHANNEL_LOGIC) {
 137                 if (trigger_match != SR_TRIGGER_ZERO &&
 138                                 trigger_match != SR_TRIGGER_ONE &&
 139                                 trigger_match != SR_TRIGGER_RISING &&
 140                                 trigger_match != SR_TRIGGER_FALLING &&
 141                                 trigger_match != SR_TRIGGER_EDGE) {
 142                         sr_err("Invalid trigger match for a logic channel.");
 143                         return SR_ERR_ARG;
 144                 }
 145         } else if (ch->type == SR_CHANNEL_ANALOG) {
 146                 if (trigger_match != SR_TRIGGER_FALLING &&
 147                                 trigger_match != SR_TRIGGER_OVER &&
 148                                 trigger_match != SR_TRIGGER_UNDER) {
 149                         sr_err("Invalid trigger match for an analog channel.");
 150                         return SR_ERR_ARG;
 151                 }
 152         }
 153
 154         match = g_malloc0(sizeof(struct sr_trigger_match));
 155         match->channel = ch;
 156         match->match = trigger_match;
 157         match->value = value;
 158         stage->matches = g_slist_append(stage->matches, match);
 159
 160         return SR_OK;
 161 }
 162
 163 /** @} */