GNU Linux-libre 4.14.266-gnu1
[releases.git] / Documentation / devicetree / bindings / crypto / fsl-sec4.txt
1 =====================================================================
2 SEC 4 Device Tree Binding
3 Copyright (C) 2008-2011 Freescale Semiconductor Inc.
4
5  CONTENTS
6    -Overview
7    -SEC 4 Node
8    -Job Ring Node
9    -Run Time Integrity Check (RTIC) Node
10    -Run Time Integrity Check (RTIC) Memory Node
11    -Secure Non-Volatile Storage (SNVS) Node
12    -Secure Non-Volatile Storage (SNVS) Low Power (LP) RTC Node
13    -Full Example
14
15 NOTE: the SEC 4 is also known as Freescale's Cryptographic Accelerator
16 Accelerator and Assurance Module (CAAM).
17
18 =====================================================================
19 Overview
20
21 DESCRIPTION
22
23 SEC 4 h/w can process requests from 2 types of sources.
24 1. DPAA Queue Interface (HW interface between Queue Manager & SEC 4).
25 2. Job Rings (HW interface between cores & SEC 4 registers).
26
27 High Speed Data Path Configuration:
28
29 HW interface between QM & SEC 4 and also BM & SEC 4, on DPAA-enabled parts
30 such as the P4080.  The number of simultaneous dequeues the QI can make is
31 equal to the number of Descriptor Controller (DECO) engines in a particular
32 SEC version.  E.g., the SEC 4.0 in the P4080 has 5 DECOs and can thus
33 dequeue from 5 subportals simultaneously.
34
35 Job Ring Data Path Configuration:
36
37 Each JR is located on a separate 4k page, they may (or may not) be made visible
38 in the memory partition devoted to a particular core.  The P4080 has 4 JRs, so
39 up to 4 JRs can be configured; and all 4 JRs process requests in parallel.
40
41 =====================================================================
42 SEC 4 Node
43
44 Description
45
46     Node defines the base address of the SEC 4 block.
47     This block specifies the address range of all global
48     configuration registers for the SEC 4 block.  It
49     also receives interrupts from the Run Time Integrity Check
50     (RTIC) function within the SEC 4 block.
51
52 PROPERTIES
53
54    - compatible
55       Usage: required
56       Value type: <string>
57       Definition: Must include "fsl,sec-v4.0"
58
59    - fsl,sec-era
60       Usage: optional
61       Value type: <u32>
62       Definition: A standard property. Define the 'ERA' of the SEC
63           device.
64
65    - #address-cells
66        Usage: required
67        Value type: <u32>
68        Definition: A standard property.  Defines the number of cells
69            for representing physical addresses in child nodes.
70
71    - #size-cells
72        Usage: required
73        Value type: <u32>
74        Definition: A standard property.  Defines the number of cells
75            for representing the size of physical addresses in
76            child nodes.
77
78    - reg
79       Usage: required
80       Value type: <prop-encoded-array>
81       Definition: A standard property.  Specifies the physical
82           address and length of the SEC4 configuration registers.
83           registers
84
85    - ranges
86        Usage: required
87        Value type: <prop-encoded-array>
88        Definition: A standard property.  Specifies the physical address
89            range of the SEC 4.0 register space (-SNVS not included).  A
90            triplet that includes the child address, parent address, &
91            length.
92
93    - interrupts
94       Usage: required
95       Value type: <prop_encoded-array>
96       Definition:  Specifies the interrupts generated by this
97            device.  The value of the interrupts property
98            consists of one interrupt specifier. The format
99            of the specifier is defined by the binding document
100            describing the node's interrupt parent.
101
102    - interrupt-parent
103       Usage: (required if interrupt property is defined)
104       Value type: <phandle>
105       Definition: A single <phandle> value that points
106           to the interrupt parent to which the child domain
107           is being mapped.
108
109    - clocks
110       Usage: required if SEC 4.0 requires explicit enablement of clocks
111       Value type: <prop_encoded-array>
112       Definition:  A list of phandle and clock specifier pairs describing
113           the clocks required for enabling and disabling SEC 4.0.
114
115    - clock-names
116       Usage: required if SEC 4.0 requires explicit enablement of clocks
117       Value type: <string>
118       Definition: A list of clock name strings in the same order as the
119           clocks property.
120
121    Note: All other standard properties (see the Devicetree Specification)
122    are allowed but are optional.
123
124
125 EXAMPLE
126
127 iMX6QDL/SX requires four clocks
128
129         crypto@300000 {
130                 compatible = "fsl,sec-v4.0";
131                 fsl,sec-era = <2>;
132                 #address-cells = <1>;
133                 #size-cells = <1>;
134                 reg = <0x300000 0x10000>;
135                 ranges = <0 0x300000 0x10000>;
136                 interrupt-parent = <&mpic>;
137                 interrupts = <92 2>;
138                 clocks = <&clks IMX6QDL_CLK_CAAM_MEM>,
139                          <&clks IMX6QDL_CLK_CAAM_ACLK>,
140                          <&clks IMX6QDL_CLK_CAAM_IPG>,
141                          <&clks IMX6QDL_CLK_EIM_SLOW>;
142                 clock-names = "mem", "aclk", "ipg", "emi_slow";
143         };
144
145
146 iMX6UL does only require three clocks
147
148         crypto: caam@2140000 {
149                 compatible = "fsl,sec-v4.0";
150                 #address-cells = <1>;
151                 #size-cells = <1>;
152                 reg = <0x2140000 0x3c000>;
153                 ranges = <0 0x2140000 0x3c000>;
154                 interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>;
155
156                 clocks = <&clks IMX6UL_CLK_CAAM_MEM>,
157                          <&clks IMX6UL_CLK_CAAM_ACLK>,
158                          <&clks IMX6UL_CLK_CAAM_IPG>;
159                 clock-names = "mem", "aclk", "ipg";
160         };
161
162 =====================================================================
163 Job Ring (JR) Node
164
165     Child of the crypto node defines data processing interface to SEC 4
166     across the peripheral bus for purposes of processing
167     cryptographic descriptors. The specified address
168     range can be made visible to one (or more) cores.
169     The interrupt defined for this node is controlled within
170     the address range of this node.
171
172   - compatible
173       Usage: required
174       Value type: <string>
175       Definition: Must include "fsl,sec-v4.0-job-ring"
176
177   - reg
178       Usage: required
179       Value type: <prop-encoded-array>
180       Definition: Specifies a two JR parameters:  an offset from
181           the parent physical address and the length the JR registers.
182
183    - fsl,liodn
184        Usage: optional-but-recommended
185        Value type: <prop-encoded-array>
186        Definition:
187            Specifies the LIODN to be used in conjunction with
188            the ppid-to-liodn table that specifies the PPID to LIODN mapping.
189            Needed if the PAMU is used.  Value is a 12 bit value
190            where value is a LIODN ID for this JR. This property is
191            normally set by boot firmware.
192
193    - interrupts
194       Usage: required
195       Value type: <prop_encoded-array>
196       Definition:  Specifies the interrupts generated by this
197            device.  The value of the interrupts property
198            consists of one interrupt specifier. The format
199            of the specifier is defined by the binding document
200            describing the node's interrupt parent.
201
202    - interrupt-parent
203       Usage: (required if interrupt property is defined)
204       Value type: <phandle>
205       Definition: A single <phandle> value that points
206           to the interrupt parent to which the child domain
207           is being mapped.
208
209 EXAMPLE
210         jr@1000 {
211                 compatible = "fsl,sec-v4.0-job-ring";
212                 reg = <0x1000 0x1000>;
213                 fsl,liodn = <0x081>;
214                 interrupt-parent = <&mpic>;
215                 interrupts = <88 2>;
216         };
217
218
219 =====================================================================
220 Run Time Integrity Check (RTIC) Node
221
222   Child node of the crypto node.  Defines a register space that
223   contains up to 5 sets of addresses and their lengths (sizes) that
224   will be checked at run time.  After an initial hash result is
225   calculated, these addresses are checked by HW to monitor any
226   change.  If any memory is modified, a Security Violation is
227   triggered (see SNVS definition).
228
229
230   - compatible
231       Usage: required
232       Value type: <string>
233       Definition: Must include "fsl,sec-v4.0-rtic".
234
235    - #address-cells
236        Usage: required
237        Value type: <u32>
238        Definition: A standard property.  Defines the number of cells
239            for representing physical addresses in child nodes.  Must
240            have a value of 1.
241
242    - #size-cells
243        Usage: required
244        Value type: <u32>
245        Definition: A standard property.  Defines the number of cells
246            for representing the size of physical addresses in
247            child nodes.  Must have a value of 1.
248
249   - reg
250       Usage: required
251       Value type: <prop-encoded-array>
252       Definition: A standard property.  Specifies a two parameters:
253           an offset from the parent physical address and the length
254           the SEC4 registers.
255
256    - ranges
257        Usage: required
258        Value type: <prop-encoded-array>
259        Definition: A standard property.  Specifies the physical address
260            range of the SEC 4 register space (-SNVS not included).  A
261            triplet that includes the child address, parent address, &
262            length.
263
264 EXAMPLE
265         rtic@6000 {
266                 compatible = "fsl,sec-v4.0-rtic";
267                 #address-cells = <1>;
268                 #size-cells = <1>;
269                 reg = <0x6000 0x100>;
270                 ranges = <0x0 0x6100 0xe00>;
271         };
272
273 =====================================================================
274 Run Time Integrity Check (RTIC) Memory Node
275   A child node that defines individual RTIC memory regions that are used to
276   perform run-time integrity check of memory areas that should not modified.
277   The node defines a register that contains the memory address &
278   length (combined) and a second register that contains the hash result
279   in big endian format.
280
281   - compatible
282       Usage: required
283       Value type: <string>
284       Definition: Must include "fsl,sec-v4.0-rtic-memory".
285
286   - reg
287       Usage: required
288       Value type: <prop-encoded-array>
289       Definition: A standard property.  Specifies two parameters:
290           an offset from the parent physical address and the length:
291
292           1. The location of the RTIC memory address & length registers.
293           2. The location RTIC hash result.
294
295   - fsl,rtic-region
296        Usage: optional-but-recommended
297        Value type: <prop-encoded-array>
298        Definition:
299            Specifies the HW address (36 bit address) for this region
300            followed by the length of the HW partition to be checked;
301            the address is represented as a 64 bit quantity followed
302            by a 32 bit length.
303
304    - fsl,liodn
305        Usage: optional-but-recommended
306        Value type: <prop-encoded-array>
307        Definition:
308            Specifies the LIODN to be used in conjunction with
309            the ppid-to-liodn table that specifies the PPID to LIODN
310            mapping.  Needed if the PAMU is used.  Value is a 12 bit value
311            where value is a LIODN ID for this RTIC memory region. This
312            property is normally set by boot firmware.
313
314 EXAMPLE
315         rtic-a@0 {
316                 compatible = "fsl,sec-v4.0-rtic-memory";
317                 reg = <0x00 0x20 0x100 0x80>;
318                 fsl,liodn   = <0x03c>;
319                 fsl,rtic-region  = <0x12345678 0x12345678 0x12345678>;
320         };
321
322 =====================================================================
323 Secure Non-Volatile Storage (SNVS) Node
324
325     Node defines address range and the associated
326     interrupt for the SNVS function.  This function
327     monitors security state information & reports
328     security violations. This also included rtc,
329     system power off and ON/OFF key.
330
331   - compatible
332       Usage: required
333       Value type: <string>
334       Definition: Must include "fsl,sec-v4.0-mon" and "syscon".
335
336   - reg
337       Usage: required
338       Value type: <prop-encoded-array>
339       Definition: A standard property.  Specifies the physical
340           address and length of the SEC4 configuration
341           registers.
342
343    - #address-cells
344        Usage: required
345        Value type: <u32>
346        Definition: A standard property.  Defines the number of cells
347            for representing physical addresses in child nodes.  Must
348            have a value of 1.
349
350    - #size-cells
351        Usage: required
352        Value type: <u32>
353        Definition: A standard property.  Defines the number of cells
354            for representing the size of physical addresses in
355            child nodes.  Must have a value of 1.
356
357    - ranges
358        Usage: required
359        Value type: <prop-encoded-array>
360        Definition: A standard property.  Specifies the physical address
361            range of the SNVS register space.  A triplet that includes
362            the child address, parent address, & length.
363
364    - interrupts
365       Usage: optional
366       Value type: <prop_encoded-array>
367       Definition:  Specifies the interrupts generated by this
368            device.  The value of the interrupts property
369            consists of one interrupt specifier. The format
370            of the specifier is defined by the binding document
371            describing the node's interrupt parent.
372
373    - interrupt-parent
374       Usage: (required if interrupt property is defined)
375       Value type: <phandle>
376       Definition: A single <phandle> value that points
377           to the interrupt parent to which the child domain
378           is being mapped.
379
380 EXAMPLE
381         sec_mon@314000 {
382                 compatible = "fsl,sec-v4.0-mon", "syscon";
383                 reg = <0x314000 0x1000>;
384                 ranges = <0 0x314000 0x1000>;
385                 interrupt-parent = <&mpic>;
386                 interrupts = <93 2>;
387         };
388
389 =====================================================================
390 Secure Non-Volatile Storage (SNVS) Low Power (LP) RTC Node
391
392   A SNVS child node that defines SNVS LP RTC.
393
394   - compatible
395       Usage: required
396       Value type: <string>
397       Definition: Must include "fsl,sec-v4.0-mon-rtc-lp".
398
399   - interrupts
400       Usage: required
401       Value type: <prop_encoded-array>
402       Definition: Specifies the interrupts generated by this
403            device.  The value of the interrupts property
404            consists of one interrupt specifier. The format
405            of the specifier is defined by the binding document
406            describing the node's interrupt parent.
407
408  - regmap
409         Usage: required
410         Value type: <phandle>
411         Definition: this is phandle to the register map node.
412
413  - offset
414         Usage: option
415         value type: <u32>
416         Definition: LP register offset. default it is 0x34.
417
418 EXAMPLE
419         sec_mon_rtc_lp@1 {
420                 compatible = "fsl,sec-v4.0-mon-rtc-lp";
421                 interrupts = <93 2>;
422                 regmap = <&snvs>;
423                 offset = <0x34>;
424         };
425
426 =====================================================================
427 System ON/OFF key driver
428
429   The snvs-pwrkey is designed to enable POWER key function which controlled
430   by SNVS ONOFF, the driver can report the status of POWER key and wakeup
431   system if pressed after system suspend.
432
433   - compatible:
434       Usage: required
435       Value type: <string>
436       Definition: Mush include "fsl,sec-v4.0-pwrkey".
437
438   - interrupts:
439       Usage: required
440       Value type: <prop_encoded-array>
441       Definition: The SNVS ON/OFF interrupt number to the CPU(s).
442
443   - linux,keycode:
444       Usage: option
445       Value type: <int>
446       Definition: Keycode to emit, KEY_POWER by default.
447
448   - wakeup-source:
449       Usage: option
450       Value type: <boo>
451       Definition: Button can wake-up the system.
452
453  - regmap:
454       Usage: required:
455       Value type: <phandle>
456       Definition: this is phandle to the register map node.
457
458 EXAMPLE:
459         snvs-pwrkey@0x020cc000 {
460                 compatible = "fsl,sec-v4.0-pwrkey";
461                 regmap = <&snvs>;
462                 interrupts = <0 4 0x4>
463                 linux,keycode = <116>; /* KEY_POWER */
464                 wakeup-source;
465         };
466
467 =====================================================================
468 FULL EXAMPLE
469
470         crypto: crypto@300000 {
471                 compatible = "fsl,sec-v4.0";
472                 #address-cells = <1>;
473                 #size-cells = <1>;
474                 reg = <0x300000 0x10000>;
475                 ranges = <0 0x300000 0x10000>;
476                 interrupt-parent = <&mpic>;
477                 interrupts = <92 2>;
478
479                 sec_jr0: jr@1000 {
480                         compatible = "fsl,sec-v4.0-job-ring";
481                         reg = <0x1000 0x1000>;
482                         interrupt-parent = <&mpic>;
483                         interrupts = <88 2>;
484                 };
485
486                 sec_jr1: jr@2000 {
487                         compatible = "fsl,sec-v4.0-job-ring";
488                         reg = <0x2000 0x1000>;
489                         interrupt-parent = <&mpic>;
490                         interrupts = <89 2>;
491                 };
492
493                 sec_jr2: jr@3000 {
494                         compatible = "fsl,sec-v4.0-job-ring";
495                         reg = <0x3000 0x1000>;
496                         interrupt-parent = <&mpic>;
497                         interrupts = <90 2>;
498                 };
499
500                 sec_jr3: jr@4000 {
501                         compatible = "fsl,sec-v4.0-job-ring";
502                         reg = <0x4000 0x1000>;
503                         interrupt-parent = <&mpic>;
504                         interrupts = <91 2>;
505                 };
506
507                 rtic@6000 {
508                         compatible = "fsl,sec-v4.0-rtic";
509                         #address-cells = <1>;
510                         #size-cells = <1>;
511                         reg = <0x6000 0x100>;
512                         ranges = <0x0 0x6100 0xe00>;
513
514                         rtic_a: rtic-a@0 {
515                                 compatible = "fsl,sec-v4.0-rtic-memory";
516                                 reg = <0x00 0x20 0x100 0x80>;
517                         };
518
519                         rtic_b: rtic-b@20 {
520                                 compatible = "fsl,sec-v4.0-rtic-memory";
521                                 reg = <0x20 0x20 0x200 0x80>;
522                         };
523
524                         rtic_c: rtic-c@40 {
525                                 compatible = "fsl,sec-v4.0-rtic-memory";
526                                 reg = <0x40 0x20 0x300 0x80>;
527                         };
528
529                         rtic_d: rtic-d@60 {
530                                 compatible = "fsl,sec-v4.0-rtic-memory";
531                                 reg = <0x60 0x20 0x500 0x80>;
532                         };
533                 };
534         };
535
536         sec_mon: sec_mon@314000 {
537                 compatible = "fsl,sec-v4.0-mon";
538                 reg = <0x314000 0x1000>;
539                 ranges = <0 0x314000 0x1000>;
540
541                 sec_mon_rtc_lp@34 {
542                         compatible = "fsl,sec-v4.0-mon-rtc-lp";
543                         regmap = <&sec_mon>;
544                         offset = <0x34>;
545                         interrupts = <93 2>;
546                 };
547
548                 snvs-pwrkey@0x020cc000 {
549                         compatible = "fsl,sec-v4.0-pwrkey";
550                         regmap = <&sec_mon>;
551                         interrupts = <0 4 0x4>;
552                         linux,keycode = <116>; /* KEY_POWER */
553                         wakeup-source;
554                 };
555         };
556
557 =====================================================================