add some bits and pieces of documentation

git-svn-id: https://svn.openpcd.org:2342/trunk@272 6dc7ffe9-61d6-0310-9af1-9938baff3ed1
This commit is contained in:
laforge 2006-10-16 16:37:59 +00:00
parent 1d505fbf35
commit ea1423e7c9
6 changed files with 698 additions and 0 deletions

0
doc/common-hardware.xml Normal file
View File

View File

@ -0,0 +1,44 @@
<section>Device Firmware Upgrade</section>
<para>
Since the device firmware is Free Software licensed under GNU GPL,
we encourage and enable users to enhance and adapt the firmware according to
their needs. In order to really benefit from this freedom, we have embedded
an easy mechanism to update the device firmware without any special tools /
adapters / cables / programmers or the like.
</para>
<para>
The OpenPICC implements the USB Device Firmware Upgrade speficication,
as released by the USB Association. Using this protocol, it is possible to
update the device firmware via special-purpose USB control requests.
</para>
<para>
A software implementation of the USB DFU host side was already available for
Linux under the name of "dfu-programmer". However, this program did not
implement the true standard, but some vendor-specific dialect of it.
Therefore, dfu-programmer has been enhanced to have full native support
for standard DFU.
</para>
</section> <!-- DFU -->
<section>Emergency Firmware Flash</section>
<para>
The AT91SAM7 microcontroller used in the device contains a USB flash loader
(called SAM-BA) in read-only memory. By setting a jumper on the PCB and
powering up the device for 20 seconds, this loader can be copied into the
first 8kb of flash memory, overwriting the existing content.
</para>
<para>
So if the DFU loader has become inoperable, e.g. because of bugs in
experimental DFU modifications, SAM-BA can be employed to rescue the system.
</para>
<para>
Apart from proprietary Windows software by Atmel, there's the Free Software
sam7utils project which provides a host program called 'sam7' to interface
with SAM-BA and facilitate a full-flash rewrite with DFU and the device firmware.
</para>
<para>
For more information on the flash procedure, we refer to the AT91SAM7 product
documentation, as well as the sam7utils documentation.
</para>
</section> <!-- SAM-BA -->

View File

@ -0,0 +1,17 @@
<section>
<title>Target Software</title>
<para>
The software doesn't use any operating system. Everything is implemented from
scratch. Some of the API's (e.g. timer API) are modelled after the
corresponding Linux kernel API's. However, this does not imply that any of the
actual implementation is shared. The reason for matching the Linux API's is
merely because they are well-understood and there's lots of example code using
them.
</para>
<para>
The SAM7 firmware is compiled using GNU GCC 4.0.2 for ARM. It uses GNU Make for
processing the Makefiles. All development of the system happened on Linux,
therefore your milage of compiling it on Windows might vary, but should
theoretically work.
</para>

190
doc/common-usbproto.xml Normal file
View File

@ -0,0 +1,190 @@
<section>
<title>USB Protocol</title>
<para>
The USB protocol is completely non-standard. Since OpenPICC is a very
special-purpose device, it's obvious that no standard USB protocol will be
applicable. However, our vendor-specific protocol is completely open and
documented to allow for development of interoperable applications.
</para>
<section>
<Title>USB Endpoints</title>
<para>
Since the SAM7 hardware only provides four USB endpoints, we have to use them
according to their endpoint type, rather than to their function within the
protocol. We have to overload and (de)multiplex within one endpoint quite a
bit.
</para>
<para>
EP0 - Control Endpoint
EP1 - Bulk Out endpoint (host -> device)
EP2 - Bulik In endpoint (device -> host)
EP3 - Interrupt In endpoint (device -> host)
</para>
<para>
The control endpoint behaves according to the USB specification. It only
takes care of usb configuration and management. No application data is
transferred over it.
</para>
</section> <!-- USB Endpoints -->
<section>
<title>USB packets, transfers</title>
<para>
In order to understand this devices' USB prootocol, some basics about any
communication with USB endpoints need to be known.
</para>
<para>
USB endpoints exchange a stream of data by means of USB transfers. Every
transfer is conveyed as multiple transaction. Every transaction transports
multiple USB packets. The Endpoint buffer size of the SAM7 usb device
controller is 64bytes for EP1, EP2 and EP3. Therefore, a single packet can be
up to 64 bytes in size. As soon as a packet smaller than the endpoint size
(64byte) is received, the end of that particular USB transfer is detected.
If the transfer size is an integral size of the endpoint size, a zero-length-packet (ZLP) is sent to explicitly signal the end of the transfer.
</para>
<para>
The buffer management inside the SAM7 firmware can deal with USB transfers of
up to 2048 bytes in size. To optimize memory efficiency, all buffers are
statically pre-allocated, and the majority of USB buffers is only 64bytes in
size. This way, the memory consumption for small transfers (such as register read/write transfers) can be kept low.
</para>
<para>
Large transfers (&gt; 64 bytes, but &let; 2024 bytes) should be used only
when they are absolutely required.
</para>
</section> <!-- USB packets, transfers -->
<section>
<title>Host software interaction with USB Endpoints</title>
<para>
Any host software operating the USB device should take into consideration
that memory is a scarce resource on the SAM7, especially for
applications with relatively high speed compared to the USB 1.1 full speed bandwith), such as higher-bitrate 847kHz ISO14443 communication.
</para>
<para>
Therefore it is important to serve device requests on the BULK IN and
INTERRUPT IN endpoints as soon as possible. In most cases, the application
will simply keep those two pipes open all the time, by re-submitting an USB
request block as soon as the previous one at that endpiont has completed.
</para>
<para>
The BULK OUT endpoint will obviously only be filled with requests from the
host software when there are any such requests.
</para>
<para>
On the highest level of the protocol, there are three different classes of device requests:
</para>
<para>
1. uni-directional without high-level acknowledgement, such as a register
write without explicit request for a response. This means that the host
software will only send a single BULK OUT transfer. This transfer is
acknowledged inherently by the USB protocol, and the host software can be sure
that the transfer was correctly received by the device.
</para>
<para>
2. bi-directional with a single response, such as a register read. This means
that the host sends a single BULK OUT transfer, to which the device replies
with a single BULK IN transfer.
</para>
<para>
3. bi-directional with multiple responses. This means that even though the
host only sends a single BULK OUT transfer, there will be multiple BULK IN
transfers in response.
</para>
</section> <!-- Host software interaction -->
<section>
<title>The usb transfer header</title>
<para>
Application data transferred over EP1, EP2 and EP3 is prefixed with a
four-byte header, 'struct openpcd_hdr'.
</para>
<para>
The first byte is the command byte. The high nibble of the command byte
specifies the command class, whereas the the low nibble selects the particular
command within a given class.
</para>
<para>
The second byte specifies flags. There are currently two flags:
</para>
<para>
The RESPOND flag signifies that the sender of this transfer explicitly
requests a response back from the other side.
</para>
<para>
The ERROR flag signifies that this transfer indicates some error
</para>
<para>
The MULTIPLE flag signifies that this is part of a response that consists of
multiple transfers.
</para>
<para>
The LAST flag signifies that the current transfer is the last transfer
of a multiple-transfer response.
</para>
<para>
The third byte is called 'register' for historical purpose. It should
actually rather be called address or index. Its significance differs
according to the actual command that is being performed.
</para>
<para>
The fourth byte is called 'val' for 'value'. Again, its purpose is command
specific. In case of e.g. a register write, it is the value to be written
into the register.
</para>
</section> <!-- USB Transfer Header -->
<section>
<title>The individual USB protocol commands</title>
<section>
<title>Generic USB commands: CMD_CLS_GENERIC</title>
<section>
<title>CMD_GET_VERSION</title>
<para>
This command is used to obtain the version number of the USB device. This
might be used to differentiate different hardware revisions by the host software.
</para>
<para>
The response to this command contains the version number in the
variable-length 'data' section of the transfer.
</para>
</section>
<section>
<title>CMD_SET_LED</title>
<para>
Using this command, the host software can control the LED's present in the
OpenPICC. The LED can be specified in the 'reg' section of the header.
Currently there are two LED's, LED 1 (green) and LED 2 (red). The 'val'
header field controls whether the LED should be switched on (1) or off (0).
</para>
</section>
<section>
<title>CMD_GET_SERIAL</title>
<para>
This command is used to obtain the serial number of the OpenPICC device.
The serial number is returned in the 'data' section of the response transfer.
</para>
</section>
</section> <!-- Generic USB commands -->
<section>
<title>USB Testing commands</title>
<section>
<title>CMD_USBTEST_IN</title>
<para>
</para>
</section>
<section>
<title>CMD_USBTEST_OUT</title>
<para>
</para>
</section>
</section> <!-- USB testing commands -->

172
doc/openpcd.xml Normal file
View File

@ -0,0 +1,172 @@
<?xml vesion='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.3//EN' 'http://www.docbook.org/xml/4.3/docbook.dtd'>
<article id="openpcd-reference">
<articleinfo>
<title>OpenPCD - A 13.56MHz RFID reader</title>
<authorgroup>
<author>
<personname>
<first>Harald</first>
<surname>Welte</surname>
</personname>
<email>hwelte@hmw-consulting.de</email>
</author>
<author>
<personname>
<first>Milosch</first>
<surname>Meriac</surname>
</personname>
<email>meriac@bitmanufaktur.de</email>
</author>
</authorgroup>
<copyright>
<year>2006</year>
<holder>Harald Welte &lt;hwelte@hmw-consultin.de&gt; </holder>
</copyright>
<date>Oct 12, 2006</date>
<edition>1</edition>
<releaseinfo>
$Revision: 1.0 $
</releaseinfo>
<abstract>
<para>
This is the reference documentation for the OpenPCD RFID
reader.
</para>
<para>
</para>
</abstract>
</articleinfo>
<section>
<title>Introduction</title>
<para>
The OpenPCD project is about desinging and building both hardware and software
for a user-programmable reader (proximity coupling device, PCD) of the ISO
14443 A+B (and later ISO15693) RFID protocols.
</para>
<para>
The hardware is based on the Atmel AT91SAM7S128 microcontroller, featuring a
48MHz, 32bit ARM7TDMI core with many integrated peripherals, such as USB
device, SSC, ADC, 128kByte Flash, 32kByte SRAM, ...
</para>
<para>
Next to the AT91SAM7, there is the Pilips CL RC 632 RFID reader ASIC. It
is attached via SPI (Serial Peripheral Interface) to the AT91SAM7.
</para>
<para>
The SAM7 attaches to a host PC using a USB 1.1 interface. The SAM7 firmware
implements various forms of interface between the RC632 and the host PC.
There are multiple firmware images available, some of them acting as a dumb
transceiver, while others implement the full ISO 14443 protocol suite inside
the SAM7 firmware.
</para>
<para>
All device firmware and host software source code is released under GNU General
Public License. The hardware design (schematics, PCB) is released under
"Creative Commons share-alike attribution" License.
</para>
</section> <!-- Introduction -->
<section>
<title>Hardware</title>
<para>
FIXME: to be filled by milosch
</para>
<xi:xinclude href="common-hardware.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</section>
<section>
<title>Software</title>
<xi:include href="common-usbproto.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<section>
<title>PICC specific commands</title>
<section>
<title>CMD_PICC_REG_WRITE</title>
<para>
Using this command, a given OpenPICC register can be written to.
</para>
</section>
<section>
<title>CMD_PICC_REG_READ</title>
<para>
Using this command, a given OpenPICC register can be read.
</para>
</section>
</section> <!-- PICC specific commands -->
<section>
<title>ADC specific commands</title>
</section> <!-- ADC specific commands -->
<section>
<title>GPIO IRQ commands</title>
<para>
Using these commands, the host software can request a USB interrupt
transfer to be sent once a given GPIO pin changes its level
</para>
</section> <!-- GPIO IRQ commands -->
</section> <!-- USB protocol commands -->
</section> <!-- USB protocol -->
<xi:include href="common-targetsoftware.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<section>
<title>The main_dumbreader firmware</title>
<para>
The main_dumbreader firmware implements a very basic PCD/VCD firmware, where
the USB device only implements an access layer to the RC632 registers and
FIFO. All protocol and application logic has to be implemented on the host
PC.
</para>
<para>
This provides the greatest flexibility to the host software, since it can
easily alter the behaviour of the device completely. Host development is
easier than cross-compilation and remote debugging required for firmware
development.
</para>
<para>
Therefore, this firmware is the choice for most security researchers, since
all timing and every bit of the protocol can be dealt with on the host.
</para>
</section> <!-- main_dumbreader -->
<section>
<title>The main_librfid firmware</title>
<para>
This firmware is called 'main_librfid' because it contains a full copy of the
librfid library, cross compiled for ARM. The librfid library implements
various 13.56MHz RFID protocols from layer 2 to layer 4 and higher, including
ISO 14443, ISO 15693, Mifare classic, Mifare ultralight and others.
</para>
<para>
The USB protocol of this firmware has not yet been fully speicified, also
there currently is no finished host software that could interface this
firmware yet. Stay tuned for upcoming news on this subject.
</para>
</section> <!-- Target Software -->
<section>
<title>Host Software</title>
<para>
TBD
</para>
<xi:include href="common-hostsoftware.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</section> <!-- Host Software -->
</section> <!-- Software -->
</article>

275
doc/openpicc.xml Normal file
View File

@ -0,0 +1,275 @@
<?xml vesion='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.3//EN' 'http://www.docbook.org/xml/4.3/docbookx.dtd'>
<article id="openpicc-reference">
<articleinfo>
<title>OpenPICC - A ISO 14443 A+B PICC RFID simulator</title>
<authorgroup>
<author>
<personname>
<first>Harald</first>
<surname>Welte</surname>
</personname>
<email>hwelte@hmw-consulting.de</email>
</author>
<author>
<personname>
<first>Milosch</first>
<surname>Meriac</surname>
</personname>
<email>meriac@bitmanufaktur.de</email>
</author>
</authorgroup>
<copyright>
<year>2006</year>
<holder>Harald Welte &lt;hwelte@hmw-consultin.de&gt; </holder>
</copyright>
<date>Oct 12, 2006</date>
<edition>1</edition>
<releaseinfo>
$Revision: 1.0 $
</releaseinfo>
<abstract>
<para>
This is the reference documentation for the OpenPICC RFID
simulator for ISO 14443.
</para>
<para>
</para>
</abstract>
</articleinfo>
<section>
<title>Introduction</title>
<para>
The OpenPICC project is about desinging and building both hardware and software
for a user-programmable simulator of the PICC (Transponder) side of the ISO
14443 A+B (and later ISO15693) RFID protocols.
</para>
<para>
The hardware is based on the Atmel AT91SAM7S256 microcontroller, featuring a
48MHz, 32bit ARM7TDMI core with many integrated peripherals, such as USB
device, SSC, ADC, 256kByte Flash, 64kByte SRAM, ...
</para>
<para>
The SAM7 attaches to a host PC using a USB 1.1 interface. The SAM7 firmware
implements encoding/decoding, the auxiliary hardware modulation/demodulation.
The host PC therefore transmits and sends raw ISO 14443-3 frames, and
implements higher protocol levels such as ISO 14443-4 or even a Smartcard OS
simulation according to 7816-4.
</para>
<para>
All device firmware and host software source code is released under GNU General
Public License. The hardware design (schematics, PCB) is released under
"Creative Commons share-alike attribution" License.
</para>
</section> <!-- Introduction -->
<section>
<title>Hardware</title>
<para>
FIXME: to be filled by milosch
</para>
<xi:xinclude href="common-hardware.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</section>
<section>
<title>Software</title>
<xi:include href="common-usbproto.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<section>
<title>PICC specific commands</title>
<section>
<title>CMD_PICC_REG_WRITE</title>
<para>
Using this command, a given OpenPICC register can be written to.
</para>
</section>
<section>
<title>CMD_PICC_REG_READ</title>
<para>
Using this command, a given OpenPICC register can be read.
</para>
</section>
</section> <!-- PICC specific commands -->
<section>
<title>ADC specific commands</title>
</section> <!-- ADC specific commands -->
<section>
<title>GPIO IRQ commands</title>
<para>
Using these commands, the host software can request a USB interrupt
transfer to be sent once a given GPIO pin changes its level
</para>
</section> <!-- GPIO IRQ commands -->
</section> <!-- USB protocol commands -->
</section> <!-- USB protocol -->
<xi:include href="common-targetsoftware.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<section> <!-- Target Software -->
<section>
<title>The OpenPICC register set</title>
<para>
Most of the behaviour of the OpenPICC simulator can be controlled using the
OpenPICC register set. This is not really a register set that corresponds to
hardware registers. The registers are actually implemented in software, and
act as global variables present in SAM7 RAM, which influence the OpenPICC
firmware operation.
</para>
<para>
This interface was chosen because it is something that software developers
(more specificially: driver developers) are used to.
</para>
<section>
<title>OPICC_REG_14443A_UIDLEN</title>
<para>
This register defines the length of the 14443-A UID or 14443-B PUPI. The
length value is specified in bytes.
</para>
<para>
Permitted values for 14443-A are: 4, 7 or 10.
</para>
<para>
Permitted values for 14443-B are: 4.
</para>
</section>
<section>
<title>OPICC_REG_14443A_FDT0</title>
<para>
ISO 14443A synchronous frame delay time in case last bit of PCD->PICC frame
was 0. According to the ISO 14443-3 specification, this has to be 1236.
</para>
</section>
<section>
<title>OPICC_REG_14443A_FDT1</title>
<para>
ISO 14443-3A synchronous frame delay time in case last bit of PCD->PICC frame
was 1. According to the ISO 14443-3A specification, this has to be 1172.
</para>
</section>
<section>
<title>OPICC_REG_14443A_ATQA</title>
<para>
The ATQA register contains a template for the 14443-3A ATQA. Only the lowest
five bits (0...4, bit frame anti-collision) and the bits 8..11 are used, the
rest will be masked and or specified by the OpenPICC firmware.
</para>
</section>
<section>
<title>OPICC_REG_14443A_STATE</title>
<para>
The PICC state according to ISO 14443-3A. Possible values are:
ISO14443A_ST_POWEROFF, ISO14443A_ST_IDLE, ISO14443A_ST_READY,
ISO14443A_ST_ACTIVE, ISO14443A_ST_HALT, ISO14443A_ST_READY2,
ISO14443A_ST_ACTIVE2.
</para>
</section>
<section>
<title>OPICC_REG_RX_CLK_DIV</title>
<para>
The receive clock divider register. This specifies the relationship
between SSC sample clock and re-generated carrier clock.
</para>
<para>
For ISO14443-A at 106kBp/s, this is usually set to 32 in order to produce
a four-times oversampled signal. Values for higher baudrtes are TBD.
</para>
</section>
<section>
<title>OPICC_REG_RX_CLK_PHASE</title>
<para>
This register defines the phase of the receive sample clock. Values
are given relative to the rx sample clock synchronization pulse caused
by the first falling edge within the frame.
</para>
</section>
<section>
<title>OPICC_REG_RX_CONTROL</title>
<para>
The receive control register controls the OpenPICC receive path
</para>
</section>
<section>
<title>OPICC_REG_TX_CLK_DIV</title>
<para>
The transmit clock divider register determines the sample clock rate of the SSC
transmit path. Since 14443-A and -B use a 847.5kHz subcarrier, the sample
rate will have to be configured to 1.695MHz, and thus a clock divider of 8
programmed into this register.
</para>
</section>
<section>
<title>OPICC_REG_TX_CLK_PHASE</title>
<para>
The transmit clock phase register defines the phase relationship between carrier clock and SSC Tx clock.
</para>
</section>
<section>
<title>OPICC_REG_TX_CONTROL</title>
<para>
The transmit control register is split in two sections: Lower nibble switches between BPSK (1) and MANCHESTER (2), whereas the higher nibble is used to configure the modulation depth (0..3).
</para>
</section>
<section>
<title>OPICC_REG_RX_COMP_LEVEL</title>
<para>
The demodulated Rx signal is digitized using a comparator. Using this
register, the comparator reference value can be specified. The value is
conveyed as a 7bit value in the range of 0..127.
</para>
</section>
<section>
<title>OPICC_SREG_14443A_UID</title>
<para>
This string register contains the 14443-3A UID or 14443-3B PUPI.
</para>
</section>
</section> <!-- The OpenPICC register set -->
</section> <!-- Target Software -->
</section>
</section> <!-- The OpenPICC register set -->
</section> <!-- Target Software -->
<section>
<title>Host Software</title>
<para>
TBD
</para>
<xi:include href="common-hostsoftware.xml" parse="xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</section> <!-- Host Software -->
</section> <!-- Software -->
</article>