source: trunk/boot/tsar_mips32/boot_utils.h @ 523

Last change on this file since 523 was 523, checked in by viala@…, 6 years ago

[boot] Remove testing if a pointer is null.

It's a bad practice in a lib to hide undesired null pointers.
Using an assert is better.

File size: 14.4 KB
RevLine 
[439]1/*
2 * boot_utils.h - TSAR bootloader utilities definition.
3 *
4 * Authors :   Alain Greiner / Vu Son  (2016)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24/****************************************************************************
25 * This file defines various utility functions for the boot code.           *
26 *                                                                          *
27 * These functions are classified as follows:                               *
28 *  - Remote accesses,                                                      *
29 *  - Atomic operations,                                                    *
30 *  - Memory functions,                                                     *
31 *  - String functions,                                                     *
32 *  - Display functions,                                                    *
33 *  - Miscellaneous functions,                                              *
34 *                                                                          *
35 * Note that <stdint.h> and <stdarg.h> headers only contain macros, defined *
36 * by the compiler itself, thus are accepted in the boot-loader, in         *
37 * constrast to other headers in the C standard library.                    *
38 ****************************************************************************/
39
40#ifndef _BOOT_UTILS_H
41#define _BOOT_UTILS_H
42
[457]43#include <hal_kernel_types.h>
[439]44#include <hard_config.h>
45
46/****************************************************************************
47 *                             Remote accesses.                             *
48 ****************************************************************************/
49
50/****************************************************************************
51 * This function reads an aligned 32-bit word from a remote cluster.
52 * @ xp     : extended pointer to the distant memory location.
53 * @ returns the value read.     
54 ****************************************************************************/
55uint32_t boot_remote_lw(xptr_t xp);
56
57/****************************************************************************
58 * This function writes an aligned 32-bit word to a remote cluster.
59 * @ xp     : extended pointer to the distant memory location.
60 * @ data   : data value to be written.
61 ****************************************************************************/
62void boot_remote_sw(xptr_t xp, uint32_t data);
63
64/****************************************************************************
65 * This function atomically adds a value 'val' to the current value stored
66 * in a remote cluster.
67 * @ xp     : extended pointer to the distant memory location.
68 * @ val    : signed value to be added.
69 * @ returns the value stored BEFORE the atomic operation.
70 ****************************************************************************/
71int32_t boot_remote_atomic_add(xptr_t xp, int32_t val);
72
73/****************************************************************************
74 * This function copies 'size' bytes from the buffer pointed to by 'src'
75 * to the buffer pointed to by 'dest'. These 2 addresses may be in any
76 * different memory address spaces. 
77 * @ dest   : extended pointer to the destination buffer.
78 * @ src    : extended pointer to the source buffer.
79 * @ size   : size of memory block to be copied (in bytes).   
80 ****************************************************************************/
81void boot_remote_memcpy(xptr_t dest, xptr_t src, uint32_t size);
82
83/****************************************************************************
84 *                            Atomic operations.                            *
85 ****************************************************************************/
86
87/****************************************************************************
88 * This function atomically adds an value 'val' to the current variable 
89 * pointed to by 'ptr'. It only returns when the atomic operation is
90 * successful. 
91 * @ ptr    : pointer to the variable to be modified. 
92 * @ val    : signed value to be added.
93 * @ returns the value of the variable BEFORE the atomic operation. 
94 ****************************************************************************/
95int32_t boot_atomic_add(int32_t* ptr, int32_t val);
96
97/****************************************************************************
98 *                            Memory functions.                             *
99 ****************************************************************************/
100
101/****************************************************************************
102 * This function performs a local memory copy (destination and source 
103 * addresses are in the same memory space) of 'size' bytes from 'src'
104 * address to 'dest' address.                   
105 * @ dest   : destination physical address, 
106 * @ src    : source physical address,   
107 * @ size   : size of memory block to be copied in bytes.
108 ****************************************************************************/
109void boot_memcpy(void* dest, void* src, uint32_t size);
110
111/****************************************************************************
112 * This function fills the first 'size' bytes of the local memory area,
113 * pointed to by 'base' with a constant value 'val'.                 
114 * @ base   : base address of the memory area to be initialized,   
115 * @ val    : value of the constant byte to initialize the area,
116 * @ size   : size of memory block to be filled in bytes.   
117 ****************************************************************************/
118void boot_memset(void* base, int val,   uint32_t size);
119
120/****************************************************************************
121 *                            String functions                              *
122 ****************************************************************************/
123
124/****************************************************************************
125 * This function converts the letter 'c' to lower case, if possible.
126 * @ c  : letter to be converted.                   
127 * @ returns the converted letter, or 'c' if conversion not possible.
128 ****************************************************************************/
129static inline unsigned char boot_to_lower(unsigned char c)
130{
131    return ((c >= 'A') && (c <= 'Z')) ? (c | 0x20) : c;
132
133} // boot_to_lower()
134
135/****************************************************************************
136 * This function converts the letter 'c' to upper case, if possible.
137 * @ c  : letter to be converted.
138 * @ returns the converted letter, or 'c' if conversion not possible.
139 ****************************************************************************/
140static inline unsigned char boot_to_upper(unsigned char c)
141{
142    return ((c >= 'a') && (c <= 'z')) ? (c & ~(0x20)) : c;
143
144} // boot_to_upper()
145
146/****************************************************************************
[523]147 * This function copies the string pointed to by 'src' (the terminating
148 * null byte '\0' NOT included) to the buffer pointed to by 'dest'.
149 * @ src    : pointer to the string to be copied, should be not NULL.
150 * @ dest   : pointer to the destination string, should be not NULL.
[439]151 ****************************************************************************/
[521]152void boot_strcpy( char* dest, const char * src );
[439]153
154/****************************************************************************
155 * This function calculates the length of the string pointed to by 's',
[523]156 * excluding the terminating null byte '\0'.
157 * @ s  : pointer to the string whose length is to be computed,
158 *        this pointer should be not NULL.
159 * @ returns the number of bytes in the string.
[439]160 ****************************************************************************/
[521]161uint32_t boot_strlen( const char * s );
[439]162
163/****************************************************************************
164 * This function compares the 2 strings pointed to by 's1' and 's2'.
[523]165 * If pointers point to the same adress assumed to be equals.
166 * @ s1 : pointer to the first string to be compared, should be not NULL.
167 * @ s2 : pointer to the second string to be compared, should be not NULL.
168 * @ returns 0 if these 2 strings match, 1 otherwise.
[439]169 ****************************************************************************/
[521]170int boot_strcmp( const char * s1, const char * s2 );
[439]171
172/****************************************************************************
173 *                            Display functions                             *
174 ****************************************************************************/
175
176/****************************************************************************
177 * This function writes the NUL terminated string pointed to by 'str'
178 * to the boot TTY terminal.                           
179 * @ str    : pointer to the string to be printed on the boot TTY terminal.
180 ****************************************************************************/
[521]181void boot_puts( const char* str );
[439]182
183/****************************************************************************
184 * This function produces output, according to the 'format' format, to the
185 * boot TTY terminal.
186 * @ format : the string defining the format of the output. It is composed
187 *            of 0 or more directives:                                 
188 *            - ordinary characters (not %), which are copied unchanged to
189 *              the boot TTY terminal.                                 
190 *            - conversion specifications (introduced by the character %,
191 *              ended by a conversion specifier), each of which results in
192 *              fetching 0 or more subsequent arguments. The arguments must
193 *              correspond properly (after type promotion) with the 
194 *              conversion specifier.                           
195 *                                                           
196 * Conversion specifiers:                                 
197 *  - %d : 32-bit signed decimal notation of an integer, 
198 *  - %u : 32-bit unsigned decimal notation of an integer,
199 *  - %x : 32-bit unsigned hexadecimal notation of an integer,
200 *  - %l : 64-bit unsigned hexadecimal notation of an integer,
201 *  - %c : character,                                     
202 *  - %s : NUL terminated string. 
203 ****************************************************************************/
[521]204void boot_printf( const char* format, ... );
[439]205
206/****************************************************************************
207 *                            Misc. functions.                              *
208 ****************************************************************************/
209
210/****************************************************************************
211 * This function causes a termination during the boot procedure once the
212 * boot code detects an error.
213 ****************************************************************************/
[474]214void boot_exit( void ) __attribute__((noreturn));
[439]215
216/****************************************************************************
217 * This function returns the cycle count stored in the CP0_COUNT register
218 * of the currently running processor. 
219 * @ returns the processor cycle count.
220 ****************************************************************************/
[474]221uint32_t boot_get_proctime( void );
[439]222
223/****************************************************************************
224 * This function returns the global hardware identifier gid stored in the
225 * CP0_PROCID register of the currently running processor.
226 * @ returns the processor gid
227 ****************************************************************************/
[474]228uint32_t boot_get_procid( void );
[439]229
230/****************************************************************************
231 * This structure defines a toggling barrier, that can be used to 
232 * synchronize a group of cores, whether or not they are in a same cluster,
233 * without any specific initialization.   
234 ****************************************************************************/
235typedef struct boot_remote_barrier_s
236{
237    uint32_t current;                      // Number of arrived cores
238    uint32_t sense;                        // Toggle barrier state
239    uint32_t pad[(CACHE_LINE_SIZE>>2)-2];  // Padding
240}
241boot_remote_barrier_t;
242
243/****************************************************************************
244 * This function blocks all processors arriving at the barrier pointed to
245 * by the extend pointer 'xp_barrier' and only returns when all 'count'
246 * expected processors reach the barrier. 
247 * @ xp_barrier : extended pointer to a toggling barrier.
248 * @ count      : number of expected processors. 
249 ****************************************************************************/
250void boot_remote_barrier( xptr_t   xp_barrier, 
251                          uint32_t count );
252
253/****************************************************************************
254 * This structure defines a remote queuing spinlock, that can be used to
255 * synchronize a group of cores, whether or not they are in a same cluster,
256 * without any specific initialization. 
257 ****************************************************************************/
258typedef struct boot_remote_spinlock_s
259{
260    uint32_t     ticket;                       // next free ticket index       
261    uint32_t     current;                      // current owner index
262    uint32_t     pad[(CACHE_LINE_SIZE>>2)-2];  // Padding
263} 
264boot_remote_spinlock_t;
265
266/****************************************************************************
267 * This blocking function returns only when the lock is successfully taken.
268 * @ lock_xp    : extended pointer on lock.
269 ****************************************************************************/
270void boot_remote_lock( xptr_t  lock_xp );
271
272/****************************************************************************
273 * This function release the lock.
274 * @ lock_xp    : extended pointer on lock.
275 ****************************************************************************/
276void boot_remote_unlock( xptr_t  lock_xp );
277
278
279#endif // _BOOT_UTILS_H
Note: See TracBrowser for help on using the repository browser.