radare2/doc/calling-conventions.md

Calling Conventions profiles
============================

Radare2 uses calling conventions to help in identifying function formal arguments and return types. It is used also as guide for basic function prototype (WIP at the time of writing this wiki).

Profile grammar
===============

Since the profiles are based on sdb database, Creating one is as simple as creating group of `key=value` pairs in text file. then parsing it into sdb data file.

Attribute list
==============

Note that you will substitute `x` for the calling convention name you will use.

`default.cc=x` : used to set the default calling convention used for all functions in `RAnal` instance for which this key is set, string of this calling convention `"x"` will be returned for every call of `R_API const char *r_anal_cc_default(RAnal *anal)`.

`x=cc`: used to initialize calling convention (think of it as their is calling convention called x).

`cc.x.name=x`: This one is a bit awkward, it is used internally to improve memory usage by reducing memory consumption No need to worry about it except for calling convention profile will probably break if this one doesn't exist.

`cc.x.arg1=reg`, `cc.x.arg2=reg`: used to set the ith argument of this calling convention to register name, feel free to use whatever register name you want to as long as it is supported by the target architecture. Ex: `cc.optlink.arg1=eax` on x86 architecture.

`cc.x.argn=stack`: means that all the arguments (or the rest of them in case there was `argi` for any i as counting number) will be stored in stack from left to right. Ex `cc.cdecl.argn=stack`.

`cc.x.argn=stack_rev`: same as `cc.x.argn=stack` except for it means argument are passed right to left. Ex: `cc.stdcall.argn=stack_rev`

`cc.x.ret=reg`: used to set where the return value is stored for the given calling convention.

File Path
=========

In order to integrate the calling convention profile you created with the r2 source, few set of conventions should be followed:

- Store the unparsed sdb file in `path-to-radare2-source/libr/anal/d`.
- If you want the sdb to be loaded for specific architecture the file name should follow this convention `cc-arch-bits`, for example to create profile that loads automatically for x86 arch with 16 bits call the file `cc-x86-16`
- In the file `path-to-radare2-source/libr/anal/d/makefile` add entry `F+= cc-arch-bits` with desired arch and bits and you should be ready to go.
Adding doc for calling convention 2016-07-28 04:05:42 +00:00			`Calling Conventions profiles`
			`============================`

			`Radare2 uses calling conventions to help in identifying function formal arguments and return types. It is used also as guide for basic function prototype (WIP at the time of writing this wiki).`

PowerPC calling conventions (#5477) * added powerpc-32 calling conventions * added powerpc-64 calling conventions * fixed grammar * added powerpc 32 and 64 2016-08-10 14:07:39 +00:00			`Profile grammar`
Adding doc for calling convention 2016-07-28 04:05:42 +00:00			`===============`

			Since the profiles are based on sdb database, Creating one is as simple as creating group of `key=value` pairs in text file. then parsing it into sdb data file.

Types docs (#5557) * Adding types documentation * refactoring and optimizing types databases All based on docs * fixing r_core_types_init Basically we needed to try all possible 7 combinatios of file name, I am not sure if there is a way to do that automatically. one extra thing, since this is init subroutine we should make sure that the db is already empty, when reloading this function (by changing env vars), it will be reloaded thus it needs a reset first. 2016-08-19 18:31:41 +00:00			`Attribute list`
Adding doc for calling convention 2016-07-28 04:05:42 +00:00			`==============`

			Note that you will substitute `x` for the calling convention name you will use.

Fix few typos in doc/ (#8618) 2017-09-30 09:58:41 +00:00			`default.cc=x` : used to set the default calling convention used for all functions in `RAnal` instance for which this key is set, string of this calling convention `"x"` will be returned for every call of `R_API const char r_anal_cc_default(RAnal anal)`.
Adding doc for calling convention 2016-07-28 04:05:42 +00:00
			`x=cc`: used to initialize calling convention (think of it as their is calling convention called x).

			`cc.x.name=x`: This one is a bit awkward, it is used internally to improve memory usage by reducing memory consumption No need to worry about it except for calling convention profile will probably break if this one doesn't exist.

			`cc.x.arg1=reg`, `cc.x.arg2=reg`: used to set the ith argument of this calling convention to register name, feel free to use whatever register name you want to as long as it is supported by the target architecture. Ex: `cc.optlink.arg1=eax` on x86 architecture.

			`cc.x.argn=stack`: means that all the arguments (or the rest of them in case there was `argi` for any i as counting number) will be stored in stack from left to right. Ex `cc.cdecl.argn=stack`.

			`cc.x.argn=stack_rev`: same as `cc.x.argn=stack` except for it means argument are passed right to left. Ex: `cc.stdcall.argn=stack_rev`

			`cc.x.ret=reg`: used to set where the return value is stored for the given calling convention.

			`File Path`
			`=========`

			`In order to integrate the calling convention profile you created with the r2 source, few set of conventions should be followed:`

			- Store the unparsed sdb file in `path-to-radare2-source/libr/anal/d`.
			- If you want the sdb to be loaded for specific architecture the file name should follow this convention `cc-arch-bits`, for example to create profile that loads automatically for x86 arch with 16 bits call the file `cc-x86-16`
			- In the file `path-to-radare2-source/libr/anal/d/makefile` add entry `F+= cc-arch-bits` with desired arch and bits and you should be ready to go.