Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.


Summary of Kernel Support Functions

This appendix summarizes the kernel support functions (and some macros that behave like functions) that loadable kernel servers can call.  Within the general categories of "General Functions" and "Network Functions," function declarations are further subgrouped to help you identify their interrelationships.

Chapter 10, "Kernel Support Functions," contains full descriptions of all the functions listed here.  In addition, loadable kernel servers can use many Mach kernel functions, which are described in a section of Chapter 4, "Mach Functions."  The Mach kernel functions are summarized in the manual, NeXTSTEP Programmer Interface Summary.

General Functions

This section contains a summary of the general purpose kernel support functions.  Most of the functions and macros in this section are declared through either the kernserv/kern_server_types.h or kernserv/prototypes.h header file.

Time Functions

Busy-wait for a certain amount of time:

void DELAY(unsigned int usecs)

Get or set the current time:
ns_time_t clock_value(clock_types_t which_clock)
void set_clock(clock_types_t which_clock, ns_time_t ns)

Get information about a clock:
clock_attributes(clock_types_t which_clock)

Convert between ns_time_t and timeval data formats:
void ns_time_to_timeval(ns_time_t ns, struct timeval *tv)
ns_time_t timeval_to_ns_time(struct timeval *tv)

Schedule or unschedule a function to be called later:
void ns_abstimeout(func function, vm_address_t arg, ns_time_t deadline, int priority)
void ns_timeout(func function, vm_address_t arg, ns_time_t time, int priority)
boolean_t ns_untimeout(func function, vm_address_t arg)

Memory Functions

Make addresses pageable or memory-resident:

kern_return_t kern_serv_unwire_range(kern_server_t *ksp, vm_address_t address, vm_size_t size)
kern_return_t kern_serv_wire_range(kern_server_t *ksp, vm_address_t address, vm_size_t size)

Copy or initialize data:
void bcopy(void *from, void *to, int length)
void bytecopy(void *from, void *to, int length)
void bzero(void *address, int length)

Allocate or free memory:
void * kalloc(int size)
void kfree(void *address, int size)
void * kget(int size)

Critical Section and Synchronization Functions

Use read and write locks:

lock_t lock_alloc(void)
void lock_free(lock_t lock)
void lock_done(lock_t lock)
void lock_init(lock_t lock, boolean_t can_sleep)
void lock_read(lock_t lock)
void lock_write(lock_t lock)

Use simple, nonsleeping locks:
void simple_lock(simple_lock_t lock)
simple_lock_t simple_lock_alloc(void)
void simple_lock_free(simple_lock_t lock)
void simple_lock_init(simple_lock_t lock)
void simple_unlock(simple_lock_t lock)

Cause a thread to sleep or wake up:
void assert_wait(int event, boolean_t interruptible)
void clear_wait(thread_t thread, int result, boolean_t interrupt_only)
void thread_block(void)
void thread_set_timeout(int ticks)
void thread_sleep(int event, simple_lock_t lock, boolean_t interruptible)
void thread_wakeup(int event)

General Task and Thread Functions

Get information about this thread or task:

task_t current_task(void)
int thread_wait_result(void)

Create or kill a thread:
thread_t kernel_thread(task_t task, void (*start)(void))
void thread_halt_self(void)

Port and Message Functions

Request notification messages, such as port death notification:

kern_return_t kern_serv_notify(kern_server_t *ksp, port_t reply_port, port_t request_port)

Get the kernel's task port:
port_t kern_serv_kernel_task_port(void)

Get or set information about this server's ports:
port_t kern_serv_bootstrap_port(kern_server_t *ksp)
port_t kern_serv_local_port(kern_server_t *ksp)
port_t kern_serv_notify_port(kern_server_t *ksp)
void kern_serv_port_gone(kern_server_t *ksp, port_name_t port)
kern_return_t kern_serv_port_proc(kern_server_t *ksp, port_all_t port, port_map_proc_t function, int arg)
kern_return_t kern_serv_port_serv(kern_server_t *ksp, port_all_t port, port_map_proc_t function, int arg)
port_set_name_t kern_serv_port_set(kern_server_t *ksp)

Hardware Interface Functions

Set up or remove an interrupt handler:

int install_polled_intr(int which, int (*my_intr)(void))
int uninstall_polled_intr(int which, int (*my_intr)(void))

Get or test a virtual address that corresponds to a hardware address:
caddr_t map_addr(caddr_t address, int size)
int probe_rb(void *address)

Change or determine the processor level:
int curipl(void)
int spl0(void), spl1(void), spl2(void), spl3(void), spl4(void), spl5(void), spl6(void), spl7(void)
void splx(int priority)

Logging and Debugging Functions

Kill the loadable kernel server:

void ASSERT(int expression)
kern_return_t kern_serv_panic(port_t bootstrap_port, panic_msg_t message)
void panic(char *string)

Log a message:
void kern_serv_log(kern_server_t *ksp, int log_level, char *format, arg1, ..., arg5)
int log(int level, char *format, arg, ...)
int printf(char *format, arg, ...)

UNIX Support Functions

In a UNIX-style server, determine whether the user has root privileges:

int suser(void)

In a UNIX-style server, wait for I/O completion on a buffer:
void biodone(struct buf *bp)
void biowait(struct buf *bp)

In a UNIX-style server, copy data between user and kernel address space:
int copyin(void *from, void *to, int length)
int copyout(void *from, void *to, int length)

In a UNIX-style server, implement the select() system call:
int selthreadcache(void **waiterPtr)
void selthreadclear(void **waiterPtr)
int selwakeup(void *waiter, int collided)

Miscellaneous Functions

Modify or inspect a string:

int sprintf(char *string, char *format, arg, ...)
char * strcat(char *string1, char *string2)
int strcmp(char *string1, char *string2)
int strncmp(char *string1, char *string2, unsigned long length)
char * strcpy(char *to, char *from)
char * strncpy(char *to, char *from, unsigned long length)
int strlen(char *string)

Call a function from the main thread:
kern_return_t kern_serv_callout(kern_server_t *ksp, void (*func)(void *), void *arg)

Network Functions

This section contains a summary of the network-specific kernel support functions, which are described in detail in Chapter 10.  A general discussion of networking drivers and protocols is in Chapter 8, "Network Modules."

Netif Functions

To use these functions, you need to include the header file net/netif.h.

Initialize and install a new netif:

netif_t if_attach(if_init_func_t init_func, if_input_func_t input_func, if_output_func_t output_func, if_getbuf_func_t getbuf_func, if_control_func_t control_func, const char *name, unsigned int unit, const char *type, unsigned int mtu, unsigned int flags, netif_class_t class, void *private)
void if_registervirtual(if_attach_func_t attach_func, void *private)

Remove a netif:
void if_detach(netif_t netif)

Get or set data for a netif:
unsigned int if_collisions(netif_t netif)
void if_collisions_set(netif_t netif, unsigned int collisions)
unsigned int if_flags(netif_t netif)
void if_flags_set(netif_t netif, unsigned int flags)
unsigned int if_ierrors(netif_t netif)
void if_ierrors_set(netif_t netif, unsigned int ierrors)
unsigned int if_oerrors(netif_t netif)
void if_oerrors_set(netif_t netif, unsigned int oerrors)
unsigned int if_ipackets(netif_t netif)
void if_ipackets_set(netif_t netif, unsigned int ipackets)
unsigned int if_opackets(netif_t netif)
void if_opackets_set(netif_t netif, unsigned int opackets)
unsigned int if_mtu(netif_t netif)
const char * if_name(netif_t netif)
void * if_private(netif_t netif)
const char * if_type(netif_t netif)
unsigned int if_unit(netif_t netif)

Call a function implemented by a network module:
int if_control(netif_t netif, const char *command, void *data)
netbuf_t if_getbuf(netif_t netif)
int if_init(netif_t netif)
int if_ioctl(netif_t netif, unsigned int command, void *data)
int if_output(netif_t netif, netbuf_t packet, void *address)

Get information about netifs:
netif_class_t if_class(netif_t netif)
netif_t iflist_first(void)
netif_t iflist_next(netif_t netif)

Dispatch a packet to a protocol handler:
int if_handle_input(netif_t netif, netbuf_t packet, void *extra)

Netbuf Functions

You should include the header file net/netbuf.h when you use these functions.

Allocate or free a netbuf or its wrapper:

netbuf_t nb_alloc(unsigned int size)
netbuf_t nb_alloc_wrapper(void *data, unsigned int size, void freefunc(void *), void *freefunc_arg)
void nb_free(netbuf_t nb)
void nb_free_wrapper(netbuf_t nb)

Change the size of a netbuf:
int nb_grow_bot(netbuf_t nb, unsigned int size)
int nb_shrink_bot(netbuf_t nb, unsigned int size)
int nb_grow_top(netbuf_t nb, unsigned int size)
int nb_shrink_top(netbuf_t nb, unsigned int size)

Access the data in a netbuf:
char * nb_map(netbuf_t nb)
int nb_read(netbuf_t nb, unsigned int offset, unsigned int size, void *target)
int nb_write(netbuf_t nb, unsigned int offset, unsigned int size, void *source)
unsigned int nb_size(netbuf_t nb)

Miscellaneous Functions

For the host-network conversion functions, you need to include the header file netinet/in.h.  For inet_queue(), you should include both net/netif.h and net/netbuf.h.

Convert values between host and network byte order:

u_long htonl(u_long hostlong)
u_short htons(u_short hostshort)
u_long ntohl(u_long netlong)
u_short ntohs(u_short netshort)

Give an IP input packet to the kernel for processing:
void inet_queue(netif_t netif, netbuf_t netbuf)