diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md new file mode 100644 index 000000000..d14b9fdb1 --- /dev/null +++ b/CODING_STANDARDS.md @@ -0,0 +1,267 @@ +# Coding Style for Apache NimBLE + +Apache NimBLE project is part of Apache Mynewt projct and follows its coding +style. + +# Coding Style for Apache Mynewt Core + +This document is meant to define the coding style for Apache Mynewt, and +all subprojects of Apache Mynewt. This covers C and Assembly coding +conventions, *only*. Other languages (such as Go), have their own +coding conventions. + +## Headers + +* All files that are newly written, should have the Apache License clause +at the top of them. + +* For files that are copied from another source, but contain an Apache +compatible license, the original license header shall be maintained. + +* For more information on applying the Apache license, the definitive +source is here: http://www.apache.org/dev/apply-license.html + +* The Apache License clause for the top of files is as follows: + +```no-highlight +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +``` + +## Whitespace and Braces + +* Code must be indented to 4 spaces, tabs should not be used. + +* Do not add whitespace at the end of a line. + +* Put space after keywords (for, if, return, switch, while). + +* for, else, if, while statements must have braces around their +code blocks, i.e., do: + +``` + if (x) { + assert(0); + } else { + assert(0); + } +``` + +Not: + +``` + if (x) + assert(0); + else + assert(0); +``` + +* Braces for statements must be on the same line as the statement. Good: + +``` + for (i = 0; i < 10; i++) { + if (i == 5) { + break; + } else { + continue; + } + } +``` + +Not: + +``` + for (i = 0; i < 10; i++) + { <-- brace must be on same line as for + if (i == 5) { + break; + } <-- no new line between else + else { + continue; + } + } +``` + +* After a function declaration, the braces should be on a newline, i.e. do: + +``` + static void * + function(int var1, int var2) + { +``` + +not: + +``` + static void * + function(int var1, int var2) { +``` + +## Line Length and Wrap + +* Line length should never exceed 79 columns. + +* When you have to wrap a long statement, put the operator at the end of the + line. i.e.: + +``` + if (x && + y == 10 && + b) +``` + +Not: + +``` + if (x + && y == 10 + && b) +``` + +## Comments + +* No C++ style comments allowed. + +* When using a single line comment, put it above the line of code that you +intend to comment, i.e., do: + +``` + /* check variable */ + if (a) { +``` + +Not: + +``` + if (a) { /* check variable */ +``` + + +* All public APIs should be commented with Doxygen style comments describing +purpose, parameters and return values. Private APIs need not be documented. + + +## Header files + +* Header files must contain the following structure: + * Apache License (see above) + * ```#ifdef``` aliasing, to prevent multiple includes + * ```#include``` directives for other required header files + * ```#ifdef __cplusplus``` wrappers to maintain C++ friendly APIs + * Contents of the header file + +* ```#ifdef``` aliasing, shall be in the following format, where +the package name is "os" and the file name is "callout.h": + +```no-highlight +#ifndef _OS_CALLOUT_H +#define _OS_CALLOUT_H +``` + +* ```#include``` directives must happen prior to the cplusplus +wrapper. + +* The cplusplus wrapper must have the following format, and precedes +any contents of the header file: + +```no-highlight +#ifdef __cplusplus +#extern "C" { +##endif +``` + +## Naming + +* Names of functions, structures and variables must be in all lowercase. + +* Names should be as short as possible, but no shorter. + +* Globally visible names must be prefixed with the name of the module, +followed by the '_' character, i.e.: + +``` + os_callout_init(&c) +``` + +Not: + +``` + callout_init(c) +``` + +## Functions + +* No spaces after function names when calling a function, i.e, do: + +``` + rc = function(a) +``` + +Not: + +``` + rc = function (a) +``` + + +* Arguments to function calls should have spaces between the comma, i.e. do: + +``` + rc = function(a, b) +``` + +Not: + +``` + rc = function(a,b) +``` + +* The function type must be on a line by itself preceding the function, i.e. do: + +``` + static void * + function(int var1, int var2) + { +``` + +Not: + +``` + static void *function(int var1, int var2) + { +``` + +* In general, for functions that return values that denote success or error, 0 +shall be success, and non-zero shall be the failure code. + +## Variables and Macros + +* Do not use typedefs for structures. This makes it impossible for +applications to use pointers to those structures opaquely. + +* typedef may be used for non-structure types, where it is beneficial to +hide or alias the underlying type used (e.g. ```os_time_t```.) Indicate +typedefs by applying the ```_t``` marker to them. + +* Place all function-local variable definitions at the top of the function body, before any statements. + +## Compiler Directives + +* Code must compile cleanly with -Wall enabled. + diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..8b36d826d --- /dev/null +++ b/LICENSE @@ -0,0 +1,449 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright {yyyy} {name of copyright owner} + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +This product bundles crc16, which is available under the "3-clause BSD" +license. For details, see: + * util/crc/include/crc/crc16.h + * util/crc/src/crc16.c + +This product bundles queue.h 8.5, which is available under the "3-clause BSD" +license. For details, see kernel/os/include/os/queue.h + +This product partly derives from FreeBSD, which is available under the +"3-clause BSD" license. For details, see: + * kernel/os/include/os/os_time.h + * kernel/os/src/os_mbuf.c + * encoding/base64/src/base64.c + * time/datetime/src/datetime.c + +This product bundles baselibc, which is available under the "3-clause BSD" +license. Baselibc bundles tinyprintf and is based on klibc for details see: +libc/baselibc/LICENSE + +This product bundles tinyprintf, which is available under the "3-clause BSD" +license. For details, see libc/baselibc/src/tinyprintf.c + +This product contains code based on klibc, which is available under the MIT +license. For details, see libc/baselibc/LICENSE + +This product bundles microjson, which is available under the "3-clause BSD" +license. For details, see encoding/json/ + +This product bundles and partly derives from parts of the Nordic nRF52 SDK, +which are available under a BSD style license. Relevant files are: + * hw/bsp/nrf51dk/src/arch/cortex_m0/gcc_startup_nrf51.s + * hw/bsp/nrf51dk/src/arch/cortex_m0/gcc_startup_nrf51_split.s + * hw/bsp/nrf52840pdk/src/arch/cortex_m4/gcc_startup_nrf52840.s + * hw/bsp/nrf52840pdk/src/arch/cortex_m4/gcc_startup_nrf52_split.s + * hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52.s + * hw/bsp/nrf52dk/src/arch/cortex_m4/gcc_startup_nrf52_split.s + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51422.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52840.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52840.h + +This product bundles Gary S. Brown's CRC32 implementation, which is available under the following license: + COPYRIGHT (C) 1986 Gary S. Brown. You may use this program, or + code or tables extracted from it, as desired without restriction. + +This product bundles parts of CMSIS-CORE, which is available under the +"3-clause BSD" license. Bundled files are: + * hw/cmsis-core/ + * kernel/os/src/arch/cortex_m0/m0/HAL_CM0.s + * kernel/os/src/arch/cortex_m0/m0/SVC_Table.s + * kernel/os/src/arch/cortex_m4/m4/HAL_CM4.s + * kernel/os/src/arch/cortex_m4/m4/SVC_Table.s + +This product bundles additional files from CMSIS-CORE, but these files are +missing licensing information. The BSD license was subsequently added to +these files in later releases. These files are: + * hw/cmsis-core/src/cmsis_nvic.c + * hw/mcu/ambiq/apollo2/include/mcu/cmsis_nvic.h + * hw/mcu/nordic/nrf51xxx/include/mcu/cmsis_nvic.h + * hw/mcu/nordic/nrf52xxx/include/mcu/cmsis_nvic.h + * hw/mcu/nxp/MK64F12/include/mcu/cmsis_nvic.h + * hw/mcu/nxp/mkw41z/include/mcu/cmsis_nvic.h + * hw/mcu/stm/stm32f1xx/include/mcu/cmsis_nvic.h + * hw/mcu/stm/stm32f3xx/include/mcu/cmsis_nvic.h + * hw/mcu/stm/stm32f4xx/include/mcu/cmsis_nvic.h + * hw/mcu/stm/stm32f7xx/include/mcu/cmsis_nvic.h + * hw/mcu/stm/stm32l1xx/include/mcu/cmsis_nvic.h + +This product bundles parts of STM32CubeF4 1.5, which is available under the +"3-clause BSD" license. Bundled files are: + * hw/mcu/stm/stm32f4xx/src/ext + * hw/bsp/nucleo-f401re/src/arch/cortex_m4/startup_STM32F40x.s + * hw/bsp/nucleo-f401re/include/bsp/stm32f4xx_hal_conf.h + * hw/bsp/nucleo-f401re/src/system_stm32f4xx.c + * hw/bsp/olimex_stm32-e407_devboard/src/arch/cortex_m4/startup_STM32F40x.s + * hw/bsp/olimex_stm32-e407_devboard/include/bsp/stm32f4xx_hal_conf.h + * hw/bsp/olimex_stm32-e407_devboard/src/system_stm32f4xx.c + * hw/bsp/stm32f4discovery/src/arch/cortex_m4/startup_STM32F40x.s + * hw/bsp/stm32f4discovery/include/bsp/stm32f4xx_hal_conf.h + * hw/bsp/stm32f4discovery/src/system_stm32f4xx.c + +This product bundles parts of STM32CubeF7, which is available under the +"3-clause BSD" license. Bundled files are: + * hw/mcu/stm/stm32f7xx/src/ext + * hw/bsp/stm32f767-nucleo/include/bsp/stm32f7xx_hal_conf.h + * hw/bsp/stm32f767-nucleo/src/system_stm32f7xx.c + * hw/bsp/stm32f767-nucleo/src/arch/cortex_m7/startup_stm32f767xx.s + +This product bundles parts of mbed, which is available under the +"3-clause BSD" license. Bundled files are: + * hw/mcu/nordic/nrf51xxx/include/mcu/cortex_m0.h + * hw/mcu/nordic/nrf52xxx/include/mcu/cortex_m4.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/compiler_abstraction.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf51.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52840.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf51_to_nrf52.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf51_to_nrf52840.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52_to_nrf52840.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf51_bitfields.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52_bitfields.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52840_bitfields.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52840_peripherals.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf51_deprecated.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51422.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf51422.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52840.c + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/toolchain/system_nrf52840.h + * hw/mcu/nordic/src/ext/nRF5_SDK_11.0.0_89a8197/components/device/nrf52_name_change.h + +This product bundles FATFS, which is available under a +"1-clause BSD" style license. Bundled files are: + * fs/fatfs/include/fatfs/diskio.h + * fs/fatfs/include/fatfs/ff.h + * fs/fatfs/include/fatfs/ffconf.h + * fs/fatfs/include/fatfs/integer.h + * fs/fatfs/src/ff.c + * fs/fatfs/src/option/unicode.c + +This product bundles part of linker scripts Nordic Semiconductor nRF5 devices, which is available under the +"modified Tcl/Tk" license. Bundled files are: + * hw/bsp/nrf52840pdk/split-nrf52840pdk.ld + * hw/bsp/nrf52840pdk/nrf52840pdk_no_boot.ld + * hw/bsp/bmd300eval/bmd300eval_no_boot.ld + * hw/bsp/nrf51dk-16kbram/nrf51dk-16kbram_no_boot.ld + * hw/bsp/nrf51dk/nrf51dk_no_boot.ld + * hw/bsp/nrf52dk/nrf52dk_no_boot.ld + * hw/mcu/nordic/nrf51xxx/nrf51.ld + * hw/mcu/nordic/nrf52xxx/nrf52.ld + * hw/mcu/ambiq/apollo2/apollo2.ld + +This product bundles part of NXP/FreeScale SDK, which is available +under the "3-clause BSD" license. Bundled files are: + * hw/mcu/nxp/src/ext + +This product bundles part of NXP mkw41z, which is available under the +"3-clause BSD" license. Bundled files are: + * hw/mcu/nxp/mkw41z/include/mcu/MKW41Z4.h + * hw/mcu/nxp/mkw41z/include/mcu/MKW41Z4_features.h + * hw/mcu/nxp/mkw41z/include/mcu/fsl_device_registers.h + * hw/mcu/nxp/mkw41z/include/mcu/system_MKW41Z4.h + * hw/mcu/nxp/mkw41z/src/system_MKW41Z4.c + * hw/bsp/usbmkw41z/boot-mkw41z512.ld + * hw/bsp/usbmkw41z/mkw41z512.ld + * hw/bsp/usbmkw41z/no-boot-mkw41z512.ld + * hw/bsp/usbmkw41z/src/arch/cortex_m0/gcc_startup_mkw41z.s + +This product bundles part of mips architecture and ci40, which is available +under the "3-clause BSD" license. Bundled files are: + * kernel/os/src/arch/mips/asm/ctx.S + * kernel/os/src/arch/mips/asm/excpt_isr.S + * hw/bsp/ci40/uhi32.ld + +This product bundles LwIP, which is available under the "3-clause BSD" +license. For details, and bundled files see: + * net/ip/lwip_base/COPYING + * net/ip/lwip_base + +This product bundles tinycrypt, which is available under the "3-clause BSD" +license. For details, and bundled files see: + * crypto/tinycrypt/LICENSE + * crypto/tinycrypt + +This product bundles parts of the Generic SX1276 driver from Semtech, which +is available under the "3-clause BSD" license. For details, see: + * apps/loraping/src/main.c + * hw/drivers/lora/sx1276/LICENSE.txt + +This product bundles parts of SEGGER RTT, which is available under the +"3-clause BSD" license. For details, see: + * hw/drivers/rtt + +This products bundle Adafruit's tsl2561 driver, which is available under the +"3-clause BSD" license. For details, see: + * hw/drivers/sensors/tsl2561 + +This products bundles Amiq Micro Apollo 2, which is available under the +"3-clause BSD" license. Bundled files are: + * hw/mcu/ambiq/apollo2/include/mcu/apollo2.h + * hw/mcu/ambiq/apollo2/include/mcu/system_apollo2.h + +This product bundles processor headers for PIC32 by Microchip Technology +Inc., which is available under the "3-clause BSD" license. Bundled files are: + * hw/mcu/microchip/pic32mx470f512h/include/mcu/p32mx470f512h.h + * hw/mcu/microchip/pic32mx470f512h/include/mcu/ppic32mx.h + +This product bundles MIPS processor low-level macros by Imagination +Technologies Limited, which is available under the "3-clause BSD" license. +Bundled files are included inside: + * hw/mips-hal/src/arch/mips + +This product bundles parts of LoRaWAN endpoint stack by Semtech, which is +available under the "3-clause BSD" license. For details, see: + * net/lora/node/LICENSE.txt + +This product bundles Eclipse Paho's MQTT by IBM Corp. which is available +under the Eclipse Public License 1.0. For details see: + * net/mqtt/eclipse/LICENSE.txt + +This product bundles SEGGER SystemView, which is available under the +"3-clause BSD" license. For details, see: + * sys/sysview/vendor + +This product bundles normalizer.css, affix.js and scrollspy.js by Twitter +which are available under the MIT license. Bundled files are: + * docs/_static/css/bootstrap-3.0.3.min.css + * docs/themes/mynewt/static/js/affix.js + * docs/themes/mynewt/static/js/scrollspy.js + +This product bundles tinycbor by Intel Corporation, which is available under +the MIT license. For details see: + * encoding/tinycbor/include/tinycbor + +This product bundles FontAwesome by Dave Gandy, which is available under the +SIL Open Font License 1.1. Bundled files are: + * docs/themes/mynewt/static/fonts/fontawesome-webfont.eot + * docs/themes/mynewt/static/fonts/fontawesome-webfont.svg + * docs/themes/mynewt/static/fonts/fontawesome-webfont.ttf + * docs/themes/mynewt/static/fonts/fontawesome-webfont.woff + * docs/themes/mynewt/static/fonts/FontAwesome.otf + +This product bundles Inconsolata by Raph Levien, which is available under the +SIL Open Font License 1.1. Bundled files are: + * docs/themes/mynewt/static/fonts/Inconsolata-Bold.ttf + * docs/themes/mynewt/static/fonts/Inconsolata-Regular.ttf + +This product bundles Lato by Łukasz Dziedzic, which is available under the +SIL Open Font License 1.1. Bundled files are: + * docs/themes/mynewt/static/fonts/Lato-Bold.ttf + * docs/themes/mynewt/static/fonts/Lato-Regular.ttf + +This product bundles RobotSlab by Christian Robertson, which is available +under the Apache License v2.0. Bundled files are: + * docs/themes/mynewt/static/fonts/RobotoSlab-Bold.ttf + * docs/themes/mynewt/static/fonts/RobotoSlab-Regular.ttf + +This product bundles part of embARC BSP SDK by Synopsys, which is available +under the "3-clause BSD" license. Bundled files are: + * hw/mcu/arc/src/ext/sdk diff --git a/NOTICE b/NOTICE new file mode 100644 index 000000000..fc24c6abc --- /dev/null +++ b/NOTICE @@ -0,0 +1,8 @@ +Apache Mynewt NimBLE +Copyright 2015-2018 The Apache Software Foundation + +This product includes software developed at +The Apache Software Foundation (http://www.apache.org/). + +Portions of this software were developed at +Runtime Inc, copyright 2015. diff --git a/README.md b/README.md new file mode 100644 index 000000000..b92f3f673 --- /dev/null +++ b/README.md @@ -0,0 +1,172 @@ + + +Apache Mynewt + +## Overview + +Apache NimBLE is an open-source Bluetooth 5.0 stack (both Host & Controller) +that completely replaces the proprietary SoftDevice on Nordic chipsets. It is +part of [Apache Mynewt project](https://github.com/apache/mynewt-core). + +Features highlight: + - Support for 251 byte packet size + - Support for all 4 roles concurrently - Broadcaster, Observer, Peripheral and Central + - Support for up to 32 simultaneous connections. + - Legacy and SC (secure connections) SMP support (pairing and bonding). + - Advertising Extensions. + - Coded (aka Long Range) and 2M PHYs. + - Bluetooth Mesh. + +## Supported hardware + +Controller supports Nordic nRF51 and nRF52 chipsets. Host runs on any board +and architecture [supported](https://github.com/apache/mynewt-core#overview) +by Apache Mynewt OS. + + +## Browsing + +If you are browsing around the source tree, and want to see some of the +major functional chunks, here are a few pointers: + +- nimble/controller: Contains code for controller including Link Layer and HCI implementation +([controller](https://github.com/apache/mynewt-nimble/tree/master/nimble/controller)) + +- nimble/drivers: Contains drivers for supported radio transceivers (Nordic nRF51 and nRF52) +([drivers](https://github.com/apache/mynewt-nimble/tree/master/nimble/drivers)) + +- nimble/host: Contains code for host subsystem. This includes protocols like +L2CAP and ATT, support for HCI commands and events, Generic Access Profile (GAP), +Generic Attribute Profile (GATT) and Security Manager (SM). +([host](https://github.com/apache/mynewt-nimble/tree/master/nimble/host)) + +- nimble/host/mesh: Contains code for Bluetooth Mesh subsystem. +([mesh](https://github.com/apache/mynewt-nimble/tree/master/nimble/host/mesh)) + +- nimble/transport: Contains code for supported transport protocols between host +and controller. This includes UART, emSPI and RAM (used in combined build when +host and controller run on same CPU) +([transport](https://github.com/apache/mynewt-nimble/tree/master/nimble/drivers)) + +- porting: Contains implementation of NimBLE Porting Layer (NPL) for supported +operating systems +([transport](https://github.com/apache/mynewt-nimble/tree/master/porting)) + +- ext: Contains external libraries used by NimBLE. Those are used if not +provided by OS +([ext](https://github.com/apache/mynewt-nimble/tree/master/ext)) + +- kernel: Contains the core of the RTOS ([kernel/os](https://github.com/apache/mynewt-core/tree/master/kernel/os)) + +## Sample Applications + +There are also some sample applications that show how to Apache Mynewt NimBLE +stack. These sample applications are located in the `apps/` directory of +Apache Mynewt [repo](https://github.com/apache/mynewt-core). Some examples: + +* [blecent](https://github.com/apache/mynewt-core/tree/master/apps/blecent): +A basic central device with no user interface. Thisa pplication scans for +a peripheral that supports the alert notification service (ANS). Upon +discovering such a peripheral, blecent connects and performs a characteristic +read, characteristic write, and notification subscription. +* [blehci](https://github.com/apache/mynewt-core/tree/master/apps/blehci): +Implements a BLE controller-only application. A separate host-only +implementation, such as Linux's BlueZ, can interface with this application via +HCI over UART. +* [bleprph](https://github.com/apache/mynewt-core/tree/master/apps/bleprph): An + implementation of a minimal BLE peripheral. +* [btshell](https://github.com/apache/mynewt-core/tree/master/apps/btshell): A + shell-like application allowing to configure and use most og NimBLE + functionality from command line. +* [bleuart](https://github.com/apache/mynewt-core/tree/master/apps/bleuart): +Implements a simple BLE peripheral that supports the Nordic +UART / Serial Port Emulation service +(https://developer.nordicsemi.com/nRF5_SDK/nRF51_SDK_v8.x.x/doc/8.0.0/s110/html/a00072.html). +* [test](https://github.com/apache/mynewt-core/tree/master/apps/test): Test + project which can be compiled either with the simulator, or on a per-architecture basis. + Test will run all the package's unit tests. + +# Getting Help + +If you are having trouble using or contributing to Apache Mynewt NimBLE, or just +want to talk to a human about what you're working on, you can contact us via the +[developers mailing list](mailto:dev@mynewt.apache.org). + +Although not a formal channel, you can also find a number of core developers +on the #mynewt channel on Freenode IRC or #general channel on [Mynewt Slack](https://join.slack.com/mynewt/shared_invite/MTkwMTg1ODM1NTg5LTE0OTYxNzQ4NzQtZTU1YmNhYjhkMg) + +Also, be sure to checkout the [Frequently Asked Questions](https://mynewt.apache.org/faq/answers) +for some help troubleshooting first. + +# Contributing + +Anybody who works with Apache Mynewt can be a contributing member of the +community that develops and deploys it. The process of releasing an operating +system for microcontrollers is never done: and we welcome your contributions +to that effort. + +More information can be found at the Community section of the Apache Mynewt +website, located [here](https://mynewt.apache.org/community). + +## Pull Requests + +Apache Mynewt welcomes pull request via Github. Discussions are done on Github, +but depending on the topic, can also be relayed to the official Apache Mynewt +developer mailing list dev@mynewt.apache.org. + +If you are suggesting a new feature, please email the developer list directly, +with a description of the feature you are planning to work on. + +## Filing Bugs + +Bugs can be filed on the +[Apache Mynewt NimBLE Issues](https://github.com/apache/mynewt-nimble/issues). +Please label the issue as a "Bug". + +Where possible, please include a self-contained reproduction case! + +## Feature Requests + +Feature requests should also be filed on the +[Apache Mynewt NimBLE Bug Tracker](https://github.com/apache/mynewt-nimble/issues). +Please label the issue as a "Feature" or "Enhancement" depending on the scope. + +## Writing Tests + +We love getting newt tests! Apache Mynewt is a huge undertaking, and improving +code coverage is a win for every Apache Mynewt user. + + + +# License + +The code in this repository is all under either the Apache 2 license, or a +license compatible with the Apache 2 license. See the LICENSE file for more +information. diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md new file mode 100644 index 000000000..a250ae182 --- /dev/null +++ b/RELEASE_NOTES.md @@ -0,0 +1,2 @@ +# RELEASE NOTES +