src/transport/transport.h

   1 /*
   2  * Copyright (c) 2010 by David Brownell
   3  * Copyright (C) 2011 Tomasz Boleslaw CEDRO (http://www.tomek.cedro.info)
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef TRANSPORT_H
  20 #define TRANSPORT_H
  21
  22 #include "helper/command.h"
  23
  24 /**
  25  * Wrapper for transport lifecycle operations.
  26  *
  27  * OpenOCD talks to targets through some kind of debugging
  28  * or programming adapter, using some protocol that probably
  29  * has target-specific aspects.
  30  *
  31  * A "transport" reflects electrical protocol to the target,
  32  * e..g jtag, swd, spi, uart, ... NOT the messaging protocols
  33  * layered over it (e.g. JTAG has eICE, CoreSight, Nexus, OnCE,
  34  * and more).
  35  *
  36  * In addition to the lifecycle operations packaged by this
  37  * structure, a transport also involves  an interface supported
  38  * by debug adapters and used by components such as debug targets.
  39  * For non-debug transports,  there may be interfaces used to
  40  * write to flash chips.
  41  */
  42 struct transport {
  43         /**
  44          * Each transport has a unique name, used to select it
  45          * from among the alternatives.  Examples might include
  46          * "jtag", * "swd", "AVR_ISP" and more.
  47          */
  48         const char *name;
  49
  50         /**
  51          * When a transport is selected, this method registers
  52          * its commands and activates the transport (e.g. resets
  53          * the link).
  54          *
  55          * After those commands are registered, they will often
  56          * be used for further configuration of the debug link.
  57          */
  58         int (*select)(struct command_context *ctx);
  59
  60         /**
  61          * server startup uses this method to validate transport
  62          * configuration.  (For example, with JTAG this interrogates
  63          * the scan chain against the list of expected TAPs.)
  64          */
  65         int (*init)(struct command_context *ctx);
  66
  67         /**
  68          * Optional. If defined, allows transport to override target
  69          * name prior to initialisation.
  70          *
  71          * @returns ERROR_OK on success, or an error code on failure.
  72          */
  73         int (*override_target)(const char **targetname);
  74
  75         /**
  76          * Transports are stored in a singly linked list.
  77          */
  78         struct transport *next;
  79 };
  80
  81 int transport_register(struct transport *new_transport);
  82
  83 struct transport *get_current_transport(void);
  84
  85 int transport_register_commands(struct command_context *ctx);
  86
  87 COMMAND_HELPER(transport_list_parse, char ***vector);
  88
  89 int allow_transports(struct command_context *ctx, const char * const *vector);
  90
  91 bool transports_are_declared(void);
  92
  93 #endif