patch -- Command

Patch a variable or flag within the kernel
/conf/patch [-k] image symbol=value ...

The command patch  alters the value of datum symbol  to value in executable
image.  In  general,  you should  use  patch  to  alter configuration  data
(constants) in  programs, in  device drivers,  and in the  COHERENT kernel.
For patch to work with a  symbolic constant, image must have a symbol table
that includes  information about  symbol. Therefore, executables  that have
been processed by the command strip cannot be patched.

Options

patch recognizes the following command-line options:

-k   Patch  image, and  patch  the kernel  memory of  the running  COHERENT
     system via device /dev/kmem. Only  the superuser root can use patch to
     access kernel memory.

-K   Patch /dev/kmem only.  Refer to image for its symbol table, but do not
     change it.

-p   ``Peek'' -- just display current values; change nothing.

-v   Verbose -- display values before and after patching.

Variable Names

symbol and  value can  be either  a numeric constant  or a symbol  from the
symbol table  of image. symbol and value expressions  can include a numeric
offset.    In  addition,   value   can  be   composed   of  the   construct
makedev(major,minor), where major and minor are the ``major'' and ``minor''
device numbers,  respectively, resulting in a  dev_t-sized device type.  No
spaces can appear around the equal sign in the symbol=constant construct.

Numeric constants default to decimal, but may be specifyed with a leading 0
prefix to specify  an octal number or a 0x  prefix to specify a hexadecimal
number.

The size  of the altered  symbol field is, by  default, sizeof(int).  patch
recognizes the following explicit size overrides:

:c The size of the altered field is sizeof(char).

:i The size of the altered field is sizeof(int).

:l The size of the altered field is sizeof(long).

:s The size of the altered field is sizeof(short).

Example

The following  example gives technique  that allows kernel  display -- that
is,  the output  of  the routines  cmn_err()  and the  kernel's version  of
printf() --  to go  to a serial  port.  With this,  you can save  the panic
messages and register dumps on a  terminal screen or printer page while you
reboot and  try to track down  what went wrong.  To do  so, plug a terminal
into a serial port, and then do the following.

1. Find  the major  and minor  numbers of  a working  serial port.   Do not
   configure  the port  for modem  control or  flow control;  use something
   simple like com2l. Make sure you can send data out the port; for example
   see that the command

       date > /dev/com2l

   sends data to the terminal's screen.  The baud rate for the port will be
   whatever is specified for the default in file /etc/default/async -- 9600
   unless you have changed it.

2. Make sure the port is not enabled.

3. Create  a test  kernel around  that you can  modify.  Call  it something
   easily remembered, such as /testcoh.

4. Patch the kernel with the command

       /conf/patch -v /testcoh condev=makedev(major,minor):s

   where major  is the major number  for the serial port,  and minor is its
   minor number.

5. Boot the patched kernel.

With this  change, you will not  be able to control  kernel output with XON
and XOFF, nor  will you seen kernel output from  very early startup (before
the page tables are working) appear on the serial device.

Example

The following  example patches the  kernel to redirect error  messages to a
terminal  device  on a  serial  port,  instead of  displaying  them on  the
console:

    /conf/patch -v /Ikernel_name "condev=makedev(maj, min):s"

where kernel_name names the kernel you  wish to patch, and maj and min are,
respectively,  the major  and minor  device numbers of  the serial  port to
which you wish to redirect messages.

Note that condev is a short integer, so the ``:s'' is essential.  The patch
is made to  the file on disk.  You must  reboot before it can work -- chaos
results if you try to switch console devices in a running kernel.

See Also

commands,
device drivers,
kernel

Notes

It is extremely dangerous to patch the COHERENT kernel.  Almost all changes
that you  may wish to  make the kernel  can be accomplished  more safely by
using  the commands  idtune and  idmkcoh.  For details  on how  to use  the
commands,  see  their  entries  in  the  Lexicon.  Therefore,  do  not  use
/conf/patch to patch the kernel unless you know exactly what you are doing.
Caveat utilitor!

Beginning with  release 4.2 of COHERENT, the symbol  table has been removed
from the  kernel, and is  kept in its  own file.  The  symbol-table file is
named after  its corresponding kernel; for example, the  symbol table for a
kernel  named /coherent  is kept  in  file /coherent.sym.  This complicates
using patch to hot-patch a kernel.  As noted above, you are well advised to
use commands idtune and  idenable to modify your kernel configuration, than
using patch to hot-patch an existing kernel.

© 2012 by Stephen A. Ness