Merge pull request #901 from sirop/PktUART

PktUART driver for MESA

man/man3/hm2_pktuart_read.3hm2

@@ -0,0 +1,69 @@
+\# Author Boris Skegin
+\# Issued under the terms of the GPL v2 License or any later version
+.TH hm2_pktuart_read "3hm2" "2016-02-26" "LinuxCNC Documentation" "Hostmot2"
+.SH NAME
+
+hm2_pktuart_read \- read data from a Hostmot2 UART buffer
+
+.SH SYNTAX
+.HP
+int hm2_pktuart_read(char *name,  unsigned char data[], u8 *num_frames, u16 *max_frame_length, u16 frame_sizes[])
+
+.SH DESCRIPTION
+\fBhm2_pktuart_read\fR reads data from the PktUART "name".
+"name" is a unique string given to each PktUART during hostmot2 setup. The names of 
+the available channels are printed to standard output during the driver loading 
+process and take the form:
+hm2_<board name>.<board index>.pktuart.<index> For example hm2_5i25.0.pktuart.0
+
+This function reads a variable number of PktUART packets from the the specified 
+channel. It should be used inside a realtime HAL component registered with the 
+main hostmot2 driver using the function hm2_pktuart_setup in the setup
+code. 
+
+"(*num_frames)*(*max_frame_length)" should be <= sizeof "data", which one tries
+to estimate or guess before calling the function.
+If there are more bytes in the buffer than the size of data array is, then
+RxArraySizeError is returned.
+
+Note that the PktUART MaxFrameSize is 1024 bytes as hard-coded in hostmot2.vhd .
+
+
+.SH RETURN VALUE
+Returns the number of bytes read on success and negative error codes on failure.
+
+"num_frames" which pointer is passed by value is set to the number of successfully 
+datagrams read.
+
+Negative error codes are:
+.TP 
+.B -1 - low level read/write error
+.TP
+.B -EINVAL - any PktUART configuration error per instance
+.TP
+.B 
+.TP
+.B  -110 - RxStartbitError, Rx mode register error
+.TP
+.B  -111 - RxOverrunError, Rx mode register error
+.TP
+.B  -114 - RxRCFIFOError, Rx mode register error
+.TP
+.B 
+.TP
+.B  -1115 - RxPacketOverrrunError, Rx count register error
+.TP
+.B  -1114 - RxPacketStartbitError, Rx count register error
+.TP
+.B 
+.TP
+.B  -1120 - RxPacketSizeZero, the size of the received packet is zero
+.TP
+.B  -1140 - RxArraySizeError, data array is too small for all the data in the buffer
+
+
+.SH SEE ALSO
+.TP
+.B man hm2_pktuart_setup, man hm2_pktuart_send
+.TP
+See src/hal/components/mesa_pktgyro_test.comp for an example usage.

man/man3/hm2_pktuart_send.3hm2

@@ -0,0 +1,49 @@
+\# Author Boris Skegin
+\# Issued under the terms of the GPL v2 License or any later version
+.TH hm2_pktuart_send "3hm2" "2016-02-29" "LinuxCNC Documentation" "Hostmot2"
+.SH NAME
+
+hm2_pktuart_send \- write data to a Hostmot2 PktUART
+
+.SH SYNTAX
+.HP
+int hm2_uart_send(char *name,  unsigned char data[], u8 *num_frames, u16 frame_sizes[])
+
+.SH DESCRIPTION
+\fBhm2_pktuart_send\fR writes "num_frames"  of data to the PktUART "name" from the 
+buffer "data" with frame sizes preset in "frame_sizes[]" array.
+"frame_sizes[]" array should not have more than 16 elements as this is the highest
+number of frames that can be sent out in the so called "burst mode".
+
+Note that the PktUART MaxFrameSize is 1024 bytes as hard-coded in hostmot2.vhd .
+
+"name" is a unique string given to each PktUART during hostmot2 setup. The names of 
+the available channels are printed to standard output during the driver loading 
+process and take the form:                                    
+hm2_<board name>.<board index>.pktuart.<index> For example hm2_5i25.0.pktuart.0 .
+
+This function sends a variable number of PktUART packets (less or equal 16) from 
+the the specified channel. It should be used inside a realtime HAL component
+registered with the main hostmot2 driver using the function hm2_pktuart_setup 
+in the setup code. 
+
+.SH RETURN VALUE
+Returns the number of bytes sent on success and negative error codes on failure.
+
+"num_frames" which pointer is passed by value is set to the number of successfully 
+datagrams sent out.
+
+Negative error codes are:
+.TP 
+.B -1 - low level read/write error
+.TP
+.B -EINVAL - any PktUART configuration error per instance
+.TP
+.B -214  - TxSCFIFOError, Tx Send Count FIFO Error
+
+
+
+.SH SEE ALSO
+.B man hm2_pktuart_setup, man hm2_pktuart_read
+.TP
+See src/hal/components/mesa_pktgyro_test.comp for an example usage.

man/man3/hm2_pktuart_setup.3hm2

@@ -0,0 +1,102 @@
+\# Author Boris Skegin
+\# Issued under the terms of the GPL v2 License or any later version
+.TH hm2_pktuart_setup "3hm2" "2016-02-29" "LinuxCNC Documentation" "Hostmot2"
+.SH NAME
+
+hm2_pktuart_setup \- setup a Hostmot2 PktUART instance
+.SH SYNTAX
+.HP
+int hm2_pktuart_setup(char *name, int bitrate, s32 tx_mode, s32 rx_mode, int txclear, int rxclear)
+
+.SH DESCRIPTION
+\fBhm2_pktuart_setup\fR Setup the bitrate for the PktUART named "name".
+"name" is a unique string given to each PktUART during hostmot2 
+setup. The names of the available UARTs are printed to standard output during 
+the driver loading process and take the form:
+hm2_<board name>.<board index>.pktuart.<index> For example hm2_5i25.0.pktuart.0 .
+
+Hostmot2 UARTs are good to about 10 Mb/sec, but higher data rates (with any UART)
+trade speed for susceptibility to impulse noise.
+
+
+The PktUART function allows different RX and TX bitrates, but that is not currently
+supported by this driver.
+
+
+tx_mode is bit mask defined in the Hostmot2 regmap:
+.TP
+.B Bit  21	       FrameBuffer Has Data
+.TP
+.B Bits 20..16     Frames to send
+.TP
+.B Bits 15..8      InterFrame delay in bit times
+.TP
+.B Bit  7	       Send busy, Transmit Logic active
+.TP
+.B Bit  6	       Drive Enable bit (enables external RS-422/485 Driver when set)
+.TP
+.B Bit  5	       Drive enable Auto (Automatic external drive enable)
+.TP
+.B Bit  4	       SCFIFO Error
+.TP
+.B Bits 3..0       Drive enable delay (delay from asserting drive enable 
+     	           to start of data transmit. In CLock Low periods 
+
+
+
+
+.TP       
+rx_mode is bit mask defined in the Hostmot2 regmap:
+.TP
+.B Bit  21	       FrameBuffer has data                                                        	
+.TP
+.B Bits 20..16     Frames received                                                               
+.TP
+.B Bits 15..8      InterFrame delay in bit times                                    
+.TP
+.B Bit  7	       Rx Logic active
+.TP
+.B Bit  6	       RXMask
+.TP
+.B Bit  5          Unused
+.TP
+.B Bit  4	       RCFIFO Error
+.TP
+.B Bit  3	       RXEnable (must be set to receive packets) 
+.TP
+.B Bit  2	       RXMask Enable (enables input data masking when transmitting)
+.TP
+.B Bit  1	       Overrun error (no stop bit when expected) (sticky)
+.TP
+.B Bit  0	       False Start bit error (sticky)
+
+.PP
+rx_mode and tx_mode registers are currently write-only.
+One can get the instance number of a PktUART instance
+with the help of hm2_get_pktuart function in order
+to read and write to Rx and Tx registers.
+
+.PP
+To write only to the tx_mode DriveEnable bit call this function with the bitrate
+unchanged and -1 as the rx_mode
+To change bitrate without altering mode settings send -1 to both modes. 
+.PP
+txclear==1 aborts any sends in process, clears the data FIFO and 
+clears the send count FIFO.
+.PP
+rxclear==1  aborts any receives in process, clears the data FIFO and 
+clears the receive count FIFO.
+.PP
+txclear!=1 or rxclear!=1 lets the corresponding registers unchanged.
+
+.SH RETURN VALUE
+Returns 0 on success and -1 or -EINVAL on failure. 
+
+.SH SEE ALSO
+.B man hm2_pktuart_send, man hm2_pktuart_read
+.TP
+See src/hal/components/mesa_pktgyro_test.comp for an example usage. 
+
+.SH FUTURE DEVELOPMENT
+This function is subject to change as digital filters will be added on the Rx UART,
+and bit rate register will gain a 12 bit field for the input filter constant.

src/Makefile

@@ -1345,8 +1345,9 @@ hostmot2-objs +=			  \
     hal/drivers/mesa-hostmot2/tp_pwmgen.o \
 	hal/drivers/mesa-hostmot2/sserial.o   \
     hal/drivers/mesa-hostmot2/stepgen.o   \
-	hal/drivers/mesa-hostmot2/bspi.o	  \
-	hal/drivers/mesa-hostmot2/uart.o	  \
+    hal/drivers/mesa-hostmot2/bspi.o  \
+    hal/drivers/mesa-hostmot2/uart.o  \
+    hal/drivers/mesa-hostmot2/pktuart.o  \
     hal/drivers/mesa-hostmot2/watchdog.o  \
     hal/drivers/mesa-hostmot2/pins.o	  \
     hal/drivers/mesa-hostmot2/dpll.o  \