]> git.sur5r.net Git - openocd/blob - src/target/target.h
First step in hiding target_type_s from public interface:
[openocd] / src / target / target.h
1 /***************************************************************************
2  *   Copyright (C) 2005 by Dominic Rath                                    *
3  *   Dominic.Rath@gmx.de                                                   *
4  *                                                                         *
5  *   Copyright (C) 2007,2008 Ã˜yvind Harboe                                 *
6  *   oyvind.harboe@zylin.com                                               *
7  *                                                                         *
8  *   Copyright (C) 2008 by Spencer Oliver                                  *
9  *   spen@spen-soft.co.uk                                                  *
10  *                                                                         *
11  *   This program is free software; you can redistribute it and/or modify  *
12  *   it under the terms of the GNU General Public License as published by  *
13  *   the Free Software Foundation; either version 2 of the License, or     *
14  *   (at your option) any later version.                                   *
15  *                                                                         *
16  *   This program is distributed in the hope that it will be useful,       *
17  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
18  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
19  *   GNU General Public License for more details.                          *
20  *                                                                         *
21  *   You should have received a copy of the GNU General Public License     *
22  *   along with this program; if not, write to the                         *
23  *   Free Software Foundation, Inc.,                                       *
24  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
25  ***************************************************************************/
26 #ifndef TARGET_H
27 #define TARGET_H
28
29 #include "breakpoints.h"
30 #include "algorithm.h"
31 #include "command.h"
32
33 struct reg_s;
34 struct trace_s;
35 struct command_context_s;
36
37 /*
38  * TARGET_UNKNOWN = 0: we don't know anything about the target yet
39  * TARGET_RUNNING = 1: the target is executing user code
40  * TARGET_HALTED  = 2: the target is not executing code, and ready to talk to the
41  * debugger. on an xscale it means that the debug handler is executing
42  * TARGET_RESET   = 3: the target is being held in reset (only a temporary state,
43  * not sure how this is used with all the recent changes)
44  * TARGET_DEBUG_RUNNING = 4: the target is running, but it is executing code on
45  * behalf of the debugger (e.g. algorithm for flashing) */
46
47 enum target_state
48 {
49         TARGET_UNKNOWN = 0,
50         TARGET_RUNNING = 1,
51         TARGET_HALTED = 2,
52         TARGET_RESET = 3,
53         TARGET_DEBUG_RUNNING = 4,
54 };
55
56 extern const Jim_Nvp nvp_target_state[];
57
58 enum nvp_assert {
59         NVP_DEASSERT,
60         NVP_ASSERT,
61 };
62
63 extern const Jim_Nvp nvp_assert[];
64
65 enum target_reset_mode
66 {
67         RESET_UNKNOWN = 0,
68         RESET_RUN = 1,          /* reset and let target run */
69         RESET_HALT = 2,         /* reset and halt target out of reset */
70         RESET_INIT = 3,         /* reset and halt target out of reset, then run init script */
71 };
72
73 extern const Jim_Nvp nvp_reset_mode[];
74
75 enum target_debug_reason
76 {
77         DBG_REASON_DBGRQ = 0,
78         DBG_REASON_BREAKPOINT = 1,
79         DBG_REASON_WATCHPOINT = 2,
80         DBG_REASON_WPTANDBKPT = 3,
81         DBG_REASON_SINGLESTEP = 4,
82         DBG_REASON_NOTHALTED = 5,
83         DBG_REASON_UNDEFINED = 6
84 };
85
86 extern const Jim_Nvp nvp_target_debug_reason[];
87
88 enum target_endianess
89 {
90         TARGET_ENDIAN_UNKNOWN=0,
91         TARGET_BIG_ENDIAN = 1, TARGET_LITTLE_ENDIAN = 2
92 };
93
94 extern const Jim_Nvp nvp_target_endian[];
95
96 struct target_s;
97
98 typedef struct working_area_s
99 {
100         u32 address;
101         u32 size;
102         int free;
103         u8 *backup;
104         struct working_area_s **user;
105         struct working_area_s *next;
106 } working_area_t;
107
108 #ifdef DEFINE_TARGET_TYPE_S
109 struct target_type_s
110 {
111         /**
112          * Name of the target.  Do @b not access this field directly, use
113          * target_get_name() instead.
114          */
115         char *name;
116
117         /**
118          * Indicates whether this target has been examined.
119          *
120          * Do @b not access this field directly, use target_was_examined()
121          * target_set_examined(), and target_reset_examined().
122          */
123         int examined;
124
125         /* poll current target status */
126         int (*poll)(struct target_s *target);
127         /* Invoked only from target_arch_state().
128          * Issue USER() w/architecture specific status.  */
129         int (*arch_state)(struct target_s *target);
130
131         /* target request support */
132         int (*target_request_data)(struct target_s *target, u32 size, u8 *buffer);
133
134         /* halt will log a warning, but return ERROR_OK if the target is already halted. */
135         int (*halt)(struct target_s *target);
136         int (*resume)(struct target_s *target, int current, u32 address, int handle_breakpoints, int debug_execution);
137         int (*step)(struct target_s *target, int current, u32 address, int handle_breakpoints);
138
139         /* target reset control. assert reset can be invoked when OpenOCD and
140          * the target is out of sync.
141          *
142          * A typical example is that the target was power cycled while OpenOCD
143          * thought the target was halted or running.
144          *
145          * assert_reset() can therefore make no assumptions whatsoever about the
146          * state of the target
147          *
148          * Before assert_reset() for the target is invoked, a TRST/tms and
149          * chain validation is executed. TRST should not be asserted
150          * during target assert unless there is no way around it due to
151          * the way reset's are configured.
152          *
153          */
154         int (*assert_reset)(struct target_s *target);
155         int (*deassert_reset)(struct target_s *target);
156         int (*soft_reset_halt_imp)(struct target_s *target);
157         int (*soft_reset_halt)(struct target_s *target);
158
159         /**
160          * Target register access for GDB.  Do @b not call this function
161          * directly, use target_get_gdb_reg_list() instead.
162          *
163          * Danger! this function will succeed even if the target is running
164          * and return a register list with dummy values.
165          *
166          * The reason is that GDB connection will fail without a valid register
167          * list, however it is after GDB is connected that monitor commands can
168          * be run to properly initialize the target
169          */
170         int (*get_gdb_reg_list)(struct target_s *target, struct reg_s **reg_list[], int *reg_list_size);
171
172         /* target memory access
173         * size: 1 = byte (8bit), 2 = half-word (16bit), 4 = word (32bit)
174         * count: number of items of <size>
175         */
176         int (*read_memory_imp)(struct target_s *target, u32 address, u32 size, u32 count, u8 *buffer);
177         /**
178          * Target memory read callback.  Do @b not call this function
179          * directly, use target_read_memory() instead.
180          */
181         int (*read_memory)(struct target_s *target, u32 address, u32 size, u32 count, u8 *buffer);
182         int (*write_memory_imp)(struct target_s *target, u32 address, u32 size, u32 count, u8 *buffer);
183         /**
184          * Target memory write callback.  Do @b not call this function
185          * directly, use target_write_memory() instead.
186          */
187         int (*write_memory)(struct target_s *target, u32 address, u32 size, u32 count, u8 *buffer);
188
189         /**
190          * Write target memory in multiples of 4 bytes, optimized for
191          * writing large quantities of data.  Do @b not call this
192          * function directly, use target_bulk_write_memory() instead.
193          */
194         int (*bulk_write_memory)(struct target_s *target, u32 address, u32 count, u8 *buffer);
195
196         int (*checksum_memory)(struct target_s *target, u32 address, u32 count, u32* checksum);
197         int (*blank_check_memory)(struct target_s *target, u32 address, u32 count, u32* blank);
198
199         /*
200          * target break-/watchpoint control
201          * rw: 0 = write, 1 = read, 2 = access
202          *
203          * Target must be halted while this is invoked as this
204          * will actually set up breakpoints on target.
205          *
206          * The breakpoint hardware will be set up upon adding the first breakpoint.
207          *
208          * Upon GDB connection all breakpoints/watchpoints are cleared.
209          */
210         int (*add_breakpoint)(struct target_s *target, breakpoint_t *breakpoint);
211
212         /* remove breakpoint. hw will only be updated if the target is currently halted.
213          * However, this method can be invoked on unresponsive targets.
214          */
215         int (*remove_breakpoint)(struct target_s *target, breakpoint_t *breakpoint);
216         int (*add_watchpoint)(struct target_s *target, watchpoint_t *watchpoint);
217         /* remove watchpoint. hw will only be updated if the target is currently halted.
218          * However, this method can be invoked on unresponsive targets.
219          */
220         int (*remove_watchpoint)(struct target_s *target, watchpoint_t *watchpoint);
221
222         /* target algorithm support */
223         int (*run_algorithm_imp)(struct target_s *target, int num_mem_params, mem_param_t *mem_params, int num_reg_params, reg_param_t *reg_param, u32 entry_point, u32 exit_point, int timeout_ms, void *arch_info);
224         /**
225          * Target algorithm support.  Do @b not call this method directly,
226          * use target_run_algorithm() instead.
227          */
228         int (*run_algorithm)(struct target_s *target, int num_mem_params, mem_param_t *mem_params, int num_reg_params, reg_param_t *reg_param, u32 entry_point, u32 exit_point, int timeout_ms, void *arch_info);
229
230         int (*register_commands)(struct command_context_s *cmd_ctx);
231
232         /* called when target is created */
233         int (*target_create)( struct target_s *target, Jim_Interp *interp );
234
235         /* called for various config parameters */
236         /* returns JIM_CONTINUE - if option not understood */
237         /* otherwise: JIM_OK, or JIM_ERR, */
238         int (*target_jim_configure)( struct target_s *target, Jim_GetOptInfo *goi );
239
240         /* target commands specifically handled by the target */
241         /* returns JIM_OK, or JIM_ERR, or JIM_CONTINUE - if option not understood */
242         int (*target_jim_commands)( struct target_s *target, Jim_GetOptInfo *goi );
243
244         /* invoked after JTAG chain has been examined & validated. During
245          * this stage the target is examined and any additional setup is
246          * performed.
247          *
248          * invoked every time after the jtag chain has been validated/examined
249          */
250         int (*examine)(struct target_s *target);
251         /* Set up structures for target.
252          *
253          * It is illegal to talk to the target at this stage as this fn is invoked
254          * before the JTAG chain has been examined/verified
255          * */
256         int (*init_target)(struct command_context_s *cmd_ctx, struct target_s *target);
257         int (*quit)(void);
258
259         int (*virt2phys)(struct target_s *target, u32 address, u32 *physical);
260         int (*mmu)(struct target_s *target, int *enabled);
261
262 };
263 #else
264 struct target_type_s;
265 #endif // DEFINE_TARGET_TYPE_S
266 typedef struct target_type_s target_type_t;
267
268 /* forward decloration */
269 typedef struct target_event_action_s target_event_action_t;
270
271 typedef struct target_s
272 {
273         target_type_t *type;                            /* target type definition (name, access functions) */
274         const char *cmd_name;                           /* tcl Name of target */
275         int target_number;                                      /* generaly, target index but may not be in order */
276         jtag_tap_t *tap;                                        /* where on the jtag chain is this */
277         const char *variant;                            /* what varient of this chip is it? */
278         target_event_action_t *event_action;
279
280         int reset_halt;                                         /* attempt resetting the CPU into the halted mode? */
281         u32 working_area;                                       /* working area (initialized RAM). Evaluated
282                                                                                  * upon first allocation from virtual/physical address. */
283         u32 working_area_virt;                          /* virtual address */
284         u32 working_area_phys;                          /* physical address */
285         u32 working_area_size;                          /* size in bytes */
286         u32 backup_working_area;                        /* whether the content of the working area has to be preserved */
287         struct working_area_s *working_areas;/* list of allocated working areas */
288         enum target_debug_reason debug_reason;/* reason why the target entered debug state */
289         enum target_endianess endianness;       /* target endianess */
290         enum target_state state;                        /* the current backend-state (running, halted, ...) */
291         struct reg_cache_s *reg_cache;          /* the first register cache of the target (core regs) */
292         struct breakpoint_s *breakpoints;       /* list of breakpoints */
293         struct watchpoint_s *watchpoints;       /* list of watchpoints */
294         struct trace_s *trace_info;                     /* generic trace information */
295         struct debug_msg_receiver_s *dbgmsg;/* list of debug message receivers */
296         u32 dbg_msg_enabled;                            /* debug message status */
297         void *arch_info;                                        /* architecture specific information */
298         struct target_s *next;                          /* next target in list */
299
300         int display;                                            /* display async info in telnet session. Do not display
301                                                                                  * lots of halted/resumed info when stepping in debugger. */
302 } target_t;
303
304 enum target_event
305 {
306         /* LD historical names
307          * - Prior to the great TCL change
308          * - June/July/Aug 2008
309          * - Duane Ellis */
310         TARGET_EVENT_OLD_gdb_program_config,
311         TARGET_EVENT_OLD_pre_reset,
312         TARGET_EVENT_OLD_post_reset,
313         TARGET_EVENT_OLD_pre_resume,
314
315         /* allow GDB to do stuff before others handle the halted event,
316          * this is in lieu of defining ordering of invocation of events,
317          * which would be more complicated */
318         TARGET_EVENT_EARLY_HALTED,
319         TARGET_EVENT_HALTED,            /* target entered debug state from normal execution or reset */
320         TARGET_EVENT_RESUMED,           /* target resumed to normal execution */
321         TARGET_EVENT_RESUME_START,
322         TARGET_EVENT_RESUME_END,
323
324         TARGET_EVENT_GDB_START, /* debugger started execution (step/run) */
325         TARGET_EVENT_GDB_END, /* debugger stopped execution (step/run) */
326
327         TARGET_EVENT_RESET_START,
328         TARGET_EVENT_RESET_ASSERT_PRE,
329         TARGET_EVENT_RESET_ASSERT_POST,
330         TARGET_EVENT_RESET_DEASSERT_PRE,
331         TARGET_EVENT_RESET_DEASSERT_POST,
332         TARGET_EVENT_RESET_HALT_PRE,
333         TARGET_EVENT_RESET_HALT_POST,
334         TARGET_EVENT_RESET_WAIT_PRE,
335         TARGET_EVENT_RESET_WAIT_POST,
336         TARGET_EVENT_RESET_INIT,
337         TARGET_EVENT_RESET_END,
338
339         TARGET_EVENT_DEBUG_HALTED,      /* target entered debug state, but was executing on behalf of the debugger */
340         TARGET_EVENT_DEBUG_RESUMED, /* target resumed to execute on behalf of the debugger */
341
342         TARGET_EVENT_EXAMINE_START,
343         TARGET_EVENT_EXAMINE_END,
344
345         TARGET_EVENT_GDB_ATTACH,
346         TARGET_EVENT_GDB_DETACH,
347
348         TARGET_EVENT_GDB_FLASH_ERASE_START,
349         TARGET_EVENT_GDB_FLASH_ERASE_END,
350         TARGET_EVENT_GDB_FLASH_WRITE_START,
351         TARGET_EVENT_GDB_FLASH_WRITE_END,
352 };
353
354 struct target_event_action_s {
355         enum target_event event;
356         Jim_Obj *body;
357         int has_percent;
358         target_event_action_t *next;
359  };
360
361 typedef struct target_event_callback_s
362 {
363         int (*callback)(struct target_s *target, enum target_event event, void *priv);
364         void *priv;
365         struct target_event_callback_s *next;
366 } target_event_callback_t;
367
368 typedef struct target_timer_callback_s
369 {
370         int (*callback)(void *priv);
371         int time_ms;
372         int periodic;
373         struct timeval when;
374         void *priv;
375         struct target_timer_callback_s *next;
376 } target_timer_callback_t;
377
378 extern int target_register_commands(struct command_context_s *cmd_ctx);
379 extern int target_register_user_commands(struct command_context_s *cmd_ctx);
380 extern int target_init(struct command_context_s *cmd_ctx);
381 extern int target_examine(void);
382 extern int handle_target(void *priv);
383 extern int target_process_reset(struct command_context_s *cmd_ctx, enum target_reset_mode reset_mode);
384
385 extern int target_register_event_callback(int (*callback)(struct target_s *target, enum target_event event, void *priv), void *priv);
386 extern int target_unregister_event_callback(int (*callback)(struct target_s *target, enum target_event event, void *priv), void *priv);
387 extern int target_poll(target_t *target);
388 extern int target_resume(target_t *target, int current, u32 address, int handle_breakpoints, int debug_execution);
389 extern int target_halt(target_t *target);
390 extern int target_call_event_callbacks(target_t *target, enum target_event event);
391
392 /* The period is very approximate, the callback can happen much more often
393  * or much more rarely than specified
394  */
395 extern int target_register_timer_callback(int (*callback)(void *priv), int time_ms, int periodic, void *priv);
396 extern int target_unregister_timer_callback(int (*callback)(void *priv), void *priv);
397 extern int target_call_timer_callbacks(void);
398 /* invoke this to ensure that e.g. polling timer callbacks happen before
399  * a syncrhonous command completes.
400  */
401 extern int target_call_timer_callbacks_now(void);
402
403 extern target_t* get_current_target(struct command_context_s *cmd_ctx);
404 extern int get_num_by_target(target_t *query_target);
405 extern target_t *get_target(const char *id);
406
407 /**
408  * Get the target name.
409  *
410  * This routine is a wrapper for the target->type->name field.
411  */
412 extern const char *target_get_name(struct target_s *target);
413
414 /**
415  * Examine the specified @a target.
416  *
417  * This routine is a wrapper for target->type->examine.
418  */
419 extern int target_examine_one(struct target_s *target);
420 /// @returns @c true if the target has been examined.
421 extern bool target_was_examined(struct target_s *target);
422 /// Sets the @c examined flag for the given target.
423 extern void target_set_examined(struct target_s *target);
424 /// Reset the @c examined flag for the given target.
425 extern void target_reset_examined(struct target_s *target);
426
427
428 /**
429  * Add the @a breakpoint for @a target.
430  *
431  * This routine is a wrapper for target->type->add_breakpoint.
432  */
433 extern int target_add_breakpoint(struct target_s *target,
434                 struct breakpoint_s *breakpoint);
435 /**
436  * Remove the @a breakpoint for @a target.
437  *
438  * This routine is a wrapper for target->type->remove_breakpoint.
439  */
440 extern int target_remove_breakpoint(struct target_s *target,
441                 struct breakpoint_s *breakpoint);
442 /**
443  * Add the @a watchpoint for @a target.
444  *
445  * This routine is a wrapper for target->type->add_watchpoint.
446  */
447 extern int target_add_watchpoint(struct target_s *target,
448                 struct watchpoint_s *watchpoint);
449 /**
450  * Remove the @a watchpoint for @a target.
451  *
452  * This routine is a wrapper for target->type->remove_watchpoint.
453  */
454 extern int target_remove_watchpoint(struct target_s *target,
455                 struct watchpoint_s *watchpoint);
456
457 /**
458  * Obtain the registers for GDB.
459  *
460  * This routine is a wrapper for target->type->get_gdb_reg_list.
461  */
462 extern int target_get_gdb_reg_list(struct target_s *target,
463                 struct reg_s **reg_list[], int *reg_list_size);
464
465 /**
466  * Step the target.
467  *
468  * This routine is a wrapper for target->type->step.
469  */
470 int target_step(struct target_s *target,
471                 int current, u32 address, int handle_breakpoints);
472 /**
473  * Run an algorithm on the @a target given.
474  *
475  * This routine is a wrapper for target->type->run_algorithm.
476  */
477 extern int target_run_algorithm(struct target_s *target,
478                 int num_mem_params, mem_param_t *mem_params,
479                 int num_reg_params, reg_param_t *reg_param,
480                 u32 entry_point, u32 exit_point,
481                 int timeout_ms, void *arch_info);
482
483 /**
484  * Read @count items of @a size bytes from the memory of @a target at
485  * the @a address given.
486  *
487  * This routine is a wrapper for target->type->read_memory.
488  */
489 extern int target_read_memory(struct target_s *target,
490                 u32 address, u32 size, u32 count, u8 *buffer);
491 /**
492  * Write @count items of @a size bytes to the memory of @a target at
493  * the @a address given.
494  *
495  * This routine is wrapper for target->type->write_memory.
496  */
497 extern int target_write_memory(struct target_s *target,
498                 u32 address, u32 size, u32 count, u8 *buffer);
499
500 /**
501  * Write @count items of 4 bytes to the memory of @a target at
502  * the @a address given.  Because it operates only on whole words,
503  * this should be faster than target_write_memory().
504  *
505  * This routine is wrapper for target->type->bulk_write_memory.
506  */
507 extern int target_bulk_write_memory(struct target_s *target,
508                 u32 address, u32 count, u8 *buffer);
509
510 extern int target_write_buffer(struct target_s *target, u32 address, u32 size, u8 *buffer);
511 extern int target_read_buffer(struct target_s *target, u32 address, u32 size, u8 *buffer);
512 extern int target_checksum_memory(struct target_s *target, u32 address, u32 size, u32* crc);
513 extern int target_blank_check_memory(struct target_s *target, u32 address, u32 size, u32* blank);
514 extern int target_wait_state(target_t *target, enum target_state state, int ms);
515
516 /* DANGER!!!!!
517  *
518  * if "area" passed in to target_alloc_working_area() points to a memory
519  * location that goes out of scope (e.g. a pointer on the stack), then
520  * the caller of target_alloc_working_area() is responsible for invoking
521  * target_free_working_area() before "area" goes out of scope.
522  *
523  * target_free_all_working_areas() will NULL out the "area" pointer
524  * upon resuming or resetting the CPU.
525  *
526  */
527 extern int target_alloc_working_area(struct target_s *target, u32 size, working_area_t **area);
528 extern int target_free_working_area(struct target_s *target, working_area_t *area);
529 extern int target_free_working_area_restore(struct target_s *target, working_area_t *area, int restore);
530 extern void target_free_all_working_areas(struct target_s *target);
531 extern void target_free_all_working_areas_restore(struct target_s *target, int restore);
532
533 extern target_t *all_targets;
534
535 extern target_event_callback_t *target_event_callbacks;
536 extern target_timer_callback_t *target_timer_callbacks;
537
538 extern u32 target_buffer_get_u32(target_t *target, const u8 *buffer);
539 extern u16 target_buffer_get_u16(target_t *target, const u8 *buffer);
540 extern u8  target_buffer_get_u8 (target_t *target, const u8 *buffer);
541 extern void target_buffer_set_u32(target_t *target, u8 *buffer, u32 value);
542 extern void target_buffer_set_u16(target_t *target, u8 *buffer, u16 value);
543 extern void target_buffer_set_u8 (target_t *target, u8 *buffer, u8  value);
544
545 int target_read_u32(struct target_s *target, u32 address, u32 *value);
546 int target_read_u16(struct target_s *target, u32 address, u16 *value);
547 int target_read_u8(struct target_s *target, u32 address, u8 *value);
548 int target_write_u32(struct target_s *target, u32 address, u32 value);
549 int target_write_u16(struct target_s *target, u32 address, u16 value);
550 int target_write_u8(struct target_s *target, u32 address, u8 value);
551
552 /* Issues USER() statements with target state information */
553 int target_arch_state(struct target_s *target);
554
555 void target_handle_event( target_t *t, enum target_event e);
556 void target_all_handle_event( enum target_event e );
557
558 #define ERROR_TARGET_INVALID    (-300)
559 #define ERROR_TARGET_INIT_FAILED (-301)
560 #define ERROR_TARGET_TIMEOUT    (-302)
561 #define ERROR_TARGET_NOT_HALTED (-304)
562 #define ERROR_TARGET_FAILURE    (-305)
563 #define ERROR_TARGET_UNALIGNED_ACCESS   (-306)
564 #define ERROR_TARGET_DATA_ABORT (-307)
565 #define ERROR_TARGET_RESOURCE_NOT_AVAILABLE     (-308)
566 #define ERROR_TARGET_TRANSLATION_FAULT  (-309)
567 #define ERROR_TARGET_NOT_RUNNING (-310)
568 #define ERROR_TARGET_NOT_EXAMINED (-311)
569
570 extern const Jim_Nvp nvp_error_target[];
571 extern const char *target_strerror_safe( int err );
572
573 #endif /* TARGET_H */