| Name | crc-tool JSON |
| Version |
1.2.3.4
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2024-09-18 10:16:53 |
| maintainer | None |
| docs_url | None |
| author | Texas Instruments |
| requires_python | None |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CRC tool
The crc_tool have been created by Texas Instruments to support the need to calculate CRC values of specific flash regions during the build process. The calculated CRC values will be inserted in the ELF file. This was introduced to support the device families CC23xx and CC27xx.
crc_tool is a tool with two primary use cases:
1. To input an ELF file, parse begin and end of section through symbols originally defined in the linker file, and add crc after the end address, as defined by these symbols.
* This is Intended to be used as a post build step in CCS to add CRCs to the generated ELF file
2. To parse a txt file, containing one or more hexadecimal values, calculate the crc of this value, and generate a binary file containing hex data and crc.
* This is intended to be given as input to a SACI command for programming the user record in the ccfg.
## Dependencies
The Python script relies on the external library [LIEF](https://pypi.org/project/lief/0.8.3/)
This libary is included in the packaged executable.
## Use case 1 - Adding CRC to ELF file
This use case is accessed through using the subcommand ``patch-image`` when invoking ``crc_tool``.
This use case will:
1. Parse symbols with a given prefix from the stated ELF file.
2. Use these symbols and their values to find sections to calculate CRC for.
3. Insert CRCs in the next four bytes after the given end of the region.
4. Write this new ELF file to disk.
You then need to specify the location of an input file on disk.
Currently the tool has only been tested with ELF files.
Other file types may be added in the future.
The following command line options are available in the ``patch-image`` use-case.
| Name | Usage | Required? | Default |
| ------------------------------------ | ------------------------------------------------- | --------- | -------------------- |
| ``--elf {file location}`` | Specify location of input file | Yes | N/A |
| ``-p {prefix} / --symbol-prefix {prefix}`` | Specify prefix of begin / end symbols in ELF file | no | ``__crc_section`` |
| ``-o {file_name} / --ouput {file_name}`` | Specify name of output file | No | ``patched.out`` |
| ``--verbose`` | Output all available logging information | No | N/A
| ``--quiet`` | Output no logging information, only fatal errors | No | N/A
### Required modifications:
For ``crc_tool`` to know where to insert crc32 values
it needs to be able to find symbols in the ELF file which matches the stated
prefix. All symbols without a matching prefix are ignored.
Symbols need to come in pairs with matching names, except for ``_end``, and ``_begin`` suffixes.
Symbols without a suffix, or without a matching counterpart are ignored..
If you have the _end values of two sections which within the same 4 byte range,
meaning that they would overwrite eachother's CRCs, then an error is thrown.
The value of the _end symbol must be greater or equal to the _begin value, otherwise
an error is thrown.
In a ticlang linker file symbols can be added like so
(Note the prefix differing from above default value):
```c
__my_prefix_boot_cfg_begin = 0x4E020000;
__my_prefix_boot_cfg_end = 0x4E02000B;
__my_prefix_main_begin = 0x4E020010;
__my_prefix_main_end = 0x4E02074B;
__my_prefix_user_record_crc32_begin = 0x4E020750;
__my_prefix_user_record_crc32_end = 0x4E0207CB;
__my_prefix_debug_cfg_crc32_begin = 0x4E0207D0;
__my_prefix_debug_cfg_crc32_end = 0x4E0207FB;
```
The following example lists **invalid** symbols, all of these will be ignored:
```c
// Ignored because no corresponding _end value
__my_prefix_boot_cfg_begin = 0x4E020000;
// Ignored because of invalid suffix
__my_prefix_main_be = 0x4E020010;
__my_prefix_main_en = 0x4E02074B;
// Ignored because no corresponding _begin value
__my_prefix_user_record_crc32_end = 0x4E020750;
// Ignored because of no valid prefix (assuming __my_prefix is used)
debug_cfg_crc32_begin = 0x4E0207D0;
debug_cfg_crc32_end = 0x4E0207FB;
```
The following example lists **invalid** symbols, all of the following will cause
the program to throw an error.
```c
// Throw error because end is before beginning
__my_prefix_main_begin = 0x4E020010;
__my_prefix_main_end = 0x4E020000;
// Throws error because overlap1 and overlap2 would overwrite eachother's CRCs
__my_prefix_overlap1_begin = 0x4E020000;
__my_prefix_overlap1_end = 0x4E020101;
__my_prefix_overlap2_begin = 0x4E020000;
__my_prefix_overlap2_end = 0x4E02100;
```
### Example 1:
In order to overwrite an ELF file named ``empty.out`` with a file with CRCs inserted,
using the above symbols, the following cli invocation can be used:
```
crc_tool patch-image --elf empty.out --symbol-prefix __my_prefix -o empty.out
```
## Use case 2 - generate binary with crc:
This use case is accessed through using the subcommand "generate-bin" when invoking crc_tool.
Currently only text files are supported, using the ``--user-record-file`` flag.
Other file types or input formats may be defined in the future.
The following command line options are available in the generate-bin use-case.
| Name | Usage | Required? | Default |
| -------------------------------------- | ------------------------------------------------- | --------- | -------------------- |
| ``--user-record-file {file_location}`` | Specify location of input file | yes | N/A |
| ``-o {file_name} / --output {file_name}`` | Specify name of output file | no | ``user_section.bin`` |
| ``--verbose`` | Output all available logging information | No | N/A
| ``--quiet`` | Output no logging information, only fatal errors | No | N/A
### Input file format:
The input text file must contain one or more valid hex values (0x prefix is optional).
Separate integers are separated by whitespace or newlines.
All hex values must consist of an even number of hex characters.
1 is invalid, 01 is valid.
The total length of all values can be at most 124 bytes.
Comments can be added with #, and blank lines are ignored.
An example of a valid input file can be seen in user_record_example.txt.
This file is found in ``docs/example/generate_user_record/`` during development,
but is placed alongside the source files during packaging.
### Output file format:
The output file will be a 128 byte binary file, containing integers in the same order as the input data,
With the first integer at the lowest address.
The output data will be right-padded with zeros to a total of 124 bytes. After the 124 bytes of content
there will be four CRC bytes.
Each integer will be written to file using little endian.
### Example 1:
In order to write to a binary file named ``output.bin`` with input data and CRC,
the following cli invocation can be used:
```
crc_tool generate-bin --user-record-file input.txt -o output.bin
```
## Generic options
A ``--version`` flag is available to check what version of crc_tool you are using.
This version number is parsed from the latest git tag when the tool was built.
Using ``--version`` will override any other options stated.
This means that:
```
crc_tool --version generate-user-record --user-record-file user_record_example.txt
```
Will NOT generate a user record binary, it will only print the version number of crc_tool
NB. the ``--version`` flag is only available before stating a use-case.
This means that:
```
crc_tool --version
```
Is a valid invocation, while:
```
crc_tool generate-user-record --user-record-file user_record_example.txt --version
```
Will throw an error.
Raw data
{
"_id": null,
"home_page": null,
"name": "crc-tool",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Texas Instruments",
"author_email": "i.hovind@ti.com",
"download_url": null,
"platform": null,
"description": "# CRC tool\n\nThe crc_tool have been created by Texas Instruments to support the need to calculate CRC values of specific flash regions during the build process. The calculated CRC values will be inserted in the ELF file. This was introduced to support the device families CC23xx and CC27xx. \n\ncrc_tool is a tool with two primary use cases:\n\n 1. To input an ELF file, parse begin and end of section through symbols originally defined in the linker file, and add crc after the end address, as defined by these symbols.\n * This is Intended to be used as a post build step in CCS to add CRCs to the generated ELF file\n 2. To parse a txt file, containing one or more hexadecimal values, calculate the crc of this value, and generate a binary file containing hex data and crc.\n * This is intended to be given as input to a SACI command for programming the user record in the ccfg.\n\n## Dependencies\nThe Python script relies on the external library [LIEF](https://pypi.org/project/lief/0.8.3/)\n\nThis libary is included in the packaged executable.\n\n## Use case 1 - Adding CRC to ELF file\nThis use case is accessed through using the subcommand ``patch-image`` when invoking ``crc_tool``.\n\nThis use case will:\n 1. Parse symbols with a given prefix from the stated ELF file.\n 2. Use these symbols and their values to find sections to calculate CRC for.\n 3. Insert CRCs in the next four bytes after the given end of the region.\n 4. Write this new ELF file to disk.\n\nYou then need to specify the location of an input file on disk.\nCurrently the tool has only been tested with ELF files.\nOther file types may be added in the future.\n\nThe following command line options are available in the ``patch-image`` use-case.\n\n| Name | Usage | Required? | Default |\n| ------------------------------------ | ------------------------------------------------- | --------- | -------------------- |\n| ``--elf {file location}`` | Specify location of input file | Yes | N/A |\n| ``-p {prefix} / --symbol-prefix {prefix}`` | Specify prefix of begin / end symbols in ELF file | no | ``__crc_section`` |\n| ``-o {file_name} / --ouput {file_name}`` | Specify name of output file | No | ``patched.out`` |\n| ``--verbose`` | Output all available logging information | No | N/A\n| ``--quiet`` | Output no logging information, only fatal errors | No | N/A\n\n\n### Required modifications:\nFor ``crc_tool`` to know where to insert crc32 values\nit needs to be able to find symbols in the ELF file which matches the stated\nprefix. All symbols without a matching prefix are ignored.\n\nSymbols need to come in pairs with matching names, except for ``_end``, and ``_begin`` suffixes.\nSymbols without a suffix, or without a matching counterpart are ignored..\n\nIf you have the _end values of two sections which within the same 4 byte range,\nmeaning that they would overwrite eachother's CRCs, then an error is thrown.\n\nThe value of the _end symbol must be greater or equal to the _begin value, otherwise\nan error is thrown.\n\nIn a ticlang linker file symbols can be added like so\n(Note the prefix differing from above default value):\n\n```c\n__my_prefix_boot_cfg_begin = 0x4E020000;\n__my_prefix_boot_cfg_end = 0x4E02000B;\n\n__my_prefix_main_begin = 0x4E020010;\n__my_prefix_main_end = 0x4E02074B;\n\n__my_prefix_user_record_crc32_begin = 0x4E020750;\n__my_prefix_user_record_crc32_end = 0x4E0207CB;\n\n__my_prefix_debug_cfg_crc32_begin = 0x4E0207D0;\n__my_prefix_debug_cfg_crc32_end = 0x4E0207FB;\n```\n\nThe following example lists **invalid** symbols, all of these will be ignored:\n```c\n// Ignored because no corresponding _end value\n__my_prefix_boot_cfg_begin = 0x4E020000;\n\n// Ignored because of invalid suffix\n__my_prefix_main_be = 0x4E020010;\n__my_prefix_main_en = 0x4E02074B;\n\n// Ignored because no corresponding _begin value\n__my_prefix_user_record_crc32_end = 0x4E020750;\n\n// Ignored because of no valid prefix (assuming __my_prefix is used)\ndebug_cfg_crc32_begin = 0x4E0207D0;\ndebug_cfg_crc32_end = 0x4E0207FB;\n```\n\nThe following example lists **invalid** symbols, all of the following will cause\nthe program to throw an error.\n```c\n// Throw error because end is before beginning\n__my_prefix_main_begin = 0x4E020010;\n__my_prefix_main_end = 0x4E020000;\n\n// Throws error because overlap1 and overlap2 would overwrite eachother's CRCs\n__my_prefix_overlap1_begin = 0x4E020000;\n__my_prefix_overlap1_end = 0x4E020101;\n\n__my_prefix_overlap2_begin = 0x4E020000;\n__my_prefix_overlap2_end = 0x4E02100;\n```\n\n### Example 1:\nIn order to overwrite an ELF file named ``empty.out`` with a file with CRCs inserted,\nusing the above symbols, the following cli invocation can be used:\n\n```\ncrc_tool patch-image --elf empty.out --symbol-prefix __my_prefix -o empty.out\n```\n\n## Use case 2 - generate binary with crc:\nThis use case is accessed through using the subcommand \"generate-bin\" when invoking crc_tool.\n\nCurrently only text files are supported, using the ``--user-record-file`` flag.\nOther file types or input formats may be defined in the future.\n\nThe following command line options are available in the generate-bin use-case.\n\n| Name | Usage | Required? | Default |\n| -------------------------------------- | ------------------------------------------------- | --------- | -------------------- |\n| ``--user-record-file {file_location}`` | Specify location of input file | yes | N/A |\n| ``-o {file_name} / --output {file_name}`` | Specify name of output file | no | ``user_section.bin`` |\n| ``--verbose`` | Output all available logging information | No | N/A\n| ``--quiet`` | Output no logging information, only fatal errors | No | N/A\n\n\n### Input file format:\nThe input text file must contain one or more valid hex values (0x prefix is optional).\nSeparate integers are separated by whitespace or newlines.\n\nAll hex values must consist of an even number of hex characters.\n\n1 is invalid, 01 is valid.\n\nThe total length of all values can be at most 124 bytes.\n\nComments can be added with #, and blank lines are ignored.\n\nAn example of a valid input file can be seen in user_record_example.txt.\n\nThis file is found in ``docs/example/generate_user_record/`` during development,\nbut is placed alongside the source files during packaging.\n\n### Output file format:\nThe output file will be a 128 byte binary file, containing integers in the same order as the input data,\nWith the first integer at the lowest address.\n\nThe output data will be right-padded with zeros to a total of 124 bytes. After the 124 bytes of content\nthere will be four CRC bytes.\n\nEach integer will be written to file using little endian.\n\n### Example 1:\nIn order to write to a binary file named ``output.bin`` with input data and CRC,\nthe following cli invocation can be used:\n\n```\ncrc_tool generate-bin --user-record-file input.txt -o output.bin\n```\n\n## Generic options\n\nA ``--version`` flag is available to check what version of crc_tool you are using.\n\nThis version number is parsed from the latest git tag when the tool was built.\n\nUsing ``--version`` will override any other options stated.\n\nThis means that:\n```\ncrc_tool --version generate-user-record --user-record-file user_record_example.txt\n```\n\nWill NOT generate a user record binary, it will only print the version number of crc_tool\n\nNB. the ``--version`` flag is only available before stating a use-case.\n\nThis means that:\n\n```\ncrc_tool --version\n```\n\nIs a valid invocation, while:\n```\ncrc_tool generate-user-record --user-record-file user_record_example.txt --version\n```\n\nWill throw an error.\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "1.2.3.4",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "81215f4a0dc6e236d886f6cea2a4b01ab4b4e10f714e5b7b9558f080c21a6778",
"md5": "ea09384a9f035186d9c03b71a73f5a2e",
"sha256": "7f839b31a13adf8e774b5e33bca73dcfced96c934b2dcdaffc07bb5f365fd7bf"
},
"downloads": -1,
"filename": "crc_tool-1.2.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ea09384a9f035186d9c03b71a73f5a2e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20717,
"upload_time": "2024-09-18T10:16:53",
"upload_time_iso_8601": "2024-09-18T10:16:53.409545Z",
"url": "https://files.pythonhosted.org/packages/81/21/5f4a0dc6e236d886f6cea2a4b01ab4b4e10f714e5b7b9558f080c21a6778/crc_tool-1.2.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 10:16:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "crc-tool"
}
