Merge pull request #964 from stlink-org/macos_kext

Updated STLink-v1 driver for macOS

CMakeLists.txt

@@ -143,7 +143,7 @@ endif ()
 set(STLINK_LIBRARY_PATH ${CMAKE_INSTALL_LIBDIR} CACHE PATH "Main library install directory")
 
 # Set the environment variable LD_LIBRARY_PATH to point to /usr/local/lib (per default).
-execute_process (COMMAND bash -c "export LD_LIBRARY_PATH="${CMAKE_INSTALL_LIBDIR}"")
+execute_process (COMMAND bash -c "export LD_LIBRARY_PATH="${CMAKE_INSTALL_LIBDIR}" ")
 
 
 ###

doc/tutorial.md

@@ -29,70 +29,7 @@ Within the GUI main window tooltips explain the available user elements.
 
 
 ## Solutions to common problems
-### a) STLINK/v1 driver: Issue with Kernel Extension (kext) (macOS 10.11 and later only)
-#### Problem:
-
-st-util fails to detect a STLINK/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 STLINK/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.
-
-For macOS 10.11 - 10.13 it is not recommended 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.
-Unfortunately this option has been removed in macOS 10.14, which leaves the only option to disable SIP completely.
-
-So who ever intends to run the STLINK/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 STLINK/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...
-```
-
-### b) Verify if udev rules are set correctly (by Dave Hylands)
+### a) Verify if udev rules are set correctly (by Dave Hylands)
 
 To investigate, start by plugging your STLINK device into the usb port. Then run `lsusb`. You should see an entry something like the following:
 

stlinkv1_macosx_driver/Makefile → stlinkv1_macos_driver/Makefile

@@ -1,15 +1,17 @@
-# make ... for both stlink v1 and stlink v2 support
-##
+###
+# Makefile for STlink-v1 support
+###
+
 VPATH=src
 
-SOURCES_LIB=stlink-common.c stlink-usb.c stlink-sg.c uglylogging.c
+SOURCES_LIB=common.c usb.c sg.c logging.c
 OBJS_LIB=$(SOURCES_LIB:.c=.o)
-TEST_PROGRAMS=test_usb test_sg
+TEST_PROGRAMS=test-flash test-sg test-usb
 LDFLAGS=-L. -lstlink -lusb-1.0
 
 CFLAGS+=-g
 CFLAGS+=-DDEBUG=1
-CFLAGS+=-std=gnu99
+CFLAGS+=-std=gnu11
 CFLAGS+=-Wall -Wextra
 
 
@@ -20,8 +22,8 @@ all:  $(LIBRARY) flash gdbserver $(TEST_PROGRAMS)
 $(LIBRARY): $(OBJS_LIB)
 	@echo "objs are $(OBJS_LIB)"
 	$(AR) -cr $@ $^
-	@echo "done making library"
-	
+	@echo "Compilation of library completed."
+
 
 test_sg: test_sg.o $(LIBRARY)
 	@echo "building test_sg"
@@ -40,18 +42,17 @@ test_usb: test_usb.o $(LIBRARY)
 clean:
 	rm -rf $(OBJS_LIB)
 	rm -rf $(LIBRARY)
-	rm -rf test_usb*
-	rm -rf test_sg*
+	rm -rf test-flash* test-sg* test-usb*
 	$(MAKE) -C flash clean
 	$(MAKE) -C gdbserver clean
-	
+
 flash:
 	$(MAKE) -C flash
 
 gdbserver:
 	$(MAKE) -C gdbserver CONFIG_USE_LIBSG="$(CONFIG_USE_LIBSG)"
 
-osx_stlink_shield:
-	./osx/install.sh
+macos_stlink_shield:
+	./install.sh
 
 .PHONY: clean all flash gdbserver

stlinkv1_macos_driver/README.md

@@ -0,0 +1,39 @@
+# Installation instructions for STLINK/v1 driver
+
+When connecting to the STLINK/v1 on macOS via USB, the system claims the programmer as a SCSI device. Thus libusb is not able to initialise and establish a connection to it. To solve this issue Marco Cassinerio ([email protected]) has created a so called "codeless driver" which claims the device. It is of higher priority then the default apple mass storage driver, what allows the device to be accessed through libusb.
+
+To make use of this alternative approach one needs to go through the following steps:
+
+1) Configure System Integrity Protection (SIP)
+
+The above system security setting introduced by Apple with OS X El Capitan (10.11) in 2015 is active per default
+and prevents the operating system amongst other things to load unsigned Kernel Extension Modules (kext).
+Thus the STLINK/v1 driver supplied with the tools, which installs as a kext, remains not functional,
+until SIP is fully deactivated. Without SIP-deactivation, st-util would fail to detect a STLINK/v1 device later on.
+
+In order to deactivate SIP, boot into the recovery mode and run ```csrutil disable``` in a terminal console window.
+
+2) Reboot the system.
+
+3) Install the macOS Kernel Extension (kext) (ST-Link-v1 driver):
+ - Open a terminal console and navigate to this subdirectory `/stlinkv1_macos_driver`
+ - Use the command ```sudo sh ./install.sh``` to install the appropiate kext for your system version.
+   This should result in the following output:
+
+```
+Requesting load of /Library/Extensions/stlink_shield.kext.
+/Library/Extensions/stlink_shield.kext loaded successfully (or already loaded).
+```
+4) Reboot the system.
+
+5) Verify correct detection of the STLINK/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...
+```

stlinkv1_macos_driver/install.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+ISMACOS=$(sw_vers -productVersion)
+case $ISMACOS in
+10.13*)
+    KEXT="stlink_shield_10_13.kext"
+    ;;
+10.14*)
+    KEXT="stlink_shield_10_14.kext"
+    ;;
+10.15*)
+    KEXT="stlink_shield_10_15.kext"
+    ;;
+*)
+    echo "OS X version not supported."
+    exit 1
+    ;;
+esac
+chown -R root:wheel $KEXT/
+cp -R $KEXT /Library/Extensions/stlink_shield.kext
+kextload -v /Library/Extensions/stlink_shield.kext
+touch /Library/Extensions

stlinkv1_macos_driver/stlink_shield_10_13.kext/Contents/Info.plist

@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>BuildMachineOSBuild</key>
+	<string>18G4032</string>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>English</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.libusb.stlink-shield</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundlePackageType</key>
+	<string>KEXT</string>
+	<key>CFBundleSignature</key>
+	<string>????</string>
+	<key>CFBundleSupportedPlatforms</key>
+	<array>
+		<string>MacOSX</string>
+	</array>
+	<key>CFBundleVersion</key>
+	<string>1.0.0</string>
+	<key>DTCompiler</key>
+	<string>com.apple.compilers.llvm.clang.1_0</string>
+	<key>DTPlatformBuild</key>
+	<string>11C504</string>
+	<key>DTPlatformVersion</key>
+	<string>GM</string>
+	<key>DTSDKBuild</key>
+	<string>19B90</string>
+	<key>DTSDKName</key>
+	<string>macosx10.15</string>
+	<key>DTXcode</key>
+	<string>1130</string>
+	<key>DTXcodeBuild</key>
+	<string>11C504</string>
+	<key>IOKitPersonalities</key>
+	<dict>
+		<key>DeviceDriver</key>
+		<dict>
+			<key>CFBundleIdentifier</key>
+			<string>com.apple.kpi.iokit</string>
+			<key>IOClass</key>
+			<string>IOService</string>
+			<key>IOProviderClass</key>
+			<string>IOUSBDevice</string>
+			<key>bcdDevice</key>
+			<integer>256</integer>
+			<key>idProduct</key>
+			<integer>14148</integer>
+			<key>idVendor</key>
+			<integer>1155</integer>
+		</dict>
+		<key>InterfaceDriver</key>
+		<dict>
+			<key>CFBundleIdentifier</key>
+			<string>com.apple.kpi.iokit</string>
+			<key>IOClass</key>
+			<string>IOService</string>
+			<key>IOProviderClass</key>
+			<string>IOUSBInterface</string>
+			<key>bConfigurationValue</key>
+			<integer>1</integer>
+			<key>bInterfaceNumber</key>
+			<integer>0</integer>
+			<key>idProduct</key>
+			<integer>14148</integer>
+			<key>idVendor</key>
+			<integer>1155</integer>
+		</dict>
+	</dict>
+	<key>LSMinimumSystemVersion</key>
+	<string>10.13</string>
+	<key>OSBundleLibraries</key>
+	<dict>
+		<key>com.apple.iokit.IOUSBFamily</key>
+		<string>1.8</string>
+		<key>com.apple.kpi.libkern</key>
+		<string>11.2.0</string>
+	</dict>
+</dict>
+</plist>

stlinkv1_macos_driver/stlink_shield_10_13.kext/Contents/PkgInfo

@@ -0,0 +1 @@
+KEXT????