kmed.8

.       @(#)kmed.1 $Revision$ $Date$
.TH KMED 1 "$Revision$ $Date$"
.if n .ds CW \fB
.if !n .ds CW \f(CW
.SH NAME
kmed \- Example of a remote kme daemon
.SH SYNOPSIS
.TP 7
\fBkmed
\fB[\-c\ \fRcorefile\fB]
\fB[\-e\ \fRendian\fB]
\fB[\-r]
\fB[\-U\ \fRport\fB]
\fB[\-D\ \fRdebug\fB]
.SH DESCRIPTION
\fIKmed\fR is an example of a remote daemon for \fIkme(1)\fP.
\fIKmed\fR communicates with \fIkme\fP over a socket using a simple
custom UDP protocol called \fBRW\fP (for read-write).  The example
version of \fIkmed\fP is useful as-is for many debugging situations.
\fIkmed\fP, however, may require customization in order to provide access
to some types of hardware.

\fIKmed\fP can provide access for \fIkme\fP to more than one \fIcorefile\fP
(special device file) at a time.  From \fIkme\fP, the Nth \fIcorefile\fP
is accessed by prefixing the memory/device address with \*(CWNN:\fP,
where \*(CWNN\fP
is zero-based (i.e. \*(CW00;\fP refers to the first \fIcorefile\fP,
\*(CW01:\fP refers to the 2nd \fIcorefile\fP, etc.);

.PP
Command line options include:
.TP
.BI \-c \ corefile(s)
A colon-separated list of pathname(s) or device names which the
remote \fIkme\fP will be given access to.  An unadorned pathname will
be accessed using open(), close(), lseek(), read(), and write().
.IP ""
.br
Two alternative syntaxes are available for \fIcorefile\fP, and both allow
access to the \fIcorefile\fP by using mmap() to map the \fIcorefile\fP into
the \fIkmed\fP process.  Mmap() is very useful when you want to access
the \fI/dev/mem\fP special file on Linux.
.IP ""
A fixed mmap()ing is selected with the syntax: \fIcorefile,offset,size\fP.
In this case, \fIsize\fP bytes at \fIoffset\fP from the start of the
\fIcorefile\fP are mmap()ed.  This is useful if you want to access
just a small region of a special device file. \fIoffset\fP and \fIsize\fP
are interpreted in hexadecimal when prefixed with \fB0x\fP,
otherwise they are decimal.
.IP ""
.br
A floating mmap()ing is selected with the syntax: \fIcorefile,1,size\fP.
In this case, \fIsize\fP bytes are mmap()ed, but the \fIoffset\fP of the mmap()
will be determined based on the addresses that \fIkme\fP requests.  The
offset may change over and over depending on what \fIkme\fP needs to
display or modify.  This
is useful if you want to access into a potentially large area of
a special device file.  However, there may be performance implications
if the addresses that \fIkme\fP needs bounce all over the place.  A well
designed \fIkme_defs\fP file and \fIkme\fP display can minimize this problem.
.IP ""
.br
The default for corefile is \fI/dev/kmem\fR.
.TP
.BI \-e \ endian
Unfortunately, the original \fBRW\fP protocol was designed eons ago with
no consideration
given to the endianess of the protocol.  This can cause problems
when \fIkme\fP and \fIkmed\fP are running on computers with different endianess.
The \fIendian\fP option can be set to \fB0\fP (as-is), \fB1\fP (big-endian),
or \fB2\fP (auto detect).
The default is to autodetect the endianess, and this usually works.
.TP
.BI \-r "\0\0\0\0\0"
Open the \fIcorefile(s)\fP for read access only.  The default is to open the
\fIcorefile(s)\fP for both read and write access.
.TP
.BI \-U \ port
The UDP \fIport\fP number to use for communications with \fIkme\fP.
The default is port 2773.
.TP
.BI \-D \ level
Set the debug output \fIlevel\fP for debugging \fIkmed\fP itself.
The default is 0 (no debugging output).
.SH EXAMPLES
.PP
Simple access to /dev/kmem:
.PP
.RS
.ft CW
# kmed &
.ft P
.RE
.PP
The 1st corefile is /dev/kmem and is accessed using lseek(), read()
and write().  The 2nd corefile is a floating mmap() of /dev/mem
with a size of 4096 (one kernel memory page).
.PP
.RS
.ft CW
# kmed -c /dev/kmem:/dev/mem,1,4096 &
.ft P
.RE
.SH "RW PROTOCOL"
The definitive specification of the \fBRW\fP protocol is the
header file \fIkme.h\fP
and the source code for \fIkme.c\fP.  The protocol is UDP based (datagrams).
.PP
When \fIkme\fP wants to read a memory location, it sends an \fBrw_t\fP packet
to \fIkmed\fP and expects an \fBrw_t\fP packet in response.
It tries this a few times,
and then gives up and displays \*(CW????????\fP for that location.  If the
response was lost due to temporary network congestion it is not a big deal
because \fIkme\fP will reissue the read request on the next display cycle.
.PP
A similar thing happens with write requests.  But in case all of
the retries of the write request are lost, the user will notice that
the value hasn't changed and reissue the \fIkme\fP \fBc\fPhange command.
Obviously,
this does not work well for hardware registers that are write-only.  In
addition, network congestion could cause \fIkmed\fP to see two or more write
requests before \fIkme\fP sees the reply from \fIkmed\fP.
For some hardware registers, multiple writes could cause unexpected behavior.
.SH "SEE ALSO"
kme(1)