1MBEDTLS Error Strings for MicroPython
2=====================================
3
4This directory contains source code and tools to rework the Mbedtls error strings for
5micropython to use less space. In short, instead of storing and printing something like
6"SSL - Our own certificate(s) is/are too large to send in an SSL message" it prints
7the name of the error #define, which would be "MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE" in
8this case, and only stores `SSL_CERTIFICATE_TOO_LARGE` in flash. The exact Mbedtls error
9defines are used because they're easy to search for to find more detailed information.
10
11Mbedtls defines a specific format for error value #defines and
12includes a Perl script to gather all `MBEDTLS_ERR` defines from includes files together with
13english error text. From that the Perl script generates `mbedtls_strerror()`. The files in this
14directory modify this process to produce a more space efficient error lookup table with
15shorter error strings.
16
17The files are as follows:
18- `generate_errors.diff` - diff for original mbedtls perl script
19- `error.fmt` - modified code template for MicroPython
20- `mp_mbedtls_errors.c` - source file with `mbedtls_strerror` this is built using the include
21  files in `../mbedtls`
22- `do-mp.sh` - shell script to produce `mp_mbedtls_errors.c`
23- `tester.c` - simple C main to test `mp_mbedtls_errors.c` locally on a dev box
24- `do-test.sh` - shell script to produce `mp_mbedtls_errors.c` and compile the `tester` app
25- `do-esp32.sh` - shell script to produce `esp32_mbedtls_errors.c` -- see below
26
27In order not to store multiple copies of `mbedtls_errors.c`
28([https://github.com/micropython/micropython/pull/5819#discussion_r445528006](see))
29it is assumed that all ports use the same version of mbedtls with the same error #defines.
30This is true as of MP v1.13, and ESP-IDF versions 3.3.2 and 4.0.1. If anything changes in the
31future the `do-esp32.sh` script can be used to generate an esp32-specific version.
32
33### How-to
34
35- To build MicroPython all that is needed is to include the `mp_mbedtls_errors.c` into the build
36  (the Makefiles do this automatically). Note that Perl is not needed for routine MicroPython
37  builds.
38- When a new version of Mbedtls is pulled-in the `do-mp.sh` script should be run to
39  re-generate `mp_mbedtls_errors.c`.
40- The `tester` app should be run if changes to the string handling in `error.fmt` are made:
41  it tests that there is not an off-by-one error in the string copying/appending, etc.
42- To include `mbedtls_strerror` error strings define `MBEDTLS_ERROR_C` in the build.
43