Skip to content

Commit

Permalink
Updated stlink-v1 driver for macOS
Browse files Browse the repository at this point in the history 
- Updated xcode project settings v11.3.1
- Removed support for 10.6-10.12
- Compiled new kexts for macOS 10.13-10.15
- Moved instructions to separate README
- Updated installation instructions
  • Loading branch information
@Nightwalker-87
Nightwalker-87 committed May 26, 2020
1 parent 937f4d6 commit 230497c
Show file tree
Hide file tree
Showing 29 changed files with 1,666 additions and 123 deletions.
65 changes: 1 addition & 64 deletions doc/tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
25 changes: 13 additions & 12 deletions stlinkv1_macosx_driver/Makefile → stlinkv1_macos_driver/Makefile
View file
Original file line number Diff line number Diff line change
@@ -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


Expand All @@ -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"
Expand All @@ -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
50 changes: 50 additions & 0 deletions stlinkv1_macos_driver/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
###
# 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) Install the macOS Kernel Extension (kext):
- 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.

2) Install the ST-Link-v1 driver from this subdirectory `/stlinkv1_macos_driver` by executing: ```sudo make osx_stlink_shield```. This should result in the following output:

```
Requesting load of /System/Library/Extensions/stlink_shield.kext.
/System/Library/Extensions/stlink_shield.kext loaded successfully (or already loaded).
```

3) 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 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
```

In order to deactivate SIP, boot into the recovery mode and run ```csrutil disable``` in a terminal console window.

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...
```
22 changes: 22 additions & 0 deletions stlinkv1_macos_driver/install.sh
View file
Original file line number Diff line number Diff line change
@@ -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 /System/Library/Extensions/stlink_shield.kext
kextload -v /System/Library/Extensions/stlink_shield.kext
touch /System/Library/Extensions
82 changes: 82 additions & 0 deletions stlinkv1_macos_driver/stlink_shield_10_13.kext/Contents/Info.plist
View file
Original file line number Diff line number Diff line change
@@ -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>
Binary file added stlinkv1_macos_driver/stlink_shield_10_13.kext/Contents/MacOS/stlink_shield_10_13
View file
Binary file not shown.
1 change: 1 addition & 0 deletions stlinkv1_macos_driver/stlink_shield_10_13.kext/Contents/PkgInfo
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
KEXT????
Loading

0 comments on commit 230497c

Please sign in to comment.