doxygen: remove warnings
[openocd.git] / src / target / dsp5680xx.h
1 /***************************************************************************
2 * Copyright (C) 2011 by Rodrigo L. Rosa *
3 * rodrigorosa.LG@gmail.com *
4 * *
5 * Based on dsp563xx_once.h written by Mathias Kuester *
6 * mkdorg@users.sourceforge.net *
7 * *
8 * This program is free software; you can redistribute it and/or modify *
9 * it under the terms of the GNU General Public License as published by *
10 * the Free Software Foundation; either version 2 of the License, or *
11 * (at your option) any later version. *
12 * *
13 * This program is distributed in the hope that it will be useful, *
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16 * GNU General Public License for more details. *
17 * *
18 * You should have received a copy of the GNU General Public License *
19 * along with this program; if not, write to the *
20 * Free Software Foundation, Inc., *
21 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
22 ***************************************************************************/
23
24 #ifndef DSP5680XX_H
25 #define DSP5680XX_H
26
27 #include <jtag/jtag.h>
28
29 /**
30 * @file dsp5680xx.h
31 * @author Rodrigo Rosa <rodrigorosa.LG@gmail.com>
32 * @date Thu Jun 9 18:54:38 2011
33 *
34 * @brief Basic support for the 5680xx DSP from Freescale.
35 * The chip has two taps in the JTAG chain, the Master tap and the Core tap.
36 * In this code the Master tap is only used to unlock the flash memory by executing a JTAG instruction.
37 *
38 */
39
40 #define S_FILE_DATA_OFFSET 0x200000
41 #define TIME_DIV_FREESCALE 0.3
42
43 /** ----------------------------------------------------------------
44 * JTAG
45 *----------------------------------------------------------------
46 */
47 #define DSP5680XX_JTAG_CORE_TAP_IRLEN 4
48 #define DSP5680XX_JTAG_MASTER_TAP_IRLEN 8
49
50 #define JTAG_STATUS_MASK 0x0F
51
52 #define JTAG_STATUS_NORMAL 0x01
53 #define JTAG_STATUS_STOPWAIT 0x05
54 #define JTAG_STATUS_BUSY 0x09
55 #define JTAG_STATUS_DEBUG 0x0D
56 #define JTAG_STATUS_DEAD 0x0f
57
58 #define JTAG_INSTR_EXTEST 0x0
59 #define JTAG_INSTR_SAMPLE_PRELOAD 0x1
60 #define JTAG_INSTR_IDCODE 0x2
61 #define JTAG_INSTR_EXTEST_PULLUP 0x3
62 #define JTAG_INSTR_HIGHZ 0x4
63 #define JTAG_INSTR_CLAMP 0x5
64 #define JTAG_INSTR_ENABLE_ONCE 0x6
65 #define JTAG_INSTR_DEBUG_REQUEST 0x7
66 #define JTAG_INSTR_BYPASS 0xF
67 /**
68 * ----------------------------------------------------------------
69 */
70
71 /** ----------------------------------------------------------------
72 * Master TAP instructions from MC56F8000RM.pdf
73 * ----------------------------------------------------------------
74 */
75 #define MASTER_TAP_CMD_BYPASS 0xF
76 #define MASTER_TAP_CMD_IDCODE 0x2
77 #define MASTER_TAP_CMD_TLM_SEL 0x5
78 #define MASTER_TAP_CMD_FLASH_ERASE 0x8
79 /**
80 * ----------------------------------------------------------------
81 */
82
83 /** ----------------------------------------------------------------
84 * EOnCE control register info
85 * ----------------------------------------------------------------
86 */
87 #define DSP5680XX_ONCE_OCR_EX (1<<5)
88 /* EX Bit Definition
89 0 Remain in the Debug Processing State
90 1 Leave the Debug Processing State */
91 #define DSP5680XX_ONCE_OCR_GO (1<<6)
92 /* GO Bit Definition
93 0 Inactive—No Action Taken
94 1 Execute Controller Instruction */
95 #define DSP5680XX_ONCE_OCR_RW (1<<7)
96 /** RW Bit Definition
97 * 0 Write To the Register Specified by the RS[4:0] Bits
98 * 1 ReadFrom the Register Specified by the RS[4:0] Bits
99 * ----------------------------------------------------------------
100 */
101
102 /** ----------------------------------------------------------------
103 * EOnCE Status Register
104 * ----------------------------------------------------------------
105 */
106 #define DSP5680XX_ONCE_OSCR_OS1 (1<<5)
107 #define DSP5680XX_ONCE_OSCR_OS0 (1<<4)
108 /**
109 * ----------------------------------------------------------------
110 */
111
112 /** ----------------------------------------------------------------
113 * EOnCE Core Status - Describes the operating status of the core controller
114 * ----------------------------------------------------------------
115 */
116 #define DSP5680XX_ONCE_OSCR_NORMAL_M (0)
117 /* 00 - Normal - Controller Core Executing Instructions or in Reset */
118 #define DSP5680XX_ONCE_OSCR_STOPWAIT_M (DSP5680XX_ONCE_OSCR_OS0)
119 /* 01 - Stop/Wait - Controller Core in Stop or Wait Mode */
120 #define DSP5680XX_ONCE_OSCR_BUSY_M (DSP5680XX_ONCE_OSCR_OS1)
121 /* 10 - Busy - Controller is Performing External or Peripheral Access (Wait States) */
122 #define DSP5680XX_ONCE_OSCR_DEBUG_M (DSP5680XX_ONCE_OSCR_OS0|DSP5680XX_ONCE_OSCR_OS1)
123 /* 11 - Debug - Controller Core Halted and in Debug Mode */
124 #define EONCE_STAT_MASK 0x30
125 /**
126 * ----------------------------------------------------------------
127 */
128
129 /** ----------------------------------------------------------------
130 * Register Select Encoding (eonce_rev.1.0_0208081.pdf:14)
131 * ----------------------------------------------------------------
132 */
133 #define DSP5680XX_ONCE_NOREG 0x00 /* No register selected */
134 #define DSP5680XX_ONCE_OCR 0x01 /* OnCE Debug Control Register */
135 #define DSP5680XX_ONCE_OCNTR 0x02 /* OnCE Breakpoint and Trace Counter */
136 #define DSP5680XX_ONCE_OSR 0x03 /* EOnCE status register */
137 #define DSP5680XX_ONCE_OBAR 0x04 /* OnCE Breakpoint Address Register */
138 #define DSP5680XX_ONCE_OBASE 0x05 /* EOnCE Peripheral Base Address register */
139 #define DSP5680XX_ONCE_OTXRXSR 0x06 /* EOnCE TXRX Status and Control Register (OTXRXSR) */
140 #define DSP5680XX_ONCE_OTX 0x07 /* EOnCE Transmit register (OTX) */
141 #define DSP5680XX_ONCE_OPDBR 0x08 /* EOnCE Program Data Bus Register (OPDBR) */
142 #define DSP5680XX_ONCE_OTX1 0x09 /* EOnCE Upper Transmit register (OTX1) */
143 #define DSP5680XX_ONCE_OPABFR 0x0A /* OnCE Program Address Register—Fetch cycle */
144 #define DSP5680XX_ONCE_ORX 0x0B /* EOnCE Receive register (ORX) */
145 #define DSP5680XX_ONCE_OCNTR_C 0x0C /* Clear OCNTR */
146 #define DSP5680XX_ONCE_ORX1 0x0D /* EOnCE Upper Receive register (ORX1) */
147 #define DSP5680XX_ONCE_OTBCR 0x0E /* EOnCE Trace Buffer Control Reg (OTBCR) */
148 #define DSP5680XX_ONCE_OPABER 0x10 /* OnCE Program Address Register—Execute cycle */
149 #define DSP5680XX_ONCE_OPFIFO 0x11 /* OnCE Program address FIFO */
150 #define DSP5680XX_ONCE_OBAR1 0x12 /* EOnCE Breakpoint 1 Unit 0 Address Reg.(OBAR1) */
151 #define DSP5680XX_ONCE_OPABDR 0x13 /* OnCE Program Address Register—Decode cycle (OPABDR) */
152 /**
153 * ----------------------------------------------------------------
154 */
155
156 #define FLUSH_COUNT_READ_WRITE 8192 /* This value works, higher values (and lower...) may work as well. */
157 #define FLUSH_COUNT_FLASH 8192
158 /** ----------------------------------------------------------------
159 * HFM (flash module) Commands (ref:MC56F801xRM.pdf:159)
160 * ----------------------------------------------------------------
161 */
162 #define HFM_ERASE_VERIFY 0x05
163 #define HFM_CALCULATE_DATA_SIGNATURE 0x06
164 #define HFM_WORD_PROGRAM 0x20
165 #define HFM_PAGE_ERASE 0x40
166 #define HFM_MASS_ERASE 0x41
167 #define HFM_CALCULATE_IFR_BLOCK_SIGNATURE 0x66
168 /**
169 * ----------------------------------------------------------------
170 */
171
172 /** ----------------------------------------------------------------
173 * Flashing (ref:MC56F801xRM.pdf:159)
174 * ----------------------------------------------------------------
175 */
176 #define HFM_BASE_ADDR 0x0F400 /** In x: mem. (write to S_FILE_DATA_OFFSET+HFM_BASE_ADDR
177 * to get data into x: mem.)
178 */
179 /**
180 * The following are register addresses, not memory
181 * addresses (though all registers are memory mapped)
182 */
183 #define HFM_CLK_DIV 0x00 /* r/w */
184 #define HFM_CNFG 0x01 /* r/w */
185 #define HFM_SECHI 0x03 /* r */
186 #define HFM_SECLO 0x04 /* r */
187 #define HFM_PROT 0x10 /* r/w */
188 #define HFM_PROTB 0x11 /* r/w */
189 #define HFM_USTAT 0x13 /* r/w */
190 #define HFM_CMD 0x14 /* r/w */
191 #define HFM_DATA 0x18 /* r */
192 #define HFM_OPT1 0x1B /* r */
193 #define HFM_TSTSIG 0x1D /* r */
194
195 #define HFM_EXEC_COMPLETE 0x40
196
197 /* User status register (USTAT) masks (MC56F80XXRM.pdf:6.7.5) */
198 #define HFM_USTAT_MASK_BLANK 0x4
199 #define HFM_USTAT_MASK_PVIOL_ACCER 0x30
200
201 /**
202 * The value used on for the FM clock is important to prevent flashing errors and to prevent deterioration of the FM.
203 * This value was calculated using a spreadsheet tool available on the Freescale website under FAQ 25464.
204 *
205 */
206 #define HFM_CLK_DEFAULT 0x27
207 /* 0x27 according to freescale cfg, but 0x40 according to freescale spreadsheet... */
208 #define HFM_FLASH_BASE_ADDR 0x0
209 #define HFM_SIZE_BYTES 0x4000 /* bytes */
210 #define HFM_SIZE_WORDS 0x2000 /* words */
211 #define HFM_SECTOR_SIZE 0x200 /* Size in bytes */
212 #define HFM_SECTOR_COUNT 0x20
213 /* A 16K block in pages of 256 words. */
214
215 /**
216 * Writing HFM_LOCK_FLASH to HFM_LOCK_ADDR_L and HFM_LOCK_ADDR_H will enable security on flash after the next reset.
217 */
218 #define HFM_LOCK_FLASH 0xE70A
219 #define HFM_LOCK_ADDR_L 0x1FF7
220 #define HFM_LOCK_ADDR_H 0x1FF8
221 /**
222 * ----------------------------------------------------------------
223 */
224
225 /** ----------------------------------------------------------------
226 * Register Memory Map (eonce_rev.1.0_0208081.pdf:16)
227 * ----------------------------------------------------------------
228 */
229 #define MC568013_EONCE_OBASE_ADDR 0xFF
230 /* The following are relative to EONCE_OBASE_ADDR (EONCE_OBASE_ADDR<<16 + ...) */
231 #define MC568013_EONCE_TX_RX_ADDR 0xFFFE
232 #define MC568013_EONCE_TX1_RX1_HIGH_ADDR 0xFFFF /* Relative to EONCE_OBASE_ADDR */
233 #define MC568013_EONCE_OCR 0xFFA0 /* Relative to EONCE_OBASE_ADDR */
234 /**
235 * ----------------------------------------------------------------
236 */
237
238 /** ----------------------------------------------------------------
239 * SIM addresses & commands (MC56F80xx.h from freescale)
240 * ----------------------------------------------------------------
241 */
242 #define MC568013_SIM_BASE_ADDR 0xF140
243 #define MC56803x_2x_SIM_BASE_ADDR 0xF100
244
245 #define SIM_CMD_RESET 0x10
246 /**
247 * ----------------------------------------------------------------
248 */
249
250 /**
251 * ----------------------------------------------------------------
252 * ERROR codes - enable automatic parsing of output
253 * ----------------------------------------------------------------
254 */
255 #define DSP5680XX_ERROR_UNKNOWN_OR_ERROR_OPENOCD -100
256 #define DSP5680XX_ERROR_JTAG_COMM -1
257 #define DSP5680XX_ERROR_JTAG_RESET -2
258 #define DSP5680XX_ERROR_JTAG_INVALID_TAP -3
259 #define DSP5680XX_ERROR_JTAG_DR_LEN_OVERFLOW -4
260 #define DSP5680XX_ERROR_INVALID_IR_LEN -5
261 #define DSP5680XX_ERROR_JTAG_TAP_ENABLE_MASTER -6
262 #define DSP5680XX_ERROR_JTAG_TAP_ENABLE_CORE -7
263 #define DSP5680XX_ERROR_JTAG_TAP_FIND_MASTER -8
264 #define DSP5680XX_ERROR_JTAG_TAP_FIND_CORE -9
265 #define DSP5680XX_ERROR_JTAG_DRSCAN -10
266 #define DSP5680XX_ERROR_JTAG_IRSCAN -11
267 #define DSP5680XX_ERROR_ENTER_DEBUG_MODE -12
268 #define DSP5680XX_ERROR_RESUME -13
269 #define DSP5680XX_ERROR_WRITE_WITH_TARGET_RUNNING -14
270 #define DSP5680XX_ERROR_INVALID_DATA_SIZE_UNIT -15
271 #define DSP5680XX_ERROR_PROTECT_CHECK_INVALID_ARGS -16
272 #define DSP5680XX_ERROR_FM_BUSY -17
273 #define DSP5680XX_ERROR_FM_CMD_TIMED_OUT -18
274 #define DSP5680XX_ERROR_FM_EXEC -19
275 #define DSP5680XX_ERROR_FM_SET_CLK -20
276 #define DSP5680XX_ERROR_FLASHING_INVALID_WORD_COUNT -21
277 #define DSP5680XX_ERROR_FLASHING_CRC -22
278 #define DSP5680XX_ERROR_FLASHING -23
279 #define DSP5680XX_ERROR_NOT_IMPLEMENTED_STEP -24
280 #define DSP5680XX_ERROR_HALT -25
281 #define DSP5680XX_ERROR_EXIT_DEBUG_MODE -26
282 #define DSP5680XX_ERROR_TARGET_RUNNING -27
283 #define DSP5680XX_ERROR_NOT_IN_DEBUG -28
284 /**
285 * ----------------------------------------------------------------
286 */
287
288 struct dsp5680xx_common {
289 uint32_t stored_pc;
290 int flush;
291 bool debug_mode_enabled;
292 };
293
294 extern struct dsp5680xx_common dsp5680xx_context;
295
296 static inline struct dsp5680xx_common *target_to_dsp5680xx(struct target
297 *target)
298 {
299 return target->arch_info;
300 }
301
302 /**
303 * Writes to flash memory.
304 * Does not check if flash is erased, it's up to the user to erase the flash before running
305 * this function.
306 * The flashing algorithm runs from RAM, reading from a register to which this function
307 * writes to. The algorithm is open loop, there is no control to verify that the FM read
308 * the register before writing the next data. A closed loop approach was much slower,
309 * and the current implementation does not fail, and if it did the crc check would detect it,
310 * allowing to flash again.
311 *
312 * @param target
313 * @param buffer
314 * @param address Word addressing.
315 * @param count In bytes.
316 * @param is_flash_lock
317 *
318 * @return
319 */
320 int dsp5680xx_f_wr(struct target *target, uint8_t * buffer, uint32_t address,
321 uint32_t count, int is_flash_lock);
322
323 /**
324 * The FM has the functionality of checking if the flash array is erased. This function
325 * executes it. It does not support individual sector analysis.
326 *
327 * @param target
328 * @param erased
329 * @param sector This parameter is ignored because the FM does not support checking if
330 * individual sectors are erased.
331 *
332 * @return
333 */
334 int dsp5680xx_f_erase_check(struct target *target, uint8_t * erased,
335 uint32_t sector);
336
337 /**
338 * Erases either a sector or the complete flash array. If either the range first-last covers
339 * the complete array or if first == 0 and last == 0 then a mass erase command is executed
340 * on the FM. If not, then individual sectors are erased.
341 *
342 * @param target
343 * @param first
344 * @param last
345 *
346 * @return
347 */
348 int dsp5680xx_f_erase(struct target *target, int first, int last);
349
350 /**
351 * Reads the memory mapped protection register. A 1 implies the sector is protected,
352 * a 0 implies the sector is not protected.
353 *
354 * @param target
355 * @param protected Data read from the protection register.
356 *
357 * @return
358 */
359 int dsp5680xx_f_protect_check(struct target *target, uint16_t * protected);
360
361 /**
362 * Writes the flash security words with a specific value. The chip's security will be
363 * enabled after the first reset following the execution of this function.
364 *
365 * @param target
366 *
367 * @return
368 */
369 int dsp5680xx_f_lock(struct target *target);
370
371 /**
372 * Executes a mass erase command. The must be done from the Master tap.
373 * It is up to the user to select the master tap (jtag tapenable dsp5680xx.chp)
374 * before running this function.
375 * The flash array will be unsecured (and erased) after the first reset following
376 * the execution of this function.
377 *
378 * @param target
379 *
380 * @return
381 */
382 int dsp5680xx_f_unlock(struct target *target);
383
384 #endif /* DSP5680XX_H */