CVS: jtag/msp430 README.txt,1.2,1.3 funclets.c,1.7,1.8

Update of /cvsroot/mspgcc/jtag/msp430
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21625/jtag/msp430

Modified Files:
	README.txt funclets.c 
Log Message:
doc updates

Index: README.txt
===================================================================
RCS file: /cvsroot/mspgcc/jtag/msp430/README.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -w -d -r1.2 -r1.3
--- README.txt	24 Sep 2002 02:17:40 -0000	1.2
+++ README.txt	26 Dec 2005 22:41:23 -0000	1.3
@@ -6,7 +6,7 @@
 
 This library is not for direct use by a client program, but for developers.
 A reference application used to program devices can be found in the python
-directory on level above and in the pyjtag module in the mspgcc CVS.
+directory on level above and in the python/msp430-jtag.py in the mspgcc CVS.
 See http://mspgcc.sf.net
 
 

Index: funclets.c
===================================================================
RCS file: /cvsroot/mspgcc/jtag/msp430/funclets.c,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -w -d -r1.7 -r1.8
--- funclets.c	22 Dec 2005 01:49:35 -0000	1.7
+++ funclets.c	26 Dec 2005 22:41:23 -0000	1.8
@@ -17,11 +17,12 @@
 void (*flash_callback)(WORD, WORD) = NULL;
 
 /**
- * msp430 code and buffer to write flash.
+ * Write flash. A funclet is downloaded and executed to do the actual work
+ * as the exact flash timing cannot be provided by the PC.
  *
- * As it's not implemented to read the MSP430 registers, return values have to be
- * passed in memory. Due to a JTAG bug in certain devices that can corrupt RAM, the
- * return value is passed in CCR0.
+ * As it's (was) not implemented to read the MSP430 registers, return values
+ * have to be passed in memory. Due to a JTAG bug in certain devices that can
+ * corrupt RAM, the return value is passed in CCR0.
  */
 STATUS_T programFlash(WORD address, const CHAR* buffer, WORD count) {
     STATUS_T res = STATUS_OK;
@@ -41,7 +42,7 @@
         code[4] = address;                                              //starting address in flash
         code[5] = blocksize/2;                                          //number of words to write
         MSP430_Log(2, "funclets: programFlash: Flash write at 0x%04x %d bytes\n", address, blocksize);
-        //download data and start flash programing funclet in RAM
+        //download data and start flash programing funclet in RAM, with retries
         for (tries=3; tries; tries--) {
             res =  executeCode(code, (sizeof(funclet_progFlash) + blocksize)/sizeof(WORD), 1, 1);
             if (res != STATUS_OK) {
@@ -71,7 +72,14 @@
 #include "eraseFlash.ci"                        //include the program to erase the flash
 #include "eraseFlashSegment.ci"                 //include the program to erase the flash by segment
 
-/** msp430 code to erase flash */
+/** 
+ * Erase flash. A funclet is downloaded and executed to do the actual work
+ * as the exact flash timing cannot be provided by the PC.
+ *
+ * Two different funclets are used:
+ * - one for MASS and MAIN erase (SegementA is NOT erased on F2xx)
+ * - an other for segment erase. This one unlocks SegmentA on F2xx devices.
+ */
 STATUS_T eraseFlash(WORD type, WORD address) {
     MSP430_Log(2, "funclets: eraseFlash(%d, 0x%04x)\n", type, address);
     //select correct erase mode
@@ -113,17 +121,21 @@
 
 /**
  * Read Memory Address Bus.
+ *
  * This function can be used at any time (when the JTAG is syncronized)
  * I may however return bogus results while the CPU is running.
  * Using it in a loop and multiple checks if it returns the same address
  * is a probable mean to check if the CPU waits on a "jmp $" insn.
+ * Used in the executeCode functions.
  */
 static WORD readMab(void) {
     HIL_JTAG_IR(IR_ADDR_CAPTURE);
     return (WORD)HIL_JTAG_DR(0, 16);
 }
 
-/** wait until CPU is on an instruction load boundary */
+/**
+ * Wait until CPU is on an instruction load boundary.
+ */
 STATUS_T syncCPU(void) {
     WORD cntrlSig;
     int i;
@@ -194,7 +206,9 @@
     }
 }
 
-/** Set PC and avoid corrupting RAM while doing so. used in executeCode*/
+/** 
+ * Set PC and avoid corrupting RAM while doing so. Used in executeCodeSafe.
+ */
 static STATUS_T setPCsafe(WORD addr) {
     HIL_JTAG_IR(IR_DATA_16BIT);
     HIL_JTAG_DR(MOV_IMM_PC, F_WORD);            // Force PC into non-RAM area.
@@ -209,7 +223,8 @@
     return (STATUS_OK);
 }
 
-/** This function downloads programs (funclets) into RAM, and starts their execution.
+/**
+ * This function downloads programs (funclets) into RAM, and starts their execution.
  * F413P, F41xC, and F12x devices contain a silicon bug that can corrupt memory when
  * the JTAG instruction register or the JTAG data register is accessed while TCLK is
  * high. The following sequence of steps has been carefully crafted to work around
@@ -433,22 +448,22 @@
 
 /** 
  * We dont have the correct code for a execute code that works with F1xx series
- * with the JTAg bug AND F2xx devices. Solution: choose one or the other
+ * with the JTAG bug AND F2xx devices. Solution: choose one or the other
  * executeCode implementation, depending on CPU type.
  */
 STATUS_T executeCode(const WORD* code, WORD sizeCode, BOOL verify, BOOL wait) {
     if ((DEVICE & 0xff00) == 0xf200) {           //is it a F2xx series device?
-        //yes F2xx use new variant
+        //yes F2xx: use new variant
         return executeCodeUnsafe(code, sizeCode, verify, wait);
     } else {
-        //no F1xx or F4xx series, use old variant with support for bad JTAGs
+        //no, F1xx or F4xx series, use old variant with support for bad JTAGs
         return executeCodeSafe(code, sizeCode, verify, wait);
     }
 }
 
 /**
- * check if the cpu is executing code or if its halted
- * may have some uncertainity if it hits a loop repeatedly on the same instruction...
+ * Check if the CPU is executing code or if it is halted.
+ * May have some uncertainity if it hits a loop repeatedly on the same instruction...
  */
 int isHalted(void) {
     int i;



-------------------------------------------------------
This SF.net email is sponsored by: Splunk Inc. Do you grep through log files
for problems?  Stop!  Download the new AJAX search engine that makes
searching your log files as easy as surfing the  web.  DOWNLOAD SPLUNK!
http://ads.osdn.com/?ad_id=7637&alloc_id=16865&op=click