/* Copyright 1998 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#pragma force_top_level
#pragma include_only_once

/*Name:    swis.h
  Purpose: Generalised SWI interface
  Author:  (c) Acorn Computers Ltd, 1989
  Version: 2.04 (09-Jan-1995)
  This file is automatically generated from Hdr:makehswis
*/

#ifndef __swis_h
#define __swis_h

#ifndef __kernel_h
  #include "kernel.h"
#endif

#ifdef __cplusplus
extern "C"
{
#endif

#pragma -v4
extern int _swi (int swi_no, unsigned int, ...);

extern _kernel_oserror *_swix (int swi_no, unsigned int, ...);
#pragma -v0

#ifdef __cplusplus
}
#endif

#define _FLAGS     0x10 /*use with _RETURN() or _OUT()*/
#define _IN(i)     (1U << (i))
#define _INR(i,j)  (~0 << (i) ^ ~0 << (j) + 1)
#define _OUT(i)    ((i) != _FLAGS? 1U << 31 - (i): 1U << 21)
#define _OUTR(i,j) (~0U >> (i) ^ ~0U >> (j) + 1)
#define _BLOCK(i)  (1U << 11 | (unsigned) (i) << 12)
#define _RETURN(i) ((i) != _FLAGS? (unsigned) (i) << 16: 0xFU << 16)
#define _C         (1U << 29)
#define _Z         (1U << 30)
#define _N         (1U << 31)

#define XOS_Bit    (1U << 17) /*deprecated: use _swi() or _swix()*/

/*
 * These functions provide a generic method of calling RISC OS SWIs from C or
 * C++.
 *
 * Two functions are provided:
 *     _swi for calling SWIs without setting the X bit
 *     _swix which sets the X bit before calling the SWI.
 *
 * swi_no is the number of the SWI to be called. This should never have the
 * X bit set.
 *
 * mask is a word containing an input and output register mask, a return
 * register, and a block parameter register.
 *
 * The arrangement of mask is as follows:
 *
 * Bits 0 -  9:  Set if R(N) is passed to the SWI.
 * Bits 22 - 31: Set if R(31-N) is output from the SWI (ie bit 31
 *               corresponds to R0, bit 22 corresponds to R9).
 * Bit 21:       Set if the PC (including the flags) is to be output.
 * Bits 16 - 19: Register no. to be returned from a _swi call. This is only
 *               applicable to _swi as _swix always returns either 0 or an error
 *               pointer.
 * Bit 11:       Set if a local block parameter is to be passed to the SWI
 * Bits 12 - 15: Register number for local block parameter if bit 11 set.
 *
 * If a register is specified as a return register (bits 16-19) it must not
 * also be specified as an output register in the output register mask
 * (bits 22-31).
 *
 * If a register is specified as a local block parameter register it must not
 * also be specified as an input register in the input register mask
 * (bits 0-9).
 *
 * If the PC is specified as a return register (ie bits 16-19 = 15) or as an
 * output registers (bit 21 = 1) the value returned will contain the flags in
 * bits 28 to 31 (28 = V, 29 = C, 30 = Z, 31 = N).
 *
 * The remainder of the variadic arguments are as follows (in order):
 *
 * The word value of each input register in order from 0 to 9 as specified by
 * bits 0 to 9 of the mask.
 *
 * The address of a word to be written for each output register in order from
 * 0 to 9 as specified by bits 31 downto 22 of the mask.
 *
 * The address of a word to be written with the PC value on exit from the SWI
 * if bit 21 of the register mask is set.
 *
 * If bit 11 is set the remainder of the arguments are placed in order in a
 * parameter block and the address of the parameter block is passed to the SWI
 * in the register specified by bits 12-15.
 *
 * The macros are as follows:
 *
 * _IN(n)       - Specifies that R(n) is used on input
 * _OUT(n)      - Specifies that R(n) is output
 * _BLOCK(n)    - Specifies that R(n) is a block parameter
 * _RETURN(n)   - Specifies that R(n) is returned from _swi.
 *
 * The values of the macros should be ORed together to produce the value for
 * the mask.
 *
 * The following constants are defined
 *
 * _FLAGS       - the register containing the flags (currently 15)
 * _C           - mask for the C bit in _FLAGS
 * _Z           - mask for the Z bit in _FLAGS
 * _N           - mask for the N bit in _FLAGS
 *
 * Example calls:
 *
 *     _swi(OS_NewLine, 0);   // Must specify 0 register mask
 *
 *     _swi(OS_Write0, _IN(0), "Hello, World");
 *
 *     task_handle = _swi(Wimp_Initialise, _IN(0)|_IN(1)|_IN(2)|_RETURN(1),
 *                        300, *(int *)"TASK", "Test");
 *
 *     e = _swix(Wimp_LoadTemplate, _IN(1)|_IN(2)|_IN(3)|_IN(4)|_IN(5)|_IN(6)|
 *                                  _OUT(2)|_OUT(6),
 *               template_buffer, workspace, workspace_end, -1, "MyWind", next,
 *               &workspace_end, &next);
 *
 *     e = _swix(Wimp_SetExtent, _IN(0)|_BLOCK(1), w, minx, miny, maxx, maxy);
 */