[PATCH v2 4/5] CRC64 commands documentation

[binutils@emagii.com]

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