pal.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511
  1. /* -*- mode:c; c-file-style:"k&r"; c-basic-offset: 4; tab-width:4; indent-tabs-mode:nil; mode:auto-fill; fill-column:78; -*- */
  2. /* vim: set ts=4 sw=4 et tw=78 fo=cqt wm=0: */
  3. /* Copyright (C) 2014 Stony Brook University
  4. This file is part of Graphene Library OS.
  5. Graphene Library OS is free software: you can redistribute it and/or
  6. modify it under the terms of the GNU Lesser General Public License
  7. as published by the Free Software Foundation, either version 3 of the
  8. License, or (at your option) any later version.
  9. Graphene Library OS is distributed in the hope that it will be useful,
  10. but WITHOUT ANY WARRANTY; without even the implied warranty of
  11. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  12. GNU Lesser General Public License for more details.
  13. You should have received a copy of the GNU Lesser General Public License
  14. along with this program. If not, see <http://www.gnu.org/licenses/>. */
  15. /*
  16. * pal.h
  17. *
  18. * This file contains definition of PAL host ABI.
  19. */
  20. #ifndef PAL_H
  21. #define PAL_H
  22. #include <stdbool.h>
  23. #include <stddef.h>
  24. #include <stdint.h>
  25. typedef unsigned long PAL_NUM;
  26. typedef const char * PAL_STR;
  27. typedef void * PAL_PTR;
  28. typedef uint32_t PAL_FLG;
  29. typedef uint32_t PAL_IDX;
  30. typedef bool PAL_BOL;
  31. #ifdef IN_PAL
  32. #include <atomic.h>
  33. typedef struct atomic_int PAL_REF;
  34. typedef struct {
  35. PAL_IDX type;
  36. PAL_FLG flags;
  37. } PAL_HDR;
  38. # include "pal_host.h"
  39. # ifndef HANDLE_HDR
  40. # define HANDLE_HDR(handle) (&((handle)->hdr))
  41. # endif
  42. # ifndef TRACE_HEAP
  43. # define TRACE_HEAP(handle) do {} while (0)
  44. # endif
  45. # ifndef UNTRACE_HEAP
  46. # define UNTRACE_HEAP(handle) do {} while (0)
  47. # endif
  48. static inline void init_handle_hdr(PAL_HDR *hdr, int pal_type) {
  49. hdr->type = pal_type;
  50. hdr->flags = 0;
  51. }
  52. # define SET_HANDLE_TYPE(handle, t) \
  53. init_handle_hdr(HANDLE_HDR(handle), pal_type_##t)
  54. # define IS_HANDLE_TYPE(handle, t) \
  55. (HANDLE_HDR(handle)->type == pal_type_##t)
  56. #else
  57. typedef union pal_handle
  58. {
  59. struct {
  60. PAL_IDX type;
  61. /* the PAL-level reference counting is deprecated */
  62. } hdr;
  63. } * PAL_HANDLE;
  64. # ifndef HANDLE_HDR
  65. # define HANDLE_HDR(handle) (&((handle)->hdr))
  66. # endif
  67. #endif /* !IN_PAL */
  68. typedef struct {
  69. #ifdef __x86_64__
  70. PAL_NUM r8, r9, r10, r11, r12, r13, r14, r15;
  71. PAL_NUM rdi, rsi, rbp, rbx, rdx, rax, rcx;
  72. PAL_NUM rsp, rip;
  73. PAL_NUM efl, csgsfs, err, trapno, oldmask, cr2;
  74. #else
  75. # error "Unsupported architecture"
  76. #endif
  77. } PAL_CONTEXT;
  78. #define PAL_TRUE true
  79. #define PAL_FALSE false
  80. /********** PAL TYPE DEFINITIONS **********/
  81. enum {
  82. pal_type_none = 0,
  83. pal_type_file,
  84. pal_type_pipe,
  85. pal_type_pipesrv,
  86. pal_type_pipecli,
  87. pal_type_pipeprv,
  88. pal_type_dev,
  89. pal_type_dir,
  90. pal_type_tcp,
  91. pal_type_tcpsrv,
  92. pal_type_udp,
  93. pal_type_udpsrv,
  94. pal_type_process,
  95. pal_type_mcast,
  96. pal_type_thread,
  97. pal_type_mutex,
  98. pal_type_event,
  99. pal_type_gipc,
  100. PAL_HANDLE_TYPE_BOUND,
  101. };
  102. /* PAL identifier poison value */
  103. #define PAL_IDX_POISON ((PAL_IDX) -1)
  104. #define PAL_GET_TYPE(h) (HANDLE_HDR(h)->type)
  105. #define PAL_CHECK_TYPE(h, t) (PAL_GET_TYPE(h) == pal_type_##t)
  106. typedef struct { PAL_PTR start, end; } PAL_PTR_RANGE;
  107. typedef struct {
  108. PAL_NUM cpu_num;
  109. PAL_STR cpu_vendor;
  110. PAL_STR cpu_brand;
  111. PAL_NUM cpu_family;
  112. PAL_NUM cpu_model;
  113. PAL_NUM cpu_stepping;
  114. PAL_STR cpu_flags;
  115. } PAL_CPU_INFO;
  116. typedef struct {
  117. PAL_NUM mem_total;
  118. } PAL_MEM_INFO;
  119. /********** PAL APIs **********/
  120. typedef struct {
  121. PAL_STR host_type;
  122. /* An identifier of current picoprocess */
  123. PAL_NUM process_id;
  124. PAL_NUM host_id;
  125. /***** Handles and executables *****/
  126. /* program manifest */
  127. PAL_HANDLE manifest_handle;
  128. /* executable name */
  129. PAL_STR executable;
  130. /* handle of parent process */
  131. PAL_HANDLE parent_process;
  132. /* handle of first thread */
  133. PAL_HANDLE first_thread;
  134. /* debug stream */
  135. PAL_HANDLE debug_stream;
  136. /* broadcast RPC stream */
  137. PAL_HANDLE broadcast_stream;
  138. /***** Memory layout ******/
  139. /* The range of user address */
  140. PAL_PTR_RANGE user_address;
  141. /* address where executable is loaded */
  142. PAL_PTR_RANGE executable_range;
  143. /* manifest preloaded here */
  144. PAL_PTR_RANGE manifest_preload;
  145. /***** Host information *****/
  146. /* host page size / allocation alignment */
  147. PAL_NUM pagesize, alloc_align;
  148. /* CPU information (only required ones) */
  149. PAL_CPU_INFO cpu_info;
  150. /* Memory information (only required ones) */
  151. PAL_MEM_INFO mem_info;
  152. /* Purely for profiling */
  153. PAL_NUM startup_time;
  154. PAL_NUM host_specific_startup_time;
  155. PAL_NUM relocation_time;
  156. PAL_NUM linking_time;
  157. PAL_NUM manifest_loading_time;
  158. PAL_NUM allocation_time;
  159. PAL_NUM tail_startup_time;
  160. PAL_NUM child_creation_time;
  161. } PAL_CONTROL;
  162. #define pal_control (*pal_control_addr())
  163. PAL_CONTROL * pal_control_addr (void);
  164. /* The ABI includes three calls to allocate, free, and modify the
  165. * permission bits on page-base virtual memory. Permissions in-
  166. * clude read, write, execute, and guard. Memory regions can be
  167. * unallocated, reserved, or backed by committed memory
  168. */
  169. /* Memory Allocation Flags */
  170. #define PAL_ALLOC_RESERVE 0x0001 /* Only reserve the memory */
  171. #ifdef IN_PAL
  172. #define PAL_ALLOC_INTERNAL 0x8000
  173. #endif
  174. /* Memory Protection Flags */
  175. #define PAL_PROT_NONE 0x0 /* 0x0 Page can not be accessed. */
  176. #define PAL_PROT_READ 0x1 /* 0x1 Page can be read. */
  177. #define PAL_PROT_WRITE 0x2 /* 0x2 Page can be written. */
  178. #define PAL_PROT_EXEC 0x4 /* 0x4 Page can be executed. */
  179. #define PAL_PROT_WRITECOPY 0x8 /* 0x8 Copy on write */
  180. PAL_PTR
  181. DkVirtualMemoryAlloc (PAL_PTR addr, PAL_NUM size, PAL_FLG alloc_type,
  182. PAL_FLG prot);
  183. void
  184. DkVirtualMemoryFree (PAL_PTR addr, PAL_NUM size);
  185. PAL_BOL
  186. DkVirtualMemoryProtect (PAL_PTR addr, PAL_NUM size, PAL_FLG prot);
  187. /* The ABI includes one call to create a child process and one call to
  188. * terminate the running process. A child process does not inherit
  189. * any objects or memory from its parent process and the parent
  190. * process may not modify the execution of its children. A parent can
  191. * wait for a child to exit using its handle. Parent and child may
  192. * communicate through I/O streams provided by the parent to the
  193. * child at creation
  194. */
  195. #define PAL_PROCESS_MASK 0x0
  196. PAL_HANDLE
  197. DkProcessCreate (PAL_STR uri, PAL_FLG flags, PAL_STR * args);
  198. void
  199. DkProcessExit (PAL_NUM exitCode);
  200. #define PAL_SANDBOX_PIPE 0x1
  201. PAL_BOL
  202. DkProcessSandboxCreate (PAL_STR manifest, PAL_FLG flags);
  203. /* The stream ABI includes nine calls to open, read, write, map, unmap,
  204. * truncate, flush, delete and wait for I/O streams and three calls to
  205. * access metadata about an I/O stream. The ABI purposefully does not
  206. * provide an ioctl call. Supported URI schemes include file:, pipe:,
  207. * http:, https:, tcp:, udp:, pipe.srv:, http.srv, tcp.srv:, and udp.srv:.
  208. * The latter four schemes are used to open inbound I/O streams for
  209. * server applications.
  210. */
  211. /* DkStreamOpen
  212. * access_mode: WRONLY or RDONLY or RDWR
  213. * share_flags: permission for the created file
  214. * create_flags: the creation options for the file
  215. * options: other options
  216. */
  217. /* Stream Access Flags */
  218. #define PAL_ACCESS_RDONLY 00
  219. #define PAL_ACCESS_WRONLY 01
  220. #define PAL_ACCESS_RDWR 02
  221. #define PAL_ACCESS_APPEND 04
  222. #define PAL_ACCESS_MASK 07
  223. /* Stream Sharing Flags */
  224. #define PAL_SHARE_GLOBAL_X 01
  225. #define PAL_SHARE_GLOBAL_W 02
  226. #define PAL_SHARE_GLOBAL_R 04
  227. #define PAL_SHARE_GROUP_X 010
  228. #define PAL_SHARE_GROUP_W 020
  229. #define PAL_SHARE_GROUP_R 040
  230. #define PAL_SHARE_OWNER_X 0100
  231. #define PAL_SHARE_OWNER_W 0200
  232. #define PAL_SHARE_OWNER_R 0400
  233. #define PAL_SHARE_MASK 0777
  234. /* Stream Create Flags */
  235. #define PAL_CREAT_TRY 0100 /* 0100 Create file if file not
  236. exist (O_CREAT) */
  237. #define PAL_CREAT_ALWAYS 0200 /* 0300 Create file and fail if file
  238. already exist (O_CREAT|O_EXCL) */
  239. #define PAL_CREAT_MASK 0300
  240. /* Stream Option Flags */
  241. #define PAL_OPTION_NONBLOCK 04000
  242. #define PAL_OPTION_MASK 04000
  243. PAL_HANDLE
  244. DkStreamOpen (PAL_STR uri, PAL_FLG access, PAL_FLG share_flags,
  245. PAL_FLG create, PAL_FLG options);
  246. PAL_HANDLE
  247. DkStreamWaitForClient (PAL_HANDLE handle);
  248. PAL_NUM
  249. DkStreamRead (PAL_HANDLE handle, PAL_NUM offset, PAL_NUM count,
  250. PAL_PTR buffer, PAL_PTR source, PAL_NUM size);
  251. PAL_NUM
  252. DkStreamWrite (PAL_HANDLE handle, PAL_NUM offset, PAL_NUM count,
  253. PAL_PTR buffer, PAL_STR dest);
  254. #define PAL_DELETE_RD 01
  255. #define PAL_DELETE_WR 02
  256. void
  257. DkStreamDelete (PAL_HANDLE handle, PAL_FLG access);
  258. PAL_PTR
  259. DkStreamMap (PAL_HANDLE handle, PAL_PTR address, PAL_FLG prot,
  260. PAL_NUM offset, PAL_NUM size);
  261. void
  262. DkStreamUnmap (PAL_PTR addr, PAL_NUM size);
  263. PAL_NUM
  264. DkStreamSetLength (PAL_HANDLE handle, PAL_NUM length);
  265. PAL_BOL
  266. DkStreamFlush (PAL_HANDLE handle);
  267. PAL_BOL
  268. DkSendHandle (PAL_HANDLE handle, PAL_HANDLE cargo);
  269. PAL_HANDLE
  270. DkReceiveHandle (PAL_HANDLE handle);
  271. /* stream attribute structure */
  272. typedef struct {
  273. PAL_IDX handle_type;
  274. PAL_BOL disconnected;
  275. PAL_BOL nonblocking;
  276. PAL_BOL readable, writeable, runnable;
  277. PAL_FLG share_flags;
  278. PAL_NUM pending_size;
  279. union {
  280. struct {
  281. PAL_NUM linger;
  282. PAL_NUM receivebuf, sendbuf;
  283. PAL_NUM receivetimeout, sendtimeout;
  284. PAL_BOL tcp_cork;
  285. PAL_BOL tcp_keepalive;
  286. PAL_BOL tcp_nodelay;
  287. } socket;
  288. };
  289. } PAL_STREAM_ATTR;
  290. PAL_BOL
  291. DkStreamAttributesQuery (PAL_STR uri, PAL_STREAM_ATTR * attr);
  292. PAL_BOL
  293. DkStreamAttributesQuerybyHandle (PAL_HANDLE handle,
  294. PAL_STREAM_ATTR * attr);
  295. PAL_BOL
  296. DkStreamAttributesSetbyHandle (PAL_HANDLE handle, PAL_STREAM_ATTR * attr);
  297. PAL_NUM
  298. DkStreamGetName (PAL_HANDLE handle, PAL_PTR buffer, PAL_NUM size);
  299. PAL_BOL
  300. DkStreamChangeName (PAL_HANDLE handle, PAL_STR uri);
  301. /* The ABI supports multithreading through five calls to create,
  302. * sleep, yield the scheduler quantum for, resume execution of, and
  303. * terminate threads, as well as seven calls to create, signal, and
  304. * block on synchronization objects
  305. */
  306. #define PAL_THREAD_MASK 0
  307. PAL_HANDLE
  308. DkThreadCreate (PAL_PTR addr, PAL_PTR param, PAL_FLG flags);
  309. // assuming duration to be in microseconds
  310. PAL_NUM
  311. DkThreadDelayExecution (PAL_NUM duration);
  312. void
  313. DkThreadYieldExecution (void);
  314. void
  315. DkThreadExit (void);
  316. PAL_BOL
  317. DkThreadResume (PAL_HANDLE thread);
  318. /* Exception Handling */
  319. /* Div-by-zero */
  320. #define PAL_EVENT_DIVZERO 1
  321. /* segmentation fault, protection fault, bus fault */
  322. #define PAL_EVENT_MEMFAULT 2
  323. /* illegal instructions */
  324. #define PAL_EVENT_ILLEGAL 3
  325. /* terminated by external program */
  326. #define PAL_EVENT_QUIT 4
  327. /* suspended by external program */
  328. #define PAL_EVENT_SUSPEND 5
  329. /* continued by external program */
  330. #define PAL_EVENT_RESUME 6
  331. /* failure within PAL calls */
  332. #define PAL_EVENT_FAILURE 7
  333. #define PAL_EVENT_NUM_BOUND 8
  334. #define PAL_EVENT_PRIVATE 0x0001 /* upcall specific to thread */
  335. #define PAL_EVENT_RESET 0x0002 /* reset the event upcall */
  336. typedef void (*PAL_EVENT_HANDLER) (PAL_PTR event, PAL_NUM arg, PAL_CONTEXT *);
  337. PAL_BOL
  338. DkSetExceptionHandler (PAL_EVENT_HANDLER handler, PAL_NUM event,
  339. PAL_FLG flags);
  340. void DkExceptionReturn (PAL_PTR event);
  341. /* parameter: keeping int threadHandle for now (to be in sync with the paper).
  342. * We may want to replace it with a PAL_HANDLE. Ideally, either use PAL_HANDLE
  343. * or threadHandle.
  344. */
  345. /* Create a Mutex.
  346. * initialCount of 0 is totally unlocked; an initialCount of 1
  347. * is initialized to locked. */
  348. PAL_HANDLE
  349. DkMutexCreate (PAL_NUM initialCount);
  350. /* Destroy a mutex using DkObjectClose */
  351. void
  352. DkMutexRelease (PAL_HANDLE mutexHandle);
  353. PAL_HANDLE
  354. DkNotificationEventCreate (PAL_BOL initialState);
  355. PAL_HANDLE
  356. DkSynchronizationEventCreate (PAL_BOL initialState);
  357. /* DkEventDestroy deprecated, replaced by DkObjectClose */
  358. void
  359. DkEventSet (PAL_HANDLE eventHandle);
  360. /* DkEventWait deprecated, replaced by DkObjectsWaitAny */
  361. void
  362. DkEventClear (PAL_HANDLE eventHandle);
  363. #define NO_TIMEOUT ((PAL_NUM) -1)
  364. /* assuming timeout to be in microseconds
  365. * NO_TIMEOUT means no timeout, as the name implies.
  366. */
  367. /* Returns: NULL if the call times out, the ready handle on success */
  368. PAL_HANDLE
  369. DkObjectsWaitAny (PAL_NUM count, PAL_HANDLE * handleArray, PAL_NUM timeout);
  370. /* Deprecate DkObjectReference */
  371. void DkObjectClose (PAL_HANDLE objectHandle);
  372. /* the ABI includes seven assorted calls to get wall clock
  373. * time, generate cryptographically-strong random bits, flush por-
  374. * tions of instruction caches, increment and decrement the reference
  375. * counts on objects shared between threads, and to coordinate
  376. * threads with the security monitor during process serialization
  377. */
  378. /* assuming the time to be in microseconds */
  379. PAL_NUM
  380. DkSystemTimeQuery (void);
  381. PAL_NUM
  382. DkRandomBitsRead (PAL_PTR buffer, PAL_NUM size);
  383. PAL_BOL
  384. DkInstructionCacheFlush (PAL_PTR addr, PAL_NUM size);
  385. #define PAL_SEGMENT_FS 0x1
  386. #define PAL_SEGMENT_GS 0x2
  387. PAL_PTR DkSegmentRegister (PAL_FLG reg, PAL_PTR addr);
  388. PAL_HANDLE
  389. DkCreatePhysicalMemoryChannel (PAL_NUM * key);
  390. PAL_NUM
  391. DkPhysicalMemoryCommit (PAL_HANDLE channel, PAL_NUM entries, PAL_PTR * addrs,
  392. PAL_NUM * sizes, PAL_FLG flags);
  393. PAL_NUM
  394. DkPhysicalMemoryMap (PAL_HANDLE channel, PAL_NUM entries, PAL_PTR * addrs,
  395. PAL_NUM * sizes, PAL_FLG * prots);
  396. PAL_NUM DkMemoryAvailableQuota (void);
  397. PAL_BOL
  398. DkCpuIdRetrieve (PAL_IDX leaf, PAL_IDX subleaf, PAL_IDX values[4]);
  399. #endif /* PAL_H */