doc: Add documentation for bootloader_{type,version}

[safe/jmp/linux-2.6] / Documentation / infiniband / user_mad.txt

diff --git a/Documentation/infiniband/user_mad.txt b/Documentation/infiniband/user_mad.txt
index cae0c83..8a36695 100644 (file)
--- a/Documentation/infiniband/user_mad.txt
+++ b/Documentation/infiniband/user_mad.txt
@@ -28,13 +28,37 @@ Creating MAD agents
 
 Receiving MADs
 
-  MADs are received using read().  The buffer passed to read() must be
-  large enough to hold at least one struct ib_user_mad.  For example:
-
-       struct ib_user_mad mad;
-       ret = read(fd, &mad, sizeof mad);
-       if (ret != sizeof mad)
+  MADs are received using read().  The receive side now supports
+  RMPP. The buffer passed to read() must be at least one
+  struct ib_user_mad + 256 bytes. For example:
+
+  If the buffer passed is not large enough to hold the received
+  MAD (RMPP), the errno is set to ENOSPC and the length of the
+  buffer needed is set in mad.length.
+
+  Example for normal MAD (non RMPP) reads:
+       struct ib_user_mad *mad;
+       mad = malloc(sizeof *mad + 256);
+       ret = read(fd, mad, sizeof *mad + 256);
+       if (ret != sizeof mad + 256) {
+               perror("read");
+               free(mad);
+       }
+
+  Example for RMPP reads:
+       struct ib_user_mad *mad;
+       mad = malloc(sizeof *mad + 256);
+       ret = read(fd, mad, sizeof *mad + 256);
+       if (ret == -ENOSPC)) {
+               length = mad.length;
+               free(mad);
+               mad = malloc(sizeof *mad + length);
+               ret = read(fd, mad, sizeof *mad + length);
+       }
+       if (ret < 0) {
                perror("read");
+               free(mad);
+       }
 
   In addition to the actual MAD contents, the other struct ib_user_mad
   fields will be filled in with information on the received MAD.  For
@@ -50,20 +74,45 @@ Sending MADs
 
   MADs are sent using write().  The agent ID for sending should be
   filled into the id field of the MAD, the destination LID should be
-  filled into the lid field, and so on.  For example:
+  filled into the lid field, and so on.  The send side does support
+  RMPP so arbitrary length MAD can be sent. For example:
 
-       struct ib_user_mad mad;
+       struct ib_user_mad *mad;
 
-       /* fill in mad.data */
+       mad = malloc(sizeof *mad + mad_length);
 
-       mad.id  = my_agent;     /* req.id from agent registration */
-       mad.lid = my_dest;      /* in network byte order... */
+       /* fill in mad->data */
+
+       mad->hdr.id  = my_agent;        /* req.id from agent registration */
+       mad->hdr.lid = my_dest;         /* in network byte order... */
        /* etc. */
 
-       ret = write(fd, &mad, sizeof mad);
-       if (ret != sizeof mad)
+       ret = write(fd, &mad, sizeof *mad + mad_length);
+       if (ret != sizeof *mad + mad_length)
                perror("write");
 
+Transaction IDs
+
+  Users of the umad devices can use the lower 32 bits of the
+  transaction ID field (that is, the least significant half of the
+  field in network byte order) in MADs being sent to match
+  request/response pairs.  The upper 32 bits are reserved for use by
+  the kernel and will be overwritten before a MAD is sent.
+
+P_Key Index Handling
+
+  The old ib_umad interface did not allow setting the P_Key index for
+  MADs that are sent and did not provide a way for obtaining the P_Key
+  index of received MADs.  A new layout for struct ib_user_mad_hdr
+  with a pkey_index member has been defined; however, to preserve
+  binary compatibility with older applications, this new layout will
+  not be used unless the IB_USER_MAD_ENABLE_PKEY ioctl is called
+  before a file descriptor is used for anything else.
+
+  In September 2008, the IB_USER_MAD_ABI_VERSION will be incremented
+  to 6, the new layout of struct ib_user_mad_hdr will be used by
+  default, and the IB_USER_MAD_ENABLE_PKEY ioctl will be removed.
+
 Setting IsSM Capability Bit
 
   To set the IsSM capability bit for a port, simply open the
@@ -79,8 +128,8 @@ Setting IsSM Capability Bit
   To create the appropriate character device files automatically with
   udev, a rule like
 
-    KERNEL="umad*", NAME="infiniband/%k"
-    KERNEL="issm*", NAME="infiniband/%k"
+    KERNEL=="umad*", NAME="infiniband/%k"
+    KERNEL=="issm*", NAME="infiniband/%k"
 
   can be used.  This will create device nodes named