/*

 * Intel(R) Enclosure LED Utilities

 * Copyright (C) 2009-2018 Intel Corporation.

 *

 * This program is free software; you can redistribute it and/or modify it

 * under the terms and conditions of the GNU General Public License,

 * version 2, as published by the Free Software Foundation.

 *

 * This program is distributed in the hope it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for

 * more details.

 *

 * You should have received a copy of the GNU General Public License along with

 * this program; if not, write to the Free Software Foundation, Inc.,

 * 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.

 *

 */

#ifndef _BLOCK_H_INCLUDED_

#define _BLOCK_H_INCLUDED_

#include "cntrl.h"

#include "ibpi.h"

#include "time.h"

#include "list.h"

#include "raid.h"

struct block_device;

/**

 * @brief Pointer to a send message function.

 *

 * The pointer to a function which knows how to send LED message to a driver of

 * storage controller using the given protocol.

 *

 * @param[in]    path             path in sysfs to a host device

 *                                @see block_device::cntrl_path.

 * @param[in]    ibpi             an IBPI pattern (state) to visualize.

 *

 * @return 1 if successful, otherwise the function returns 0.

 */

typedef int (*send_message_t) (struct block_device *device,

			       enum ibpi_pattern ibpi);

/**

 * @brief Pointer to a flush buffer function.

 *

 * @param[in]    device           pointer to a block device

 *

 * @return 1 if successful, otherwise the function returns 0.

 */

typedef int (*flush_message_t) (struct block_device *device);

/**

 * @brief Describes a block device.

 *

 * This structure describes a block device. It does not describe virtual devices

 * or partitions on physical block devices.

 */

struct block_device {

/**

 * Real path in sysfs tree. This means i.e. if /sys/block/sda is symbolic link

 * then the link will be read and path stored in sysfs_path field. This path

 * may not exist in sysfs if connection to physical drive is lost. This filed

 * cannot have NULL pointer assigned.

 */

	char *sysfs_path;

/**

 * The pointer to a function which sends a message to driver in order to

 * control LEDs in an enclosure or DAS system - @see send_message_t for details.

 * This field cannot have NULL pointer assigned.

 */

	send_message_t send_fn;

/**

 * The pointer to a function which flush buffers filled by send_fn.

 */

	flush_message_t flush_fn;

/**

 * Canonical path to block device where enclosure management fields are located.

 * This path is always accessible even if the connection to physical device

 * is lost. In case of AHCI controller it points to SATA phy. In case of SAS

 * this path points to SES entry associated with the slot in an enclosure.

 * This field cannot have NULL pointer assign.

 */

	char *cntrl_path;

/**

 * The current state of block device. This is an IBPI pattern and it is used

 * to visualize the state of block device.

 */

	enum ibpi_pattern ibpi;

/**

 * The previous state of block device.

 */

	enum ibpi_pattern ibpi_prev;

/**

 * The time stamp used to determine if the given block device still exist or

 * it failed and the device is no longer available. Every time IBPI pattern

 * is updated, the time-stamp is updated, too.

 */

	time_t timestamp;

/**

 * The pointer to storage controller structure the device is connected to.

 */

	struct cntrl_device *cntrl;

	struct _host_type *host;

	int host_id;

/**

 * The index of phy utilized by directly attached to controller block device.

 * It is meaningful if device is controlled by isci driver.

 */

	int phy_index;

/**

 * The index in Enclosure. This is what should be used when using SES-2.

 */

	int encl_index;

	struct enclosure_device *enclosure;

/**

 * If disk is a raid member, this field will be set with a copy of raid device

 * struct.

 */

	struct raid_device *raid_dev;

};

/**

 * @brief Creates a block device structure.

 *

 * This function allocates memory for a new structure of block device. It reads

 * the sysfs entries and populates the structure fields. It performs all this

 * actions only if the block device is connected to the one of supported storage

 * controllers and the controller has enclosure management services enabled.

 *

 * @param[in]      cntrl_list     pointer to a list of supported controller

 *                                devices.

 * @param[in]      sysfs_path     a path to block device in sysfs.

 *

 * @return Pointer to block device structure if successful, otherwise the function

 *         returns the NULL pointer.

 */

struct block_device *block_device_init(const struct list *cntrl_list, const char *path);

/**

 * @brief Releases a block device structure.

 *

 * This function releases memory allocated for block device structure.

 *

 * @param[in]      device         pointer to block device structure.

 *

 * @return The function does not return a value.

 */

void block_device_fini(struct block_device *device);

/**

 * @brief Duplicates a block device structure.

 *

 * The function allocates memory for a block device structure and copies values

 * stored in fields of source block structure. The function allocates new memory

 * for all string fields in a copy structure. It is safe to release source block

 * structure just after it has been duplicated.

 *

 * @param[in]      device         pointer to source block device structure.

 *

 * @return Pointer to block device structure if successful, otherwise the function

 *         returns the NULL pointer.

 */

struct block_device *block_device_duplicate(struct block_device *device);

/**

 * @brief Determines a storage controller.

 *

 * This is the internal function of 'block device' module. The function gets

 * a pointer to controller structure the device is connected to.

 *

 * @param[in]      cntrl_list     pointer to list of supported controllers.

 * @param[in]      path           path to block device in sysfs tree.

 *

 * @return Pointer to controller structure if successful, otherwise the function

 *         returns NULL pointer. The NULL pointer means that block devices is

 *         connected to unsupported storage controller.

 */

struct cntrl_device *block_get_controller(const struct list *cntrl_list, char *path);

/**

 * The global timestamp variable. It is updated every time the sysfs is scanning

 * by an application. The value stored in this variable should be used to update

 * all timestamp stored in block device structures.

 */

extern time_t timestamp;

/**

 * @brief Determines if block device is attached directly or via expander

 */

int dev_directly_attached(const char *path);

/**

 * @brief Gets the host structure for given control device and host_id

 */

struct _host_type *block_get_host(struct cntrl_device *cntrl, int host_id);

/**

 * @brief Checks the presence of block device.

 *

 * This is internal function of monitor service. The function is checking

 * whether block device is already on the list or it is missing from the list.

 * The function is design to be used as 'test' parameter for list_find_first()

 * function.

 *

 * @param[in]    bd_old          - an element from a list to compare to.

 * @param[in]    bd_new          - a block device being searched.

 *

 * @return 0 if the block devices do not match, otherwise function returns 1.

 */

int block_compare(const struct block_device *bd_old,

		  const struct block_device *bd_new);

#endif				/* _BLOCK_H_INCLUDED_ */