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 =====================================================================