Moved unused pkg-config settings to /doc/dev

(Closes #971)

.gitignore

@@ -1,5 +1,5 @@
 build
 build-mingw
+.project
 obj-*
 *.user*
-.project

CMakeLists.txt

@@ -47,13 +47,6 @@ endif ()
 
 find_package(libusb REQUIRED)
 
-## Package configuration (pkg-config) on unix-based systems
-if (NOT WIN32 AND NOT CMAKE_CROSSCOMPILING)
-    #add_subdirectory(cmake/pkgconfig)
-    find_package(PkgConfig)
-    pkg_check_modules(GTK3 gtk+-3.0)
-endif ()
-
 ## Check for system-specific additional header files and libraries
 include(CheckIncludeFile)
 

doc/compiling.md

@@ -88,7 +88,6 @@ Install the following packages from your package repository:
 * `build-essential` (on Debian based distros (Debian, Ubuntu))
 * `cmake` (3.4.2 or later, use the latest version available from the repository)
 * `rpm` (on Debian based distros (Debian, Ubuntu), needed for package build with `make package`)
-* `pkg-config`
 * `libusb-1.0`
 * `libusb-1.0-0-dev` (development headers for building)
 * `libgtk-3-dev` (_optional_, needed for `stlink-gui`)
@@ -194,7 +193,6 @@ Then install the following dependencies from the package repository:
 * `git`
 * `gcc` or `llvm` (for clang) (C-compiler)
 * `cmake`
-* `pkg-config`
 * `libusb`
 * `gtk+3` or `gtk3` (_optional_, needed for `stlink-gui`)
 

doc/dev/developer.txt

@@ -1,4 +1,21 @@
-  
+=== Compilation with pkg-config ===
+
+In order to use pkg-config for development purposes, add the following lines to the toplevel CMakeLists.txt file:
+
+###
+# Additional build tasks
+###
+
+## Package configuration (pkg-config) on unix-based systems
+if (NOT WIN32 AND NOT CMAKE_CROSSCOMPILING)
+    add_subdirectory(doc/dev/pkg-config) # Option A: external tool pkg-config
+    find_package(PkgConfig)              # Option B: internal cmake module for pkg-config integration
+    pkg_check_modules(GTK3 gtk+-3.0)
+endif ()
+
+ToDo: Check for compatibility issues between options A and B.
+
+
 === Target Identification ===
 
 The following information is available about the target:
@@ -42,7 +59,7 @@ Include stlink/backend.h
         int (*current_mode) (stlink_t * stl);
         int (*force_debug) (stlink_t *sl);
         int32_t (*target_voltage) (stlink_t *sl);
-        int (*set_swdclk) (stlink_t * stl, uint16_t divisor);		
+        int (*set_swdclk) (stlink_t * stl, uint16_t divisor);
     } stlink_backend_t;
 
 Descriptions below describe the actions of the usb.h backend:
@@ -55,7 +72,7 @@ int (*exit_debug_mode) (stlink_t * sl);
 int (*enter_swd_mode) (stlink_t * sl);
   _stlink_usb_enter_swd_mode: Send STLINK_DEBUG_ENTER+STLINK_DEBUG_ENTER_SWD
   returns -1 or 0
-  
+
 int (*enter_jtag_mode) (stlink_t * stl);
 
 int (*exit_dfu_mode) (stlink_t * stl);
@@ -65,19 +82,19 @@ int (*exit_dfu_mode) (stlink_t * stl);
 int (*core_id) (stlink_t * stl);
   _stlink_usb_core_id: Assign the result from STLINK_DEBUG_READCOREID to stl->core_id
   returns -1 or 0
-  
+
 int (*reset) (stlink_t * stl);
   _stlink_usb_reset: Send STLINK_DEBUG_RESETSYS and reset via AIRCR
-  AIRCR is part of the CMSIS System Control Block (SCB), which is located in 
+  AIRCR is part of the CMSIS System Control Block (SCB), which is located in
   the System Control Space at 0xE000ED0C
   returns -1 or 0 ?
-  
+
 int (*jtag_reset) (stlink_t * stl, int value);
   _stlink_usb_jtag_reset: Send STLINK_JTAG_DRIVE_NRST.
   "value" is sent as argument for STLINK_JTAG_DRIVE_NRST and probably contains
   the status of the NRST line (0: low, 1: high). Also the value 2 is used in the software.
   returns -1 or 0
-  
+
 int (*run) (stlink_t * stl);
   _stlink_usb_run: Send STLINK_DEBUG_RUNCORE
   returns -1 or 0
@@ -85,12 +102,12 @@ int (*run) (stlink_t * stl);
 int (*status) (stlink_t * stl);
   _stlink_usb_status: Assign the result from STLINK_DEBUG_GETSTATUS to stl->q_len
   returns -1 or 0
-  
+
 int (*version) (stlink_t *sl);
   _stlink_usb_version: Read version with STLINK_GET_VERSION.
   Result is stored in sl->q_buf (6 bytes????)
   returns -1 or 0
-  
+
 int (*read_debug32) (stlink_t *sl, uint32_t addr, uint32_t *data);
   _stlink_usb_read_debug32: Send STLINK_JTAG_READDEBUG_32BIT
   to read 32 bits from "addr". The result data is stored at "*data".
@@ -99,10 +116,10 @@ int (*read_debug32) (stlink_t *sl, uint32_t addr, uint32_t *data);
 int (*read_mem32) (stlink_t *sl, uint32_t addr, uint16_t len);
   _stlink_usb_read_mem32: Use STLINK_DEBUG_READMEM_32BIT
   to read "len" bytes from "addr"
-  Result is returned in sl->q_buf, sl->q_len returns the size of the data (should be 
+  Result is returned in sl->q_buf, sl->q_len returns the size of the data (should be
   equal to "len"???).
   returns -1 or 0
-  
+
 int (*write_debug32) (stlink_t *sl, uint32_t addr, uint32_t data);
   _stlink_usb_write_debug32: Use STLINK_JTAG_WRITEDEBUG_32BIT
   to store "data" at "addr"
@@ -124,13 +141,13 @@ int (*read_all_regs) (stlink_t *sl, struct stlink_reg * regp);
   _stlink_usb_read_all_regs: Send STLINK_DEBUG_READALLREGS to read
   all register values and store them into *regp;
   returns -1 or 0
-  
+
 int (*read_reg) (stlink_t *sl, int r_idx, struct stlink_reg * regp);
   _stlink_usb_read_reg: Send STLINK_DEBUG_READREG to read specific register "r_idx".
-  The result is then stored in *regp in the correct register. 
+  The result is then stored in *regp in the correct register.
   Example if "r_idx" is 18, then the result is stored in regp->process_sp
   returns -1 or 0
-  
+
 int (*read_all_unsupported_regs) (stlink_t *sl, struct stlink_reg *regp);
   _stlink_usb_read_all_unsupported_regs: Calls "_stlink_usb_read_unsupported_reg"
   (see below) to read all registers.
@@ -142,7 +159,7 @@ int (*read_unsupported_reg) (stlink_t *sl, int r_idx, struct stlink_reg *regp);
   Also will fill regp->s (???) for some specific "r_idx" values.
   WARNING: Some r_idx values may lead to a out of array bound problem in C.
   returns -1 or 0
-    
+
 int (*write_unsupported_reg) (stlink_t *sl, uint32_t value, int idx, struct stlink_reg *regp);
   _stlink_usb_write_unsupported_reg:
   Updates one of the following registers:
@@ -154,14 +171,14 @@ int (*write_unsupported_reg) (stlink_t *sl, uint32_t value, int idx, struct stli
   returns -1 or 0
 
 int (*write_reg) (stlink_t *sl, uint32_t reg, int idx);
-  _stlink_usb_write_reg: Use STLINK_DEBUG_WRITEREG to update register "idx" 
+  _stlink_usb_write_reg: Use STLINK_DEBUG_WRITEREG to update register "idx"
   with value "reg".
   returns -1 or 0
-  
+
 int (*step) (stlink_t * stl);
   _stlink_usb_step: Send STLINK_DEBUG_STEPCORE
   returns -1 or 0
-  
+
 int (*current_mode) (stlink_t * stl);
   _stlink_usb_current_mode: Send STLINK_GET_CURRENT_MODE and return
   the current mode.
@@ -174,15 +191,15 @@ int (*current_mode) (stlink_t * stl);
 int (*force_debug) (stlink_t *sl);
   _stlink_usb_force_debug: Sends STLINK_DEBUG_FORCEDEBUG. No other side effects
   returns -1 or 0
-  
+
 int32_t (*target_voltage) (stlink_t *sl);
   _stlink_usb_target_voltage: Send STLINK_GET_TARGET_VOLTAGE
   returns -1 or the target voltage. (??? dimension is not clear...)
 
-int (*set_swdclk) (stlink_t * stl, uint16_t divisor);	
+int (*set_swdclk) (stlink_t * stl, uint16_t divisor);
   _stlink_usb_set_swdclk: Send STLINK_DEBUG_APIV2_SWD_SET_FREQ and "divisor" value
   returns -1 or 0
-  
+
 
 === Other Functions ===
 
@@ -193,17 +210,17 @@ Include: stlink.h
 Prototype:	void stlink_close(stlink_t *sl);
 Include:		inc/stlink.h
 Definition: 	src/common.c
-Description:	
+Description:
   Calls the backend "close" procedure and frees 'sl'
 Backend:		"close"
 Arguments:
   sl:	Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
 Return:		-
- 
+
 Include:		inc/stlink.h
 Prototype:	int stlink_core_id(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
+Description:
   Calls the backend "core_id", calls stlink_print_data() on higher verbose levels.
   Assigns the core id returned by STLINK_DEBUGREADCOREID to sl->core_id
   Only some specific core ids are used: See include/stm32.h
@@ -216,8 +233,8 @@ Return:		-1 for error. 0 for success.
 Include:		inc/stlink.h
 Prototype:	int stlink_reset(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
-  Just calls the backend "reset" procedure (reset via STLINK_DEBUG_RESETSYS 
+Description:
+  Just calls the backend "reset" procedure (reset via STLINK_DEBUG_RESETSYS
   and reset via AIRCR register at 0xE000ED0C)
 Backend:		"reset"
 Arguments:
@@ -227,29 +244,29 @@ Return:		-1 for error. 0 for success.
 Include:		inc/stlink.h
 Prototype:	int stlink_jtag_reset(stlink_t *sl, int value);
 Definition: 	src/common.c
-Description:	
-  Just calls the backend "jtag_reset" procedure 
+Description:
+  Just calls the backend "jtag_reset" procedure
 Backend:		"jtag_reset"
 Arguments:
   sl:		Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
   value: 	0: drive low, 1: drive high, 2: ????
 Return:		-1 for error. 0 for success.
-  
- 
+
+
 Include:		inc/stlink.h
 Prototype:	int stlink_run(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
+Description:
   Just calls the backend "run" procedure.
 Backend:		"run"
 Arguments:
   sl:	Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
 Return:		-1 for error. 0 for success.
-    
+
 Include:		inc/stlink.h
 Prototype:	int stlink_status(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
+Description:
   Calls the backend "status" procedure and the procedure "stlink_core_stat()" to
   store the status in "sl->core_stat". Possible value for "sl->core_stat" are:
     STLINK_CORE_RUNNING
@@ -259,12 +276,12 @@ Backend:		"status"
 Arguments:
   sl:	Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
 Return:		-1 for error. 0 for success.
-    
+
 
 Include:		inc/stlink.h
 Prototype:	int stlink_version(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
+Description:
   Calls the backend "version" procedure, parses the result and puts the result into sl->version
   This version probably refers to the version of the adapter.
 Backend:		"version"
@@ -272,9 +289,9 @@ Arguments:
   sl:	Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
 Return:		-1 for error. 0 for success.
 
-    
+
     int stlink_read_debug32(stlink_t *sl, uint32_t addr, uint32_t *data);
-    int stlink_read_mem32(stlink_t *sl, uint32_t addr, uint16_t len);    
+    int stlink_read_mem32(stlink_t *sl, uint32_t addr, uint16_t len);
     int stlink_write_debug32(stlink_t *sl, uint32_t addr, uint32_t data);
     int stlink_write_mem32(stlink_t *sl, uint32_t addr, uint16_t len);
     int stlink_write_mem8(stlink_t *sl, uint32_t addr, uint16_t len);
@@ -305,9 +322,9 @@ Return:		-1 for error. 0 for success.
 Include:		inc/stlink.h
 Prototype:	int stlink_chip_id(stlink_t *sl, uint32_t *chip_id);
 Definition: 	src/common.c
-Description:	
+Description:
   Tries to read out the chip id via memory read from the device.
-  Note: sl->chip_id is NOT updated by this procedure. Instead this happens in stlink_load_device_params(): 
+  Note: sl->chip_id is NOT updated by this procedure. Instead this happens in stlink_load_device_params():
   Do not call this function, but instead call stlink_load_device_params()
 Backend:		-
 Arguments:
@@ -319,7 +336,7 @@ Return:		-1 for error. 0 for success.
 Include:		inc/stlink.h
 Prototype:	int stlink_cpu_id(stlink_t *sl, cortex_m3_cpuid_t *cpuid);
 Definition: 	src/common.c
-Description:	
+Description:
   Reads the CPU id from STLINK_REG_CM3_CPUID (0xE000ED00, first value of
   the SCB, system control block) and splits this into
     cpuid->implementer_id
@@ -333,19 +350,19 @@ Arguments:
   cpuid:	Pointer. Result is stored via this pointer.
 Return:		-1 for error. 0 for success.
 
-    
-    
+
+
 
     int stlink_erase_flash_page(stlink_t* sl, stm32_addr_t flashaddr);
     uint32_t stlink_calculate_pagesize(stlink_t *sl, uint32_t flashaddr);
     uint16_t read_uint16(const unsigned char *c, const int pt);
     void stlink_core_stat(stlink_t *sl);
-    
+
 
 Include:		inc/stlink.h
 Prototype:	void stlink_print_data(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
+Description:
   If debug logging is enabled: Print the HEX content of the q_buf array.
   q_buf will contain the result of the last "backend" command.
 Backend:		-
@@ -362,21 +379,21 @@ Return:		-
     int write_buffer_to_sram(stlink_t *sl, flash_loader_t* fl, const uint8_t* buf, size_t size);
     int write_loader_to_sram(stlink_t *sl, stm32_addr_t* addr, size_t* size);
     int stlink_fread(stlink_t* sl, const char* path, bool is_ihex, stm32_addr_t addr, size_t size);
-    
-    
+
+
 Include:		inc/stlink.h
 Prototype:	int stlink_load_device_params(stlink_t *sl);
 Definition: 	src/common.c
-Description:	
+Description:
   This is one of the most important procedures. It will get all the device info
   and store the results in the "sl" structure. Many other procedures will depend
   on this information.
-  The identification is based on the stlink_chip_id() result and the flash_size register value 
+  The identification is based on the stlink_chip_id() result and the flash_size register value
 Backend:		-
 Arguments:
   sl:	Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
 Return:		-1 for error. 0 for success.
-    
+
     int stlink_read_option_bytes_f2(stlink_t *sl, uint32_t* option_byte);
     int stlink_read_option_bytes_f4(stlink_t *sl, uint32_t* option_byte);