|
1 |
| -## Hardware CRC - Porting Guide |
| 1 | +## Hardware CRC |
2 | 2 |
|
3 |
| -The Hardware CRC HAL API provides a low-level interface to the Hardware CRC |
4 |
| -module of a target platform. Implementing the Hardware CRC API will allow you |
5 |
| -to gain the performance benefits of using hardware acceleration for CRC |
6 |
| -calculations. For platforms without hardware CRC capabilities the API will |
7 |
| -fallback to using the table and bitwise CRC implementations. |
| 3 | +The hardware CRC HAL API provides a low-level interface to the hardware CRC module of a target platform. Implementing the hardware CRC API allows you to gain the performance benefits of using hardware acceleration for CRC calculations. For platforms without hardware CRC capabilities, the API falls back to using the table and bitwise CRC implementations. |
8 | 4 |
|
9 | 5 | #### Assumptions
|
10 | 6 |
|
11 |
| -##### Defined Behaviour |
| 7 | +##### Defined behavior |
12 | 8 |
|
13 |
| -* Calling hal_crc_compute_partial_start() multiple times will override the |
14 |
| - current CRC configuration and calculation. |
| 9 | +- Calling `hal_crc_compute_partial_start()` multiple times overrides the current CRC configuration and calculation. |
| 10 | +- The current intermediate calculation is lost if the module is reconfigured with `hal_crc_compute_partial_start()`. |
| 11 | +- `hal_crc_compute_partial()` does nothing if either the buffer is undefined or the size is equal to 0. |
| 12 | +- `hal_crc_compute_partial()` is safe to call multiple times. The new data is appended to the current calculation. |
| 13 | +- `hal_crc_is_supported` must return false if the the platform cannot support the initial or final values or data reflection in or out that the input polynomial requires. |
15 | 14 |
|
16 |
| -* The current intermediate calculation is lost if the module is reconfigured |
17 |
| - with hal_crc_compute_partial_start(). |
| 15 | +##### Undefined behavior |
18 | 16 |
|
19 |
| -* hal_crc_compute_partial() does nothing if either the buffer is undefined or |
20 |
| - the size is equal to 0. |
| 17 | +- Calling the `hal_crc_get_result()` function multiple times is undefined. The contents of the result register after it has been read is platform-specific. The HAL API makes no assumptions about what the register contains, so it is not safe to call this multiple times. |
| 18 | +- Calling the `hal_crc_partial_start()` function with a polynomial unsupported by the current platform is undefined. Polynomial support should be checked before this function is called. |
| 19 | +- Calling the `hal_crc_get_result()` function before calling `hal_crc_partial_start()` is undefined. The module must be initialized before the get result function can return meaningful values. |
| 20 | +- Calling the `hal_crc_compute_partial()` function before calling `hal_crc_partial_start()` is undefined. The hardware CRC module must be configured correctly using the start function before writing data to it. |
21 | 21 |
|
22 |
| -* hal_crc_compute_partial() is safe to call multiple times. The new data is |
23 |
| - appended to the current calculation. |
| 22 | +#### Dependency |
24 | 23 |
|
25 |
| -* hal_crc_is_supported must return false if the the platform cannot support the |
26 |
| - initial/final values or data reflection in/out that is required by the input |
27 |
| - polynomial. |
28 |
| - |
29 |
| -##### Undefined Behaviour |
30 |
| - |
31 |
| -* Calling the hal_crc_get_result() function multiple times is undefined. The |
32 |
| - contents of the result register after it has been read is platform-specific. |
33 |
| - The HAL API makes no assumptions what the register contains so it is not safe |
34 |
| - to call this multiple times. |
35 |
| - |
36 |
| -* Calling the hal_crc_partial_start() function with a polynomial unsupported by |
37 |
| - the current platform is undefined. Polynomial support should be checked before |
38 |
| - this function is called. |
39 |
| - |
40 |
| -* Calling the hal_crc_get_result() function before calling |
41 |
| - hal_crc_partial_start() is undefined. The module must be initialized before |
42 |
| - the get result function can return meaningful values. |
43 |
| - |
44 |
| -* Calling the hal_crc_compute_partial() function before calling |
45 |
| - hal_crc_partial_start() is undefined. The Hardware CRC module must be |
46 |
| - configured correctly using the start function before writing data to it. |
47 |
| - |
48 |
| -#### Dependencies |
49 |
| - |
50 |
| -Hardware CRC module in MCU that supports at least one of the following defined |
51 |
| -polynomials: `POLY_8BIT_CCITT, POLY_7BIT_SD, POLY_16BIT_CCITT, POLY_16BIT_IBM, |
52 |
| -POLY_32BIT_ANSI ` |
| 24 | +The hardware CRC module in the MCU that supports at least one of the following defined polynomials: `POLY_8BIT_CCITT, POLY_7BIT_SD, POLY_16BIT_CCITT, POLY_16BIT_IBM, POLY_32BIT_ANSI ` |
53 | 25 |
|
54 | 26 | #### Implementing the CRC API
|
55 | 27 |
|
56 |
| -You can find the API and specification for the Hardware CRC API in the following |
57 |
| -header file: |
| 28 | +You can find the API and specification for the hardware CRC API in the following header file: |
58 | 29 |
|
59 | 30 | ```
|
60 | 31 | Fix link after code is merged.
|
61 | 32 | ```
|
62 | 33 |
|
63 |
| -To enable Hardware CRC support in Mbed OS, add the `CRC` label in the |
64 |
| -`device_has` option of the target's section in the `targets.json` file. |
| 34 | +To enable hardware CRC support in Mbed OS, add the `CRC` label in the `device_has` option of the target's section in the `targets.json` file. |
65 | 35 |
|
66 | 36 | #### Testing
|
67 | 37 |
|
68 |
| -The Mbed OS HAL API provides a set of conformance tests for Hardware CRC. You |
69 |
| -can use these tests to validate the correctness of your implementation. To run |
70 |
| -the Hardware CRC HAL tests use the following command: |
| 38 | +The Mbed OS HAL API provides a set of conformance tests for Hardware CRC. You can use these tests to validate the correctness of your implementation. To run the hardware CRC HAL tests, use the following command: |
71 | 39 |
|
72 | 40 | ```
|
73 | 41 | mbed test -t <toolchain> -m <target> -n "tests-mbed_hal-crc*"
|
|
0 commit comments