Allow transports to override the selected target (hla configs unification)
[openocd.git] / 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, write to the Free Software Foundation,
17 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 */
19
20 #ifndef TRANSPORT_H
21 #define TRANSPORT_H
22
23 #include "helper/command.h"
24
25 /**
26 * Wrapper for transport lifecycle operations.
27 *
28 * OpenOCD talks to targets through some kind of debugging
29 * or programming adapter, using some protocol that probably
30 * has target-specific aspects.
31 *
32 * A "transport" reflects electrical protocol to the target,
33 * e..g jtag, swd, spi, uart, ... NOT the messaging protocols
34 * layered over it (e.g. JTAG has eICE, CoreSight, Nexus, OnCE,
35 * and more).
36 *
37 * In addition to the lifecycle operations packaged by this
38 * structure, a transport also involves an interface supported
39 * by debug adapters and used by components such as debug targets.
40 * For non-debug transports, there may be interfaces used to
41 * write to flash chips.
42 */
43 struct transport {
44 /**
45 * Each transport has a unique name, used to select it
46 * from among the alternatives. Examples might include
47 * "jtag", * "swd", "AVR_ISP" and more.
48 */
49 const char *name;
50
51 /**
52 * When a transport is selected, this method registers
53 * its commands and activates the transport (e.g. resets
54 * the link).
55 *
56 * After those commands are registered, they will often
57 * be used for further configuration of the debug link.
58 */
59 int (*select)(struct command_context *ctx);
60
61 /**
62 * server startup uses this method to validate transport
63 * configuration. (For example, with JTAG this interrogates
64 * the scan chain against the list of expected TAPs.)
65 */
66 int (*init)(struct command_context *ctx);
67
68 /**
69 * Optional. If defined, allows transport to override target
70 * name prior to initialisation.
71 *
72 * @returns ERROR_OK on success, or an error code on failure.
73 */
74 int (*override_target)(const char **targetname);
75
76 /**
77 * Transports are stored in a singly linked list.
78 */
79 struct transport *next;
80 };
81
82 int transport_register(struct transport *new_transport);
83
84 struct transport *get_current_transport(void);
85
86 int transport_register_commands(struct command_context *ctx);
87
88 COMMAND_HELPER(transport_list_parse, char ***vector);
89
90 int allow_transports(struct command_context *ctx, const char * const *vector);
91
92 bool transports_are_declared(void);
93
94 #endif