[OpenSPARC-T2-SAM] / obp / obp / arch / sun4v / api-version.fth

\ ========== Copyright Header Begin ==========================================
\ 
\ Hypervisor Software File: api-version.fth
\ 
\ Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
\ 
\  - Do no alter or remove copyright notices
\ 
\  - Redistribution and use of this software in source and binary forms, with 
\    or without modification, are permitted provided that the following 
\    conditions are met: 
\ 
\  - Redistribution of source code must retain the above copyright notice, 
\    this list of conditions and the following disclaimer.
\ 
\  - Redistribution in binary form must reproduce the above copyright notice,
\    this list of conditions and the following disclaimer in the
\    documentation and/or other materials provided with the distribution. 
\ 
\    Neither the name of Sun Microsystems, Inc. or the names of contributors 
\ may be used to endorse or promote products derived from this software 
\ without specific prior written permission. 
\ 
\     This software is provided "AS IS," without a warranty of any kind. 
\ ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, 
\ INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A 
\ PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN 
\ MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR 
\ ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR 
\ DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN 
\ OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR 
\ FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE 
\ DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, 
\ ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF 
\ SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
\ 
\ You acknowledge that this software is not designed, licensed or
\ intended for use in the design, construction, operation or maintenance of
\ any nuclear facility. 
\ 
\ ========== Copyright Header End ============================================
id: @(#)api-version.fth 1.5 07/06/22 
purpose: 
copyright: Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
copyright: Use is subject to license terms.

headerless

fload ${BP}/arch/sun4v/hv-errcode.fth 

struct
   /w    field  >id          \ api group id
   /w    field  >major       \ major number
   /w    field  >minor       \ minor number
constant /apiver-info

\ htrap number
h# 7f constant core-trap#

\ htrap function numbers
h# 00 constant api-set-version-func#
h# 01 constant api-putchar-func#  \ Is an alias for fast-trap func cons-putchar
h# 02 constant api-exit-func#     \ Is an alias for fast-trap func mach-exit
h# 03 constant api-get-version-func#


\ Hypervisor calls
2 3 api-set-version-func# core-trap#
    hypercall: api-set-version  ( mnr mjr grp -- amnr err )

3 1 api-get-version-func# core-trap#
    hypercall: api-get-version  ( grp -- amnr amjr err )

\ The hypervisor and OBP are tightly coupled and are released together in
\ the same package so the minors numbers in the OBP table are the largest
\ available numbers supported in the hypervisor. We don't need to save the
\ minor numbers because the numbers returned from hypervisor are expected
\ to match those of OBP list.
\
: init-apis ( -- )
   apigroup-ptr dup #api /apiver-info * + swap do ( )
      i >minor w@                                 ( mnr )
      i >major w@                                 ( mnr mjr )
      i >id w@                                    ( mnr mjr grp )
      api-set-version nip hvcheck if              ( )
         i >id w@ id>$group                       ( $group )
         cmn-fatal[ " Could not negotiate %s hypervisor API group" ]cmn-end
      then                                        ( )
   /apiver-info +loop                             ( )
;

stand-init: Configure required API call availability
   init-apis
;

headers
\ SUNW,set-sun4v-api-version
\
\    Input:  api group id
\            major number
\            requested minor number
\    Output: hypervisor call error status
\            supported minor number
\    - Return the larger of the requested minor numbers.
\
\    - Note about selecting the larger minor number:
\        Because guest components are decoupled, different components may 
\        want to choose different versions of the same API group. The 
\        recommendation is that guests should resolve difference as follows:
\ 
\        * If two different components request services in different API 
\          groups, they may interact freely.
\        * If two different components request services in the same API 
\          group, but with different major numbers, one of the components 
\          must be denied the service.
\        * If two different components request services in the same API 
\          group, with the same major number, but with different minor 
\          numbers, the two components should be constrained to use the 
\          larger of the requested minor numbers. This necessitates that new 
\          minor versions be backwards compatible (for example, if a component 
\          negotiates a minor number of '1', the API interfaces must still work 
\          with components that are using a minor number of '0'.
\
cif: SUNW,set-sun4v-api-version  ( mnr mjr grp -- amnr err )
   apigroup-ptr dup #api /apiver-info * + swap do   ( mnr mjr grp )
      dup i >id w@ = if                             ( mnr mjr grp )
         over i >major w@ = if                      ( mnr mjr grp )
            rot i >minor w@ max -rot                ( mnr' mjr grp )
            leave                                   
         else                                       ( mnr mjr grp )
            3drop 0 HV-EBUSY                        ( amnr err )
            unloop exit                             
         then
      then
   /apiver-info +loop                               ( mnr' mjr grp )
   api-set-version                                  ( amnr err )
;

\ SUNW,get-sun4v-api-version
\
\    Input:  api group id
\    Output: hypervisor call error status
\            major number
\            minor number
\
\    - Return the API version info as reported by the hypervisor.
\
cif: SUNW,get-sun4v-api-version  ( grp -- amnr amjr err )
   api-get-version
;

headerless
Commit	Line	Data
920dae64 AT	1	\ ========== Copyright Header Begin ==========================================
	2	\
	3	\ Hypervisor Software File: api-version.fth
	4	\
	5	\ Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
	6	\
	7	\ - Do no alter or remove copyright notices
	8	\
	9	\ - Redistribution and use of this software in source and binary forms, with
	10	\ or without modification, are permitted provided that the following
	11	\ conditions are met:
	12	\
	13	\ - Redistribution of source code must retain the above copyright notice,
	14	\ this list of conditions and the following disclaimer.
	15	\
	16	\ - Redistribution in binary form must reproduce the above copyright notice,
	17	\ this list of conditions and the following disclaimer in the
	18	\ documentation and/or other materials provided with the distribution.
	19	\
	20	\ Neither the name of Sun Microsystems, Inc. or the names of contributors
	21	\ may be used to endorse or promote products derived from this software
	22	\ without specific prior written permission.
	23	\
	24	\ This software is provided "AS IS," without a warranty of any kind.
	25	\ ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
	26	\ INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
	27	\ PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
	28	\ MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
	29	\ ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
	30	\ DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN
	31	\ OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR
	32	\ FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
	33	\ DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
	34	\ ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
	35	\ SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
	36	\
	37	\ You acknowledge that this software is not designed, licensed or
	38	\ intended for use in the design, construction, operation or maintenance of
	39	\ any nuclear facility.
	40	\
	41	\ ========== Copyright Header End ============================================
	42	id: @(#)api-version.fth 1.5 07/06/22
	43	purpose:
	44	copyright: Copyright 2007 Sun Microsystems, Inc. All rights reserved.
	45	copyright: Use is subject to license terms.
	46
	47	headerless
	48
	49	fload ${BP}/arch/sun4v/hv-errcode.fth
	50
	51	struct
	52	/w field >id \ api group id
	53	/w field >major \ major number
	54	/w field >minor \ minor number
	55	constant /apiver-info
	56
	57	\ htrap number
	58	h# 7f constant core-trap#
	59
	60	\ htrap function numbers
	61	h# 00 constant api-set-version-func#
	62	h# 01 constant api-putchar-func# \ Is an alias for fast-trap func cons-putchar
	63	h# 02 constant api-exit-func# \ Is an alias for fast-trap func mach-exit
	64	h# 03 constant api-get-version-func#
65
66
67	\ Hypervisor calls
68	2 3 api-set-version-func# core-trap#
69	hypercall: api-set-version ( mnr mjr grp -- amnr err )
70
71	3 1 api-get-version-func# core-trap#
72	hypercall: api-get-version ( grp -- amnr amjr err )
73
74	\ The hypervisor and OBP are tightly coupled and are released together in
75	\ the same package so the minors numbers in the OBP table are the largest
76	\ available numbers supported in the hypervisor. We don't need to save the
77	\ minor numbers because the numbers returned from hypervisor are expected
78	\ to match those of OBP list.
79	\
80	: init-apis ( -- )
81	apigroup-ptr dup #api /apiver-info * + swap do ( )
82	i >minor w@ ( mnr )
83	i >major w@ ( mnr mjr )
84	i >id w@ ( mnr mjr grp )
85	api-set-version nip hvcheck if ( )
86	i >id w@ id>$group ( $group )
87	cmn-fatal[ " Could not negotiate %s hypervisor API group" ]cmn-end
88	then ( )
89	/apiver-info +loop ( )
90	;
91
92	stand-init: Configure required API call availability
93	init-apis
94	;
95
96	headers
97	\ SUNW,set-sun4v-api-version
98	\
99	\ Input: api group id
100	\ major number
101	\ requested minor number
102	\ Output: hypervisor call error status
103	\ supported minor number
104	\ - Return the larger of the requested minor numbers.
105	\
106	\ - Note about selecting the larger minor number:
107	\ Because guest components are decoupled, different components may
108	\ want to choose different versions of the same API group. The
109	\ recommendation is that guests should resolve difference as follows:
110	\
111	\ * If two different components request services in different API
112	\ groups, they may interact freely.
113	\ * If two different components request services in the same API
114	\ group, but with different major numbers, one of the components
115	\ must be denied the service.
116	\ * If two different components request services in the same API
117	\ group, with the same major number, but with different minor
118	\ numbers, the two components should be constrained to use the
119	\ larger of the requested minor numbers. This necessitates that new
120	\ minor versions be backwards compatible (for example, if a component
121	\ negotiates a minor number of '1', the API interfaces must still work
122	\ with components that are using a minor number of '0'.
123	\
124	cif: SUNW,set-sun4v-api-version ( mnr mjr grp -- amnr err )
125	apigroup-ptr dup #api /apiver-info * + swap do ( mnr mjr grp )
126	dup i >id w@ = if ( mnr mjr grp )
127	over i >major w@ = if ( mnr mjr grp )
128	rot i >minor w@ max -rot ( mnr' mjr grp )
129	leave
130	else ( mnr mjr grp )
131	3drop 0 HV-EBUSY ( amnr err )
132	unloop exit
133	then
134	then
135	/apiver-info +loop ( mnr' mjr grp )
136	api-set-version ( amnr err )
137	;
138
139	\ SUNW,get-sun4v-api-version
140	\
141	\ Input: api group id
142	\ Output: hypervisor call error status
143	\ major number
144	\ minor number
145	\
146	\ - Return the API version info as reported by the hypervisor.
147	\
148	cif: SUNW,get-sun4v-api-version ( grp -- amnr amjr err )
149	api-get-version
150	;
151
152	headerless