From ade735dd671ea30ebbef36aaa17b51c6294425cf Mon Sep 17 00:00:00 2001 From: nightwalker-87 <15526941+Nightwalker-87@users.noreply.github.com> Date: Wed, 3 Jun 2020 20:02:09 +0200 Subject: [PATCH] Moved unused pkg-config settings to /doc/dev (Closes #971) --- .gitignore | 2 +- CMakeLists.txt | 7 -- doc/compiling.md | 2 - doc/{ => dev}/app-example/CMakeLists.txt | 0 doc/{ => dev}/app-example/README.md | 0 doc/{ => dev}/app-example/main.c | 0 doc/{ => dev}/developer.txt | 115 ++++++++++-------- .../dev/pkg-config}/CMakeLists.txt | 0 .../dev/pkg-config}/pkgconfig.pc.cmake | 0 9 files changed, 67 insertions(+), 59 deletions(-) rename doc/{ => dev}/app-example/CMakeLists.txt (100%) rename doc/{ => dev}/app-example/README.md (100%) rename doc/{ => dev}/app-example/main.c (100%) rename doc/{ => dev}/developer.txt (93%) rename {cmake/pkgconfig => doc/dev/pkg-config}/CMakeLists.txt (100%) rename {cmake/pkgconfig => doc/dev/pkg-config}/pkgconfig.pc.cmake (100%) diff --git a/.gitignore b/.gitignore index 09b9b33..229242a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ build build-mingw +.project obj-* *.user* -.project diff --git a/CMakeLists.txt b/CMakeLists.txt index 51d0941..0538f3b 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/doc/compiling.md b/doc/compiling.md index 428d9cc..c278c9c 100644 --- a/doc/compiling.md +++ b/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`) diff --git a/doc/app-example/CMakeLists.txt b/doc/dev/app-example/CMakeLists.txt similarity index 100% rename from doc/app-example/CMakeLists.txt rename to doc/dev/app-example/CMakeLists.txt diff --git a/doc/app-example/README.md b/doc/dev/app-example/README.md similarity index 100% rename from doc/app-example/README.md rename to doc/dev/app-example/README.md diff --git a/doc/app-example/main.c b/doc/dev/app-example/main.c similarity index 100% rename from doc/app-example/main.c rename to doc/dev/app-example/main.c diff --git a/doc/developer.txt b/doc/dev/developer.txt similarity index 93% rename from doc/developer.txt rename to doc/dev/developer.txt index 2d05b93..4032eca 100644 --- a/doc/developer.txt +++ b/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); diff --git a/cmake/pkgconfig/CMakeLists.txt b/doc/dev/pkg-config/CMakeLists.txt similarity index 100% rename from cmake/pkgconfig/CMakeLists.txt rename to doc/dev/pkg-config/CMakeLists.txt diff --git a/cmake/pkgconfig/pkgconfig.pc.cmake b/doc/dev/pkg-config/pkgconfig.pc.cmake similarity index 100% rename from cmake/pkgconfig/pkgconfig.pc.cmake rename to doc/dev/pkg-config/pkgconfig.pc.cmake