Permalink
Browse files

Merge https://github.com/0x10cStandardsCommittee/0x10c-Standards

Conflicts:
	ASM/Draft_Assembly_Relocation_Table.txt
  • Loading branch information...
2 parents da559a4 + 61348f2 commit c94771afea60ff85ff00428227880301bc0610fd @hach-que hach-que committed Apr 25, 2012
View
@@ -0,0 +1,5 @@
+*.aux
+*.log
+*.out
+*.tex
+*~
View
@@ -0,0 +1,165 @@
+RFC X1000 (Standard-ABI) A. Bleck, Ed.
+ April 2012
+
+
+ ABI draft
+
+Abstract
+
+ This draft specifies an application binary interface for
+ interoperability between subroutines written by different authors or
+ compiled by different compilers.
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 2
+ 2. Rules common to both calling conventions . . . . . . . . . . . 2
+ 3. Stackcall . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 4. Registercall . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 5. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bleck [Page 1]
+
+ ABI draft April 2012
+
+
+1. Introduction
+
+ Currently there is no standard defined for the behavior of functions
+ that, if conformed to, will allow functions from multiple sources to
+ be compatible. This RFC specifies two 'calling conventions',
+ hereafter called stackcall and registercall. Any compiler
+ implementing these calling conventions would be able to call code
+ generated from a different compiler that also implements these
+ conventions safely.
+
+1.1. Requirements Language
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119. The key
+ word "CALLER" is the function or code that is making the call, the
+ key word "CALLEE" is the function being called
+
+
+2. Rules common to both calling conventions
+
+ The CALLER is REQUIRED to assume that the contents of registers A, B
+ and C are not preserved. The CALLEE is REQUIRED to preserve the
+ contents of registers X, Y, Z, I and J. The CALLER is REQUIRED to
+ assume that the contents of the special purpose register O is not
+ preserved, and contains no valuable information. The CALLEE MUST
+ return it's result, if any, in register A. The CALLEE MUST remove
+ anything and everything it adds to the stack. The CALLER is
+ responsible for cleaning any function arguments passed on the stack
+ from the stack.
+
+
+3. Stackcall
+
+ The CALLER MUST push all arguments to the stack in right to left
+ order, followed by the return pointer, such that the first argument
+ is located on the stack at SP+1, the second is at SP+2, etc. (The
+ CALLER is RECOMMENDED to use the JSR instruction to perform the jump)
+
+
+4. Registercall
+
+ The CALLER MUST place the first three function arguments in registers
+ A, B and C, in that order. Further arguments, if any, MUST be pushed
+ to the stack in right to left order. The return pointer MUST be
+ pushed last, such that argument four is located on the stack at SP+1,
+ argument five is located at SP+2, etc. (The CALLER is RECOMMENDED to
+ use the JSR instruction to perform the jump)
+
+
+
+Bleck [Page 2]
+
+ ABI draft April 2012
+
+
+5. Scope
+
+ This specification applies only to the interface functions present to
+ each other. Internal implementation details are intentially
+ excluded.
+
+
+Author's Address
+
+ Blecki (editor)
+
+ Email: jm@omnisu.com
+ URI: http://jemgine.omnisu.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bleck [Page 3]
+
View
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+<?rfc strict="yes" ?>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="no" ?>
+<?rfc private="RFC X1000 (Standard-ABI)" ?>
+<rfc ipr="none" number="1000" category="info" docName="abi-draft">
+ <front>
+ <title abbrev="ABI draft">ABI draft</title>
+
+ <author fullname="Blecki" initials="A.C." role="editor"
+ surname="Bleck">
+ <organization></organization>
+
+ <address>
+ <email>jm@omnisu.com</email>
+ <uri>http://jemgine.omnisu.com</uri>
+ </address>
+ </author>
+
+ <date month="April" year="2012" />
+ <area>ABI</area>
+ <workgroup>0x10c Standards Committee</workgroup>
+ <abstract>
+ <t>This draft specifies an application binary interface for
+ interoperability between subroutines written by different
+ authors or compiled by different compilers.</t>
+ </abstract>
+ </front>
+
+ <middle>
+ <section title="Introduction">
+ <t>Currently there is no standard defined for the behavior of
+ functions that, if conformed to, will allow functions from
+ multiple sources to be compatible. This RFC specifies two
+ 'calling conventions', hereafter called stackcall and
+ registercall. Any compiler implementing these calling
+ conventions would be able to call code generated from a
+ different compiler that also implements these conventions
+ safely.</t>
+
+ <section title="Requirements Language">
+ <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119.
+
+ The key word "CALLER" is the function or code that is making
+ the call, the key word "CALLEE" is the function being called</t>
+ </section>
+ </section>
+
+ <section anchor="common" title="Rules common to both calling conventions">
+ <t>The CALLER is REQUIRED to assume that the contents of registers A, B and C
+ are not preserved.
+
+ The CALLEE is REQUIRED to preserve the contents of registers X, Y, Z, I and J.
+
+ The CALLER is REQUIRED to assume that the contents of the special purpose
+ register O is not preserved, and contains no valuable information.
+
+ The CALLEE MUST return it's result, if any, in register A.
+
+ The CALLEE MUST remove anything and everything it adds to the stack.
+
+ The CALLER is responsible for cleaning any function arguments passed on the
+ stack from the stack.
+ </t>
+ </section>
+
+ <section anchor="stackcall" title="Stackcall">
+ <t>The CALLER MUST push all arguments to the stack in right to left order,
+ followed by the return pointer, such that the first argument is located
+ on the stack at SP+1, the second is at SP+2, etc. (The CALLER is RECOMMENDED
+ to use the JSR instruction to perform the jump)
+ </t>
+ </section>
+
+ <section anchor="registercall" title="Registercall">
+ <t>The CALLER MUST place the first three function arguments in registers A,
+ B and C, in that order. Further arguments, if any, MUST be pushed to the stack
+ in right to left order. The return pointer MUST be pushed last, such that
+ argument four is located on the stack at SP+1, argument five is located at
+ SP+2, etc. (The CALLER is RECOMMENDED to use the JSR instruction to perform
+ the jump)
+ </t>
+ </section>
+
+ <section anchor="scope" title="Scope">
+ <t>This specification applies only to the interface functions present to
+ each other. Internal implementation details are intentially excluded.</t>
+ </section>
+ </middle>
+
+
+
+</rfc>
+
View
@@ -6,21 +6,30 @@ On April 5 2012, #0x10c-dev agreed to the following standard ABI:
- Return in A
-- J is used for base stack pointer (preserving the value of SP before allocating
- data for locals)
-
- Function local variables are kept on the stack
- Caller cleans stack
- First three arguments to A, B, C, remaining arguments pushed right-to-left onto
the stack
-- Varargs: follow normal rules, except the entire "..." must go on the stack
- even if it's one of the first three arguments
+- Varargs: follow normal rules; the vararg callee should push C,B,A in its
+prolog to have a nice walkable array, and then clear off these three registers
+from the stack in its epilog.
+
- No stupid tricks with the overflow flag
+Note: A compiler is free to optimize away pointless preservations of registers.
+
+The storage location of preserved copies of registers must be re-entrant safe.
+(For all practical purposes, on the stack.)
+
+Non-required suggestions for convention:
+
+- J is used for base stack pointer (preserving the value of SP before allocating
+ data for locals)
+
--------------------------------------------------------------------------------
EXAMPLE FUNCTION CALL:
@@ -59,3 +68,55 @@ SET PC, POP # return
Last updated for DCPU16v11
example by masterm
+
+---------------------------------------------------------------------
+
+The calling convention I am currently using in DCPUC. I'm not necessarily
+ proposing a complete alternative, just a working implementation to compare with. ~~Blecki
+
+DCPUC Calling Convention
+
+First three arguments are passed in registers A, B and C.
+Remaining arguments are pushed onto the stack left-to-right (Such that the last argument has the lowest address)
+Push the return address last (Using the JSR instruction is preferred)
+Return value is placed in A.
+
+Callee is free to clobber all registers.
+Caller must preserve the registers it cares about (Which includes A, B and C, which may be it's own parameters).
+The Caller removes any arguments on the stack itself.
+
+A sample program and the generated assembly, illustrating a function call.
+
+function foo(a,b,c,d) {
+return foo(1,2,3,4);
+}
+
+foo(1,2,3,4);
+
+SET A, 0x0001 ;Literal
+SET B, 0x0002 ;Literal
+SET C, 0x0003 ;Literal
+SET PUSH, 0x0004 ;Literal
+JSR LABEL1_foo ;Calling function
+ADD SP, 0x0001 ;Remove parameters
+BRK ;Non-standard
+:LABEL1_foo
+SET PUSH, A ;Saving register
+SET A, 0x0001 ;Literal
+SET PUSH, B ;Saving register
+SET B, 0x0002 ;Literal
+SET PUSH, C ;Saving register
+SET C, 0x0003 ;Literal
+SET PUSH, X ;Saving register
+SET PUSH, 0x0004 ;Literal
+JSR LABEL1_foo ;Calling function
+ADD SP, 0x0001 ;Remove parameters
+SET J, A ;Save return value from being overwritten by stored register
+SET X, POP ;Restoring register
+SET C, POP ;Restoring register
+SET B, POP ;Restoring register
+SET A, POP ;Restoring register
+SET X, J
+SET A, X
+SET PC, POP ;Return
+SET PC, POP ;Return
Oops, something went wrong. Retry.

0 comments on commit c94771a

Please sign in to comment.