This section describes the M2MB APIs to perform various SPI master operations. More...

#define	M2MB_SPI_CLKPOL_IDLE_LOW 0

#define	M2MB_SPI_CLKPOL_IDLE_HIGH 1

#define	M2MB_SPI_CLKPHASE_RISING_EDGE 0

#define	M2MB_SPI_CLKPHASE_FALLING_EDGE 1

#define	M2MB_SPI_BITS_PER_WORD_8 8

#define	M2MB_SPI_BAUD_RATE_10MHZ 10000000

enum	M2MB_SPI_IOCTL_REQUEST { M2MB_SPI_IOCTL_SET_CFG = 0, M2MB_SPI_IOCTL_GET_CFG, M2MB_SPI_IOCTL_SET_SHIFT_MODE, M2MB_SPI_IOCTL_GET_SHIFT_MODE, M2MB_SPI_IOCTL_SET_CS_POLARITY, M2MB_SPI_IOCTL_GET_CS_POLARITY, M2MB_SPI_IOCTL_SET_CS_MODE, M2MB_SPI_IOCTL_GET_CS_MODE, M2MB_SPI_IOCTL_SET_BYTE_ORDER, M2MB_SPI_IOCTL_GET_BYTE_ORDER, M2MB_SPI_IOCTL_SET_CALLBACK_FN, M2MB_SPI_IOCTL_GET_CALLBACK_FN, M2MB_SPI_IOCTL_SET_CALLBACK_CTXT, M2MB_SPI_IOCTL_GET_CALLBACK_CTXT, M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ, M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ, M2MB_SPI_IOCTL_SET_BITS_PER_WORD, M2MB_SPI_IOCTL_GET_BITS_PER_WORD, M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES, M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES, M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES, M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES, M2MB_SPI_IOCTL_SET_LOOPBACK_MODE, M2MB_SPI_IOCTL_GET_LOOPBACK_MODE, M2MB_SPI_IOCTL_GET_WEITE_COMPLETE, M2MB_SPI_IOCTL_NOF_REQ, M2MB_SPI_IOCTL_SET_CFG = 0, M2MB_SPI_IOCTL_GET_CFG, M2MB_SPI_IOCTL_SET_SHIFT_MODE, M2MB_SPI_IOCTL_GET_SHIFT_MODE, M2MB_SPI_IOCTL_SET_CS_POLARITY, M2MB_SPI_IOCTL_GET_CS_POLARITY, M2MB_SPI_IOCTL_SET_CS_MODE, M2MB_SPI_IOCTL_GET_CS_MODE, M2MB_SPI_IOCTL_SET_BYTE_ORDER, M2MB_SPI_IOCTL_GET_BYTE_ORDER, M2MB_SPI_IOCTL_SET_CALLBACK_FN, M2MB_SPI_IOCTL_GET_CALLBACK_FN, M2MB_SPI_IOCTL_SET_CALLBACK_CTXT, M2MB_SPI_IOCTL_GET_CALLBACK_CTXT, M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ, M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ, M2MB_SPI_IOCTL_SET_BITS_PER_WORD, M2MB_SPI_IOCTL_GET_BITS_PER_WORD, M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES, M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES, M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES, M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES, M2MB_SPI_IOCTL_SET_LOOPBACK_MODE, M2MB_SPI_IOCTL_GET_LOOPBACK_MODE, M2MB_SPI_IOCTL_NOF_REQ, M2MB_SPI_IOCTL_SET_CFG = 0, M2MB_SPI_IOCTL_GET_CFG, M2MB_SPI_IOCTL_SET_SHIFT_MODE, M2MB_SPI_IOCTL_GET_SHIFT_MODE, M2MB_SPI_IOCTL_SET_CS_POLARITY, M2MB_SPI_IOCTL_GET_CS_POLARITY, M2MB_SPI_IOCTL_SET_CS_MODE, M2MB_SPI_IOCTL_GET_CS_MODE, M2MB_SPI_IOCTL_SET_BYTE_ORDER, M2MB_SPI_IOCTL_GET_BYTE_ORDER, M2MB_SPI_IOCTL_SET_CALLBACK_FN, M2MB_SPI_IOCTL_GET_CALLBACK_FN, M2MB_SPI_IOCTL_SET_CALLBACK_CTXT, M2MB_SPI_IOCTL_GET_CALLBACK_CTXT, M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ, M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ, M2MB_SPI_IOCTL_SET_BITS_PER_WORD, M2MB_SPI_IOCTL_GET_BITS_PER_WORD, M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES, M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES, M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES, M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES, M2MB_SPI_IOCTL_SET_LOOPBACK_MODE, M2MB_SPI_IOCTL_GET_LOOPBACK_MODE, M2MB_SPI_IOCTL_NOF_REQ }

enum	M2MB_SPI_SHIFT_MODE_T { M2MB_SPI_MODE_0, M2MB_SPI_MODE_1, M2MB_SPI_MODE_2, M2MB_SPI_MODE_3, M2MB_SPI_MODE_INVALID = 0x7FFFFFFF, M2MB_SPI_MODE_0, M2MB_SPI_MODE_1, M2MB_SPI_MODE_2, M2MB_SPI_MODE_3, M2MB_SPI_MODE_INVALID = 0x7FFFFFFF, M2MB_SPI_MODE_0, M2MB_SPI_MODE_1, M2MB_SPI_MODE_2, M2MB_SPI_MODE_3, M2MB_SPI_MODE_INVALID = 0x7FFFFFFF }

enum	M2MB_SPI_CS_POLARITY_T { M2MB_SPI_CS_ACTIVE_LOW, M2MB_SPI_CS_ACTIVE_HIGH, M2MB_SPI_CS_ACTIVE_INVALID = 0x7FFFFFFF, M2MB_SPI_CS_ACTIVE_LOW, M2MB_SPI_CS_ACTIVE_HIGH, M2MB_SPI_CS_ACTIVE_INVALID = 0x7FFFFFFF, M2MB_SPI_CS_ACTIVE_LOW, M2MB_SPI_CS_ACTIVE_HIGH, M2MB_SPI_CS_ACTIVE_INVALID = 0x7FFFFFFF }

enum	M2MB_SPI_CLK_MODE_T { M2MB_SPI_CLK_NORMAL, M2MB_SPI_CLK_ALLWAYS_ON, M2MB_SPI_CLK_INVALID = 0x7FFFFFFF }

enum	M2MB_SPI_CS_MODE_T { M2MB_SPI_CS_DEASSERT, M2MB_SPI_CS_KEEP_ASSERTED, M2MB_SPI_CS_MODE_INVALID = 0x7FFFFFFF, M2MB_SPI_CS_DEASSERT, M2MB_SPI_CS_KEEP_ASSERTED, M2MB_SPI_CS_MODE_INVALID = 0x7FFFFFFF, M2MB_SPI_CS_DEASSERT, M2MB_SPI_CS_KEEP_ASSERTED, M2MB_SPI_CS_MODE_INVALID = 0x7FFFFFFF }

enum	M2MB_SPI_BYTE_ORDER_T { M2MB_SPI_NATIVE = 0, M2MB_SPI_LITTLE_ENDIAN = 0, M2MB_SPI_BIG_ENDIAN, M2MB_SPI_NATIVE = 0, M2MB_SPI_LITTLE_ENDIAN = 0, M2MB_SPI_BIG_ENDIAN, M2MB_SPI_BYTE_ORDER_INVALID = 0x7FFFFFFF, M2MB_SPI_NATIVE = 0, M2MB_SPI_LITTLE_ENDIAN = 0, M2MB_SPI_BIG_ENDIAN }

typedef enum M2MB_SPI_IOCTL_REQUEST	M2MB_SPI_IOCTL_REQUEST_T

typedef void(*	M2MB_SPI_CALLBACK_FN_T) (UINT32 status, void *callback_ctxt)

typedef void *	M2MB_SPI_ID_t

INT32	m2mb_spi_open (const CHAR *path, INT32 flags,...)
	open a SPI device More...

INT32	m2mb_spi_close (INT32 fd)
	close a SPI device More...

INT32	m2mb_spi_ioctl (INT32 fd, M2MB_SPI_IOCTL_REQUEST_T request,...)
	configure a SPI device More...

SSIZE_T	m2mb_spi_read (INT32 fd, void *buf, SIZE_T nbyte)
	read nbyte Bytes from a SPI device into the array pointed by buf More...

SSIZE_T	m2mb_spi_write (INT32 fd, const void *buf, SIZE_T nbyte)
	write nbyte Bytes from the array pointed by buf to a SPI device More...

SSIZE_T	m2mb_spi_write_read (INT32 fd, const void bufwr, void bufWr, SIZE_T nbyte)
	perform a bi-directional (full duplex) transfer. More...

Detailed Description

This section describes the M2MB APIs to perform various SPI master operations.

Macro Definition Documentation

◆ M2MB_SPI_BAUD_RATE_10MHZ

#define M2MB_SPI_BAUD_RATE_10MHZ 10000000

baud rate 10MHZ

Definition at line 60 of file m2mb_spi_master.h.

◆ M2MB_SPI_BITS_PER_WORD_8

#define M2MB_SPI_BITS_PER_WORD_8 8

bits per word

Definition at line 58 of file m2mb_spi_master.h.

◆ M2MB_SPI_CLKPHASE_FALLING_EDGE

#define M2MB_SPI_CLKPHASE_FALLING_EDGE 1

SPI clock falling edge

Definition at line 56 of file m2mb_spi_master.h.

◆ M2MB_SPI_CLKPHASE_RISING_EDGE

#define M2MB_SPI_CLKPHASE_RISING_EDGE 0

SPI clock rising edge

Definition at line 55 of file m2mb_spi_master.h.

◆ M2MB_SPI_CLKPOL_IDLE_HIGH

#define M2MB_SPI_CLKPOL_IDLE_HIGH 1

SPI clock polarity idle high

Definition at line 53 of file m2mb_spi_master.h.

◆ M2MB_SPI_CLKPOL_IDLE_LOW

#define M2MB_SPI_CLKPOL_IDLE_LOW 0

SPI clock polarity idle low

Definition at line 52 of file m2mb_spi_master.h.

Typedef Documentation

◆ M2MB_SPI_CALLBACK_FN_T

typedef void(* M2MB_SPI_CALLBACK_FN_T) (UINT32 status, void *callback_ctxt)

Definition at line 152 of file m2mb_spi_master.h.

◆ M2MB_SPI_ID_t

typedef void* M2MB_SPI_ID_t

Definition at line 155 of file m2mb_spi_master.h.

◆ M2MB_SPI_IOCTL_REQUEST_T

typedef enum M2MB_SPI_IOCTL_REQUEST M2MB_SPI_IOCTL_REQUEST_T

Enumeration Type Documentation

◆ M2MB_SPI_BYTE_ORDER_T

enum M2MB_SPI_BYTE_ORDER_T

Enumerator
M2MB_SPI_NATIVE
M2MB_SPI_LITTLE_ENDIAN
M2MB_SPI_BIG_ENDIAN
M2MB_SPI_NATIVE	Native
M2MB_SPI_LITTLE_ENDIAN	Little Endian
M2MB_SPI_BIG_ENDIAN	Big Endian (network)
M2MB_SPI_BYTE_ORDER_INVALID
M2MB_SPI_NATIVE
M2MB_SPI_LITTLE_ENDIAN
M2MB_SPI_BIG_ENDIAN

Definition at line 139 of file m2mb_spi_master.h.

◆ M2MB_SPI_CLK_MODE_T

enum M2MB_SPI_CLK_MODE_T

Enumerator
M2MB_SPI_CLK_NORMAL	Turns off the SPI clock during the Idle state
M2MB_SPI_CLK_ALLWAYS_ON	Runs the SPI clock during the Idle state
M2MB_SPI_CLK_INVALID

Definition at line 120 of file m2mb_spi_master.h.

◆ M2MB_SPI_CS_MODE_T

enum M2MB_SPI_CS_MODE_T

Enumerator
M2MB_SPI_CS_DEASSERT
M2MB_SPI_CS_KEEP_ASSERTED
M2MB_SPI_CS_MODE_INVALID
M2MB_SPI_CS_DEASSERT	CS is deasserted after transferring data for N clock cycles
M2MB_SPI_CS_KEEP_ASSERTED	CS is asserted as long as the core is in the Run state
M2MB_SPI_CS_MODE_INVALID
M2MB_SPI_CS_DEASSERT
M2MB_SPI_CS_KEEP_ASSERTED
M2MB_SPI_CS_MODE_INVALID

Definition at line 130 of file m2mb_spi_master.h.

◆ M2MB_SPI_CS_POLARITY_T

enum M2MB_SPI_CS_POLARITY_T

Enumerator
M2MB_SPI_CS_ACTIVE_LOW
M2MB_SPI_CS_ACTIVE_HIGH
M2MB_SPI_CS_ACTIVE_INVALID
M2MB_SPI_CS_ACTIVE_LOW	During Idle state, the CS line is held low
M2MB_SPI_CS_ACTIVE_HIGH	During Idle state, the CS line is held high
M2MB_SPI_CS_ACTIVE_INVALID
M2MB_SPI_CS_ACTIVE_LOW
M2MB_SPI_CS_ACTIVE_HIGH
M2MB_SPI_CS_ACTIVE_INVALID

Definition at line 111 of file m2mb_spi_master.h.

◆ M2MB_SPI_IOCTL_REQUEST

enum M2MB_SPI_IOCTL_REQUEST

Enumerator
M2MB_SPI_IOCTL_SET_CFG
M2MB_SPI_IOCTL_GET_CFG
M2MB_SPI_IOCTL_SET_SHIFT_MODE
M2MB_SPI_IOCTL_GET_SHIFT_MODE
M2MB_SPI_IOCTL_SET_CS_POLARITY
M2MB_SPI_IOCTL_GET_CS_POLARITY
M2MB_SPI_IOCTL_SET_CS_MODE
M2MB_SPI_IOCTL_GET_CS_MODE
M2MB_SPI_IOCTL_SET_BYTE_ORDER
M2MB_SPI_IOCTL_GET_BYTE_ORDER
M2MB_SPI_IOCTL_SET_CALLBACK_FN
M2MB_SPI_IOCTL_GET_CALLBACK_FN
M2MB_SPI_IOCTL_SET_CALLBACK_CTXT
M2MB_SPI_IOCTL_GET_CALLBACK_CTXT
M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ
M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ
M2MB_SPI_IOCTL_SET_BITS_PER_WORD
M2MB_SPI_IOCTL_GET_BITS_PER_WORD
M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES
M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES
M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES
M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES
M2MB_SPI_IOCTL_SET_LOOPBACK_MODE
M2MB_SPI_IOCTL_GET_LOOPBACK_MODE
M2MB_SPI_IOCTL_GET_WEITE_COMPLETE
M2MB_SPI_IOCTL_NOF_REQ
M2MB_SPI_IOCTL_SET_CFG	set whole spi device configuration
M2MB_SPI_IOCTL_GET_CFG	get whole spi device configuration
M2MB_SPI_IOCTL_SET_SHIFT_MODE	set spi device shift mode
M2MB_SPI_IOCTL_GET_SHIFT_MODE	get spi device shift mode
M2MB_SPI_IOCTL_SET_CS_POLARITY	set spi device CS polarity
M2MB_SPI_IOCTL_GET_CS_POLARITY	get spi device CS polarity
M2MB_SPI_IOCTL_SET_CS_MODE	set spi device CS mode
M2MB_SPI_IOCTL_GET_CS_MODE	get spi device CS mode
M2MB_SPI_IOCTL_SET_BYTE_ORDER	set spi device endianness
M2MB_SPI_IOCTL_GET_BYTE_ORDER	get spi device endianness
M2MB_SPI_IOCTL_SET_CALLBACK_FN	set spi device callback function
M2MB_SPI_IOCTL_GET_CALLBACK_FN	get spi device callback function
M2MB_SPI_IOCTL_SET_CALLBACK_CTXT	set spi device callback context
M2MB_SPI_IOCTL_GET_CALLBACK_CTXT	get spi device callback context
M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ	set spi device clock frequency in Hz
M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ	get spi device clock frequency in Hz
M2MB_SPI_IOCTL_SET_BITS_PER_WORD	set spi device bits per word
M2MB_SPI_IOCTL_GET_BITS_PER_WORD	get spi device bits per word
M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES	set spi device cs_clk_delay_cycles
M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES	get spi device cs_clk_delay_cycles
M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES	set spi device inter_word_delay_cycles
M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES	get spi device inter_word_delay_cycles
M2MB_SPI_IOCTL_SET_LOOPBACK_MODE	set spi device loopback mode
M2MB_SPI_IOCTL_GET_LOOPBACK_MODE	get spi device loopback mode
M2MB_SPI_IOCTL_NOF_REQ	number of m2mb ioctl requests
M2MB_SPI_IOCTL_SET_CFG
M2MB_SPI_IOCTL_GET_CFG
M2MB_SPI_IOCTL_SET_SHIFT_MODE
M2MB_SPI_IOCTL_GET_SHIFT_MODE
M2MB_SPI_IOCTL_SET_CS_POLARITY
M2MB_SPI_IOCTL_GET_CS_POLARITY
M2MB_SPI_IOCTL_SET_CS_MODE
M2MB_SPI_IOCTL_GET_CS_MODE
M2MB_SPI_IOCTL_SET_BYTE_ORDER
M2MB_SPI_IOCTL_GET_BYTE_ORDER
M2MB_SPI_IOCTL_SET_CALLBACK_FN
M2MB_SPI_IOCTL_GET_CALLBACK_FN
M2MB_SPI_IOCTL_SET_CALLBACK_CTXT
M2MB_SPI_IOCTL_GET_CALLBACK_CTXT
M2MB_SPI_IOCTL_SET_CLK_FREQ_HZ
M2MB_SPI_IOCTL_GET_CLK_FREQ_HZ
M2MB_SPI_IOCTL_SET_BITS_PER_WORD
M2MB_SPI_IOCTL_GET_BITS_PER_WORD
M2MB_SPI_IOCTL_SET_CS_CLK_DELAY_CYCLES
M2MB_SPI_IOCTL_GET_CS_CLK_DELAY_CYCLES
M2MB_SPI_IOCTL_SET_INTER_WORD_DELAY_CYCLES
M2MB_SPI_IOCTL_GET_INTER_WORD_DELAY_CYCLES
M2MB_SPI_IOCTL_SET_LOOPBACK_MODE
M2MB_SPI_IOCTL_GET_LOOPBACK_MODE
M2MB_SPI_IOCTL_NOF_REQ

Definition at line 65 of file m2mb_spi_master.h.

◆ M2MB_SPI_SHIFT_MODE_T

enum M2MB_SPI_SHIFT_MODE_T

Enumerator
M2MB_SPI_MODE_0
M2MB_SPI_MODE_1
M2MB_SPI_MODE_2
M2MB_SPI_MODE_3
M2MB_SPI_MODE_INVALID
M2MB_SPI_MODE_0	CPOL = 0, CPHA = 0
M2MB_SPI_MODE_1	CPOL = 0, CPHA = 1
M2MB_SPI_MODE_2	CPOL = 1, CPHA = 0
M2MB_SPI_MODE_3	CPOL = 1, CPHA = 1
M2MB_SPI_MODE_INVALID
M2MB_SPI_MODE_0
M2MB_SPI_MODE_1
M2MB_SPI_MODE_2
M2MB_SPI_MODE_3
M2MB_SPI_MODE_INVALID

Definition at line 100 of file m2mb_spi_master.h.

Function Documentation

◆ m2mb_spi_close()

INT32 m2mb_spi_close ( INT32 fd )

close a SPI device

Parameters

[in] fd file descriptor returned by m2mb_spi_open

Returns: 0 on SUCCESS -1 on FAILURE

Note: <Notes>

Example

◆ m2mb_spi_ioctl()

INT32 m2mb_spi_ioctl	(	INT32	fd,
		M2MB_SPI_IOCTL_REQUEST_T	request,
			...
	)

configure a SPI device

configure a SPI device. Pass pointer to the set/get val, casted to void* as the variable argument.

Parameters

[in]	fd	file descriptor returned by m2mb_spi_open
[in]	request	required operation (see M2MB_SPI_IOCTL_REQUEST)

Returns: 0 on SUCCESS -1 on FAILURE

Note: <Notes> i.e. m2mb_spi_ioctl(fd, M2MB_SPI_IOCTL_SET_CFG, (void *)&config) where config is a M2MB_SPI_CFG_T struct

Example

◆ m2mb_spi_open()

INT32 m2mb_spi_open	(	const CHAR *	path,
		INT32	flags,
			...
	)

open a SPI device

Parameters

[in]	path	/dev/devspiX.Y where X is the HW SPI master instance index (from 1 to 24). Default is 5. Y is the SPI slave device index (from 0 to 6). At most 7 slaves are allowed. Default is 0. Path "/dev/devspiX" is equivalent to default "/dev/devspiX.0" Path "/dev/devspi" is equivalent to default "/dev/devspi5.0"
[in]	flags	currently unused

Returns: file descriptor on SUCCESS -1 on FAILURE

Note: <Notes> i.e.: fd = m2mb_spi_open( "/dev/spidev1.0", 0 );

Example

◆ m2mb_spi_read()

SSIZE_T m2mb_spi_read	(	INT32	fd,
		void *	buf,
		SIZE_T	nbyte
	)

read nbyte Bytes from a SPI device into the array pointed by buf

Parameters

[in]	fd	file descriptor returned by m2mb_spi_open
[in]	buf	destination buffer, previously allocated
[in]	nbyte	length of destination buffer in Bytes

Returns: number of read Bytes on SUCCESS, -1 on FAILURE

Note: <Notes>

Example

◆ m2mb_spi_write()

SSIZE_T m2mb_spi_write	(	INT32	fd,
		const void *	buf,
		SIZE_T	nbyte
	)

write nbyte Bytes from the array pointed by buf to a SPI device

Parameters

[in]	fd	file descriptor returned by m2mb_spi_open
[in]	buf	source buffer, previously allocated
[in]	nbyte	length of source buffer in Bytes

Returns: number of written Bytes on SUCCESS, -1 on FAILURE

Note: <Notes>

Example

◆ m2mb_spi_write_read()

SSIZE_T m2mb_spi_write_read	(	INT32	fd,
		const void *	bufwr,
		void *	bufWr,
		SIZE_T	nbyte
	)

perform a bi-directional (full duplex) transfer.

perform a bi-directional (full duplex) transfer. Read nbyte Bytes from a SPI device into the buffer bufRd and write nbyte Bytes from the buffer bufWr to a SPI device

Parameters

[in]	fd	file descriptor returned by m2mb_spi_open
[in]	bufwr	source buffer, previously allocated
[in]	bufWr	destination buffer, previously allocated
[in]	nbyte	length of source and destination buffers in Bytes

Returns: number of written/read Bytes on SUCCESS, -1 on FAILURE

Note: <Notes>

Example