1 /*
2  * Copyright (c) 2022 Google Inc. All rights reserved
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining
5  * a copy of this software and associated documentation files
6  * (the "Software"), to deal in the Software without restriction,
7  * including without limitation the rights to use, copy, modify, merge,
8  * publish, distribute, sublicense, and/or sell copies of the Software,
9  * and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be
13  * included in all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22  */
23 
24 #pragma once
25 
26 /*
27  * ARM True Random Number Generator Firmware Interface
28  * (https://developer.arm.com/documentation/den0098/latest).
29  */
30 
31 #include <lib/sm/smcall.h>
32 
33 #define SMC_TRNG_CURRENT_MAJOR_VERSION 1
34 
35 /**
36  * enum trng_error - TRNG error code
37  * @TRNG_ERROR_NOT_SUPPORTED:
38  *         Operation is not supported by the current implementation.
39  * @TRNG_ERROR_INVALID_PARAMETER:
40  *         Invalid parameter. Conditions function specific.
41  * @TRNG_ERROR_NO_ENTROPY:
42  *         No entropy.
43  */
44 enum trng_error {
45     TRNG_ERROR_NOT_SUPPORTED = -1,
46     TRNG_ERROR_INVALID_PARAMETER = -2,
47     TRNG_ERROR_NO_ENTROPY = -3,
48 };
49 
50 /**
51  * SMC_FC_TRNG_VERSION - SMC opcode to return supported TRNG version
52  *
53  * Register arguments:
54  *
55  * * w1-w7:  Must be 0.
56  *
57  * Return:
58  * * w0:     Major version bit[30:16], minor version in bit[15:0], bit[31] must
59  *           be 0.
60  * * w1-w3:  Must be 0.
61  *
62  * or
63  *
64  * * w0:     %TRNG_ERROR_NOT_SUPPORTED.
65  */
66 #define SMC_FC_TRNG_VERSION SMC_FASTCALL_NR(SMC_ENTITY_STD, 0x50)
67 
68 /**
69  * SMC_FC_TRNG_FEATURES - SMC opcode to check optional feature support
70  *
71  * Register arguments:
72  *
73  * * w1:     TRNG function ID
74  * * w2-w7:  Must be 0.
75  *
76  * Return:
77  * * w0:     Function-specific features if the function is implemented.
78  *
79  * or
80  *
81  * * w0:     %TRNG_ERROR_NOT_SUPPORTED.
82  */
83 #define SMC_FC_TRNG_FEATURES SMC_FASTCALL_NR(SMC_ENTITY_STD, 0x51)
84 
85 /**
86  * SMC_FC_GET_UUID - SMC opcode to retrieve the UUID of the TRNG back end.
87  *
88  * Register arguments:
89  *
90  * * w1-w7:  Must be 0.
91  *
92  * Return:
93  * * w0:     UUID[31:0].
94  * * w1:     UUID[63:32].
95  * * w2:     UUID[95:64].
96  * * w3:     UUID[127:96].
97  *
98  * or
99  *
100  * * w0:     %TRNG_ERROR_NOT_SUPPORTED.
101  */
102 #define SMC_FC_TRNG_GET_UUID SMC_FASTCALL_NR(SMC_ENTITY_STD, 0x52)
103 
104 /**
105  * SMC_FC_TRNG_RND - SMC opcode to request N bits of entropy.
106  *
107  * Register arguments:
108  *
109  * * w1:     Bits of entropy requested, between 1 and 96.
110  * * w2-w7:  Must be 0.
111  *
112  * Return:
113  * * w0:     Must be 0.
114  * * w1:     Entropy[95:64].
115  * * w2:     Entropy[63:32].
116  * * w3:     Entropy[31:0].
117  *
118  * or
119  *
120  * * w0:     One of &enum trng_error.
121  * * w1-w3:  Must be 0.
122  */
123 #define SMC_FC_TRNG_RND SMC_FASTCALL_NR(SMC_ENTITY_STD, 0x53)
124 
125 /**
126  * SMC_FC64_TRNG_RND - SMC opcode to request N bits of entropy.
127  *
128  * Register arguments:
129  *
130  * * x1:     Bits of entropy requested, between 1 and 192.
131  * * x2-x7:  Must be 0.
132  *
133  * Return:
134  * * x0:     Must be 0.
135  * * x1:     Entropy[191:128].
136  * * x2:     Entropy[127:64].
137  * * x3:     Entropy[63:0].
138  *
139  * or
140  *
141  * * x0:     One of &enum trng_error.
142  * * x1-x3:  Must be 0.
143  */
144 #define SMC_FC64_TRNG_RND SMC_FASTCALL64_NR(SMC_ENTITY_STD, 0x53)
145