Lines Matching +full:soc +full:-
3 SoC Porting Guide
6 This page describes how to add support for a new :term:`SoC` in Zephyr, be it in
9 SoC Definitions
16 For SoC porting, the most important terms are:
18 - SoC: the exact system on a chip the board's CPU is part of.
19 - SoC series: a group of tightly related SoCs.
20 - SoC family: a wider group of SoCs with similar characteristics.
21 - CPU Cluster: a cluster of one or more CPU cores.
22 - CPU core: a particular CPU instance of a given architecture.
23 - Architecture: an instruction set architecture.
31 Create your SoC directory
34 Each SoC must have a unique name. Use the official name given by the SoC vendor
36 contributed a SoC with identical name. If the SoC name is already in use, then
37 you should probably improve the existing SoC instead of creating a new one.
39 in Zephyr, for example ``./scripts/list_hardware.py --soc-root=. --socs`` from
42 Start by creating the directory ``zephyr/soc/<VENDOR>/soc1``, where
46 A ``<VENDOR>`` subdirectory is mandatory if contributing your SoC
47 to Zephyr, but if your SoC is placed in a local repo, then any folder
48 structure under ``<your-repo>/soc`` is permitted.
50 :zephyr_file:`dts/bindings/vendor-prefixes.txt`. If the SoC vendor does not
55 The SoC directory name does not need to match the name of the SoC.
57 organized in sub-folders in a common SoC Family or SoC Series tree.
59 Your SoC directory should look like this:
61 .. code-block:: none
63 soc/<VENDOR>/<soc-name>
64 ├── soc.yml
65 ├── soc.h
68 ├── Kconfig.soc
71 Replace ``<soc-name>`` with your SoC's name.
76 #. :file:`soc.yml`: a YAML file describing the high-level meta data of the
77 SoC such as:
79 - SoC name: the name of the SoC
80 - CPU clusters: CPU clusters if the SoC contains one or more clusters
81 - SoC series: the SoC series to which the SoC belong
82 - SoC family: the SoC family to which the series belong
84 #. :file:`soc.h`: a header file which can be used to describe or provide
85 configuration macros for the SoC. The :file:`soc.h` will often be included in
86 drivers, sub-systems, boards, and other source code found in Zephyr.
88 #. :file:`Kconfig.soc`: the base SoC configuration which defines a Kconfig SoC
89 symbol in the form of ``config SOC_<soc-name>`` and provides the SoC name to
90 the Kconfig ``SOC`` setting.
91 If the ``soc.yml`` describes a SoC family and series, then those must also
92 be defined in this file. Kconfig settings outside of the SoC tree must not be
98 when a build targets the SoC. Also the base line linker script to use must be
103 - :file:`Kconfig`, :file:`Kconfig.defconfig` software configuration in
107 Write your SoC YAML
110 The SoC YAML file describes the SoC family, SoC series, and SoC at a high level.
115 The skeleton of a simple SoC YAML file containing just one SoC is:
117 .. code-block:: yaml
120 - name: <soc1>
122 It is possible to have multiple SoC located in the SoC folder.
124 locate such SoC in a common tree.
125 Multiple SoCs and SoC series in a common folder can be described in the
126 :file:`soc.yml` file as:
128 .. code-block:: yaml
131 name: <family-name>
133 - name: <series-1-name>
135 - name: <soc1>
137 - name: <coreA>
138 - name: <coreB>
140 - name: <soc2>
141 - name: <series-2-name>
145 Write your SoC devicetree
148 SoC devicetree include files are located in the :file:`<zephyr-repo>/dts` folder
151 The SoC :file:`dts/<ARCH>/<VENDOR>/<soc>.dtsi` describes your SoC hardware in
153 the SoC.
156 include this file in your :file:`<soc>.dtsi`.
158 In general, :file:`<soc>.dtsi` should look like this:
160 .. code-block:: devicetree
166 /* common chosen settings for your SoC */
170 #address-cells = <m>;
171 #size-cells = <n>;
179 soc {
180 /* Your SoC definitions and peripherals */
186 It is possible to structure multiple :file:`<VENDOR>/<soc>.dtsi` files in
187 sub-directories for a cleaner file system structure. For example organized
188 pre SoC series, like this: :file:`<VENDOR>/<SERIES>/<soc>.dtsi`.
199 :file:`<soc>_<cluster>.dtsi`. A :file:`<soc>_<cluster>.dtsi` file will look
200 similar to a SoC :file:`.dtsi` without CPU clusters.
205 Zephyr uses the Kconfig language to configure software features. Your SoC
212 There is one mandatory Kconfig file in the SoC directory, and two optional
213 files for a SoC:
215 .. code-block:: none
217 soc/<vendor>/<your soc>
218 ├── Kconfig.soc
222 :file:`Kconfig.soc`
226 This file selects the SoC family and series in the Kconfig tree and potential
227 other SoC related Kconfig settings. In some cases a SOC_PART_NUMBER.
228 This file must not select anything outside the re-usable Kconfig SoC tree.
230 A :file:`Kconfig.soc` may look like this:
232 .. code-block:: kconfig
241 config SOC
242 default "SoC name" if SOC_<SOC_NAME>
244 Notice that ``SOC_NAME`` is a pure upper case version of the SoC name.
246 The Kconfig ``SOC`` setting is globally defined as a string and therefore the
247 :file:`Kconfig.soc` file shall only define the default string value and not
248 the type. Notice that the string value must match the SoC name used in the
249 :file:`soc.yml` file.
252 Included by :zephyr_file:`soc/Kconfig`.
254 This file can add Kconfig settings which are specific to the current SoC.
259 .. code-block:: kconfig
270 SoC specific default values for Kconfig options.
277 .. code-block:: kconfig
289 CPU clusters must provide additional Kconfig settings in the :file:`Kconfig.soc`
294 SoC's When a SoC defines CPU cluster
296 .. code-block:: kconfig