7efc80da5f681cbe9ab5f1cb60a78b884c62ac41
[sbcl.git] / src / runtime / os.h
1 /*
2  * common interface for OS-dependent functions
3  */
4
5 /*
6  * This software is part of the SBCL system. See the README file for
7  * more information.
8  *
9  * This software is derived from the CMU CL system, which was
10  * written at Carnegie Mellon University and released into the
11  * public domain. The software is in the public domain and is
12  * provided with absolutely no warranty. See the COPYING and CREDITS
13  * files for more information.
14  */
15
16 #if !defined(_OS_H_INCLUDED_)
17
18 #define _OS_H_INCLUDED_
19
20 #include "sbcl.h"
21 #include "runtime.h"
22
23 /* Some standard preprocessor definitions and typedefs are needed from
24  * the OS-specific #include files. This is an attempt to document
25  * them on 20000729, by WHN the impatient reverse engineer.
26  *
27  * OS_VM_PROT_READ, OS_VM_PROT_WRITE, OS_VM_PROT_EXECUTE
28  *   flags for mmap, mprotect, etc. controlling memory protection
29  * os_vm_prot_t
30  *   type used for flags for mmap, mprotect, etc.
31  *
32  * os_vm_address_t
33  *   the type used to represent addresses? (dunno why not just void*)
34  * os_vm_size_t, os_vm_off_t
35  *   corresponding to standard (POSIX?) types size_t, off_t
36  * os_context_t
37  *   the type used to represent context in a POSIX sigaction SA_SIGACTION
38  *   handler, i.e. the actual type of the thing pointed to by the
39  *   void* third argument of a handler */
40
41 #include "target-os.h"
42
43
44 #define OS_VM_PROT_ALL \
45   (OS_VM_PROT_READ | OS_VM_PROT_WRITE | OS_VM_PROT_EXECUTE)
46
47 #define OS_VM_PROT_NONE 0
48
49 extern os_vm_size_t os_vm_page_size;
50
51 /* Do anything we need to do when starting up the runtime environment
52  * in this OS. */
53 extern void os_init(char *argv[], char *envp[]);
54
55 /* Install any OS-dependent low-level signal handlers which are needed
56  * by the runtime environment. E.g. the signals raised by a violation
57  * of the gencgc write barrier need to be caught at a low level, and
58  * they may be SIGSEGV on one OS and SIGBUS on another, so we install
59  * them in an OS-dependent way. */
60 extern void os_install_interrupt_handlers(void);
61
62 /* Clear a possibly-huge region of memory using any tricks available to
63  * do it efficiently, e.g. possibly unmapping it and then remapping it.
64  *
65  * FIXME: For the x86 Linux/OpenBSD/FreeBSD ports, I'd be somewhat
66  * surprised if bzero() wasn't substantially as efficient as
67  * any tricks like this. It might make sense to benchmark it
68  * and simplify if the difference isn't too large. */
69 extern void os_zero(os_vm_address_t addr, os_vm_size_t length);
70
71 /* It looks as though this function allocates 'len' bytes at 'addr',
72  * or at an OS-chosen address if 'addr' is zero.
73  *
74  * FIXME: There was some documentation for these functions in
75  * "hp-ux.c" in the old CMU CL code. Perhaps move/merge it in here. */
76 extern os_vm_address_t os_validate(os_vm_address_t addr, os_vm_size_t len);
77
78 #ifdef LISP_FEATURE_WIN32
79 void* os_validate_recommit(os_vm_address_t addr, os_vm_size_t len);
80 #endif
81
82 /* This function seems to undo the effect of os_validate(..). */
83 extern void os_invalidate(os_vm_address_t addr, os_vm_size_t len);
84
85 /* This maps a file into memory, or calls lose(..) for various
86  * failures. */
87 extern os_vm_address_t os_map(int fd,
88                               int offset,
89                               os_vm_address_t addr,
90                               os_vm_size_t len);
91
92 /* This presumably flushes the instruction cache, if that can be done
93  * explicitly. (It doesn't seem to be an issue for the i386 port,
94  * which is all that exists for SBCL. It might be important for some
95  * other architecture which CMU CL has been ported to, though. */
96 extern void os_flush_icache(os_vm_address_t addr, os_vm_size_t len);
97
98 /* This sets access rights for an area of memory, e.g.
99  * write-protecting a page so that the garbage collector can find out
100  * whether it's modified by handling the signal. */
101 extern void os_protect(os_vm_address_t addr,
102                        os_vm_size_t len,
103                        os_vm_prot_t protection);
104
105 /* This returns true for an address which makes sense at the Lisp level. */
106 extern boolean is_valid_lisp_addr(os_vm_address_t test);
107
108 /* Given a signal context, return the address for storage of the
109  * register, of the specified offset, for that context. The offset is
110  * defined in the storage class (SC) defined in the Lisp virtual
111  * machine (i.e. the file "vm.lisp" for the appropriate architecture). */
112 os_context_register_t *
113 os_context_register_addr(os_context_t *context, int offset);
114
115 /* FIXME: Pending investigation, this #ifdef stays as alpha. If it
116  * turns out that the alpha truly requires this, it can change to
117  * ARCH_HAS_FLOAT_REGISTERS (currently #defined in alpha-arch.h -- CSR
118  * 2002-02-04 */
119 #ifdef LISP_FEATURE_ALPHA
120 os_context_register_t *
121 os_context_float_register_addr(os_context_t *context, int offset);
122 #endif
123
124 /* Given a signal context, return the address for storage of the
125  * program counter for that context. */
126 os_context_register_t *os_context_pc_addr(os_context_t *context);
127 #ifdef ARCH_HAS_NPC_REGISTER
128 os_context_register_t *os_context_npc_addr(os_context_t *context);
129 #endif
130 #ifdef ARCH_HAS_LINK_REGISTER
131 os_context_register_t *os_context_lr_addr(os_context_t *context);
132 #endif
133
134 /* Given a signal context, return the address for storage of the
135  * system stack pointer for that context. */
136 #ifdef ARCH_HAS_STACK_POINTER
137 os_context_register_t *os_context_sp_addr(os_context_t *context);
138 #endif
139 /* Given a signal context, return the address for storage of the
140  * signal mask for that context. */
141 sigset_t *os_context_sigmask_addr(os_context_t *context);
142
143 /* (Note that there may be other accessors for os_context_t which
144  * depend not only on the OS, but also on the architecture, e.g.
145  * getting at EFL/EFLAGS on the x86. Such things are defined in the
146  * architecture-dependence files, not the OS-dependence files.) */
147
148 /* These are not architecture-specific functions, but are instead
149  * general utilities defined in terms of the architecture-specific
150  * function os_validate(..) and os_invalidate(..).
151  */
152 extern os_vm_address_t os_allocate(os_vm_size_t len);
153 extern void os_deallocate(os_vm_address_t addr, os_vm_size_t len);
154
155 /* FIXME: The os_trunc_foo(..) and os_round_foo(..) macros here could
156  * be functions. */
157
158 #define os_trunc_to_page(addr) \
159     (os_vm_address_t)(((long)(addr))&~(os_vm_page_size-1))
160 #define os_round_up_to_page(addr) \
161     os_trunc_to_page((addr)+(os_vm_page_size-1))
162
163 #define os_trunc_size_to_page(size) \
164     (os_vm_size_t)(((long)(size))&~(os_vm_page_size-1))
165 #define os_round_up_size_to_page(size) \
166     os_trunc_size_to_page((size)+(os_vm_page_size-1))
167
168 /* KLUDGE: The errno error reporting system is an ugly nonreentrant
169  * botch which nonetheless wasn't too painful in the old days.
170  * However, it's obviously not good for multithreaded programs, and n
171  * order to accommodate multithreading while retaining the C-level
172  * syntax of the old UNIX interface, errno has now been changed from a
173  * true variable to a preprocessor definition which is too hairy for
174  * us to try to unscrew in Lisp code. Instead, Lisp code calls this
175  * service routine to do whatever hackery is necessary in C code, and
176  * to return the value in a way that Lisp can understand. */
177 int os_get_errno(void);
178
179 /* Return an absolute path to the runtime executable, or NULL if this
180  * information is unavailable.  Unless external_path is non-zero the
181  * returned path may only be valid for the current process, ie:
182  * something like /proc/curproc/file.  If a non-null pathname is
183  * returned, it must be 'free'd. */
184 extern char *os_get_runtime_executable_path(int external_path);
185
186 /* Write platforms specific ones when necessary. This is to get us off
187  * the ground. */
188 #if N_WORD_BITS == 32
189 # define OS_VM_SIZE_FMT "u"
190 # define OS_VM_SIZE_FMTX "x"
191 #else
192 # define OS_VM_SIZE_FMT "lu"
193 # define OS_VM_SIZE_FMTX "lx"
194 #endif
195
196 /* FIXME: this is not the right place for this, but here we have
197  * a convenient base type to hand. If it turns out we can just use
198  * size_t everywhere, this can more to runtime.h. */
199 typedef os_vm_size_t word_t;
200 #define WORD_FMTX OS_VM_SIZE_FMTX
201
202 #ifdef LISP_FEATURE_SB_THREAD
203 #  ifndef CANNOT_USE_POSIX_SEM_T
204 #    include <semaphore.h>
205      typedef sem_t os_sem_t;
206 #  endif
207    void os_sem_init(os_sem_t *sem, unsigned int value);
208    void os_sem_wait(os_sem_t *sem, char *what);
209    void os_sem_post(os_sem_t *sem, char *what);
210    void os_sem_destroy(os_sem_t *sem);
211 #endif
212
213 #endif