211A CyUartWrite DLL Call Questions

[jocac_4016601]

6.4 CyUartWrite

This API writes the data to UART device.

Description

This API writes the data to UART device. User need to initialize the writeBuffer with buffer pointer, number of bytes

to write before invoking the API. On return the transferCount parameter in CY_DATA_BUFFER will contain the

number of bytes written.

Parameters

Parameters          Description

CY_HANDLE           handle Valid device handle

CY_DATA_BUFFER*

writeBuffer         Write buffer details

UINT32 timeout      API timeout value

3.10 CY_DATA_BUFFER

This structure is used to hold data buffer information.

Description

This structure is used by all the data transaction APIs in the library to perform read, write operations. Before using a

variable of this structre users need to initialize various members appropriately.

Data Types

CY_DATA_BUFFER

Members

Members                 Description

UCHAR * buffer;         Pointer to the buffer from where the data is read/written

UINT32 length;          Length of the buffer

UINT32 transferCount;   Number of bytes actually read/written

Questions:

1. UINT32 timeout   This is in what units?  days, years, pico seconds, ??  And what is a typical value?

2. On the write DLL call you expect a pointer to the CY_DATA_BUFFER data structure.  In that structure you want a pointer, in ASCII, of the pointer to the data buffer.  Not sure this makes sense. 

The pointer is an ASCII string?  So, we have and address to an address that hs been converted to ASCII that when converted back from ASCII points to the ASCII string to be sent to the UART?

3. transferCount is bi directional?  On a write I pass it the count "by value" and on the return you don't need to know the address "by reference" to store the byte count?  How does that work?

4. Why didn't you put the timeout value in the data structure with the rest of the stuff?

[SrinathS_16]

Hello,

- The UINT32 timeout parameter is in milli-seconds. The typical value of timeout is 5000 (5 seconds).

- Below is the structure definition from the CyUSBSerial.h file.

typedef struct _CY_DATA_BUFFER {

    UCHAR *buffer;                      /*Pointer to the buffer from where the data is read/written */

    UINT32 length;                      /*Length of the buffer */

    UINT32 transferCount;              /*Number of bytes actually read/written*/

} CY_DATA_BUFFER,*PCY_DATA_BUFFER;

Below is the API usage.

rStatus = CyUartWrite(handle, &cyDatabuffer, 5000);

The CyUartWrite() API expects a pointer to CY_DATA_BUFFER structure type. Hence, the address of the cyDatabuffer structure is passed to the API. The cyDatabuffer structure contains a character pointer that stores the starting address of the array of read/written data. Since, the cyDatabuffer is passed by reference in the API, any change made to the buffer contents inside the API call will be reflected outside too. Please let us know your point of confusion in the API usage.

- Yes, transferCount is bidirectional. transferCount is again a part of the CY_DATA_BUFFER structure which is passed as a reference to the CyUartWrite() API and hence changes inside the API will be reflected outside too.

- The CY_DATA_BUFFER structure groups all the variables that are related to the data transfer. timeout is a parameter associated with the completion of API and not with the data structure. Hence, it is being used as a separate parameter of the API.

Best regards,

Srinath S

[jocac_4016601]

So far, from trial and error,:

UINT32 length;                      /*Length of the buffer */

is not the length of the buffer, it is the number of characters to write.  The API should read:

UINT32 character_count /* the number of characters to write */

/* if the used defines a buffer whose length is less than the characters to send the call will never happen since you can't put 128 characters in a 3 byte length buffer*/

UINT32 transferCount;              /*Number of bytes actually read/written*/

is not bidirectional, it is the count of characters the uart sent or received.  If you ask for 23 bytes to be sent and it doesn't send it, an error flag should be set.  This should be done so that the calling application can't read the error status. */

/* It also seems that transfercount should be transfercount* so that it knows where to store the data, kind of hard to do when sending the data TO the API.*/

[SrinathS_16 · Accepted solution]

Hello,

- CY_DATA_BUFFER.length parameter determines the memory that is to be allocated for the data buffer. As you can see in the USB-Serial SDK example, this value is set to 64, indicating 64 bytes of memory (use of unsigned char type).

- CY_DATA_BUFFER.transferCount parameter indicates the actual number of bytes of data transferred by the API. This need not be passed as a reference since the CY_DATA_BUFFER structure variable itself is passed as a reference to the API. Please view the attached Uart.cpp file that uses the CyUartWrite() API and the associated output as in the below image. It can be seen that the transferCount parameter indicates the number of bytes of data transferred.

Best regards,

Srinath S