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/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         if (!trig)
  79                 return;
  80
  81         for (l = trig->stages; l; l = l->next) {
  82                 stage = l->data;
  83                 g_slist_free_full(stage->matches, g_free);
  84         }
  85         g_slist_free_full(trig->stages, g_free);
  86
  87         g_free(trig->name);
  88         g_free(trig);
  89 }
  90
  91 /**
  92  * Allocate a new trigger stage and add it to the specified trigger.
  93  *
  94  * The caller is responsible to free the trigger (including all stages and
  95  * matches) using sr_trigger_free() once it is no longer needed.
  96  *
  97  * @param trig The trigger to add a stage to. Must not be NULL.
  98  *
  99  * @retval NULL An invalid (NULL) trigger was passed into the function.
 100  * @retval other A newly allocated trigger stage (which has also been added
 101  *               to the list of stages of the specified trigger).
 102  *
 103  * @since 0.4.0
 104  */
 105 SR_API struct sr_trigger_stage *sr_trigger_stage_add(struct sr_trigger *trig)
 106 {
 107         struct sr_trigger_stage *stage;
 108
 109         if (!trig)
 110                 return NULL;
 111
 112         stage = g_malloc0(sizeof(struct sr_trigger_stage));
 113         stage->stage = g_slist_length(trig->stages);
 114         trig->stages = g_slist_append(trig->stages, stage);
 115
 116         return stage;
 117 }
 118
 119 /**
 120  * Allocate a new trigger match and add it to the specified trigger stage.
 121  *
 122  * The caller is responsible to free the trigger (including all stages and
 123  * matches) using sr_trigger_free() once it is no longer needed.
 124  *
 125  * @param stage The trigger stage to add the match to. Must not be NULL.
 126  * @param ch The channel for this trigger match. Must not be NULL. Must be
 127  *           either of type SR_CHANNEL_LOGIC or SR_CHANNEL_ANALOG.
 128  * @param trigger_match The type of trigger match. Must be a valid trigger
 129  *                      type from enum sr_trigger_matches. The trigger type
 130  *                      must be valid for the respective channel type as well.
 131  * @param value Trigger value.
 132  *
 133  * @retval SR_OK Success.
 134  * @retval SR_ERR_ARG Invalid argument(s) were passed to this functions.
 135  *
 136  * @since 0.4.0
 137  */
 138 SR_API int sr_trigger_match_add(struct sr_trigger_stage *stage,
 139                 struct sr_channel *ch, int trigger_match, float value)
 140 {
 141         struct sr_trigger_match *match;
 142
 143         if (!stage || !ch)
 144                 return SR_ERR_ARG;
 145
 146         if (ch->type == SR_CHANNEL_LOGIC) {
 147                 if (trigger_match != SR_TRIGGER_ZERO &&
 148                                 trigger_match != SR_TRIGGER_ONE &&
 149                                 trigger_match != SR_TRIGGER_RISING &&
 150                                 trigger_match != SR_TRIGGER_FALLING &&
 151                                 trigger_match != SR_TRIGGER_EDGE) {
 152                         sr_err("Invalid trigger match for a logic channel.");
 153                         return SR_ERR_ARG;
 154                 }
 155         } else if (ch->type == SR_CHANNEL_ANALOG) {
 156                 if (trigger_match != SR_TRIGGER_RISING &&
 157                                 trigger_match != SR_TRIGGER_FALLING &&
 158                                 trigger_match != SR_TRIGGER_EDGE &&
 159                                 trigger_match != SR_TRIGGER_OVER &&
 160                                 trigger_match != SR_TRIGGER_UNDER) {
 161                         sr_err("Invalid trigger match for an analog channel.");
 162                         return SR_ERR_ARG;
 163                 }
 164         } else {
 165                 sr_err("Unsupported channel type: %d.", ch->type);
 166                 return SR_ERR_ARG;
 167         }
 168
 169         match = g_malloc0(sizeof(struct sr_trigger_match));
 170         match->channel = ch;
 171         match->match = trigger_match;
 172         match->value = value;
 173         stage->matches = g_slist_append(stage->matches, match);
 174
 175         return SR_OK;
 176 }
 177
 178 /** @} */