Barebox over RATP: libratp-barebox Reference Manual

Barebox over RATP

Barebox over RATP — Barebox operations over the RATP link

Types and Values

enum	ratp_barebox_link_i2c_flag_t
enum	ratp_barebox_link_gpio_direction_t

Description

This section defines the methods that allow the user to run barebox specific operations over the RATP link.

Functions

ratp_barebox_link_ping ()

ratp_status_t
ratp_barebox_link_ping (ratp_link_t *ratp,
                        unsigned long  timeout_ms);

Sends a PING to barebox and waits for the PONG as return.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]

Returns

a ratp_status_t.

ratp_barebox_link_command ()

ratp_status_t
ratp_barebox_link_command (ratp_link_t *ratp,
                           unsigned long  timeout_ms,
                           const char *command,
                           uint32_t *out_errno_result,
                           char **out_stdout_result);

Sends a command to barebox and waits for it to finish. Both the command result and the standard output it generated are returned.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
command	command to send, in ASCII.	[in][not nullable]
out_errno_result	output location to store the errno result returned.	[out][optional]
out_stdout_result	output location to store the resulting stdout output.	[out callee-allocates][optional]

Returns

a ratp_status_t.

ratp_barebox_link_getenv ()

ratp_status_t
ratp_barebox_link_getenv (ratp_link_t *ratp,
                          unsigned long  timeout_ms,
                          const char *env_name,
                          char **env_value);

Reads the contents of a given environment variable in the remote barebox instance.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
env_name	name of the environment variable to read.	[in]
env_value	output location to store the value of the environment variable.	[out callee-allocates][optional]

Returns

a ratp_status_t.

ratp_barebox_link_md ()

ratp_status_t
ratp_barebox_link_md (ratp_link_t *ratp,
                      unsigned long  timeout_ms,
                      const char *path,
                      uint16_t addr,
                      uint16_t size,
                      uint8_t **out,
                      uint16_t *out_size);

Memory display.

Reads size bytes of memory from the file at path , starting at addr . If RATP_STATUS_OK is returned, out and out_size will be set.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
path	path to the display file, or `NULL` for the default.	[in][nullable]
addr	address where to start reading from.	[in]
size	amount of bytes to read.	[in]
out	output location to store the data read.	[out callee-allocates][array length=out_size][optional]
out_size	size of the data read in `out` .	[out][optional]

Returns

a ratp_status_t.

ratp_barebox_link_mw ()

ratp_status_t
ratp_barebox_link_mw (ratp_link_t *ratp,
                      unsigned long  timeout_ms,
                      const char *path,
                      uint16_t addr,
                      const uint8_t *data,
                      uint16_t data_size,
                      uint16_t *out_written);

Memory write.

Writes data_size bytes into the display file at path , starting at addr . If RATP_STATUS_OK is returned, out_written will be set.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation (in): finish, or 0 to wait forever.	[in]
path	path to the display file, or `NULL` for the default.	[in][nullable]
addr	address where to start writing to.	[in]
data	data to write.	[in][array length=data_size][not nullable]
data_size	amount of bytes to write.	[in]
out_written	number of bytes successfully written.	[out][optional]

Returns

a ratp_status_t.

ratp_barebox_link_i2c_read ()

ratp_status_t
ratp_barebox_link_i2c_read (ratp_link_t *ratp,
                            unsigned long  timeout_ms,
                            uint8_t bus,
                            uint8_t addr,
                            uint16_t reg,
                            ratp_barebox_link_i2c_flag_t flags,
                            uint16_t size,
                            uint8_t **out,
                            uint16_t *out_size);

i2c read.

Reads size bytes from device at bus /addr .

If RATP_STATUS_OK is returned, out and out_size will be set.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
bus	bus number.	[in]
addr	device address.	[in]
reg	start register.	[in]
flags	a bitmask of ratp_barebox_link_i2c_flag_t values.	[in]
size	amount of bytes to read.	[in]
out	output location to store the data read.	[out callee-allocates][array length=out_size][optional]
out_size	size of the data read in `out` .	[out][optional]

Returns

a ratp_status_t.

ratp_barebox_link_i2c_write ()

ratp_status_t
ratp_barebox_link_i2c_write (ratp_link_t *ratp,
                             unsigned long  timeout_ms,
                             uint8_t bus,
                             uint8_t addr,
                             uint16_t reg,
                             ratp_barebox_link_i2c_flag_t flags,
                             const uint8_t *data,
                             uint16_t data_size,
                             uint16_t *out_written);

i2c write.

Writes data_size bytes to the device at bus /addr .

If RATP_STATUS_OK is returned, out_written will be set.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
bus	bus number.	[in]
addr	device address.	[in]
reg	optional start register, set to 0xffff to ignore.	[in]
flags	a bitmask of ratp_barebox_link_i2c_flag_t values.	[in]
data	data to write.	[in][array length=data_size][not nullable]
data_size	amount of bytes to write.	[in]
out_written	number of bytes successfully written.	[out][optional]

Returns

a ratp_status_t.

ratp_barebox_link_gpio_get_value ()

ratp_status_t
ratp_barebox_link_gpio_get_value (ratp_link_t *ratp,
                                  unsigned long  timeout_ms,
                                  uint32_t gpio,
                                  bool *value);

Gets the current value of the input GPIO gpio .

This method should only be used with GPIOs configured as RATP_BAREBOX_LINK_GPIO_DIRECTION_INPUT.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
gpio	a GPIO number.	[in]
value	output location to store the value.	[out][optional]

Returns

a ratp_status_t.

ratp_barebox_link_gpio_set_value ()

ratp_status_t
ratp_barebox_link_gpio_set_value (ratp_link_t *ratp,
                                  unsigned long  timeout_ms,
                                  uint32_t gpio,
                                  bool value);

Sets the current value of the output GPIO gpio .

This method should only be used with GPIOs configured as RATP_BAREBOX_LINK_GPIO_DIRECTION_OUTPUT.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
gpio	a GPIO number.	[in]
value	the value to set.	[in]

Returns

a ratp_status_t.

ratp_barebox_link_gpio_set_direction ()

ratp_status_t
ratp_barebox_link_gpio_set_direction (ratp_link_t *ratp,
                                      unsigned long  timeout_ms,
                                      uint32_t gpio,
                                      ratp_barebox_link_gpio_direction_t direction,
                                      bool value);

Sets the direction of the GPIO gpio .

Parameters

ratp	a ratp_link_t.	[in][not nullable]
timeout_ms	maximum time, in milliseconds, to wait for the operation to finish, or 0 to wait forever.	[in]
gpio	a GPIO number.	[in]
direction	a ratp_barebox_link_gpio_direction_t.	[in]
value	if `direction` is `RATP_BAREBOX_LINK_GPIO_DIRECTION_OUTPUT`, the value to set.	[in]

Returns

a ratp_status_t.

ratp_barebox_link_reset ()

ratp_status_t
ratp_barebox_link_reset (ratp_link_t *ratp,
                         bool force);

Performs a reset in barebox.

Note that this operation will make the RATP session abort.

Parameters

ratp	a ratp_link_t.	[in][not nullable]
force	force reset, don't call shutdown.	[in]

Returns

a ratp_status_t.

Types and Values

enum ratp_barebox_link_i2c_flag_t

Flags to use in the i2c read/write operations.

Members

RATP_BAREBOX_LINK_I2C_FLAG_NONE	None.
RATP_BAREBOX_LINK_I2C_FLAG_WIDE_ADDRESS	Word (16bit) wide access should be used.
RATP_BAREBOX_LINK_I2C_FLAG_MASTER_MODE	Master send/receive, ignoring start register.

enum ratp_barebox_link_gpio_direction_t

Direction of the GPIO.

Members

RATP_BAREBOX_LINK_GPIO_DIRECTION_INPUT	GPIO configured as input.
RATP_BAREBOX_LINK_GPIO_DIRECTION_OUTPUT	GPIO configured as output.

ratp_status_t	ratp_barebox_link_ping ()
ratp_status_t	ratp_barebox_link_command ()
ratp_status_t	ratp_barebox_link_getenv ()
ratp_status_t	ratp_barebox_link_md ()
ratp_status_t	ratp_barebox_link_mw ()
ratp_status_t	ratp_barebox_link_i2c_read ()
ratp_status_t	ratp_barebox_link_i2c_write ()
ratp_status_t	ratp_barebox_link_gpio_get_value ()
ratp_status_t	ratp_barebox_link_gpio_set_value ()
ratp_status_t	ratp_barebox_link_gpio_set_direction ()
ratp_status_t	ratp_barebox_link_reset ()