natfeats example

Native Feature Development Guide

There is a complete Native Features SDK ready to develop new NF's to be easily accessible according to the Native Features 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.

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

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.

# 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;
    }

    ...

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).

...
#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;
    }

    ...

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 Native Features 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 Native Features Best Practice to use Native Features.

    /* 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");