docs: update readme, add macros section

2022-01-08 23:40:44 +08:00 · 2022-01-08 23:40:44 +08:00 · 2e14c6415d
commit 2e14c6415d
parent 15a9e03b85
2 changed files with 97 additions and 8 deletions
--- a/README.cn.md
+++ b/README.cn.md
@ -29,13 +29,22 @@ git clone https://gitee.com/iosetting/fw-lib_-stc8.git FwLib_STC8
 ├── src
 └── test
 ```
-3. 在代码中引用 `fw_hal.h`后, 就可以开始使用了
+3. 在 platformio.ini 中添加编译参数
+```
+build_flags =
+    -D__CONF_FOSC=36864000UL                       ;MCU的运行频率
+    -D__CONF_MCU_MODEL=MCU_MODEL_STC8H3K32S2       ;MCU型号
+    -D__CONF_CLKDIV=0x02                           ;以下参数均用于频率修剪
+    -D__CONF_IRCBAND=0x03
+    -D__CONF_VRTRIM=0x19
+    -D__CONF_IRTRIM=0x28
+    -D__CONF_LIRTRIM=0x00
+```
+4. 在代码中引用 `fw_hal.h`后, 就可以开始使用了
 ```c
 #include "fw_hal.h"
 ```

-4. 更多的使用细节, 请查看demo中的例程代码.
-

 # Keil C51 快速上手

@ -48,11 +57,47 @@ git clone https://gitee.com/iosetting/fw-lib_-stc8.git FwLib_STC8
 ```
 2. 复制(或移动)到 Keil C51 项目目录下
 3. 将其通过 Project -> Manage -> Project Items, 添加到项目文件中
-4. 在代码中引用 `fw_hal.h`后, 就可以开始使用了
+4. 通过菜单 Project -> Options for Target ... 打开项目选项, 切换到 C51 标签页, 在 Preprocessor Symbols -> Define 内输入以下内容
+```
+__CX51__, __CONF_MCU_MODEL=MCU_MODEL_STC8H3K32S2,__CONF_FOSC=36864000UL
+```
+关于以上的参数
+``` 
+   __CX51__ 将使宏定义切换为 Keil C51 关键字
+   __CONF_MCU_MODEL, 修改为你的MCU型号, 在 include/fw_conf.h 下可以查看所有的可用型号.
+   __CONF_FOSC The osc/irc MCU的运行频率, 可以使用STC-ISP下载时对MCU设定的频率.
+```
+5. 在代码中引用 `fw_hal.h`后, 就可以开始使用了
 ```c
 #include "fw_hal.h"
 ```

+# 宏定义
+
+封装库中引入了一些宏定义, 用于保证对 Keil C51 和 SDCC 的兼容性.
+
+命名和形式来源于 [sdcc compiler.h](https://sourceforge.net/p/sdcc/code/HEAD/tree/trunk/sdcc/device/include/mcs51/compiler.h). 
+如果你希望代码在 Keil C51 和 SDCC 下都能编译, 在编码时就应当使用这些宏, 而不是编译器对应的关键词.
+
+以下是相关的宏定义列表
+
+| Macro | Keil C51 | SDCC |
+| ----------- | ---------------- | ----------------- |
+| __BIT | bit | __bit |
+| __IDATA | idata | __idata |
+| __PDATA | pdata | __pdata |
+| __XDATA | xdata | __xdata |
+| __CODE | code | __code |
+| SBIT(name, addr, bit) | sbit name = addr^bit | __sbit __at(addr+bit) name |
+| SFR(name, addr) | sfr name = addr | __sfr __at(addr) name |
+| SFRX(addr) | (*(unsigned char volatile xdata *)(addr)) | (*(unsigned char volatile __xdata *)(addr)) |
+| SFR16X(addr) | (*(unsigned int  volatile xdata *)(addr)) | (*(unsigned int  volatile __xdata *)(addr)) |
+| INTERRUPT(name, vector) | void name (void) interrupt vector | void name (void) __interrupt (vector) |
+| INTERRUPT_USING(name, vector, regnum) | void name (void) interrupt vector using regnum | void name (void) __interrupt (vector) __using (regnum) |
+| NOP() | _nop_() | __asm NOP __endasm |
+
+这些宏定义可以在 include/fw_reg_base.h 中查看
+

 # 授权

--- a/README.md
+++ b/README.md
@ -29,14 +29,23 @@ git clone https://gitee.com/iosetting/fw-lib_-stc8.git FwLib_STC8
 ├── src
 └── test
 ```
-3. Include `fw_hal.h` in your code
+3. Add compile arguments in platformio.ini
+```
+build_flags =
+    -D__CONF_FOSC=36864000UL                       ;The osc/irc frequency you MCU will be running on
+    -D__CONF_MCU_MODEL=MCU_MODEL_STC8H3K32S2       ;change this to your MCU type
+    -D__CONF_CLKDIV=0x02                           ;frequency trimming
+    -D__CONF_IRCBAND=0x03
+    -D__CONF_VRTRIM=0x19
+    -D__CONF_IRTRIM=0x28
+    -D__CONF_LIRTRIM=0x00
+```
+4. Include `fw_hal.h` in your code
 ```c
 #include "fw_hal.h"
 ```
 then it's ready to use.

-4. For more detailed usage, please check the code in demos
-

 # Keil C51 Quick Start

@ -49,12 +58,47 @@ git clone https://gitee.com/iosetting/fw-lib_-stc8.git FwLib_STC8
 ```
 2. Copy(or move) it to your Keil C51 project directory, 
 3. Add it to project through Project -> Manage -> Project Items,
-4. Include `fw_hal.h` in your code
+4. Open project option dialog by clicking Project -> Options for Target ... , switch to C51 tab, and input following content in Preprocessor Symbols -> Define:
+```
+__CX51__, __CONF_MCU_MODEL=MCU_MODEL_STC8H3K32S2,__CONF_FOSC=36864000UL
+```
+The explanation of these arguments
+``` 
+   __CX51__ This will tell the macros to switch to Keil C51 keywords
+   __CONF_MCU_MODEL, change this to your MCU type, please look into FwLib_STC8/include/fw_conf.h for all available types.
+   __CONF_FOSC The osc/irc frequency you MCU will be running on. It equals to the frequency this MCU will be trimmed to in STC-ISP.
+```
+5. Include `fw_hal.h` in your code
 ```c
 #include "fw_hal.h"
 ```
 then it's ready to use.

+# Macros
+
+Some macros were introduced for code compatibility with Keil C51 and SDCC. 
+
+The naming is from [sdcc compiler.h](https://sourceforge.net/p/sdcc/code/HEAD/tree/trunk/sdcc/device/include/mcs51/compiler.h). If you want your code to work with both compilers, you need to stick to these macros instead of the compiler specific keywords:
+
+Here is a list of the macros:
+
+| Macro | Keil C51 | SDCC |
+| ----------- | ---------------- | ----------------- |
+| __BIT | bit | __bit |
+| __IDATA | idata | __idata |
+| __PDATA | pdata | __pdata |
+| __XDATA | xdata | __xdata |
+| __CODE | code | __code |
+| SBIT(name, addr, bit) | sbit name = addr^bit | __sbit __at(addr+bit) name |
+| SFR(name, addr) | sfr name = addr | __sfr __at(addr) name |
+| SFRX(addr) | (*(unsigned char volatile xdata *)(addr)) | (*(unsigned char volatile __xdata *)(addr)) |
+| SFR16X(addr) | (*(unsigned int  volatile xdata *)(addr)) | (*(unsigned int  volatile __xdata *)(addr)) |
+| INTERRUPT(name, vector) | void name (void) interrupt vector | void name (void) __interrupt (vector) |
+| INTERRUPT_USING(name, vector, regnum) | void name (void) interrupt vector using regnum | void name (void) __interrupt (vector) __using (regnum) |
+| NOP() | _nop_() | __asm NOP __endasm |
+
+The definition of these macros can be found in include/fw_reg_base.h
+

 # License