From: Jack <jack@espressif.com>
Date: Tue, 6 Sep 2016 12:21:47 +0000 (+0800)
Subject: add comments to register read/write operations
X-Git-Tag: v0.9~56^2~1
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=d0442602c7a1be11cc07f5a686601c40edf99a90;p=esp-idf

add comments to register read/write operations
---

diff --git a/components/esp32/include/soc/soc.h b/components/esp32/include/soc/soc.h
index 46389106c5..2deab13e53 100755
--- a/components/esp32/include/soc/soc.h
+++ b/components/esp32/include/soc/soc.h
@@ -58,35 +58,70 @@
 
 #define BIT(nr)                 (1UL << (nr))
 
+//write value to register
 #define REG_WRITE(_r, _v)    (*(volatile uint32_t *)(_r)) = (_v)
+
+//read value from register
 #define REG_READ(_r) (*(volatile uint32_t *)(_r))
 
-//get bit or get bits
+//get bit or get bits from register
 #define REG_GET_BIT(_r, _b)  (*(volatile uint32_t*)(_r) & (_b))
-//set bit or set bits
+
+//set bit or set bits to register
 #define REG_SET_BIT(_r, _b)  (*(volatile uint32_t*)(_r) |= (_b))
-//clear bit or clear bits
+
+//clear bit or clear bits of register
 #define REG_CLR_BIT(_r, _b)  (*(volatile uint32_t*)(_r) &= ~(_b))
-//set bits controll by mask
+
+//set bits of register controlled by mask
 #define REG_SET_BITS(_r, _b, _m) (*(volatile uint32_t*)(_r) = (*(volatile uint32_t*)(_r) & ~(_m)) | ((_b) & (_m)))
 
+//get field from register, used when _f is not left shifted by _f##_S
+#define REG_GET_FIELD(_r, _f) ((REG_READ(_r) >> (_f##_S)) & (_f))
+
+//set field to register, used when _f is not left shifted by _f##_S
+#define REG_SET_FIELD(_r, _f, _v) (REG_WRITE((_r),((REG_READ(_r) & ~((_f) << (_f##_S)))|(((_v) & (_f))<<(_f##_S)))))
+
+//get field value from a variable, used when _f is not left shifted by _f##_S
 #define VALUE_GET_FIELD(_r, _f) (((_r) >> (_f##_S)) & (_f))
+
+//get field value from a variable, used when _f is left shifted by _f##_S
 #define VALUE_GET_FIELD2(_r, _f) (((_r) & (_f))>> (_f##_S))
+
+//set field value to a variable, used when _f is not left shifted by _f##_S
 #define VALUE_SET_FIELD(_r, _f, _v) ((_r)=(((_r) & ~((_f) << (_f##_S)))|((_v)<<(_f##_S))))
+
+//set field value to a variable, used when _f is left shifted by _f##_S
 #define VALUE_SET_FIELD2(_r, _f, _v) ((_r)=(((_r) & ~(_f))|((_v)<<(_f##_S))))
+
+//generate a value from a field value, used when _f is not left shifted by _f##_S
 #define FIELD_TO_VALUE(_f, _v) (((_v)&(_f))<<_f##_S)
-#define FIELD_TO_VALUE2(_f, _v) (((_v)<<_f##_S) & (_f))
-#define REG_GET_FIELD(_r, _f) ((REG_READ(_r) >> (_f##_S)) & (_f))
-#define REG_SET_FIELD(_r, _f, _v) (REG_WRITE((_r),((REG_READ(_r) & ~((_f) << (_f##_S)))|(((_v) & (_f))<<(_f##_S)))))
 
+//generate a value from a field value, used when _f is left shifted by _f##_S
+#define FIELD_TO_VALUE2(_f, _v) (((_v)<<_f##_S) & (_f))
 
+//read value from register
 #define READ_PERI_REG(addr) (*((volatile uint32_t *)ETS_UNCACHED_ADDR(addr))) 
+
+//write value to register
 #define WRITE_PERI_REG(addr, val) (*((volatile uint32_t *)ETS_UNCACHED_ADDR(addr))) = (uint32_t)(val)   
+
+//clear bits of register controlled by mask
 #define CLEAR_PERI_REG_MASK(reg, mask) WRITE_PERI_REG((reg), (READ_PERI_REG(reg)&(~(mask))))
+
+//set bits of register controlled by mask
 #define SET_PERI_REG_MASK(reg, mask)   WRITE_PERI_REG((reg), (READ_PERI_REG(reg)|(mask)))
+
+//get bits of register controlled by mask
 #define GET_PERI_REG_MASK(reg, mask)   (READ_PERI_REG(reg) & (mask))
-#define GET_PERI_REG_BITS(reg, hipos,lowpos)      ((READ_PERI_REG(reg)>>(lowpos))&((1<<((hipos)-(lowpos)+1))-1)) 
+
+//get bits of register controlled by highest bit and lowest bit
+#define GET_PERI_REG_BITS(reg, hipos,lowpos)      ((READ_PERI_REG(reg)>>(lowpos))&((1<<((hipos)-(lowpos)+1))-1))
+
+//set bits of register controlled by mask and shift
 #define SET_PERI_REG_BITS(reg,bit_map,value,shift) (WRITE_PERI_REG((reg),(READ_PERI_REG(reg)&(~((bit_map)<<(shift))))|(((value) & bit_map)<<(shift)) ))
+
+//get field of register
 #define GET_PERI_REG_BITS2(reg, mask,shift)      ((READ_PERI_REG(reg)>>(shift))&(mask))
 //}}