121 lines
3.6 KiB
Plaintext
121 lines
3.6 KiB
Plaintext
.TH "hwgraph.dev" D3X
|
|
.SH NAME
|
|
\f4hwgraph.dev:\f1 hwgraph_block_device_add, hwgraph_char_device_add,
|
|
hwgraph_chmod, device_info_set, device_info_get \- create and use device vertex
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft 3
|
|
#include <sys/types.h>
|
|
#include <sys/hwgraph.h>
|
|
#include <sys/ddi.h>
|
|
.sp .8v
|
|
graph_error_t
|
|
hwgraph_block_device_add(vertex_hdl_t \f2from_vhdl\fP,
|
|
char *\f2path\fP,
|
|
char *\f2driver_prefix\fP,
|
|
vertex_hdl_t *\f2vhdl_ptr\fP);
|
|
.sp .8v
|
|
graph_error_t
|
|
hwgraph_char_device_add(vertex_hdl_t \f2from_vhdl\fP,
|
|
char *\f2path\fP,
|
|
char *\f2driver_prefix\fP,
|
|
vertex_hdl_t *\f2vhdl_ptr\fP);
|
|
.sp .8v
|
|
void
|
|
device_info_set(vertex_hdl_t \f2device\fP, void *\f2info\fP);
|
|
.sp .8v
|
|
void *
|
|
device_info_get(vertex_hdl_t \f2device\fP);
|
|
.sp .8v
|
|
void
|
|
hwgraph_chmod(vertex_hdl_t \f2vhdl\fP, mode_t \f2mode\fP);
|
|
.ft 1
|
|
.fi
|
|
.SS Arguments
|
|
.IP "\f2device\fP" 12n
|
|
Vertex handle of a device vertex,
|
|
typically one created by
|
|
.IR hwgraph_block_device_add ()
|
|
or
|
|
.IR hwgraph_char_device_add ().
|
|
.IP "\f2driver_prefix\f1" 12n
|
|
The device driver character string prefix of the
|
|
device driver that is to manage the newly-created device.
|
|
.IP "\f2from_vhdl\fP" 12n
|
|
Vertex handle that is the connection point of the device to be described.
|
|
Typically the vertex handle passed to the
|
|
.I attach
|
|
entry point of a device driver.
|
|
.IP "\f2mode\fP" 12n
|
|
A standard file protection mode as declared in sys/stat.h.
|
|
.IP "\f2path\f1" 12n
|
|
An edge name,
|
|
or a sequence of edge names separated by slashes
|
|
(which looks exactly like a relative pathname in the /hw filesystem).
|
|
.IP "\f2vhdl\fP"
|
|
A vertex handle of a device in the hwgraph.
|
|
.P
|
|
.IP "\f2vhdl_ptr\fP" 12n
|
|
A pointer to a field where a new vertex handle is returned.
|
|
.SH DESCRIPTION
|
|
The device_add functions operate on the hardware graph to
|
|
add a new vertex that represents a block or a char device.
|
|
The new vertex is visible in /hw as a character or block device special file.
|
|
The device is controlled by the device driver that is identified by
|
|
.IR prefix ,
|
|
so that
|
|
.IR prefix_open ()
|
|
is called when the new vertex is opened.
|
|
When it is opened,
|
|
the dev_t passed to the driver's open entry point matches the
|
|
vertex_hdl_t returned in
|
|
.IR vhdl_ptr .
|
|
.P
|
|
The
|
|
.IR device_info_set ()
|
|
function associates a pointer-sized piece of information
|
|
with a specified dev_t for later retrieval by
|
|
.IR device_info_get ().
|
|
Typically, this information is a pointer to a per-device data
|
|
structure allocated by the driver in its
|
|
.I attach
|
|
entry point.
|
|
.P
|
|
.BR Caution :
|
|
A device driver should never change the device-info of any vertex
|
|
that the device driver did not create.
|
|
In particular, the vertex that is passed to the
|
|
.IR attach ()
|
|
entry point of a PCI driver is owned by the PCI infrastructure.
|
|
If the driver sets the device-info of that connection-point vertex,
|
|
the PCI infrastructure is likely to crash.
|
|
A driver is always free to change the device-info of a vertex that
|
|
the driver itself creates using the device_add functions.
|
|
.P
|
|
.IR hwgraph_chmod ()
|
|
sets the initial (default) access mode of the /hw representation
|
|
of the specified vertex.
|
|
.SH DIAGNOSTICS
|
|
The *_device_add functions return GRAPH_SUCCESS
|
|
when the operation completes successfully,
|
|
or a failure code as listed in
|
|
.IR hwgraph (D3X)
|
|
when the operation does not complete successfully.
|
|
.P
|
|
.IR device_info_set ()
|
|
always succeeds and has no return value.
|
|
It is the caller's responsibility to pass a valid
|
|
.IR device ;
|
|
that is, a dev_t that represents a vertex in the hardware graph.
|
|
.P
|
|
.IR device_info_get ()
|
|
returns the pointer-sized piece of information associated
|
|
with the specified
|
|
.IR device .
|
|
This value is unpredictable until
|
|
.IR device_info_set ()
|
|
has been called.
|
|
.SH SEE ALSO
|
|
hwgraph.inv(D3X),
|
|
hwgraph.intro(D4X).
|