1 /*
2 * Copyright (C) 2020 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 #pragma once
18
19 #include <lk/compiler.h>
20 #include <stdbool.h>
21 #include <stddef.h>
22 #include <stdint.h>
23
24 __BEGIN_CDECLS
25
26 /**
27 * translate_srv_err() - translate SPI error code to LK error code
28 * @srv_err: SPI error code - one of &enum spi_srv_err
29 *
30 * Returns: one of LK error codes
31 */
32 int translate_srv_err(uint32_t srv_err);
33
34 /**
35 * translate_lk_err() - translate LK error code to SPI error code
36 * @rc: LK error code
37 *
38 * Returns: one of &enum spi_srv_err
39 */
40 uint32_t translate_lk_err(int rc);
41
42 /**
43 * mem_buf - tracks state of a memory buffer
44 * @buf: pointer to the buffer
45 * @capacity: capacity of @buf
46 * @align: alignment requirement for @buf and @pos
47 * @curr_size: current size of @buf, must not exceed @capacity
48 * @pos: offset to the current position in @buf
49 */
50 struct mem_buf {
51 uint8_t* buf;
52 size_t capacity;
53 size_t align;
54 size_t curr_size;
55 size_t pos;
56 };
57
58 /**
59 * mb_curr_pos() - get current position of memory buffer
60 * @mb: pointer to memory buffer - see &struct mem_buf
61 *
62 * Return: current position of @mb
63 */
mb_curr_pos(struct mem_buf * mb)64 static inline size_t mb_curr_pos(struct mem_buf* mb) {
65 return mb->pos;
66 }
67
68 /**
69 * mb_size() - get current size of memory buffer
70 * @mb: pointer to memory buffer - see &struct mem_buf
71 *
72 * return: size of @mb
73 */
mb_size(struct mem_buf * mb)74 static inline size_t mb_size(struct mem_buf* mb) {
75 return mb->curr_size;
76 }
77
78 /**
79 * mb_space_left() - get number of bytes available in memory buffer
80 * @mb: pointer to memory buffer - see &struct mem_buf
81 *
82 * return: amount of space available in @mb
83 */
mb_space_left(struct mem_buf * mb)84 static inline size_t mb_space_left(struct mem_buf* mb) {
85 return mb_size(mb) - mb_curr_pos(mb);
86 }
87
88 /**
89 * mb_rewind_pos() - rewind position of memory buffer back to zero
90 * @mb: pointer to memory buffer - see &struct mem_buf
91 */
mb_rewind_pos(struct mem_buf * mb)92 static inline void mb_rewind_pos(struct mem_buf* mb) {
93 mb->pos = 0;
94 }
95
96 /**
97 * mb_init() - initialize memory buffer
98 * @mb: pointer to memory buffer - see &struct mem_buf
99 * @buf: pointer to the buffer
100 * @cap: capacity of @buf
101 * @align: alignment requirement
102 *
103 * Set initial @curr_size to 0. @buf must be aligned by @align.
104 */
105 void mb_init(struct mem_buf* mb, void* buf, size_t cap, size_t align);
106
107 /**
108 * mb_destroy() - destroy memory buffer
109 * @mb: pointer to memory buffer - see &struct mem_buf
110 *
111 * After calling this routine, mb_init() is the only valid operation on @mb.
112 * Other operations will return an error.
113 */
114 void mb_destroy(struct mem_buf* mb);
115
116 /**
117 * mb_resize() - resize memory buffer
118 * @mb: pointer to memory buffer - see &struct mem_buf
119 * @sz: new size of memory buffer in bytes
120 *
121 * Successfully resizing @mb resets @pos to zero. @sz can not exceed capacity of
122 * @mb.
123 *
124 * Return: true on success, false otherwise
125 */
126 bool mb_resize(struct mem_buf* mb, size_t sz);
127
128 /**
129 * mb_advance_pos() - advance memory buffer position by a given amount
130 * @mb: pointer to memory buffer - see &struct mem_buf
131 * @sz: number of bytes to advance buffer position by
132 *
133 * This routine can only advance @mb's position by a multiple of the alignment
134 * specified by mb_init(). It rounds @sz up to meet the alignment requirement.
135 * Note that as consequence return pointer is also always aligned.
136 *
137 * Return: pointer to current position in memory buffer if possible to advance
138 * position by @size, NULL otherwise
139 */
140 void* mb_advance_pos(struct mem_buf* mb, size_t sz);
141
142 __END_CDECLS
143