Add man page

This commit is contained in:
Mario Hüttel 2022-10-25 18:17:54 +02:00
parent 7e56af08bf
commit c033ec7206
7 changed files with 138 additions and 10 deletions

View File

@ -8,7 +8,7 @@ arch=('i686' 'x86_64')
url="https://git.shimatta.de/mhu/patchelfcrc" url="https://git.shimatta.de/mhu/patchelfcrc"
licence=('GPLv2') licence=('GPLv2')
depends=('libelf') depends=('libelf')
makedepends=('cmake' 'git') makedepends=('cmake' 'pandoc' 'git')
provides=('patchelfcrc') provides=('patchelfcrc')
source=("${pkgname}-git"::"git+https://git.shimatta.de/mhu/patchelfcrc" "git+https://git.shimatta.de/3rd-party/libfort.git" "git+https://git.shimatta.de/mhu/linklist-lib") source=("${pkgname}-git"::"git+https://git.shimatta.de/mhu/patchelfcrc" "git+https://git.shimatta.de/3rd-party/libfort.git" "git+https://git.shimatta.de/mhu/linklist-lib")
sha1sums=('SKIP' 'SKIP' 'SKIP') sha1sums=('SKIP' 'SKIP' 'SKIP')
@ -36,4 +36,5 @@ prepare () {
package () { package () {
install -Dm755 "$srcdir/$pkgname-git/build/patchelfcrc" "$pkgdir/usr/bin/patchelfcrc" install -Dm755 "$srcdir/$pkgname-git/build/patchelfcrc" "$pkgdir/usr/bin/patchelfcrc"
install -Dm644 "$srcdir/$pkgname-git/build/man/patchelfcrc.1.gz" "$pkgdir/use/share/man/man1/patchelfcrc.1.gz"
} }

View File

@ -27,6 +27,8 @@ pkg_check_modules(ELF REQUIRED libelf)
find_package(Doxygen) find_package(Doxygen)
add_subdirectory(man)
aux_source_directory("src" CFILES) aux_source_directory("src" CFILES)
set(GEN_HEADER_PATH "${CMAKE_CURRENT_BINARY_DIR}/include/generated") set(GEN_HEADER_PATH "${CMAKE_CURRENT_BINARY_DIR}/include/generated")

View File

@ -2556,7 +2556,7 @@ DOT_IMAGE_FORMAT = svg
# The default value is: NO. # The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES. # This tag requires that the tag HAVE_DOT is set to YES.
INTERACTIVE_SVG = YES INTERACTIVE_SVG = NO
# The DOT_PATH tag can be used to specify the path where the dot tool can be # The DOT_PATH tag can be used to specify the path where the dot tool can be
# found. If left blank, it is assumed the dot tool can be found in the path. # found. If left blank, it is assumed the dot tool can be found in the path.

19
man/CMakeLists.txt Normal file
View File

@ -0,0 +1,19 @@
set (MAN_PAGE_NAME "patchelfcrc.1.gz")
add_custom_target(man-page
ALL
DEPENDS
${CMAKE_CURRENT_BINARY_DIR}/${MAN_PAGE_NAME}
)
add_custom_command(
OUTPUT
${CMAKE_CURRENT_BINARY_DIR}/${MAN_PAGE_NAME}
COMMAND
bash -c "pandoc \"${CMAKE_CURRENT_SOURCE_DIR}/patchelfcrc.1.md\" -s -t man | gzip > \"${CMAKE_CURRENT_BINARY_DIR}/${MAN_PAGE_NAME}\""
VERBATIM
WORKING_DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}
MAIN_DEPENDENCY
${CMAKE_CURRENT_SOURCE_DIR}/patchelfcrc.1.md
)

View File

@ -3,13 +3,20 @@
% October 2022 % October 2022
# NAME # NAME
patchelfcrc - Patch CRC checksums into ELF files **patchelfcrc** - Patch CRC checksums into ELF files
# SYNOPSYS # SYNOPSYS
**patchelfcrc** [*OPTIONS*] *ELFFILE* **patchelfcrc** [**-lrv?V**] [**-g** *GRANULARITY*] [**-p** *POLYNOMIAL*] [**-s** *STARTVALUE*]
[**-x** *XORVAL*] [**-F** *FORMAT*] [**-O** *OUTPUTSECTION*] [**-S** *SEC*]
[**\--granularity**=*GRANULARITY*] [**\--little-endian**] [**\--dry-run**]
[**\--poly**=*POLYNOMIAL*] [**\--reversed**] [**\--start-value**=*STARTVALUE*]
[**--verbose**] [**\--xor-out**=*XORVAL*] [**\--end-magic**=*MAGIC*]
[**\--crc-format**=*FORMAT*] [**\--list-crcs**] [**\--output-section**=*OUTPUTSECTION*]
[**\--start-magic**=*MAGIC*] [**\--section**=*SECTION*] [**\--help**] [**\--usage**]
[**\--version**] *ELF*
# DESCRIPTION # DESCRIPTION
**patchelfcrc** reads in sections of an *ELFFILE* and computes CRC checksums over the data. The calculated CRCs are placed in an output section of the *ELFFILE*. The output section must already exist inside the *ELFFILE* and must be big enough to hold all generated CRC checksums. **patchelfcrc** reads in sections of an *ELF* file and computes CRC checksums over the data. The calculated CRCs are placed in an output section of the *ELFFILE*. The output section must already exist inside the *ELF* file and must be big enough to hold all generated CRC checksums.
**patchelfcrc** supports multiple predefined CRCs as well as custom polynomials. **patchelfcrc** supports multiple predefined CRCs as well as custom polynomials.
@ -20,6 +27,18 @@ patchelfcrc - Patch CRC checksums into ELF files
**\--usage** **\--usage**
: Display usage information : Display usage information
**-p** *POLYNOMIAL*, **\--polynomial**=*POLYNOMIAL*
: Polynomial to use for CRC calculation. For a n bit wide CRC supply a number with n+1 bits and the MSB set. Alternatively, a predifined name can be supplied. See **\--list-crcs** for details. At maximum a 32 bit wide CRC can be calculated. If nothing is given, crc-32-mpeg is used.
**-s** *STARTVALUE*, **\--start-value**=*STARTVALUE*
: Start value to preload CRC register with. This value is XORed with the *XORVAL* (see option **-x**).
**-x** *XORVAL*, **\--xor-value**=*XORVAL*
: XOR Value applied to initial start value (**-s**) and to the final CRC result.
**-r**, **\--reversed**
: Use bitreversed CRC. This is not implemented yet!
**-g** *GRANULARITY*, **\--granularity**=*GRANULARITY* **-g** *GRANULARITY*, **\--granularity**=*GRANULARITY*
: CRC calculation granularity. This has no effect if big endian layout is used. For little endian layout, it specifies the sizes of the individual elements the CRC is computed over. : CRC calculation granularity. This has no effect if big endian layout is used. For little endian layout, it specifies the sizes of the individual elements the CRC is computed over.
@ -28,8 +47,77 @@ patchelfcrc - Patch CRC checksums into ELF files
**-l**, **\--little-endian** **-l**, **\--little-endian**
: The memory layout of the *ELFFILE* is in little-endian format. : The memory layout of the *ELFFILE* is in little-endian format.
**-F** *FORMAT*, **\--crc-format**=*FORMAT*
: Output format to place in output section. Options for *FORMAT* are *bare* or *struct*
**--start-magic**=*MAGIC*, **--endmagic**=*MAGIC* **--start-magic**=*MAGIC*, **--endmagic**=*MAGIC*
: *MAGIC* numbers (32 bit unsigned) that are expected to be found at the start and the end of the given output section. This serves as safety guard against accidental corruption of the output file. *It is highly recommended to use these options*. : *MAGIC* numbers (32 bit unsigned) that are expected to be found at the start and the end of the given output section. This serves as safety guard against accidental corruption of the output file. *It is highly recommended to use these options*.
**--help**, **-h**, **-?**
: Print help.
**\--dry-run**
: Dry run. Do all calculations but do not write changes to file. *ELF* file will only be opened readonly. This mode implicitly activates the verbose output
**-v**, **\--verbose**
: Activate verbose output
**-V**, **\--version**
: Print version number
**--usage**
: Print usage hints on command line options.
# EXAMPLES
**patchelfcrc** --list-crcs
| Name | Polynomial | Reversed | Start Value | Output XOR |
|------------------|-------------|----------|-------------|------------|
| crc-8 | 0x107 | no | 0x0 | 0x0 |
| crc-8-darc | 0x139 | yes | 0x0 | 0x0 |
| crc-8-i-code | 0x11d | no | 0xfd | 0x0 |
| crc-8-itu | 0x107 | no | 0x55 | 0x55 |
| crc-8-maxim | 0x131 | yes | 0x0 | 0x0 |
| crc-8-rohc | 0x107 | yes | 0xff | 0x0 |
| crc-8-wcdma | 0x19b | yes | 0x0 | 0x0 |
| crc-16 | 0x18005 | yes | 0x0 | 0x0 |
| crc-16-buypass | 0x18005 | no | 0x0 | 0x0 |
| crc-16-dds-110 | 0x18005 | no | 0x800d | 0x0 |
| crc-16-dect | 0x10589 | no | 0x1 | 0x1 |
| crc-16-dnp | 0x13d65 | yes | 0xffff | 0xffff |
| crc-16-en-13757 | 0x13d65 | no | 0xffff | 0xffff |
| crc-16-genibus | 0x11021 | no | 0x0 | 0xffff |
| crc-16-maxim | 0x18005 | yes | 0xffff | 0xffff |
| crc-16-mcrf4xx | 0x11021 | yes | 0xffff | 0x0 |
| crc-16-riello | 0x11021 | yes | 0x554d | 0x0 |
| crc-16-t10-dif | 0x18bb7 | no | 0x0 | 0x0 |
| crc-16-teledisk | 0x1a097 | no | 0x0 | 0x0 |
| crc-16-usb | 0x18005 | yes | 0x0 | 0xffff |
| x-25 | 0x11021 | yes | 0x0 | 0xffff |
| xmodem | 0x11021 | no | 0x0 | 0x0 |
| modbus | 0x18005 | yes | 0xffff | 0x0 |
| kermit | 0x11021 | yes | 0x0 | 0x0 |
| crc-ccitt-false | 0x11021 | no | 0xffff | 0x0 |
| crc-aug-ccitt | 0x11021 | no | 0x1d0f | 0x0 |
| crc-24 | 0x1864cfb | no | 0xb704ce | 0x0 |
| crc-24-flexray-a | 0x15d6dcb | no | 0xfedcba | 0x0 |
| crc-24-flexray-b | 0x15d6dcb | no | 0xabcdef | 0x0 |
| crc-32 | 0x104c11db7 | yes | 0x0 | 0xffffffff |
| crc-32-bzip2 | 0x104c11db7 | no | 0x0 | 0xffffffff |
| crc-32c | 0x11edc6f41 | yes | 0x0 | 0xffffffff |
| crc-32d | 0x1a833982b | yes | 0x0 | 0xffffffff |
| crc-32-mpeg | 0x104c11db7 | no | 0xffffffff | 0x0 |
| posix | 0x104c11db7 | no | 0xffffffff | 0xffffffff |
| crc-32q | 0x1814141ab | no | 0x0 | 0x0 |
| jamcrc | 0x104c11db7 | yes | 0xffffffff | 0x0 |
| xfer | 0x1000000af | no | 0x0 | 0x0 |
**patchelfcrc** -l -g word --start-magic=0x12345678 --end-magic=0x8754321 -p crc-32-mpeg -f bare -O .outputsection -S .text executable.elf
: Calculate the CRC over *.text* section and place the result in the *.outputsection* section.
The output sections start and end are checked for the given magic numbers in order to assure correct memory layout.
*CRC-32-MPEG* is used as CRC algorothm.
The memory is interpreted as *little endian* and the CRC calculation granularity is a 32 bit *word*.
# BUGS # BUGS
Currently, reversed CRC algorithms are not implemented. Currently, reversed CRC algorithms are not implemented.

View File

@ -1,3 +1,21 @@
/*
* This file is part of patchelfcrc.
* Copyright (c) 2022 Mario Hüttel.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, version 2 only.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <patchelfcrc/elfpatch.h> #include <patchelfcrc/elfpatch.h>
#include <patchelfcrc/reporting.h> #include <patchelfcrc/reporting.h>
#include <unistd.h> #include <unistd.h>

View File

@ -373,6 +373,11 @@ int main(int argc, char **argv)
reporting_enable_verbose(); reporting_enable_verbose();
print_verbose_start_info(&cmd_opts); print_verbose_start_info(&cmd_opts);
if (cmd_opts.list) {
list_predefined_crcs();
goto free_cmds;
}
/* Check if file has been supplied */ /* Check if file has been supplied */
if (!cmd_opts.elf_path) { if (!cmd_opts.elf_path) {
print_err("No ELF file specified. Exiting...\n"); print_err("No ELF file specified. Exiting...\n");
@ -383,11 +388,6 @@ int main(int argc, char **argv)
print_err("No output section specified. Will continue but not patch file.\n"); print_err("No output section specified. Will continue but not patch file.\n");
} }
if (cmd_opts.list) {
list_predefined_crcs();
goto free_cmds;
}
/* Do error printing if using a reversed polynomial. It is not implemented yet! */ /* Do error printing if using a reversed polynomial. It is not implemented yet! */
if (cmd_opts.crc.rev) { if (cmd_opts.crc.rev) {
print_err("Reversed polynomials are not supported yet\nExiting...\n"); print_err("Reversed polynomials are not supported yet\nExiting...\n");