KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
arch.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
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 /** \defgroup hw_consoles Console types
223 
224  These are the various console types that can be returned by the
225  hardware_sys_mode() function.
226 
227  @{
228 */
229 #define HW_TYPE_RETAIL 0x0 /**< \brief A retail Dreamcast. */
230 #define HW_TYPE_SET5 0x9 /**< \brief A Set5.xx devkit. */
231 /** @} */
232 
233 /** \defgroup hw_regions Region codes
234 
235  These are the various region codes that can be returned by the
236  hardware_sys_mode() function. Note that a retail Dreamcast will always
237  return 0 for the region code. You must read the region of a retail device
238  from the flashrom.
239 
240  \see fr_region
241  \see flashrom_get_region()
242 
243  @{
244 */
245 #define HW_REGION_UNKNOWN 0x0 /**< \brief Unknown region. */
246 #define HW_REGION_ASIA 0x1 /**< \brief Japan/Asia (NTSC) */
247 #define HW_REGION_US 0x4 /**< \brief North America */
248 #define HW_REGION_EUROPE 0xC /**< \brief Europe (PAL) */
249 /** @} */
250 
251 /** \brief Retrieve the system mode of the console in use.
252 
253  This function retrieves the system mode register of the console that is in
254  use. This register details the actual system type in use (and in some system
255  types the region of the device).
256 
257  \param region On return, the region code (one of the
258  \ref hw_regions) of the device if the console type
259  allows reading it through the system mode register
260  -- otherwise, you must retrieve the region from the
261  flashrom.
262  \return The console type (one of the \ref hw_consoles).
263 */
264 int hardware_sys_mode(int *region);
265 
266 /* These three aught to be in their own header file at some point, but for now,
267  they'll stay here. */
268 
269 /** \brief Retrieve the banner printed at program initialization.
270 
271  This function retrieves the banner string that is printed at initialization
272  time by the kernel. This contains the version of KOS in use and basic
273  information about the environment in which it was compiled.
274 
275  \retval A pointer to the banner string.
276 */
277 const char *kos_get_banner(void);
278 
279 /** \brief Retrieve the license information for the compiled copy of KOS.
280 
281  This function retrieves a string containing the license terms that the
282  version of KOS in use is distributed under. This can be used to easily add
283  information to your program to be displayed at runtime.
284 
285  \retval A pointer to the license terms.
286 */
287 const char *kos_get_license(void);
288 
289 /** \brief Retrieve a list of authors and the dates of their contributions.
290 
291  This function retrieves the copyright information for the version of KOS in
292  use. This function can be used to add such information to the credits of
293  programs using KOS to give the appropriate credit to those that have worked
294  on KOS.
295 
296  Remember, you do need to give credit where credit is due, and this is an
297  easy way to do so. ;-)
298 
299  \retval A pointer to the authors' copyright information.
300 */
301 const char *kos_get_authors(void);
302 
303 /** \brief Dreamcast specific sleep mode "function". */
304 #define arch_sleep() do { \
305  __asm__ __volatile__("sleep"); \
306  } while(0)
307 
308 /** \brief DC specific "function" to get the return address from the current
309  function.
310  \return The return address of the current function.
311 */
312 #define arch_get_ret_addr() ({ \
313  uint32 pr; \
314  __asm__ __volatile__("sts pr,%0\n" \
315  : "=&z" (pr) \
316  : /* no inputs */ \
317  : "memory" ); \
318  pr; })
319 
320 /* Please note that all of the following frame pointer macros are ONLY
321  valid if you have compiled your code WITHOUT -fomit-frame-pointer. These
322  are mainly useful for getting a stack trace from an error. */
323 
324 /** \brief DC specific "function" to get the frame pointer from the current
325  function.
326  \return The frame pointer from the current function.
327  \note This only works if you don't disable frame pointers.
328 */
329 #define arch_get_fptr() ({ \
330  uint32 fp; \
331  __asm__ __volatile__("mov r14,%0\n" \
332  : "=&z" (fp) \
333  : /* no inputs */ \
334  : "memory" ); \
335  fp; })
336 
337 /** \brief Pass in a frame pointer value to get the return address for the
338  given frame.
339 
340  \param fptr The frame pointer to look at.
341  \return The return address of the pointer.
342 */
343 #define arch_fptr_ret_addr(fptr) (*((uint32*)fptr))
344 
345 /** \brief Pass in a frame pointer value to get the previous frame pointer for
346  the given frame.
347 
348  \param fptr The frame pointer to look at.
349  \return The previous frame pointer.
350 */
351 #define arch_fptr_next(fptr) (*((uint32*)(fptr+4)))
352 
353 /** \brief Returns true if the passed address is likely to be valid. Doesn't
354  have to be exact, just a sort of general idea.
355 
356  \return Whether the address is valid or not for normal
357  memory access.
358 */
359 #define arch_valid_address(ptr) ((ptr_t)(ptr) >= 0x8c010000 && (ptr_t)(ptr) < 0x8d000000)
360 
361 __END_DECLS
362 
363 #endif /* __ARCH_ARCH_H */
364 
void arch_menu() __noreturn
Kernel "exit to menu" call.
void arch_dtors()
Call to run all dtors.
const char * kos_get_authors(void)
Retrieve a list of authors and the dates of their contributions.
void arch_return() __noreturn
Kernel "return" point.
int mm_init()
Initialize the memory management system.
void arch_real_exit() __noreturn
Jump back to the bootloader.
void arch_exit() __noreturn
Generic kernel "exit" point.
void arch_abort() __noreturn
Kernel "abort" point.
int hardware_sys_init()
Initialize bare-bones hardware systems.
Functions related to video output.
void hardware_shutdown()
Shut down hardware that was initted.
int arch_main()
Kernel C-level entry point.
void __crtend_pullin()
Hook to ensure linking of crtend.c.
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
const char * kos_get_banner(void)
Retrieve the banner printed at program initialization.
void arch_ctors()
Call to run all ctors.
int hardware_periph_init()
Initialize some peripheral systems.
void arch_reboot() __noreturn
Kernel "reboot" call.
void panic(const char *str) __noreturn
Panic function.
Potentially useful definitions for C Programs.
void * mm_sbrk(unsigned long increment)
Request more core memory from the system.
#define __noreturn
Identify a function that will never return.
Definition: cdefs.h:37
int hardware_sys_mode(int *region)
Retrieve the system mode of the console in use.
void * __kos_romdisk
Built-in romdisk. Do not modify this directly!
uint32 __kos_init_flags
The init flags. Do not modify this directly!
void arch_set_exit_path(int path)
Set the exit path.
const char * kos_get_license(void)
Retrieve the license information for the compiled copy of KOS.