Previous Next Contents

5. Man Page

This section also appears in the MemGuard man page (/usr/man/man9/memguard.9).

5.1 NAME

The MemGuard API - Programming interface to the MemGuard function library for the MemGuard users.

5.2 SYNOPOSIS

#include <ogi_mg/memguard.h>

void mgReset(void);
int mgEnable(void);
int mgDisable(void);
int mgAdd( char *name, caddr_t vaddr, u_int size );
int mgDelete( caddr_t vaddr );
int mgSet( caddr_t vaddr, u_int size, char *content );
int mgGet( caddr_t vaddr, u_int size, char *content );
int mgAssert( caddr_t vaddr, u_int size, char *content );
int mgPrintErr(void);

5.3 OVERVIEW

MemGuard is a memory-protection-based run-time guarding tool for the Synthetix project, which is aimed at operat- ing system specialization. A specialized system tries to run specialized components according to some particular system state properties. To ensure correctness, a system should always runs a specialized component under correct assumptions on system states. Since any change to a state property is indicated by writes to some particular data structure, guarding against these writes helps find all potential changes to system state properties.

MemGuard uses memory protection (page protection) hardware to write-protect the data structures that we are concerned with. These data structures are called quasi-invariant terms. Any unexpected write to a quasi-invariant term will trigger page protection fault, so that the system can catch the write and report an error to the programmer. By using MemGuard, a specialized system guarantees to run under correct specialization assumptions.

MemGuard is a function library integrated into the kernel. It provides an API as the programming interface for the MemGuard users.

5.4 DESCRIPTION

void mgReset(void);

mgReset removes the MemGuard protection and resets MemGuard data structures to their initial state. MemGuard is also disabled. Nothing is returned.

int mgEnable(void);

mgEnable enables the MemGuard protection to protect quasi-invariant terms. Among the return values, MG_ENABLE_OK means success; MG_ENABLE_ENABLED means that MemGuard was already enabled.

int mgDisable(void);

mgDisable disables the MemGuard protection so that quasi-invariant terms are unprotected until Mem- Guard is enabled again. However, the user can con- tinue to delete old quasi-invariant terms and add new ones. Newly added quasi-invariant terms will be protected as soon as MemGuard is re-enabled. Among the return values, MG_DISABLE_OK means suc- cess; MG_DISABLE_DISABLED means that MemGuard was already disabled.

int mgAdd( char *name, caddr_t vaddr, u_int size );

mgAdd protects a quasi-invariant term whose virtual address and size are vaddr size. The name of the quasi-invariant term helps debugging. Among the return values, MG_ADD_OK means success; MG_ADD_VADDR means invalid vaddr; MG_ADD_SIZE means invalid size; MG_ADD_NAME means invalid name; MG_ADD_CONFLICT means that the perspective quasi- invariant term is conflict with existing quasi- invariant terms; MG_ADD_FULL means that there are already too many quasi-invariant terms.

int mgDelete( caddr_t vaddr );

mgDelete removes the MemGuard protection from the quasi-invariant term whose virtual address is vaddr. Among the return values, MG_DELETE_OK means success; MG_DELETE_VADDR means that the quasi- invariant term does not exist.

int mgSet( caddr_t vaddr, u_int size, char *content );

mgSet writes to the quasi-invariant term whose vir- tual address and size are vaddr and size with the new value stored in the buffer starting at content. Among the return values, MG_SET_OK means success; MG_SET_VADDR means that the quasi-invariant term does not exist; MG_SET_SIZE means invalid size; MG_SET_CONTENT means that there was an error during the copy.

int mgGet( caddr_t vaddr, u_int size, char *content );

mgGet reads the content of the quasi-invariant term whose virtual address and size are vaddr and size into the buffer starting at content. Among the return values, MG_GET_OK means success; MG_GET_VADDR means that the quasi-invariant term does not exist; MG_GET_SIZE means invalid size; MG_GET_CONTENT means that there was an error during the copy.

int mgAssert( caddr_t vaddr, u_int size, char *content );

mgAssert asserts the content of the quasi-invariant term whose virtual address and size are vaddr and size is equal to the content of the buffer starting at content. Among the return values, MG_ASSERT_OK means success; MG_ASSERT_VADDR means that the quasi-invariant term does not exist; MG_ASSERT_SIZE means invalid size; MG_ASSERT_CONTENT means that the contents are different or there was an error during the copy.

int mgPrintErr(void);

mgPrintErr prints out the error message for the just finished MemGuard function. This function is similar to the user-level perror function. Among the return values, MG_PERROR_OK means success; MG_PERROR_ERROR means that the previous error is not understandable. The user should report this error to the author of MemGuard.

5.5 EXAMPLES

5.6 SEE ALSO

memguard_internal(9)

5.7 BUGS

Current error messages from MemGuard sometimes are incom- plete and conservative because of lack of accurate analy- sis of the faulting instruction.

Current MemGuard does not support multi-processor.

Since a kernel variable may be in the same page with a variable that will be written during the page protection fault handling, protecting the former may result in strange behaviors of the kernel. For example, some of our specialization experiments need to mark some fields of a task structure as quasi-invariant terms, but unfortu- nately, protecting task structures will crash the system. In these situations, thorough system testing without Mem- Guard is required. Future MemGuard will try to avoid this case as much as possible. Similar to the copy-on-write mechanism, future user-level MemGuard will not have this problem when it is used for memory protection in user address space.


Previous Next Contents