Moved unused pkg-config settings to /doc/dev

(Closes #971)
pull/978/head
nightwalker-87 2020-06-03 20:02:09 +02:00
rodzic b0dcb0cd39
commit ade735dd67
9 zmienionych plików z 67 dodań i 59 usunięć

2
.gitignore vendored
Wyświetl plik

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

Wyświetl plik

@ -47,13 +47,6 @@ endif ()
find_package(libusb REQUIRED) 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 ## Check for system-specific additional header files and libraries
include(CheckIncludeFile) include(CheckIncludeFile)

Wyświetl plik

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

Wyświetl plik

@ -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 === === Target Identification ===
The following information is available about the target: The following information is available about the target:
@ -42,7 +59,7 @@ Include stlink/backend.h
int (*current_mode) (stlink_t * stl); int (*current_mode) (stlink_t * stl);
int (*force_debug) (stlink_t *sl); int (*force_debug) (stlink_t *sl);
int32_t (*target_voltage) (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; } stlink_backend_t;
Descriptions below describe the actions of the usb.h backend: 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); int (*enter_swd_mode) (stlink_t * sl);
_stlink_usb_enter_swd_mode: Send STLINK_DEBUG_ENTER+STLINK_DEBUG_ENTER_SWD _stlink_usb_enter_swd_mode: Send STLINK_DEBUG_ENTER+STLINK_DEBUG_ENTER_SWD
returns -1 or 0 returns -1 or 0
int (*enter_jtag_mode) (stlink_t * stl); int (*enter_jtag_mode) (stlink_t * stl);
int (*exit_dfu_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); int (*core_id) (stlink_t * stl);
_stlink_usb_core_id: Assign the result from STLINK_DEBUG_READCOREID to stl->core_id _stlink_usb_core_id: Assign the result from STLINK_DEBUG_READCOREID to stl->core_id
returns -1 or 0 returns -1 or 0
int (*reset) (stlink_t * stl); int (*reset) (stlink_t * stl);
_stlink_usb_reset: Send STLINK_DEBUG_RESETSYS and reset via AIRCR _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 the System Control Space at 0xE000ED0C
returns -1 or 0 ? returns -1 or 0 ?
int (*jtag_reset) (stlink_t * stl, int value); int (*jtag_reset) (stlink_t * stl, int value);
_stlink_usb_jtag_reset: Send STLINK_JTAG_DRIVE_NRST. _stlink_usb_jtag_reset: Send STLINK_JTAG_DRIVE_NRST.
"value" is sent as argument for STLINK_JTAG_DRIVE_NRST and probably contains "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. the status of the NRST line (0: low, 1: high). Also the value 2 is used in the software.
returns -1 or 0 returns -1 or 0
int (*run) (stlink_t * stl); int (*run) (stlink_t * stl);
_stlink_usb_run: Send STLINK_DEBUG_RUNCORE _stlink_usb_run: Send STLINK_DEBUG_RUNCORE
returns -1 or 0 returns -1 or 0
@ -85,12 +102,12 @@ int (*run) (stlink_t * stl);
int (*status) (stlink_t * stl); int (*status) (stlink_t * stl);
_stlink_usb_status: Assign the result from STLINK_DEBUG_GETSTATUS to stl->q_len _stlink_usb_status: Assign the result from STLINK_DEBUG_GETSTATUS to stl->q_len
returns -1 or 0 returns -1 or 0
int (*version) (stlink_t *sl); int (*version) (stlink_t *sl);
_stlink_usb_version: Read version with STLINK_GET_VERSION. _stlink_usb_version: Read version with STLINK_GET_VERSION.
Result is stored in sl->q_buf (6 bytes????) Result is stored in sl->q_buf (6 bytes????)
returns -1 or 0 returns -1 or 0
int (*read_debug32) (stlink_t *sl, uint32_t addr, uint32_t *data); int (*read_debug32) (stlink_t *sl, uint32_t addr, uint32_t *data);
_stlink_usb_read_debug32: Send STLINK_JTAG_READDEBUG_32BIT _stlink_usb_read_debug32: Send STLINK_JTAG_READDEBUG_32BIT
to read 32 bits from "addr". The result data is stored at "*data". 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); int (*read_mem32) (stlink_t *sl, uint32_t addr, uint16_t len);
_stlink_usb_read_mem32: Use STLINK_DEBUG_READMEM_32BIT _stlink_usb_read_mem32: Use STLINK_DEBUG_READMEM_32BIT
to read "len" bytes from "addr" 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"???). equal to "len"???).
returns -1 or 0 returns -1 or 0
int (*write_debug32) (stlink_t *sl, uint32_t addr, uint32_t data); int (*write_debug32) (stlink_t *sl, uint32_t addr, uint32_t data);
_stlink_usb_write_debug32: Use STLINK_JTAG_WRITEDEBUG_32BIT _stlink_usb_write_debug32: Use STLINK_JTAG_WRITEDEBUG_32BIT
to store "data" at "addr" 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 _stlink_usb_read_all_regs: Send STLINK_DEBUG_READALLREGS to read
all register values and store them into *regp; all register values and store them into *regp;
returns -1 or 0 returns -1 or 0
int (*read_reg) (stlink_t *sl, int r_idx, struct stlink_reg * regp); 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". _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 Example if "r_idx" is 18, then the result is stored in regp->process_sp
returns -1 or 0 returns -1 or 0
int (*read_all_unsupported_regs) (stlink_t *sl, struct stlink_reg *regp); int (*read_all_unsupported_regs) (stlink_t *sl, struct stlink_reg *regp);
_stlink_usb_read_all_unsupported_regs: Calls "_stlink_usb_read_unsupported_reg" _stlink_usb_read_all_unsupported_regs: Calls "_stlink_usb_read_unsupported_reg"
(see below) to read all registers. (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. 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. WARNING: Some r_idx values may lead to a out of array bound problem in C.
returns -1 or 0 returns -1 or 0
int (*write_unsupported_reg) (stlink_t *sl, uint32_t value, int idx, struct stlink_reg *regp); int (*write_unsupported_reg) (stlink_t *sl, uint32_t value, int idx, struct stlink_reg *regp);
_stlink_usb_write_unsupported_reg: _stlink_usb_write_unsupported_reg:
Updates one of the following registers: 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 returns -1 or 0
int (*write_reg) (stlink_t *sl, uint32_t reg, int idx); 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". with value "reg".
returns -1 or 0 returns -1 or 0
int (*step) (stlink_t * stl); int (*step) (stlink_t * stl);
_stlink_usb_step: Send STLINK_DEBUG_STEPCORE _stlink_usb_step: Send STLINK_DEBUG_STEPCORE
returns -1 or 0 returns -1 or 0
int (*current_mode) (stlink_t * stl); int (*current_mode) (stlink_t * stl);
_stlink_usb_current_mode: Send STLINK_GET_CURRENT_MODE and return _stlink_usb_current_mode: Send STLINK_GET_CURRENT_MODE and return
the current mode. the current mode.
@ -174,15 +191,15 @@ int (*current_mode) (stlink_t * stl);
int (*force_debug) (stlink_t *sl); int (*force_debug) (stlink_t *sl);
_stlink_usb_force_debug: Sends STLINK_DEBUG_FORCEDEBUG. No other side effects _stlink_usb_force_debug: Sends STLINK_DEBUG_FORCEDEBUG. No other side effects
returns -1 or 0 returns -1 or 0
int32_t (*target_voltage) (stlink_t *sl); int32_t (*target_voltage) (stlink_t *sl);
_stlink_usb_target_voltage: Send STLINK_GET_TARGET_VOLTAGE _stlink_usb_target_voltage: Send STLINK_GET_TARGET_VOLTAGE
returns -1 or the target voltage. (??? dimension is not clear...) 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 _stlink_usb_set_swdclk: Send STLINK_DEBUG_APIV2_SWD_SET_FREQ and "divisor" value
returns -1 or 0 returns -1 or 0
=== Other Functions === === Other Functions ===
@ -193,17 +210,17 @@ Include: stlink.h
Prototype: void stlink_close(stlink_t *sl); Prototype: void stlink_close(stlink_t *sl);
Include: inc/stlink.h Include: inc/stlink.h
Definition: src/common.c Definition: src/common.c
Description: Description:
Calls the backend "close" procedure and frees 'sl' Calls the backend "close" procedure and frees 'sl'
Backend: "close" Backend: "close"
Arguments: Arguments:
sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb() sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
Return: - Return: -
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_core_id(stlink_t *sl); Prototype: int stlink_core_id(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
Calls the backend "core_id", calls stlink_print_data() on higher verbose levels. 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 Assigns the core id returned by STLINK_DEBUGREADCOREID to sl->core_id
Only some specific core ids are used: See include/stm32.h 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 Include: inc/stlink.h
Prototype: int stlink_reset(stlink_t *sl); Prototype: int stlink_reset(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
Just calls the backend "reset" procedure (reset via STLINK_DEBUG_RESETSYS Just calls the backend "reset" procedure (reset via STLINK_DEBUG_RESETSYS
and reset via AIRCR register at 0xE000ED0C) and reset via AIRCR register at 0xE000ED0C)
Backend: "reset" Backend: "reset"
Arguments: Arguments:
@ -227,29 +244,29 @@ Return: -1 for error. 0 for success.
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_jtag_reset(stlink_t *sl, int value); Prototype: int stlink_jtag_reset(stlink_t *sl, int value);
Definition: src/common.c Definition: src/common.c
Description: Description:
Just calls the backend "jtag_reset" procedure Just calls the backend "jtag_reset" procedure
Backend: "jtag_reset" Backend: "jtag_reset"
Arguments: Arguments:
sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb() sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
value: 0: drive low, 1: drive high, 2: ???? value: 0: drive low, 1: drive high, 2: ????
Return: -1 for error. 0 for success. Return: -1 for error. 0 for success.
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_run(stlink_t *sl); Prototype: int stlink_run(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
Just calls the backend "run" procedure. Just calls the backend "run" procedure.
Backend: "run" Backend: "run"
Arguments: Arguments:
sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb() sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
Return: -1 for error. 0 for success. Return: -1 for error. 0 for success.
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_status(stlink_t *sl); Prototype: int stlink_status(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
Calls the backend "status" procedure and the procedure "stlink_core_stat()" to 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: store the status in "sl->core_stat". Possible value for "sl->core_stat" are:
STLINK_CORE_RUNNING STLINK_CORE_RUNNING
@ -259,12 +276,12 @@ Backend: "status"
Arguments: Arguments:
sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb() sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
Return: -1 for error. 0 for success. Return: -1 for error. 0 for success.
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_version(stlink_t *sl); Prototype: int stlink_version(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
Calls the backend "version" procedure, parses the result and puts the result into sl->version 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. This version probably refers to the version of the adapter.
Backend: "version" Backend: "version"
@ -272,9 +289,9 @@ Arguments:
sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb() sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
Return: -1 for error. 0 for success. Return: -1 for error. 0 for success.
int stlink_read_debug32(stlink_t *sl, uint32_t addr, uint32_t *data); 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_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_mem32(stlink_t *sl, uint32_t addr, uint16_t len);
int stlink_write_mem8(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 Include: inc/stlink.h
Prototype: int stlink_chip_id(stlink_t *sl, uint32_t *chip_id); Prototype: int stlink_chip_id(stlink_t *sl, uint32_t *chip_id);
Definition: src/common.c Definition: src/common.c
Description: Description:
Tries to read out the chip id via memory read from the device. 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() Do not call this function, but instead call stlink_load_device_params()
Backend: - Backend: -
Arguments: Arguments:
@ -319,7 +336,7 @@ Return: -1 for error. 0 for success.
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_cpu_id(stlink_t *sl, cortex_m3_cpuid_t *cpuid); Prototype: int stlink_cpu_id(stlink_t *sl, cortex_m3_cpuid_t *cpuid);
Definition: src/common.c Definition: src/common.c
Description: Description:
Reads the CPU id from STLINK_REG_CM3_CPUID (0xE000ED00, first value of Reads the CPU id from STLINK_REG_CM3_CPUID (0xE000ED00, first value of
the SCB, system control block) and splits this into the SCB, system control block) and splits this into
cpuid->implementer_id cpuid->implementer_id
@ -333,19 +350,19 @@ Arguments:
cpuid: Pointer. Result is stored via this pointer. cpuid: Pointer. Result is stored via this pointer.
Return: -1 for error. 0 for success. Return: -1 for error. 0 for success.
int stlink_erase_flash_page(stlink_t* sl, stm32_addr_t flashaddr); int stlink_erase_flash_page(stlink_t* sl, stm32_addr_t flashaddr);
uint32_t stlink_calculate_pagesize(stlink_t *sl, uint32_t flashaddr); uint32_t stlink_calculate_pagesize(stlink_t *sl, uint32_t flashaddr);
uint16_t read_uint16(const unsigned char *c, const int pt); uint16_t read_uint16(const unsigned char *c, const int pt);
void stlink_core_stat(stlink_t *sl); void stlink_core_stat(stlink_t *sl);
Include: inc/stlink.h Include: inc/stlink.h
Prototype: void stlink_print_data(stlink_t *sl); Prototype: void stlink_print_data(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
If debug logging is enabled: Print the HEX content of the q_buf array. 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. q_buf will contain the result of the last "backend" command.
Backend: - 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_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 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); int stlink_fread(stlink_t* sl, const char* path, bool is_ihex, stm32_addr_t addr, size_t size);
Include: inc/stlink.h Include: inc/stlink.h
Prototype: int stlink_load_device_params(stlink_t *sl); Prototype: int stlink_load_device_params(stlink_t *sl);
Definition: src/common.c Definition: src/common.c
Description: Description:
This is one of the most important procedures. It will get all the device info 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 and store the results in the "sl" structure. Many other procedures will depend
on this information. 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: - Backend: -
Arguments: Arguments:
sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb() sl: Pointer to the stlink data structure, returned by stlink_v1_open() or stlink_open_usb()
Return: -1 for error. 0 for success. 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_f2(stlink_t *sl, uint32_t* option_byte);
int stlink_read_option_bytes_f4(stlink_t *sl, uint32_t* option_byte); int stlink_read_option_bytes_f4(stlink_t *sl, uint32_t* option_byte);