1  \# Author Andy Pugh
 2  \# Issued under the terms of the GPL v2 License or any later version
 3  .TH hm2_bspi_setup_chan "3hm2" "2011-05-31" "LinuxCNC Documentation" "Hostmot2"
 4  .SH NAME
 5  
 6  hm2_bspi_setup_chan \- setup a Hostmot2 bspi channel
 7  
 8  .SH SYNTAX
 9  .nf
10  .B #include <hostmot2-serial.h>
11  .HP
12  int hm2_bspi_setup_chan(char *name, int chan, int cs, int bits, float mhz,
13  int delay, int cpol, int cpha, int noclear, int noecho)
14  
15  .SH DESCRIPTION
16  \fBhm2_bspi_setup_chan\fR allows a realtime component to claim and configure
17  a BSPI channel on a previously configured hostmot2 board.
18  
19  .IP name
20  A unique string given to the BSPI channel during hostmot2 setup.
21  The names of the available
22  channels are printed to standard output during the driver loading process and 
23  take the form \fBhm2_\fIboard-name\fB.\fIboard-index\fB.bspi.\fIbspi-index\fR.
24  For example, the first index on the first hm2_5i23 board would be called hm2_5i23.0.bspi.0.
25  
26  .IP chan
27  Channels are numbered 0 to 15.  The value on the chip-select lines is set by cs
28  and need not match the channel number.
29  
30  .IP cs
31  The chip select line(s) to assert when accessing this channel.
32  BSPI supports 4 chip select lines, so the valid range for cs is 
33  0-15.
34  
35  .IP bits
36  sets the bit-length of the SPI packet. The maximum supported length
37  is 64 bits but this will span two read FIFO entries and will need special 
38  handling. (values 32 and below require no special handling)
39  
40  .IP mhz
41  sets the chip communication rate. The maximum value for this is 
42  half the FPGA base frequency, so for example with a 48MHz 5i23 the max SPI 
43  frequency is 24Mhz. Values in excess of the max supported will be silently 
44  rounded down.
45  
46  .IP delay
47  sets the chip select valid delay (in nS)
48  
49  .IP cpha\ and\ cpol
50  Set the clock phase and polarity (according to the device datasheet). 
51  
52  .IP noclear
53  controls whether the frame clear bit is set after the 32 bit buffer 
54  transfer. This parameter should be set to 1 when the frame length is greater 
55  than 32 bits and the next data in the FIFO contains the other bits.
56  
57  .IP noecho
58  Set to 1 for devices which do not return data (such as DACs).
59  
60  .IP samplelate
61  Set to 1 to sample the received SPI data 1/2 SPI clock later than normal.
62  This is useful when high clock rates or isolation cause significant delays from clock to received data.
63  
64  .SH REALTIME CONSIDERATIONS
65  Call only from within user or init/cleanup code, not from relatime tasks.
66  
67  .SH RETURN VALUE
68  Returns 0 on success and \-1 on failure.
69  
70  .SH SEE ALSO
71  \fBhm2_allocate_bspi_tram(3hm2)\fR,
72  \fBhm2_bspi_set_read_function(3hm2)\fR,
73  \fBhm2_bspi_set_write_function(3hm2)\fR,
74  \fBhm2_bspi_write_chan(3hm2)\fR,
75  \fBhm2_tram_add_bspi_frame(3hm2)\fR,
76  See src/hal/drivers mesa_7i65.comp for an example usage.