Remove FSF address from GPL notices

[openocd.git] / src / jtag / interface.h

diff --git a/src/jtag/interface.h b/src/jtag/interface.h
index 958af8f5a518b5844db4322ae80a83c2f9830c1b..cdfc676eec8993607c5c44336cde4b0b623a7a8f 100644 (file)
--- a/src/jtag/interface.h
+++ b/src/jtag/interface.h
@@ -19,14 +19,14 @@
  *   GNU General Public License for more details.                          *
  *                                                                         *
  *   You should have received a copy of the GNU General Public License     *
- *   along with this program; if not, write to the                         *
- *   Free Software Foundation, Inc.,                                       *
- *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
+ *   along with this program.  If not, see <http://www.gnu.org/licenses/>. *
  ***************************************************************************/
+
 #ifndef OPENOCD_JTAG_INTERFACE_H
 #define OPENOCD_JTAG_INTERFACE_H
 
 #include <jtag/jtag.h>
+#include <target/armv7m_trace.h>
 
 /* @file
  * The "Cable Helper API" is what the cable drivers can use to help
@@ -54,7 +54,7 @@ void tap_set_state_impl(tap_state_t new_state);
  * expected to traverse, not just end points of a multi-step state path.
  *
  * @param new_state The state we think the TAPs are currently in (or
- *     are about to enter).
+ * are about to enter).
  */
 #if defined(_DEBUG_JTAG_IO_)
 #define tap_set_state(new_state) \
@@ -85,7 +85,7 @@ tap_state_t tap_get_state(void);
  * state follower via tap_set_state().
  *
  * @param new_end_state The state the TAPs should enter at completion of
- *     a pending TAP operation.
+ * a pending TAP operation.
  */
 void tap_set_end_state(tap_state_t new_end_state);
 
@@ -106,11 +106,10 @@ tap_state_t tap_get_end_state(void);
  * @param from The starting state.
  * @param to The desired final state.
  * @return int The required TMS bit sequence, with the first bit in the
- *     sequence at bit 0.
+ * sequence at bit 0.
  */
 int tap_get_tms_path(tap_state_t from, tap_state_t to);
 
-
 /**
  * Function int tap_get_tms_path_len
  * returns the total number of bits that represents a TMS path
@@ -160,9 +159,9 @@ bool tap_is_state_stable(tap_state_t astate);
  */
 tap_state_t tap_state_transition(tap_state_t current_state, bool tms);
 
-/// Allow switching between old and new TMS tables. @see tap_get_tms_path
+/** Allow switching between old and new TMS tables. @see tap_get_tms_path */
 void tap_use_new_tms_table(bool use_new);
-/// @returns True if new TMS table is active; false otherwise.
+/** @returns True if new TMS table is active; false otherwise. */
 bool tap_uses_new_tms_table(void);
 
 #ifdef _DEBUG_JTAG_IO_
@@ -182,7 +181,7 @@ static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
 {
        return start_tap_state;
 }
-#endif // _DEBUG_JTAG_IO_
+#endif /* _DEBUG_JTAG_IO_ */
 
 /**
  * Represents a driver for a debugging interface.
@@ -197,8 +196,8 @@ static inline tap_state_t jtag_debug_state_machine(const void *tms_buf,
  * debugging interface.
  */
 struct jtag_interface {
-       /// The name of the JTAG interface driver.
-       char* name;
+       /** The name of the JTAG interface driver. */
+       const char * const name;
 
        /**
         * Bit vector listing capabilities exposed by this driver.
@@ -207,7 +206,7 @@ struct jtag_interface {
 #define DEBUG_CAP_TMS_SEQ      (1 << 0)
 
        /** transports supported in C code (NULL terminated vector) */
-       const char **transports;
+       const char * const *transports;
 
        const struct swd_driver *swd;
 
@@ -231,8 +230,14 @@ struct jtag_interface {
        const struct command_registration *commands;
 
        /**
-        * Interface driver must initalize any resources and connect to a
+        * Interface driver must initialize any resources and connect to a
         * JTAG device.
+        *
+        * quit() is invoked if and only if init() succeeds. quit() is always
+        * invoked if init() succeeds. Same as malloc() + free(). Always
+        * invoke free() if malloc() succeeds and do not invoke free()
+        * otherwise.
+        *
         * @returns ERROR_OK on success, or an error code on failure.
         */
        int (*init)(void);
@@ -240,6 +245,7 @@ struct jtag_interface {
        /**
         * Interface driver must tear down all resources and disconnect from
         * the JTAG device.
+        *
         * @returns ERROR_OK on success, or an error code on failure.
         */
        int (*quit)(void);
@@ -254,7 +260,7 @@ struct jtag_interface {
         *  and use a fallback kHz TCK.
         * @returns ERROR_OK on success, or an error code on failure.
         */
-       int (*khz)(int khz, int* jtag_speed);
+       int (*khz)(int khz, int *jtag_speed);
 
        /**
         * Calculate the clock frequency (in KHz) for the given @a speed.
@@ -263,7 +269,7 @@ struct jtag_interface {
         * @returns ERROR_OK on success, or an error code if the
         * interface cannot support the specified speed (KHz or RTCK).
         */
-       int (*speed_div)(int speed, int* khz);
+       int (*speed_div)(int speed, int *khz);
 
        /**
         * Read and clear the power dropout flag. Note that a power dropout
@@ -276,7 +282,7 @@ struct jtag_interface {
         *
         * @returns ERROR_OK on success, or an error code on failure.
         */
-       int (*power_dropout)(int* power_dropout);
+       int (*power_dropout)(int *power_dropout);
 
        /**
         * Read and clear the srst asserted detection flag.
@@ -290,12 +296,40 @@ struct jtag_interface {
         * been asserted.
         * @returns ERROR_OK on success, or an error code on failure.
         */
-       int (*srst_asserted)(int* srst_asserted);
-};
+       int (*srst_asserted)(int *srst_asserted);
 
+       /**
+        * Configure trace parameters for the adapter
+        *
+        * @param enabled Whether to enable trace
+        * @param pin_protocol Configured pin protocol
+        * @param port_size Trace port width for sync mode
+        * @param trace_freq A pointer to the configured trace
+        * frequency; if it points to 0, the adapter driver must write
+        * its maximum supported rate there
+        * @returns ERROR_OK on success, an error code on failure.
+        */
+       int (*config_trace)(bool enabled, enum tpio_pin_protocol pin_protocol,
+                           uint32_t port_size, unsigned int *trace_freq);
+
+       /**
+        * Poll for new trace data
+        *
+        * @param buf A pointer to buffer to store received data
+        * @param size A pointer to buffer size; must be filled with
+        * the actual amount of bytes written
+        *
+        * @returns ERROR_OK on success, an error code on failure.
+        */
+       int (*poll_trace)(uint8_t *buf, size_t *size);
+};
 
-extern const char *jtag_only[];
+extern const char * const jtag_only[];
 
-extern const struct swd_driver *swd;
+void adapter_assert_reset(void);
+void adapter_deassert_reset(void);
+int adapter_config_trace(bool enabled, enum tpio_pin_protocol pin_protocol,
+                        uint32_t port_size, unsigned int *trace_freq);
+int adapter_poll_trace(uint8_t *buf, size_t *size);
 
-#endif // OPENOCD_JTAG_INTERFACE_H
+#endif /* OPENOCD_JTAG_INTERFACE_H */