Unified Hosting Interface. MD01069 Reference Manual

Transcription

1 Unified Hosting Interface MD01069 Reference Manual Copyright Imagination Technologies Limited. All Rights Reserved. This publication contains proprietary information which is subject to change without notice and is supplied 'as is' without warranty of any kind. Imagination Technologies, the Imagination logo, PowerVR, MIPS, Meta, Ensigma and Codescape are trademarks or registered trademarks of Imagination Technologies Limited. All other logos, products, trademarks and registered trademarks are the property of their respective owners. Filename : MIPS_Toolchain.UHI Reference Manual.docx Version : External Issue Issue Date : 06 Jul 2015 Author : Imagination Technologies Limited Unified Hosting Interface 1 Revision 1.1.6

2 Imagination Technologies Public Contents 1. Introduction Addresses Standards ABI Exit Open Close Read Write Lseek Unlink Fstat Argc Argnlen Argn RAM Range Plog Assert Exception Pread Pwrite Link Boot Failure Boot protocols Boot monitors General Exception entry point UHI exception chaining Appendix A. Error values List of Figures Figure 1 UHI in Embedded OS... 3 Figure 2 Forwarding a UHI operation to a debugger Revision MD01069 Reference Manual

3 1. Introduction A hosting interface provides a mechanism for user-mode applications to request services that require complex processing or knowledge of the current hardware. Such requests are either processed on the same target by a higher level OS (self-hosting or fully hosted) or offloaded to a remote host (semihosted). The MIPS Unified Hosting Interface (UHI) aims to support both scenarios of self-hosting and semihosting without the need to neither modify the software when switching between the two nor require any special knowledge of the current hardware. The interface is layered to allow requests to propagate upwards through software stacks, boot monitors and debuggers. MIPS UHI is based around the SYSCALL and SDBBP instructions along with a custom ABI and a reserved SYSCALL/SDBBP number. The SYSCALL instruction is used wherever there may be a higher level of software handling, the SDBBP instruction is used when a debugger is the only remaining option. Note: This interface does not apply to Linux userland applications where a fully featured hosting environment is provided via a SYSCALL interface. Host QEMU IASim Codescape Debugger UHI - SDBBP Handler Boot Monitor From Toolchain RTOS Function RTOS Toolchain exception vector UHI - SYSCALL C library From Toolchain Application File operations: read, open, write & close. Figure 1 UHI in Embedded OS 1.1. Addresses All addresses mentioned in this document are virtual addresses, not physical. Unified Hosting Interface 3 Revision 1.1.6

4 Imagination Technologies Public 1.2. Standards Several operations supported by UHI aim to comply with industry standards to the extent that the host OS can support this. Where features are unsupportable it is up to the implementation to select an appropriate error to report. Online reference for the IEEE Std (POSIX) standard can be found here: Compliance to this is noted in the description for each UHI operation where applicable. Revision MD01069 Reference Manual

5 2. ABI UHI defines a special ABI for argument passing in order to abstract most differences between 32-bit and 64-bit architectures. Most arguments are passed by value in registers, except some larger structures that are passed by reference (with respect to target endianess). Any such structures are precisely defined in this specification. values are also passed in registers. All arguments and return values are sign or zero extended as appropriate to the full width of a register. In: $2 syscall number /* i.e. 1 */ $25 operation code $4-$7 operation arguments Out: $2-5 operation return values SYSCALL 1 / SDBBP 1 are reserved for UHI. $2 must also be set to 1 to ease software servicing but is not required when using the SDBBP interface. Any operation that may set errno will return the errno value as an additional result. Values for errno results are provided in Error values on page 18. Unimplemented or undefined UHI operations should not return control to the target Exit Operation code 1 void mips_exit (int32_t exit_code) None Arguments $25: Operation code 1 $4: Exit code Allow interception of an application exit event, boot monitors which can be resumed are expected to handle this operation specially. Please see Boot monitors for further details Open Operation code 2 int32_t mips_open (const char *file_name, int32_t flags, int32_t mode) $2: New file descriptor or -1 in case of an error Unified Hosting Interface 5 Revision 1.1.6

6 Imagination Technologies Public Arguments $25: Operation code 2 $4: Path/file name. $5: One or more file creation flags. Refer to Table 1: Flags for details $6: Permissions to use when a new file is created. Refer to Table 2: Modes for details. Table 1: Flags Flag Value O_RDONLY 0x0000 Read enabled O_WRONLY 0x0001 Write enabled O_RDWR 0x0002 Read and write enabled O_APPEND 0x0008 Open in append mode O_CREAT 0x0200 Create a new file if the file does not exist O_TRUNC 0x0400 If the file already exists truncated to length 0 O_EXCL 0x0800 Generate error on open if file exists Table 2: Modes Flag Value S_IXOTH 0001 Others have execute permission S_IWOTH 0002 Others have write permission S_IROTH 0004 Others have read permission S_IRWXO 0007 Others have read, write and execute permission S_IXGRP 0010 Group has execute permission S_IWGRP 0020 Group has write permission S_IRGRP 0040 Group has read permission S_IRWXG 0070 Group has read, write and execute permission S_IXUSR 0100 User (file owner) has execute permission S_IWUSR 0200 User has write permission S_IRUSR 0400 User has read permission S_IRWXU 0700 User has read, write and execute permission Special filenames: /dev/stdin, /dev/stdout and /dev/stderr for stdin, stdout and stderr respectively. File descriptors 0, 1 and 2 are reserved for these streams. Standards Conforms to IEEE Std Revision MD01069 Reference Manual

7 2.3. Close Operation code 3 int32_t mips_close (int32_t fd) $2: 0 on success or -1 in case of error Arguments $25: Operation code 3 $4: File descriptor to close Standards Conforms to IEEE Std Read Operation code 4 long mips_read (int32_t file, void *buffer, long len) $2: Number of bytes read or -1 in case of error Arguments $25: Operation code 4 $4: File descriptor to read from $5: Buffer to read into $6: Max number of bytes to read The buffer must span at least len bytes. Standards Conforms to IEEE Std Write Operation code 5 long mips_write (int32_t file, const void *buffer, long count) $2: Number of bytes read or -1 in case of error Arguments $25: Operation code 5 $4: File descriptor to write to $5: Buffer to write from $6: Max number of bytes to write The buffer must span at least count bytes. Standards Conforms to IEEE Std Unified Hosting Interface 7 Revision 1.1.6

8 Imagination Technologies Public 2.6. Lseek Operation code 6 long mips_lseek (int32_t file, long offset, int32_t whence) $2: New offset or -1 in case of error Arguments $25: Operation code 6 $4: File descriptor to operate on $5: Number of bytes to reposition $6: How to reposition. Refer Table 3: Whence values for possible values. Table 3: Whence values Flag Value SEEK_SET 0x0001 The offset is set to offset bytes SEEK_CUR 0x0002 The offset is set to its current location plus offset bytes SEEK_END 0x0004 The offset is set to the size of the file plus offset bytes Standards Conforms to IEEE Std Unlink Operation code 7 int32_t mips_unlink (const char *file) $2: 0 on success or non-zero on failure Arguments $25: Operation code 7 $4: Path/file name to remove from file system Standards Conforms to IEEE Std , where hardlinks are not supported on the host OS then this operation can be implemented as deleting the file. Revision MD01069 Reference Manual

9 2.8. Fstat Operation code 8 int32_t mips_fstat (int32_t file, struct uhi_stat *sbuf) $2: 0 on success or non-zero on failure Arguments $25: Operation code 8 $4: File descriptor to operate on $5: Buffer to store the status information. The stat structure is given below: struct uhi_stat { }; int16_t st_dev; uint16_t st_ino; uint32_tst_mode; uint16_t st_nlink; uint16_tst_uid; uint16_t st_gid; int16_t st_rdev; uint64_t st_size; uint64_t st_atime; uint64_t st_spare1; uint64_t st_mtime; uint64_t st_spare2; uint64_t st_ctime; uint64_t st_spare3; uint64_t st_blksize; uint64_t st_blocks; uint64_t st_spare4[2]; The UHI stat structure is abstracted to be the same regardless of the target ABI. The upper-32 bits of several fields should be discarded for a 32-bit program. Standards Conforms to IEEE Std Unified Hosting Interface 9 Revision 1.1.6

10 Imagination Technologies Public 2.9. Argc Operation code 9 int32_t mips_argc (void) $2: Number of arguments Arguments $25: Operation code 9 s the number of arguments, minimum of Argnlen Operation code 10 int32_t mips_arglen (int32_t n) $2: Length of n th argument or -1 on error Arguments $25: Operation code 10 $4: Argument number s the length of the n th argument (excluding the terminating null character) Argn Operation code 11 int32_t mips_argn (int32_t n, char *buf) $2: 0 on success or -1 on error Arguments $25: Operation code 11 $4: Argument number $5: Destination buffer, where the argument is copied s the n th argument in the buffer provided. The buffer must be at least as large as the value obtained from argnlen for same argument. These operations can be used to construct argv and argc as shown in the following pseudo-code: Revision MD01069 Reference Manual

11 int i, argc; char **argv; argc = mips_argc (); argv = malloc (argc * sizeof (char*)); for (i = 0; i < argc; i++) { argv[i] = malloc ( mips_arglen (i) + 1); mips_argn (i, argv[i]); } main (argc, argv); RAM Range Operation code 12 (void*, void *) mips_ramrange () $2: The first address of RAM $3: The last address+1 of RAM Arguments $25: Operation code 12 Reports the range of the largest usable block of RAM in the system. This memory will commonly be used for placing a stack and/or heap but may be used for any dynamic memory allocation needs Plog Operation code 13 int32_t mips_plog (const char* msg, int32_t num) $2: Number of characters output Arguments $25: Operation code 13 $4: Null terminated character array to output $5; Integer to use in formatting msg (if %d is present) A limited form of printf. Initially support for just one integer argument. String formatting to be done by the hosting platform. Unified Hosting Interface 11 Revision 1.1.6

12 Imagination Technologies Public Assert Operation code 14 void mips_assert (char *message, char *filename, int line_num) None Arguments $25: Operation code 14 $4: Message to display $5: File containing assert statement $6: Line number in the specified file Indicates a software assertion has triggered Exception Operation code 15 void mips_exception (struct gpctx*, int abi) None Arguments $25: Operation code 15 $4: Pointer to a GP context structure or NULL if the current hardware context should be used. See definitions below for o32, n32 and n64 context definitions. Indicates an unhandled exception has occurred with state available from the GP context or current hardware registers. When a non-null context is provided the cause register in the context should be inspected to determine the specific exception. Where a null context is provided then the value of $25 at the point of the exception must be copied to K0 and the value of $4 at the point of the exception must be copied to K1. The values of K0/K1 are therefore not available without a soft-context. ABI Name 0 O32 1 N32 2 N64 Revision MD01069 Reference Manual

13 #if ABI == O32 typedef uint32_t reg_t; #else typedef uint64_t reg_t; #endif #if ABI == N64 sizeof(void *) == 8 #else sizeof(void *) == 4 #endif struct gpctx { union { struct { reg_t at; reg_t v[2]; #if ABI!= O32 reg_t a[8]; reg_t t[4]; #else reg_t a[4]; reg_t t[8]; #endif reg_t s[8]; reg_t t2[2]; reg_t k[2]; reg_t gp; reg_t sp; reg_t fp; reg_t ra; }; reg_t r[31]; }; reg_t epc; reg_t badvaddr; reg_t hi; reg_t lo; /* This field is for future extension */ void *link; /* Status represents the status at the point of exception but with EXL cleared */ uint32_t status; /* These fields should be considered read-only */ uint32_t cause; uint32_t badinstr; uint32_t badpinstr; Pread Operation code 19 long mips_pread (int32_t fd, void *buf, long count, long offset) $2: Number of bytes read or -1 in case of error Arguments $25: Operation code 19 $4: File descriptor to read from $5: Buffer to read into $6: Max number of bytes to read $7: Offset in file from which bytes are to be read Standards Conforms to IEEE Std Unified Hosting Interface 13 Revision 1.1.6

14 Imagination Technologies Public Pwrite Operation code 20 long mips_pwrite (int32_t fd, const void *buf, long count, long offset) $2: Number of bytes written or -1 in case of error Arguments $25: Operation code 20 $4: File descriptor to write to $5: Buffer to write from $6: Max number of bytes to write $7: Offset in file at which bytes are to be written Standards Conforms to IEEE Std Link Operation code 22 int32_t mips_link (const char *oldname, const char *newname) $2: 0 on success or -1 in case of error Arguments $25: Operation code 22 $4: Old name of a file $5: New name to be given Standards Conforms to IEEE Std Where hardlinks are not supported on the host OS then this operation can be implemented as copying the file Boot Failure Operation code 23 void mips_boot_fail (int reason) Only returns if the problem has been corrected via the debugger Arguments $25: Operation code 23 $4: reason code, see below. This operation is only available via the SDBBP interface Reason 1 L2 cache configuration is external to the core and no custom initialization code provided. (Config5.L2C == 1). If the L2 cache can be initialized by the debugger then this failure can be recovered. 2 Incompatible core configuration detected. This is unrecoverable. Revision MD01069 Reference Manual

15 3. Boot protocols A UHI compliant entry point will expect to receive a number of parameters. The $4 register is the control and determines which of the other registers are used and their meaning. Note: All other negative values provided for $4 are reserved for future extension. As a general rule, the existing protocols listed below cannot be extended to have more parameters; doing so would risk becoming incompatible with existing UHI compliant implementations. $4=Any non-zero positive value Represents argc and the $6 and $7 parameters become valid. Register Values Meaning $5 argv An array of char* pointers $6 envp A null terminated array of char* pointers with each string having format key=value $4=0 All other registers will be ignored. $4=-1 The UHI interface for obtaining argc and argv is available to obtain the command line. $4=-2 The Device Tree handover is in use. Register Values Meaning $5 DT Address Virtual (kseg0) address of Device Tree Blob As a special rule to cope with running 32-bit applications under a 64-bit boot monitor, the argv and envp structures are allowed to be 64-bit if Status.KX==1 at the point of running an application s startup code. For an o32 or n32 application, this means that the argv and envp arrays may need converting from 64-bit to 32-bit pointers before being passed to a user s main function by creating a temporary structure on the stack. Checks should be made in any such code that the 64-bit pointers are 32-bit safe. Unified Hosting Interface 15 Revision 1.1.6

16 Imagination Technologies Public 4. Boot monitors A boot monitor may implement any subset of operations as required. For operations that are not supported the operations should be forwarded to a debugger using code similar to Figure 2. Note: This design is suitable for boot-monitors and applications that use o32, n32 or n64 as their ABI. A common feature needed in a boot loader is the ability to resume the boot process after a test application has executed. The most important consideration when trying to do this is avoiding corruption of the monitor state which requires segregating the address space. There is no one-sizefits-all answer to this problem so a conservative recommendation is to leave 2MB of space at the start of KSEG0 and therefore place an application starting at address 0x (0xffffffff for 64-bit). A boot monitor may then sit at either the start of KSEG0 (which is often ROM anyway) or at the upper most location in memory although the latter option requires some co-ordination on where application stack and heap are placed. A UHI compliant runtime will generally invoke the EXIT operation using the SYSCALL interface as a last ditch attempt to yield control of the processor. A boot-monitor must hook this operation to support resuming from application exit. If the monitor can be resumed, then the EXIT operation must succeed and return control to the application. This may seem odd but the program must be responsible for restoring critical state back to that of the boot context. Resuming a boot-monitor requires additional register state to be preserved across the execution of an application: On entry to the start-up code $31 (RA) must hold the address to resume in the boot-monitor. Additional register state on entry to the start-up code will be preserved and restored before return: $28 (GP) $29 (SP) $30 (FP) $16 - $30 (S0 > S8) Note: Floating-point callee-saved state is not part of the preserved set. $2 on return to the boot-monitor will contain the overall exit code for the application. All CP0 registers modified as part of the application startup will also be preserved This definition allows a boot-monitor to be built as soft-float (which is almost certainly reasonable) and allows a guest program to be invoked from C code by calling the entry point as if calling the main() function directly General Exception entry point When a boot monitor implements some UHI operations directly then the general exception entry points must be careful to avoid assumptions about the active state. In particular: The GP register is likely to be set as part of the loaded application code and would need restoring to the value required by the boot monitor during exception handling. Ideally K0 and K1 registers would not be considered as scratch registers in a boot monitor exception handler to allow application code to have used these outside of exception context (an application in this context does include an RTOS). Avoiding use of K0 and K1 is however only possible when the COP0 KScratch registers are available. There should be no assumption that the boot monitor is still in control of the exception vector as this may have been replaced (see the next section for UHI exception chaining). For 64-bit boot-monitors then application code may have configured COP0 Status to disable 64-bit operations which may lead to exceptions. If EXL is cleared during exception handling then the KX bit may need explicitly setting. The value of COP0 Status must however be restored before exception return. Revision MD01069 Reference Manual

17 Interrupts may be enabled and the exception handler may be interrupted if EXL is cleared. There is a chance of re-entering the general exception vector for another UHI operation as part of handling an interrupt. The impact of this should be considered and interrupts disabled if the UHI operation handlers are not re-entrant. When hooking a UHI operation that is part of a set (such as open/close/fstat/read/write) then all related operations should be hooked to the same extent; to ensure consistent handling. Fine grained hooks are also possible by only responding to operations with specific argument values. Any operations which are not hooked should be forwarded to a debugger via the SDBBP interface. Example C code for this is as follows: Note: This example assumes all GP context state is placed in a structure and regtype is 32-bit for an o32 boot monitor and 64-bit for n32 or n64: int excpt_uhi_sdbbp (struct gpctx *ctx) { register regtype arg1 asm ("$4") = ctx->a[0]; register regtype arg2 asm ("$5") = ctx->a[1]; register regtype arg3 asm ("$6") = ctx->a[2]; register regtype arg4 asm ("$7") = ctx->a[3]; register regtype op asm ("$25") = ctx->t2[1]; register regtype ret1 asm ("$2") = 1; register regtype ret2 asm ("$3"); asm volatile (" # UHI indirect\n" "\tsdbbp 1" : "+r" (ret1), "=r" (ret2), "+r" (arg1), "+r" (arg2) : "r" (arg3), "r" (arg4), "r" (op)); ctx->v[0] = ret1; ctx->v[1] = ret2; ctx->a[0] = arg1; ctx->a[1] = arg2; /* Handled, move on. SYSCALL is 4-bytes in all ISAs. */ ctx->epc += 4; } return 1; /* exception handled */ Figure 2 Forwarding a UHI operation to a debugger 4.2. UHI exception chaining For an application to make use of a boot monitors UHI implementation then one of two solutions must be in place. The simplest option is to leave the boot monitors exception vector in place and the application will naturally invoke the boot monitor using the UHI SYSCALL interface. Using this option does however mean that no custom interrupt or exception handling is possible in an application. If an exception handler is installed then it must forward UHI exceptions on to the boot monitor. There are several steps required to do this: 1) During application startup the address of the boot monitor s exception vector must be collected. This will either be the value in EBASE (if COP0 Status.BEV is clear) or 0xBFC00200 otherwise. 2) When processing a general exception then a UHI SYSCALL must be detected and a decision made as to whether this should be passed on to the boot monitor. 3) To forward the exception to the boot monitor; restore all saved context and (instead of issuing an ERET to return from exception) perform an indirect jump to the boot monitor general exception entry point (i.e. 0x180 offset from the exception base). The indirect jump can be performed using register $3 as this register is defined as clobbered for all UHI operations and never has an input value. 4) Optionally restore the K0/K1 values from the initial boot context if you need to cope with boot monitors that use K0/K1 for persistent state. It is possible to design a trampoline such that the exit from the boot monitor exception vector can go on to restore the application values of K0/K1 but this is left as an implementation detail if required. Unified Hosting Interface 17 Revision 1.1.6

18 Imagination Technologies Public Appendix A. Error values Error Value List of operations (that can trigger the error) EACCES 13 pwrite, link, unlink, open, write EAGAIN 11 pread, pwrite, read, write EBADF 9 pwrite, pread, close, lseek, fstat, read, write EBADMSG 77 pread, read EBUSY 16 unlink, ECONNRESET 104 pread, pwrite, read EEXIST 17 link, open, EFBIG 27 pwrite, read, write EINTR 4 open, close, read, write EINVAL 22 lseek, pread, pwrite, open, read EIO 5 pwrite, open, close, fstat, pread, read, write EISDIR 21 open, pread, read ELOOP 92 open, link, unlink EMFILE 24 open EMLINK 31 link, ENAMETOOLONG 91 link, unlink, open ENETDOWN 115 pwrite, write ENETUNREACH 114 pwrite, write ENFILE 23 open ENOBUFS 105 pread, pwrite, read, write ENOENT 2 link, unlink, open ENOMEM 12 open, pread, read ENOSPC 28 pwrite, link, open, write ENOSR 63 open ENOTCONN 128 pread, read ENOTDIR 20 link, unlink, open ENXIO 6 open, pread, pwrite, read, write EOVERFLOW 139 open, lseek, fstat, pread, read EPERM 1 link, unlink EPIPE 32 pwrite, write, write ERANGE 34 pwrite, write EROFS 30 link, unlink, open ESPIPE 29 lseek, pread, pwrite, read ETIMEDOUT 116 pread, read Revision MD01069 Reference Manual

19 Error Value List of operations (that can trigger the error) ETXTBSY 26 unlink, open EWOULDBLOCK 11 pread, pwrite EXDEV 18 link Unified Hosting Interface 19 Revision 1.1.6