深入理解Arduino下的ESP8266_Non-OS_SDK API① Non-OS SDK

授人以鱼不如授人以渔，目的不是为了教会你具体项目开发，而是学会学习的能力。希望大家分享给你周边需要的朋友或者同学，说不定大神成长之路有博哥的奠基石。。。

1.前言

    在介绍Arduino Core For ESP8266的时候，博主之前一直讲解Arduino For ESP8266，但是它本质上还是基于ESP8266 Non-OS SDK，所以有必要去了解一下Arduino下的ESP8266 Nos-OS SDK。

2.ESP8266 Non-OS SDK

2.1 简介

    Non-OS SDK为用户提供了一套应用程序编程接⼝ (API)，能够实现 ESP8266 的核心功能
改，例如数据接收/发送、TCP/IP 功能、硬件接口功能，以及基本的系统管理功能等。⽤
户不必关心底层网络，如 Wi-Fi、TCP/IP 等的具体实现，只需要专注于物联网上层应用的
开发，利用相应接口实现各种功能即可。
ESP8266 物联网平台的所有网络功能均在库中实现，对用户不透明。用户应用的初始化
功能可以在 user_main.c 中实现。

    根据上面这点说明，我们去查阅Arduino Core For ESP8266的源码，可以发现以下关键代码（代码在core_esp8266_main.cpp，请读者关注一下中文注释就好）：

/*
 main.cpp - platform initialization and context switching
 emulation

 Copyright (c) 2014 Ivan Grokhotkov. All rights reserved.
 This file is part of the esp8266 core for Arduino environment.

 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

//This may be used to change user task stack size:
//#define CONT_STACKSIZE 4096
#include <Arduino.h>
#include "Schedule.h"
extern "C" {
#include "ets_sys.h"
#include "os_type.h"
#include "osapi.h"
#include "mem.h"
#include "user_interface.h"
#include "cont.h"
}
#include <core_version.h>
#include "gdb_hooks.h"
//轮询任务相关
#define LOOP_TASK_PRIORITY 1
#define LOOP_QUEUE_SIZE    1
#define OPTIMISTIC_YIELD_TIME_US 16000

extern "C" void call_user_start();
//是不是非常熟悉的两个方法。。。。
extern void loop();
extern void setup();
//是不是非常熟悉的两个方法。。。。
extern void (*__init_array_start)(void);
extern void (*__init_array_end)(void);

/* Not static, used in Esp.cpp */
//用户重置信息，特别是异常信息
struct rst_info resetInfo;

/* Not static, used in core_esp8266_postmortem.c and other places.
 * Placed into noinit section because we assign value to this variable
 * before .bss is zero-filled, and need to preserve the value.
 */
cont_t* g_pcont __attribute__((section(".noinit")));

/* Event queue used by the main (arduino) task */
//创建一个事件队列，队列大小是1
static os_event_t s_loop_queue[LOOP_QUEUE_SIZE];

/* Used to implement optimistic_yield */
static uint32_t s_micros_at_task_start;


extern "C" {
extern const uint32_t __attribute__((section(".ver_number"))) core_version = ARDUINO_ESP8266_GIT_VER;
const char* core_release = 
#ifdef ARDUINO_ESP8266_RELEASE
    ARDUINO_ESP8266_RELEASE;
#else
    NULL;
#endif
} // extern "C"

void initVariant() __attribute__((weak));
void initVariant() {
}

void preloop_update_frequency() __attribute__((weak));
void preloop_update_frequency() {
#if defined(F_CPU) && (F_CPU == 160000000L)
    REG_SET_BIT(0x3ff00014, BIT(0));
    ets_update_cpu_frequency(160);
#endif
}


extern "C" void esp_yield() {
    if (cont_can_yield(g_pcont)) {
        cont_yield(g_pcont);
    }
}

extern "C" void esp_schedule() {
    ets_post(LOOP_TASK_PRIORITY, 0, 0);
}

extern "C" void __yield() {
    if (cont_can_yield(g_pcont)) {
        esp_schedule();
        esp_yield();
    }
    else {
        panic();
    }
}

extern "C" void yield(void) __attribute__ ((weak, alias("__yield")));

extern "C" void optimistic_yield(uint32_t interval_us) {
    if (cont_can_yield(g_pcont) &&
        (system_get_time() - s_micros_at_task_start) > interval_us)
    {
        yield();
    }
}

//真正的业务操作，这是一个非常重要的方法
static void loop_wrapper() {
    static bool setup_done = false;
    preloop_update_frequency();
    if(!setup_done) {
        //这里就是我们常见的setup方法
        setup();
        setup_done = true;
    }
    //这里就是我们常见的loop方法 终于看到arduino相关的了
    loop();
    //下面这个方法也非常重要 顾名思义 schedule（日程安排 跟配置好的一些回调方法相关）， 但是请注意这个方法是在loop后面执行的。。
    run_scheduled_functions();
    esp_schedule();
}

//轮询任务
static void loop_task(os_event_t *events) {
    (void) events;
    s_micros_at_task_start = system_get_time();
    cont_run(g_pcont, &loop_wrapper);
    //发现情况不对 就执行panic
    if (cont_check(g_pcont) != 0) {
        panic();
    }
}

static void do_global_ctors(void) {
    void (**p)(void) = &__init_array_end;
    while (p != &__init_array_start)
        (*--p)();
}

//初始化完成操作
void init_done() {
   //设置打印功能
    system_set_os_print(1);
    gdb_init();
    do_global_ctors();
    esp_schedule();
}

/* This is the entry point of the application.
 * It gets called on the default stack, which grows down from the top
 * of DRAM area.
 * .bss has not been zeroed out yet, but .data and .rodata are in place.
 * Cache is not enabled, so only ROM and IRAM functions can be called.
 * Peripherals (except for SPI0 and UART0) are not initialized.
 * This function does not return.
 */
/*
   A bit of explanation for this entry point:

   SYS is the SDK task/context used by the upperlying system to run its
   administrative tasks (at least WLAN and lwip's receive callbacks and
   Ticker).  NONOS-SDK is designed to run user's non-threaded code in
   another specific task/context with its own stack in BSS.

   Some clever fellows found that the SYS stack was a large and quite unused
   piece of ram that we could use for the user's stack instead of using user's
   main memory, thus saving around 4KB on ram/heap.

   A problem arose later, which is that this stack can heavily be used by
   the SDK for some features.  One of these features is WPS.  We still don't
   know if other features are using this, or if this memory is going to be
   used in future SDK releases.

   WPS beeing flawed by its poor security, or not beeing used by lots of
   users, it has been decided that we are still going to use that memory for
   user's stack and disable the use of WPS.

   app_entry() jumps to app_entry_custom() defined as "weakref" calling
   itself a weak customizable function, allowing to use another one when
   this is required (see core_esp8266_app_entry_noextra4k.cpp, used by WPS).

   (note: setting app_entry() itself as "weak" is not sufficient and always
    ends up with the other "noextra4k" one linked, maybe because it has a
    default ENTRY(app_entry) value in linker scripts).

   References:
   https://github.com/esp8266/Arduino/pull/4553
   https://github.com/esp8266/Arduino/pull/4622
   https://github.com/esp8266/Arduino/issues/4779
   https://github.com/esp8266/Arduino/pull/4889

*/

extern "C" void ICACHE_RAM_ATTR app_entry_redefinable(void) __attribute__((weak));
extern "C" void ICACHE_RAM_ATTR app_entry_redefinable(void)
{
    /* Allocate continuation context on this SYS stack,
       and save pointer to it. */
    cont_t s_cont __attribute__((aligned(16)));
    g_pcont = &s_cont;

    /* Call the entry point of the SDK code. */
    call_user_start();
}

static void ICACHE_RAM_ATTR app_entry_custom (void) __attribute__((weakref("app_entry_redefinable")));

extern "C" void ICACHE_RAM_ATTR app_entry (void)
{
    return app_entry_custom();
}

//程序入口函数
extern "C" void user_init(void) {
    //打印重启信息 特别是异常信息
    struct rst_info *rtc_info_ptr = system_get_rst_info();
    memcpy((void *) &resetInfo, (void *) rtc_info_ptr, sizeof(resetInfo));

    uart_div_modify(0, UART_CLK_FREQ / (115200));

    init();

    initVariant();

    cont_init(g_pcont);
    //开始业务操作 跑轮询任务
    ets_task(loop_task,
        LOOP_TASK_PRIORITY, s_loop_queue,
        LOOP_QUEUE_SIZE);
    //初始化完成
    system_init_done_cb(&init_done);
}

2.2 代码结构

    Non-OS SDK 不像基于RTOS的应用程序支持任务调度。Non-OS SDk使用四种类型的函数：

• 应用函数
• 回调函数
• 用户任务(不讲)
• 中断服务程序 (Interrupt Service Routines, ISR)

2.2.1 应用函数

• 就是普通常用C函数。这些函数必须由另一个函数调用。
• 应用函数定义时建议添加 ICACHE_FLASH_ATTR 宏，对应函数将存放在flash中，被调用时才加载到cache运行。而如果添加了IRAM ATTR宏的函数，则会在上电启动时就加载到IRAM中；

2.2.2 回调函数

• 不直接从用户程序调用的函数，而是当某系统事件发生时，相应的回调函数由non-OS SDK内核调用执行。这使得开发者能够在不使用RTOS或者轮询事件的情况下响应实时事件；

2.2.3 中断服务程序

• 特殊类型的回调函数，发生硬件中断时会调用这些函数
• 使能中断时，必须注册相应的中断处理函数
• ISR必须添加IRAM_ATTR

注意点：

• non-OS SDK不支持抢占任务或者进程切换。因此开发者需要自行保证程序的正确运行，用户代码不能长期占用CPU。否则会导致看门狗复位，esp8266重启。
• 如果用户必须执行较长时间（比如大于500ms），建议经常调用 system_soft_wdt_feed（）API来喂软件看门狗，而不建议禁用软件看门狗。

2.3 系统性能

• ESP8266通常的运行速率是80MHz，在高性能应用中也可以配置为160MHz。但是，请注意，外设不受CPU频率设置的影响，因为它们使用了不同的时钟源。
• 设置更高的时钟频率或者禁用休眠模式，会导致更大的功耗，但能获得更好的性能。需要两者考虑平衡点；
• 添加了 ICACHE_FLASH_ATTR 的代码通常比使用 ICACHE_RAM_ATTR 标记的代码执行得慢。然而，像大多数嵌入式平台一样，ESP8266的IRAM空间有限，建议一般代码添加 ICACHE_FLASH_ATTR ，仅对执行效率要求高的代码添加 ICACHE_RAM_ATTR宏。
• Flash模式和频率直接影响代码执行速度。将flash设置为更高的频率和QIO模式会产生更好的性能，但会导致更大的功耗。

2.4 系统存储

• ESP8266支持高达 128 Mbits 的外部 QSPI flash，用于存储代码和数据。也可以使用辅
  助存储芯片来存储用户数据。
• ESP8266 带有 160 KB 的 RAM，其中 64 KB 为 iRAM，96 KB 为 dRAM。iRAM 进一步
  分成两块：32 KB iRAM 块运行标有 ICACHE_RAM_ATTR 的代码，另一个 32 KB 块用作
  cache，运行标有 ICACHE_FLASH_ATTR 的代码。
• RAM 和 flash访问都是4字节对齐，请勿直接进行指针转换（os_memcpy）