Sort sections in various manual pages.
[dragonfly.git] / share / man / man4 / cmx.4
1 .\"
2 .\" Copyright (c) 2006-2007 Daniel Roethlisberger <daniel@roe.ch>
3 .\" All rights reserved.
4 .\" 
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice unmodified, this list of conditions, and the following
10 .\"    disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .\" $FreeBSD: src/share/man/man4/cmx.4,v 1.2 2008/03/06 08:47:16 rink Exp $
28 .\" $DragonFly: src/share/man/man4/cmx.4,v 1.2 2008/04/29 11:59:08 swildner Exp $
29 .\"
30 .Dd July 7, 2007
31 .Dt CMX 4
32 .Os
33 .Sh NAME
34 .Nm cmx
35 .Nd Omnikey CardMan 4040 smartcard reader device driver
36 .Sh SYNOPSIS
37 .Cd device cmx
38 .Sh DESCRIPTION
39 The
40 .Nm
41 driver provides support for the PCCARD based
42 .Em Omnikey CardMan 4040
43 smartcard reader.
44 The driver provides a character device special file based
45 .Em Chip/Smart Card Interface Devices (CCID)
46 interface.  The driver implements what the vendor calls the
47 .Em Synchronious API
48 onto the smartcard reader device.
49 .Pp
50 Reading and writing is synchronious, meaning that a call to
51 .Xr write 2
52 directly corresponds to a complete CCID command sent to the
53 device, while the following
54 .Xr read 2
55 will return the complete answer from the reader.  There is no
56 support for partial reads or writes.  There is no upper limit on
57 CCID request or response sizes, but the complete CCID request
58 must be sent to the driver in
59 .Xr write 2
60 and the complete CCID response must fit into the buffer
61 supplied to
62 .Xr read 2 .
63 .Pp
64 Non-blocking I/O,
65 .Xr select 2
66 and
67 .Xr poll 2
68 are supported and work as expected.  An open file descriptor
69 will always be ready for writing, but only ready for reading
70 if the device indicates that it has data available.
71 .Sh FILES
72 .Bl -tag -width /dev/cmxn -compact
73 .It Pa /dev/cmx\fBn\fP
74 Character device special file.
75 .\".It Pa /usr/ports/security/openct
76 .\"OpenCT, a userspace smartcard daemon containing a
77 .\".Em CCID
78 .\"driver which directly supports
79 .\".Nm
80 .\"devices.
81 .\".It Pa /usr/ports/devel/pcsc-lite
82 .\"PC/SC-Lite, a userspace smartcard daemon.
83 .\".It Pa /usr/ports/devel/libccid
84 .\"libccid, a generic
85 .\".Em CCID
86 .\"driver for use by PC/SC-Lite to interface to
87 .\".Nm
88 .\"devices.
89 .El
90 .Sh COMPATIBILITY
91 Userland smartcard code written for the vendor's Linux drivers
92 should work with the
93 .Nm
94 driver without modification.
95 .Sh SEE ALSO
96 .Xr pccard 4
97 .Sh HISTORY
98 The
99 .Nm
100 driver first appeared in
101 .Fx 7.1
102 and was imported into
103 .Dx 1.13 .
104 .Sh AUTHORS
105 .An -nosplit
106 The
107 .Nm
108 driver was written by
109 .An Daniel Roethlisberger Aq daniel@roe.ch ,
110 originally based on the Linux driver v1.1.0 by
111 .An Omnikey GmbH Aq www.omnikey.com .
112 Early testing and bug fixes by
113 .An Marcin Cieslak Aq saper@system.pl .
114 .Sh BUGS
115 .An -nosplit
116 The way the
117 .Nm
118 driver talks to the CardMan 4040 is a bit rough.  Due to the
119 complete lack of hardware documentation other than vendor drivers
120 for other operating systems, the gory details of the device's
121 I/O registers are not understood very well.  There may be error
122 conditions which can only be solved by physically reinserting the
123 reader.