From 80469b4bfaf49a407d8d6b5bf3c2eb0d1c9870e6 Mon Sep 17 00:00:00 2001
From: Joe Zhao <ztuowen@gmail.com>
Date: Fri, 16 May 2014 17:12:37 +0800
Subject: Comments update

---
 rs422lib/main.c    |  2 +-
 rs422lib/precomp.h | 15 ++++++++++++---
 rs422lib/rsbus.c   |  3 +--
 rs422lib/rsbus.h   | 19 ++++++++++++++++---
 rs422lib/sysctl.c  |  2 +-
 rs422lib/sysctl.h  | 23 +++++++++++++++++++++--
 6 files changed, 52 insertions(+), 12 deletions(-)

diff --git a/rs422lib/main.c b/rs422lib/main.c
index 7f7ea11..2a2517f 100644
--- a/rs422lib/main.c
+++ b/rs422lib/main.c
@@ -11,7 +11,7 @@ void port_init(void)
     P1OUT = 0;
 }
 
-void received(unsigned char* str,int len)
+void received(unsigned char* str,unsigned int len)
 {
 	rsbus_w(0,str,len);
 }
diff --git a/rs422lib/precomp.h b/rs422lib/precomp.h
index 11f64be..d2d2380 100644
--- a/rs422lib/precomp.h
+++ b/rs422lib/precomp.h
@@ -10,17 +10,26 @@
 
 #include<msp430g2553.h>
 
+// ====== RSBUS configuration ======
+
+// Data Enable pin configuration
+// P1.0 -> red led
 #define RSDIR (P1DIR)
 #define RSOUT (P1OUT)
 #define RSPIN (BIT0)
 
-#define RSSYSBIT (SYS_BIT7) // This is the lowest level
-#define RSSYSRET (SYS_BIT6) // Second lowest level
+// This is the highest level
+#define RSSYSBIT (SYS_BIT0)
 
+// Specify the physical address on the rsbus
 #define RSADDR (1)
 
-#define MACTYPE (0x00) //TYPE 0 is a dummy used for debug
+// Machine Type
+// TYPE 0 is a dummy used for debug
 // Change it in real implementation
+#define MACTYPE (0x00)
+
+// ====== End RSBUS configuration ======
 
 //define delay func
 #define delay_ms(ms)    __delay_cycles(16000*(ms))
diff --git a/rs422lib/rsbus.c b/rs422lib/rsbus.c
index 2b548a6..c69a664 100644
--- a/rs422lib/rsbus.c
+++ b/rs422lib/rsbus.c
@@ -28,6 +28,7 @@ volatile unsigned char tx_pos=255;
 
 volatile unsigned char mac_stat[4]={0,0,0,0};
 
+// UART transmit routine
 #pragma vector=USCIAB0TX_VECTOR
 __interrupt void USCI0TX_ISR(void)
 {
@@ -136,8 +137,6 @@ __interrupt void rsbus_rx(void)
 	}
 }
 
-// Send something to the rs422 bus
-// Length must not exceeds RS_MAX
 void rsbus_w(int addr,unsigned char* buf,unsigned int len)
 {
 	while (tx_pos < tx_len)		// This shouldn't happen
diff --git a/rs422lib/rsbus.h b/rs422lib/rsbus.h
index 2faf620..2e29b9b 100644
--- a/rs422lib/rsbus.h
+++ b/rs422lib/rsbus.h
@@ -34,17 +34,30 @@
 //		Available indices 0,1,2
 #define STATE(X) (mac_stat[X+1])
 
+// Start and Stop bits definition
+// 		Every message sent that does not agree with it will be ignored
+// 		Please avoid this pattern in STATE(X)
 #define STBIT0 (0x5B)
 #define STBIT1 (0xAD)
 #define EDBIT0 (0xA4)
 #define EDBIT1 (0x52)
 
-typedef void (*rshdlr)(unsigned char*,int);
+// Receieve handler ->
+//	Received message and it's length
+typedef void (*rshdlr)(unsigned char* msg,unsigned int len);
 
+// RSBUS init function
+// Setting up UART, DE pin, receieve handler
 void rsbus_init(rshdlr);
 
-void rsbus_w(int addr,unsigned char* buf,unsigned int len);
+// Send something to the rs422 bus
+// Length must not exceeds RS_MAX
+void rsbus_w(int,unsigned char*,unsigned int);
 
-extern volatile unsigned char mac_stat[4]; // Machine status -> change it to change the auto respond status
+// Machine status -> change it to change the auto respond status
+// 		0 is reserved for machine state specification
+// 		1-3 used for mac_type specific state
+// recommend using SWITCH_STATE & STATE
+extern volatile unsigned char mac_stat[4];
 
 #endif /* RSBUS_H_ */
diff --git a/rs422lib/sysctl.c b/rs422lib/sysctl.c
index fbacb9c..4562702 100644
--- a/rs422lib/sysctl.c
+++ b/rs422lib/sysctl.c
@@ -21,7 +21,7 @@ void sysctl_void()
 void sysroutine()
 {
 	if (syscall>0)
-	switch ((syscall & (-syscall)))
+	switch ((syscall & (-syscall))) // This is used to get the lowest bit
 	{
 	case SYS_BIT7:
 		syscall=syscall&(~SYS_BIT7);
diff --git a/rs422lib/sysctl.h b/rs422lib/sysctl.h
index 11b65ed..b8301fa 100644
--- a/rs422lib/sysctl.h
+++ b/rs422lib/sysctl.h
@@ -12,6 +12,8 @@
 #ifndef SYSCTL_H_
 #define SYSCTL_H_
 
+// Sysctl priority bit
+// Lowest first
 #define SYS_BIT7 (0x80)
 #define SYS_BIT6 (0x40)
 #define SYS_BIT5 (0x20)
@@ -20,17 +22,34 @@
 #define SYS_BIT2 (0x04)
 #define SYS_BIT1 (0x02)
 #define SYS_BIT0 (0x01)
+
+// SYSCALL invocation routine
+// Used this in IRQ, also wakes up the cpu
 #define SYSCALL_IRQ(X) (syscall|=X,_BIC_SR_IRQ(CPUOFF))
+// Use this in anywhere other than IRQ
+// Continuous invocation ?
 #define SYSCALL(X) (syscall|=X)
 
+// Call handler type
+// Does't have any input
+// 	Preserve the state in other global variables
+//	Usage example -> rsbus_syscall()
 typedef void (*syshdlr)();
 
-void sysctl_reghdlr(unsigned int bit,syshdlr rot);// Always replace
+// Register call handler
+// Always replace old value
+void sysctl_reghdlr(unsigned int bit,syshdlr rot);
 
-void sysctl_rmhdlr(unsigned int bit);// Replace with something useless
+// Remove old call handler
+// Replace with something useless
+void sysctl_rmhdlr(unsigned int bit);
 
+// Insert it into mainloop
+// enabling automatic procedure invocation
 void sysroutine();
 
+// Setting up the proc base
+// Call before usage
 void sysctl_init();
 
 extern volatile unsigned char syscall;
-- 
cgit v1.2.3-70-g09d2