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