1  \# Author Boris Skegin
 2  \# Issued under the terms of the GPL v2 License or any later version
 3  .TH hm2_pktuart_read "3hm2" "2016-02-26" "LinuxCNC Documentation" "Hostmot2"
 4  .SH NAME
 5  
 6  hm2_pktuart_read \- read data from a Hostmot2 UART buffer
 7  
 8  .SH SYNTAX
 9  .nf
10  .B #include <hostmot2-serial.h>
11  .HP
12  int hm2_pktuart_read(char *name,  unsigned char data[], rtapi_u8 *num_frames, rtapi_u16 *max_frame_length, rtapi_u16 frame_sizes[])
13  
14  .SH DESCRIPTION
15  \fBhm2_pktuart_read\fR reads data from the PktUART "name".
16  "name" is a unique string given to each PktUART during hostmot2 setup. The names of 
17  the available channels are printed to standard output during the driver loading 
18  process and take the form:
19  hm2_<board name>.<board index>.pktuart.<index> For example hm2_5i25.0.pktuart.0
20  
21  This function reads a variable number of PktUART packets from the the specified 
22  channel. It should be used inside a realtime HAL component registered with the 
23  main hostmot2 driver using the function hm2_pktuart_setup in the setup
24  code. 
25  
26  "(*num_frames)*(*max_frame_length)" should be <= sizeof "data", which one tries
27  to estimate or guess before calling the function.
28  If there are more bytes in the buffer than the size of data array is, then
29  RxArraySizeError is returned.
30  
31  Note that the PktUART MaxFrameSize is 1024 bytes as hard-coded in hostmot2.vhd .
32  
33  
34  .SH RETURN VALUE
35  Returns the number of bytes read on success and negative error codes on failure.
36  
37  "num_frames" which pointer is passed by value is set to the number of successfully 
38  datagrams read.
39  
40  Negative error codes are:
41  .TP 
42  .B -1 - low level read/write error
43  .TP
44  .B -EINVAL - any PktUART configuration error per instance
45  .TP
46  .B 
47  .TP
48  .B -HM2_PKTUART_RxStartbitError - Rx mode register error
49  .TP
50  .B -HM2_PKTUART_RxOverrunError - Rx mode register error
51  .TP
52  .B -HM2_PKTUART_RxRCFIFOError - Rx mode register error
53  .TP
54  .B 
55  .TP
56  .B -HM2_PKTUART_RxPacketOverrrunError - Rx count register error
57  .TP
58  .B -HM2_PKTUART_RxPacketStartbitError - Rx count register error
59  .TP
60  .B 
61  .TP
62  .B -HM2_PKTUART_RxPacketSizeZero - the size of the received packet is zero
63  .TP
64  .B -HM2_PKTUART_RxArraySizeError - data array is too small for all the data in the buffer
65  .TP
66  Numeric values of the HM2_PKTUART_ error codes are defined in src/hal/drivers/mesa-hostmot2/pktuart_errno.h .
67  
68  
69  .SH SEE ALSO
70  .TP
71  .B man hm2_pktuart_setup, man hm2_pktuart_send
72  .TP
73  See src/hal/drivers/mesa_pktgyro_test.comp for an example usage.