ChorusOS man pages section 9DDI: Device Driver Interfaces

flashCtl(9DDI)

NAME

flashCtl- Flash control device driver interface

SYNOPSIS

#include <ddi/flash/flashCtl.h>

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

DDI

DESCRIPTION

The flashCtl device driver interface provides a basic interface by abstracting board specific operation for flash device write enabling/disabling management. Basically, the driver implements routines that allow the device driver client to enable/disable the write access on a flash device.

The flash control device operates synchronously.

Service Routines

The character string "flash-ctl" labels the flashCtl device class. The device clients use the device class name to obtain the driver service routines from the device registry as described in svDeviceLookup(9DKI). The flash control device driver is a mono-client driver. The driver registry prevents multiple look-ups to be done on the same flashCtl device driver instance.

The FlashCtlDevOps structure specifies the interface of the flash control device driver service routines.

typedef struct FlashCtlDevOps {
	FlashCtlVersion version;
		KnError
	(*open) (FlashCtlId  id);
		KnError
	(*write_enable) (FlashCtlId  id);
		void
	(*write_disable) (FlashCtlId  id);
		void
	(*close) (FlashCtlId  id);
} FlashCtlDevOps;

`version`

The version field specifies the highest version number of the flashCtl device driver interface supported by the driver. Currently, only one version is available and therefore the version field must be set to zero (FLASH_CTL_VERSION_INITIAL). In the future, the flash control device driver interface may be extended, but backward compatibility is guaranteed; extra methods may be added to the FlashCtlDevOps structure but the existing methods will remain unchanged.

`open()`

The open() routine must be the first call to the driver. The open routine makes the flash control device operational and enables subsequent invocations of the write_enable(), write_disable() and close() routines. The id argument specifies a given flash control device. It is obtained from the device registry entry dev_id field.

open() returns K_OK on success. The K_EFAIL error code is returned if the driver is not able to put the device in operation.

`write_enable()`

The write_enable() routine enables the write access to the flash device if the board implements the write enabling/disabling.

The write_enable routine returns K_OK on success. The K_EFAIL error code is returned if the driver is unable to enable the write access. When write_enable() returns the write access is effectively enabled.

`write_disable()`

The write_disable() routine disables the write access to the flash device if the board implements the write enabling/disabling.

The write_disable() routine returns no error code. When write_disable() returns the write access is effectively disabled.

`close()`

K The close() routine must be the last call to the driver because it makes the flash control device non-operational. Once the device is closed, the only routine allowed to call is open(). The id argument specifies a given flash control device. It is obtained from the device registry entry dev_id field. The close() routine returns no error code.

Device Node Properties

Properties attached to the flash control device node give to the device driver, and to the client driver some physical characteristics of the flash control device.

The following properties are optionnal :

Name	Alias	Value type
"mem-rgn"	BUS_PROP_MEM_RGN	<bus class specific>
"size"	FLASH_CTL_PROP_SIZE	FlashCtlSize

The BUS_PROP_MEM_RGN property specifies the physical flash memory region that the driver can manage.

The FLASH_CTL_PROP_SIZE specifies the physical flash memory size that the driver can manage.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving