• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright 2010 Tilera Corporation. All Rights Reserved.
3  *
4  *   This program is free software; you can redistribute it and/or
5  *   modify it under the terms of the GNU General Public License
6  *   as published by the Free Software Foundation, version 2.
7  *
8  *   This program is distributed in the hope that it will be useful, but
9  *   WITHOUT ANY WARRANTY; without even the implied warranty of
10  *   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
11  *   NON INFRINGEMENT.  See the GNU General Public License for
12  *   more details.
13  */
14 
15 /**
16  * @file hypervisor.h
17  * The hypervisor's public API.
18  */
19 
20 #ifndef _HV_HV_H
21 #define _HV_HV_H
22 
23 #include <arch/chip.h>
24 
25 /* Linux builds want unsigned long constants, but assembler wants numbers */
26 #ifdef __ASSEMBLER__
27 /** One, for assembler */
28 #define __HV_SIZE_ONE 1
29 #elif !defined(__tile__) && CHIP_VA_WIDTH() > 32
30 /** One, for 64-bit on host */
31 #define __HV_SIZE_ONE 1ULL
32 #else
33 /** One, for Linux */
34 #define __HV_SIZE_ONE 1UL
35 #endif
36 
37 /** The log2 of the span of a level-1 page table, in bytes.
38  */
39 #define HV_LOG2_L1_SPAN 32
40 
41 /** The span of a level-1 page table, in bytes.
42  */
43 #define HV_L1_SPAN (__HV_SIZE_ONE << HV_LOG2_L1_SPAN)
44 
45 /** The log2 of the initial size of small pages, in bytes.
46  * See HV_DEFAULT_PAGE_SIZE_SMALL.
47  */
48 #define HV_LOG2_DEFAULT_PAGE_SIZE_SMALL 16
49 
50 /** The initial size of small pages, in bytes. This value should be verified
51  * at runtime by calling hv_sysconf(HV_SYSCONF_PAGE_SIZE_SMALL).
52  * It may also be modified when installing a new context.
53  */
54 #define HV_DEFAULT_PAGE_SIZE_SMALL \
55   (__HV_SIZE_ONE << HV_LOG2_DEFAULT_PAGE_SIZE_SMALL)
56 
57 /** The log2 of the initial size of large pages, in bytes.
58  * See HV_DEFAULT_PAGE_SIZE_LARGE.
59  */
60 #define HV_LOG2_DEFAULT_PAGE_SIZE_LARGE 24
61 
62 /** The initial size of large pages, in bytes. This value should be verified
63  * at runtime by calling hv_sysconf(HV_SYSCONF_PAGE_SIZE_LARGE).
64  * It may also be modified when installing a new context.
65  */
66 #define HV_DEFAULT_PAGE_SIZE_LARGE \
67   (__HV_SIZE_ONE << HV_LOG2_DEFAULT_PAGE_SIZE_LARGE)
68 
69 #if CHIP_VA_WIDTH() > 32
70 
71 /** The log2 of the initial size of jumbo pages, in bytes.
72  * See HV_DEFAULT_PAGE_SIZE_JUMBO.
73  */
74 #define HV_LOG2_DEFAULT_PAGE_SIZE_JUMBO 32
75 
76 /** The initial size of jumbo pages, in bytes. This value should
77  * be verified at runtime by calling hv_sysconf(HV_SYSCONF_PAGE_SIZE_JUMBO).
78  * It may also be modified when installing a new context.
79  */
80 #define HV_DEFAULT_PAGE_SIZE_JUMBO \
81   (__HV_SIZE_ONE << HV_LOG2_DEFAULT_PAGE_SIZE_JUMBO)
82 
83 #endif
84 
85 /** The log2 of the granularity at which page tables must be aligned;
86  *  in other words, the CPA for a page table must have this many zero
87  *  bits at the bottom of the address.
88  */
89 #define HV_LOG2_PAGE_TABLE_ALIGN 11
90 
91 /** The granularity at which page tables must be aligned.
92  */
93 #define HV_PAGE_TABLE_ALIGN (__HV_SIZE_ONE << HV_LOG2_PAGE_TABLE_ALIGN)
94 
95 /** Normal start of hypervisor glue in client physical memory. */
96 #define HV_GLUE_START_CPA 0x10000
97 
98 /** This much space is reserved at HV_GLUE_START_CPA
99  * for the hypervisor glue. The client program must start at
100  * some address higher than this, and in particular the address of
101  * its text section should be equal to zero modulo HV_PAGE_SIZE_LARGE
102  * so that relative offsets to the HV glue are correct.
103  */
104 #define HV_GLUE_RESERVED_SIZE 0x10000
105 
106 /** Each entry in the hv dispatch array takes this many bytes. */
107 #define HV_DISPATCH_ENTRY_SIZE 32
108 
109 /** Version of the hypervisor interface defined by this file */
110 #define _HV_VERSION 13
111 
112 /** Last version of the hypervisor interface with old hv_init() ABI.
113  *
114  * The change from version 12 to version 13 corresponds to launching
115  * the client by default at PL2 instead of PL1 (corresponding to the
116  * hv itself running at PL3 instead of PL2).  To make this explicit,
117  * the hv_init() API was also extended so the client can report its
118  * desired PL, resulting in a more helpful failure diagnostic.  If you
119  * call hv_init() with _HV_VERSION_OLD_HV_INIT and omit the client_pl
120  * argument, the hypervisor will assume client_pl = 1.
121  *
122  * Note that this is a deprecated solution and we do not expect to
123  * support clients of the Tilera hypervisor running at PL1 indefinitely.
124  */
125 #define _HV_VERSION_OLD_HV_INIT 12
126 
127 /* Index into hypervisor interface dispatch code blocks.
128  *
129  * Hypervisor calls are invoked from user space by calling code
130  * at an address HV_BASE_ADDRESS + (index) * HV_DISPATCH_ENTRY_SIZE,
131  * where index is one of these enum values.
132  *
133  * Normally a supervisor is expected to produce a set of symbols
134  * starting at HV_BASE_ADDRESS that obey this convention, but a user
135  * program could call directly through function pointers if desired.
136  *
137  * These numbers are part of the binary API and will not be changed
138  * without updating HV_VERSION, which should be a rare event.
139  */
140 
141 /** reserved. */
142 #define _HV_DISPATCH_RESERVED                     0
143 
144 /** hv_init  */
145 #define HV_DISPATCH_INIT                          1
146 
147 /** hv_install_context */
148 #define HV_DISPATCH_INSTALL_CONTEXT               2
149 
150 /** hv_sysconf */
151 #define HV_DISPATCH_SYSCONF                       3
152 
153 /** hv_get_rtc */
154 #define HV_DISPATCH_GET_RTC                       4
155 
156 /** hv_set_rtc */
157 #define HV_DISPATCH_SET_RTC                       5
158 
159 /** hv_flush_asid */
160 #define HV_DISPATCH_FLUSH_ASID                    6
161 
162 /** hv_flush_page */
163 #define HV_DISPATCH_FLUSH_PAGE                    7
164 
165 /** hv_flush_pages */
166 #define HV_DISPATCH_FLUSH_PAGES                   8
167 
168 /** hv_restart */
169 #define HV_DISPATCH_RESTART                       9
170 
171 /** hv_halt */
172 #define HV_DISPATCH_HALT                          10
173 
174 /** hv_power_off */
175 #define HV_DISPATCH_POWER_OFF                     11
176 
177 /** hv_inquire_physical */
178 #define HV_DISPATCH_INQUIRE_PHYSICAL              12
179 
180 /** hv_inquire_memory_controller */
181 #define HV_DISPATCH_INQUIRE_MEMORY_CONTROLLER     13
182 
183 /** hv_inquire_virtual */
184 #define HV_DISPATCH_INQUIRE_VIRTUAL               14
185 
186 /** hv_inquire_asid */
187 #define HV_DISPATCH_INQUIRE_ASID                  15
188 
189 /** hv_nanosleep */
190 #define HV_DISPATCH_NANOSLEEP                     16
191 
192 /** hv_console_read_if_ready */
193 #define HV_DISPATCH_CONSOLE_READ_IF_READY         17
194 
195 /** hv_console_write */
196 #define HV_DISPATCH_CONSOLE_WRITE                 18
197 
198 /** hv_downcall_dispatch */
199 #define HV_DISPATCH_DOWNCALL_DISPATCH             19
200 
201 /** hv_inquire_topology */
202 #define HV_DISPATCH_INQUIRE_TOPOLOGY              20
203 
204 /** hv_fs_findfile */
205 #define HV_DISPATCH_FS_FINDFILE                   21
206 
207 /** hv_fs_fstat */
208 #define HV_DISPATCH_FS_FSTAT                      22
209 
210 /** hv_fs_pread */
211 #define HV_DISPATCH_FS_PREAD                      23
212 
213 /** hv_physaddr_read64 */
214 #define HV_DISPATCH_PHYSADDR_READ64               24
215 
216 /** hv_physaddr_write64 */
217 #define HV_DISPATCH_PHYSADDR_WRITE64              25
218 
219 /** hv_get_command_line */
220 #define HV_DISPATCH_GET_COMMAND_LINE              26
221 
222 /** hv_set_caching */
223 #define HV_DISPATCH_SET_CACHING                   27
224 
225 /** hv_bzero_page */
226 #define HV_DISPATCH_BZERO_PAGE                    28
227 
228 /** hv_register_message_state */
229 #define HV_DISPATCH_REGISTER_MESSAGE_STATE        29
230 
231 /** hv_send_message */
232 #define HV_DISPATCH_SEND_MESSAGE                  30
233 
234 /** hv_receive_message */
235 #define HV_DISPATCH_RECEIVE_MESSAGE               31
236 
237 /** hv_inquire_context */
238 #define HV_DISPATCH_INQUIRE_CONTEXT               32
239 
240 /** hv_start_all_tiles */
241 #define HV_DISPATCH_START_ALL_TILES               33
242 
243 /** hv_dev_open */
244 #define HV_DISPATCH_DEV_OPEN                      34
245 
246 /** hv_dev_close */
247 #define HV_DISPATCH_DEV_CLOSE                     35
248 
249 /** hv_dev_pread */
250 #define HV_DISPATCH_DEV_PREAD                     36
251 
252 /** hv_dev_pwrite */
253 #define HV_DISPATCH_DEV_PWRITE                    37
254 
255 /** hv_dev_poll */
256 #define HV_DISPATCH_DEV_POLL                      38
257 
258 /** hv_dev_poll_cancel */
259 #define HV_DISPATCH_DEV_POLL_CANCEL               39
260 
261 /** hv_dev_preada */
262 #define HV_DISPATCH_DEV_PREADA                    40
263 
264 /** hv_dev_pwritea */
265 #define HV_DISPATCH_DEV_PWRITEA                   41
266 
267 /** hv_flush_remote */
268 #define HV_DISPATCH_FLUSH_REMOTE                  42
269 
270 /** hv_console_putc */
271 #define HV_DISPATCH_CONSOLE_PUTC                  43
272 
273 /** hv_inquire_tiles */
274 #define HV_DISPATCH_INQUIRE_TILES                 44
275 
276 /** hv_confstr */
277 #define HV_DISPATCH_CONFSTR                       45
278 
279 /** hv_reexec */
280 #define HV_DISPATCH_REEXEC                        46
281 
282 /** hv_set_command_line */
283 #define HV_DISPATCH_SET_COMMAND_LINE              47
284 
285 #if !CHIP_HAS_IPI()
286 
287 /** hv_clear_intr */
288 #define HV_DISPATCH_CLEAR_INTR                    48
289 
290 /** hv_enable_intr */
291 #define HV_DISPATCH_ENABLE_INTR                   49
292 
293 /** hv_disable_intr */
294 #define HV_DISPATCH_DISABLE_INTR                  50
295 
296 /** hv_raise_intr */
297 #define HV_DISPATCH_RAISE_INTR                    51
298 
299 /** hv_trigger_ipi */
300 #define HV_DISPATCH_TRIGGER_IPI                   52
301 
302 #endif /* !CHIP_HAS_IPI() */
303 
304 /** hv_store_mapping */
305 #define HV_DISPATCH_STORE_MAPPING                 53
306 
307 /** hv_inquire_realpa */
308 #define HV_DISPATCH_INQUIRE_REALPA                54
309 
310 /** hv_flush_all */
311 #define HV_DISPATCH_FLUSH_ALL                     55
312 
313 #if CHIP_HAS_IPI()
314 /** hv_get_ipi_pte */
315 #define HV_DISPATCH_GET_IPI_PTE                   56
316 #endif
317 
318 /** hv_set_pte_super_shift */
319 #define HV_DISPATCH_SET_PTE_SUPER_SHIFT           57
320 
321 /** hv_console_set_ipi */
322 #define HV_DISPATCH_CONSOLE_SET_IPI               63
323 
324 /** hv_send_nmi */
325 #define HV_DISPATCH_SEND_NMI                      65
326 
327 /** One more than the largest dispatch value */
328 #define _HV_DISPATCH_END                          66
329 
330 
331 #ifndef __ASSEMBLER__
332 
333 #ifdef __KERNEL__
334 #include <asm/types.h>
335 typedef u32 __hv32;        /**< 32-bit value */
336 typedef u64 __hv64;        /**< 64-bit value */
337 #else
338 #include <stdint.h>
339 typedef uint32_t __hv32;   /**< 32-bit value */
340 typedef uint64_t __hv64;   /**< 64-bit value */
341 #endif
342 
343 
344 /** Hypervisor physical address. */
345 typedef __hv64 HV_PhysAddr;
346 
347 #if CHIP_VA_WIDTH() > 32
348 /** Hypervisor virtual address. */
349 typedef __hv64 HV_VirtAddr;
350 #else
351 /** Hypervisor virtual address. */
352 typedef __hv32 HV_VirtAddr;
353 #endif /* CHIP_VA_WIDTH() > 32 */
354 
355 /** Hypervisor ASID. */
356 typedef unsigned int HV_ASID;
357 
358 /** Hypervisor tile location for a memory access
359  * ("location overridden target").
360  */
361 typedef unsigned int HV_LOTAR;
362 
363 /** Hypervisor size of a page. */
364 typedef unsigned long HV_PageSize;
365 
366 /** A page table entry.
367  */
368 typedef struct
369 {
370   __hv64 val;                /**< Value of PTE */
371 } HV_PTE;
372 
373 /** Hypervisor error code. */
374 typedef int HV_Errno;
375 
376 #endif /* !__ASSEMBLER__ */
377 
378 #define HV_OK           0    /**< No error */
379 #define HV_EINVAL      -801  /**< Invalid argument */
380 #define HV_ENODEV      -802  /**< No such device */
381 #define HV_ENOENT      -803  /**< No such file or directory */
382 #define HV_EBADF       -804  /**< Bad file number */
383 #define HV_EFAULT      -805  /**< Bad address */
384 #define HV_ERECIP      -806  /**< Bad recipients */
385 #define HV_E2BIG       -807  /**< Message too big */
386 #define HV_ENOTSUP     -808  /**< Service not supported */
387 #define HV_EBUSY       -809  /**< Device busy */
388 #define HV_ENOSYS      -810  /**< Invalid syscall */
389 #define HV_EPERM       -811  /**< No permission */
390 #define HV_ENOTREADY   -812  /**< Device not ready */
391 #define HV_EIO         -813  /**< I/O error */
392 #define HV_ENOMEM      -814  /**< Out of memory */
393 #define HV_EAGAIN      -815  /**< Try again */
394 
395 #define HV_ERR_MAX     -801  /**< Largest HV error code */
396 #define HV_ERR_MIN     -815  /**< Smallest HV error code */
397 
398 #ifndef __ASSEMBLER__
399 
400 /** Pass HV_VERSION to hv_init to request this version of the interface. */
401 typedef enum {
402   HV_VERSION = _HV_VERSION,
403   HV_VERSION_OLD_HV_INIT = _HV_VERSION_OLD_HV_INIT,
404 
405 } HV_VersionNumber;
406 
407 /** Initializes the hypervisor.
408  *
409  * @param interface_version_number The version of the hypervisor interface
410  * that this program expects, typically HV_VERSION.
411  * @param chip_num Architecture number of the chip the client was built for.
412  * @param chip_rev_num Revision number of the chip the client was built for.
413  * @param client_pl Privilege level the client is built for
414  *   (not required if interface_version_number == HV_VERSION_OLD_HV_INIT).
415  */
416 void hv_init(HV_VersionNumber interface_version_number,
417              int chip_num, int chip_rev_num, int client_pl);
418 
419 
420 /** Queries we can make for hv_sysconf().
421  *
422  * These numbers are part of the binary API and guaranteed not to change.
423  */
424 typedef enum {
425   /** An invalid value; do not use. */
426   _HV_SYSCONF_RESERVED       = 0,
427 
428   /** The length of the glue section containing the hv_ procs, in bytes. */
429   HV_SYSCONF_GLUE_SIZE       = 1,
430 
431   /** The size of small pages, in bytes. */
432   HV_SYSCONF_PAGE_SIZE_SMALL = 2,
433 
434   /** The size of large pages, in bytes. */
435   HV_SYSCONF_PAGE_SIZE_LARGE = 3,
436 
437   /** Processor clock speed, in hertz. */
438   HV_SYSCONF_CPU_SPEED       = 4,
439 
440   /** Processor temperature, in degrees Kelvin.  The value
441    *  HV_SYSCONF_TEMP_KTOC may be subtracted from this to get degrees
442    *  Celsius.  If that Celsius value is HV_SYSCONF_OVERTEMP, this indicates
443    *  that the temperature has hit an upper limit and is no longer being
444    *  accurately tracked.
445    */
446   HV_SYSCONF_CPU_TEMP        = 5,
447 
448   /** Board temperature, in degrees Kelvin.  The value
449    *  HV_SYSCONF_TEMP_KTOC may be subtracted from this to get degrees
450    *  Celsius.  If that Celsius value is HV_SYSCONF_OVERTEMP, this indicates
451    *  that the temperature has hit an upper limit and is no longer being
452    *  accurately tracked.
453    */
454   HV_SYSCONF_BOARD_TEMP      = 6,
455 
456   /** Legal page size bitmask for hv_install_context().
457    * For example, if 16KB and 64KB small pages are supported,
458    * it would return "HV_CTX_PG_SM_16K | HV_CTX_PG_SM_64K".
459    */
460   HV_SYSCONF_VALID_PAGE_SIZES = 7,
461 
462   /** The size of jumbo pages, in bytes.
463    * If no jumbo pages are available, zero will be returned.
464    */
465   HV_SYSCONF_PAGE_SIZE_JUMBO = 8,
466 
467 } HV_SysconfQuery;
468 
469 /** Offset to subtract from returned Kelvin temperature to get degrees
470     Celsius. */
471 #define HV_SYSCONF_TEMP_KTOC 273
472 
473 /** Pseudo-temperature value indicating that the temperature has
474  *  pegged at its upper limit and is no longer accurate; note that this is
475  *  the value after subtracting HV_SYSCONF_TEMP_KTOC. */
476 #define HV_SYSCONF_OVERTEMP 999
477 
478 /** Query a configuration value from the hypervisor.
479  * @param query Which value is requested (HV_SYSCONF_xxx).
480  * @return The requested value, or -1 the requested value is illegal or
481  *         unavailable.
482  */
483 long hv_sysconf(HV_SysconfQuery query);
484 
485 
486 /** Queries we can make for hv_confstr().
487  *
488  * These numbers are part of the binary API and guaranteed not to change.
489  */
490 typedef enum {
491   /** An invalid value; do not use. */
492   _HV_CONFSTR_RESERVED        = 0,
493 
494   /** Board part number. */
495   HV_CONFSTR_BOARD_PART_NUM   = 1,
496 
497   /** Board serial number. */
498   HV_CONFSTR_BOARD_SERIAL_NUM = 2,
499 
500   /** Chip serial number. */
501   HV_CONFSTR_CHIP_SERIAL_NUM  = 3,
502 
503   /** Board revision level. */
504   HV_CONFSTR_BOARD_REV        = 4,
505 
506   /** Hypervisor software version. */
507   HV_CONFSTR_HV_SW_VER        = 5,
508 
509   /** The name for this chip model. */
510   HV_CONFSTR_CHIP_MODEL       = 6,
511 
512   /** Human-readable board description. */
513   HV_CONFSTR_BOARD_DESC       = 7,
514 
515   /** Human-readable description of the hypervisor configuration. */
516   HV_CONFSTR_HV_CONFIG        = 8,
517 
518   /** Human-readable version string for the boot image (for instance,
519    *  who built it and when, what configuration file was used). */
520   HV_CONFSTR_HV_CONFIG_VER    = 9,
521 
522   /** Mezzanine part number. */
523   HV_CONFSTR_MEZZ_PART_NUM   = 10,
524 
525   /** Mezzanine serial number. */
526   HV_CONFSTR_MEZZ_SERIAL_NUM = 11,
527 
528   /** Mezzanine revision level. */
529   HV_CONFSTR_MEZZ_REV        = 12,
530 
531   /** Human-readable mezzanine description. */
532   HV_CONFSTR_MEZZ_DESC       = 13,
533 
534   /** Control path for the onboard network switch. */
535   HV_CONFSTR_SWITCH_CONTROL  = 14,
536 
537   /** Chip revision level. */
538   HV_CONFSTR_CHIP_REV        = 15,
539 
540   /** CPU module part number. */
541   HV_CONFSTR_CPUMOD_PART_NUM = 16,
542 
543   /** CPU module serial number. */
544   HV_CONFSTR_CPUMOD_SERIAL_NUM = 17,
545 
546   /** CPU module revision level. */
547   HV_CONFSTR_CPUMOD_REV      = 18,
548 
549   /** Human-readable CPU module description. */
550   HV_CONFSTR_CPUMOD_DESC     = 19,
551 
552   /** Per-tile hypervisor statistics.  When this identifier is specified,
553    *  the hv_confstr call takes two extra arguments.  The first is the
554    *  HV_XY_TO_LOTAR of the target tile's coordinates.  The second is
555    *  a flag word.  The only current flag is the lowest bit, which means
556    *  "zero out the stats instead of retrieving them"; in this case the
557    *  buffer and buffer length are ignored. */
558   HV_CONFSTR_HV_STATS        = 20
559 
560 } HV_ConfstrQuery;
561 
562 /** Query a configuration string from the hypervisor.
563  *
564  * @param query Identifier for the specific string to be retrieved
565  *        (HV_CONFSTR_xxx).  Some strings may require or permit extra
566  *        arguments to be appended which select specific objects to be
567  *        described; see the string descriptions above.
568  * @param buf Buffer in which to place the string.
569  * @param len Length of the buffer.
570  * @return If query is valid, then the length of the corresponding string,
571  *        including the trailing null; if this is greater than len, the string
572  *        was truncated.  If query is invalid, HV_EINVAL.  If the specified
573  *        buffer is not writable by the client, HV_EFAULT.
574  */
575 int hv_confstr(HV_ConfstrQuery query, HV_VirtAddr buf, int len, ...);
576 
577 /** Tile coordinate */
578 typedef struct
579 {
580   /** X coordinate, relative to supervisor's top-left coordinate */
581   int x;
582 
583   /** Y coordinate, relative to supervisor's top-left coordinate */
584   int y;
585 } HV_Coord;
586 
587 
588 #if CHIP_HAS_IPI()
589 
590 /** Get the PTE for sending an IPI to a particular tile.
591  *
592  * @param tile Tile which will receive the IPI.
593  * @param pl Indicates which IPI registers: 0 = IPI_0, 1 = IPI_1.
594  * @param pte Filled with resulting PTE.
595  * @result Zero if no error, non-zero for invalid parameters.
596  */
597 int hv_get_ipi_pte(HV_Coord tile, int pl, HV_PTE* pte);
598 
599 /** Configure the console interrupt.
600  *
601  * When the console client interrupt is enabled, the hypervisor will
602  * deliver the specified IPI to the client in the following situations:
603  *
604  * - The console has at least one character available for input.
605  *
606  * - The console can accept new characters for output, and the last call
607  *   to hv_console_write() did not write all of the characters requested
608  *   by the client.
609  *
610  * Note that in some system configurations, console interrupt will not
611  * be available; clients should be prepared for this routine to fail and
612  * to fall back to periodic console polling in that case.
613  *
614  * @param ipi Index of the IPI register which will receive the interrupt.
615  * @param event IPI event number for console interrupt. If less than 0,
616  *        disable the console IPI interrupt.
617  * @param coord Tile to be targeted for console interrupt.
618  * @return 0 on success, otherwise, HV_EINVAL if illegal parameter,
619  *         HV_ENOTSUP if console interrupt are not available.
620  */
621 int hv_console_set_ipi(int ipi, int event, HV_Coord coord);
622 
623 #else /* !CHIP_HAS_IPI() */
624 
625 /** A set of interrupts. */
626 typedef __hv32 HV_IntrMask;
627 
628 /** The low interrupt numbers are reserved for use by the client in
629  *  delivering IPIs.  Any interrupt numbers higher than this value are
630  *  reserved for use by HV device drivers. */
631 #define HV_MAX_IPI_INTERRUPT 7
632 
633 /** Enable a set of device interrupts.
634  *
635  * @param enab_mask Bitmap of interrupts to enable.
636  */
637 void hv_enable_intr(HV_IntrMask enab_mask);
638 
639 /** Disable a set of device interrupts.
640  *
641  * @param disab_mask Bitmap of interrupts to disable.
642  */
643 void hv_disable_intr(HV_IntrMask disab_mask);
644 
645 /** Clear a set of device interrupts.
646  *
647  * @param clear_mask Bitmap of interrupts to clear.
648  */
649 void hv_clear_intr(HV_IntrMask clear_mask);
650 
651 /** Raise a set of device interrupts.
652  *
653  * @param raise_mask Bitmap of interrupts to raise.
654  */
655 void hv_raise_intr(HV_IntrMask raise_mask);
656 
657 /** Trigger a one-shot interrupt on some tile
658  *
659  * @param tile Which tile to interrupt.
660  * @param interrupt Interrupt number to trigger; must be between 0 and
661  *        HV_MAX_IPI_INTERRUPT.
662  * @return HV_OK on success, or a hypervisor error code.
663  */
664 HV_Errno hv_trigger_ipi(HV_Coord tile, int interrupt);
665 
666 #endif /* !CHIP_HAS_IPI() */
667 
668 /** Store memory mapping in debug memory so that external debugger can read it.
669  * A maximum of 16 entries can be stored.
670  *
671  * @param va VA of memory that is mapped.
672  * @param len Length of mapped memory.
673  * @param pa PA of memory that is mapped.
674  * @return 0 on success, -1 if the maximum number of mappings is exceeded.
675  */
676 int hv_store_mapping(HV_VirtAddr va, unsigned int len, HV_PhysAddr pa);
677 
678 /** Given a client PA and a length, return its real (HV) PA.
679  *
680  * @param cpa Client physical address.
681  * @param len Length of mapped memory.
682  * @return physical address, or -1 if cpa or len is not valid.
683  */
684 HV_PhysAddr hv_inquire_realpa(HV_PhysAddr cpa, unsigned int len);
685 
686 /** RTC return flag for no RTC chip present.
687  */
688 #define HV_RTC_NO_CHIP     0x1
689 
690 /** RTC return flag for low-voltage condition, indicating that battery had
691  * died and time read is unreliable.
692  */
693 #define HV_RTC_LOW_VOLTAGE 0x2
694 
695 /** Date/Time of day */
696 typedef struct {
697 #if CHIP_WORD_SIZE() > 32
698   __hv64 tm_sec;   /**< Seconds, 0-59 */
699   __hv64 tm_min;   /**< Minutes, 0-59 */
700   __hv64 tm_hour;  /**< Hours, 0-23 */
701   __hv64 tm_mday;  /**< Day of month, 0-30 */
702   __hv64 tm_mon;   /**< Month, 0-11 */
703   __hv64 tm_year;  /**< Years since 1900, 0-199 */
704   __hv64 flags;    /**< Return flags, 0 if no error */
705 #else
706   __hv32 tm_sec;   /**< Seconds, 0-59 */
707   __hv32 tm_min;   /**< Minutes, 0-59 */
708   __hv32 tm_hour;  /**< Hours, 0-23 */
709   __hv32 tm_mday;  /**< Day of month, 0-30 */
710   __hv32 tm_mon;   /**< Month, 0-11 */
711   __hv32 tm_year;  /**< Years since 1900, 0-199 */
712   __hv32 flags;    /**< Return flags, 0 if no error */
713 #endif
714 } HV_RTCTime;
715 
716 /** Read the current time-of-day clock.
717  * @return HV_RTCTime of current time (GMT).
718  */
719 HV_RTCTime hv_get_rtc(void);
720 
721 
722 /** Set the current time-of-day clock.
723  * @param time time to reset time-of-day to (GMT).
724  */
725 void hv_set_rtc(HV_RTCTime time);
726 
727 /** Installs a context, comprising a page table and other attributes.
728  *
729  *  Once this service completes, page_table will be used to translate
730  *  subsequent virtual address references to physical memory.
731  *
732  *  Installing a context does not cause an implicit TLB flush.  Before
733  *  reusing an ASID value for a different address space, the client is
734  *  expected to flush old references from the TLB with hv_flush_asid().
735  *  (Alternately, hv_flush_all() may be used to flush many ASIDs at once.)
736  *  After invalidating a page table entry, changing its attributes, or
737  *  changing its target CPA, the client is expected to flush old references
738  *  from the TLB with hv_flush_page() or hv_flush_pages(). Making a
739  *  previously invalid page valid does not require a flush.
740  *
741  *  Specifying an invalid ASID, or an invalid CPA (client physical address)
742  *  (either as page_table_pointer, or within the referenced table),
743  *  or another page table data item documented as above as illegal may
744  *  lead to client termination; since the validation of the table is
745  *  done as needed, this may happen before the service returns, or at
746  *  some later time, or never, depending upon the client's pattern of
747  *  memory references.  Page table entries which supply translations for
748  *  invalid virtual addresses may result in client termination, or may
749  *  be silently ignored.  "Invalid" in this context means a value which
750  *  was not provided to the client via the appropriate hv_inquire_* routine.
751  *
752  *  To support changing the instruction VAs at the same time as
753  *  installing the new page table, this call explicitly supports
754  *  setting the "lr" register to a different address and then jumping
755  *  directly to the hv_install_context() routine.  In this case, the
756  *  new page table does not need to contain any mapping for the
757  *  hv_install_context address itself.
758  *
759  *  At most one HV_CTX_PG_SM_* flag may be specified in "flags";
760  *  if multiple flags are specified, HV_EINVAL is returned.
761  *  Specifying none of the flags results in using the default page size.
762  *  All cores participating in a given client must request the same
763  *  page size, or the results are undefined.
764  *
765  * @param page_table Root of the page table.
766  * @param access PTE providing info on how to read the page table.  This
767  *   value must be consistent between multiple tiles sharing a page table,
768  *   and must also be consistent with any virtual mappings the client
769  *   may be using to access the page table.
770  * @param asid HV_ASID the page table is to be used for.
771  * @param flags Context flags, denoting attributes or privileges of the
772  *   current context (HV_CTX_xxx).
773  * @return Zero on success, or a hypervisor error code on failure.
774  */
775 int hv_install_context(HV_PhysAddr page_table, HV_PTE access, HV_ASID asid,
776                        __hv32 flags);
777 
778 #endif /* !__ASSEMBLER__ */
779 
780 #define HV_CTX_DIRECTIO     0x1   /**< Direct I/O requests are accepted from
781                                        PL0. */
782 
783 #define HV_CTX_PG_SM_4K     0x10  /**< Use 4K small pages, if available. */
784 #define HV_CTX_PG_SM_16K    0x20  /**< Use 16K small pages, if available. */
785 #define HV_CTX_PG_SM_64K    0x40  /**< Use 64K small pages, if available. */
786 #define HV_CTX_PG_SM_MASK   0xf0  /**< Mask of all possible small pages. */
787 
788 #ifndef __ASSEMBLER__
789 
790 
791 /** Set the number of pages ganged together by HV_PTE_SUPER at a
792  * particular level of the page table.
793  *
794  * The current TILE-Gx hardware only supports powers of four
795  * (i.e. log2_count must be a multiple of two), and the requested
796  * "super" page size must be less than the span of the next level in
797  * the page table.  The largest size that can be requested is 64GB.
798  *
799  * The shift value is initially "0" for all page table levels,
800  * indicating that the HV_PTE_SUPER bit is effectively ignored.
801  *
802  * If you change the count from one non-zero value to another, the
803  * hypervisor will flush the entire TLB and TSB to avoid confusion.
804  *
805  * @param level Page table level (0, 1, or 2)
806  * @param log2_count Base-2 log of the number of pages to gang together,
807  * i.e. how much to shift left the base page size for the super page size.
808  * @return Zero on success, or a hypervisor error code on failure.
809  */
810 int hv_set_pte_super_shift(int level, int log2_count);
811 
812 
813 /** Value returned from hv_inquire_context(). */
814 typedef struct
815 {
816   /** Physical address of page table */
817   HV_PhysAddr page_table;
818 
819   /** PTE which defines access method for top of page table */
820   HV_PTE access;
821 
822   /** ASID associated with this page table */
823   HV_ASID asid;
824 
825   /** Context flags */
826   __hv32 flags;
827 } HV_Context;
828 
829 /** Retrieve information about the currently installed context.
830  * @return The data passed to the last successful hv_install_context call.
831  */
832 HV_Context hv_inquire_context(void);
833 
834 
835 /** Flushes all translations associated with the named address space
836  *  identifier from the TLB and any other hypervisor data structures.
837  *  Translations installed with the "global" bit are not flushed.
838  *
839  *  Specifying an invalid ASID may lead to client termination.  "Invalid"
840  *  in this context means a value which was not provided to the client
841  *  via <tt>hv_inquire_asid()</tt>.
842  *
843  * @param asid HV_ASID whose entries are to be flushed.
844  * @return Zero on success, or a hypervisor error code on failure.
845 */
846 int hv_flush_asid(HV_ASID asid);
847 
848 
849 /** Flushes all translations associated with the named virtual address
850  *  and page size from the TLB and other hypervisor data structures. Only
851  *  pages visible to the current ASID are affected; note that this includes
852  *  global pages in addition to pages specific to the current ASID.
853  *
854  *  The supplied VA need not be aligned; it may be anywhere in the
855  *  subject page.
856  *
857  *  Specifying an invalid virtual address may lead to client termination,
858  *  or may silently succeed.  "Invalid" in this context means a value
859  *  which was not provided to the client via hv_inquire_virtual.
860  *
861  * @param address Address of the page to flush.
862  * @param page_size Size of pages to assume.
863  * @return Zero on success, or a hypervisor error code on failure.
864  */
865 int hv_flush_page(HV_VirtAddr address, HV_PageSize page_size);
866 
867 
868 /** Flushes all translations associated with the named virtual address range
869  *  and page size from the TLB and other hypervisor data structures. Only
870  *  pages visible to the current ASID are affected; note that this includes
871  *  global pages in addition to pages specific to the current ASID.
872  *
873  *  The supplied VA need not be aligned; it may be anywhere in the
874  *  subject page.
875  *
876  *  Specifying an invalid virtual address may lead to client termination,
877  *  or may silently succeed.  "Invalid" in this context means a value
878  *  which was not provided to the client via hv_inquire_virtual.
879  *
880  * @param start Address to flush.
881  * @param page_size Size of pages to assume.
882  * @param size The number of bytes to flush. Any page in the range
883  *        [start, start + size) will be flushed from the TLB.
884  * @return Zero on success, or a hypervisor error code on failure.
885  */
886 int hv_flush_pages(HV_VirtAddr start, HV_PageSize page_size,
887                    unsigned long size);
888 
889 
890 /** Flushes all non-global translations (if preserve_global is true),
891  *  or absolutely all translations (if preserve_global is false).
892  *
893  * @param preserve_global Non-zero if we want to preserve "global" mappings.
894  * @return Zero on success, or a hypervisor error code on failure.
895 */
896 int hv_flush_all(int preserve_global);
897 
898 
899 /** Restart machine with optional restart command and optional args.
900  * @param cmd Const pointer to command to restart with, or NULL
901  * @param args Const pointer to argument string to restart with, or NULL
902  */
903 void hv_restart(HV_VirtAddr cmd, HV_VirtAddr args);
904 
905 
906 /** Halt machine. */
907 void hv_halt(void);
908 
909 
910 /** Power off machine. */
911 void hv_power_off(void);
912 
913 
914 /** Re-enter virtual-is-physical memory translation mode and restart
915  *  execution at a given address.
916  * @param entry Client physical address at which to begin execution.
917  * @return A hypervisor error code on failure; if the operation is
918  *         successful the call does not return.
919  */
920 int hv_reexec(HV_PhysAddr entry);
921 
922 
923 /** Chip topology */
924 typedef struct
925 {
926   /** Relative coordinates of the querying tile */
927   HV_Coord coord;
928 
929   /** Width of the querying supervisor's tile rectangle. */
930   int width;
931 
932   /** Height of the querying supervisor's tile rectangle. */
933   int height;
934 
935 } HV_Topology;
936 
937 /** Returns information about the tile coordinate system.
938  *
939  * Each supervisor is given a rectangle of tiles it potentially controls.
940  * These tiles are labeled using a relative coordinate system with (0,0) as
941  * the upper left tile regardless of their physical location on the chip.
942  *
943  * This call returns both the size of that rectangle and the position
944  * within that rectangle of the querying tile.
945  *
946  * Not all tiles within that rectangle may be available to the supervisor;
947  * to get the precise set of available tiles, you must also call
948  * hv_inquire_tiles(HV_INQ_TILES_AVAIL, ...).
949  **/
950 HV_Topology hv_inquire_topology(void);
951 
952 /** Sets of tiles we can retrieve with hv_inquire_tiles().
953  *
954  * These numbers are part of the binary API and guaranteed not to change.
955  */
956 typedef enum {
957   /** An invalid value; do not use. */
958   _HV_INQ_TILES_RESERVED       = 0,
959 
960   /** All available tiles within the supervisor's tile rectangle. */
961   HV_INQ_TILES_AVAIL           = 1,
962 
963   /** The set of tiles used for hash-for-home caching. */
964   HV_INQ_TILES_HFH_CACHE       = 2,
965 
966   /** The set of tiles that can be legally used as a LOTAR for a PTE. */
967   HV_INQ_TILES_LOTAR           = 3,
968 
969   /** The set of "shared" driver tiles that the hypervisor may
970    *  periodically interrupt. */
971   HV_INQ_TILES_SHARED          = 4
972 } HV_InqTileSet;
973 
974 /** Returns specific information about various sets of tiles within the
975  *  supervisor's tile rectangle.
976  *
977  * @param set Which set of tiles to retrieve.
978  * @param cpumask Pointer to a returned bitmask (in row-major order,
979  *        supervisor-relative) of tiles.  The low bit of the first word
980  *        corresponds to the tile at the upper left-hand corner of the
981  *        supervisor's rectangle.  In order for the supervisor to know the
982  *        buffer length to supply, it should first call hv_inquire_topology.
983  * @param length Number of bytes available for the returned bitmask.
984  **/
985 HV_Errno hv_inquire_tiles(HV_InqTileSet set, HV_VirtAddr cpumask, int length);
986 
987 
988 /** An identifier for a memory controller. Multiple memory controllers
989  * may be connected to one chip, and this uniquely identifies each one.
990  */
991 typedef int HV_MemoryController;
992 
993 /** A range of physical memory. */
994 typedef struct
995 {
996   HV_PhysAddr start;   /**< Starting address. */
997   __hv64 size;         /**< Size in bytes. */
998   HV_MemoryController controller;  /**< Which memory controller owns this. */
999 } HV_PhysAddrRange;
1000 
1001 /** Returns information about a range of physical memory.
1002  *
1003  * hv_inquire_physical() returns one of the ranges of client
1004  * physical addresses which are available to this client.
1005  *
1006  * The first range is retrieved by specifying an idx of 0, and
1007  * successive ranges are returned with subsequent idx values.  Ranges
1008  * are ordered by increasing start address (i.e., as idx increases,
1009  * so does start), do not overlap, and do not touch (i.e., the
1010  * available memory is described with the fewest possible ranges).
1011  *
1012  * If an out-of-range idx value is specified, the returned size will be zero.
1013  * A client can count the number of ranges by increasing idx until the
1014  * returned size is zero. There will always be at least one valid range.
1015  *
1016  * Some clients might not be prepared to deal with more than one
1017  * physical address range; they still ought to call this routine and
1018  * issue a warning message if they're given more than one range, on the
1019  * theory that whoever configured the hypervisor to provide that memory
1020  * should know that it's being wasted.
1021  */
1022 HV_PhysAddrRange hv_inquire_physical(int idx);
1023 
1024 /** Possible DIMM types. */
1025 typedef enum
1026 {
1027   NO_DIMM                    = 0,  /**< No DIMM */
1028   DDR2                       = 1,  /**< DDR2 */
1029   DDR3                       = 2   /**< DDR3 */
1030 } HV_DIMM_Type;
1031 
1032 #ifdef __tilegx__
1033 
1034 /** Log2 of minimum DIMM bytes supported by the memory controller. */
1035 #define HV_MSH_MIN_DIMM_SIZE_SHIFT 29
1036 
1037 /** Max number of DIMMs contained by one memory controller. */
1038 #define HV_MSH_MAX_DIMMS 8
1039 
1040 #else
1041 
1042 /** Log2 of minimum DIMM bytes supported by the memory controller. */
1043 #define HV_MSH_MIN_DIMM_SIZE_SHIFT 26
1044 
1045 /** Max number of DIMMs contained by one memory controller. */
1046 #define HV_MSH_MAX_DIMMS 2
1047 
1048 #endif
1049 
1050 /** Number of bits to right-shift to get the DIMM type. */
1051 #define HV_DIMM_TYPE_SHIFT 0
1052 
1053 /** Bits to mask to get the DIMM type. */
1054 #define HV_DIMM_TYPE_MASK 0xf
1055 
1056 /** Number of bits to right-shift to get the DIMM size. */
1057 #define HV_DIMM_SIZE_SHIFT 4
1058 
1059 /** Bits to mask to get the DIMM size. */
1060 #define HV_DIMM_SIZE_MASK 0xf
1061 
1062 /** Memory controller information. */
1063 typedef struct
1064 {
1065   HV_Coord coord;   /**< Relative tile coordinates of the port used by a
1066                          specified tile to communicate with this controller. */
1067   __hv64 speed;     /**< Speed of this controller in bytes per second. */
1068 } HV_MemoryControllerInfo;
1069 
1070 /** Returns information about a particular memory controller.
1071  *
1072  *  hv_inquire_memory_controller(coord,idx) returns information about a
1073  *  particular controller.  Two pieces of information are returned:
1074  *  - The relative coordinates of the port on the controller that the specified
1075  *    tile would use to contact it.  The relative coordinates may lie
1076  *    outside the supervisor's rectangle, i.e. the controller may not
1077  *    be attached to a node managed by the querying node's supervisor.
1078  *    In particular note that x or y may be negative.
1079  *  - The speed of the memory controller.  (This is a not-to-exceed value
1080  *    based on the raw hardware data rate, and may not be achievable in
1081  *    practice; it is provided to give clients information on the relative
1082  *    performance of the available controllers.)
1083  *
1084  *  Clients should avoid calling this interface with invalid values.
1085  *  A client who does may be terminated.
1086  * @param coord Tile for which to calculate the relative port position.
1087  * @param controller Index of the controller; identical to value returned
1088  *        from other routines like hv_inquire_physical.
1089  * @return Information about the controller.
1090  */
1091 HV_MemoryControllerInfo hv_inquire_memory_controller(HV_Coord coord,
1092                                                      int controller);
1093 
1094 
1095 /** A range of virtual memory. */
1096 typedef struct
1097 {
1098   HV_VirtAddr start;   /**< Starting address. */
1099   __hv64 size;         /**< Size in bytes. */
1100 } HV_VirtAddrRange;
1101 
1102 /** Returns information about a range of virtual memory.
1103  *
1104  * hv_inquire_virtual() returns one of the ranges of client
1105  * virtual addresses which are available to this client.
1106  *
1107  * The first range is retrieved by specifying an idx of 0, and
1108  * successive ranges are returned with subsequent idx values.  Ranges
1109  * are ordered by increasing start address (i.e., as idx increases,
1110  * so does start), do not overlap, and do not touch (i.e., the
1111  * available memory is described with the fewest possible ranges).
1112  *
1113  * If an out-of-range idx value is specified, the returned size will be zero.
1114  * A client can count the number of ranges by increasing idx until the
1115  * returned size is zero. There will always be at least one valid range.
1116  *
1117  * Some clients may well have various virtual addresses hardwired
1118  * into themselves; for instance, their instruction stream may
1119  * have been compiled expecting to live at a particular address.
1120  * Such clients should use this interface to verify they've been
1121  * given the virtual address space they expect, and issue a (potentially
1122  * fatal) warning message otherwise.
1123  *
1124  * Note that the returned size is a __hv64, not a __hv32, so it is
1125  * possible to express a single range spanning the entire 32-bit
1126  * address space.
1127  */
1128 HV_VirtAddrRange hv_inquire_virtual(int idx);
1129 
1130 
1131 /** A range of ASID values. */
1132 typedef struct
1133 {
1134   HV_ASID start;        /**< First ASID in the range. */
1135   unsigned int size;    /**< Number of ASIDs. Zero for an invalid range. */
1136 } HV_ASIDRange;
1137 
1138 /** Returns information about a range of ASIDs.
1139  *
1140  * hv_inquire_asid() returns one of the ranges of address
1141  * space identifiers which are available to this client.
1142  *
1143  * The first range is retrieved by specifying an idx of 0, and
1144  * successive ranges are returned with subsequent idx values.  Ranges
1145  * are ordered by increasing start value (i.e., as idx increases,
1146  * so does start), do not overlap, and do not touch (i.e., the
1147  * available ASIDs are described with the fewest possible ranges).
1148  *
1149  * If an out-of-range idx value is specified, the returned size will be zero.
1150  * A client can count the number of ranges by increasing idx until the
1151  * returned size is zero. There will always be at least one valid range.
1152  */
1153 HV_ASIDRange hv_inquire_asid(int idx);
1154 
1155 
1156 /** Waits for at least the specified number of nanoseconds then returns.
1157  *
1158  * NOTE: this deprecated function currently assumes a 750 MHz clock,
1159  * and is thus not generally suitable for use.  New code should call
1160  * hv_sysconf(HV_SYSCONF_CPU_SPEED), compute a cycle count to wait for,
1161  * and delay by looping while checking the cycle counter SPR.
1162  *
1163  * @param nanosecs The number of nanoseconds to sleep.
1164  */
1165 void hv_nanosleep(int nanosecs);
1166 
1167 
1168 /** Reads a character from the console without blocking.
1169  *
1170  * @return A value from 0-255 indicates the value successfully read.
1171  * A negative value means no value was ready.
1172  */
1173 int hv_console_read_if_ready(void);
1174 
1175 
1176 /** Writes a character to the console, blocking if the console is busy.
1177  *
1178  *  This call cannot fail. If the console is broken for some reason,
1179  *  output will simply vanish.
1180  * @param byte Character to write.
1181  */
1182 void hv_console_putc(int byte);
1183 
1184 
1185 /** Writes a string to the console, blocking if the console is busy.
1186  * @param bytes Pointer to characters to write.
1187  * @param len Number of characters to write.
1188  * @return Number of characters written, or HV_EFAULT if the buffer is invalid.
1189  */
1190 int hv_console_write(HV_VirtAddr bytes, int len);
1191 
1192 
1193 /** Dispatch the next interrupt from the client downcall mechanism.
1194  *
1195  *  The hypervisor uses downcalls to notify the client of asynchronous
1196  *  events.  Some of these events are hypervisor-created (like incoming
1197  *  messages).  Some are regular interrupts which initially occur in
1198  *  the hypervisor, and are normally handled directly by the client;
1199  *  when these occur in a client's interrupt critical section, they must
1200  *  be delivered through the downcall mechanism.
1201  *
1202  *  A downcall is initially delivered to the client as an INTCTRL_CL
1203  *  interrupt, where CL is the client's PL.  Upon entry to the INTCTRL_CL
1204  *  vector, the client must immediately invoke the hv_downcall_dispatch
1205  *  service.  This service will not return; instead it will cause one of
1206  *  the client's actual downcall-handling interrupt vectors to be entered.
1207  *  The EX_CONTEXT registers in the client will be set so that when the
1208  *  client irets, it will return to the code which was interrupted by the
1209  *  INTCTRL_CL interrupt.
1210  *
1211  *  Under some circumstances, the firing of INTCTRL_CL can race with
1212  *  the lowering of a device interrupt.  In such a case, the
1213  *  hv_downcall_dispatch service may issue an iret instruction instead
1214  *  of entering one of the client's actual downcall-handling interrupt
1215  *  vectors.  This will return execution to the location that was
1216  *  interrupted by INTCTRL_CL.
1217  *
1218  *  Any saving of registers should be done by the actual handling
1219  *  vectors; no registers should be changed by the INTCTRL_CL handler.
1220  *  In particular, the client should not use a jal instruction to invoke
1221  *  the hv_downcall_dispatch service, as that would overwrite the client's
1222  *  lr register.  Note that the hv_downcall_dispatch service may overwrite
1223  *  one or more of the client's system save registers.
1224  *
1225  *  The client must not modify the INTCTRL_CL_STATUS SPR.  The hypervisor
1226  *  will set this register to cause a downcall to happen, and will clear
1227  *  it when no further downcalls are pending.
1228  *
1229  *  When a downcall vector is entered, the INTCTRL_CL interrupt will be
1230  *  masked.  When the client is done processing a downcall, and is ready
1231  *  to accept another, it must unmask this interrupt; if more downcalls
1232  *  are pending, this will cause the INTCTRL_CL vector to be reentered.
1233  *  Currently the following interrupt vectors can be entered through a
1234  *  downcall:
1235  *
1236  *  INT_MESSAGE_RCV_DWNCL   (hypervisor message available)
1237  *  INT_DEV_INTR_DWNCL      (device interrupt)
1238  *  INT_DMATLB_MISS_DWNCL   (DMA TLB miss)
1239  *  INT_SNITLB_MISS_DWNCL   (SNI TLB miss)
1240  *  INT_DMATLB_ACCESS_DWNCL (DMA TLB access violation)
1241  */
1242 void hv_downcall_dispatch(void);
1243 
1244 #endif /* !__ASSEMBLER__ */
1245 
1246 /** We use actual interrupt vectors which never occur (they're only there
1247  *  to allow setting MPLs for related SPRs) for our downcall vectors.
1248  */
1249 /** Message receive downcall interrupt vector */
1250 #define INT_MESSAGE_RCV_DWNCL    INT_BOOT_ACCESS
1251 /** DMA TLB miss downcall interrupt vector */
1252 #define INT_DMATLB_MISS_DWNCL    INT_DMA_ASID
1253 /** Static nework processor instruction TLB miss interrupt vector */
1254 #define INT_SNITLB_MISS_DWNCL    INT_SNI_ASID
1255 /** DMA TLB access violation downcall interrupt vector */
1256 #define INT_DMATLB_ACCESS_DWNCL  INT_DMA_CPL
1257 /** Device interrupt downcall interrupt vector */
1258 #define INT_DEV_INTR_DWNCL       INT_WORLD_ACCESS
1259 /** NMI downcall interrupt vector */
1260 #define INT_NMI_DWNCL            64
1261 
1262 #define HV_NMI_FLAG_FORCE    0x1  /**< Force an NMI downcall regardless of
1263                the ICS bit of the client. */
1264 
1265 #ifndef __ASSEMBLER__
1266 
1267 /** Requests the inode for a specific full pathname.
1268  *
1269  * Performs a lookup in the hypervisor filesystem for a given filename.
1270  * Multiple calls with the same filename will always return the same inode.
1271  * If there is no such filename, HV_ENOENT is returned.
1272  * A bad filename pointer may result in HV_EFAULT instead.
1273  *
1274  * @param filename Constant pointer to name of requested file
1275  * @return Inode of requested file
1276  */
1277 int hv_fs_findfile(HV_VirtAddr filename);
1278 
1279 
1280 /** Data returned from an fstat request.
1281  * Note that this structure should be no more than 40 bytes in size so
1282  * that it can always be returned completely in registers.
1283  */
1284 typedef struct
1285 {
1286   int size;             /**< Size of file (or HV_Errno on error) */
1287   unsigned int flags;   /**< Flags (see HV_FS_FSTAT_FLAGS) */
1288 } HV_FS_StatInfo;
1289 
1290 /** Bitmask flags for fstat request */
1291 typedef enum
1292 {
1293   HV_FS_ISDIR    = 0x0001   /**< Is the entry a directory? */
1294 } HV_FS_FSTAT_FLAGS;
1295 
1296 /** Get stat information on a given file inode.
1297  *
1298  * Return information on the file with the given inode.
1299  *
1300  * IF the HV_FS_ISDIR bit is set, the "file" is a directory.  Reading
1301  * it will return NUL-separated filenames (no directory part) relative
1302  * to the path to the inode of the directory "file".  These can be
1303  * appended to the path to the directory "file" after a forward slash
1304  * to create additional filenames.  Note that it is not required
1305  * that all valid paths be decomposable into valid parent directories;
1306  * a filesystem may validly have just a few files, none of which have
1307  * HV_FS_ISDIR set.  However, if clients may wish to enumerate the
1308  * files in the filesystem, it is recommended to include all the
1309  * appropriate parent directory "files" to give a consistent view.
1310  *
1311  * An invalid file inode will cause an HV_EBADF error to be returned.
1312  *
1313  * @param inode The inode number of the query
1314  * @return An HV_FS_StatInfo structure
1315  */
1316 HV_FS_StatInfo hv_fs_fstat(int inode);
1317 
1318 
1319 /** Read data from a specific hypervisor file.
1320  * On error, may return HV_EBADF for a bad inode or HV_EFAULT for a bad buf.
1321  * Reads near the end of the file will return fewer bytes than requested.
1322  * Reads at or beyond the end of a file will return zero.
1323  *
1324  * @param inode the hypervisor file to read
1325  * @param buf the buffer to read data into
1326  * @param length the number of bytes of data to read
1327  * @param offset the offset into the file to read the data from
1328  * @return number of bytes successfully read, or an HV_Errno code
1329  */
1330 int hv_fs_pread(int inode, HV_VirtAddr buf, int length, int offset);
1331 
1332 
1333 /** Read a 64-bit word from the specified physical address.
1334  * The address must be 8-byte aligned.
1335  * Specifying an invalid physical address will lead to client termination.
1336  * @param addr The physical address to read
1337  * @param access The PTE describing how to read the memory
1338  * @return The 64-bit value read from the given address
1339  */
1340 unsigned long long hv_physaddr_read64(HV_PhysAddr addr, HV_PTE access);
1341 
1342 
1343 /** Write a 64-bit word to the specified physical address.
1344  * The address must be 8-byte aligned.
1345  * Specifying an invalid physical address will lead to client termination.
1346  * @param addr The physical address to write
1347  * @param access The PTE that says how to write the memory
1348  * @param val The 64-bit value to write to the given address
1349  */
1350 void hv_physaddr_write64(HV_PhysAddr addr, HV_PTE access,
1351                          unsigned long long val);
1352 
1353 
1354 /** Get the value of the command-line for the supervisor, if any.
1355  * This will not include the filename of the booted supervisor, but may
1356  * include configured-in boot arguments or the hv_restart() arguments.
1357  * If the buffer is not long enough the hypervisor will NUL the first
1358  * character of the buffer but not write any other data.
1359  * @param buf The virtual address to write the command-line string to.
1360  * @param length The length of buf, in characters.
1361  * @return The actual length of the command line, including the trailing NUL
1362  *         (may be larger than "length").
1363  */
1364 int hv_get_command_line(HV_VirtAddr buf, int length);
1365 
1366 
1367 /** Set a new value for the command-line for the supervisor, which will
1368  *  be returned from subsequent invocations of hv_get_command_line() on
1369  *  this tile.
1370  * @param buf The virtual address to read the command-line string from.
1371  * @param length The length of buf, in characters; must be no more than
1372  *        HV_COMMAND_LINE_LEN.
1373  * @return Zero if successful, or a hypervisor error code.
1374  */
1375 HV_Errno hv_set_command_line(HV_VirtAddr buf, int length);
1376 
1377 /** Maximum size of a command line passed to hv_set_command_line(); note
1378  *  that a line returned from hv_get_command_line() could be larger than
1379  *  this.*/
1380 #define HV_COMMAND_LINE_LEN  256
1381 
1382 /** Tell the hypervisor how to cache non-priority pages
1383  * (its own as well as pages explicitly represented in page tables).
1384  * Normally these will be represented as red/black pages, but
1385  * when the supervisor starts to allocate "priority" pages in the PTE
1386  * the hypervisor will need to start marking those pages as (e.g.) "red"
1387  * and non-priority pages as either "black" (if they cache-alias
1388  * with the existing priority pages) or "red/black" (if they don't).
1389  * The bitmask provides information on which parts of the cache
1390  * have been used for pinned pages so far on this tile; if (1 << N)
1391  * appears in the bitmask, that indicates that a 4KB region of the
1392  * cache starting at (N * 4KB) is in use by a "priority" page.
1393  * The portion of cache used by a particular page can be computed
1394  * by taking the page's PA, modulo CHIP_L2_CACHE_SIZE(), and setting
1395  * all the "4KB" bits corresponding to the actual page size.
1396  * @param bitmask A bitmap of priority page set values
1397  */
1398 void hv_set_caching(unsigned long bitmask);
1399 
1400 
1401 /** Zero out a specified number of pages.
1402  * The va and size must both be multiples of 4096.
1403  * Caches are bypassed and memory is directly set to zero.
1404  * This API is implemented only in the magic hypervisor and is intended
1405  * to provide a performance boost to the minimal supervisor by
1406  * giving it a fast way to zero memory pages when allocating them.
1407  * @param va Virtual address where the page has been mapped
1408  * @param size Number of bytes (must be a page size multiple)
1409  */
1410 void hv_bzero_page(HV_VirtAddr va, unsigned int size);
1411 
1412 
1413 /** State object for the hypervisor messaging subsystem. */
1414 typedef struct
1415 {
1416 #if CHIP_VA_WIDTH() > 32
1417   __hv64 opaque[2]; /**< No user-serviceable parts inside */
1418 #else
1419   __hv32 opaque[2]; /**< No user-serviceable parts inside */
1420 #endif
1421 }
1422 HV_MsgState;
1423 
1424 /** Register to receive incoming messages.
1425  *
1426  *  This routine configures the current tile so that it can receive
1427  *  incoming messages.  It must be called before the client can receive
1428  *  messages with the hv_receive_message routine, and must be called on
1429  *  each tile which will receive messages.
1430  *
1431  *  msgstate is the virtual address of a state object of type HV_MsgState.
1432  *  Once the state is registered, the client must not read or write the
1433  *  state object; doing so will cause undefined results.
1434  *
1435  *  If this routine is called with msgstate set to 0, the client's message
1436  *  state will be freed and it will no longer be able to receive messages.
1437  *  Note that this may cause the loss of any as-yet-undelivered messages
1438  *  for the client.
1439  *
1440  *  If another client attempts to send a message to a client which has
1441  *  not yet called hv_register_message_state, or which has freed its
1442  *  message state, the message will not be delivered, as if the client
1443  *  had insufficient buffering.
1444  *
1445  *  This routine returns HV_OK if the registration was successful, and
1446  *  HV_EINVAL if the supplied state object is unsuitable.  Note that some
1447  *  errors may not be detected during this routine, but might be detected
1448  *  during a subsequent message delivery.
1449  * @param msgstate State object.
1450  **/
1451 HV_Errno hv_register_message_state(HV_MsgState* msgstate);
1452 
1453 /** Possible message recipient states. */
1454 typedef enum
1455 {
1456   HV_TO_BE_SENT,    /**< Not sent (not attempted, or recipient not ready) */
1457   HV_SENT,          /**< Successfully sent */
1458   HV_BAD_RECIP      /**< Bad recipient coordinates (permanent error) */
1459 } HV_Recip_State;
1460 
1461 /** Message recipient. */
1462 typedef struct
1463 {
1464   /** X coordinate, relative to supervisor's top-left coordinate */
1465   unsigned int x:11;
1466 
1467   /** Y coordinate, relative to supervisor's top-left coordinate */
1468   unsigned int y:11;
1469 
1470   /** Status of this recipient */
1471   HV_Recip_State state:10;
1472 } HV_Recipient;
1473 
1474 /** Send a message to a set of recipients.
1475  *
1476  *  This routine sends a message to a set of recipients.
1477  *
1478  *  recips is an array of HV_Recipient structures.  Each specifies a tile,
1479  *  and a message state; initially, it is expected that the state will
1480  *  be set to HV_TO_BE_SENT.  nrecip specifies the number of recipients
1481  *  in the recips array.
1482  *
1483  *  For each recipient whose state is HV_TO_BE_SENT, the hypervisor attempts
1484  *  to send that tile the specified message.  In order to successfully
1485  *  receive the message, the receiver must be a valid tile to which the
1486  *  sender has access, must not be the sending tile itself, and must have
1487  *  sufficient free buffer space.  (The hypervisor guarantees that each
1488  *  tile which has called hv_register_message_state() will be able to
1489  *  buffer one message from every other tile which can legally send to it;
1490  *  more space may be provided but is not guaranteed.)  If an invalid tile
1491  *  is specified, the recipient's state is set to HV_BAD_RECIP; this is a
1492  *  permanent delivery error.  If the message is successfully delivered
1493  *  to the recipient's buffer, the recipient's state is set to HV_SENT.
1494  *  Otherwise, the recipient's state is unchanged.  Message delivery is
1495  *  synchronous; all attempts to send messages are completed before this
1496  *  routine returns.
1497  *
1498  *  If no permanent delivery errors were encountered, the routine returns
1499  *  the number of messages successfully sent: that is, the number of
1500  *  recipients whose states changed from HV_TO_BE_SENT to HV_SENT during
1501  *  this operation.  If any permanent delivery errors were encountered,
1502  *  the routine returns HV_ERECIP.  In the event of permanent delivery
1503  *  errors, it may be the case that delivery was not attempted to all
1504  *  recipients; if any messages were successfully delivered, however,
1505  *  recipients' state values will be updated appropriately.
1506  *
1507  *  It is explicitly legal to specify a recipient structure whose state
1508  *  is not HV_TO_BE_SENT; such a recipient is ignored.  One suggested way
1509  *  of using hv_send_message to send a message to multiple tiles is to set
1510  *  up a list of recipients, and then call the routine repeatedly with the
1511  *  same list, each time accumulating the number of messages successfully
1512  *  sent, until all messages are sent, a permanent error is encountered,
1513  *  or the desired number of attempts have been made.  When used in this
1514  *  way, the routine will deliver each message no more than once to each
1515  *  recipient.
1516  *
1517  *  Note that a message being successfully delivered to the recipient's
1518  *  buffer space does not guarantee that it is received by the recipient,
1519  *  either immediately or at any time in the future; the recipient might
1520  *  never call hv_receive_message, or could register a different state
1521  *  buffer, losing the message.
1522  *
1523  *  Specifying the same recipient more than once in the recipient list
1524  *  is an error, which will not result in an error return but which may
1525  *  or may not result in more than one message being delivered to the
1526  *  recipient tile.
1527  *
1528  *  buf and buflen specify the message to be sent.  buf is a virtual address
1529  *  which must be currently mapped in the client's page table; if not, the
1530  *  routine returns HV_EFAULT.  buflen must be greater than zero and less
1531  *  than or equal to HV_MAX_MESSAGE_SIZE, and nrecip must be less than the
1532  *  number of tiles to which the sender has access; if not, the routine
1533  *  returns HV_EINVAL.
1534  * @param recips List of recipients.
1535  * @param nrecip Number of recipients.
1536  * @param buf Address of message data.
1537  * @param buflen Length of message data.
1538  **/
1539 int hv_send_message(HV_Recipient *recips, int nrecip,
1540                     HV_VirtAddr buf, int buflen);
1541 
1542 /** Maximum hypervisor message size, in bytes */
1543 #define HV_MAX_MESSAGE_SIZE 28
1544 
1545 
1546 /** Return value from hv_receive_message() */
1547 typedef struct
1548 {
1549   int msglen;     /**< Message length in bytes, or an error code */
1550   __hv32 source;  /**< Code identifying message sender (HV_MSG_xxx) */
1551 } HV_RcvMsgInfo;
1552 
1553 #define HV_MSG_TILE 0x0         /**< Message source is another tile */
1554 #define HV_MSG_INTR 0x1         /**< Message source is a driver interrupt */
1555 
1556 /** Receive a message.
1557  *
1558  * This routine retrieves a message from the client's incoming message
1559  * buffer.
1560  *
1561  * Multiple messages sent from a particular sending tile to a particular
1562  * receiving tile are received in the order that they were sent; however,
1563  * no ordering is guaranteed between messages sent by different tiles.
1564  *
1565  * Whenever the a client's message buffer is empty, the first message
1566  * subsequently received will cause the client's MESSAGE_RCV_DWNCL
1567  * interrupt vector to be invoked through the interrupt downcall mechanism
1568  * (see the description of the hv_downcall_dispatch() routine for details
1569  * on downcalls).
1570  *
1571  * Another message-available downcall will not occur until a call to
1572  * this routine is made when the message buffer is empty, and a message
1573  * subsequently arrives.  Note that such a downcall could occur while
1574  * this routine is executing.  If the calling code does not wish this
1575  * to happen, it is recommended that this routine be called with the
1576  * INTCTRL_1 interrupt masked, or inside an interrupt critical section.
1577  *
1578  * msgstate is the value previously passed to hv_register_message_state().
1579  * buf is the virtual address of the buffer into which the message will
1580  * be written; buflen is the length of the buffer.
1581  *
1582  * This routine returns an HV_RcvMsgInfo structure.  The msglen member
1583  * of that structure is the length of the message received, zero if no
1584  * message is available, or HV_E2BIG if the message is too large for the
1585  * specified buffer.  If the message is too large, it is not consumed,
1586  * and may be retrieved by a subsequent call to this routine specifying
1587  * a sufficiently large buffer.  A buffer which is HV_MAX_MESSAGE_SIZE
1588  * bytes long is guaranteed to be able to receive any possible message.
1589  *
1590  * The source member of the HV_RcvMsgInfo structure describes the sender
1591  * of the message.  For messages sent by another client tile via an
1592  * hv_send_message() call, this value is HV_MSG_TILE; for messages sent
1593  * as a result of a device interrupt, this value is HV_MSG_INTR.
1594  */
1595 
1596 HV_RcvMsgInfo hv_receive_message(HV_MsgState msgstate, HV_VirtAddr buf,
1597                                  int buflen);
1598 
1599 
1600 /** Start remaining tiles owned by this supervisor.  Initially, only one tile
1601  *  executes the client program; after it calls this service, the other tiles
1602  *  are started.  This allows the initial tile to do one-time configuration
1603  *  of shared data structures without having to lock them against simultaneous
1604  *  access.
1605  */
1606 void hv_start_all_tiles(void);
1607 
1608 
1609 /** Open a hypervisor device.
1610  *
1611  *  This service initializes an I/O device and its hypervisor driver software,
1612  *  and makes it available for use.  The open operation is per-device per-chip;
1613  *  once it has been performed, the device handle returned may be used in other
1614  *  device services calls made by any tile.
1615  *
1616  * @param name Name of the device.  A base device name is just a text string
1617  *        (say, "pcie").  If there is more than one instance of a device, the
1618  *        base name is followed by a slash and a device number (say, "pcie/0").
1619  *        Some devices may support further structure beneath those components;
1620  *        most notably, devices which require control operations do so by
1621  *        supporting reads and/or writes to a control device whose name
1622  *        includes a trailing "/ctl" (say, "pcie/0/ctl").
1623  * @param flags Flags (HV_DEV_xxx).
1624  * @return A positive integer device handle, or a negative error code.
1625  */
1626 int hv_dev_open(HV_VirtAddr name, __hv32 flags);
1627 
1628 
1629 /** Close a hypervisor device.
1630  *
1631  *  This service uninitializes an I/O device and its hypervisor driver
1632  *  software, and makes it unavailable for use.  The close operation is
1633  *  per-device per-chip; once it has been performed, the device is no longer
1634  *  available.  Normally there is no need to ever call the close service.
1635  *
1636  * @param devhdl Device handle of the device to be closed.
1637  * @return Zero if the close is successful, otherwise, a negative error code.
1638  */
1639 int hv_dev_close(int devhdl);
1640 
1641 
1642 /** Read data from a hypervisor device synchronously.
1643  *
1644  *  This service transfers data from a hypervisor device to a memory buffer.
1645  *  When the service returns, the data has been written from the memory buffer,
1646  *  and the buffer will not be further modified by the driver.
1647  *
1648  *  No ordering is guaranteed between requests issued from different tiles.
1649  *
1650  *  Devices may choose to support both the synchronous and asynchronous read
1651  *  operations, only one of them, or neither of them.
1652  *
1653  * @param devhdl Device handle of the device to be read from.
1654  * @param flags Flags (HV_DEV_xxx).
1655  * @param va Virtual address of the target data buffer.  This buffer must
1656  *        be mapped in the currently installed page table; if not, HV_EFAULT
1657  *        may be returned.
1658  * @param len Number of bytes to be transferred.
1659  * @param offset Driver-dependent offset.  For a random-access device, this is
1660  *        often a byte offset from the beginning of the device; in other cases,
1661  *        like on a control device, it may have a different meaning.
1662  * @return A non-negative value if the read was at least partially successful;
1663  *         otherwise, a negative error code.  The precise interpretation of
1664  *         the return value is driver-dependent, but many drivers will return
1665  *         the number of bytes successfully transferred.
1666  */
1667 int hv_dev_pread(int devhdl, __hv32 flags, HV_VirtAddr va, __hv32 len,
1668                  __hv64 offset);
1669 
1670 #define HV_DEV_NB_EMPTY     0x1   /**< Don't block when no bytes of data can
1671                                        be transferred. */
1672 #define HV_DEV_NB_PARTIAL   0x2   /**< Don't block when some bytes, but not all
1673                                        of the requested bytes, can be
1674                                        transferred. */
1675 #define HV_DEV_NOCACHE      0x4   /**< The caller warrants that none of the
1676                                        cache lines which might contain data
1677                                        from the requested buffer are valid.
1678                                        Useful with asynchronous operations
1679                                        only. */
1680 
1681 #define HV_DEV_ALLFLAGS     (HV_DEV_NB_EMPTY | HV_DEV_NB_PARTIAL | \
1682                              HV_DEV_NOCACHE)   /**< All HV_DEV_xxx flags */
1683 
1684 /** Write data to a hypervisor device synchronously.
1685  *
1686  *  This service transfers data from a memory buffer to a hypervisor device.
1687  *  When the service returns, the data has been read from the memory buffer,
1688  *  and the buffer may be overwritten by the client; the data may not
1689  *  necessarily have been conveyed to the actual hardware I/O interface.
1690  *
1691  *  No ordering is guaranteed between requests issued from different tiles.
1692  *
1693  *  Devices may choose to support both the synchronous and asynchronous write
1694  *  operations, only one of them, or neither of them.
1695  *
1696  * @param devhdl Device handle of the device to be written to.
1697  * @param flags Flags (HV_DEV_xxx).
1698  * @param va Virtual address of the source data buffer.  This buffer must
1699  *        be mapped in the currently installed page table; if not, HV_EFAULT
1700  *        may be returned.
1701  * @param len Number of bytes to be transferred.
1702  * @param offset Driver-dependent offset.  For a random-access device, this is
1703  *        often a byte offset from the beginning of the device; in other cases,
1704  *        like on a control device, it may have a different meaning.
1705  * @return A non-negative value if the write was at least partially successful;
1706  *         otherwise, a negative error code.  The precise interpretation of
1707  *         the return value is driver-dependent, but many drivers will return
1708  *         the number of bytes successfully transferred.
1709  */
1710 int hv_dev_pwrite(int devhdl, __hv32 flags, HV_VirtAddr va, __hv32 len,
1711                   __hv64 offset);
1712 
1713 
1714 /** Interrupt arguments, used in the asynchronous I/O interfaces. */
1715 #if CHIP_VA_WIDTH() > 32
1716 typedef __hv64 HV_IntArg;
1717 #else
1718 typedef __hv32 HV_IntArg;
1719 #endif
1720 
1721 /** Interrupt messages are delivered via the mechanism as normal messages,
1722  *  but have a message source of HV_DEV_INTR.  The message is formatted
1723  *  as an HV_IntrMsg structure.
1724  */
1725 
1726 typedef struct
1727 {
1728   HV_IntArg intarg;  /**< Interrupt argument, passed to the poll/preada/pwritea
1729                           services */
1730   HV_IntArg intdata; /**< Interrupt-specific interrupt data */
1731 } HV_IntrMsg;
1732 
1733 /** Request an interrupt message when a device condition is satisfied.
1734  *
1735  *  This service requests that an interrupt message be delivered to the
1736  *  requesting tile when a device becomes readable or writable, or when any
1737  *  data queued to the device via previous write operations from this tile
1738  *  has been actually sent out on the hardware I/O interface.  Devices may
1739  *  choose to support any, all, or none of the available conditions.
1740  *
1741  *  If multiple conditions are specified, only one message will be
1742  *  delivered.  If the event mask delivered to that interrupt handler
1743  *  indicates that some of the conditions have not yet occurred, the
1744  *  client must issue another poll() call if it wishes to wait for those
1745  *  conditions.
1746  *
1747  *  Only one poll may be outstanding per device handle per tile.  If more than
1748  *  one tile is polling on the same device and condition, they will all be
1749  *  notified when it happens.  Because of this, clients may not assume that
1750  *  the condition signaled is necessarily still true when they request a
1751  *  subsequent service; for instance, the readable data which caused the
1752  *  poll call to interrupt may have been read by another tile in the interim.
1753  *
1754  *  The notification interrupt message could come directly, or via the
1755  *  downcall (intctrl1) method, depending on what the tile is doing
1756  *  when the condition is satisfied.  Note that it is possible for the
1757  *  requested interrupt to be delivered after this service is called but
1758  *  before it returns.
1759  *
1760  * @param devhdl Device handle of the device to be polled.
1761  * @param events Flags denoting the events which will cause the interrupt to
1762  *        be delivered (HV_DEVPOLL_xxx).
1763  * @param intarg Value which will be delivered as the intarg member of the
1764  *        eventual interrupt message; the intdata member will be set to a
1765  *        mask of HV_DEVPOLL_xxx values indicating which conditions have been
1766  *        satisifed.
1767  * @return Zero if the interrupt was successfully scheduled; otherwise, a
1768  *         negative error code.
1769  */
1770 int hv_dev_poll(int devhdl, __hv32 events, HV_IntArg intarg);
1771 
1772 #define HV_DEVPOLL_READ     0x1   /**< Test device for readability */
1773 #define HV_DEVPOLL_WRITE    0x2   /**< Test device for writability */
1774 #define HV_DEVPOLL_FLUSH    0x4   /**< Test device for output drained */
1775 
1776 
1777 /** Cancel a request for an interrupt when a device event occurs.
1778  *
1779  *  This service requests that no interrupt be delivered when the events
1780  *  noted in the last-issued poll() call happen.  Once this service returns,
1781  *  the interrupt has been canceled; however, it is possible for the interrupt
1782  *  to be delivered after this service is called but before it returns.
1783  *
1784  * @param devhdl Device handle of the device on which to cancel polling.
1785  * @return Zero if the poll was successfully canceled; otherwise, a negative
1786  *         error code.
1787  */
1788 int hv_dev_poll_cancel(int devhdl);
1789 
1790 
1791 /** NMI information */
1792 typedef struct
1793 {
1794   /** Result: negative error, or HV_NMI_RESULT_xxx. */
1795   int result;
1796 
1797   /** PC from interrupted remote core (if result != HV_NMI_RESULT_FAIL_HV). */
1798   HV_VirtAddr pc;
1799 
1800 } HV_NMI_Info;
1801 
1802 /** NMI issued successfully. */
1803 #define HV_NMI_RESULT_OK        0
1804 
1805 /** NMI not issued: remote tile running at client PL with ICS set. */
1806 #define HV_NMI_RESULT_FAIL_ICS  1
1807 
1808 /** NMI not issued: remote tile waiting in hypervisor. */
1809 #define HV_NMI_RESULT_FAIL_HV   2
1810 
1811 /** Force an NMI downcall regardless of the ICS bit of the client. */
1812 #define HV_NMI_FLAG_FORCE    0x1
1813 
1814 /** Send an NMI interrupt request to a particular tile.
1815  *
1816  *  This will cause the NMI to be issued on the remote tile regardless
1817  *  of the state of the client interrupt mask.  However, if the remote
1818  *  tile is in the hypervisor, it will not execute the NMI, and
1819  *  HV_NMI_RESULT_FAIL_HV will be returned.  Similarly, if the remote
1820  *  tile is in a client interrupt critical section at the time of the
1821  *  NMI, it will not execute the NMI, and HV_NMI_RESULT_FAIL_ICS will
1822  *  be returned.  In this second case, however, if HV_NMI_FLAG_FORCE
1823  *  is set in flags, then the remote tile will enter its NMI interrupt
1824  *  vector regardless.  Forcing the NMI vector during an interrupt
1825  *  critical section will mean that the client can not safely continue
1826  *  execution after handling the interrupt.
1827  *
1828  *  @param tile Tile to which the NMI request is sent.
1829  *  @param info NMI information which is defined by and interpreted by the
1830  *         supervisor, is passed to the specified tile, and is
1831  *         stored in the SPR register SYSTEM_SAVE_{CLIENT_PL}_2 on the
1832  *         specified tile when entering the NMI handler routine.
1833  *         Typically, this parameter stores the NMI type, or an aligned
1834  *         VA plus some special bits, etc.
1835  *  @param flags Flags (HV_NMI_FLAG_xxx).
1836  *  @return Information about the requested NMI.
1837  */
1838 HV_NMI_Info hv_send_nmi(HV_Coord tile, unsigned long info, __hv64 flags);
1839 
1840 
1841 /** Scatter-gather list for preada/pwritea calls. */
1842 typedef struct
1843 #if CHIP_VA_WIDTH() <= 32
1844 __attribute__ ((packed, aligned(4)))
1845 #endif
1846 {
1847   HV_PhysAddr pa;  /**< Client physical address of the buffer segment. */
1848   HV_PTE pte;      /**< Page table entry describing the caching and location
1849                         override characteristics of the buffer segment.  Some
1850                         drivers ignore this element and will require that
1851                         the NOCACHE flag be set on their requests. */
1852   __hv32 len;      /**< Length of the buffer segment. */
1853 } HV_SGL;
1854 
1855 #define HV_SGL_MAXLEN 16  /**< Maximum number of entries in a scatter-gather
1856                                list */
1857 
1858 /** Read data from a hypervisor device asynchronously.
1859  *
1860  *  This service transfers data from a hypervisor device to a memory buffer.
1861  *  When the service returns, the read has been scheduled.  When the read
1862  *  completes, an interrupt message will be delivered, and the buffer will
1863  *  not be further modified by the driver.
1864  *
1865  *  The number of possible outstanding asynchronous requests is defined by
1866  *  each driver, but it is recommended that it be at least two requests
1867  *  per tile per device.
1868  *
1869  *  No ordering is guaranteed between synchronous and asynchronous requests,
1870  *  even those issued on the same tile.
1871  *
1872  *  The completion interrupt message could come directly, or via the downcall
1873  *  (intctrl1) method, depending on what the tile is doing when the read
1874  *  completes.  Interrupts do not coalesce; one is delivered for each
1875  *  asynchronous I/O request.  Note that it is possible for the requested
1876  *  interrupt to be delivered after this service is called but before it
1877  *  returns.
1878  *
1879  *  Devices may choose to support both the synchronous and asynchronous read
1880  *  operations, only one of them, or neither of them.
1881  *
1882  * @param devhdl Device handle of the device to be read from.
1883  * @param flags Flags (HV_DEV_xxx).
1884  * @param sgl_len Number of elements in the scatter-gather list.
1885  * @param sgl Scatter-gather list describing the memory to which data will be
1886  *        written.
1887  * @param offset Driver-dependent offset.  For a random-access device, this is
1888  *        often a byte offset from the beginning of the device; in other cases,
1889  *        like on a control device, it may have a different meaning.
1890  * @param intarg Value which will be delivered as the intarg member of the
1891  *        eventual interrupt message; the intdata member will be set to the
1892  *        normal return value from the read request.
1893  * @return Zero if the read was successfully scheduled; otherwise, a negative
1894  *         error code.  Note that some drivers may choose to pre-validate
1895  *         their arguments, and may thus detect certain device error
1896  *         conditions at this time rather than when the completion notification
1897  *         occurs, but this is not required.
1898  */
1899 int hv_dev_preada(int devhdl, __hv32 flags, __hv32 sgl_len,
1900                   HV_SGL sgl[/* sgl_len */], __hv64 offset, HV_IntArg intarg);
1901 
1902 
1903 /** Write data to a hypervisor device asynchronously.
1904  *
1905  *  This service transfers data from a memory buffer to a hypervisor
1906  *  device.  When the service returns, the write has been scheduled.
1907  *  When the write completes, an interrupt message will be delivered,
1908  *  and the buffer may be overwritten by the client; the data may not
1909  *  necessarily have been conveyed to the actual hardware I/O interface.
1910  *
1911  *  The number of possible outstanding asynchronous requests is defined by
1912  *  each driver, but it is recommended that it be at least two requests
1913  *  per tile per device.
1914  *
1915  *  No ordering is guaranteed between synchronous and asynchronous requests,
1916  *  even those issued on the same tile.
1917  *
1918  *  The completion interrupt message could come directly, or via the downcall
1919  *  (intctrl1) method, depending on what the tile is doing when the read
1920  *  completes.  Interrupts do not coalesce; one is delivered for each
1921  *  asynchronous I/O request.  Note that it is possible for the requested
1922  *  interrupt to be delivered after this service is called but before it
1923  *  returns.
1924  *
1925  *  Devices may choose to support both the synchronous and asynchronous write
1926  *  operations, only one of them, or neither of them.
1927  *
1928  * @param devhdl Device handle of the device to be read from.
1929  * @param flags Flags (HV_DEV_xxx).
1930  * @param sgl_len Number of elements in the scatter-gather list.
1931  * @param sgl Scatter-gather list describing the memory from which data will be
1932  *        read.
1933  * @param offset Driver-dependent offset.  For a random-access device, this is
1934  *        often a byte offset from the beginning of the device; in other cases,
1935  *        like on a control device, it may have a different meaning.
1936  * @param intarg Value which will be delivered as the intarg member of the
1937  *        eventual interrupt message; the intdata member will be set to the
1938  *        normal return value from the write request.
1939  * @return Zero if the write was successfully scheduled; otherwise, a negative
1940  *         error code.  Note that some drivers may choose to pre-validate
1941  *         their arguments, and may thus detect certain device error
1942  *         conditions at this time rather than when the completion notification
1943  *         occurs, but this is not required.
1944  */
1945 int hv_dev_pwritea(int devhdl, __hv32 flags, __hv32 sgl_len,
1946                    HV_SGL sgl[/* sgl_len */], __hv64 offset, HV_IntArg intarg);
1947 
1948 
1949 /** Define a pair of tile and ASID to identify a user process context. */
1950 typedef struct
1951 {
1952   /** X coordinate, relative to supervisor's top-left coordinate */
1953   unsigned int x:11;
1954 
1955   /** Y coordinate, relative to supervisor's top-left coordinate */
1956   unsigned int y:11;
1957 
1958   /** ASID of the process on this x,y tile */
1959   HV_ASID asid:10;
1960 } HV_Remote_ASID;
1961 
1962 /** Flush cache and/or TLB state on remote tiles.
1963  *
1964  * @param cache_pa Client physical address to flush from cache (ignored if
1965  *        the length encoded in cache_control is zero, or if
1966  *        HV_FLUSH_EVICT_L2 is set, or if cache_cpumask is NULL).
1967  * @param cache_control This argument allows you to specify a length of
1968  *        physical address space to flush (maximum HV_FLUSH_MAX_CACHE_LEN).
1969  *        You can "or" in HV_FLUSH_EVICT_L2 to flush the whole L2 cache.
1970  *        You can "or" in HV_FLUSH_EVICT_L1I to flush the whole L1I cache.
1971  *        HV_FLUSH_ALL flushes all caches.
1972  * @param cache_cpumask Bitmask (in row-major order, supervisor-relative) of
1973  *        tile indices to perform cache flush on.  The low bit of the first
1974  *        word corresponds to the tile at the upper left-hand corner of the
1975  *        supervisor's rectangle.  If passed as a NULL pointer, equivalent
1976  *        to an empty bitmask.  On chips which support hash-for-home caching,
1977  *        if passed as -1, equivalent to a mask containing tiles which could
1978  *        be doing hash-for-home caching.
1979  * @param tlb_va Virtual address to flush from TLB (ignored if
1980  *        tlb_length is zero or tlb_cpumask is NULL).
1981  * @param tlb_length Number of bytes of data to flush from the TLB.
1982  * @param tlb_pgsize Page size to use for TLB flushes.
1983  *        tlb_va and tlb_length need not be aligned to this size.
1984  * @param tlb_cpumask Bitmask for tlb flush, like cache_cpumask.
1985  *        If passed as a NULL pointer, equivalent to an empty bitmask.
1986  * @param asids Pointer to an HV_Remote_ASID array of tile/ASID pairs to flush.
1987  * @param asidcount Number of HV_Remote_ASID entries in asids[].
1988  * @return Zero for success, or else HV_EINVAL or HV_EFAULT for errors that
1989  *        are detected while parsing the arguments.
1990  */
1991 int hv_flush_remote(HV_PhysAddr cache_pa, unsigned long cache_control,
1992                     unsigned long* cache_cpumask,
1993                     HV_VirtAddr tlb_va, unsigned long tlb_length,
1994                     unsigned long tlb_pgsize, unsigned long* tlb_cpumask,
1995                     HV_Remote_ASID* asids, int asidcount);
1996 
1997 /** Include in cache_control to ensure a flush of the entire L2. */
1998 #define HV_FLUSH_EVICT_L2 (1UL << 31)
1999 
2000 /** Include in cache_control to ensure a flush of the entire L1I. */
2001 #define HV_FLUSH_EVICT_L1I (1UL << 30)
2002 
2003 /** Maximum legal size to use for the "length" component of cache_control. */
2004 #define HV_FLUSH_MAX_CACHE_LEN ((1UL << 30) - 1)
2005 
2006 /** Use for cache_control to ensure a flush of all caches. */
2007 #define HV_FLUSH_ALL -1UL
2008 
2009 #else   /* __ASSEMBLER__ */
2010 
2011 /** Include in cache_control to ensure a flush of the entire L2. */
2012 #define HV_FLUSH_EVICT_L2 (1 << 31)
2013 
2014 /** Include in cache_control to ensure a flush of the entire L1I. */
2015 #define HV_FLUSH_EVICT_L1I (1 << 30)
2016 
2017 /** Maximum legal size to use for the "length" component of cache_control. */
2018 #define HV_FLUSH_MAX_CACHE_LEN ((1 << 30) - 1)
2019 
2020 /** Use for cache_control to ensure a flush of all caches. */
2021 #define HV_FLUSH_ALL -1
2022 
2023 #endif  /* __ASSEMBLER__ */
2024 
2025 #ifndef __ASSEMBLER__
2026 
2027 /** Return a 64-bit value corresponding to the PTE if needed */
2028 #define hv_pte_val(pte) ((pte).val)
2029 
2030 /** Cast a 64-bit value to an HV_PTE */
2031 #define hv_pte(val) ((HV_PTE) { val })
2032 
2033 #endif  /* !__ASSEMBLER__ */
2034 
2035 
2036 /** Bits in the size of an HV_PTE */
2037 #define HV_LOG2_PTE_SIZE 3
2038 
2039 /** Size of an HV_PTE */
2040 #define HV_PTE_SIZE (1 << HV_LOG2_PTE_SIZE)
2041 
2042 
2043 /* Bits in HV_PTE's low word. */
2044 #define HV_PTE_INDEX_PRESENT          0  /**< PTE is valid */
2045 #define HV_PTE_INDEX_MIGRATING        1  /**< Page is migrating */
2046 #define HV_PTE_INDEX_CLIENT0          2  /**< Page client state 0 */
2047 #define HV_PTE_INDEX_CLIENT1          3  /**< Page client state 1 */
2048 #define HV_PTE_INDEX_NC               4  /**< L1$/L2$ incoherent with L3$ */
2049 #define HV_PTE_INDEX_NO_ALLOC_L1      5  /**< Page is uncached in local L1$ */
2050 #define HV_PTE_INDEX_NO_ALLOC_L2      6  /**< Page is uncached in local L2$ */
2051 #define HV_PTE_INDEX_CACHED_PRIORITY  7  /**< Page is priority cached */
2052 #define HV_PTE_INDEX_PAGE             8  /**< PTE describes a page */
2053 #define HV_PTE_INDEX_GLOBAL           9  /**< Page is global */
2054 #define HV_PTE_INDEX_USER            10  /**< Page is user-accessible */
2055 #define HV_PTE_INDEX_ACCESSED        11  /**< Page has been accessed */
2056 #define HV_PTE_INDEX_DIRTY           12  /**< Page has been written */
2057                                          /*   Bits 13-14 are reserved for
2058                                               future use. */
2059 #define HV_PTE_INDEX_SUPER           15  /**< Pages ganged together for TLB */
2060 #define HV_PTE_INDEX_MODE            16  /**< Page mode; see HV_PTE_MODE_xxx */
2061 #define HV_PTE_MODE_BITS              3  /**< Number of bits in mode */
2062 #define HV_PTE_INDEX_CLIENT2         19  /**< Page client state 2 */
2063 #define HV_PTE_INDEX_LOTAR           20  /**< Page's LOTAR; must be high bits
2064                                               of word */
2065 #define HV_PTE_LOTAR_BITS            12  /**< Number of bits in a LOTAR */
2066 
2067 /* Bits in HV_PTE's high word. */
2068 #define HV_PTE_INDEX_READABLE        32  /**< Page is readable */
2069 #define HV_PTE_INDEX_WRITABLE        33  /**< Page is writable */
2070 #define HV_PTE_INDEX_EXECUTABLE      34  /**< Page is executable */
2071 #define HV_PTE_INDEX_PTFN            35  /**< Page's PTFN; must be high bits
2072                                               of word */
2073 #define HV_PTE_PTFN_BITS             29  /**< Number of bits in a PTFN */
2074 
2075 /*
2076  * Legal values for the PTE's mode field
2077  */
2078 /** Data is not resident in any caches; loads and stores access memory
2079  *  directly.
2080  */
2081 #define HV_PTE_MODE_UNCACHED          1
2082 
2083 /** Data is resident in the tile's local L1 and/or L2 caches; if a load
2084  *  or store misses there, it goes to memory.
2085  *
2086  *  The copy in the local L1$/L2$ is not invalidated when the copy in
2087  *  memory is changed.
2088  */
2089 #define HV_PTE_MODE_CACHE_NO_L3       2
2090 
2091 /** Data is resident in the tile's local L1 and/or L2 caches.  If a load
2092  *  or store misses there, it goes to an L3 cache in a designated tile;
2093  *  if it misses there, it goes to memory.
2094  *
2095  *  If the NC bit is not set, the copy in the local L1$/L2$ is invalidated
2096  *  when the copy in the remote L3$ is changed.  Otherwise, such
2097  *  invalidation will not occur.
2098  *
2099  *  Chips for which CHIP_HAS_COHERENT_LOCAL_CACHE() is 0 do not support
2100  *  invalidation from an L3$ to another tile's L1$/L2$.  If the NC bit is
2101  *  clear on such a chip, no copy is kept in the local L1$/L2$ in this mode.
2102  */
2103 #define HV_PTE_MODE_CACHE_TILE_L3     3
2104 
2105 /** Data is resident in the tile's local L1 and/or L2 caches.  If a load
2106  *  or store misses there, it goes to an L3 cache in one of a set of
2107  *  designated tiles; if it misses there, it goes to memory.  Which tile
2108  *  is chosen from the set depends upon a hash function applied to the
2109  *  physical address.  This mode is not supported on chips for which
2110  *  CHIP_HAS_CBOX_HOME_MAP() is 0.
2111  *
2112  *  If the NC bit is not set, the copy in the local L1$/L2$ is invalidated
2113  *  when the copy in the remote L3$ is changed.  Otherwise, such
2114  *  invalidation will not occur.
2115  *
2116  *  Chips for which CHIP_HAS_COHERENT_LOCAL_CACHE() is 0 do not support
2117  *  invalidation from an L3$ to another tile's L1$/L2$.  If the NC bit is
2118  *  clear on such a chip, no copy is kept in the local L1$/L2$ in this mode.
2119  */
2120 #define HV_PTE_MODE_CACHE_HASH_L3     4
2121 
2122 /** Data is not resident in memory; accesses are instead made to an I/O
2123  *  device, whose tile coordinates are given by the PTE's LOTAR field.
2124  *  This mode is only supported on chips for which CHIP_HAS_MMIO() is 1.
2125  *  The EXECUTABLE bit may not be set in an MMIO PTE.
2126  */
2127 #define HV_PTE_MODE_MMIO              5
2128 
2129 
2130 /* C wants 1ULL so it is typed as __hv64, but the assembler needs just numbers.
2131  * The assembler can't handle shifts greater than 31, but treats them
2132  * as shifts mod 32, so assembler code must be aware of which word
2133  * the bit belongs in when using these macros.
2134  */
2135 #ifdef __ASSEMBLER__
2136 #define __HV_PTE_ONE 1        /**< One, for assembler */
2137 #else
2138 #define __HV_PTE_ONE 1ULL     /**< One, for C */
2139 #endif
2140 
2141 /** Is this PTE present?
2142  *
2143  * If this bit is set, this PTE represents a valid translation or level-2
2144  * page table pointer.  Otherwise, the page table does not contain a
2145  * translation for the subject virtual pages.
2146  *
2147  * If this bit is not set, the other bits in the PTE are not
2148  * interpreted by the hypervisor, and may contain any value.
2149  */
2150 #define HV_PTE_PRESENT               (__HV_PTE_ONE << HV_PTE_INDEX_PRESENT)
2151 
2152 /** Does this PTE map a page?
2153  *
2154  * If this bit is set in a level-0 page table, the entry should be
2155  * interpreted as a level-2 page table entry mapping a jumbo page.
2156  *
2157  * If this bit is set in a level-1 page table, the entry should be
2158  * interpreted as a level-2 page table entry mapping a large page.
2159  *
2160  * This bit should not be modified by the client while PRESENT is set, as
2161  * doing so may race with the hypervisor's update of ACCESSED and DIRTY bits.
2162  *
2163  * In a level-2 page table, this bit is ignored and must be zero.
2164  */
2165 #define HV_PTE_PAGE                  (__HV_PTE_ONE << HV_PTE_INDEX_PAGE)
2166 
2167 /** Does this PTE implicitly reference multiple pages?
2168  *
2169  * If this bit is set in the page table (either in the level-2 page table,
2170  * or in a higher level page table in conjunction with the PAGE bit)
2171  * then the PTE specifies a range of contiguous pages, not a single page.
2172  * The hv_set_pte_super_shift() allows you to specify the count for
2173  * each level of the page table.
2174  *
2175  * Note: this bit is not supported on TILEPro systems.
2176  */
2177 #define HV_PTE_SUPER                 (__HV_PTE_ONE << HV_PTE_INDEX_SUPER)
2178 
2179 /** Is this a global (non-ASID) mapping?
2180  *
2181  * If this bit is set, the translations established by this PTE will
2182  * not be flushed from the TLB by the hv_flush_asid() service; they
2183  * will be flushed by the hv_flush_page() or hv_flush_pages() services.
2184  *
2185  * Setting this bit for translations which are identical in all page
2186  * tables (for instance, code and data belonging to a client OS) can
2187  * be very beneficial, as it will reduce the number of TLB misses.
2188  * Note that, while it is not an error which will be detected by the
2189  * hypervisor, it is an extremely bad idea to set this bit for
2190  * translations which are _not_ identical in all page tables.
2191  *
2192  * This bit should not be modified by the client while PRESENT is set, as
2193  * doing so may race with the hypervisor's update of ACCESSED and DIRTY bits.
2194  *
2195  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2196  */
2197 #define HV_PTE_GLOBAL                (__HV_PTE_ONE << HV_PTE_INDEX_GLOBAL)
2198 
2199 /** Is this mapping accessible to users?
2200  *
2201  * If this bit is set, code running at any PL will be permitted to
2202  * access the virtual addresses mapped by this PTE.  Otherwise, only
2203  * code running at PL 1 or above will be allowed to do so.
2204  *
2205  * This bit should not be modified by the client while PRESENT is set, as
2206  * doing so may race with the hypervisor's update of ACCESSED and DIRTY bits.
2207  *
2208  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2209  */
2210 #define HV_PTE_USER                  (__HV_PTE_ONE << HV_PTE_INDEX_USER)
2211 
2212 /** Has this mapping been accessed?
2213  *
2214  * This bit is set by the hypervisor when the memory described by the
2215  * translation is accessed for the first time.  It is never cleared by
2216  * the hypervisor, but may be cleared by the client.  After the bit
2217  * has been cleared, subsequent references are not guaranteed to set
2218  * it again until the translation has been flushed from the TLB.
2219  *
2220  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2221  */
2222 #define HV_PTE_ACCESSED              (__HV_PTE_ONE << HV_PTE_INDEX_ACCESSED)
2223 
2224 /** Is this mapping dirty?
2225  *
2226  * This bit is set by the hypervisor when the memory described by the
2227  * translation is written for the first time.  It is never cleared by
2228  * the hypervisor, but may be cleared by the client.  After the bit
2229  * has been cleared, subsequent references are not guaranteed to set
2230  * it again until the translation has been flushed from the TLB.
2231  *
2232  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2233  */
2234 #define HV_PTE_DIRTY                 (__HV_PTE_ONE << HV_PTE_INDEX_DIRTY)
2235 
2236 /** Migrating bit in PTE.
2237  *
2238  * This bit is guaranteed not to be inspected or modified by the
2239  * hypervisor.  The name is indicative of the suggested use by the client
2240  * to tag pages whose L3 cache is being migrated from one cpu to another.
2241  */
2242 #define HV_PTE_MIGRATING             (__HV_PTE_ONE << HV_PTE_INDEX_MIGRATING)
2243 
2244 /** Client-private bit in PTE.
2245  *
2246  * This bit is guaranteed not to be inspected or modified by the
2247  * hypervisor.
2248  */
2249 #define HV_PTE_CLIENT0               (__HV_PTE_ONE << HV_PTE_INDEX_CLIENT0)
2250 
2251 /** Client-private bit in PTE.
2252  *
2253  * This bit is guaranteed not to be inspected or modified by the
2254  * hypervisor.
2255  */
2256 #define HV_PTE_CLIENT1               (__HV_PTE_ONE << HV_PTE_INDEX_CLIENT1)
2257 
2258 /** Client-private bit in PTE.
2259  *
2260  * This bit is guaranteed not to be inspected or modified by the
2261  * hypervisor.
2262  */
2263 #define HV_PTE_CLIENT2               (__HV_PTE_ONE << HV_PTE_INDEX_CLIENT2)
2264 
2265 /** Non-coherent (NC) bit in PTE.
2266  *
2267  * If this bit is set, the mapping that is set up will be non-coherent
2268  * (also known as non-inclusive).  This means that changes to the L3
2269  * cache will not cause a local copy to be invalidated.  It is generally
2270  * recommended only for read-only mappings.
2271  *
2272  * In level-1 PTEs, if the Page bit is clear, this bit determines how the
2273  * level-2 page table is accessed.
2274  */
2275 #define HV_PTE_NC                    (__HV_PTE_ONE << HV_PTE_INDEX_NC)
2276 
2277 /** Is this page prevented from filling the L1$?
2278  *
2279  * If this bit is set, the page described by the PTE will not be cached
2280  * the local cpu's L1 cache.
2281  *
2282  * If CHIP_HAS_NC_AND_NOALLOC_BITS() is not true in <chip.h> for this chip,
2283  * it is illegal to use this attribute, and may cause client termination.
2284  *
2285  * In level-1 PTEs, if the Page bit is clear, this bit
2286  * determines how the level-2 page table is accessed.
2287  */
2288 #define HV_PTE_NO_ALLOC_L1           (__HV_PTE_ONE << HV_PTE_INDEX_NO_ALLOC_L1)
2289 
2290 /** Is this page prevented from filling the L2$?
2291  *
2292  * If this bit is set, the page described by the PTE will not be cached
2293  * the local cpu's L2 cache.
2294  *
2295  * If CHIP_HAS_NC_AND_NOALLOC_BITS() is not true in <chip.h> for this chip,
2296  * it is illegal to use this attribute, and may cause client termination.
2297  *
2298  * In level-1 PTEs, if the Page bit is clear, this bit determines how the
2299  * level-2 page table is accessed.
2300  */
2301 #define HV_PTE_NO_ALLOC_L2           (__HV_PTE_ONE << HV_PTE_INDEX_NO_ALLOC_L2)
2302 
2303 /** Is this a priority page?
2304  *
2305  * If this bit is set, the page described by the PTE will be given
2306  * priority in the cache.  Normally this translates into allowing the
2307  * page to use only the "red" half of the cache.  The client may wish to
2308  * then use the hv_set_caching service to specify that other pages which
2309  * alias this page will use only the "black" half of the cache.
2310  *
2311  * If the Cached Priority bit is clear, the hypervisor uses the
2312  * current hv_set_caching() value to choose how to cache the page.
2313  *
2314  * It is illegal to set the Cached Priority bit if the Non-Cached bit
2315  * is set and the Cached Remotely bit is clear, i.e. if requests to
2316  * the page map directly to memory.
2317  *
2318  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2319  */
2320 #define HV_PTE_CACHED_PRIORITY       (__HV_PTE_ONE << \
2321                                       HV_PTE_INDEX_CACHED_PRIORITY)
2322 
2323 /** Is this a readable mapping?
2324  *
2325  * If this bit is set, code will be permitted to read from (e.g.,
2326  * issue load instructions against) the virtual addresses mapped by
2327  * this PTE.
2328  *
2329  * It is illegal for this bit to be clear if the Writable bit is set.
2330  *
2331  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2332  */
2333 #define HV_PTE_READABLE              (__HV_PTE_ONE << HV_PTE_INDEX_READABLE)
2334 
2335 /** Is this a writable mapping?
2336  *
2337  * If this bit is set, code will be permitted to write to (e.g., issue
2338  * store instructions against) the virtual addresses mapped by this
2339  * PTE.
2340  *
2341  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2342  */
2343 #define HV_PTE_WRITABLE              (__HV_PTE_ONE << HV_PTE_INDEX_WRITABLE)
2344 
2345 /** Is this an executable mapping?
2346  *
2347  * If this bit is set, code will be permitted to execute from
2348  * (e.g., jump to) the virtual addresses mapped by this PTE.
2349  *
2350  * This bit applies to any processor on the tile, if there are more
2351  * than one.
2352  *
2353  * This bit is ignored in level-1 PTEs unless the Page bit is set.
2354  */
2355 #define HV_PTE_EXECUTABLE            (__HV_PTE_ONE << HV_PTE_INDEX_EXECUTABLE)
2356 
2357 /** The width of a LOTAR's x or y bitfield. */
2358 #define HV_LOTAR_WIDTH 11
2359 
2360 /** Converts an x,y pair to a LOTAR value. */
2361 #define HV_XY_TO_LOTAR(x, y) ((HV_LOTAR)(((x) << HV_LOTAR_WIDTH) | (y)))
2362 
2363 /** Extracts the X component of a lotar. */
2364 #define HV_LOTAR_X(lotar) ((lotar) >> HV_LOTAR_WIDTH)
2365 
2366 /** Extracts the Y component of a lotar. */
2367 #define HV_LOTAR_Y(lotar) ((lotar) & ((1 << HV_LOTAR_WIDTH) - 1))
2368 
2369 #ifndef __ASSEMBLER__
2370 
2371 /** Define accessor functions for a PTE bit. */
2372 #define _HV_BIT(name, bit)                                      \
2373 static __inline int                                             \
2374 hv_pte_get_##name(HV_PTE pte)                                   \
2375 {                                                               \
2376   return (pte.val >> HV_PTE_INDEX_##bit) & 1;                   \
2377 }                                                               \
2378                                                                 \
2379 static __inline HV_PTE                                          \
2380 hv_pte_set_##name(HV_PTE pte)                                   \
2381 {                                                               \
2382   pte.val |= 1ULL << HV_PTE_INDEX_##bit;                        \
2383   return pte;                                                   \
2384 }                                                               \
2385                                                                 \
2386 static __inline HV_PTE                                          \
2387 hv_pte_clear_##name(HV_PTE pte)                                 \
2388 {                                                               \
2389   pte.val &= ~(1ULL << HV_PTE_INDEX_##bit);                     \
2390   return pte;                                                   \
2391 }
2392 
2393 /* Generate accessors to get, set, and clear various PTE flags.
2394  */
_HV_BIT(present,PRESENT)2395 _HV_BIT(present,         PRESENT)
2396 _HV_BIT(page,            PAGE)
2397 _HV_BIT(super,           SUPER)
2398 _HV_BIT(client0,         CLIENT0)
2399 _HV_BIT(client1,         CLIENT1)
2400 _HV_BIT(client2,         CLIENT2)
2401 _HV_BIT(migrating,       MIGRATING)
2402 _HV_BIT(nc,              NC)
2403 _HV_BIT(readable,        READABLE)
2404 _HV_BIT(writable,        WRITABLE)
2405 _HV_BIT(executable,      EXECUTABLE)
2406 _HV_BIT(accessed,        ACCESSED)
2407 _HV_BIT(dirty,           DIRTY)
2408 _HV_BIT(no_alloc_l1,     NO_ALLOC_L1)
2409 _HV_BIT(no_alloc_l2,     NO_ALLOC_L2)
2410 _HV_BIT(cached_priority, CACHED_PRIORITY)
2411 _HV_BIT(global,          GLOBAL)
2412 _HV_BIT(user,            USER)
2413 
2414 #undef _HV_BIT
2415 
2416 /** Get the page mode from the PTE.
2417  *
2418  * This field generally determines whether and how accesses to the page
2419  * are cached; the HV_PTE_MODE_xxx symbols define the legal values for the
2420  * page mode.  The NC, NO_ALLOC_L1, and NO_ALLOC_L2 bits modify this
2421  * general policy.
2422  */
2423 static __inline unsigned int
2424 hv_pte_get_mode(const HV_PTE pte)
2425 {
2426   return (((__hv32) pte.val) >> HV_PTE_INDEX_MODE) &
2427          ((1 << HV_PTE_MODE_BITS) - 1);
2428 }
2429 
2430 /** Set the page mode into a PTE.  See hv_pte_get_mode. */
2431 static __inline HV_PTE
hv_pte_set_mode(HV_PTE pte,unsigned int val)2432 hv_pte_set_mode(HV_PTE pte, unsigned int val)
2433 {
2434   pte.val &= ~(((1ULL << HV_PTE_MODE_BITS) - 1) << HV_PTE_INDEX_MODE);
2435   pte.val |= val << HV_PTE_INDEX_MODE;
2436   return pte;
2437 }
2438 
2439 /** Get the page frame number from the PTE.
2440  *
2441  * This field contains the upper bits of the CPA (client physical
2442  * address) of the target page; the complete CPA is this field with
2443  * HV_LOG2_PAGE_TABLE_ALIGN zero bits appended to it.
2444  *
2445  * For all PTEs in the lowest-level page table, and for all PTEs with
2446  * the Page bit set in all page tables, the CPA must be aligned modulo
2447  * the relevant page size.
2448  */
2449 static __inline unsigned long
hv_pte_get_ptfn(const HV_PTE pte)2450 hv_pte_get_ptfn(const HV_PTE pte)
2451 {
2452   return pte.val >> HV_PTE_INDEX_PTFN;
2453 }
2454 
2455 /** Set the page table frame number into a PTE.  See hv_pte_get_ptfn. */
2456 static __inline HV_PTE
hv_pte_set_ptfn(HV_PTE pte,unsigned long val)2457 hv_pte_set_ptfn(HV_PTE pte, unsigned long val)
2458 {
2459   pte.val &= ~(((1ULL << HV_PTE_PTFN_BITS)-1) << HV_PTE_INDEX_PTFN);
2460   pte.val |= (__hv64) val << HV_PTE_INDEX_PTFN;
2461   return pte;
2462 }
2463 
2464 /** Get the client physical address from the PTE.  See hv_pte_set_ptfn. */
2465 static __inline HV_PhysAddr
hv_pte_get_pa(const HV_PTE pte)2466 hv_pte_get_pa(const HV_PTE pte)
2467 {
2468   return (__hv64) hv_pte_get_ptfn(pte) << HV_LOG2_PAGE_TABLE_ALIGN;
2469 }
2470 
2471 /** Set the client physical address into a PTE.  See hv_pte_get_ptfn. */
2472 static __inline HV_PTE
hv_pte_set_pa(HV_PTE pte,HV_PhysAddr pa)2473 hv_pte_set_pa(HV_PTE pte, HV_PhysAddr pa)
2474 {
2475   return hv_pte_set_ptfn(pte, pa >> HV_LOG2_PAGE_TABLE_ALIGN);
2476 }
2477 
2478 
2479 /** Get the remote tile caching this page.
2480  *
2481  * Specifies the remote tile which is providing the L3 cache for this page.
2482  *
2483  * This field is ignored unless the page mode is HV_PTE_MODE_CACHE_TILE_L3.
2484  *
2485  * In level-1 PTEs, if the Page bit is clear, this field determines how the
2486  * level-2 page table is accessed.
2487  */
2488 static __inline unsigned int
hv_pte_get_lotar(const HV_PTE pte)2489 hv_pte_get_lotar(const HV_PTE pte)
2490 {
2491   unsigned int lotar = ((__hv32) pte.val) >> HV_PTE_INDEX_LOTAR;
2492 
2493   return HV_XY_TO_LOTAR( (lotar >> (HV_PTE_LOTAR_BITS / 2)),
2494                          (lotar & ((1 << (HV_PTE_LOTAR_BITS / 2)) - 1)) );
2495 }
2496 
2497 
2498 /** Set the remote tile caching a page into a PTE.  See hv_pte_get_lotar. */
2499 static __inline HV_PTE
hv_pte_set_lotar(HV_PTE pte,unsigned int val)2500 hv_pte_set_lotar(HV_PTE pte, unsigned int val)
2501 {
2502   unsigned int x = HV_LOTAR_X(val);
2503   unsigned int y = HV_LOTAR_Y(val);
2504 
2505   pte.val &= ~(((1ULL << HV_PTE_LOTAR_BITS)-1) << HV_PTE_INDEX_LOTAR);
2506   pte.val |= (x << (HV_PTE_INDEX_LOTAR + HV_PTE_LOTAR_BITS / 2)) |
2507              (y << HV_PTE_INDEX_LOTAR);
2508   return pte;
2509 }
2510 
2511 #endif  /* !__ASSEMBLER__ */
2512 
2513 /** Converts a client physical address to a ptfn. */
2514 #define HV_CPA_TO_PTFN(p) ((p) >> HV_LOG2_PAGE_TABLE_ALIGN)
2515 
2516 /** Converts a ptfn to a client physical address. */
2517 #define HV_PTFN_TO_CPA(p) (((HV_PhysAddr)(p)) << HV_LOG2_PAGE_TABLE_ALIGN)
2518 
2519 #if CHIP_VA_WIDTH() > 32
2520 
2521 /*
2522  * Note that we currently do not allow customizing the page size
2523  * of the L0 pages, but fix them at 4GB, so we do not use the
2524  * "_HV_xxx" nomenclature for the L0 macros.
2525  */
2526 
2527 /** Log number of HV_PTE entries in L0 page table */
2528 #define HV_LOG2_L0_ENTRIES (CHIP_VA_WIDTH() - HV_LOG2_L1_SPAN)
2529 
2530 /** Number of HV_PTE entries in L0 page table */
2531 #define HV_L0_ENTRIES (1 << HV_LOG2_L0_ENTRIES)
2532 
2533 /** Log size of L0 page table in bytes */
2534 #define HV_LOG2_L0_SIZE (HV_LOG2_PTE_SIZE + HV_LOG2_L0_ENTRIES)
2535 
2536 /** Size of L0 page table in bytes */
2537 #define HV_L0_SIZE (1 << HV_LOG2_L0_SIZE)
2538 
2539 #ifdef __ASSEMBLER__
2540 
2541 /** Index in L0 for a specific VA */
2542 #define HV_L0_INDEX(va) \
2543   (((va) >> HV_LOG2_L1_SPAN) & (HV_L0_ENTRIES - 1))
2544 
2545 #else
2546 
2547 /** Index in L1 for a specific VA */
2548 #define HV_L0_INDEX(va) \
2549   (((HV_VirtAddr)(va) >> HV_LOG2_L1_SPAN) & (HV_L0_ENTRIES - 1))
2550 
2551 #endif
2552 
2553 #endif /* CHIP_VA_WIDTH() > 32 */
2554 
2555 /** Log number of HV_PTE entries in L1 page table */
2556 #define _HV_LOG2_L1_ENTRIES(log2_page_size_large) \
2557   (HV_LOG2_L1_SPAN - log2_page_size_large)
2558 
2559 /** Number of HV_PTE entries in L1 page table */
2560 #define _HV_L1_ENTRIES(log2_page_size_large) \
2561   (1 << _HV_LOG2_L1_ENTRIES(log2_page_size_large))
2562 
2563 /** Log size of L1 page table in bytes */
2564 #define _HV_LOG2_L1_SIZE(log2_page_size_large) \
2565   (HV_LOG2_PTE_SIZE + _HV_LOG2_L1_ENTRIES(log2_page_size_large))
2566 
2567 /** Size of L1 page table in bytes */
2568 #define _HV_L1_SIZE(log2_page_size_large) \
2569   (1 << _HV_LOG2_L1_SIZE(log2_page_size_large))
2570 
2571 /** Log number of HV_PTE entries in level-2 page table */
2572 #define _HV_LOG2_L2_ENTRIES(log2_page_size_large, log2_page_size_small) \
2573   (log2_page_size_large - log2_page_size_small)
2574 
2575 /** Number of HV_PTE entries in level-2 page table */
2576 #define _HV_L2_ENTRIES(log2_page_size_large, log2_page_size_small) \
2577   (1 << _HV_LOG2_L2_ENTRIES(log2_page_size_large, log2_page_size_small))
2578 
2579 /** Log size of level-2 page table in bytes */
2580 #define _HV_LOG2_L2_SIZE(log2_page_size_large, log2_page_size_small) \
2581   (HV_LOG2_PTE_SIZE + \
2582    _HV_LOG2_L2_ENTRIES(log2_page_size_large, log2_page_size_small))
2583 
2584 /** Size of level-2 page table in bytes */
2585 #define _HV_L2_SIZE(log2_page_size_large, log2_page_size_small) \
2586   (1 << _HV_LOG2_L2_SIZE(log2_page_size_large, log2_page_size_small))
2587 
2588 #ifdef __ASSEMBLER__
2589 
2590 #if CHIP_VA_WIDTH() > 32
2591 
2592 /** Index in L1 for a specific VA */
2593 #define _HV_L1_INDEX(va, log2_page_size_large) \
2594   (((va) >> log2_page_size_large) & (_HV_L1_ENTRIES(log2_page_size_large) - 1))
2595 
2596 #else /* CHIP_VA_WIDTH() > 32 */
2597 
2598 /** Index in L1 for a specific VA */
2599 #define _HV_L1_INDEX(va, log2_page_size_large) \
2600   (((va) >> log2_page_size_large))
2601 
2602 #endif /* CHIP_VA_WIDTH() > 32 */
2603 
2604 /** Index in level-2 page table for a specific VA */
2605 #define _HV_L2_INDEX(va, log2_page_size_large, log2_page_size_small) \
2606   (((va) >> log2_page_size_small) & \
2607    (_HV_L2_ENTRIES(log2_page_size_large, log2_page_size_small) - 1))
2608 
2609 #else /* __ASSEMBLER __ */
2610 
2611 #if CHIP_VA_WIDTH() > 32
2612 
2613 /** Index in L1 for a specific VA */
2614 #define _HV_L1_INDEX(va, log2_page_size_large) \
2615   (((HV_VirtAddr)(va) >> log2_page_size_large) & \
2616    (_HV_L1_ENTRIES(log2_page_size_large) - 1))
2617 
2618 #else /* CHIP_VA_WIDTH() > 32 */
2619 
2620 /** Index in L1 for a specific VA */
2621 #define _HV_L1_INDEX(va, log2_page_size_large) \
2622   (((HV_VirtAddr)(va) >> log2_page_size_large))
2623 
2624 #endif /* CHIP_VA_WIDTH() > 32 */
2625 
2626 /** Index in level-2 page table for a specific VA */
2627 #define _HV_L2_INDEX(va, log2_page_size_large, log2_page_size_small) \
2628   (((HV_VirtAddr)(va) >> log2_page_size_small) & \
2629    (_HV_L2_ENTRIES(log2_page_size_large, log2_page_size_small) - 1))
2630 
2631 #endif /* __ASSEMBLER __ */
2632 
2633 /** Position of the PFN field within the PTE (subset of the PTFN). */
2634 #define _HV_PTE_INDEX_PFN(log2_page_size) \
2635   (HV_PTE_INDEX_PTFN + (log2_page_size - HV_LOG2_PAGE_TABLE_ALIGN))
2636 
2637 /** Length of the PFN field within the PTE (subset of the PTFN). */
2638 #define _HV_PTE_INDEX_PFN_BITS(log2_page_size) \
2639   (HV_PTE_INDEX_PTFN_BITS - (log2_page_size - HV_LOG2_PAGE_TABLE_ALIGN))
2640 
2641 /** Converts a client physical address to a pfn. */
2642 #define _HV_CPA_TO_PFN(p, log2_page_size) ((p) >> log2_page_size)
2643 
2644 /** Converts a pfn to a client physical address. */
2645 #define _HV_PFN_TO_CPA(p, log2_page_size) \
2646   (((HV_PhysAddr)(p)) << log2_page_size)
2647 
2648 /** Converts a ptfn to a pfn. */
2649 #define _HV_PTFN_TO_PFN(p, log2_page_size) \
2650   ((p) >> (log2_page_size - HV_LOG2_PAGE_TABLE_ALIGN))
2651 
2652 /** Converts a pfn to a ptfn. */
2653 #define _HV_PFN_TO_PTFN(p, log2_page_size) \
2654   ((p) << (log2_page_size - HV_LOG2_PAGE_TABLE_ALIGN))
2655 
2656 #endif /* _HV_HV_H */
2657