1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - CARD - include
3 File: backup.h
4
5 Copyright 2007-2008 Nintendo. All rights reserved.
6
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12
13 $Date:: 2008-10-21#$
14 $Rev: 9023 $
15 $Author: yosizaki $
16
17 *---------------------------------------------------------------------------*/
18 #ifndef NITRO_CARD_BACKUP_H_
19 #define NITRO_CARD_BACKUP_H_
20
21
22 #include <nitro/card/types.h>
23
24 #include <nitro/mi/dma.h>
25
26
27 #ifdef __cplusplus
28 extern "C"
29 {
30 #endif
31
32
33 /*---------------------------------------------------------------------------*/
34 /* Constants */
35
36 // Backup device type
37 #define CARD_BACKUP_TYPE_DEVICE_SHIFT 0
38 #define CARD_BACKUP_TYPE_DEVICE_MASK 0xFF
39 #define CARD_BACKUP_TYPE_DEVICE_EEPROM 1
40 #define CARD_BACKUP_TYPE_DEVICE_FLASH 2
41 #define CARD_BACKUP_TYPE_DEVICE_FRAM 3
42 #define CARD_BACKUP_TYPE_SIZEBIT_SHIFT 8
43 #define CARD_BACKUP_TYPE_SIZEBIT_MASK 0xFF
44 #define CARD_BACKUP_TYPE_VENDER_SHIFT 16
45 #define CARD_BACKUP_TYPE_VENDER_MASK 0xFF
46 #define CARD_BACKUP_TYPE_DEFINE(type, size, vender) \
47 (((CARD_BACKUP_TYPE_DEVICE_ ## type) << CARD_BACKUP_TYPE_DEVICE_SHIFT) | \
48 ((size) << CARD_BACKUP_TYPE_SIZEBIT_SHIFT) | \
49 ((vender) << CARD_BACKUP_TYPE_VENDER_SHIFT))
50
51 typedef enum CARDBackupType
52 {
53 CARD_BACKUP_TYPE_EEPROM_4KBITS = CARD_BACKUP_TYPE_DEFINE(EEPROM, 9, 0),
54 CARD_BACKUP_TYPE_EEPROM_64KBITS = CARD_BACKUP_TYPE_DEFINE(EEPROM, 13, 0),
55 CARD_BACKUP_TYPE_EEPROM_512KBITS = CARD_BACKUP_TYPE_DEFINE(EEPROM, 16, 0),
56 CARD_BACKUP_TYPE_EEPROM_1MBITS = CARD_BACKUP_TYPE_DEFINE(EEPROM, 17, 0),
57 CARD_BACKUP_TYPE_FLASH_2MBITS = CARD_BACKUP_TYPE_DEFINE(FLASH, 18, 0),
58 CARD_BACKUP_TYPE_FLASH_4MBITS = CARD_BACKUP_TYPE_DEFINE(FLASH, 19, 0),
59 CARD_BACKUP_TYPE_FLASH_8MBITS = CARD_BACKUP_TYPE_DEFINE(FLASH, 20, 0),
60 CARD_BACKUP_TYPE_FLASH_16MBITS = CARD_BACKUP_TYPE_DEFINE(FLASH, 21, 0),
61 CARD_BACKUP_TYPE_FLASH_64MBITS = CARD_BACKUP_TYPE_DEFINE(FLASH, 23, 0),
62 CARD_BACKUP_TYPE_FRAM_256KBITS = CARD_BACKUP_TYPE_DEFINE(FRAM, 15, 0),
63 CARD_BACKUP_TYPE_NOT_USE = 0
64 }
65 CARDBackupType;
66
67 #define CARD_BACKUP_TYPE_FLASH_64MBITS_EX (CARDBackupType)CARD_BACKUP_TYPE_DEFINE(FLASH, 23, 1)
68
69
70 // (Used internally by the library)
71
72 // PXI command request to components and the ensata emulator
73 typedef enum CARDRequest
74 {
75 CARD_REQ_INIT = 0, /* initialize (setting from ARM9) */
76 CARD_REQ_ACK, /* request done (acknowledge from ARM7) */
77 CARD_REQ_IDENTIFY, /* CARD_IdentifyBackup */
78 CARD_REQ_READ_ID, /* CARD_ReadRomID (TEG && ARM9) */
79 CARD_REQ_READ_ROM, /* CARD_ReadRom (TEG && ARM9) */
80 CARD_REQ_WRITE_ROM, /* (reserved) */
81 CARD_REQ_READ_BACKUP, /* CARD_ReadBackup */
82 CARD_REQ_WRITE_BACKUP, /* CARD_WriteBackup */
83 CARD_REQ_PROGRAM_BACKUP, /* CARD_ProgramBackup */
84 CARD_REQ_VERIFY_BACKUP, /* CARD_VerifyBackup */
85 CARD_REQ_ERASE_PAGE_BACKUP, /* CARD_EraseBackupPage */
86 CARD_REQ_ERASE_SECTOR_BACKUP, /* CARD_EraseBackupSector */
87 CARD_REQ_ERASE_CHIP_BACKUP, /* CARD_EraseBackupChip */
88 CARD_REQ_READ_STATUS, /* CARD_ReadStatus */
89 CARD_REQ_WRITE_STATUS, /* CARD_WriteStatus */
90 CARD_REQ_ERASE_SUBSECTOR_BACKUP, /* CARD_EraseBackupSubSector */
91 CARD_REQ_MAX
92 }
93 CARDRequest;
94
95 // Command request operation type
96 typedef enum CARDRequestMode
97 {
98 CARD_REQUEST_MODE_RECV, /* Receive data */
99 CARD_REQUEST_MODE_SEND, /* Send data (including single verify) */
100 CARD_REQUEST_MODE_SEND_VERIFY, /* Send data + verify */
101 CARD_REQUEST_MODE_SPECIAL /* Special operations like sector deletion */
102 }
103 CARDRequestMode;
104
105 // Maximum number of retries
106 #define CARD_RETRY_COUNT_MAX 10
107
108 // PXI protocol definition
109 #define CARD_PXI_COMMAND_MASK 0x0000003f // command part
110 #define CARD_PXI_COMMAND_SHIFT 0
111 #define CARD_PXI_COMMAND_PARAM_MASK 0x01ffffc0 // parameter part
112 #define CARD_PXI_COMMAND_PARAM_SHIFT 6
113
114 //---- PXI command
115 #define CARD_PXI_COMMAND_TERMINATE 0x0001 // arm9->arm7 terminate command
116 #define CARD_PXI_COMMAND_PULLED_OUT 0x0011 // arm7->arm9 pulled out message
117 #define CARD_PXI_COMMAND_RESET_SLOT 0x0002 // arm7->arm9 reset-slot message
118
119
120 /*---------------------------------------------------------------------------*/
121 /* Functions */
122
123 /*---------------------------------------------------------------------------*
124 Name: CARD_IdentifyBackup
125
126 Description: Specifies the type of the card backup device.
127
128 Arguments: type: A CARDBackupType device type
129
130 Returns: TRUE if a test read succeeded.
131 *---------------------------------------------------------------------------*/
132 BOOL CARD_IdentifyBackup(CARDBackupType type);
133
134 /*---------------------------------------------------------------------------*
135 Name: CARD_GetCurrentBackupType
136
137 Description: Gets the backup device type that is currently specified.
138
139 Arguments: None.
140
141 Returns: The backup device type that is currently specified.
142 *---------------------------------------------------------------------------*/
143 CARDBackupType CARD_GetCurrentBackupType(void);
144
145 /*---------------------------------------------------------------------------*
146 Name: CARD_GetBackupTotalSize
147
148 Description: Gets the overall size of the currently specified backup device.
149
150 Arguments: None.
151
152 Returns: Overall size of the backup device.
153 *---------------------------------------------------------------------------*/
154 u32 CARD_GetBackupTotalSize(void);
155
156 /*---------------------------------------------------------------------------*
157 Name: CARD_GetBackupSectorSize
158
159 Description: Gets the sector size of the currently specified backup device.
160
161 Arguments: None.
162
163 Returns: Sector size of the backup device
164 *---------------------------------------------------------------------------*/
165 u32 CARD_GetBackupSectorSize(void);
166
167 /*---------------------------------------------------------------------------*
168 Name: CARD_GetBackupPageSize
169
170 Description: Gets the page size of the currently specified backup device.
171
172 Arguments: None.
173
174 Returns: Page size of the backup device
175 *---------------------------------------------------------------------------*/
176 u32 CARD_GetBackupPageSize(void);
177
178 /*---------------------------------------------------------------------------*
179 Name: CARD_LockBackup
180
181 Description: Locks the card bus to access the backup device.
182
183 Arguments: lock_id Mutex ID allocated by the OS_GetLockID function
184
185 Returns: None.
186 *---------------------------------------------------------------------------*/
187 void CARD_LockBackup(u16 lock_id);
188
189 /*---------------------------------------------------------------------------*
190 Name: CARD_UnlockBackup
191
192 Description: Unlocks the card bus that was locked to access the backup device.
193
194 Arguments: lock_id Mutex ID used by the CARD_LockBackup function
195
196 Returns: None.
197 *---------------------------------------------------------------------------*/
198 void CARD_UnlockBackup(u16 lock_id);
199
200 /*---------------------------------------------------------------------------*
201 Name: CARD_TryWaitBackupAsync
202
203 Description: Determines whether a backup device access function has completed.
204
205 Arguments: None.
206
207 Returns: TRUE if a backup device access function has completed
208 *---------------------------------------------------------------------------*/
209 BOOL CARD_TryWaitBackupAsync(void);
210
211 /*---------------------------------------------------------------------------*
212 Name: CARD_WaitBackupAsync
213
214 Description: Waits for a backup device access function to complete.
215
216 Arguments: None.
217
218 Returns: TRUE if the last call to a backup device access function completed with CARD_RESULT_SUCCESS. Otherwise, FALSE.
219
220 *---------------------------------------------------------------------------*/
221 BOOL CARD_WaitBackupAsync(void);
222
223 /*---------------------------------------------------------------------------*
224 Name: CARD_CancelBackupAsync
225
226 Description: Sends a cancel request to the backup device access function being processed.
227
228 Arguments: None.
229
230 Returns: None.
231 *---------------------------------------------------------------------------*/
232 void CARD_CancelBackupAsync(void);
233
234
235 // internal chip command as Serial-Bus-Interface
236
237 /*---------------------------------------------------------------------------*
238 Name: CARDi_RequestStreamCommand
239
240 Description: Issues a command request to transfer data.
241
242 Arguments: src Transfer source offset or memory address
243 dst Transfer destination offset or memory address
244 len Transfer size
245 callback Completion callback (NULL if not used)
246 arg Argument of completion callback (ignored if not used)
247 is_async If async operation was specified, TRUE
248 req_type Command request type
249 req_retry Maximum number of retries when command request fails
250 req_mode Command request operation mode
251
252 Returns: TRUE if processing was successful.
253 *---------------------------------------------------------------------------*/
254 BOOL CARDi_RequestStreamCommand(u32 src, u32 dst, u32 len,
255 MIDmaCallback callback, void *arg, BOOL is_async,
256 CARDRequest req_type, int req_retry, CARDRequestMode req_mode);
257
258 /*---------------------------------------------------------------------------*
259 Name: CARDi_RequestWriteSectorCommand
260
261 Description: Erases sectors and issues program requests.
262
263 Arguments: src Transfer source memory address
264 dst Transfer destination offset
265 len Transfer size
266 verify TRUE when performing a verify
267 callback Completion callback (NULL if not used)
268 arg Argument of completion callback (ignored if not used)
269 is_async If async operation was specified, TRUE
270
271 Returns: TRUE if processing was successful.
272 *---------------------------------------------------------------------------*/
273 BOOL CARDi_RequestWriteSectorCommand(u32 src, u32 dst, u32 len, BOOL verify,
274 MIDmaCallback callback, void *arg, BOOL is_async);
275
276 /*---------------------------------------------------------------------------*
277 Name: CARDi_ReadBackup
278
279 Description: Issues a "read" chip command.
280
281 Arguments: src Transfer source offset or memory address
282 dst Transfer destination offset or memory address
283 len Transfer size
284 callback Completion callback (NULL if not used)
285 arg Argument of completion callback (ignored if not used)
286 is_async If async operation was specified, TRUE
287
288 Returns: TRUE if processing was successful.
289 *---------------------------------------------------------------------------*/
CARDi_ReadBackup(u32 src,void * dst,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)290 SDK_INLINE BOOL CARDi_ReadBackup(u32 src, void *dst, u32 len,
291 MIDmaCallback callback, void *arg, BOOL is_async)
292 {
293 return CARDi_RequestStreamCommand((u32)src, (u32)dst, len,
294 callback, arg, is_async,
295 CARD_REQ_READ_BACKUP, 1, CARD_REQUEST_MODE_RECV);
296 }
297
298 /*---------------------------------------------------------------------------*
299 Name: CARDi_ProgramBackup
300
301 Description: Issues a read command that uses the "program" chip command.
302
303 Arguments: src Transfer source offset or memory address
304 dst Transfer destination offset or memory address
305 len Transfer size
306 callback Completion callback (NULL if not used)
307 arg Argument of completion callback (ignored if not used)
308 is_async If async operation was specified, TRUE
309
310 Returns: TRUE if processing was successful.
311 *---------------------------------------------------------------------------*/
CARDi_ProgramBackup(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)312 SDK_INLINE BOOL CARDi_ProgramBackup(u32 dst, const void *src, u32 len,
313 MIDmaCallback callback, void *arg, BOOL is_async)
314 {
315 return CARDi_RequestStreamCommand((u32)src, (u32)dst, len, callback, arg, is_async,
316 CARD_REQ_PROGRAM_BACKUP, CARD_RETRY_COUNT_MAX,
317 CARD_REQUEST_MODE_SEND);
318 }
319
320 /*---------------------------------------------------------------------------*
321 Name: CARDi_WriteBackup
322
323 Description: Issues a write command that uses the "write" chip command.
324
325 Arguments: src Transfer source offset or memory address
326 dst Transfer destination offset or memory address
327 len Transfer size
328 callback Completion callback (NULL if not used)
329 arg Argument of completion callback (ignored if not used)
330 is_async If async operation was specified, TRUE
331
332 Returns: TRUE if processing was successful.
333 *---------------------------------------------------------------------------*/
CARDi_WriteBackup(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)334 SDK_INLINE BOOL CARDi_WriteBackup(u32 dst, const void *src, u32 len,
335 MIDmaCallback callback, void *arg, BOOL is_async)
336 {
337 return CARDi_RequestStreamCommand((u32)src, (u32)dst, len, callback, arg, is_async,
338 CARD_REQ_WRITE_BACKUP, CARD_RETRY_COUNT_MAX,
339 CARD_REQUEST_MODE_SEND);
340 }
341
342 /*---------------------------------------------------------------------------*
343 Name: CARDi_VerifyBackup
344
345 Description: Issues a verify command that uses the "read" chip command.
346
347 Arguments: src Transfer source offset or memory address
348 dst Transfer destination offset or memory address
349 len Transfer size
350 callback Completion callback (NULL if not used)
351 arg Argument of completion callback (ignored if not used)
352 is_async If async operation was specified, TRUE
353
354 Returns: TRUE if processing was successful.
355 *---------------------------------------------------------------------------*/
CARDi_VerifyBackup(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)356 SDK_INLINE BOOL CARDi_VerifyBackup(u32 dst, const void *src, u32 len,
357 MIDmaCallback callback, void *arg, BOOL is_async)
358 {
359 return CARDi_RequestStreamCommand((u32)src, (u32)dst, len, callback, arg, is_async,
360 CARD_REQ_VERIFY_BACKUP, 1, CARD_REQUEST_MODE_SEND);
361 }
362
363 /*---------------------------------------------------------------------------*
364 Name: CARDi_ProgramAndVerifyBackup
365
366 Description: Issues a program and verify command that uses the "program" chip command.
367
368 Arguments: src Transfer source offset or memory address
369 dst Transfer destination offset or memory address
370 len Transfer size
371 callback Completion callback (NULL if not used)
372 arg Argument of completion callback (ignored if not used)
373 is_async If async operation was specified, TRUE
374
375 Returns: TRUE if processing was successful.
376 *---------------------------------------------------------------------------*/
CARDi_ProgramAndVerifyBackup(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)377 SDK_INLINE BOOL CARDi_ProgramAndVerifyBackup(u32 dst, const void *src, u32 len,
378 MIDmaCallback callback, void *arg, BOOL is_async)
379 {
380 return CARDi_RequestStreamCommand((u32)src, (u32)dst, len, callback, arg, is_async,
381 CARD_REQ_PROGRAM_BACKUP, CARD_RETRY_COUNT_MAX,
382 CARD_REQUEST_MODE_SEND_VERIFY);
383 }
384
385 /*---------------------------------------------------------------------------*
386 Name: CARDi_WriteAndVerifyBackup
387
388 Description: Issues a program and verify command that uses the "write" chip command.
389
390 Arguments: src Transfer source offset or memory address
391 dst Transfer destination offset or memory address
392 len Transfer size
393 callback Completion callback (NULL if not used)
394 arg Argument of completion callback (ignored if not used)
395 is_async If async operation was specified, TRUE
396
397 Returns: TRUE if processing was successful.
398 *---------------------------------------------------------------------------*/
CARDi_WriteAndVerifyBackup(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)399 SDK_INLINE BOOL CARDi_WriteAndVerifyBackup(u32 dst, const void *src, u32 len,
400 MIDmaCallback callback, void *arg, BOOL is_async)
401 {
402 return CARDi_RequestStreamCommand((u32)src, (u32)dst, len, callback, arg, is_async,
403 CARD_REQ_WRITE_BACKUP, CARD_RETRY_COUNT_MAX,
404 CARD_REQUEST_MODE_SEND_VERIFY);
405 }
406
407 /*---------------------------------------------------------------------------*
408 Name: CARDi_EraseBackupSector
409
410 Description: Issues a sector deletion command that uses the "erase sector" chip command.
411
412 Arguments: dst the deletion target offset
413 len the deletion size
414 callback Completion callback (NULL if not used)
415 arg Argument of completion callback (ignored if not used)
416 is_async If async operation was specified, TRUE
417
418 Returns: TRUE if processing was successful.
419 *---------------------------------------------------------------------------*/
CARDi_EraseBackupSector(u32 dst,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)420 SDK_INLINE BOOL CARDi_EraseBackupSector(u32 dst, u32 len,
421 MIDmaCallback callback, void *arg, BOOL is_async)
422 {
423 return CARDi_RequestStreamCommand(0, (u32)dst, len, callback, arg, is_async,
424 CARD_REQ_ERASE_SECTOR_BACKUP, CARD_RETRY_COUNT_MAX,
425 CARD_REQUEST_MODE_SPECIAL);
426 }
427
428 /*---------------------------------------------------------------------------*
429 Name: CARDi_EraseBackupSubSector
430
431 Description: Issues a sector deletion command using the chip command, "erase subsector".
432
433 Arguments: dst the deletion target offset
434 len the deletion size
435 callback Completion callback (NULL if not used)
436 arg Argument of completion callback (ignored if not used)
437 is_async If async operation was specified, TRUE
438
439 Returns: If processing is successful, TRUE.
440 *---------------------------------------------------------------------------*/
CARDi_EraseBackupSubSector(u32 dst,u32 len,MIDmaCallback callback,void * arg,BOOL is_async)441 SDK_INLINE BOOL CARDi_EraseBackupSubSector(u32 dst, u32 len,
442 MIDmaCallback callback, void *arg, BOOL is_async)
443 {
444 return CARDi_RequestStreamCommand(0, (u32)dst, len, callback, arg, is_async,
445 CARD_REQ_ERASE_SUBSECTOR_BACKUP, CARD_RETRY_COUNT_MAX,
446 CARD_REQUEST_MODE_SPECIAL);
447 }
448
449 /*---------------------------------------------------------------------------*
450 Name: CARDi_EraseBackupChip
451
452 Description: Issues a sector deletion command that uses the "erase chip" chip command.
453
454 Arguments: callback Completion callback (NULL if not used)
455 arg Argument of completion callback (ignored if not used)
456 is_async If async operation was specified, TRUE
457
458 Returns: TRUE if processing was successful.
459 *---------------------------------------------------------------------------*/
CARDi_EraseBackupChip(MIDmaCallback callback,void * arg,BOOL is_async)460 SDK_INLINE BOOL CARDi_EraseBackupChip(MIDmaCallback callback, void *arg, BOOL is_async)
461 {
462 return CARDi_RequestStreamCommand(0, 0, 0, callback, arg, is_async,
463 CARD_REQ_ERASE_CHIP_BACKUP, 1, CARD_REQUEST_MODE_SPECIAL);
464 }
465
466 /*---------------------------------------------------------------------------*
467 Name: CARD_ReadBackupAsync
468
469 Description: Asynchronous backup read (equivalent to the chip command "read")
470
471 Arguments: src Transfer source offset
472 dst Transfer destination memory address
473 len Transfer size
474 callback Completion callback (NULL if not used)
475 arg Argument of completion callback (ignored if not used)
476
477 Returns: None.
478 *---------------------------------------------------------------------------*/
CARD_ReadBackupAsync(u32 src,void * dst,u32 len,MIDmaCallback callback,void * arg)479 SDK_INLINE void CARD_ReadBackupAsync(u32 src, void *dst, u32 len, MIDmaCallback callback, void *arg)
480 {
481 (void)CARDi_ReadBackup(src, dst, len, callback, arg, TRUE);
482 }
483
484 /*---------------------------------------------------------------------------*
485 Name: CARD_ReadBackup
486
487 Description: Synchronous backup read (equivalent to the chip command "read")
488
489 Arguments: src Transfer source offset
490 dst Transfer destination memory address
491 len Transfer size
492
493 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
494 *---------------------------------------------------------------------------*/
CARD_ReadBackup(u32 src,void * dst,u32 len)495 SDK_INLINE BOOL CARD_ReadBackup(u32 src, void *dst, u32 len)
496 {
497 return CARDi_ReadBackup(src, dst, len, NULL, NULL, FALSE);
498 }
499
500 /*---------------------------------------------------------------------------*
501 Name: CARD_ProgramBackupAsync
502
503 Description: Asynchronous backup program (equivalent to the chip command "program")
504
505 Arguments: dst: Transfer destination offset
506 src: Transfer source memory address
507 len Transfer size
508 callback Completion callback (NULL if not used)
509 arg Argument of completion callback (ignored if not used)
510
511 Returns: None.
512 *---------------------------------------------------------------------------*/
CARD_ProgramBackupAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)513 SDK_INLINE void CARD_ProgramBackupAsync(u32 dst, const void *src, u32 len,
514 MIDmaCallback callback, void *arg)
515 {
516 (void)CARDi_ProgramBackup(dst, src, len, callback, arg, TRUE);
517 }
518
519 /*---------------------------------------------------------------------------*
520 Name: CARD_ProgramBackup
521
522 Description: Synchronous backup program (equivalent to the chip command "program")
523
524 Arguments: dst Transfer destination offset
525 src Transfer source memory address
526 len Transfer size
527
528 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
529 *---------------------------------------------------------------------------*/
CARD_ProgramBackup(u32 dst,const void * src,u32 len)530 SDK_INLINE BOOL CARD_ProgramBackup(u32 dst, const void *src, u32 len)
531 {
532 return CARDi_ProgramBackup(dst, src, len, NULL, NULL, FALSE);
533 }
534
535 /*---------------------------------------------------------------------------*
536 Name: CARD_WriteBackupAsync
537
538 Description: Asynchronous backup write (equivalent to the chip command "write")
539
540 Arguments: dst Transfer destination offset
541 src Transfer source memory address
542 len Transfer size
543 callback Completion callback (NULL if not used)
544 arg Argument of completion callback (ignored if not used)
545
546 Returns: None.
547 *---------------------------------------------------------------------------*/
CARD_WriteBackupAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)548 SDK_INLINE void CARD_WriteBackupAsync(u32 dst, const void *src, u32 len,
549 MIDmaCallback callback, void *arg)
550 {
551 (void)CARDi_WriteBackup(dst, src, len, callback, arg, TRUE);
552 }
553
554 /*---------------------------------------------------------------------------*
555 Name: CARD_WriteBackup
556
557 Description: Synchronous backup write (equivalent to the chip command "write")
558
559 Arguments: dst Transfer destination offset
560 src Transfer source memory address
561 len Transfer size
562
563 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
564 *---------------------------------------------------------------------------*/
CARD_WriteBackup(u32 dst,const void * src,u32 len)565 SDK_INLINE BOOL CARD_WriteBackup(u32 dst, const void *src, u32 len)
566 {
567 return CARDi_WriteBackup(dst, src, len, NULL, NULL, FALSE);
568 }
569
570 /*---------------------------------------------------------------------------*
571 Name: CARD_VerifyBackupAsync
572
573 Description: Asynchronous backup verify (equivalent to the chip command "read")
574
575 Arguments: src Comparison source offset
576 dst Comparison destination memory address
577 len Comparison size
578 callback Completion callback (NULL if not used)
579 arg Argument of completion callback (ignored if not used)
580
581 Returns: None.
582 *---------------------------------------------------------------------------*/
CARD_VerifyBackupAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)583 SDK_INLINE void CARD_VerifyBackupAsync(u32 dst, const void *src, u32 len,
584 MIDmaCallback callback, void *arg)
585 {
586 (void)CARDi_VerifyBackup(dst, src, len, callback, arg, TRUE);
587 }
588
589 /*---------------------------------------------------------------------------*
590 Name: CARD_VerifyBackup
591
592 Description: Synchronous backup verify (equivalent to the chip command "read")
593
594 Arguments: src Comparison source offset
595 dst Comparison destination memory address
596 len Comparison size
597
598 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
599 *---------------------------------------------------------------------------*/
CARD_VerifyBackup(u32 dst,const void * src,u32 len)600 SDK_INLINE BOOL CARD_VerifyBackup(u32 dst, const void *src, u32 len)
601 {
602 return CARDi_VerifyBackup(dst, src, len, NULL, NULL, FALSE);
603 }
604
605 /*---------------------------------------------------------------------------*
606 Name: CARD_ProgramAndVerifyBackupAsync
607
608 Description: Asynchronous backup program + verify
609
610 Arguments: dst Transfer destination offset
611 src Transfer source memory address
612 len Transfer size
613 callback Completion callback (NULL if not used)
614 arg Argument of completion callback (ignored if not used)
615
616 Returns: None.
617 *---------------------------------------------------------------------------*/
CARD_ProgramAndVerifyBackupAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)618 SDK_INLINE void CARD_ProgramAndVerifyBackupAsync(u32 dst, const void *src, u32 len,
619 MIDmaCallback callback, void *arg)
620 {
621 (void)CARDi_ProgramAndVerifyBackup(dst, src, len, callback, arg, TRUE);
622 }
623
624 /*---------------------------------------------------------------------------*
625 Name: CARD_ProgramAndVerifyBackup
626
627 Description: Synchronous backup program + verify
628
629 Arguments: dst Transfer destination offset
630 src Transfer source memory address
631 len Transfer size
632
633 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
634 *---------------------------------------------------------------------------*/
CARD_ProgramAndVerifyBackup(u32 dst,const void * src,u32 len)635 SDK_INLINE BOOL CARD_ProgramAndVerifyBackup(u32 dst, const void *src, u32 len)
636 {
637 return CARDi_ProgramAndVerifyBackup(dst, src, len, NULL, NULL, FALSE);
638 }
639
640 /*---------------------------------------------------------------------------*
641 Name: CARD_WriteAndVerifyBackupAsync
642
643 Description: Asynchronous backup write + verify
644
645 Arguments: dst Transfer destination offset
646 src Transfer source memory address
647 len Transfer size
648 callback Completion callback (NULL if not used)
649 arg Argument of completion callback (ignored if not used)
650
651 Returns: None.
652 *---------------------------------------------------------------------------*/
CARD_WriteAndVerifyBackupAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)653 SDK_INLINE void CARD_WriteAndVerifyBackupAsync(u32 dst, const void *src, u32 len,
654 MIDmaCallback callback, void *arg)
655 {
656 (void)CARDi_WriteAndVerifyBackup(dst, src, len, callback, arg, TRUE);
657 }
658
659 /*---------------------------------------------------------------------------*
660 Name: CARD_WriteAndVerifyBackup
661
662 Description: Synchronous backup write + Verify
663
664 Arguments: dst Transfer destination offset
665 src Transfer source memory address
666 len Transfer size
667
668 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
669 *---------------------------------------------------------------------------*/
CARD_WriteAndVerifyBackup(u32 dst,const void * src,u32 len)670 SDK_INLINE BOOL CARD_WriteAndVerifyBackup(u32 dst, const void *src, u32 len)
671 {
672 return CARDi_WriteAndVerifyBackup(dst, src, len, NULL, NULL, FALSE);
673 }
674
675 /*---------------------------------------------------------------------------*
676 Name: CARD_EraseBackupSectorAsync
677
678 Description: Asynchronous sector deletion.
679
680 Arguments: dst Deletion target offset
681 len Deletion size
682 callback Completion callback (NULL if not used)
683 arg Argument of completion callback (ignored if not used)
684
685 Returns: None.
686 *---------------------------------------------------------------------------*/
CARD_EraseBackupSectorAsync(u32 dst,u32 len,MIDmaCallback callback,void * arg)687 SDK_INLINE void CARD_EraseBackupSectorAsync(u32 dst, u32 len, MIDmaCallback callback, void *arg)
688 {
689 (void)CARDi_EraseBackupSector(dst, len, callback, arg, TRUE);
690 }
691
692 /*---------------------------------------------------------------------------*
693 Name: CARD_EraseBackupSector
694
695 Description: Deletes sectors synchronously.
696
697 Arguments: dst Deletion target offset
698 len Deletion size
699
700 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
701 *---------------------------------------------------------------------------*/
CARD_EraseBackupSector(u32 dst,u32 len)702 SDK_INLINE BOOL CARD_EraseBackupSector(u32 dst, u32 len)
703 {
704 return CARDi_EraseBackupSector(dst, len, NULL, NULL, FALSE);
705 }
706
707 /*---------------------------------------------------------------------------*
708 Name: CARD_EraseBackupSubSectorAsync
709
710 Description: Asynchronous subsector deletion.
711
712 Arguments: dst Deletion target offset
713 len Deletion size
714 callback Completion callback (NULL if not used)
715 arg Argument of completion callback (ignored if not used)
716
717 Returns: None.
718 *---------------------------------------------------------------------------*/
CARD_EraseBackupSubSectorAsync(u32 dst,u32 len,MIDmaCallback callback,void * arg)719 SDK_INLINE void CARD_EraseBackupSubSectorAsync(u32 dst, u32 len, MIDmaCallback callback, void *arg)
720 {
721 (void)CARDi_EraseBackupSubSector(dst, len, callback, arg, TRUE);
722 }
723
724 /*---------------------------------------------------------------------------*
725 Name: CARD_EraseBackupSubSector
726
727 Description: Synchronous subsector deletion.
728
729 Arguments: dst Deletion target offset
730 len Deletion size
731
732 Returns: TRUE if completed with CARD_RESULT_SUCCESS, FALSE for everything else.
733 *---------------------------------------------------------------------------*/
CARD_EraseBackupSubSector(u32 dst,u32 len)734 SDK_INLINE BOOL CARD_EraseBackupSubSector(u32 dst, u32 len)
735 {
736 return CARDi_EraseBackupSubSector(dst, len, NULL, NULL, FALSE);
737 }
738
739 /*---------------------------------------------------------------------------*
740 Name: CARD_EraseBackupChipAsync
741
742 Description: Deletes a chip asynchronously.
743
744 Arguments: callback Completion callback (NULL if not used)
745 arg Argument of completion callback (ignored if not used)
746
747 Returns: None.
748 *---------------------------------------------------------------------------*/
CARD_EraseBackupChipAsync(MIDmaCallback callback,void * arg)749 SDK_INLINE void CARD_EraseBackupChipAsync(MIDmaCallback callback, void *arg)
750 {
751 (void)CARDi_EraseBackupChip(callback, arg, TRUE);
752 }
753
754 /*---------------------------------------------------------------------------*
755 Name: CARD_EraseBackupChip
756
757 Description: Deletes sectors synchronously.
758
759 Arguments: None.
760
761 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
762 *---------------------------------------------------------------------------*/
CARD_EraseBackupChip(void)763 SDK_INLINE BOOL CARD_EraseBackupChip(void)
764 {
765 return CARDi_EraseBackupChip(NULL, NULL, FALSE);
766 }
767
768 /*---------------------------------------------------------------------------*
769 Name: CARD_WriteBackupSectorAsync
770
771 Description: Erases and programs by sector.
772
773 Arguments: dst Transfer destination offset
774 src Transfer source memory address
775 len Transfer size
776 callback Completion callback (NULL if not used)
777 arg Argument of completion callback (ignored if not used)
778
779 Returns: None.
780 *---------------------------------------------------------------------------*/
CARD_WriteBackupSectorAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)781 SDK_INLINE void CARD_WriteBackupSectorAsync(u32 dst, const void *src, u32 len,
782 MIDmaCallback callback, void *arg)
783 {
784 (void)CARDi_RequestWriteSectorCommand((u32)src, dst, len, FALSE, callback, arg, TRUE);
785 }
786
787 /*---------------------------------------------------------------------------*
788 Name: CARD_WriteBackupSector
789
790 Description: Erases and programs by sector.
791
792 Arguments: dst Transfer destination offset
793 src Transfer source memory address
794 len Transfer size
795
796 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
797 *---------------------------------------------------------------------------*/
CARD_WriteBackupSector(u32 dst,const void * src,u32 len)798 SDK_INLINE BOOL CARD_WriteBackupSector(u32 dst, const void *src, u32 len)
799 {
800 return CARDi_RequestWriteSectorCommand((u32)src, dst, len, FALSE, NULL, NULL, FALSE);
801 }
802
803 /*---------------------------------------------------------------------------*
804 Name: CARD_WriteAndVerifyBackupSectorAsync
805
806 Description: Erases and programs by sectors, then verifies.
807
808 Arguments: dst Transfer destination offset
809 src Transfer source memory address
810 len Transfer size
811 callback Completion callback (NULL if not used)
812 arg Argument of completion callback (ignored if not used)
813
814 Returns: None.
815 *---------------------------------------------------------------------------*/
CARD_WriteAndVerifyBackupSectorAsync(u32 dst,const void * src,u32 len,MIDmaCallback callback,void * arg)816 SDK_INLINE void CARD_WriteAndVerifyBackupSectorAsync(u32 dst, const void *src, u32 len,
817 MIDmaCallback callback, void *arg)
818 {
819 (void)CARDi_RequestWriteSectorCommand((u32)src, dst, len, TRUE, callback, arg, TRUE);
820 }
821
822 /*---------------------------------------------------------------------------*
823 Name: CARD_WriteAndVerifyBackupSector
824
825 Description: Erases and programs by sectors, then verifies.
826
827 Arguments: dst Transfer destination offset
828 src Transfer source memory address
829 len Transfer size
830
831 Returns: TRUE on completion with CARD_RESULT_SUCCESS and FALSE otherwise.
832 *---------------------------------------------------------------------------*/
CARD_WriteAndVerifyBackupSector(u32 dst,const void * src,u32 len)833 SDK_INLINE BOOL CARD_WriteAndVerifyBackupSector(u32 dst, const void *src, u32 len)
834 {
835 return CARDi_RequestWriteSectorCommand((u32)src, dst, len, TRUE, NULL, NULL, FALSE);
836 }
837
838 /*---------------------------------------------------------------------------*
839 Name: CARDi_AccessStatus
840
841 Description: Status read or write (for testing)
842
843 Arguments: command CARD_REQ_READ_STATUS or CARD_REQ_WRITE_STATUS
844 value The value to write, if CARD_REQ_WRITE_STATUS
845
846 Returns: Returns a value of 0 or higher if successful; a negative number otherwise.
847 *---------------------------------------------------------------------------*/
848 int CARDi_AccessStatus(CARDRequest command, u8 value);
849
850 /*---------------------------------------------------------------------------*
851 Name: CARDi_ReadStatus
852
853 Description: Status read (for testing)
854
855 Arguments: None.
856
857 Returns: Returns a value of 0 or higher if successful; a negative number otherwise.
858 *---------------------------------------------------------------------------*/
CARDi_ReadStatus(void)859 SDK_INLINE int CARDi_ReadStatus(void)
860 {
861 return CARDi_AccessStatus(CARD_REQ_READ_STATUS, 0);
862 }
863
864 /*---------------------------------------------------------------------------*
865 Name: CARDi_WriteStatus
866
867 Description: Status write (for testing)
868
869 Arguments: value The value to be written
870
871 Returns: TRUE if completed with CARD_RESULT_SUCCESS, FALSE for everything else.
872 *---------------------------------------------------------------------------*/
CARDi_WriteStatus(u8 value)873 SDK_INLINE BOOL CARDi_WriteStatus(u8 value)
874 {
875 return (CARDi_AccessStatus(CARD_REQ_WRITE_STATUS, value) >= 0);
876 }
877
878
879 #ifdef __cplusplus
880 }
881 #endif // extern "C"
882
883
884 #endif // NITRO_CARD_BACKUP_H_
885