It has come to my attention that there is a desire to use properties for
objects other than devices.  To address this need, here is a proposal
for a framework to support generic kernel properties.  More specific
property frameworks, like device properties, can be built on top of
this:



			Generic Properties


1	Summary

There are many places in the kernel where the association of a set of variform
properties with some type of object is desireable.  While this is less
efficient than embedding the data in fixed data structures, it provides much
greater flexibility and modularity without being required to modify public
data structures to provide private,or machine dependent functionality.

Generic Properties proposes to solve these issues by providing generic kernel
database management infrastructure for such information.  The primitives
provided can be used either directly or as building blocks for more complex
semantics.

The database infrastructure operates on 5 entities: 

    Databases contain segregated collections of information associated with a
    collection of objects.

    Objects provide a database key for sorting instances of discrete
    properties.

    Properties are ( Object , Name , Data ) tuples contained within separate
    databases.

    Names are Nul terminated strings to identify particular properties.

    Data is an arbitrary aggregation of opaque data.


2	Synopsis

2.0	Public Data Structures

Two new opaque types are defined:

typedef void *kdatabase_t;	-- Database container object.
typedef void *opaque_t;		-- Container for opaque identifier.
typedef void *prop_iter_t	-- Property iterator.

2.1	Property Types

PROP_STRING			-- Property is a string.
PROP_INT			-- Property is an integer value.
PROP_ARRAY			-- Property is an array of the 
				   same type of values.
PROP_AGREGATE			-- Property is an agregation of 
				   different types of values.
PROP_CONST			-- Property is constant, do not 
				   allocate storage for the data.

2.3	Functions

Kernel Only:

   kdatabase_t createpropdb(const char *name);
   void delpropdb(kdatabase_t db);

User Only:

   kdatabase_t openpropdb(const char *name);
   void closepropdb(kdatabase_t db);

Both kernel and user:

   int setprop(kdatabase_t db, opaque_t object, const char *name, 
		void *val, size_t len, int type, int wait);
   size_t getprop(kdatabase_t db, opaque_t object, prop_iter_t *next,
		const char *name, void *val, size_t len, int *type);
   int delprop(kdatabase_t db, opaque_t object, const char *name);
   int copyprops(kdatabase_t db, opaque_t source, opaque_t dest, 
			int wait);


3	Description

A database is a container for a set of properties.  It is created with
createpropdb(9) and discarded with delpropdb(9);

A property is a tuple that consists of an opaque identifier (often a pointer
to a kernel data structure), string, and an arbitrary amount of data.  This
tuple is established by setprop(9), retrieved by getprop(9), and destroyed by
delprop(9).

Similar interfaces are provided for manipulating kernel databases for both
inside the kernel as well as a system call interface.  Only root can create or
modify property values, but anyone can query properties.


3.1	New Functionality

kdatabase_t createpropdb(const char *name);

Allocate and initialize a kernel database object, and associate `name' with
the database.  `name' may later be used to access this database from userland
throught the userland database query interface.  This operation may block.
Returns NULL on failure.


void delpropdb(kdatabase_t db);

Destroy and deallocate a kernel database objects and all data within.  This
routine deallocates all properties contained within the database.


int setprop(kdatabase_t db, opaque_t object, const char *name, 
		void *val, size_t len, int type, int wait);

Create a property `name' associated with `object' inside database `db', with a
`len' byte value copied from location `val'.  The database must already have
been initialized with createpropdb(9).  `object' is treated as an opaque
value.  The type field is used to identify what the format of the object is.
This value is usually only used to help programs dump property values into
human readable formats.  If `wait' is zero specified then setprop(9) will not
sleep for resource shortage.  If PROP_CONST is specified in the `type' field,
no storage is allocated for the value, and when the property is queried it
will copy `len' bytes from the location specified by `val', so that data
cannot be freed or the kernel may panic.  Returns 0 on success or an error
value.


size_t getprop(kdatabase_t db, opaque_t object, prop_iter_t *next,
		const char **name, void *val, size_t len, int *type);

Retrieve a property called `name' associated with `object'.  Name is a pointer
to a string.  If what `name' points to is NULL, some property in the database
associated with `object' will be selected, `name' will be changed to point to
the name of that property, and the data associated with that property will be
returned.  If `next' is not NULL, its contents should be initialized to zero,
and it will be set so subsequent calls to getprop(9) will be able to iterate
over properties associated with `object'.  To iterate correctly, the contents
`name' should be set to NULL before calling getprop(9).  When iterating,
properites will be returned in no particular order.  Returns -1 if the
property cannot be found, otherwise it returns the length of the value data
and if `val' is not NULL it copies up to `len' bytes of the property data to
the location pointed to by `val'.  The type value associated with that
property is stored in the location pointed to by `type' if it is not NULL.



int delprop(kdatabase_t db, opaque_t object, const char *name);

Remove a property from a database.  If a NULL is supplied for the name,
dev_delprop(9) will remove all properties associated with `object'.  It
returns 0 on success or an error value.


int copyprops(kdatabase_t db, opaque_t source, opaque_t dest, 
		int wait);

Copy all properties associated with `source' to `dest' structure.  If `wait'
is zero then dev_copyprops(9) will not sleep for resource shortage.  Returns 0
on success or an error value.  The state of properties is undefined if the
operation fails.


Eduardo