source: trunk/tools/bootloader_tsar/boot_utils.h @ 1

Last change on this file since 1 was 1, checked in by alain, 8 years ago

First import
File size: 15.0 KB
Line 
1/****************************************************************************
2 * This file defines various utility functions for the boot code.           *
3 *                                                                          *
4 * These functions are classified as follows:                               *
5 *  - Remote accesses,                                                      *
6 *  - Atomic operations,                                                    *
7 *  - Memory functions,                                                     *
8 *  - String functions,                                                     *
9 *  - Display functions,                                                    *
10 *  - Miscellaneous functions,                                              *
11 *                                                                          *
12 * Note that <stdint.h> and <stdarg.h> headers only contain macros, defined *
13 * by the compiler itself, thus are accepted in the boot-loader, in         *
14 * constrast to other headers in the C standard library.                    *
15 ****************************************************************************/
16
17#ifndef _BOOT_UTILS_H
18#define _BOOT_UTILS_H
19
20#include <hal_types.h>
21#include <hard_config.h>
22
23/****************************************************************************
24 *                             Remote accesses.                             *
25 ****************************************************************************/
26
27/****************************************************************************
28 * This function reads an aligned 32-bit word from another memory address   *
29 * space.                                                                   *
30 * @ xp     : extended pointer to the distant memory location to be read    *
31 *            from.                                                         *
32 *                                                                          *
33 * @ returns the value read.                                                *
34 ****************************************************************************/
35uint32_t boot_remote_lw(xptr_t xp);
36
37/****************************************************************************
38 * This function writes an aligned 32-bit word in another memory address    *
39 * space.                                                                   *
40 * @ xp     : extended pointer to the distant memory location to be written *
41 *            to.                                                           *
42 * @ data   : data value to be written to the distant memory location.      *
43 ****************************************************************************/
44void boot_remote_sw(xptr_t xp, uint32_t data);
45
46/****************************************************************************
47 * This function atomically adds an value 'val' to the current value stored *
48 * at a distant memory location pointed to by the extended pointer 'xp'.    *
49 * @ xp     : extended pointer to the distant memory location whose value   *
50 *            is to be modified.                                            *
51 * @ val    : signed value to be added.                                     *
52 *                                                                          *
53 * @ returns the value stored at the distant memory location BEFORE the     *
54 *   atomic operation.                                                      *
55 ****************************************************************************/
56int32_t boot_remote_atomic_add(xptr_t xp, int32_t val);
57
58/****************************************************************************
59 * This function copies 'size' bytes from the buffer pointed to by 'src'    *
60 * to the buffer pointed to by 'dest'. These 2 addresses may be in any      *
61 * different memory address spaces.                                         *
62 * @ dest   : extended pointer to the destination buffer.                   *
63 * @ src    : extended pointer to the source buffer.                        *
64 * @ size   : size of memory block to be copied (in bytes).                 *   
65 ****************************************************************************/
66void boot_remote_memcpy(xptr_t dest, xptr_t src, unsigned int size);
67
68/****************************************************************************
69 *                            Atomic operations.                            *
70 ****************************************************************************/
71
72/****************************************************************************
73 * This function atomically adds an value 'val' to the current variable     *
74 * pointed to by 'ptr'. It only returns when the atomic operation is        *
75 * successful.                                                              *
76 * @ ptr    : pointer to the variable to be modified.                       *
77 * @ val    : signed value to be added.                                     *
78 *                                                                          *
79 * @ returns the value of the variable BEFORE the atomic operation.         *
80 ****************************************************************************/
81int32_t boot_atomic_add(int32_t* ptr, int32_t val);
82
83/****************************************************************************
84 *                            Memory functions.                             *
85 ****************************************************************************/
86
87/****************************************************************************
88 * This function performs a local memory copy (destination and source       *
89 * addresses are in the same memory space) of 'size' bytes from 'src'       *
90 * address to 'dest' address.                                               *
91 * @ dest   : destination physical address,                                 *
92 * @ src    : source physical address,                                      *
93 * @ size   : size of memory block to be copied in bytes.                   *
94 ****************************************************************************/
95void boot_memcpy(void* dest, void* src, unsigned int size);
96
97/****************************************************************************
98 * This function fills the first 'size' bytes of the local memory area,     *
99 * pointed to by 'base' with a constant value 'val'.                        *
100 * @ base   : base address of the memory area to be initialized,            *
101 * @ val    : value of the constant byte to initialize the area,            *
102 * @ size   : size of memory block to be filled in bytes.                   *
103 ****************************************************************************/
104void boot_memset(void* base, int val,   unsigned int size);
105
106/****************************************************************************
107 *                            String functions                              *
108 ****************************************************************************/
109
110/****************************************************************************
111 * This function converts the letter 'c' to lower case, if possible.        *
112 * @ c  : letter to be converted.                                           *
113 *                                                                          *
114 * @ returns the converted letter, or 'c' if the conversion was not         *
115 *   possible.                                                              *
116 ****************************************************************************/
117static inline unsigned char boot_to_lower(unsigned char c)
118{
119    return ((c >= 'A') && (c <= 'Z')) ? (c | 0x20) : c;
120
121} // boot_to_lower()
122
123/****************************************************************************
124 * This function converts the letter 'c' to upper case, if possible.        *
125 * @ c  : letter to be converted.                                           *
126 *                                                                          *
127 * @ returns the converted letter, or 'c' if the conversion was not         *
128 *   possible.                                                              *
129 ****************************************************************************/
130static inline unsigned char boot_to_upper(unsigned char c)
131{
132    return ((c >= 'a') && (c <= 'z')) ? (c & ~(0x20)) : c;
133
134} // boot_to_upper()
135
136/****************************************************************************
137 * This function copies the string pointed to by 'src' (the terminating     *
138 * null byte '\0' NOT included) to the buffer pointed to by 'dest'.         *
139 * @ src    : pointer to the string to be copied.                           *
140 * @ dest   : pointer to the destination string.                            *
141 ****************************************************************************/
142void boot_strcpy(char* dest, char* src);
143
144/****************************************************************************
145 * This function calculates the length of the string pointed to by 's',     *
146 * excluding the terminating null byte '\0'.                                *
147 * @ s  : pointer to the string whose length is to be computed.             *
148 *                                                                          *
149 * @ returns the number of bytes in the string.                             *
150 ****************************************************************************/
151unsigned int boot_strlen(char* s);
152
153/****************************************************************************
154 * This function compares the 2 strings pointed to by 's1' and 's2'.        *
155 * @ s1 : pointer to the first string to be compared.                       *
156 * @ s2 : pointer to the second string to be compared.                      *
157 *                                                                          *
158 * @ returns 0 if these 2 strings match, 1 otherwise.                       *
159 ****************************************************************************/
160int boot_strcmp(char* s1, char* s2);
161
162/****************************************************************************
163 *                            Display functions                             *
164 ****************************************************************************/
165
166/****************************************************************************
167 * This function writes the NUL terminated string pointed to by 'str' to    *
168 * the boot TTY terminal.                                                   *
169 * @ str    : pointer to the string to be printed on the boot TTY terminal. *
170 ****************************************************************************/
171void boot_puts(char* str);
172
173/****************************************************************************
174 * This function produces output, according to the 'format' format, to the  *
175 * boot TTY terminal.                                                       *
176 * @ format : the string defining the format of the output. It is composed  *
177 *            of 0 or more directives:                                      *
178 *            - ordinary characters (not %), which are copied unchanged to  *
179 *              the boot TTY terminal.                                      *
180 *            - conversion specifications (introduced by the character %,   *
181 *              ended by a conversion specifier), each of which results in  *
182 *              fetching 0 or more subsequent arguments. The arguments must *
183 *              correspond properly (after type promotion) with the         *
184 *              conversion specifier.                                       *
185 *                                                                          *
186 * Conversion specifiers:                                                   *
187 *  - %d : 32-bit signed decimal notation of an integer,                    *
188 *  - %u : 32-bit unsigned decimal notation of an integer,                  *
189 *  - %x : 32-bit unsigned hexadecimal notation of an integer,              *
190 *  - %l : 64-bit unsigned hexadecimal notation of an integer,              *
191 *  - %c : character,                                                       *
192 *  - %s : NUL terminated string.                                           *
193 ****************************************************************************/
194void boot_printf(char* format, ...);
195
196/****************************************************************************
197 *                            Misc. functions.                              *
198 ****************************************************************************/
199
200/****************************************************************************
201 * This function causes a termination during the boot procedure once the    *
202 * boot code detects an error.                                              *
203 ****************************************************************************/
204void boot_exit() __attribute__((noreturn));
205
206/****************************************************************************
207 * This function returns the cycle count stored in the CP0_COUNT register   *
208 * of the currently running processor.                                      *
209 *                                                                          *
210 * @ returns the processor cycle count.                                     *
211 ****************************************************************************/
212unsigned int boot_get_proctime();
213
214/****************************************************************************
215 * This function returns the global hardware identifier gid stored in the   *
216 * CP0_PROCID register of the currently running processor.                  *
217 *                                                                          *
218 * @ returns the processor gid.                                             *
219 ****************************************************************************/
220unsigned int boot_get_procid();
221
222/****************************************************************************
223 * This structure defines a toggling barrier, that can be used to           *
224 * synchronize a group of cores, whether or not they are in a same cluster, *
225 * without any specific initialization.                                     *
226 ****************************************************************************/
227typedef struct boot_barrier_s
228{
229    uint32_t current;                      // Number of arrived cores
230    uint32_t sense;                        // Toggle barrier state
231    uint32_t pad[(CACHE_LINE_SIZE>>2)-2];  // Padding
232}
233boot_barrier_t;
234
235/****************************************************************************
236 * This function blocks all processors arriving at the barrier pointed to   *
237 * by the extend pointer 'xp_barrier' and only returns when all 'count'     *
238 * expected processors reach the barrier.                                   *
239 * @ xp_barrier : extended pointer to a toggling barrier.                   *
240 * @ count      : number of expected processors.                            *
241 ****************************************************************************/
242void boot_barrier( xptr_t   xp_barrier, 
243                   uint32_t count );
244
245
246#endif // _BOOT_UTILS_H
Note: See TracBrowser for help on using the repository browser.