vdml.h File Reference

#include <stdbool.h>
#include <stdint.h>
#include "vdml/registry.h"

Go to the source code of this file.

Macros
#define	VALIDATE_PORT_NO(PORT)
#define	VALIDATE_PORT_NO_INTERNAL(PORT)
#define	claim_port(port, device_type, error_code)
#define	claim_port_i(port, device_type)
#define	claim_port_f(port, device_type)
#define	return_port(port, rtn)
#define	V5_PORT_BATTERY   24
#define	V5_PORT_CONTROLLER_1   25
#define	V5_PORT_CONTROLLER_2   26

Functions
int32_t	claim_port_try (uint8_t port, v5_device_e_t type)
void	vdml_set_port_error (uint8_t port)
void	vdml_unset_port_error (uint8_t port)
bool	vdml_get_port_error (uint8_t port)
int	port_mutex_take (uint8_t port)
int	port_mutex_give (uint8_t port)
void	port_mutex_take_all ()
void	port_mutex_give_all ()
int	internal_port_mutex_take (uint8_t port)
int	internal_port_mutex_give (uint8_t port)

Variables
int32_t	port_errors

Detailed Description

This file contains all types and functions used throughout multiple VDML (Vex Data Management Layer) files.

Copyright

Copyright (c) 2017-2024, Purdue University ACM SIGBots.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Macro Definition Documentation

claim_port

#define claim_port	(		port,
			device_type,
			error_code )

Value:

  if (registry_validate_binding(port, device_type) != 0) { \
    return error_code;                                     \
  }                                                        \
  v5_smart_device_s_t* device = registry_get_device(port); \
  if (!port_mutex_take(port)) {                            \
    errno = EACCES;                                        \
    return error_code;                                     \
  }

Macro that handles error checking, sanity checking, automatic registration, and mutex taking for all of the motor wrapper functions. If port is out of range, the calling function sets errno and returns. If a port isn't yet registered, it registered as a motor automatically. If a mutex cannot be taken, errno is set to EACCES (access denied) and returns.

Parameters

port	The V5 port number from 0-20
device_type	The v5_device_e_t that the port is configured as
error_code	The error code that return if error checking failed

claim_port_f

#define claim_port_f	(		port,
			device_type )

Value:

claim_port(port, device_type, PROS_ERR_F)

Function like claim_port. This macro should only be used in functions that return double or float as PROS_ERR_F could be returned.

Parameters

port	The V5 port number from 0-20
device_type	The v5_device_e_t that the port is configured as

claim_port_i

#define claim_port_i	(		port,
			device_type )

Value:

claim_port(port, device_type, PROS_ERR)

Function like claim_port. This macro should only be used in functions that return int32_t or enums as PROS_ERR could be returned.

Parameters

port	The V5 port number from 0-20
device_type	The v5_device_e_t that the port is configured as

return_port

#define return_port	(		port,
			rtn )

Value:

  port_mutex_give(port);       \
  return rtn;

Macro that release the mutex for the given port and sets errno to 0 if the function is an accessor wrapper whos return value is PROS_ERR or PROS_ERR_F.

Parameters

port	The V5 port number from 0-20
rtn	The desired return value

Returns

The rtn parameter

VALIDATE_PORT_NO

#define VALIDATE_PORT_NO

(

PORT

)

Value:

((PORT) >= 0 && (PORT) < NUM_V5_PORTS)

Macro, returns true if the port is in range of user configurable ports, false otherwise.

VALIDATE_PORT_NO_INTERNAL

#define VALIDATE_PORT_NO_INTERNAL

(

PORT

)

Value:

((PORT) >= 0 && (PORT) < V5_MAX_DEVICE_PORTS)

Function Documentation

claim_port_try()

int32_t claim_port_try	(	uint8_t	port,
		v5_device_e_t	type )

A function that executes claim_port and allows you to execute a block of code if an error occurs.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (1-21). EACCES - Another resource is currently trying to access the port.

Parameters

port	The V5 port number from 0-20
device_type	The v5_device_e_t that the port is configured as

Returns

1 if the operation was successful or 0 if the operation failed, setting errno.

internal_port_mutex_give()

int internal_port_mutex_give

(

uint8_t

port

)

Returns a port mutex with bounds checking for V5_MAX_PORTS (32) not user exposed device ports (20). Intended for internal usage for protecting thread-safety on devices such as the controller and battery

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-32).

Parameters

port	The V5 port number from 0-32

Returns

True if the mutex was successfully returned, false otherwise. If false is returned, then errno is set with a hint about why the mutex couldn't be returned.

internal_port_mutex_take()

int internal_port_mutex_take

(

uint8_t

port

)

Obtains a port mutex with bounds checking for V5_MAX_PORTS (32) not user exposed device ports (20). Intended for internal usage for protecting thread-safety on devices such as the controller and battery

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-32).

Parameters

port	The V5 port number from 0-32

Returns

True if the mutex was successfully taken, false otherwise. If false is returned, then errno is set with a hint about why the the mutex couldn't be taken.

port_mutex_give()

int port_mutex_give

(

uint8_t

port

)

Returns the mutex for the given port.

Frees the mutex for this port, allowing other tasks to continue.

WARNING: If a mutex was claimed by a task, this MUST be called immediately after the port is no longer needed by that task in order to prevent delays in other tasks.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-20).

Parameters

port	The V5 port number to free from 0-20

port_mutex_give_all()

void port_mutex_give_all

(

)

Executes port_mutex_give() for all of the V5 Smart Ports.

port_mutex_take()

int port_mutex_take

(

uint8_t

port

)

Claims the mutex for the given port.

Reserves the mutex for this port. Any other tasks trying to access this port will block until the mutex is returned. If a higher-priortiy task attempts to claim this port, the task which has the port claimed will temporarily be raised to an equal priority until the mutex is given, reducing the impact of the delay. See FreeRTOS documentation for more details.

This MUST be called before any call to the v5 api to maintain thread saftey.

This function uses the following values of errno when an error state is reached: ENXIO - The given value is not within the range of V5 ports (0-20).

Parameters

port	The V5 port number to claim from 0-20

Returns

1 if the mutex was successfully taken, 0 if not, -1 if port is invalid.

port_mutex_take_all()

void port_mutex_take_all

(

)

Executes port_mutex_take() for all of the V5 Smart Ports.

vdml_get_port_error()

bool vdml_get_port_error

(

uint8_t

port

)

Gets the error bit for the port, indicating whether or not there has been an error on this port.

Parameters

port	The V5 port number to check from 0-20

Returns

True if the port's bit is set, false otherwise.

vdml_set_port_error()

void vdml_set_port_error

(

uint8_t

port

)

Sets the port's bit to 1, indicating there has already been an error on this port.

Parameters

port	The V5 port number to set from 0-20

vdml_unset_port_error()

void vdml_unset_port_error

(

uint8_t

port

)

Sets the port's bit to 0, effectively resetting it.

Parameters

port	The V5 port number to unset from 0-20

Variable Documentation

port_errors

int32_t port_errors

extern

Bitmap to indicate if a port has had an error printed or not.