====== Native Feature Development Guide ======

There is a complete Native Features SDK ready to develop new NF's to
be easily accessible according to the [[best_practice]] document. The
key is to provide device drivers for every functionality implemented
using NF. The base usage code to use NFs is completely the same for
both FreeMiNT .xdd and BetaDOS .bos driver (except for the #include
statements and a single nf_ops initialization line).

**NOTE: In the initialization code is indeed almost the same  for both
FreeMiNT as well as for BetaDOS drivers.  The only difference is where
it gets the 'struct *nf_ops' pointer from.**

===== Initialization Code =====

In order to call NFs you need to get a pointer to the 'struct nf_ops'
which provides the ''get_id()'' and ''call()'' methods.

<code>
struct nf_ops
{
	long __CDECL (*get_id)(const char *);
	long __CDECL (*call)(long id, ...);
	long res[3];
};
</code>


==== FreeMiNT ====

For FreeMiNT the ''struct nf_ops'' is defined in the ''freemint/sys/mint/arch/nf_ops.h'' header file
and provided by the kernel as a part of the ''kerinfo'' structure which is passed to a device
driver init routine.

Note: The kernel must be compiled with -DARANYM in order to provide valid nf_ops pointer. This is
of course the default build setup for aranym kernel builds.

<code>
# include "mint/mint.h"
# include "mint/arch/nf_ops.h"

...

DEVDRV * _cdecl init (struct kerinfo *k)
{
    struct nf_ops *nf_ops;

    /* get the 'struct nf_ops*' pointer from kerinfo* */
    nf_ops = k->nf_ops;

    if ( ! nf_ops ) {
        c_conws ("The System Does Not Support Native Features.\r\n");
        return NULL;
    }

    ...
</code>

A very simple example of working nfstderr.xdd implementation can be found
in the FreeMiNT CVS repository at ''freemint/sys/xdd/nfstderr''.


==== BetaDOS ====

BetaDOS doesn't provide any built-in support which would give us the
''sturct nf_ops*'' directly. There is a simple library-like code available
in the aranym CVS in the ''aranym/atari/natfeat'' folder. This library
provides the ''atari/natfeat/nf_ops.h'' header which makes the usage
almost the same as for FreeMiNT driver.

You need to use the ''nf_init()'' function to get the ''struct nf_ops*''
to use (as there is no ''kerinfo'' structure to get it from).


<code>
...
#include "atari/natfeat/nf_ops.h"

void *init_driver(void)
{
    struct nf_ops *nf_ops;

    /* get the 'struct nf_ops*' pointer using the nf_init() */
    nf_ops = nf_init();

    if ( ! nf_ops ) {
        Cconws ("The System Does Not Support Native Features.\r\n");
        return (void*)NULL;
    }

    ...
</code>

The nfstderr.bos driver source (a BetaDOS nfstderr.xdd equivalent) sources
can be found in the ARAnyM CVS repository in the ''atari/nfstderr'' folder.


===== Actual Native Feature Call =====

As defined in the [[proposal]] the workflow is to look the ''long'' ID of
the native feature up (using the NF name string). And then use the ID to
call the feature placing its arguments to the stack.

**Note: This is only designed for OS driver development. No application
should do this directly! Applications should use the [[best_practice]] to
use Native Features.**

<code>
    /* get the "NF_STDERR" NF id */
    long nf_stderr_id = nf_ops->get_id( "NF_STDERR" );
    if ( ! nf_stderr_id ) {
        return NULL;
    }

    /* use the NF: this will send the string to the emulator's stderr */
    nf_ops->call( nf_stderr_id, "nfstderr: installed\r\n");
</code>