docs: add OpenOCD/JTAG instructions for macOS

diff --git a/docs/api-guides/jtag-debugging/building-openocd-macos.rst b/docs/api-guides/jtag-debugging/building-openocd-macos.rst
index 29fadc08661eb71a1a12ba531cc0c50dde50aebf..349fd882c325994e0bfb2e905a113f5070eae67c 100644 (file)
--- a/docs/api-guides/jtag-debugging/building-openocd-macos.rst
+++ b/docs/api-guides/jtag-debugging/building-openocd-macos.rst
@@ -4,13 +4,47 @@ Building OpenOCD from Sources for MacOS
 
 The following instructions are alternative to downloading binary OpenOCD from Espressif website. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :doc:`setup-openocd-macos`.
 
+.. highlight:: bash
+
+Download Sources of OpenOCD
+===========================
+
+The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
+
+    cd ~/esp
+    git clone –recursive https://github.com/espressif/openocd-esp32.git
+
+The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.
+
+
+Install Dependencies
+====================
+
+Install packages that are required to compile OpenOCD using Homebrew::
+
+       brew install automake libtool libusb wget gcc@4.9
 
 Build OpenOCD
 =============
 
-Refer to build process described in ``README.OSX`` file, that is provided with
-OpenOCD source code in https://github.com/espressif/openocd-esp32 repository.
+Proceed with configuring and building OpenOCD::
+
+    cd ~/esp/openocd-esp32
+    ./bootstrap
+    ./configure
+    make
+
+Optionally you can add ``sudo make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten.
+
+.. note::
+
+    * Should an error occur, resolve it and try again until the command ``make`` works. 
+    * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``.
+    * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. 
+    * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in  ``../openocd-esp32/doc/INSTALL.txt``.
+    * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.OSX``.
 
+Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src/openocd`` directory.
 
 Next Steps
 ==========

diff --git a/docs/api-guides/jtag-debugging/configure-wrover.rst b/docs/api-guides/jtag-debugging/configure-wrover.rst
index 0fb6d5c4731ddae6420e6926c547aa5b98c7f0a4..5737ca1c0e3a6a985963ea87c33583e16c0c4ce7 100644 (file)
--- a/docs/api-guides/jtag-debugging/configure-wrover.rst
+++ b/docs/api-guides/jtag-debugging/configure-wrover.rst
@@ -31,11 +31,13 @@ Configure USB Drivers
 
 Install and configure USB drivers, so OpenOCD is able to communicate with JTAG interface on ESP32 WROVER KIT board as well as with UART interface used to upload application for flash. Follow steps below specific to your operating system.
 
+.. note:: ESP32 WROVER KIT uses an FT2232 adapter. The following instructions can also be used for other FT2232 based JTAG adapters.
+
 
 Windows
 """""""
 
-1.  Using standard USB A / mini USB B cable connect ESP32 WROVER KIT to the computer. Switch the WROVER KIT on.
+1.  Using standard USB A / micro USB B cable connect ESP32 WROVER KIT to the computer. Switch the WROVER KIT on.
 
 2.  Wait until USB ports of WROVER KIT are recognized by Windows and drives are installed. If they do not install automatically, then then download them from http://www.ftdichip.com/Drivers/D2XX.htm and install manually.
 
@@ -64,7 +66,7 @@ Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To car
 Linux
 """""
 
-1.  Using standard USB A / mini USB B cable connect ESP32 WROVER KIT board to the computer. Power on the board.
+1.  Using standard USB A / micro USB B cable connect ESP32 WROVER KIT board to the computer. Power on the board.
 
 .. highlight:: none
 
@@ -97,6 +99,97 @@ Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To car
 MacOS
 """""
 
-[TBD]
+On macOS, using FT2232 for JTAG and serial port at the same time needs some additional steps. When the OS loads FTDI serial port driver, it does so for both channels of FT2232 chip. However only one of these channels is used as a serial port, while the other is used as JTAG. If the OS has loaded FTDI serial port driver for the channel used for JTAG, OpenOCD will not be able to connect to to the chip. There are two ways around this:
+
+1. Manually unload the FTDI serial port driver before starting OpenOCD, start OpenOCD, then load the serial port driver.
+
+2. Modify FTDI driver configuration so that it doesn't load itself for channel B of FT2232 chip, which is the channel used for JTAG on WROVER KIT. 
+
+Manually unloading the driver
+.............................
+
+1. Install FTDI driver from http://www.ftdichip.com/Drivers/VCP.htm
+
+2. Connect USB cable to the WROVER KIT.
+
+3. Unload the serial port driver::
+
+    sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver
+
+   In some cases you may need to unload Apple's FTDI driver as well::
+
+    sudo kextunload -b com.apple.driver.AppleUSBFTDI
+
+4. Run OpenOCD (paths are given for downloadable OpenOCD archive)::
+
+    bin/openocd -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
+
+   Or, if OpenOCD was built from source::
+
+    src/openocd -s tcl -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
+
+5. In another terminal window, load FTDI serial port driver again::
+
+    sudo kextload -b com.FTDI.driver.FTDIUSBSerialDriver
+
+
+Note that if you need to restart OpenOCD, there is no need to unload FTDI driver again — just stop OpenOCD and start it again. The driver only needs to be unloaded if WROVER KIT was reconnected or power was toggled.
+
+This procedure can be wrapped into a shell script, if desired.
+
+Modifying FTDI driver
+.....................
+
+In a nutshell, this approach requires modification to FTDI driver configuration file, which prevents the driver from being loaded for channel B of FT2232H.
+
+.. note:: Other boards may use channel A for JTAG, so use this option with caution.
+
+.. warning:: This approach also needs signature verification of drivers to be disabled, so may not be acceptable for all users.
+
+
+1. Open FTDI driver configuration file using a text editor (note ``sudo``)::
+
+    sudo nano /Library/Extensions/FTDIUSBSerialDriver.kext/Contents/Info.plist
+
+2. Find and delete the following lines::
+
+        <key>FT2232H_B</key>
+        <dict>
+            <key>CFBundleIdentifier</key>
+            <string>com.FTDI.driver.FTDIUSBSerialDriver</string>
+            <key>IOClass</key>
+            <string>FTDIUSBSerialDriver</string>
+            <key>IOProviderClass</key>
+            <string>IOUSBInterface</string>
+            <key>bConfigurationValue</key>
+            <integer>1</integer>
+            <key>bInterfaceNumber</key>
+            <integer>1</integer>
+            <key>bcdDevice</key>
+            <integer>1792</integer>
+            <key>idProduct</key>
+            <integer>24592</integer>
+            <key>idVendor</key>
+            <integer>1027</integer>
+        </dict>
+
+3. Save and close the file
+
+4. Disable driver signature verification:
+
+   1. Open Apple logo menu, choose "Restart..."
+
+   2. When you hear the chime after reboot, press CMD+R immediately
+
+   3. Once Recovery mode starts up, open Terminal
+
+   4. Run the command::
+
+       csrutil enable --without kext
+
+   5. Restart again
+
+After these steps, serial port and JTAG can be used at the same time.
+
+To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.
 
-Now ESP32 WROVER KIT's JTAG interface should be available to the OpenOCD. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`.