15.2.1 Function Attributes

access(access-mode, ref-index[, size-index])

The access attribute provides additional information about how a function accesses memory. It can assist in diagnosing potential bugs related to memory access via compiler warnings and help the compiler perform better optimizations.

The ref_index argument is the index (starting from the left with index 1) of the function pointer argument that points to the target object being accessed. A function pointer argument can be referenced by at most one distinct access attribute.

The optional size_index argument is the index of the function argument that specifies the number of elements of the pointer type referenced by ref-index, or the number of bytes when the pointer type is void *. When this argument is not specified, the pointer argument must be either NULL or point to a space that is suitably aligned and sized for at least one object of the referenced type (this implies that a past-the-end pointer is not a valid argument). The actual size of the access may be less but it must not be more.

__attribute__ ((access (read_only, 1))) int puts(const char *);

__attribute__ ((access (read_only, 2, 3))) void * memcpy(void *, const void *, size_t);

address(addr)

The address attribute specifies an absolute physical address at which the attributed routine will be placed in memory. It can be used with C and C++ functions.

__attribute__((address(0x9D008000))) void bar (void);

The compiler performs no error checking on the address. The section containing the function will be located at the specified address regardless of the memory-regions specified in the linker script or the actual memory ranges on the target device. The application code must ensure that the address is valid for the target device.

Sections used to hold functions placed at an absolute address will use a name .address.N.decl, where N is the address and decl is the name of the declaration.

To make effective use of absolute sections and the new best-fit allocator, standard program-memory and data-memory sections should not be mapped in the linker script. The built-in linker script does not map most standard sections such as the .text, .data, .bss, or .ramfunc sections. By not mapping these sections in the linker script, we allow these sections to be allocated using the best-fit allocator rather than the sequential allocator. Sections that are unmapped in the linker script can flow around absolute sections, whereas sections that are linker-script mapped are grouped together and allocated sequentially, potentially causing conflicts with absolute sections.

alias ("symbol")

Indicates that the function is an alias for another symbol. For example:

	void foo (void) { /* stuff */ }
	__attribute__ ((alias("foo"))) void bar (void);

Symbol bar is considered to be an alias for the symbol foo.

always_inline

void __attribute__ ((always_inline))  foo (void);

at_vector

void __attribute__ ((interrupt(IPL4SOFT))) __attribute__ ((at_vector(54)))
foo void);

See also Interrupts and Exception Handlers.

const

int __attribute((const)) rv(int a);

deprecated

deprecated (msg)

void __attribute__ ((deprecated ("The bar function is no longer used"))) bar (void);

externally_visible

void __attribute__((externally_visible)) foo (void);

far

void __attribute__((far)) foo (void);

format (type, format_index, first_to_check)

extern int __attribute__ ((format (printf, 2, 3))) my_printf (void *my_object, const char *my_format, ...);

The type parameter is one of printf, scanf, strftime or strfmon (optionally with surrounding double underscores, for example, __printf__) and determines how the format string will be interpreted.

The format_index parameter specifies which function parameter is the format string. Function parameters are numbered from the left-most parameter, starting from 1.

The first_to_check parameter specifies which parameter is the first to check against the format string. If first_to_check is zero, type checking is not performed and the compiler only checks the format string for consistency (for example, vfprintf).

format_arg (index)

extern char * __attribute__ ((format_arg (2))) my_foo (char *my_str, const char *my_format);

function_replacement_prologue

This feature allows the application to redirect one function to another implementation at runtime without replacing the existing function. This is achieved by changing the method of invoking functions through a function replacement table instead of from a linker-resolved address. Initially the function address in the table points to the location of the entry point of the original function's prologue. The application can then replace the table entry with the new function address. Now, during the program execution, the control will pass to the new function address and returns to the caller function. This feature adds a new function_replacement_prologue function attribute. To redirect the function, modify the corresponding Function Replacement Table entry at runtime.

Example C code:

int a, b, c, d;
int __attribute__((function_replacement_prologue)) foo (void)
{
   a = b + c;
   return (a);
}
int main()
{
   d = foo();
   return 0;
}

Example generated assembly code:

# Function Replacement Table entries, located in data memory
   .section .fixtable, data
fixtable.foo:
   .word     cont.foo         # By default, populate the table with the address
                              # of the original implementation. Redirect to
                              # another implementation by overwriting this
                              # location with the address of the new implementation.

   .section .text, code
   .globl foo
   .ent foo
   .type foo, @function
foo:
   # Begin Function Replacement Table Prologue
   lui $25,%hi(fixtable.foo)        # Load address from .fixtable above
   lw $25,%lo(fixtable.foo)($25)
   j $25                            # Jump to address loaded from table
   nop
cont.foo:
   # End Function Replacement Table Prologue
   addiu $sp,$sp,-8
   sw $fp,4($sp)
   move $fp,$sp
   lw $3,%gp_rel(b)($28)
   ...........
   j $31
   nop

interrupt (priority)

Generate prologue and epilogue code for the function as an interrupt handler function. See Interrupts . The argument specified the interrupt priority level using the symbols IPLnSOFT, IPLnSRS, or IPLnAUTO where n represents the 7 levels of priority and SOFT|SRS|AUTO specifies the context saving mode.

keep

void __attribute__((keep)) foo(void);

longcall

void __attribute__((longcall)) foo (void);

malloc

void __attribute__ ((malloc)) *custom_malloc (int size_t);  

micromips

void __attribute__ ((microcmips)) foo(void);

mips16

void __attribute__ ((mips16)) foo(void);

naked

void __attribute__ ((naked)) foo(void);

near

void __attribute__ ((near)) foo(void);

no_fpu

void __attribute__((interrupt(IPL7SRS), vector(_CORE_TIMER_VECTOR), no_fpu)) isr(void);

noinline

void __attribute__ ((noinline)) foo(void);

noload

void __attribute__ ((noload)) foo(void);

nomips16

void __attribute__ ((nomips16)) foo(void);

nonnull (index, ...)

Indicate to the compiler that one or more pointer arguments to the function must be non-null. If the compiler determines that a Null Pointer is passed as a value to a non-null argument, and the -Wnonnull command line option was specified, a warning diagnostic is issued.

void * __attribute__((nonnull)) my_memset (void * ptr, int x, size_t len);

noreturn

void __attribute__ ((noreturn)) myExit(void);

optimize(optimization)

int __attribute__((optimize("O3"))) pandora (void) {
  if (maya > axton)
    return 1;
  return 0;
}

pure

void __attribute__ ((pure)) foo(void);

ramfunc

The ramfunc attribute locates the attributed routine in RAM rather than in Flash memory on devices that normally execute code from Flash. This attribute can be used for both C functions and C++ class methods. The compiler's default runtime startup code uses the data-initialization template to copy the code associated with functions using this attribute from Flash to RAM at program startup.

When this attribute is used with C functions, the function is placed at the highest appropriately aligned address for executable code. Note that due to ramfunc alignment and placement requirements, the address attribute should not be used with the ramfunc attribute. The presence of the ramfunc section causes the linker to emit the symbols necessary for the crt0.S start-up code to initialize the bus matrix appropriately for executing code out of data memory.

  __attribute__((ramfunc,section(".ramfunc"),far,unique_section))
  unsigned int myramfunct (void_
    { /* code */ }

  #include <sys/attribs.h>
  __longramfunc__ unsigned int  myramfunct (void)
    { /* code */ }

class printmyname {
    // Access specifier
public:
    // Data  Members
    string myname;
    int  dummy ;
    // Member Functions()
    printmyname (){
        myname = "microchip";
    }
    
    void  __attribute__((ramfunc, long_call)) set_name(string newname){
        myname = newname;
        dummy = 9;
    }
    void printname() { cout << "name is:" << myname; }
};

section("name")

Place the function into the named section.

For example:

void __attribute__ ((section (".wilma"))) baz () {return;}

Function baz will be placed in section .wilma.

The -ffunction-sections command line option has no effect on functions defined with a section attribute.

unique_section

Place the function in a uniquely named section, as if -ffunction-sections had been specified. If the function also has a section attribute, use that section name as the prefix for generating the unique section name.

For example:

void __attribute__ ((section (".fred"), unique_section) foo (void) {return;}

Function foo will be placed in section .fred.foo.

unused

void __attribute__ ((unused)) opt_setting(void);

used

void __attribute__ ((used)) foo(void);

vector (num)

void __attribute__((vector(0), interrupt(IPL7AUTO))) myisr(void);

warn_unused_result

void __attribute__ ((warn_unused_result)) foo(void);

weak

void __attribute__ ((weak)) foo(void);