mirror of
https://github.com/avrdudes/avrdude.git
synced 2026-06-02 09:46:34 +03:00
Merge pull request #1916 from ndim/document-elf2tag
Document elf2tag script
This commit is contained in:
Stefan Rueger
18
.github/workflows/check-sourcecode.yml
vendored
18
.github/workflows/check-sourcecode.yml
vendored
@@ -22,3 +22,21 @@ jobs:
|
||||
|
||||
- name: "Check the sourcecode"
|
||||
run: ./tools/check-sourcecode
|
||||
|
||||
check-generated:
|
||||
name: "Check Generated Files"
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install prerequisites
|
||||
run: >-
|
||||
sudo apt-get update
|
||||
|
||||
sudo apt-get install -y
|
||||
asciidoctor
|
||||
|
||||
- name: "Verify elf2tag.1 consistency"
|
||||
run: ./src/update-elf2tag-manpage --verify
|
||||
|
||||
10
src/elf2tag
10
src/elf2tag
@@ -10,14 +10,16 @@ for pgm in sort grep awk avr-objdump avr-nm; do
|
||||
hash $pgm 2>/dev/null || { echo "$progname: $pgm does not seem to be installed, exiting"; exit 1; }
|
||||
done
|
||||
|
||||
if [ "$1" == "" ]; then
|
||||
cat <<END
|
||||
case "$1" in
|
||||
"" | -h | --help )
|
||||
cat <<END
|
||||
Syntax: $progname <file>.elf
|
||||
Function: output a tagfile suitable for the avrdude disasm -t=<tagfile> command
|
||||
Options: none
|
||||
END
|
||||
exit 1
|
||||
fi
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "# Automatically generated tagfile via ${progname} ${1}"
|
||||
avr-objdump -d "$1" | grep '<.*>:' | awk '{
|
||||
|
||||
62
src/elf2tag.1
Normal file
62
src/elf2tag.1
Normal file
@@ -0,0 +1,62 @@
|
||||
'\" t
|
||||
.\" Title: elf2tag
|
||||
.\" Author: [see the "AUTHOR(S)" section]
|
||||
.\" Generator: Asciidoctor 2.0.20
|
||||
.\" Date: 2024-11-23
|
||||
.\" Manual: avrdude Manual
|
||||
.\" Source: avrdude
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "ELF2TAG" "1" "2024-11-23" "avrdude" "avrdude Manual"
|
||||
.ie \n(.g .ds Aq \(aq
|
||||
.el .ds Aq '
|
||||
.ss \n[.ss] 0
|
||||
.nh
|
||||
.ad l
|
||||
.de URL
|
||||
\fI\\$2\fP <\\$1>\\$3
|
||||
..
|
||||
.als MTO URL
|
||||
.if \n[.g] \{\
|
||||
. mso www.tmac
|
||||
. am URL
|
||||
. ad l
|
||||
. .
|
||||
. am MTO
|
||||
. ad l
|
||||
. .
|
||||
. LINKSTYLE blue R < >
|
||||
.\}
|
||||
.SH "NAME"
|
||||
elf2tag \- output a tagfile for the avrdude disasm command
|
||||
.SH "SYNOPSIS"
|
||||
.sp
|
||||
\fBelf2tag\fP <file.elf>
|
||||
.sp
|
||||
\fBelf2tag\fP [\fB\-h\fP | \fB\-\-help\fP]
|
||||
.SH "DESCRIPTION"
|
||||
.sp
|
||||
\fIelf2tag\fP generates a tagfile for use with the \fIavrdude disasm\fP command.
|
||||
.SH "OPTIONS"
|
||||
.sp
|
||||
\fB\-h\fP \fB\-\-help\fP
|
||||
.RS 4
|
||||
Prints the help message and exits.
|
||||
.RE
|
||||
.SH "EXAMPLES"
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
.fam C
|
||||
$ elf2tag blink.elf > blink.tag
|
||||
$ avrdude \-qq \-c dryrun \-p m328p \-U blink.elf \-t
|
||||
avrdude> disasm \-t=blink.tag flash 0 512
|
||||
.fam
|
||||
.fi
|
||||
.if n .RE
|
||||
.SH "AUTHORS"
|
||||
.sp
|
||||
\fIelf2tag\fP was written by Johannes Bauer with small modifications by Stefan Rueger.
|
||||
.SH "SEE ALSO"
|
||||
.sp
|
||||
\fBavrdude(1)\fP, \fBavr\-nm(1)\fP, \fBavr\-objdump(1)\fP
|
||||
47
src/elf2tag.1.adoc
Normal file
47
src/elf2tag.1.adoc
Normal file
@@ -0,0 +1,47 @@
|
||||
ELF2TAG(1)
|
||||
==========
|
||||
:doctype: manpage
|
||||
:man source: avrdude
|
||||
:man manual: avrdude Manual
|
||||
|
||||
NAME
|
||||
----
|
||||
|
||||
elf2tag - output a tagfile for the avrdude disasm command
|
||||
|
||||
SYNOPSIS
|
||||
--------
|
||||
|
||||
*elf2tag* <file.elf>
|
||||
|
||||
*elf2tag* [*-h* | *--help*]
|
||||
|
||||
DESCRIPTION
|
||||
-----------
|
||||
|
||||
_elf2tag_ generates a tagfile for use with the _avrdude disasm_ command.
|
||||
|
||||
OPTIONS
|
||||
-------
|
||||
|
||||
*-h* *--help*::
|
||||
Prints the help message and exits.
|
||||
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
....
|
||||
$ elf2tag blink.elf > blink.tag
|
||||
$ avrdude -qq -c dryrun -p m328p -U blink.elf -t
|
||||
avrdude> disasm -t=blink.tag flash 0 512
|
||||
....
|
||||
|
||||
AUTHORS
|
||||
-------
|
||||
|
||||
_elf2tag_ was written by Johannes Bauer with small modifications by Stefan Rueger.
|
||||
|
||||
SEE ALSO
|
||||
--------
|
||||
|
||||
*avrdude(1)*, *avr-nm(1)*, *avr-objdump(1)*
|
||||
140
src/update-elf2tag-manpage
Executable file
140
src/update-elf2tag-manpage
Executable file
@@ -0,0 +1,140 @@
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# update-elf2tag-manpage - update the elf2tag.1 manpage from adoc source
|
||||
#
|
||||
# Usage:
|
||||
# ./path/to/update-elf2tag-manpage
|
||||
# ./path/to/update-elf2tag-manpage --verify
|
||||
#
|
||||
# Without a command line argument given, changes into the directory
|
||||
# where update-elf2tag-manpage and elf2tag.1.adoc are, runs
|
||||
# asciidoctor to produce a man page elf2tag.1 from elf2tag.1.adoc, but
|
||||
# only updates the elf2tag.1 file in the case of actual changes.
|
||||
#
|
||||
# Just the asciidoctor version or the current date being different
|
||||
# from the last asciidoctor run is not considered an actual change.
|
||||
#
|
||||
# With the --verify argument given, only verify that elf2tag.1 and
|
||||
# elf2tag.1.adoc are consistent with each other, i.e. elf2tag.1 would
|
||||
# not be changed.
|
||||
#
|
||||
# Requires asciidoctor to be installed.
|
||||
#
|
||||
# Environment variables used (if unset, uses the command from PATH):
|
||||
# ASCIIDOCTOR the asciidoctor command to run
|
||||
# CMP the cmp command to run (e.g. "busybox cmp")
|
||||
# DIFF the diff command to run with -u (used with --verify only)
|
||||
# SED the sed command to run (e.g. "busybox sed")
|
||||
|
||||
# This script uses the shell feature called "process substitution" which
|
||||
# is implemented by bash and busybox sh, but not by e.g. dash and can
|
||||
# therefore not be a /bin/sh script.
|
||||
|
||||
set -e
|
||||
|
||||
prog="$(basename "$0")"
|
||||
|
||||
if test "$#" -gt 1; then
|
||||
echo "$prog: Too many command line arguments"
|
||||
exit 2
|
||||
fi
|
||||
|
||||
verify=false
|
||||
if test "$#" -eq 1; then
|
||||
case "$1" in
|
||||
-h | --help )
|
||||
${SED-sed} -n '/^#\( .*\)$/,$p' "$0" \
|
||||
| ${SED-sed} '/^#\( .*\)\?$/!q' \
|
||||
| ${SED-sed} '/^$/d' \
|
||||
| ${SED-sed} 's|^#$||; s|^# ||'
|
||||
exit 0
|
||||
;;
|
||||
--verify )
|
||||
verify=:
|
||||
;;
|
||||
* )
|
||||
echo "$prog: Unhandled command line argument."
|
||||
exit 2
|
||||
;;
|
||||
esac
|
||||
fi
|
||||
|
||||
cd "$(dirname "$0")"
|
||||
|
||||
test -s elf2tag.1.adoc
|
||||
test -s elf2tag
|
||||
|
||||
# Usage: normalize_manpage original.1 normalized.1
|
||||
#
|
||||
# Normalizes a man page generated by asciidoctor by replacing data not
|
||||
# present in the sources such as generation date, asciidoctor version.
|
||||
normalize_manpage() {
|
||||
${SED-sed} -f <(cat<<EOF
|
||||
#s|^\.\\\\|==TITLE==|
|
||||
s|^\.\\\\" Generator: Asciidoctor .*|.\\" Generator: GENERATOR|
|
||||
s|^\.\\\\" Date: 20[0-9][0-9]-[0-1][0-9]-[0-3][0-9]|.\\" Date: DATE|
|
||||
s|^\.TH "ELF2TAG" "1" "20[0-9][0-9]-[0-1][0-9]-[0-3][0-9]" "avrdude" "avrdude Manual"|\.\\" TH HEADER|
|
||||
EOF
|
||||
) < "$1" > "$2"
|
||||
}
|
||||
|
||||
tmpdir="tmp$$"
|
||||
|
||||
if ! ${ASCIIDOCTOR-asciidoctor} -b manpage -D "$tmpdir" elf2tag.1.adoc; then
|
||||
echo "$prog: Error updating elf2tag.1"
|
||||
rm -rf "$tmpdir"
|
||||
exit 2
|
||||
fi
|
||||
|
||||
# Have sed ensure a trailing newline character by appending empty string
|
||||
#
|
||||
# This is necessary as asciidoctor likes to create files without a
|
||||
# trailing newline, while it is good form for text editors to add one.
|
||||
if ${SED-sed} '$a\' < "$tmpdir/elf2tag.1" > "$tmpdir/elf2tag.1.newline"; then
|
||||
mv -f "$tmpdir/elf2tag.1.newline" "$tmpdir/elf2tag.1"
|
||||
else
|
||||
echo "$prog: Error ensuring trailing newline character"
|
||||
rm -rf "$tmpdir"
|
||||
exit 2
|
||||
fi
|
||||
|
||||
if ! test -e elf2tag.1; then
|
||||
if "$verify"; then
|
||||
echo "$prog: Cannot ensure consistency if there is no old elf2tag.1 file"
|
||||
rm -rf "$tmpdir"
|
||||
exit 1
|
||||
fi
|
||||
echo "$prog: Generate elf2tag.1"
|
||||
mv -f "$tmpdir/elf2tag.1" elf2tag.1
|
||||
rmdir "$tmpdir"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
normalize_manpage elf2tag.1 "$tmpdir/elf2tag.1.norm-old"
|
||||
normalize_manpage "$tmpdir/elf2tag.1" "$tmpdir/elf2tag.1.norm-new"
|
||||
|
||||
if ${CMP-cmp} "$tmpdir/elf2tag.1.norm-old" "$tmpdir/elf2tag.1.norm-new" > /dev/null; then
|
||||
echo "$prog: elf2tag.1 is up to date"
|
||||
rm -f "$tmpdir/elf2tag.1"
|
||||
rm -f "$tmpdir/elf2tag.1.norm-old"
|
||||
rm -f "$tmpdir/elf2tag.1.norm-new"
|
||||
rmdir "$tmpdir"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if "$verify"; then
|
||||
echo "$prog: Error: src/elf2tag.1 is inconsistent with src/elf2tag.1.adoc"
|
||||
${DIFF-diff} -u "$tmpdir/elf2tag.1.norm-old" "$tmpdir/elf2tag.1.norm-new" ||:
|
||||
rm -f "$tmpdir/elf2tag.1"
|
||||
rm -f "$tmpdir/elf2tag.1.norm-old"
|
||||
rm -f "$tmpdir/elf2tag.1.norm-new"
|
||||
rmdir "$tmpdir"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Updating elf2tag.1"
|
||||
mv -f "$tmpdir/elf2tag.1" elf2tag.1
|
||||
rm -f "$tmpdir/elf2tag.1.norm-old"
|
||||
rm -f "$tmpdir/elf2tag.1.norm-new"
|
||||
rmdir "$tmpdir"
|
||||
exit 0
|
||||
Reference in New Issue
Block a user