mynewt-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ad...@apache.org
Subject incubator-mynewt-site git commit: the build.py script requires me to track and commit again
Date Sat, 10 Dec 2016 23:52:50 GMT
Repository: incubator-mynewt-site
Updated Branches:
  refs/heads/master ce698cda2 -> cdce5e533


the build.py script requires me to track and commit again


Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/cdce5e53
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/cdce5e53
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/cdce5e53

Branch: refs/heads/master
Commit: cdce5e5337eed361a350c41f66df5c982c397838
Parents: ce698cd
Author: aditihilbert <aditi@runtime.io>
Authored: Fri Dec 9 23:56:19 2016 -0800
Committer: aditihilbert <aditi@runtime.io>
Committed: Fri Dec 9 23:56:19 2016 -0800

----------------------------------------------------------------------
 docs/os/modules/drivers/driver.md               | 50 ++++++++++++++++++++
 docs/os/modules/hal/hal_bsp/hal_bsp.md          | 19 ++++++++
 docs/os/modules/hal/hal_os_tick/hal_os_tick.md  | 28 +++++++++++
 docs/os/modules/hal/hal_timer/hal_timer.md      | 27 +++++++++++
 .../os/modules/hal/hal_watchdog/hal_watchdog.md | 28 +++++++++++
 5 files changed, 152 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/cdce5e53/docs/os/modules/drivers/driver.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/drivers/driver.md b/docs/os/modules/drivers/driver.md
new file mode 100644
index 0000000..8c5b586
--- /dev/null
+++ b/docs/os/modules/drivers/driver.md
@@ -0,0 +1,50 @@
+# Drivers
+
+###Description
+
+Device drivers in the Mynewt context includes libraries that interface with devices external
to the CPU. These devices are connected to the CPU via standard peripherals such as SPI, GPIO,
I2C etc. Device drivers leverage the base HAL services in Mynewt to provide friendly abstractions
to application developers. 
+
+```no-highlight
+
++———————————————————————————+
+|            app            |
++———————————————————————————+
+|          (n)drivers       |
++———————————————————————————+
+|     HAL     |     BSP     |
++—————————————+—————————————+
+
+```
+ 
+* The Board Support Package (BSP) abstracts board specific configurations e.g. CPU frequency,
input voltage, LED pins, on-chip flash map etc.
+
+* The Hardware Abstraction Layer (HAL) abstracts architecture-specific functionality. It
initializes and enables components within a master processor. It is designed to be portable
across all the various MCUs supported in Mynewt (e.g. Nordic's nRF51, Nordic's nRF52, NXP's
MK64F12 etc.). It includes code that initializes and manages access to components of the board
such as board buses (I2C, PCI, PCMCIA, etc.), off-chip memory (controllers, level 2+ cache,
Flash, etc.), and off-chip I/O (Ethernet, RS-232, display, mouse, etc.)
+
+* The driver sits atop the BSP and HAL. It abstracts the common modes of operation for each
peripheral device connected via the standard interfaces to the processor. There may be multiple
driver implementations of differing complexities for a particular peripheral device.  For
example, for an Analog to Digital Converter (ADC) peripheral you might have a simple driver
that does blocking ADC reads and uses the HAL only.  You might have a more complex driver
that can deal with both internal and external ADCs, and has chip specific support for doing
things like DMA’ing ADC reads into a buffer and posting an event to a task every ’n’
samples.  The drivers are the ones that register with the kernel’s power management APIs,
and manage turning on and off peripherals and external chipsets, etc. The Mynewt core repository
comes with a base set of drivers to help the user get started.
+
+
+### General design principles
+
+* Device drivers should have a consistent structure and unified interface whenever possible.
For example, we have a top-level package, “adc”, which contains the interface for all
ADC drivers, and then we have the individual implementation of the driver itself.  The following
source files point to this:
+
+    * high-level ADC API: `hw/drivers/adc/include/adc/adc.h` 
+    * implementation of ADC for STM32F4: `hw/drivers/adc/adc_stm32f4/src/adc_stm32f4.c` (As
of the 1.0.0-beta release, ADC for nRF51 and nRF52 are available at an external [repo](https://github.com/runtimeinc/mynewt_nordic/tree/master/hw/drivers/adc).
They are expected to be pulled into the core repo on Apache Mynewt after the license terms
are clarified.). The only exported call in this example is `int stm32f4_adc_dev_init(struct
os_dev *, void *)` which is passed as a function pointer to `os_dev_create()` in `hal_bsp.c`,
when the adc device is created.
+
+* Device drivers should be easy to use. In Mynewt, creating a device initializes it as well,
making it readily available for the user to open, use (e.g. read, configure etc.) and close.
Creating a device is simple using `os_dev_create(struct os_dev *dev, char *name, uint8_t stage,
uint8_t priority, os_dev_init_func_t od_init, void *arg)`. The `od_init` function is defined
within the appropriate driver directory e.g. `stm32f4_adc_dev_init` in `hw/drivers/adc/adc_stm32f4/src/adc_stm32f4.c`
for the ADC device initialization function. 
+
+* The implementation should allow for builds optimized for minimal memory usage. Additional
functionality can be enabled by writing a more complex driver (usually based on the simple
implementation included by default in the core repository) and optionally compiling the relevant
packages in. Typically, only a basic driver that addresses a device’s core functionality
(covering ~90% of use cases) is included in the Mynewt core repository, thus keeping the footprint
small.
+
+* The implementation should allow a user to be able to instantiate multiple devices of a
certain kind. In the Mynewt environment the user can, for example, maintain separate contexts
for multiple ADCs over different peripheral connections such as SPI, I2C etc. It is also possible
for a user to use a single peripheral interface (e.g. SPI) to drive multiple devices (e.g.
ADC), and in that case the device driver has to handle the proper synchronization of the various
tasks. 
+
+* Device drivers should be MCU independent. In Mynewt, device creation and operation functions
are independent of the underlying MCU. 
+* Device drivers should be able to offer high-level interfaces for generic operations common
to a particular device group. An example of such a class or group of devices is a group for
sensors with generic operations such as channel discovery, configure, and read values. The
organization of the driver directory is work in progress - so we encourage you to hop on the
dev@ mailing list and offer your insights!
+
+* Device drivers should be searchable. The plan is to have the newt tool offer a `newt pkg
search` capability. This is work in progress. You are welcome to join the conversation on
the dev@ mailing list!
+
+
+###Example
+
+The Mynewt core repo includes an example of a driver using the HAL to provide extra functionality
- the UART driver. It uses HAL GPIO and UART to provide multiple serial ports on the NRF52
(but allowed on other platforms too.)
+
+The gist of the driver design is that there is an API for the driver (for use by applications),
and then sub-packages to that driver that implement that driver API using the HAL and BSP
APIs.
+

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/cdce5e53/docs/os/modules/hal/hal_bsp/hal_bsp.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/hal/hal_bsp/hal_bsp.md b/docs/os/modules/hal/hal_bsp/hal_bsp.md
new file mode 100644
index 0000000..0380459
--- /dev/null
+++ b/docs/os/modules/hal/hal_bsp/hal_bsp.md
@@ -0,0 +1,19 @@
+# hal_bsp
+
+
+This is the hardware independent BSP (Board Support Package) Interface for Mynewt.
+
+### Description
+
+Contains the basic operations to initialize, specify memory to include in coredump, configure
interrupt priority etc.
+
+### Definition
+
+[hal_bsp.h](https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_bsp.h)
+
+### Examples
+
+
+<br>
+
+---------------------

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/cdce5e53/docs/os/modules/hal/hal_os_tick/hal_os_tick.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/hal/hal_os_tick/hal_os_tick.md b/docs/os/modules/hal/hal_os_tick/hal_os_tick.md
new file mode 100644
index 0000000..216cccc
--- /dev/null
+++ b/docs/os/modules/hal/hal_os_tick/hal_os_tick.md
@@ -0,0 +1,28 @@
+# hal_os_tick
+
+The hardware independent interface to set up interrupt timers or halt CPU in terms of OS
ticks.
+
+###Description
+
+Set up the periodic timer to interrupt at a frequency of 'os_ticks_per_sec' using the following
function call where 'prio' is the cpu-specific priority of the periodic timer interrupt. 
+
+```c
+void os_tick_init(uint32_t os_ticks_per_sec, int prio);
+```
+
+You can halt CPU for up to `n` ticks:
+
+```c
+void os_tick_idle(os_time_t n);
+```
+
+The function implementations are in the mcu-specific directories such as `hw/mcu/nordic/nrf51xxx/src/hal_os_tick.c`.
+
+
+###Definition
+
+[hal_os_tick.h](https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_os_tick.h)
+
+###Examples
+
+An example of the API being used by the OS kernel for the Cortex M0 architecture to initialize
and start the system clock timer can be seen in [kernel/os/src/arch/cortex_m0/os_arch_arm.c](https://github.com/apache/incubator-mynewt-core/blob/master/kernel/os/src/arch/cortex_m0/os_arch_arm.c).

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/cdce5e53/docs/os/modules/hal/hal_timer/hal_timer.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/hal/hal_timer/hal_timer.md b/docs/os/modules/hal/hal_timer/hal_timer.md
new file mode 100644
index 0000000..cc2be46
--- /dev/null
+++ b/docs/os/modules/hal/hal_timer/hal_timer.md
@@ -0,0 +1,27 @@
+# hal_timer
+
+The hardware independent timer structure and API to configure, initialize, and run timers.
+
+###Description
+
+The HAL timer structure is shown below. The user can declare as many of these structures
as required. They are enqueued on a particular HW timer queue when the user calls the hal_timer_start
or hal_timer_start_at API. The user must have called hal_timer_set_cb before starting a timer.
+
+NOTE: the user should not have to modify/examine the contents of this structure; the hal
timer API should be used.
+
+```c
+struct hal_timer
+{
+    void                *bsp_timer; /* Internal platform specific pointer */
+    hal_timer_cb        cb_func;    /* Callback function */
+    void                *cb_arg;    /* Callback argument */
+    uint32_t            expiry;     /* Tick at which timer should expire */
+    TAILQ_ENTRY(hal_timer) link;    /* Queue linked list structure */
+};
+```
+
+###Definition
+
+[hal_timer.h](https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_timer.h)
+
+###Examples
+

http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/cdce5e53/docs/os/modules/hal/hal_watchdog/hal_watchdog.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/hal/hal_watchdog/hal_watchdog.md b/docs/os/modules/hal/hal_watchdog/hal_watchdog.md
new file mode 100644
index 0000000..d9ce4fe
--- /dev/null
+++ b/docs/os/modules/hal/hal_watchdog/hal_watchdog.md
@@ -0,0 +1,28 @@
+# hal_watchdog
+
+
+The hardware independent interface to enable internal hardware watchdogs.
+
+###Description
+
+The `hal_watchdog_init` interface can be used to set a recurring watchdog timer to fire no
sooner than in 'expire_secs' seconds. 
+
+```c
+int hal_watchdog_init(uint32_t expire_msecs);
+```
+
+Watchdog needs to be then started with a call to `hal_watchdog_enable()`.
+Watchdog should be tickled periodically with a frequency smaller than 'expire_secs' using
`hal_watchdog_tickle()`.
+
+
+###Definition
+
+[hal_watchdog](https://github.com/apache/incubator-mynewt-core/blob/master/hw/hal/include/hal/hal_watchdog.h)
+
+
+###Examples
+
+The OS initializes and starts a watchdog timer and tickles it periodically to check that
the OS is running properly. This can be seen in [/kernel/os/src/os.c](https://github.com/apache/incubator-mynewt-core/blob/master/kernel/os/src/os.c).
+
+
+


Mime
View raw message