Skip to content

Commit dfeb228

Browse files
mheimhei
authored
Merge pull request #88 from chargebyte/everest/charge_som_dt_eeprom
Add new chapter for carrier board development
2 parents 2f6f25a + b3c273d commit dfeb228

2 files changed

Lines changed: 190 additions & 0 deletions

File tree

‎docs/source/carrierboard_development.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
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 fulfill 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), i.e. a 24C256 [#]_: the Device Tree
31+
overlay and a digital signature must fit into it.
32+
Once the customer has created the Device Tree overlay and signature and it also fits into
33+
e.g. a 16 kB EEPROM, it is usually only a BOM change to populate such a smaller version.
34+
35+
.. [#] Many vendors provide compatible devices. In Device Tree, we still recommend to use
36+
``compatible = "atmel,24c256"`` since U-Boot does not support other vendor prefixes than ``atmel``.
37+
38+
The EEPROM content consists of a 128 byte fixed-length header and a variable length DT overlay content,
39+
plus a variable length digital signature (optional for now) for the DT overlay blob.
40+
41+
The C structure for the header looks like follows:
42+
43+
.. code-block:: c
44+
45+
struct cb_dt_eeprom_header {
46+
uint16_t signature; /* big-endian 'CB' = 0x4342 */
47+
uint8_t reserved0; /* 0x00 */
48+
uint8_t header_version; /* 0x01 */
49+
uint16_t dt_offset; /* little-endian */
50+
uint16_t dt_size; /* little-endian */
51+
uint16_t dt_sig_offset; /* little-endian */
52+
uint16_t dt_sig_size; /* little-endian */
53+
uint32_t vendor_code; /* little-endian */
54+
union {
55+
struct {
56+
uint32_t hw_rev; /* special encoding, see below */
57+
uint8_t order_code[32]; /* ASCII string */
58+
uint8_t reserved1[72];
59+
} cb_dt_chargebyte;
60+
} vendor_specific;
61+
uint32_t crc32; /* little-endian */
62+
};
63+
64+
Or, presented in a more visually appealing ASCII art way:
65+
66+
::
67+
68+
+--------++-----+-----+-----+-----+-----+-----+-----+-----+-------+-------+-------+-------+-----+-----+-----+-----+
69+
| Offset || 0x0 | 0x1 | 0x2 | 0x3 | 0x4 | 0x5 | 0x6 | 0x7 | 0x8 | 0x9 | 0xA | 0xB | 0xC | 0xD | 0xE | 0xF |
70+
+========++=====+=====+=====+=====+=====+=====+=====+=====+=======+=======+=======+=======+=====+=====+=====+=====+
71+
| 0x0000 || 'C' | 'B' | 0x0 | 0x1 | DT Offset | DT Size | DT Signature | DT Signature | Vendor Code |
72+
| || | | | | | | Offset | Size | |
73+
+--------++-----+-----+-----+-----+-----+-----+-----+-----+-------+-------+-------+-------+-----+-----+-----+-----+
74+
| 0x0010 || Vendor Specific |
75+
+--------++-------------------------------------------------------------------------------------------------------+
76+
| ... || Vendor Specific (cont.) |
77+
+--------++-------------------------------------------------------------------------------+-----------------------+
78+
| 0x0070 || Vendor Specific (cont.) | CRC32 |
79+
+--------++-------------------------------------------------------------------------------+-----------------------+
80+
| 0x0080 || Device Tree Overlay BLOB |
81+
+--------++-------------------------------------------------------------------------------------------------------+
82+
| ... || Device Tree Overlay BLOB (cont.) |
83+
+--------++-------------------------------------------------------------------------------------------------------+
84+
| ... || Device Tree Overlay Signature BLOB |
85+
+--------++-------------------------------------------------------------------------------------------------------+
86+
| ... || Device Tree Overlay Signature BLOB (cont.) |
87+
+--------++-------------------------------------------------------------------------------------------------------+
88+
89+
Additional notes regarding the content:
90+
91+
- All multi-byte fields use the little-endian byte order since U-Boot and Linux kernel run the CPU in little-endian
92+
mode and thus it is simpler to use the fields. Only the leading signature is stored big-endian to have a
93+
human-friendly nice hexdump when looking at the EEPROM content.
94+
- The ``DT offset`` can point to any location in the EEPROM. It is not required that the DT Overlay Blob starts directly
95+
after the header. This allows for vendors to store custom data and/or additional fields in the EEPROM.
96+
- The same applies to the DT Overlay Signature Blob.
97+
- The vendor specific header part can also be used for customer specific data. The C structure reflects what chargebyte
98+
is going to use as an example.
99+
- The ``Vendor Code`` can be used by customers to identify different carrier boards and/or to determine how the vendor
100+
specific area is structured. chargebyte will use the fixed-value 0x63624342 (ASCII “cbCB” → 0x42 0x43 0x62 0x63 in
101+
little-endianess) for its boards. Customers can choose arbitrary values ​​here, but it is recommended (though not
102+
mandatory) to coordinate the value with chargebyte. If desired, chargebyte can also record such values here in this
103+
documentation.
104+
- As example, chargebyte will use the vendor specific part to store a hardware board revision and an order code
105+
of this board model. It can be accessed in the field later by the firmware for debugging and/or maintainance purpose.
106+
Customers might have their own requirements to store individual board specific, or general product information.
107+
- The header check in U-Boot will be very simple for the moment: only the CRC32 is validated and when it is correct,
108+
then DT offset and DT length fields are used without further checks.
109+
Customers are advised to fully comply with this specification since the implemented behaviour can be extended
110+
to be more strict in the future.
111+
- The digital DT overlay signature is currently not checked by U-Boot or any other software component but this
112+
is recommended for production use. chargebyte aims to extend the software support for this later.
113+
114+
The idea of the digital DT overlay signature is to ensure that the Device Tree overlay blob is from a trusted source and
115+
thus can be loaded and used without damaging the system. The signature can be created using a X.509 certificate
116+
using e.g. ``openssl cms …`` and thus creating a *detached* signature of the binary DT overlay file.
117+
118+
To keep the DT overlay signature small, the certificate could be *not* included in this signature (and thus not stored
119+
inside the EEPROM), but to verify this signature, accessing the signing certificate must then be possible (e.g. placed in
120+
and loaded from the root filesystem). This raises other topics, so chargebyte's start point is to include it as
121+
a complete X.509 signature in the EEPROM even if this requires a larger EEPROM type.
122+
123+
Such a signature can be created for example using the following command line:
124+
125+
.. code-block:: shell
126+
127+
openssl cms -sign -in imx93-charge-som-my-custom-carrier-board.dtbo -out imx93-charge-som-my-custom-carrier-board.dtbo.sig -outform DER -binary -signer my-company.crt -inkey my-company.key
128+
129+
It is possible to re-use an existing Public-Key Infrastructure which is already used for signing the firmware
130+
update files.
131+
132+
Once a matching Device Tree overlay and the corresponding signature are available, the EEPROM content needs to be created
133+
using the helper tool ``cb-dt-eeprom`` which is included in
134+
chargebyte's Github space: https://github.com/chargebyte/cb-eeprom-utils
135+
136+
An example invocation for the carrier board which is the base for chargebyte's Charge Control V looks for example like follows.
137+
The example uses the typical chargebyte board revision number and a chargebyte order code which was assigned to this carrier board type.
138+
139+
.. code-block:: shell
140+
141+
cb-dt-eeprom -r V0R1a -o CBCSOMC-D200-00001 imx93-charge-control-v.dtbo imx93-charge-control-v.dtbo.sig > dt-eeprom.bin
142+
143+
For a random customer, this might look like this (here with a randomly chosen vendor code):
144+
145+
.. code-block:: shell
146+
147+
cb-dt-eeprom --vendor-code 0x6d686569 imx93-charge-som-my-custom-carrier-board.dtbo imx93-charge-som-my-custom-carrier-board.dtbo.sig > dt-eeprom.bin
148+
149+
During carrier board manufacturing, it is assumed that writing the EEPROM is done via an external programmer
150+
which is out-of-scope for this documentation.
151+
152+
But during the development phase, it might be necessary to exchange the EEPROM content and/or rewrite it for testing purpose.
153+
Then using an external programmer is cumbersome. Better and simpler is to write the created binary EEPROM image file
154+
into the EEPROM directly from the Charge SOM hooked up to such a carrier board. The following command can be used
155+
via SSH and/or Debug UART:
156+
157+
.. code-block:: shell
158+
159+
dd if="dt-eeprom.bin" of=/sys/class/i2c-dev/i2c-0/device/0-0050/eeprom
160+
161+
Even so, it's still a complex process and long round trip. So it is possible to directly place such Device Tree overlay
162+
files in the root filesystem of the firmware in the ``/boot`` directory.
163+
Loading of such files can be controlled with the U-Boot environment variable ``overlays``. This variable can hold a whitespace
164+
separated list of filenames (basename of the file, i.e. without ``/boot`` prefix) which are loaded and merged
165+
in order *after* the base Device Tree file (given via ``fdtfile`` environment variable) is loaded.
166+
This approach can also be used for a custom carrier board when the EEPROM approach does not fit.
167+
168+
Here is a summary of related U-Boot environment variables:
169+
170+
+------------------------------+------------------------------------------------------------------------------+
171+
| U-Boot Variable Name | Description |
172+
+==============================+==============================================================================+
173+
| fdtfile | The base Device Tree blob to load. This variable must be always set |
174+
| | to a valid filename of a file in ``/boot``. |
175+
| | By default, this variable is set to ``imx93-charge-som.dtb``. |
176+
+------------------------------+------------------------------------------------------------------------------+
177+
| overlays | List of filenames to be loaded as DT overlays. |
178+
| | Unset by default. |
179+
+------------------------------+------------------------------------------------------------------------------+
180+
| no_overlays | Boolean flag, i.e. ``0`` or ``1``. Can be used to disable the DT |
181+
| | overlay loading from filesystem completely. Set to ``0`` by default. |
182+
+------------------------------+------------------------------------------------------------------------------+
183+
| no_eeprom_dtbo | Boolean flag, i.e. ``0`` or ``1``. Can be used to disable the DT |
184+
| | overlay loading from EEPROM. Set to ``0`` by default. |
185+
| | Can - for example - be used during DT oveerlay development. |
186+
+------------------------------+------------------------------------------------------------------------------+
187+
188+
From Linux user-space, such U-Boot environment variables can be displayed with ``fw_printenv`` and set
189+
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)