From 15edf26d7585a2147a9794da1cac000d60e8d3cf Mon Sep 17 00:00:00 2001
From: Simon Rettberg
Date: Wed, 7 Oct 2020 12:32:24 +0200
Subject: [dev] Add comments

---
 modules/dev.inc | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

(limited to 'modules/dev.inc')

diff --git a/modules/dev.inc b/modules/dev.inc
index 6080af6..1ac57d3 100644
--- a/modules/dev.inc
+++ b/modules/dev.inc
@@ -40,7 +40,7 @@ dev_find_partitions() {
 	done
 	local label number mbrid uuid
 	for dev in $(find $target* -type b); do
-		dev_get_type "$dev"
+		dev_get_type "$dev" || continue
 		if regex_imatch "$mbrid" "^($want_type)$" || regex_imatch "$uuid" "^($want_uuid)$" \
 				|| regex_match "$label" "^($want_label)$"; then
 			printf "%s\n" "$(blockdev --getsize64 "$dev") $dev"
@@ -48,6 +48,11 @@ dev_find_partitions() {
 	done | sort -n -k1 -r | cut -d' ' -f2
 }
 
+# Pass partition block device. If it could be identified successfully,
+# fills the variables number, mbrid, uuid, label, depending on MBR/GPT.
+# Otherwise, return code is != 0 and contents are undefined.
+# This only makes sense if called within this script, or if slx-tools
+# was sourced, otherwise the variables will be inaccessible.
 dev_get_type() {
 	local part dev partn devn pstart
 	dev=
@@ -115,7 +120,7 @@ dev_get_type() {
 					current="$(( next_start + ex_start ))"
 					no="$(( no + 1 ))"
 				else
-					no=0
+					return 1 # End of linked list
 				fi
 			done
 		fi
@@ -137,24 +142,35 @@ dev_get_type() {
 			echo "Found partition $number, but start mismatch (want: $pstart found: $log_start)" >&2
 			return 1
 		fi
-		uuid="$( dd if="$dev" bs=1 count=16 skip="$(( current + entry_size * (number - 1) ))" 2> /dev/null | xxd -p \
-			| sed -r 's/^(..)(..)(..)(..)(..)(..)(..)(..)(....)/\4\3\2\1-\6\5-\8\7-\9-/' )"
+		# Convert raw hex stream to proper string representation. First 3 groups are little endian.
+		uuid="$( dd if="$dev" bs=1 count=16 skip="$(( current + entry_size * (number - 1) ))" 2> /dev/null \
+			| xxd -p | sed -r 's/^(..)(..)(..)(..)(..)(..)(..)(..)(....)/\4\3\2\1-\6\5-\8\7-\9-/' )"
 		return 0
 	fi
+	# Unknown
+	return 1
 }
 
+# Get MBR type of partition (1 byte) as hex
+# Pass "$device" "$lba_offset" "$partition_number"
 __read_mbrid() {
 	dd if="$1" bs=1 skip=$(( 512 * $2 + 446 + ($3 - 1) * 16 + 4 )) count=1 2> /dev/null | xxd -p
 }
 
+# Get LBA start address of MBR partition
+# Pass "$device" "$lba_offset" "$partition_number"
 __read_mbrstart() {
 	__read_le "$1" "$(( 512 * $2 + 446 + ($3 - 1) * 16 + 8 ))" 4
 }
 
+# Read the MBR signature in the given sector
+# Pass "$device" "$lba_offset"
 __read_mbrsig() {
 	dd if="$1" bs=1 skip=$(( 512 * $2 + 510 )) count=2 2> /dev/null | xxd -p
 }
 
+# Read a little endian value at given byte offset
+# Pass "$source_path" "$byte_offset" "$size"
 __read_le() {
 	local v="$( dd if="$1" bs=1 count="$3" skip="$2" 2> /dev/null | xxd -e -g "$3" | cut -d' ' -f2 )"
 	echo $(( 0x$v ))
-- 
cgit v1.2.3-55-g7522