-- require libmgmt_protocol 库
local libmgmt_protocol = require 'libmgmt_protocol'

-- 各组件定义所属硬件的访问协议配置文件
local config_obj = require 'path.to.config.obj'

-- 根据文件创建可访问对象
-- 若配置有问题这里会抛异常
local obj = libmgmt_protocol.device_spec_parser(config_obj)

-- 根据配置文件的具体值获得对应硬件属性值
-- 对于单次访问返回值的属性，需要调用:value()获取具体的值
-- 若属性不存在或者无法获取属性值:value()会返回nil
-- 入参为配置请求数据的补充，若冲突则不会覆盖配置中的请求数据
local on_demand_property = obj:OnDemandProperty({data = 'some data'}):value()

-- 对于轮询访问的属性，返回体为scheduler对象
-- 若请求数据不需要变化，则不用传入任何数据
local on_schedule_property_scheduler = obj:OnScheduleProperty()
-- scheduler不会自动开启，需要手动调用:start()开启，同时会返回第一次获取的数据
local on_schedule_property = on_schedule_property_scheduler:start()
-- scheduler支持订阅数据变更信号，当获取数据不同于scheduler缓存数据时，会发送
-- on_data_change信号和新的数据
on_schedule_property_scheduler.on_data_change:on(function(data)
  print('new data received!')
end)
-- scheduler支持订阅错误信号，当每次轮询获取数据失败（nil）时，会发送on_error信号
on_schedule_property_scheduler.on_error:on(function()
  error('unable to read data from hardware!')
end)
-- scheduler支持更换入参，调用后下一次轮询时便会使用新的参数
on_schedule_property_scheduler:update_params({
  name = 'another_property_name', -- 新属性名
  protocol = 'new protocol', -- 新协议名称（暂不支持加载未使用过的协议）
  request = {...}, -- 协议所需的入参
})
-- scheduler支持更换轮询周期，调用后下一次轮询时便会使用新的参数
on_schedule_property_scheduler:set_period(10) -- 10s轮询一次

-- scheduler会根据配置的轮询周期一直访问数据，在不使用时需要调用:deconstruct()停止轮询访问
on_schedule_property_scheduler:deconstruct()

--对于不存在的属性，调用scheduler的任意函数都不会起效，用于在不确定属性是否存在时
local not_exist_property = obj:NotExistProperty()
not_exist_property:start()                    -- no op
not_exist_property.on_data_change:on(function()
  assert('never reach here')                  -- 此行永远无法到达
end)
not_exist_property.on_error:on(function()
  assert('never reach here')                  -- 此行永远无法到达
end)
not_exist_property:deconstruct()              -- no op

local a_network_adapter = {
  protocol_dependencies = {
    smbus = {           -- 所用通过I2C的协议都需要传入ref_chip对象，
      ref_chip = nil,   -- 通过hwproxy对硬件进行访问
      buffer_len = 64,  -- 协议支持的最大字节数
    },
    ncsi_huawei = {     -- 所有通过mctp的协议都需要传入endpoint对象，
      endpoint = nil    -- 通过mctpd对硬件进行访问
    }
  },
  properties = {
    ...
  }
}

return a_network_adapter

properties = {
  ChipTemp = {        -- 属性名，也是属性访问接口， obj:ChipTemp()
    protocol = 'smbus',   -- 协议名，必须是已支持的协议
    action = 'on_schedule',   -- 单次访问还是轮询访问
    period_in_sec = 2,      -- 轮询访问的周期，单位为秒
    request = {             -- 协议所需的请求数据，具体格式由各协议检查
      opcode = 0x3,         -- smbus协议需要的opcode
      expect_data_len = 2   -- smbus需要的返回数据长度
    },
    response = function(data) -- 返回数据解析函数，会去掉协议中协议的部分，data仅包括具体数据
      -- 仅在硬件正常返回响应时才会调用此函数，有错误时不会调用此函数
      local r = bs.new([[<<temp:16>>]]):unpack(data, true) -- 支持使用bitstring进行二进制解包
      return r.temp -- 返回值为obj:ChipTemp()的返回值
    end
  },
  MacAddressNCSI = {
    protocol = 'ncsi_huawei',
    action = 'on_demand',       -- 单次访问，单次访问不需要配置period_in_sec
    request = {
      huawei_cmd_id = 0x1,
      sub_cmd_id = 0x0
    },
    response = function(data)
      local r = bs.new([[<<
        _:8,
        mac_address_count:16/big,
        _:16,                     # libmgmt_protocol提供一些通用的bitstring格式，例如MAC_Address
        mac_addrs:8/MAC_ADDRESS    
      >>]], libmgmt_protocol.common_bs_helper):unpack(data, true) -- 在创建bs的时候直接传入即可
      return r.mac_addrs[1].mac_address
    end
  }
}

-- @function 构建函数
-- @param    request:table
function protocol:ctor(params)
  -- params为协议配置文件中的protocol_dependencies，由使用组件定义
  -- 例如mctp中需要传入endpoint，smbus需要传入ref_chip和buffer_len
  -- 需要与组件配置文件协同
end

-- @function 传输请求函数
-- @param    request:table
-- @return   binary|boolean|nil
function protocol:send_request(request)
  -- request为协议配置文件中各属性的request请求结构体，包括运行态和配置静态的结合体
  -- 返回响应体的具体数据，若配置文件中配置了响应解析函数，这里的返回数据为响应解析函数的入参
  -- 若请求失败，返回nil
  -- 若无需调用响应解析函数，则返回true代表发送成功
end

-- @function 传输请求函数
-- @param    request:table
-- @return   binary
function protocol:validate_request_params(request)
  -- request为协议配置文件中个属性的request请求结构体
  -- 在解析配置文件时会调用一次，入参为配置文件中的静态数据
  -- 在运行时会再调用一次，入参为运行时传入的动态数据，若为nil则不会调用
  -- 返回true才可继续传输，返回false则不会进行传输
end

-- ncsi_standard拼装函数只需要拼装ncsi标准协议的部分
function ncsi_standard:construct_request_data(ctx, request)
  return req_ctx, req_bin
end

-- ncsi_standard解析函数只需要解析ncsi标准协议的部分
function ncsi_standard:unpack_response_data(ctx, rsp_data_bin)
  return ...  
end

-- 将协议拼装和解包拆成独立的函数
function ncsi_standard:send_request(request)
  local req_ctx, req_bin = self:construct_request_data(ctx, request)
  local ok, rsp_data_bin = pcall(self.endpoint.Request, self.endpoint, req_ctx, req_bin, 0)
  return self:unpack_response_data(ctx, rsp_data_bin)
end

local ncsi_huawei = class(ncsi_standard)

-- ncsi_huawei重写基类封装函数，封装自己的部分，再调用基类封装函数
function ncsi_huawei::construct_request_data(ctx, request)
  local request_with_ncsi_huawei_info = ...
  return ncsi_huawei.super.construct_request_data(ctx, request_with_ncsi_huawei_info)
end

-- ncsi_huawei重写基类解析函数，代替基类函数直接返回自己的解析数据
function ncsi_standard:unpack_response_data(ctx, rsp_data_bin)
  return data
end

-- std_smbus硬件访问使用hwproxy的WriteRead函数
function std_smbus:send_and_receive(data, len)
  return pcall(function()
    return self.ref_chip:WriteRead(ctx:new(), data, len)
  end)
end

-- 将硬件访问拆成独立的函数
function std_smbus:send_request(request)
  ...
  local ok, rsp_bin = self:send_and_receive(data, len)
  ...
end

local smbus_5902 = class(std_smbus)

-- smbus_5902要求在发送之前检查硬件是否可以访问，所以必须将Write和Read单独发送
-- 可以通过重写基类硬件访问函数，加入自己所需的步骤
function smbus_5902:send_and_receive(data, len)
  if self:check_idle() then
    self:send(data)
    if self:check_idle() then
      return self:receive(len)
    end
  end
end

-- std_smbus允许arg和data参数
local request_params_template<const> = {
  opcode = true,
  expect_data_len = true,
  arg = true,
  data = true
}

-- 在构建函数时存储request_params_template
function std_smbus:ctor()
  self.request_params_template = request_params_template
end

-- 将request_params_template独立出来
function std_smbus:validate_request_params(request)
  for key in pairs(req) do
    if not self.request_params_template[key] then
      return false
    end
  end
  return true
end

local smbus = class(std_smbus)

local request_params_template<const> = {
  opcode = true,
  expect_data_len = true
}

-- 在构建时会先调用基类构建函数，再调用子类构建函数
-- 在这里存储request_params_template即可覆盖，在调用validate_request_params时
-- 会使用本地的request_params_template
function smbus:ctor()
  self.request_params_template = request_params_template
end