document ASIO SDK windows crash bug fix in ASIO-README.txt and docs. f…

…ixes PortAudio#331 (PortAudio#760)
dechamps · Jan 30, 2023 · 4bccdfb · 4bccdfb
1 parent bbe2b5a
commit 4bccdfb
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 6 deletions.
diff --git a/doc/src/tutorial/compile_windows.dox b/doc/src/tutorial/compile_windows.dox
@@ -9,7 +9,7 @@ PortAudio can be compiled using Visual C++ Express Edition which is available fr
 
 1) Building PortAudio with DirectSound support requires the files <i>dsound.h</i> and <i>dsconf.h</i>. Download and install the DirectX SDK from http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=3021d52b-514e-41d3-ad02-438a3ba730ba to obtain these files. If you installed the DirectX SDK then the DirectSound libraries and header files should be found automatically by Visual Studio/Visual C++. If you get an error saying dsound.h or dsconf.h is missing, you will need to add an extra include path to the Visual Studio project file referencing the DirectX includes directory.
 
-2) For ASIO support, download the ASIO SDK from Steinberg at http://www.steinberg.net/en/company/developer.html . The SDK is free, but you will need to set up a developer account with Steinberg. To use the Visual Studio projects mentioned below, copy the entire ASIOSDK2 folder into src\\hostapi\\asio\\. Rename it from ASIOSDK2 to ASIOSDK. To build without ASIO (or other host API) see the "Building without ASIO support" section below.
+2) To build without ASIO (or other host API) see the "Building without ASIO support" section below. To build with ASIO support, download the ASIO SDK from Steinberg at http://www.steinberg.net/en/company/developer.html . The SDK is free, but you will need to set up a developer account with Steinberg. To use the Visual Studio projects mentioned below, copy the entire ASIOSDK2 folder into src\\hostapi\\asio\\. Rename it from ASIOSDK2 to ASIOSDK. Note: There's an array deletion bug in some versions of the ASIO SDK on Windows. To work around this issue you will need to patch the ASIO SDK. Please see src/host/asio/ASIO-README.txt for the fix.
 
 3) If you have Visual Studio 6.0, 7.0(VC.NET/2001) or 7.1(VC.2003), open portaudio.dsp and convert if needed.
 

diff --git a/doc/src/tutorial/compile_windows_asio_msvc.dox b/doc/src/tutorial/compile_windows_asio_msvc.dox
@@ -89,6 +89,8 @@ You'll need to make sure the relative paths are correct for the particular direc
 
 Some source code in the ASIO SDK is not compatible with the Win32 API UNICODE mode (The ASIO SDK expects the non-Unicode Win32 API). Therefore you need to make sure your project is set to not use Unicode. You do this by setting the project Character Set to "Use Multi-Byte Character Set" (NOT "Use Unicode Character Set"). In VS2010 the Character Set option can be found at Configuration Properties > General > Character Set. (An alternative to setting the project to non-Unicode is to patch asiolist.cpp to work when UNICODE is defined: put #undef UNICODE at the top of the file before windows.h is included.)
 
+Note: There's an array deletion bug in some versions of the ASIO SDK on Windows. To work around this issue you will need to patch the ASIO SDK. Please see src/host/asio/ASIO-README.txt for the fix.
+
 You should now be able to build any of the test executables in the portaudio\\examples directory.
 We suggest that you start with paex_saw.c because it's one of the simplest example files.
 

diff --git a/src/hostapi/asio/ASIO-README.txt b/src/hostapi/asio/ASIO-README.txt
@@ -13,7 +13,7 @@ Building PortAudio with ASIO support
 ------------------------------------
 
 To build PortAudio with ASIO support you need to compile and link with
-pa_asio.c, and files from the ASIO SDK (see below), along with the common 
+pa_asio.cpp, and files from the ASIO SDK (see below), along with the common
 PortAudio files from src/common/ and platform specific files from 
 src/os/win/ (for Win32).
 
@@ -32,7 +32,7 @@ path to the ASIO SDK.
 
 
 For Microsoft Visual C++ there is an build tutorial here:
-http://www.portaudio.com/trac/wiki/TutorialDir/Compile/WindowsASIOMSVC
+http://files.portaudio.com/docs/v19-doxydocs/compile_windows_asio_msvc.html
 
 
 
@@ -60,9 +60,9 @@ Building the ASIO SDK on Windows
 To build the ASIO SDK on Windows you need to compile and link with the 
 following files from the ASIO SDK:
 
-asio_sdk\common\asio.cpp
-asio_sdk\host\asiodrivers.cpp
-asio_sdk\host\pc\asiolist.cpp
+$ASIOSDK\common\asio.cpp
+$ASIOSDK\host\asiodrivers.cpp
+$ASIOSDK\host\pc\asiolist.cpp
 
 You may also need to adjust your include paths to support inclusion of 
 header files from the above directories.
@@ -72,6 +72,28 @@ CoInitialize, CoUninitialize, CoCreateInstance, CLSIDFromString
 For compilation with MinGW you will need to link with -lole32, for
 Borland compilers link with Import32.lib.
 
+See the next section for information about patching a bug in the SDK.
+
+
+Windows ASIO SDK 2.3 Bug Patch
+------------------------------
+
+There is a regression in some versions of the ASIO SDK (e.g. version 2.3)
+which may trigger a crash in the `deleteDrvStruct()` function in
+file `$ASIOSDK\host\pc\asiolist.cpp`.
+
+To fix this issue replace the line:
+    delete lpdrv;
+with:
+    delete [] lpdrv;
+
+Explanation: lpdrv is allocated as an array on the line:
+    lpdrv = new ASIODRVSTRUCT[1];
+Hence it must also be deleted as an array as per standard C++ rules.
+
+We are tracking this issue here:
+https://github.com/PortAudio/portaudio/issues/331
+
 
 
 Non-Microsoft (MSVC) Compilers on Windows including Borland and GCC
@@ -112,6 +134,7 @@ host/mac/codefragements.cpp
 You may also need to adjust your include paths to support inclusion of 
 header files from the above directories.
 
+See the next section for information about patching a bug in the SDK.
 
 
 (Pre-OS X) Macintosh ASIO SDK Bug Patch