From 51ec59404cd24dfbbe52d7109a3310c4a6bcfbd9 Mon Sep 17 00:00:00 2001
From: nightwalker-87 <15526941+Nightwalker-87@users.noreply.github.com>
Date: Tue, 7 Apr 2020 18:30:26 +0200
Subject: [PATCH] [doc] macOS ST-Link-v1 detection

Added documentation on how to solve a failed detection of the ST-Link-v1
programmer in macOS v10.11 and later.
(Closes #574, #587)
---
 doc/tutorial.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/doc/tutorial.md b/doc/tutorial.md
index 1d48eaa38..9c1f7f26d 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -13,6 +13,70 @@ This option accepts decimal (128k), octal 0200k, or hex 0x80k.
 Obviously leaving the multiplier out is equally valid, for example: `--flash=0x20000`.
 The size may be followed by an optional "k" or "m" to multiply the given value by 1k (1024) or 1M respectively.
 
+
+## Solution to common problems
+### ST-Link-v1 driver: Issue with Kernel Extension (kext) (macOS 10.11 and later only)
+#### Problem:
+
+st-util fails to detect a ST-Link-v1 device:
+
+```
+st-util -1
+st-util $VERSION-STRING$
+WARN src/sg.c: Failed to find an stlink v1 by VID:PID
+ERROR src/sg.c: Could not open stlink device
+```
+
+#### Solution (clean setup):
+
+1) Configure System Integrity Protection (SIP)
+
+The root of this problem is a system security setting introduced by Apple with OS X El Capitan (10.11) in 2015.
+The so called System Integrity Protection (SIP) is active per default
+and prevents the operating system amongst other things to load unsigned Kernel Extension Modules (kext).
+Thus the ST-Link-v1 driver supplied with the tools, which installs as a kext, remains not functional,
+while SIP is fully activated (as is per default).
+
+Action needs to be taken here by booting into the recovery mode where a terminal console window needs to be opened.
+
+Here it is **NOT RECOMMEND to disable SIP completely as with the command** `csrutil disable`,
+**because this leaves the system more vulnerable to common threats.
+Instead there is a more adequate and reasonable option implemented by Apple.
+Running** `csrutil enable --without kext`, **allows to load unsigned kernel extensions
+while leaving SIP active with all other security features.**
+So who ever intends to run the ST-Link-v1 programmer on macOS please take this into account.
+
+Further details can be found here: https://forums.developer.apple.com/thread/17452
+
+2) Install the ST-Link-v1 driver from the subdirectory `/stlinkv1_macosx_driver`
+   by referring to the instructions in the README file available there.
+
+3) Move the $OS_VERSION$.kext file to `/System/Library/Extensions`.
+
+4) Load the Kernel Extension (kext): `$ sudo kextload -v /System/Library/Extensions/stlink_shield10_x.kext`
+
+```
+Requesting load of /System/Library/Extensions/stlink_shield10_x.kext.
+/System/Library/Extensions/stlink_shield10_x.kext loaded successfully (or already loaded).
+```
+
+5) Enter the command `$ sudo touch /System/Library/Extensions`
+
+
+7) Verify correct detection of the ST-Link-v1 device with the following input: `st-util -1`
+
+You should then see a similar output like in this example:
+
+```
+INFO common.c: Loading device parameters....
+INFO common.c: Device connected is: F1 High-density device, id 0x10036414
+INFO common.c: SRAM size: 0x10000 bytes (64 KiB), Flash: 0x80000 bytes (512 KiB) in pages of 2048 bytes
+INFO sg.c: Successfully opened a stlink v1 debugger
+INFO gdb-server.c: Chip ID is 00000414, Core ID is  1ba01477.
+INFO gdb-server.c: Listening at *:4242...
+```
+
+
 ------
 
 Using STM32 discovery kits with open source tools