Skip to content

Commit 77cf4a8

Browse files
mheimhei
committed
Add new chapter for carrier board development
Start this new section with some idea/background for the DT EEPROM. Later we can make this a sub-chapter and add other hints as well. Signed-off-by: Michael Heimpold <michael.heimpold@chargebyte.com>
1 parent 78ad17a commit 77cf4a8

2 files changed

Lines changed: 175 additions & 0 deletions

File tree

‎docs/source/carrierboard_development.rst‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
.. _carrierboard_development.rst:
2+
3+
********************************
4+
Custom Carrier Board Development
5+
********************************
6+
7+
After the evaluation of the Charge SOM platform based on chargebyte's Evaluation Board (EVB), the customer
8+
might have the wish to create a customer-specific carrier board that best fits their individual requirements.
9+
10+
During hardware development, customers are advised to not only pay attention to the hardware requirements
11+
like choosing connectors, board layout etc. but also have software engineering in mind, product life cycle,
12+
product variants and similar aspects.
13+
14+
At chargebyte, the Charge SOMs are not only manufactured for each customer request but we aim to have
15+
some boards in stock to fullfill customer request demands in a timely fashion. This means that we pre-install
16+
a firmware on the boards which has a given software revision and may include only software support for
17+
carrier boards which are already know at the time of manufacturing. However, this has the small disadvantage that
18+
customers could mount the Charge SOM on carrier boards without prior updating the factory firmware. In this
19+
case, there might be a minimal electrical risk that the software configuration of the board connector does not
20+
match the electrical expectation/requirement of the carrier board.
21+
To prevent this and to have a more Plug & Play like feeling, customers can place an EEPROM on their custom
22+
carrier board design. The idea is not new: similiar to the well-known Raspberry Pi(tm) ecosystem where
23+
Pi HATs also use such an EEPROM, the U-Boot bootloader of the Charge SOM checks such an EEPROM - when available - for
24+
a Device Tree overlay which is then loaded and passed to the Linux kernel dynamically. This allows customers
25+
to model all the specific pin settings of their custom carrier board so that the electrical compatibitiliy
26+
is ensured.
27+
28+
Such an EEPROM has to be connected to the ``I2C1`` pins ``SCL`` (Connector X5/41) and ``SDA`` (Connector X5/43) and
29+
it must be configured for I2C address ``0x50``.
30+
chargebyte recommends to plan with an EERPOM of at least 32 kB (kilobyte): the Device Tree overlay and a digitial
31+
signature must fit into it. Once the customer have created the Device Tree overlay and signature and it fits also into
32+
e.g. a 16 kB EEPROM, it is usually only a BOM change to populate such a smaller version.
33+
34+
The EEPROM content consists of a 128 byte fixed-length header and a variable length DT overlay content,
35+
plus a variable length digital signature (optional for now) for the DT overlay blob.
36+
37+
The C structure for the header looks like follows:
38+
39+
.. code-block:: c
40+
41+
struct cb_dt_eeprom_header {
42+
uint16_t signature; /* big-endian 'CB' = 0x4342 */
43+
uint8_t reserved0; /* 0x00 */
44+
uint8_t header_version; /* 0x01 */
45+
uint16_t dt_offset; /* little-endian */
46+
uint16_t dt_size; /* little-endian */
47+
uint16_t dt_sig_offset; /* little-endian */
48+
uint16_t dt_sig_size; /* little-endian */
49+
uint32_t vendor_code; /* little-endian */
50+
union {
51+
struct {
52+
uint32_t hw_rev; /* special encoding, see below */
53+
uint8_t order_code[32]; /* ASCII string */
54+
uint8_t reserved1[72];
55+
} cb_dt_chargebyte;
56+
} vendor_specific;
57+
uint32_t crc32; /* little-endian */
58+
};
59+
60+
Or, presented in a more visually appealing ASCII art way:
61+
62+
::
63+
64+
+--------++-----+-----+-----+-----+-----+-----+-----+-----+-------+-------+-------+-------+-----+-----+-----+-----+
65+
| Offset || 0x0 | 0x1 | 0x2 | 0x3 | 0x4 | 0x5 | 0x6 | 0x7 | 0x8 | 0x9 | 0xA | 0xB | 0xC | 0xD | 0xE | 0xF |
66+
+========++=====+=====+=====+=====+=====+=====+=====+=====+=======+=======+=======+=======+=====+=====+=====+=====+
67+
| 0x0000 || 'C' | 'B' | 0x0 | 0x1 | DT Offset | DT Size | DT Signature | DT Signature | Vendor ID |
68+
| || | | | | | | Offset | Size | |
69+
+--------++-----+-----+-----+-----+-----+-----+-----+-----+-------+-------+-------+-------+-----+-----+-----+-----+
70+
| 0x0010 || Vendor Specific |
71+
+--------++-------------------------------------------------------------------------------------------------------+
72+
| ... || Vendor Specific (cont.) |
73+
+--------++-------------------------------------------------------------------------------+-----------------------+
74+
| 0x0070 || Vendor Specific (cont.) | CRC32 |
75+
+--------++-------------------------------------------------------------------------------+-----------------------+
76+
| 0x0080 || Device Tree Overlay BLOB |
77+
+--------++-------------------------------------------------------------------------------------------------------+
78+
| ... || Device Tree Overlay BLOB (cont.) |
79+
+--------++-------------------------------------------------------------------------------------------------------+
80+
| ... || Device Tree Overlay Signature BLOB |
81+
+--------++-------------------------------------------------------------------------------------------------------+
82+
| ... || Device Tree Overlay Signature BLOB (cont.) |
83+
+--------++-------------------------------------------------------------------------------------------------------+
84+
85+
Additional notes regarding the content:
86+
87+
- All multi-byte fields use the little-endian byte order since U-Boot and Linux kernel run the CPU in little-endian
88+
mode and thus it is simpler to use the fields. Only the leading signature is stored big-endian to have a
89+
human-friendly nice hexdump when looking at the EEPROM content.
90+
- The DT offset can point to any location in the EEPROM. It is not required that the DT Overlay Blob starts directly
91+
after the header. This allows for vendors to store custom data and/or additional fields in the EEPROM.
92+
- The same applies to the DT Overlay Signature Blob.
93+
- The vendor specific header part can be used also for customer specific data. The C structure reflects what chargebyte
94+
is going to use as example.
95+
- The Vendor ID can be used by customers to identify different carrier boards and/or to determine how the vendor
96+
specific area is structured. chargebyte will use the fixed-value 0x63624342 (ASCII “cbCB” → 0x42 0x43 0x62 0x63 in
97+
little-endianess) for its boards. Customers can choose arbitrary values ​​here, but it is recommended (though not
98+
mandatory) to coordinate the value with chargebyte. If desired, chargebyte can also document such values here in this
99+
documentation.
100+
- The header check in U-Boot will be very simple for the moment: only the CRC32 is validated and when it is correct,
101+
then DT offset and DT length fields are used without further checks.
102+
Customers are advised to fully comply with this specification since the implemented behaviour can be extended
103+
to be more strict in the future.
104+
- The digitial signature is currently not checked by U-Boot or any other software component.
105+
106+
The idea of the digital signature is to ensure that the Device Tree overlay blob is from trusted source and thus can
107+
be loaded and used without damaging the system. The signature can be created using a X.509 certificate using e.g.
108+
``openssl cms …`` and thus creating a 'detached' signature of the binary DT overlay file.
109+
110+
To keep the signature small, the certificate could be *not* included in the signature (and thus not stored inside
111+
the EEPROM), but to verify the signature, accessing the signing certificate must then be possible (e.g. placed in
112+
and loaded from the root filesystem). This raises other topics, so chargebyte's start point is to include it as
113+
complete signature in the EERPOM even if this requires a larger EEROM type.
114+
115+
Such a signature can be created for example using the following command line:
116+
117+
.. code-block:: shell
118+
119+
openssl cms -sign -in imx93-charge-som-dc-2c.dtbo -out imx93-charge-som-dc-2c.dtbo.sig -outform DER -binary -signer my-company.crt -inkey my-company.key
120+
121+
It is possible to re-use an existing Public-Key Infrastructure which is already used for signing the firmware
122+
update files.
123+
124+
Once a matching Device Tree overlay and the corresponding signature is available, the EEPROM content needs to be created
125+
using the helper tool ``cb-dt-eeprom`` which is included in
126+
chargebyte's Github space: https://github.com/chargebyte/cb-eeprom-utils
127+
128+
An example invocation for a chargebyte carrier board looks for example like this:
129+
130+
.. code-block:: shell
131+
132+
cb-dt-eeprom -r V0R1a -o CBCSOMC-D200-00001 imx93-charge-som-dc-2c.dtbo imx93-charge-som-dc-2c.dtbo.sig > dt-eeprom.bin
133+
134+
During carrier board manufacturing, it is assumed that writing the EEPROM is be done via external programmer
135+
which is out-of-scope for this documentation.
136+
137+
But during development phase, it might be necessary to exchange the EEPROM content and/or rewrite it for testing purpose.
138+
Then using an external programmer is cumbersome. Better and simpler is to write the created binary EEPROM image file
139+
into the EEPROM directly from the Charge SOM hooked up to such a carrier board. The following command can be used
140+
via SSH and/or Debug UART:
141+
142+
.. code-block:: shell
143+
144+
dd if="dt-eeprom.bin" of=/sys/class/i2c-dev/i2c-0/device/0-0050/eeprom
145+
146+
Even so, it's still a complex process and long round trip. So it is possible to directly place such Device Tree overlay
147+
files in the root filesystem of the firmware in the ``/boot`` directory.
148+
Loading of such files can be controled with the U-Boot environment variable ``overlays``. This variable can hold a whitespace
149+
separated list of filenames (basename of the file, i.e. without ``/boot`` prefix) which are loaded and merged
150+
in order *after* the base Device Tree file (given via ``fdtfile`` environment variable) is loaded.
151+
This appraoch can also be used for custom carrier board when the EEPROM approach does not fit.
152+
153+
Here is a summary of related U-Boot environment variables:
154+
155+
+------------------------------+------------------------------------------------------------------------------+
156+
| U-Boot Variable Name | Description |
157+
+==============================+==============================================================================+
158+
| fdtfile | The base Device Tree blob to load. This variable must be always set |
159+
| | to a valid filename of a file in ``/boot``. |
160+
| | By default, this variable is set to ``imx93-charge-som.dtb``. |
161+
+------------------------------+------------------------------------------------------------------------------+
162+
| overlays | List of filenames to be loaded as DT overlays. |
163+
| | Unset by default. |
164+
+------------------------------+------------------------------------------------------------------------------+
165+
| no_overlays | Boolean flag, i.e. ``0`` or ``1``. Can be used to disable the DT |
166+
| | overlay loading from filesystem completely. Set to ``0`` by default. |
167+
+------------------------------+------------------------------------------------------------------------------+
168+
| no_eeprom_dtbo | Boolean flag, i.e. ``0`` or ``1``. Can be used to disable the DT |
169+
| | overlay loading from EEPROM. Set to ``0`` by default. |
170+
| | Can - for example - be used during DT oveerlay development. |
171+
+------------------------------+------------------------------------------------------------------------------+
172+
173+
From Linux user-space, such U-Boot environment variables can be displayed with ``fw_printenv`` and set
174+
with ``fw_setenv`` utility. Both tools are included in chargebyte's example firmware image.

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,5 @@ Charge SOM Evaluation Kit.
2727
everest_charging_stack
2828
cb_energy
2929
development
30+
carrierboard_development
3031
troubleshooting

0 commit comments

Comments
 (0)