Hardware Abstraction Layer API

Hardware abstraction layer (HAL) API, used by Renesas Environmental Sensor APIs to physically access the sensor. More...

Files
file	hal.h
	Renesas Environmental Sensor HAL definitions.

Functions
int	HAL_Init (Interface_t *hal)
	Initialize hardware and populate Interface_t object. More...
int	HAL_Deinit (Interface_t *hal)
	Cleanup before program exit. More...
void	HAL_HandleError (int errorCode, void const *context)
	Error handling function. More...
int	HAL_SetError (int error, int scope, ErrorStringGenerator_t errStrFn)
	Function storing error information. More...
char const *	HAL_GetErrorInfo (int *error, int *scope, char *str, int bufSize)
	Get detailed information for last error. More...
char const *	HAL_GetErrorString (int error, int scope, char *str, int bufSize)
	Error string generator for HAL-scoped errors. More...

Data Structures
struct	Interface_t
	A structure of pointers to hardware specific functions. More...

Typedefs
typedef int(*	I2CImpl_t) (void *, uint8_t, uint8_t *, int, uint8_t *, int)
	Function pointer type defining signature of I2C functions. More...
typedef char const *(*	ErrorStringGenerator_t) (int, int, char *, int)
	Function type used for generation of error strings. More...

Enumerations
enum	GenericError_t { ecSuccess = 0, ecHALError = 0x10000 }
	Error code definitions. More...
enum	ErrorScope_t { esSensor = 0x00000000, esAlgorithm = 0x10000000, esInterface = 0x20000000, esHAL = 0x30000000 }
	Success status code and error scopes. More...
enum	HALError_t {   heNoInterface = 1, heNotImplemented, heI2CReadMissing, heI2CWriteMissing,   heSleepMissing, heResetMissing }
	HAL scope error definitions. More...

Detailed Description

Hardware abstraction layer (HAL) API, used by Renesas Environmental Sensor APIs to physically access the sensor.

The HAL API is a generic API that is used by all Renesas types of Environmental Sensors. It defines the interface that the sensor API can use to access the sensor on an arbitrary hardware platform. Renesas provides HAL implementations for EVK boards, Raspberry PI and Arduino. In order to use a specific sensor API in the customer application, the customer must implement the HAL API for his hardware platform. For that purpose, the template file template.c is provided, which must be adapted to work on the customer hardware. Please refer to the comments in the template file and the documentation of the HAL API for details.

All HAL API related files are located in path src/hal and its subdirectories.

---

Data Structure Documentation

Interface_t

struct Interface_t

A structure of pointers to hardware specific functions.

Data Fields
void *	handle
I2CImpl_t	i2cRead
I2CImpl_t	i2cWrite
void(*	msSleep )(uint32_t ms)
int(*	reset )(void *handle)

Field Documentation

handle

void* handle

handle to physical interface

i2cRead

I2CImpl_t i2cRead

Pointer to I2C read implementation

The read operation may be preceded by a write to the same slave address. The function accepts a pointer to the interface handle, the slave address of the device to communicate with and two pairs of buffer pointer and buffer length. The first pair of buffer pointer / buffer length defines the data to be written, the second pair provides the pointer to the buffer where received data is stored and how many bytes shall be read. If the length field of the first buffer is not zero, the implementation must send an I2C write condition on the bus, transfer the data and send a repeated start condition followed by the corresponding read condition on the bus. If the length parameter of the first buffer is zero, no write is generated and the read is started immediately. The transmission must be terminated with a stop condition on the bus.

i2cWrite

I2CImpl_t i2cWrite

Pointer to I2C write implementation

For convenience the write operation accepts two pairs of buffer pointer and buffer length. This allows to transfer addresses or commands prior to data without the need to manually concatenate transmit data in a buffer. The implementation of this function must generate a start condition followed by the I2C slave address of the target device, followed by all data from both buffers. At the end of the transmission a stop bit must be generated on the bus.

msSleep

void( * msSleep) (uint32_t ms)

Pointer to delay function

An implementation must delay execution by the specified number of ms

reset

int( * reset) (void *handle)

Pointer to reset function

Implementation must pulse the reset pin

Typedef Documentation

ErrorStringGenerator_t

typedef char const*( * ErrorStringGenerator_t) (int, int, char *, int)

Function type used for generation of error strings.

Functions of this type may be passed to HAL_SetError() to generate meaningful descriptions of error conditions.

I2CImpl_t

typedef int( * I2CImpl_t) (void *, uint8_t, uint8_t *, int, uint8_t *, int)

Function pointer type defining signature of I2C functions.

This function pointer typedef is used in Interface_t objects to hold pointers to I2C implementations of read and write.

Enumeration Type Documentation

ErrorScope_t

enum ErrorScope_t

Success status code and error scopes.

Enumerator
esSensor	Sensor scope
esAlgorithm	Algorithm scope
esInterface	Interface scope
esHAL	HAL scope

GenericError_t

enum GenericError_t

Error code definitions.

Enumerator
ecSuccess	Operation completed successfully
ecHALError	Returned by sensor API if a HAL function failed. Specific information about the error can be obtained using the function HAL_GetErrorInfo().

HALError_t

enum HALError_t

HAL scope error definitions.

When sensors are initialized (e.g. init_hardware()), the hal objects is checked whether all HAL functions required by the sensor are provided. If a function is missing one of the errors from this enumeration is returned.

Enumerator
heNoInterface	There was no interface found
heNotImplemented	The requested function is not implemented
heI2CReadMissing	Interface_t::i2cRead not provided
heI2CWriteMissing	Interface_t::i2cWrite not provided
heSleepMissing	Interface_t::msSleep not provided
heResetMissing	Interface_t::reset not provided

Function Documentation

HAL_Deinit()

int HAL_Deinit

(

Interface_t *

hal

)

Cleanup before program exit.

This function shall free up resources that have been allocated through HAL_Init().

Parameters

hal	pointer to Interface_t object to be deinitialized

Returns

error code

Return values

0	on success
!=0	in case of error

HAL_GetErrorInfo()

char const* HAL_GetErrorInfo	(	int *	error,
		int *	scope,
		char *	str,
		int	bufSize
	)

Get detailed information for last error.

Use this function in the error handler to obtain information about the last error code and which component generated it. In addition if an error string generator function was provided during error generation, this function may return a text string, describing the error in more detail.

Parameters

error	Pointer to integer, where the error code is written
scope	Pointer to integer, where the error scope (module that was generating the error is written)
str	Pointer to string buffer, where error message is written. If no string information is required, pass NULL pointer.
bufSize	Size of the string buffer, pass 0 if not used

Returns

Value passed in str

HAL_GetErrorString()

char const* HAL_GetErrorString	(	int	error,
		int	scope,
		char *	str,
		int	bufSize
	)

Error string generator for HAL-scoped errors.

This function generates error information for HAL scoped errors. Usually user code does not need to use this function directly.

Parameters

error	Error code for which error information is to be returned
scope	Error scope for which error information is to be returned
str	Pointer to string buffer, where error message is written
bufSize	Size of the string buffer

Returns

Value passed in str

HAL_HandleError()

void HAL_HandleError	(	int	errorCode,
		void const *	context
	)

Error handling function.

The implementation of this function defines the behavior of the application code when an error occurs during execution.

Parameters

errorCode	code of the error to be handled
context	additional context information

Define what happens in case of error

HAL_Init()

int HAL_Init

(

Interface_t *

hal

)

Initialize hardware and populate Interface_t object.

Any implementation must initialize those members of the Interface_t object that are required by the sensor being operated with pointers to functions that implement the behavior as specified in the Interface_t member documentation.

Parameters

hal	pointer to Interface_t object to be initialized

Returns

error code

Return values

0	on success
!=0	in case of error

HAL_SetError()

int HAL_SetError	(	int	error,
		int	scope,
		ErrorStringGenerator_t	errStrFn
	)

Function storing error information.

The sensor interface has different components which may generate error conditions. To keep the sensor interface as simple as possible, this function is called in case of an error. The return value of this function will be returned as error code of the function in which an error has occurred.

Internally, this function stores the error code and the scope of the error (that is which module was generating the error) in a data structure. For all errors which do not have the scope esSensor, this function will return the generic error code ecHALError. Error codes generated by the sensor, are returned directly.

It is possible to pass an error string generator function along with the error information. If this function is provided, the error handler can query an error string, providing more meaningful error information.

Parameters

error	An error code
scope	The scope of the error (integer identifying a module)
errStrFn	Optional function pointer that can decode generate a meaningful message for the error code. Pass NULL if not used.