[PATCH v2 4/5] CRC64 commands documentation
binutils@emagii.com
binutils@emagii.com
Fri Feb 17 17:40:36 GMT 2023
From: Ulf Samuelsson <binutils@emagii.com>
* LIBCRC license
* NEWS
* ls.texi
Signed-off-by: Ulf Samuelsson <binutils@emagii.com>
---
COPYING.CRC64 | 42 +++++++++++++++++++++++
ld/NEWS | 29 ++++++++++++++++
ld/ld.texi | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 163 insertions(+)
create mode 100755 COPYING.CRC64
diff --git a/COPYING.CRC64 b/COPYING.CRC64
new file mode 100755
index 00000000000..618e1c63dae
--- /dev/null
+++ b/COPYING.CRC64
@@ -0,0 +1,42 @@
+The GNU linker contains CRC routines that are used to implement the
+CRC64 command in the output section.
+
+The CRC routines are extracted from LIBCRC available at
+
+They are used to
+* https://www.libcrc.org/
+* https://github.com/lammertb/libcrc/tree/v2.0
+
+
+/*
+ * Library: libcrc
+ * File: src/crc64.c
+ * Author: Lammert Bies
+ *
+ * This file is licensed under the MIT License as stated below
+ *
+ * Copyright (c) 2016 Lammert Bies
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * Description
+ * -----------
+ * The source file src/crc64.c contains the routines which are needed to
+ * calculate a 64 bit CRC value of a sequence of bytes.
+ */
diff --git a/ld/NEWS b/ld/NEWS
index 4b91f2c3b0a..a3203d53035 100644
--- a/ld/NEWS
+++ b/ld/NEWS
@@ -1,5 +1,34 @@
-*- text -*-
+* The linker script syntax has new commands for handling CRC-64 calculations
+ on the '.text' section
+ It uses code from https://www.libcrc.org/
+
+ CRC64 ECMA (start, end)
+ CRC64 ISO (start, end)
+ CRC64 POLY(polynome) (start, end)
+ CRC64 POLYI(polynome)(start, end) (inversion during CRC calculation)
+ CRC64 TABLE
+
+ The ECMA, ISO, POLY, POLYI defines the polynome to use
+ and reserves space for the 64-bit CRC in the '.text' section.
+ The default polynome is the ECMA.
+
+ The CRC64 <polynome> command defines some global symbols.
+ ___CRC64___ is the address of the CRC64 checksum
+ ___CRC64_START___ is the address where CRC calculation starts
+ ___CRC64_END___ The CRC calculation ends before this address.
+ All three symbols must refer to addresses in the '.text' section.
+ If they are defined at the end of the linking process, then
+ the CRC64 will be calculated between ___CRC64_START___ .. ___CRC64_END___ -1
+ and the result will be inserted at ___CRC64___.
+
+ The CRC64 TABLE command generates a table for CRC generation.
+ This is not neccessary, but will speed up the calculation
+ and makes it compatible with the CRC check routines at https://www.libcrc.org/
+ It defines the ___CRC64_TABLE___ symbol at the start of the table.
+ The user may choose to add this table to his code instead of using the linker.
+
* The linker script syntax has two new commands for inserting text into output
sections:
ASCII (<size>) "string"
diff --git a/ld/ld.texi b/ld/ld.texi
index 7802f0661b0..ee5eb98a951 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -5394,6 +5394,98 @@ area:
ASCIZ "This is 16 bytes"
@end smallexample
+@cindex output section strings
+@kindex CRC64 ECMA (@var{expression}, @var{expression})
+@kindex CRC64 ISO (@var{expression}, @var{expression})
+@kindex CRC64 POLY (@var{expression})(@var{expression}, @var{expression})
+@kindex CRC64 POLYI (@var{expression})(@var{expression}, @var{expression})
+
+You can calculate the CRC of a part of the '.text' section through the
+@code{CRC64} commands. The commands take a parameter for the @code{polynome}
+and then two more, specifying range of the checked area. The end address is
+the first address past the checked area.
+
+There are two predefined polynomes
+
+* @code{ECMA} @code{0x42F0E1EBA9EA3693}
+
+* @code{ISO} @code{0xD800000000000000}
+
+You can also select your own @code{polynome} using the @code{CRC64 POLY} or
+@code{CRC64 POLYI}. The @code{POLYI} will invert the polynome before and after
+the calculation which is neccessary for the @code{CRC64-WE} algorithm
+
+The default polynome is the @code{ECMA}
+
+The CRC64 <polynome> command defines some global symbols.
+
+* @code{___CRC64___} address of the CRC64 checksum
+
+* @code{___CRC64_START___} first address in the checked area.
+
+* @code{___CRC64_END___} first address past the checked area.
+
+Note: The generated CRC value must be stored outside the checked area.
+
+Example 1: This request a CRC check using the @code{ECMA} algorithm
+
+@smallexample
+ CRC = '.';
+ CRC65 ECMA (START_CHECK,END_TEXT)
+ START_CHECK = '.';
+@end smallexample
+
+The user can retrieve the CRC value through the @code{CRC} label.
+
+Example 2: This request a CRC check using the @code{ISO} algorithm
+
+@smallexample
+ CRC = '.';
+ CRC64 ISO (START_CHECK,END_TEXT)
+ START_CHECK = '.';
+@end smallexample
+
+The user can retrieve the CRC value through the @code{CRC} label.
+
+Example 3: This request a CRC check using a user defined @code{polynome}
+
+@smallexample
+ CRC = '.';
+ CRC64 POLY (0xDEADBEEFDEADBEEF) (START_CHECK,END_TEXT)
+ START_CHECK = '.';
+@end smallexample
+
+The user can retrieve the CRC value through the @code{CRC} label.
+
+Example 4: This request a CRC check using a user defined @code{polynome}
+ The @code{polynome} is inverted before use, and teh result is inverted.
+
+@smallexample
+ CRC = '.';
+ CRC64 POLYI (0xDEADBEEFDEADBEEF) (START_CHECK,END_TEXT)
+ START_CHECK = '.';
+@end smallexample
+
+The user can retrieve the CRC value through the @code{CRC} label.
+
+@cindex output section strings
+@kindex CRC64 TABLE
+
+The @code{CRC64 TABLE} command creates a 2 kByte table for a table-driven
+CRC calculation. This speeds up the CRC calculation over a non-table-driver
+version since you can handle 8 bits at a time, instead of 1 bit.
+
+The table generated is for the @code{polynome} selected using a @code{CRC64}
+command. If no @code{CRC64} command has been emitted, the @code{ECMA} is used.
+
+Example 1: Generate a 2 kB table
+@smallexample
+ mytable = '.';
+ CRC64 TABLE
+@end smallexample
+
+The use can declare @code{extern uint64_t *mytable;} in his code to use it.
+
@kindex FILL(@var{expression})
@cindex holes, filling
@cindex unspecified memory
--
2.17.1
More information about the Binutils
mailing list