1 /*
2  * Copyright (C) 2023 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*
18 This defines the messages between various secure world applications that
19 have been instrumented and the coverage aggregator. The shared memory is passed
20 onto those application via this.
21 */
22 
23 #pragma once
24 
25 #include <lk/compiler.h>
26 #include <stdint.h>
27 
28 __BEGIN_CDECLS
29 
30 #define LINE_COVERAGE_AGGREGATOR_PORT "com.android.trusty.linecoverage.aggregator"
31 
32 /**
33  * enum line_coverage_aggregator_cmd - command identifiers for coverage aggregator
34  *                                interface
35  * @LINE_COVERAGE_AGGREGATOR_CMD_RESP_BIT:   response bit set as part of response
36  * @LINE_COVERAGE_AGGREGATOR_CMD_SHIFT:      number of bits used by response bit
37  * @LINE_COVERAGE_AGGREGATOR_CMD_REGISTER:   command to register with coverage
38  *                                      aggregator
39  * @LINE_COVERAGE_AGGREGATOR_CMD_GET_RECORD: command to get shared memory region
40  *                                      where coverage record will be written to
41  */
42 enum line_coverage_aggregator_cmd {
43     LINE_COVERAGE_AGGREGATOR_CMD_RESP_BIT = 1U,
44     LINE_COVERAGE_AGGREGATOR_CMD_SHIFT = 1U,
45     LINE_COVERAGE_AGGREGATOR_CMD_REGISTER = (1U << LINE_COVERAGE_AGGREGATOR_CMD_SHIFT),
46     LINE_COVERAGE_AGGREGATOR_CMD_GET_RECORD = (2U << LINE_COVERAGE_AGGREGATOR_CMD_SHIFT),
47 };
48 
49 /**
50  * struct line_coverage_aggregator_hdr - header for coverage aggregator messages
51  * @cmd: command identifier
52  *
53  * Note that no messages return a status code. Any error on the server side
54  * results in the connection being closed. So, operations can be assumed to be
55  * successful if they return a response.
56  */
57 struct line_coverage_aggregator_hdr {
58     uint32_t cmd;
59 };
60 
61 /**
62  * struct line_coverage_aggregator_register_req - arguments for request to register
63  *                                           with coverage aggregator
64  * @record_len: length of coverage record that will be emitted by this TA
65  */
66 struct line_coverage_aggregator_register_req {
67     uint32_t record_len;
68 };
69 
70 /**
71  * struct line_coverage_aggregator_register_resp - arguments for response to register
72  *                                           with coverage aggregator
73  * @idx:         unique index assigned to this TA
74  * @mailbox_len: length of memory region used as a mailbox
75  *
76  * A handle to a memory region must be sent along with this message. This memory
77  * is used by coverage server to drop messages that TAs asynchronously respond
78  * to. Possible mailbox messages are defined by &enum line_coverage_mailbox_event.
79  */
80 struct line_coverage_aggregator_register_resp {
81     uint32_t idx;
82     uint32_t mailbox_len;
83 };
84 
85 /**
86  * struct line_coverage_aggregator_get_record_resp - arguments for response to get
87  *                                             shared memory for coverage record
88  * @shm_len: length of memory region being shared
89  *
90  * A handle to a memory region must be sent along with this message. This memory
91  * is used to identify and send coverage record.
92  */
93 struct line_coverage_aggregator_get_record_resp {
94     uint32_t shm_len;
95 };
96 
97 /**
98  * struct line_coverage_aggregator_req - structure for a coverage aggregator request
99  * @hdr:           message header
100  * @register_args: arguments for %COVERAGE_AGGREGATOR_CMD_REGISTER request
101  */
102 struct line_coverage_aggregator_req {
103     struct line_coverage_aggregator_hdr hdr;
104     union {
105         struct line_coverage_aggregator_register_req register_args;
106     };
107 };
108 
109 /**
110  * struct line_coverage_aggregator_resp - structure for a coverage aggregator
111  *                                   response
112  * @hdr:             message header
113  * @register_args:   arguments for %COVERAGE_AGGREGATOR_CMD_REGISTER response
114  * @get_record_args: arguments for %COVERAGE_AGGREGATOR_CMD_GET_RECORD response
115  */
116 struct line_coverage_aggregator_resp {
117     struct line_coverage_aggregator_hdr hdr;
118     union {
119         struct line_coverage_aggregator_register_resp register_args;
120         struct line_coverage_aggregator_get_record_resp get_record_args;
121     };
122 };
123 
124 /**
125  * enum line_coverage_mailbox_event - mailbox messages
126  * @LINE_COVERAGE_MAILBOX_EMPTY:        mailbox is empty
127  * @LINE_COVERAGE_MAILBOX_RECORD_READY: shared memory for coverage record is ready
128  */
129 enum line_coverage_mailbox_event {
130     LINE_COVERAGE_MAILBOX_EMPTY = 0U,
131     LINE_COVERAGE_MAILBOX_RECORD_READY = 1U,
132 };
133 
134 __END_CDECLS
135