| Drivers |
| ======= |
| |
| .. toctree:: |
| :maxdepth: 1 |
| |
| flash <flash> |
| mmc <mmc> |
| |
| |
| 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. |
| |
| .. code-block:: console |
| |
| |
| +———————————————————————————+ |
| | 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/runtimeco/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. |
| |
| Implemented drivers |
| ~~~~~~~~~~~~~~~~~~~ |
| |
| Drivers live under ``hw/drivers``. The current list of supported drivers |
| includes: |
| |
| +----------------------------------------+--------------------------+ |
| | Driver | Description | |
| +========================================+==========================+ |
| | ``adc`` | TODO: ADC driver. | |
| +----------------------------------------+--------------------------+ |
| | ``flash`` | SPI/I2C flash drivers. | |
| +----------------------------------------+--------------------------+ |
| | ``lwip`` | TODO: LWIP. | |
| +----------------------------------------+--------------------------+ |
| | ``mmc`` | MMC/SD card driver. | |
| +----------------------------------------+--------------------------+ |
| | ``sensors`` | TODO: sensors. | |
| +----------------------------------------+--------------------------+ |
| | ``uart`` | TODO: UART driver. | |
| +----------------------------------------+--------------------------+ |
