KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
arch.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  arch/dreamcast/include/arch.h
4  Copyright (C) 2001 Dan Potter
5  Copyright (C) 2013 Lawrence Sebald
6 
7 */
8 
9 /** \file arch/arch.h
10  \brief Dreamcast architecture specific options.
11 
12  This file has various architecture specific options defined in it. Also, any
13  functions that start with arch_ are in here.
14 
15  \author Dan Potter
16 */
17 
18 #ifndef __ARCH_ARCH_H
19 #define __ARCH_ARCH_H
20 
21 #include <kos/cdefs.h>
22 __BEGIN_DECLS
23 
24 #include <dc/video.h>
25 
26 #define PAGESIZE 4096 /**< \brief Page size (for MMU) */
27 #define PAGESIZE_BITS 12 /**< \brief Bits for page size */
28 #define PAGEMASK (PAGESIZE - 1) /**< \brief Mask for page offset */
29 
30 /** \brief Page count "variable".
31 
32  The number of pages is static, so we can optimize this quite a bit. */
33 #define page_count ((16*1024*1024 - 0x10000) / PAGESIZE)
34 
35 /** \brief Base address of available physical pages. */
36 #define page_phys_base 0x8c010000
37 
38 /** \brief Number of timer ticks per second. */
39 #define HZ 100
40 
41 /** \brief Default thread stack size. */
42 #define THD_STACK_SIZE 32768
43 
44 /** \brief Default video mode. */
45 #define DEFAULT_VID_MODE DM_640x480
46 
47 /** \brief Default pixel mode for video. */
48 #define DEFAULT_PIXEL_MODE PM_RGB565
49 
50 /** \brief Default serial bitrate. */
51 #define DEFAULT_SERIAL_BAUD 57600
52 
53 /** \brief Default serial FIFO behavior. */
54 #define DEFAULT_SERIAL_FIFO 1
55 
56 /** \brief Global symbol prefix in ELF files. */
57 #define ELF_SYM_PREFIX "_"
58 
59 /** \brief Length of global symbol prefix in ELF files. */
60 #define ELF_SYM_PREFIX_LEN 1
61 
62 /** \brief Panic function.
63 
64  This function will cause a kernel panic, printing the specified message.
65 
66  \param str The error message to print.
67  \note This function will never return!
68 */
69 void panic(const char *str) __noreturn;
70 
71 /** \brief Kernel C-level entry point.
72  \return The program's return value.
73 */
74 int arch_main();
75 
76 /** \defgroup arch_retpaths Potential exit paths from the kernel on
77  arch_exit()
78 
79  @{
80 */
81 #define ARCH_EXIT_RETURN 1 /**< \brief Return to loader */
82 #define ARCH_EXIT_MENU 2 /**< \brief Return to system menu */
83 #define ARCH_EXIT_REBOOT 3 /**< \brief Reboot the machine */
84 /** @} */
85 
86 /** \brief Set the exit path.
87 
88  The default, if you don't call this, is ARCH_EXIT_RETURN.
89 
90  \param path What arch_exit() should do.
91  \see arch_retpaths
92 */
93 void arch_set_exit_path(int path);
94 
95 /** \brief Generic kernel "exit" point.
96  \note This function will never return!
97 */
98 void arch_exit() __noreturn;
99 
100 /** \brief Kernel "return" point.
101  \note This function will never return!
102 */
103 void arch_return() __noreturn;
104 
105 /** \brief Kernel "abort" point.
106  \note This function will never return!
107 */
108 void arch_abort() __noreturn;
109 
110 /** \brief Kernel "reboot" call.
111  \note This function will never return!
112 */
113 void arch_reboot() __noreturn;
114 
115 /** \brief Kernel "exit to menu" call.
116  \note This function will never return!
117 */
118 void arch_menu() __noreturn;
119 
120 /** \brief Call to run all ctors. */
121 void arch_ctors();
122 
123 /** \brief Call to run all dtors. */
124 void arch_dtors();
125 
126 /** \brief Hook to ensure linking of crtend.c. */
127 void __crtend_pullin();
128 
129 /* These are in mm.c */
130 /** \brief Initialize the memory management system.
131  \retval 0 On success (no error conditions defined).
132 */
133 int mm_init();
134 
135 /** \brief Request more core memory from the system.
136  \param increment The number of bytes requested.
137  \return A pointer to the memory.
138  \note This function will panic if no memory is available.
139 */
140 void * mm_sbrk(unsigned long increment);
141 
142 /** \brief Use this macro to determine the level of initialization you'd like
143  in your program by default.
144 
145  The defaults line will be fine for most things.
146 
147  \param flags Parts of KOS to init.
148 */
149 #define KOS_INIT_FLAGS(flags) uint32 __kos_init_flags = (flags)
150 
151 /** \brief The init flags. Do not modify this directly! */
152 extern uint32 __kos_init_flags;
153 
154 /** \brief Define a romdisk for your program, if you'd like one.
155  \param rd Pointer to the romdisk image in your code.
156 */
157 #define KOS_INIT_ROMDISK(rd) void * __kos_romdisk = (rd)
158 
159 /** \brief Built-in romdisk. Do not modify this directly! */
160 extern void * __kos_romdisk;
161 
162 /** \brief State that you don't want a romdisk. */
163 #define KOS_INIT_ROMDISK_NONE NULL
164 
165 /** \defgroup arch_initflags Available flags for initialization
166 
167  These are the flags you can specify with KOS_INIT_FLAGS().
168  @{
169 */
170 /** \brief Default init flags (IRQs on, preemption enabled). */
171 #define INIT_DEFAULT \
172  (INIT_IRQ | INIT_THD_PREEMPT)
173 
174 #define INIT_NONE 0x0000 /**< \brief Don't init optional things */
175 #define INIT_IRQ 0x0001 /**< \brief Enable IRQs at startup */
176 #define INIT_THD_PREEMPT 0x0002 /**< \brief Enable thread preemption */
177 #define INIT_NET 0x0004 /**< \brief Enable built-in networking */
178 #define INIT_MALLOCSTATS 0x0008 /**< \brief Enable malloc statistics */
179 #define INIT_QUIET 0x0010 /**< \brief Disable dbgio */
180 
181 /* DC-specific stuff */
182 #define INIT_OCRAM 0x10000 /**< \brief Use half of the dcache as RAM */
183 #define INIT_NO_DCLOAD 0x20000 /**< \brief Disable dcload */
184 /** @} */
185 
186 /* Dreamcast-specific arch init things */
187 /** \brief Jump back to the bootloader.
188 
189  You generally shouldn't use this function, but rather use arch_exit() or
190  exit() instead.
191 
192  \note This function will never return!
193 */
194 void arch_real_exit() __noreturn;
195 
196 /** \brief Initialize bare-bones hardware systems.
197 
198  This will be done automatically for you on start by the default arch_main(),
199  so you shouldn't have to deal with this yourself.
200 
201  \retval 0 On success (no error conditions defined).
202 */
203 int hardware_sys_init();
204 
205 /** \brief Initialize some peripheral systems.
206 
207  This will be done automatically for you on start by the default arch_main(),
208  so you shouldn't have to deal with this yourself.
209 
210  \retval 0 On success (no error conditions defined).
211 */
213 
214 /** \brief Shut down hardware that was initted.
215 
216  This function will shut down anything initted with hardware_sys_init() and
217  hardware_periph_init(). This will be done for you automatically by the
218  various exit points, so you shouldn't have to do this yourself.
219 */
220 void hardware_shutdown();
221 
222 /* These three aught to be in their own header file at some point, but for now,
223  they'll stay here. */
224 
225 /** \brief Retrieve the banner printed at program initialization.
226 
227  This function retrieves the banner string that is printed at initialization
228  time by the kernel. This contains the version of KOS in use and basic
229  information about the environment in which it was compiled.
230 
231  \retval A pointer to the banner string.
232 */
233 const char *kos_get_banner(void);
234 
235 /** \brief Retrieve the license information for the compiled copy of KOS.
236 
237  This function retrieves a string containing the license terms that the
238  version of KOS in use is distributed under. This can be used to easily add
239  information to your program to be displayed at runtime.
240 
241  \retval A pointer to the license terms.
242 */
243 const char *kos_get_license(void);
244 
245 /** \brief Retrieve a list of authors and the dates of their contributions.
246 
247  This function retrieves the copyright information for the version of KOS in
248  use. This function can be used to add such information to the credits of
249  programs using KOS to give the appropriate credit to those that have worked
250  on KOS.
251 
252  Remember, you do need to give credit where credit is due, and this is an
253  easy way to do so. ;-)
254 
255  \retval A pointer to the authors' copyright information.
256 */
257 const char *kos_get_authors(void);
258 
259 /** \brief Dreamcast specific sleep mode "function". */
260 #define arch_sleep() do { \
261  __asm__ __volatile__("sleep"); \
262  } while(0)
263 
264 /** \brief DC specific "function" to get the return address from the current
265  function.
266  \return The return address of the current function.
267 */
268 #define arch_get_ret_addr() ({ \
269  uint32 pr; \
270  __asm__ __volatile__("sts pr,%0\n" \
271  : "=&z" (pr) \
272  : /* no inputs */ \
273  : "memory" ); \
274  pr; })
275 
276 /* Please note that all of the following frame pointer macros are ONLY
277  valid if you have compiled your code WITHOUT -fomit-frame-pointer. These
278  are mainly useful for getting a stack trace from an error. */
279 
280 /** \brief DC specific "function" to get the frame pointer from the current
281  function.
282  \return The frame pointer from the current function.
283  \note This only works if you don't disable frame pointers.
284 */
285 #define arch_get_fptr() ({ \
286  uint32 fp; \
287  __asm__ __volatile__("mov r14,%0\n" \
288  : "=&z" (fp) \
289  : /* no inputs */ \
290  : "memory" ); \
291  fp; })
292 
293 /** \brief Pass in a frame pointer value to get the return address for the
294  given frame.
295 
296  \param fptr The frame pointer to look at.
297  \return The return address of the pointer.
298 */
299 #define arch_fptr_ret_addr(fptr) (*((uint32*)fptr))
300 
301 /** \brief Pass in a frame pointer value to get the previous frame pointer for
302  the given frame.
303 
304  \param fptr The frame pointer to look at.
305  \return The previous frame pointer.
306 */
307 #define arch_fptr_next(fptr) (*((uint32*)(fptr+4)))
308 
309 /** \brief Returns true if the passed address is likely to be valid. Doesn't
310  have to be exact, just a sort of general idea.
311 
312  \return Whether the address is valid or not for normal
313  memory access.
314 */
315 #define arch_valid_address(ptr) ((ptr_t)(ptr) >= 0x8c010000 && (ptr_t)(ptr) < 0x8d000000)
316 
317 __END_DECLS
318 
319 #endif /* __ARCH_ARCH_H */
320