Introduced in 9c23b8e5 and 4f87a62f. To get higher speed, menuconfig
options are added to put ISR and other functions into the IRAM. The
interrupt flag ESP_INTR_FLAG_IRAM is also mistakenly set when the ISR is
put into the IRAM. However callbacks, which are wrote by the user, are
called in the master and slave ISR. The user may not be aware of that
these callbacks are not disabled during flash operations. Any cache miss
during flash operation will cause panic.
Essentially IRAM functions and intrrupt flag ESP_INTR_FLAG_IRAM are
different, the latter means not disabling the ISR during flash
operations. New bus_config flag intr_flags is offered to help set the
interrupt attribute, including priority level, SHARED, IRAM (not
disabled during flash operations). It introduced a small BREAK to
IDFv3.1 (but the same as IDFv3.0) that the user has to manually set IRAM
flag now (therefore he's aware of the IRAM thing) to void the ISR being
disabled during flash operations.
Uninstaller is still unsigned, as currently building and signing in 'wine'
and running Linux osslsigncode inside Inno Setup inside wine is awkward.
Closes https://github.com/espressif/esp-idf/issues/1909
TW20810
This example adds functionality to support basic communication in RS485 networks using Modbus protocol.
This example uses FreeModbus stack and regular UART driver API to communicate in RS485 half duplex mode.
Added initial support of modbus controller pure C api to access device parameters over Modbus transport.
Move freemodbus stack and port files into components folder
Move the modbus_controller interface into components idf folder
Source files updated after review.
Add modbus interface documentation docs/en/api-reference/protocols/modbus.rst
porttimer.c: fix bug with timer1 selected in the Kconfig
Add support of cmake system (added cmake files)
Closes https://github.com/espressif/esp-idf/issues/858
If CONFIG_FREERTOS_LEGACY_HOOKS is kept enabled then defining
idle/tick hooks will be applications responsibility as was the
case earlier.
Signed-off-by: Mahavir Jain <mahavir@espressif.com>
This commit adds an option to enclose all FreeRTOS task functions within a
wrapper function. In the case that a task function returns, the wrapper function
will log an error and abort the application immediately.
Closes#2269Closes#2300
Changes:
KConfig: The option CONFIG_ESP32_RTCDATA_IN_FAST_MEM is added in Kconfig file for esp32 component.
esp32.common.ld: added support of RTC_DATA_ATTR, RTC_RODATA_ATTR data placement into appropriate segment according to Kconfig option.
esp32.ld: linker script is modified to set alias for memory segment selected by Kconfig option to place data. The segments for force placement are added for RTC_FAST_ATTR, RTC_SLOW_ATTR attributes.
esp_attr.h: added new attributes RTC_FAST_ATTR, RTC_SLOW_ATTR for force placement into fest/slow memory.
test_rtc_fast.c: Added unit test cases to check data placement into appropriate memory segment.
Updated documentation for RTC_DATA_ATTR, RTC_FAST_ATTR, RTC_SLOW_ATTR in deep_sleep_stub.rst file.
TW#18001
Closes https://github.com/espressif/esp-idf/issues/1553
added docs and tests for mqtt library, small fixes (removed warnings, option for custom outbox, websocket bug fixed for longer transports). refactored to use common tcp_transport component, support for CMake build system.
Closes#2108
Using 'sudo pip install' can cause a lot of problems because usually
there are a couple of Python interpreters installed. This fix encourages
developers to use `pip install --user` instead which is safer.
On some systems pip and setuptools are no longer installed as
dependencies of the python packages. This commit adds the requirement
for these packages.
The following commit rewrites the ESP-MESH docs. This commit includes
new diagrams and a structure approach to the mesh docs. Some mesh api references
have also been modified.
This commit does the following
- Add power management lock to CAN driver so that APB frequency does not change
whilst CAN driver is in use
- Fix incorrect flag in can_transmit()
- Refactor can_driver_install() and can_driver_uninstall() so that critical sections
are shorter
- Fix CAN gpio configuration bug on RX pin. Closes#2302
- Add docs about multiple ID configuration and fix example links
Guarantees that a component's project_include.cmake will be called after its dependent components'
project_include.cmake. Because of cycles in the dependency graph, this is less useful than you'd
think but it gives a strong guarantee for any component which is not part of a cycle.
Also applies deterministic ordering (ordering is initialised as COMPONENT_REQUIRES_COMMON then all
COMPONENTS in alphabetical order, but then the sorting by dependencies is applied.)
Eclipse was unable to resolve the std::mutex type eventhough the mutex header file was succesfully included. By adding this modification, the issues was resolved.
Fixes mismatches where default Python interpreter may not match the most recently
installed sphinx-build wrapper script (if sphinx 2 & 3 both installed, pip will
clobber any previous copy of /bin/sphinx-build when it installs the new one.)
Hardware implements conditions LE, LT, GE, and conditions EQ and GT
are implemented in the assembler by emitting two JUMPS instructions
with other conditions.
The argument to ulp_run should be expressed in 32-bit words. Both the
address of ulp_entry and RTC_SLOW_MEM already are uint32_t*, so their
difference is the difference in addresses divided by sizeof(uint32_t).
Therefore the extra division by sizeof(uint32_t) is not needed.
* "git clone" command and a small version header are generated
depending on git properties.
* Add Versions page with details about each version
* Make it clear using master branch is living on the "bleeding
edge"
Based on report on forum here:
https://esp32.com/viewtopic.php?f=13&t=6382&p=27514
Previous versions were much more relaxed about what could be in the partition
table, erroring out avoids unexpected changes on upgrade like different
partition offsets.
Add a command `make erase_ota` - erases otadata if it there is in the
partition table otherwise error 'Partition table does not have ota_data partition'.
Closes https://github.com/espressif/esp-idf/issues/1821
1. Move channel to the first row of the table.
2. Remove the condition of HT20/HT40 for they are determined by
secondary channel.
3. Clean up the CSI table.
The WiFi station connect sequence diagram does not have any "successful" ending.
It looks like a copy-paste error, because there are two consequent `SYSTEM_EVENT_STA_DISCONNECTED` events firing with nothing happening in between.
I think the original meaning was that the last event should be `SYSTEM_EVENT_STA_CONNECTED` to signify that if all goes well, that is the event that will be fired.
Merges https://github.com/espressif/esp-idf/pull/2065
Since 94250e42a0, UART output is suspended when entering sleep mode
(deep or light sleep). This makes sense for light sleep, where sleep
normally takes small amount of time, and flushing the UART would add
a lot of latency. But this breaks existing behaviour for deep sleep,
where UART output was previously sent out before entering sleep mode.
Closes https://github.com/espressif/esp-idf/issues/2145
An existing UART driver does not support RS485 half duplex mode.
This task adds this functionality to ESP_IDF UART driver.
driver/uart.c/h: updated to add support of RS485 half duplex mode
examples/peripherals/uart_echo_rs485/main/rs485_example.c: added test example
components/driver/test/test_uart.c: added test of RS485 half duplex mode
docs/en/api-reference/peripherals/uart.rst: updated documentation
test_uart.c: suppress GCC warnings about discarded const qualifiers
uart.rst: remove sphinx warning - "Duplicate explicit target name"
simple change in uart.h file
update (test_uart.c) after rebase from master
update uart.rst, uart.c, rs485_example.c
Update example description in file Readme.md
update uart.c/h, uart.rst, test_uart.c according to review results
update uart.h (uart_set_rx_timeout() description
test_uart.c remove ignore tag
uart.c/h: fix param errors
test_uart.c: Remove GCC warning supress
uart.rst: fix the notes
rs485_example.c: fix output
The tests are completed using RS485 adapters hardware connected to two ESP32 WROVER KITs.
TW#13812
Closes https://github.com/espressif/esp-idf/pull/667
Closes https://github.com/espressif/esp-idf/pull/1006
An existing UART driver does not support RS485 half duplex mode.
This task adds this functionality to ESP_IDF UART driver.
driver/uart.c/h: updated to add support of RS485 half duplex mode
examples/peripherals/uart_echo_rs485/main/rs485_example.c: added test example
components/driver/test/test_uart.c: added test of RS485 half duplex mode
docs/en/api-reference/peripherals/uart.rst: updated documentation
test_uart.c: suppress GCC warnings about discarded const qualifiers
uart.rst: remove sphinx warning - "Duplicate explicit target name"
simple change in uart.h file
update (test_uart.c) after rebase from master
update uart.rst, uart.c, rs485_example.c
Update example description in file Readme.md
update uart.c/h, uart.rst, test_uart.c according to review results
The tests are completed using RS485 adapters hardware connected to two ESP32 WROVER KITs.
TW#13812
Closes https://github.com/espressif/esp-idf/pull/667
Closes https://github.com/espressif/esp-idf/pull/1006
This change allows readonly FATFS to be mounted without wear levelling
support. This will provide the customers a simple way to mount FATFS images
generated on host and flashed onto the chip during factory provisioning.
Since NVS encryption is not supported yet and NVS entry size is limited,
the change will provide an easy alternative for securing the provisioning data
by just marking FATFS parition as encrypted.
The old command caused was incorrect (x is “examine”, not “execute”)
and caused GDB register update only by chance. This replaces it with
“flushregs” command which purpose is exactly that — force GDB to
fetch registers from the remote.
These versions of conf/mconf are forked from the upstream, and the CMake system allows mconf-idf to
be installed externally on the path. So the best option is to rename.
Includes changes to Windows installer for v1.1
Don't show the "Python 2 interpreter" option in menuconfig when using CMake.
This is a stop-gap until we support Python 2 & 3 together in ESP-IDF (soon).
Closes https://github.com/espressif/esp-idf/issues/1924
Added feature:
- reset firmware to Factory app.(by long pressing of the button)
- boot Test app. (by long pressing of the button)
- Added feature erase data partitions from factory reset.
TW10281
TW10280
This includes changing the picture of JTAG jumper block by removing the jumper on S_TDI. It has been reported by a number of users that removing this jumper fixes random communication issues observed in OpenOCD.
Add error handling for http client
set ssid password correct with Example_WIFI test, and clear password before free
Fixed the CI failure due to HTTP errror names
This fixes multiple bugs with ring buffers and re-factors the code. The public
API has not changed, however the underlying implementation have various private
functions have been changed. The following behavioral changes have been made
- Size of ring buffers for No-Split/Allow-Split buffers will not be rounded
up to the nearest 32-bit aligned size. This was done to simplify the
implementation
- Item size for No-Split/Allow-Split buffers will also be rounded up to the
nearest 32-bit aligned size.
The following bugs have been fixed
- In copyItemToRingbufAllowSplit(), when copying an item where the aligned
size is smaller than the remaining length, the function does not consider
the case where the true size of the item is less than 4 bytes.
- The copy functions will automatically wrap around the write pointers when
the remaining length of the buffer is not large enough to fit a header, but
does not consider if wrapping around will cause an overlap with the read
pointer. This will make a full buffer be mistaken for an empty buffer
closes#1711
- xRingbufferSend() can get stuck in a infinite loop when the size of the
free memory is larger than the needed_size, but too small to fit in the ring
buffer due to alignment and extra overhead of wrapping around.
closes#1846
- Fixed documentation with ring buffer queue set API
- Adding and removing from queue set does not consider the case where the
read/write semaphores actually hold a value.
The following functions have been deprecated
- xRingbufferIsNextItemWrapped() due to lack of thread safety
- xRingbufferAddToQueueSetWrite() and xRingbufferRemoveFromQueueSetWrite()
as adding the queue sets only work under receive operations.
The following functions have been added
- xRingbufferReceiveSplit() and xRingbufferReceiveSplitFromISR() as a thread
safe way to receive from allow-split buffers
- vRingbufferGetInfo()
Documentation for ring buffers has also been added.
Added .rtc_noinit and .noinit section definitions into linker file /esp32/ld/esp32.common.ld.
The macro __NOINIT_ATTR, RTC_NOINIT_ATTR declared in esp32/esp_attr.h file.
Added unit test file to test added behavior for noinit variables and its attributes.
Added documentation changes for new added attributes.
Make some corrections after code review:
The linker file has been corrected to place noinit section before bss_start to make it safer.
Documentation file has been modified to clarify reset behavior of allocated data .
Corrected typos in test_noinit.c and removed assertion of noinit variable to avoid possible issues with ROM boot loader memory allocation.
The linker file has been corrected to place noinit section before bss_start to make it safer.
Documentation file has been modified to clarify reset behavior of allocated data .
Corrected typos in test_noinit.c and removed assertion of noinit variable to avoid possible issues with ROM boot loader memory allocation.
Update test_noinit.c file to address RTCWDT_RTC_RESET reset reason instead of POWERON_RESET.
Test optimized to pass automated unit testing.
esp32: Add .noinit and .rtc_noinit sections to the linker script
Update of general-notes.rst documentation to fomat examples as code and attributes as identifiers.
Test test_noinit.c corrected to pass automated testing (support ofTEST_CASE_MULTIPLE_STAGES())
https://ezredmine.espressif.cn:8765/issues/15878
1. add the L1 include path with a prefix, such like osi/list.h, stack/a2d_api.h and etc.
2. modify component, only bluedroid/api/include/api is export to another component and application,
other include path just for bluedroid used
3. put bluedroid/include into common/include/common, so the root directory of bluedroid have no include path.
4. modify doxygen to use esp_bt.h and redirect to
component/bt/bluedroid/api/include/api/
fix compile
Ideally suited for generating a binary externally, containing key-value pairs specific
to device manufacturers. Utility allows creation of a binary, compatible
with NVS structure, which can be separately flashed onto a new
partition. This helps device manufacturers set different values for
different devices, e.g. serial numbers, but using a single firmaware
image.
Need to make the bootloader modular so that users can redefine its functional part.
- refactoring and moving functions to the bootloader_support component
- Changed function to `void` bootloader_utility_load_image(...);
TW19596
- Split SDMMC page into pages about SDMMC/SDSPI hosts and a page about
the protocol layer.
- Use autogenerated API reference instead of manually generated one.
- Add information about SDIO APIs.
The expected usage is:
esp_pthread_set_cfg(cfg);
pthread_create()
If the inherit flag is set, then all subsequent threads forked by this
thread will also inherit this configuration. This avoids having to
change/prefix this for each and every pthread_create() call.
The files updated according to code review discussions.
In the sleep_modes.c removed immidiate disable of ULP mode and leave just trigger deactivation.
The esp_sleep.h is updated to have the same defines for source as esp_sleep_wakeup_cause_t.
Updated documentation in sleep_modes.rst file to include cross references and address esp_sleep_wakeup_cause_t type.
Some minor changes in test_sleep.c unit test.
(TW#18952)
Closes https://github.com/espressif/esp-idf/issues/1677
The files updated according to code review discussions.
In the sleep_modes.c removed immidiate disable of ULP mode and leave just trigger deactivation.
The esp_sleep.h is updated to have the same defines for source as esp_sleep_wakeup_cause_t.
Updated documentation in sleep_modes.rst file to include cross references.
Some minor changes in test_sleep.c unit test.
(TW#18952)
Closes https://github.com/espressif/esp-idf/issues/1677
Added function esp_sleep_disable_wakeup_source() to deactivate wakeup trigger for selected source.
Updated documentation for this function in sleep_modes.rst file.
Updated unit test to check this functionality for light sleep.
The test_sleep.c unit test is updated to add reliability for unit testing.
(TW#18952)
Closes https://github.com/espressif/esp-idf/issues/1677
The timer wakeup function once activated cannot be disabled later using existing api. If user wants to use different wakeup sources after first sleep but it does not work. This change disables timer wakeup trigger in configuration that will be set into appropriate RTC registers in esp_light_sleep_start() function.
Added function esp_sleep_disable_wakeup_source() to deactivate wakeup trigger for selected source.
Updated documentation for this function in sleep_modes.rst file to pass make html.
Updated unit test to check this functionality for light sleep.
The test_sleep.c unit test is updated to add reliability for auto unit testing.
(TW#18952)
Closes https://github.com/espressif/esp-idf/issues/1677
On each documentation build (‘make html’), doxygen regenerates XML
files. In addition to that, gen-dxd.py regenerates API reference
files under _build/inc/. This results in Sphinx flagging about half
of the input files as modified, and incremental builds taking long
time.
With this change, XML files generated by Doxygen are copied into
docs/xml_in directory only when they are changed. Breathe is pointed
to docs/xml_in directory instead of docs/xml. In addition to that,
gen-dxd.py is modified to only write to the output file when contents
change.
Overall, incremental build time (with no source files changed) is
reduced from ~7 minutes to ~8 seconds (on a particular OS X
computer).
Due to the way Breathe includes Doxygen XML files, there is still
going to be a massive rebuild every time functions, enums, macros,
structures are added or removed from the header files scanned
by Doxygen, but at least individual .rst files can be edited
at a much faster pace.
This commit removes the lookup table mode due to inferior performance when compared
to linear mode under attenuation 0, 1 and 2. However small portions of the lookup table
are kept for the higher voltages of atten 3 (above ADC reading 2880). That voltage range
in atten 3 has non linear characteristics making the LUT performan better than linear mode.
Chapter Flash from Eclipse: Changed "Select Make Targets -> ..." to "Select Build Targets -> ..." to match the Eclipse wording. Same with "Project -> Make Target" replace Make by build to match the Eclipse wording.
This commit updates the esp_adc_cal ocmponent to support new calibration methods
which utilize calibratoin values stored in eFuse. This commit includes LUT mode
current unit-test-app don't support test components need to communicate
with each other (like GPIO, SPI ...). Now we add multiple devices mode
to unit test app, support writing and running test with multiple DUTs.
please refer to `docs/api-guides/unit-tests.rst` for detail.
- Use `code` tags instead of a mix of `<pre></pre>` and
`@verbatim .. @endverbatim`
- Remove manually added function prototypes from comment blocks
- Remove of grouping (`\defgroup`) — some extra work is needed
to make groups compatible with the way we auto-generate API
reference from Doxygen XML files. It's pretty easy to add the
grouping directives back if/when we implement support for
Doxygen groups in the later stages of documentation build
process.
- Hide private APIs under `@cond .. @endcond`
- Convert some comments into Doxygen-compatible ones
- Fix various documentation issues: missing documentation for
some parameters, mismatch between parameter names in comment
block and in function prototype.
- Add doxygen comments for functions which didn't have them
(thread local storage).
- Add [out] param tags where necessary
- Redefine `xTaskCreate` and `xTaskCreateStatic` as inline
functions instead of macros.
This commit backports vTaskDelete() behavior from FreeRTOS v9.0.0 which
allows for the immediate freeing of task memory if the task being deleted
is not currently running and not pinned to the other core. This commit also
fixes a bug in prvCheckTasksWaitingTermination which prevented the
Idle Task from cleaning up all tasks awaiting deletion. Each iteration of the Idle
Task should traverse the xTasksWaitingTermination list and clean up all tasks
not pinned to the other core. The previous implementation would cause
prvCheckTasksWaitingTermination to return when encountering a task
pinned to the other core whilst traversing the xTasksWaitingTermination list.
The test case for vTaskDelete() has been updated to test for the bugfix and
backported deletion behavior.
This commit backports the following features from FreeRTOS v9.0.0
- uxSemaphoreGetCount()
- vTimerSetTimerId(), xTimerGetPeriod(), xTimerGetExpiryTime()
- xTimerCreateStatic()
- xEventGroupCreateStatic()
- uxSemaphoreGetCount()
Functions backported previously
- xTaskCreateStatic()
- xQueueCreateStatic()
- xSemaphoreCreateBinaryStatic(), xSemaphoreCreateCountingStatic()
- xSemaphoreCreateMutexStatic(), xSemaphoreCreateRecursiveMutexStatic()
- pcQueueGetName()
- vTaskSetThreadLocalStoragePointer()
- pvTaskGetThreadLocalStoragePointer()
Unit tests were also written for the functions above (except for pcQueueGetName
which is tested in a separate Queue Registry MR). The original tlsp and del cb test case
was deleted and integrated into the test cases of this MR.
This commit reverts the revert on the new task watchdog API. It also
fixes the following bug which caused the reversion.
- sdkconfig TASK_WDT_TIMEOUT_S has been reverted from the unit of ms back to the
unit of seconds. Fixes bug where projects using the new API without rebuilding sdkconfig
would cause the old default value of 5 to be interpreted in ms.
This commit also adds the following features to the task watchdog
- Updated idle hook registration to be compatible with dual core hooks
- Updated dual core hooks to support deregistration for cpu
- Legacy mode has been removed and esp_task_wdt_feed() is now replaced by
esp_task_wdt_reset(). esp_task_wdt_feed() is deprecated
- Idle hooks to reset are now registered/deregistered when the idle tasks are
added/deleted from the Task Watchdog instead of at Task Watchdog init/deinit
- Updated example
append adc support and api
- esp_err_t adc2_config_width(adc_bits_width_t width_bit);
- esp_err_t adc2_config_channel_atten(adc2_channel_t channel, adc_atten_t atten);
- int adc2_get_voltage(adc2_channel_t channel);
Previously if multiple tasks had been added to xPendingReadyList for the CPU, only the first one was resumed.
Includes a test case for resuming multiple (pending) tasks on xTaskResumeAll().
Document the limitation that while scheduler is suspended on one CPU, it can't wake tasks on either CPU.
for me it was necessary to add the key manually to the key ring. Otherwise I could not have installed the packages
Merges https://github.com/espressif/esp-idf/pull/1029
(Amended to remove reference to exact key, references AUR links instead.)
using apll_param to setup APLL
new apll calculation method, much faster
validate freq calculation
Ensure that the i2s frequency is greater than the hardware limit
Add description of how to calculate apll clock, support apll for other 16-bits audio, check rev0 chip
correct space
Legacy API of task watchdog used the same function esp_task_wdt_feed() to add
and feed a task. This caused issues of implicitly adding a task to the wdt list
if the function was used in shared code.
The new API introduces init, adding, feeding, deleting, deinit functions. Tasks
must now be explicitly added to the task watchdog using their handles. Deletion
must also be explicit using task handles. This resolves the issue of implicit
task additions to the task watchdog due to shared code calling
esp_task_wdt_feed().
Task watchdog is now fully configurable at runtime by calling the init and
deinit functions.
Also added functions to get the handles of idle tasks of the other core. This
helps when adding idle tasks to the watchdog at run time.
Configuring the task watchdog using menu config is still available, however
menu config will only result in calling the init and add functions for idle
tasks shortly after the scheduler starts.
Menu config also allows for using legacy behavior, however the legacy behavior
willcall the new API functions but with slight variations to make them legacy
compatible.
Documentation and example have also been updated
gcov_rtio.c headers updated to prevent error of freertos header files being
included in the wrong order.
Resolves issue TW#13265
Added documentation about the ESP-IDF changes to FreeRTOS.
The documentation covers changes to the following FreeRTOS aspects.
- Task Creation
- Affects on scheduling (Task skipping, scheduler suspension, tick synchronicity)
- Critical sections and disabling interrupts
- Thread Local Storage Pointers and deletion callbacks
- Configuring ESP-IDF FreeRTOS
Previously suggested parser command pattern:
xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)
was incorrect for compilation of c++ files, as it is expanded by Eclipse into or between:
xtensa-esp32-elf-(g?cc)
([gc]\+\+)
(clang)
Additional grouping around existing pattern solves that issue, and helps Eclipse to correctly find ESP-IDF includes.
Merges https://github.com/espressif/esp-idf/pull/1005
New multi_heap code has proven effective at aborting when buffer overruns occur,
but it's currently hard to debug the stack traces from these failures.
1. Support built-in ADC for I2S.
2. Modify code of ADC, made no change to the original APIs.
3. Add APIs in I2S:
esp_err_t i2s_set_adc_mode(adc_unit_t adc_unit, adc1_channel_t adc_channel);
4. Add I2S ADC/DAC example code.
5. add old-fashion definition to make it more compatible
6. replase spi_flash_ APIs with esp_partition_ APIs
7. add example of generating audio table from wav
8. change example sound
* Fixes issue in !1250 when IDF_PATH changes on build runner
* Allows checking document warnings before CI run
* Will be robust to line number changes in document files
ESPNOW is a kind of WiFi communication bettween WiFi devices, no
matter they are connected to each other or not. Once two WiFi
devices are paired, they can send data to or receive data from
each other. The data is transmitted in action frame which can
be encrypted with CCMP method. ESPNOW also support mutilcast frame
transmitting.
Since 9a8c0392, XTAL frequency is set to 40MHz by default, and users
of 26MHz boards need to select 26MHz manually. Most users are not aware
of this change, and existing getting started guides do not mention that
XTAL frequency needs to be set for some boards. So users are left with
garbage output from UART without any clue what to check.
This change adds a warning in case specific XTAL frequency was set, and
it does not match automatically detected one. This should help users
fix the issue.
Added component containg API that is able to correct raw ADC readings
into a voltage in mV. Also provided a helper function that combines
the process of getting the raw ADC1 reading then converting it to a
voltage in mV. In doing so, the adc1_get_voltage() function of the ADC
driver has been deprecated. Instead there is now adc1_get_raw to obtain
the raw ADC1 reading, and adc1_to_voltage() that gets the raw reading
and converts all in one function. Functions using the deprecated
adc1_get_voltage() have also been updated to use adc1_get_raw().
Conversion is based on ADC characteristics. The characteristics are based
on the ADC's v_ref, herefore the appropriate structure and functions have
been provided to obtain the ADC characteristics.
The existing ADC driver has also been modified by adding a function to
route the internal ADC reference voltage to a GPIO allowing users to measure
it manually.
Relevant documentation has also been updated
1. add sens_struct.h
2. add definition of RTCCNTL and RTCIO
3. modify touch pad examples
4. update example code.
5. add comments add option in menuconfig
6. fix issue that pad index 8 and 9 are mismatched
7. add touch_pad_read_filtered() api to get value filtered by iir filter
8. modify touch pad isr func
9. Make the items in perihperal.ld in the sequence of address
10. delete Kconfig for touch pad
11. add touchpad filter APIs to adjust the filter
12. add touch_pad into index.rst
13. add touch_pad in Doxyfile
14. add touch_pad.rst
This adds a simple script which parses Kconfig files using Kconfiglib
and emits ReST document with the list of all options. For each option
a link target is generated, to make it possible to link to any Kconfig
option from the rest of the documentation.
Since Kconfiglib is not on PyPI, the latest version (45f87b9d) is
bundled into the docs directory.
SD SPI mode driver
This MR adds functionality to support SD cards connected via SPI interface.
Additionally, two bugs are fixed:
- Definition of `SPI_TRANS_MODE_DIOQIO_ADDR` in spi_master driver
- SD card probing frequency was 4000kHz instead of 400kHz as required by the standard
See merge request !727
For config-only components, component.mk should now contain "COMPONENT_CONFIG_ONLY := 1"
Also refactored some of the generation of linker paths, library list. This required cleaning up the way the bootloader
project works, it's now mostly independent from the parent.
Each COMPONENT_DIRS directory can now either be a component directory, or a parent directory containing component
subdirectories.
When searching for components, skip any directory which doesn't have component.mk, Kconfig.projbuild, or
Makefile.projbuild in it. This helps with debugging, list-components output, etc.
Implements support for system level traces compatible with SEGGER
SystemView tool on top of ESP32 application tracing module.
That kind of traces can help to analyse program's behaviour.
SystemView can show timeline of tasks/ISRs execution, context switches,
statistics related to the CPUs' load distribution etc.
Also this commit adds useful feature to ESP32 application tracing module:
- Trace data buffering is implemented to handle temporary peaks of events load
1. Name change from chopper to carrier, block diagram update, minor changes to example codes
2. mcpwm_reg.h changed, brought uniformity in comments, worked on suggestions, duty to accept float. Some name changes!
3. Minor readme changes and Indetation
4. Minor change: move mcpwm_reg.h and mcpwm_struct.h to new path
5. Minor change: addition of BLDC example code and Readme
6. Name changed from epwm to mcpwm
7. Improve the reg name in mcpwm_struct.h
8. Name change chopper>carrier, deadband>deadtime
CI: save download config in CI build jobs:
IDF built app download config may change with some modification.
save the download configs for built APP in build stage.
then we can use the correct download config in test stage.
See merge request !676
Split common SPI stuff out of master driver; add slave driver; add workaround for DMA issue.
This merge req mainly adds a slave device. In order to do this, the original master driver is refactored into common code shared by master and slave modes, and a slave driver is added.
The other things added are:
- Added a workaround for a 'feature' of the ESP32 silicon that can lock up the receive DMA channel in some situations. This can only be fixed by resetting *both* DMA channels. The workaround implemented makes sure that the reset only happens when both channels are idle
- Got rid of the automatic choice between register- and DMA-based transfers. The master (and slave) code will now always go for a DMA transfer if a DMA channel is given, and always go for register-based transfers if no DMA channel is given.
- Add in a bunch of fixes for outstanding Github issues.
See merge request !659
wear levelling
This MR adds wear levelling component. It presents an interface similar to the interface of spi_flash and esp_partition. Inside, it stores data inside a partition to in a way that reduces worst case number of erase cycles for any given sector.
Also included are APIs similar to the ones provided for SDMMC to mount FAT filesystem on top of the wear levelling partition. A simple example shows how this API can be used.
Ref TW10338.
See merge request !567
Feature/btdm avrc
The source branch "feature/btdm_avrc" includes classic Bluetooth profiles A2DP(sink role) and AVRCP(controller role);
Menuconfig options to control whether to enable classic BT is added.
See merge request !591
1) fixed SPI_read_status: added check for flash busy flag in matrix mode
2) fixed SPI_page_program: enable write before writing data to SPI FIFO
3) SPI flash ROM funcs replacement is controlled via menuconfig option
Windows setup improvements
* Tweak Makefile to significantly reduce startup time on Windows (also reduced on other platforms, but less obvious.)
* Revise windows setup installation script to fix various issues, use latest toolchain.
* Tweak Windows config docs
See merge request !597
doc: add dev module and boards by Espressif
Overview, picture, link to schematic, ref. design, etc. for the following development module and boards:
- ESP-WROOM-32
- ESP32 Core Board V2 / ESP32 DevKitC
- ESP32 Demo Board V2
- ESP32 WROVER KIT V1 / ESP32 DevKitJ V1
- ESP32 WROVER KIT V2
See merge request !560
Error handling in NVS initialization
Previously nvs_flash_init worked under an assumption that there should always be at least one free page available. This is true during normal operation, but in some cases (such as when changing application partition table from a non-OTA to an OTA one), NVS partition may get truncated, which will cause empty pages to be lost.
This MR adds error checks for this condition, and updates code which calls `nvs_flash_init` to check for the return code.
For most examples, a simple `ESP_ERROR_CHECK` is added around `nvs_flash_init`. For NVS examples and the OTA example, more robust error handling is added.
This change also removes nvs_flash_init calls from examples which don't use NVS.
See merge request !582
* "make monitor" not passed the configured baud rate
Closes#436https://github.com/espressif/esp-idf/issues/436
* Pass toolchain prefix from sdkconfig into monitor tool
* Allow setting EOL in idf_monitor.py, use CRLF by default
* Detect if /dev/tty.X is used on macOS, warn and replace with /dev/cu.X
* If a build fails or gdb exits, ignore Ctrl-T (allowing Ctrl-T Ctrl-A/F to be same key sequence everywhere)
* Add a note about winpty on Windows
Ref 02fdf8271d (commitcomment-21369196)
Expand 'make monitor' support
New 'make monitor' idf_monitor tool for better monitor output. Running 'make monitor' will now:
* Automatically look up code addresses via addr2line and print function, source file, line number in terminal.
* Can reset the ESP32 by typing Ctrl-T Ctrl-R.
* Can run "make flash" by typing Ctrl-T Ctrl-F.
* Can run "make app-flash" by typing Ctrl-T Ctrl-A.
* If gdb stub starts, monitor will automatically run gdb and connect. When gdb exits, ESP32 resets and monitor resumes.
* Exit is still Ctrl-[
Have some more features I'd like to add (log output to file, crash dump support) but I think this is at the point of being useful.
See merge request !565
This change adds a check for the free page count to nvs_flash_init.
Under normal operation, NVS keeps at least one free page available,
except for transient states such as freeing up new page. Due to external
factors (such as NVS partition size reduction) this free page could be
lost, making NVS operation impossible. Previously this would cause an
error when performing any nvs_set operation or opening a new namespace.
With this change, an error is returned from nvs_flash_init to indicate
that NVS partition is in such a state.
add wakeup from touch sensor, and deep sleep example
- add new deep sleep wakeup mode
- change documentation to explain incompatibilities between different wakeup mode, add error checks
- add new ULP instructions necessary for ULP wakeup scenario
- fix issues with I_WR_REG, I_SLEEP, I_END instructions
- add deep sleep example, illustrating the use of timer, gpio, touch, and ULP wakeup triggers
See merge request !461
Not sure which Ubuntu is used in the installation guide but for the latest LTS release 16.04 we need libtool-bin for
compiling crosstool-NG proper
Merges #46https://github.com/espressif/esp-idf/pull/46
FATFS enable support for multiple drives
Current implementation has drive numbers and paths hardcoded to support
only one FATFS drive. Arduino has it's own SPI driver to allow
compatibility and flexibility. With the MR it is possible to have up to
```_VOLUMES``` drives connected (SPI, SDMMC and others) at the same
time and accessed through VFS
See merge request !478
Partition/SPI/OTA docs & OTA new functionality
* Update partition, SPI flash & OTA docs to reflect functionality changes
* Refactor OTA implementation to perform checks mentioned in API doc
* Add new functions to OTA API: esp_ota_get_running_partition() & esp_ota_get_next_update_partition() functions
* Add spi_flash_cache2phys() & spi_flash_phys2cache() functions to support esp_ota_get_running_partition()
See merge request !513
1. indicate adv/scan start complete success or failed
2. controller do limit of adv/scan concurrence, so add some codes to report adv/scan start failed or not.
This change adds esp_deep_sleep_get_wakeup_cause, which returns the
source which has caused wakeup from deep sleep.
Similar to esp_deep_sleep_get_ext1_wakeup_status, a function is added
to check touch pad wakeup status: esp_deep_sleep_get_touchpad_wakeup_status.
This function returns the touch pad which has caused wakeup.
ULP and touch FSMs in ESP32 revisions 0 and 1 do not operate correctly
if RTC_PERIPH power domain is force powered on (ESP_PD_OPTION_ON).
Both ULP and touch still work, but clock frequency of the ULP may be
incorrect and touch values may be off by considerable amount. As such,
when these wakeup modes are used, RTC_PERIPH power domain has to be set
to ESP_PD_OPTION_AUTO (or, in the current implementation,
ESP_PD_OPTION_OFF — though this will change in the future when _OFF will
actually *force* the power domain to be powered off).
Because EXT0 wakeup source requires RTC_PERIPH to be powered ON, mark
ULP and touch wakeup sources as incompatible with EXT0. Workaround for
this is to use EXT1 wakeup source instead, which offers similar or
better functions without having to keep RTC_PERIPH powered on.
1. add new APIs bt controller enable/disab/deinit
2. make bt controller work need to call two APIs of esp_bt_controller_init and enable
3. modify phy init to make mac reset once
Also add steps to disable flash encryption, as some people seem to
accidentally enable it.
Explicitly mark the flash encryption and secure boot as "READ DOCS
FIRST" in menuconfig.
docs: use custom roles to generate GitHub links
This change replaces direct links to GitHub master branch with
auto-generated links using docutils custom roles.
These auto-generated links point to the tree or blob for the git commit
ID (or tag) of the repository. This is needed to ensure that links don’t
become broken when files in master branch are moved around or deleted.
The following roles are introduced:
```
- :idf:`path` - points to directory inside ESP-IDF
- :idf_blob:`path` - points to file inside ESP-IDF
- :idf_raw:`path` - points to raw view of the file inside ESP-IDF
- :component:`path` - points to directory inside ESP-IDF components dir
- :component_blob:`path` - points to file inside ESP-IDF components dir
- :component_raw:`path` - points to raw view of the file inside ESP-IDF
components dir
- :example:`path` - points to directory inside ESP-IDF examples dir
- :example_blob:`path` - points to file inside ESP-IDF examples dir
- :example_raw:`path` - points to raw view of the file inside ESP-IDF
examples dir
```
A check is added to the CI build script, which searches RST files for
presence of hard-coded links (identified by tree/master, blob/master,
or raw/master part of the URL).
This check can be run manually: cd docs && make gh-linkcheck
Additionally, Sphinx linkcheck build type is used to create new CI test,
which check for broken links. This test has to be triggered explicitly,
because including it in normal build process (when the commit is not yet
deployed to Github) will not work. It can be triggered in a regular
fashion using a combination of cron and Curl, similar to stress tests.
See merge request !455
This change replaces direct links to GitHub master branch with
auto-generated links using docutils custom roles.
These auto-generated links point to the tree or blob for the git commit
ID (or tag) of the repository. This is needed to ensure that links don’t
become broken when files in master branch are moved around or deleted.
The following roles are introduced:
- :idf:`path` - points to directory inside ESP-IDF
- :idf_blob:`path` - points to file inside ESP-IDF
- :idf_raw:`path` - points to raw view of the file inside ESP-IDF
- :component:`path` - points to directory inside ESP-IDF components dir
- :component_blob:`path` - points to file inside ESP-IDF components dir
- :component_raw:`path` - points to raw view of the file inside ESP-IDF
components dir
- :example:`path` - points to directory inside ESP-IDF examples dir
- :example_blob:`path` - points to file inside ESP-IDF examples dir
- :example_raw:`path` - points to raw view of the file inside ESP-IDF
examples dir
A check is added to the CI build script, which searches RST files for
presence of hard-coded links (identified by tree/master, blob/master,
or raw/master part of the URL).
This check can be run manually: cd docs && make gh-linkcheck
Additionally, Sphinx linkcheck build type is used to create new CI test,
which check for broken links. This test has to be triggered explicitly,
because including it in normal build process (when the commit is not yet
deployed to Github) will not work. It can be triggered in a regular
fashion using a combination of cron and Curl, similar to stress tests.
Organize examples and API documentation - supplement to !430
This supplement to !430, both intended to replace bulky !421.
1. Fixed broken links
2. Added links to available examples in API documentation, where missing
3. Updated links to point directly to example folder (to show README.md with example description)
4. Added README.md in docs folder info to point reader to ReadTheDocs instead of doc sources, ref. https://github.com/espressif/esp-idf/issues/243
5. Fixed some typo errors / Sphinx warnings
6. Fixed memory leak in example, ref. https://github.com/espressif/esp-idf/issues/209
See merge request !440
Most of the packages mentioned are only needed for building the toolchain using crosstool-NG, not for the normal ESP-IDF environment.
Mention that pyserial needs to be installed (fixes https://github.com/espressif/esp-idf/issues/229).
esp32 core dump to flash
1. menuconfig option to select where to store core dump: flash, uart or disable
2. Saving of core dump to flash
3. Partition table definitions files with core dump partition
4. Python scripts to support core dump generation from GDB command line
See merge request !341
The following issues mentioned during MR!341 review were fixed:
1) Core dump test application description
2) Usage of CONFIG_ESP32_ENABLE_COREDUMP_TO_FLASH and CONFIG_ESP32_ENABLE_COREDUMP_TO_UART
3) FLASH_GUARD_START macro usage is fixed in flash API
4) Core dump module logging facility
5) cache util functions doc updated
6) interactive delay before print core dump to uart
7) core dump partion support in build system
component bt:Added the create attribute table method to the new API
GATT Server service table APIs.
Have already modify the style and other things as @jeroen suggestion in other MR(the MR have been closed)
See merge request !399
update toolchain version, rebuild newlib
- This MR updates the toolchain version used in the ESP-IDF
- Compiler version check and warning is added to project.mk
- Newlib is rebuilt to include wcsftime function
- libstdc++ build uses correct newlib headers (so we won't get undefined reference to `__impure_ptr` anymore)
See merge request !387
ethernet: support flow control
(1) Only fullduplex mode support flow ctrl .
(2) Fix reboot exception which caused by not-reset EMAC hardware (such as DMA) when reset CPU.
See merge request !392
component/bt: bug fix of lack of checking bluetooth stack status inside API functions
Add an API function for checking bluetooth stack status: whether it is uninitialized, initialized or enabled.
The function is intended to be used by users to check the bluetooth stack status, also, it is used inside bluetooth API functions to ensure the stack is in valid state.
See merge request !405
build system: add IDF_VER environment variable and preprocessor define
This adds an `IDF_VER` preprocessor define which is obtained from `git describe`.
Looks like `v1.0-275-g0efaa4f` for non-release version or `v2.0` for a tagged (release) version.
See merge request !403
SDMMC peripheral driver, SD protocol driver, FATFS library, VFS integration
This MR contains:
- SDMMC host peripheral driver
- SD protocol driver in sdmmc component (can be extended to support MMC/eMMC and SPI based hosts)
- ChaN's FATFS library v0.12b
- VFS integration
- FAT access via VFS is thread-safe (unless same file is read/written/unlinked/renamed from different tasks)
- Support for POSIX directory-related functions in VFS (and in vfs_fatfs.c)
- unit test for the above
- Example
- API documentation
Will be done in other MRs:
- Support for spi_flash IO driver for FatFs
- SPI host driver and support for SPI mode commands in sdmmc component
- MMC/eMMC support in sdmmc component
- Support for slightly higher 53/26.6MHz clocks (currently I'm using 20MHz for DS and 40MHz for HS, instead of 25MHz/50MHz per standard), and arbitrary low clocks (e.g. 4MHz).
See merge request !353
Enable bootloader entropy source for RNG
Enables an entropy source when bootloader starts up, which both seeds the RNG for use before WiFi/BT stack is enabled and provides an adequate RNG for secure boot & flash encryption key generation.
A prerequisite was enabling 80MHz operation, so the CPU is now set to 80MHz as soon as second stage bootloader starts running.
See merge request !363
SPI master driver
This merge requests adds an SPI Master driver. This driver is (of course) multithread capable, has device abstraction, has command queueing, DMA support and all other sorts of nice things you'd expect from a SPI driver.
See merge request !332
1. add fading functions.
2. clear up ledc.c and ledc.h
3. update api doc.
4. add ledc example
5. edit ledc.rst and add readme for example code.
6. add s_ prefix for static global values.
7. add mutex for fade functions
8. minor changes according to the comments.
2. update example comments and other minor changes
3. rename API: i2c_cmd_link_create/i2c_cmd_link_delete (+4 squashed commits)
Squashed commits:
[2e0ac3e] 1. coding style: add one space after condition key words.
2. modify i2c.h, use gpio_num_t instead of int, improve comments of return values
3. add i2c index in index.rst
4. add readme for i2c example
[4991d92] update i2c.doc
[88b672e] driver: i2c
1. add mux and spin lock to run in a thread-safe way.
2. modify example code
[4eb15fe] driver: i2c code
1. add i2c master code
2. add i2c slave code
3. add i2c example code
4. add DRAM_ATTR for I2C array
GPIO driver: add per-pin interrupt handlers
1. add ISR handler apis so that users of different layers can hook their own isr handler on different GPIO.
Audio project has different software layers, they need different gpio isr handler for layer instead of processing all GPIO interrupts in one handler.
If this kind of calling a handler from isr is not proper, please kindly point out.
2. add gpio example code.
3. update gpio doc.
See merge request !345
Clarification on documenting examples
Improve documentation of examples with two basic actions:
- include README.md in each example project
- add a link with synopsis in API documentation
This was not clear reading original API documentation template.
See merge request !349
1. add ISR handler apis so that users of different layers can hook their own isr handler on different GPIO.
Audio project has different software layers, they need different gpio isr handler for layer instead of processing all GPIO interrupts in one handler.
If this kind of calling a handler from isr is not proper, please kindly point out.
2. add gpio example code.
3. improve gpio.rst
4. add readme for gpio example
Squashed commits:
[278e50f] update: GPIO
1. coding style, add a space between conditional or loop keyword and an opening paren.
2. modify some return value and doc
3. use printf in example code
Squashed commits:
[efb23bb] minor change of comment
Secure boot: Option for app & partition table signing to happen outside build system
Allows for a remote signing server, private signing key does not need to be on the build system.
See merge request !320
1. add sigma-delta code and example.
2. add gpio output signal in io matrix.
Squashed commits:
[a25e7d4] minor changes for doc
[6a03a1e] minor changes on comments and doc.
[97dd9e4] Add doc.
update index.rst
change example index
1. TW8657, WIFI send the whole packet to smartconfig;
2. modify API annotation of smartconfig and sniffer;
3. export smartconfig APIs to programming guide;
Restore ability to alloc IRAM, and more.
- Fix mem regions so allocating IRAM works again
- Optimize allocator slightly, uses 4 less bytes per malloc now
- Allow querying free heap memory space per memory type
See merge request !301
Flash encryption support
Flash encryption support in build system, tooling
To come in future MR:
* On-device key generation on first boot (for production devices), need to finalise testing of bootloader entropy seeding.
* spi_flash_encrypted_write to support non-32-byte block writes (at least optionally.)
* I think a lot of the bootloader_support component can possibly be rolled into "spiflash" and other components, to use a common API.
See merge request !240
Add dynamic interrupt allocation mechanism
This adds:
- Dynamic allocation of interrupts. Pass it the features of the interrupt you want, it'll set you up with an int.
- Shared interrupts. Enables multiple peripheral drivers to use the same interrupt.
- Marking what interrupts are fully executable from IRAM; if an int isn't marked like that it will get disabled once flash cache gets disabled.
Also:
- Modifies driver to be in line with these changes
See merge request !254
Fail CI build on warnings
This allows developers to add CFLAGS for -Wno-error=XXX while developing, but before code passes the CI build then it must be warning-free.
See merge request !279
Initial support for generation of ULP coprocessor code
This adds basic support for writing ULP coprocessor programs using an assembly-like syntax, with integer labels and branches to labels.
See merge request !261
* App access functions are all flash encryption-aware
* Documentation for flash encryption
* Partition read/write is flash aware
* New encrypted write function
Feature/btdm bluedroid
This branch contain the bluedroid host code.
Currently, Only GAP/GATT SERVER/GATT CLIENT release to users.
Actually, the content of the codes is further more than GAP/GATT and etc.
In this release version, users only need to concern about the APIs which are in "api/include/".
Now, suggestions in comment have been resolved are following:
1. The APIs use callback function. Ivan , Jeroen and me have discussed it. Currently the code will not be changed.
2. The APIs use OPEN/CLOSE. I have ask Ivan, besides bluedroid do this, we will keep the name.
3. Coding style. I have run format.sh to handle the style. And some spell error have been fixed.
4. APIs doxygen. I have clean the warning by doxygen. But bt.rst is still need to be completed.
5. Other comment without resolved face to face that I have to add response in the comment and fix them in the code
6. Fix some incorrect things. See the git log for details.
This 1st version of bluedroid release still have lots of things to do. But it can be done after this merge.
1. Compelete the BLUFI(Bluetooth config wifi connection) documents, security, application protocol and other.
2. Add SPP-LIKE profile.
3. Do more examples codes to cover most of the APIs.
4. Test and fix bug.
Another thing：
1. Do the document of APIs.(xml->bt.rst->html)
(I will do this before merge as Ivan's suggestion)
This is already done. Besides, the union type in doxygen have something error. Ivan will fix it.
See merge request !239
SHA acceleration integrated to mbedTLS incl. TLS sessions
Uses hardware SHA acceleration where available, fails over to software where not available.
Ref TW7112
See merge request !232
SHA hardware allows each of SHA1, SHA256, SHA384&SHA512 to calculate digests
concurrently.
Currently incompatible with AES acceleration due to a hardware reset problem.
Ref TW7111.
Docs: new documentation and warnings cleanup
This change set
- adds a high-level description of application startup flow. Some parts are missing, but hopefully we can use this description as a base to expand on.
- adds a few notes about memory regions and their use in ESP-IDF.
- add SPI flash and partition APIs page
- fixes all Doxygen warnings in header files
- enables build failures on new Doxygen warnings
See merge request !201
Secure boot related fixes
Fix some issues (mostly build system) from the secure boot implementation
Also refactor the way submodule checks are applied to make them more reliable.
See merge request !207
nvs_flash: adjust the nvs_flash start sector number
Modify the nvs flash start sector from 6 to 9 because the partition table bin burn address is modified from 0x4000 to 0x8000
See merge request !215
Required at project level because some components use header files in
other components' submodules, and one component with a
submodule (esptool.py) doesn't have or need a component.mk.
Simplifies examples of embedding a certificate file or a root cert.
This is a much cruder mechanism than the full flash filesystem we want
eventually, but still sometimes useful.
Read the Docs is building documentation referencing to specific releases
on GitHub.
Changing version / release in this script is breaking menu in bottom
left corner
Now version / release should change only for local builds and not for
builds on Read the Docs
This adds initial code style guide. Only section on code formatting is written, other sections to be added later.
Also adds scripts to format code using astyle.
Deep sleep: Any source named rtc_wake_stub* is linked as RTC wake stub code
Also move esp_deepsleep.h documentation out to docs/deep-sleep-stub.rst
See merge request !142
Used by mbedTLS to set MBEDTLS_CONFIG_FILE in all components.
This change sets CFLAGS/etc at the project level and then exports those
variables for components, rather than setting them independently each time
a component Makefile is invoked.
Currently this is mostly a verbatim copy of macOS guide with some obvious changes.
Exact lists of dependencies for Debian and Arch need to be specified.
Also made minor fixes to Windows and macOS guides:
- changed http urls to https
- added --prefix=$PWD to crosstool-NG's configure
- added chmod u+w for the build output directory
In general, except for prerequisites, Linux and macOS guides are virtually identical.
It might make sense to refactor this into single document with prerequisites being
described in separate docs.
