GB/T 42691.5-2023 道路车辆 局域互联网络（LIN） 第5部分：应用程序接口

Roadvehicles—LocalInterconnectNetw国家市场监督管理总局国家市场监督管理总局国家标准化管理委员会IGB/T42691.5—2023/ISO17987-5:2016 Ⅲ 12规范性引用文件 1 13.1术语和定义 13.2符号 1 14应用程序接口定义 2 2 24.3API约定 24.4节点配置及识别 4.5传输层 24 Ⅲ本文件为GB/T42691《道路车辆局域互V V1道路车辆局域互联网络(LIN)本文件规定了LIN应用程序接口(API)。本文件适用于LIN通信的应用程序接口定义。下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文ISO17987-2道路车辆局域互联网络(LIN)第2部分：传输协议和网络层服务[Roadvehicles—LocalInterconnectNetwork(LIN)—PaISO17987-3道路车辆局域互联网络(LIN)第3部分：协议规范[Roadvehicles—LocalInter-connectNetwork(LIN)—Part3.2符号下列符号适用于本文件API:应用程序接口(aplicationprogrammersOSI:开放式系统互联(opensystemsinterconnection)RX:收发器的接收引脚(Rxpinofthetransceiver)UART:通用异步收发器(universalasynchronousreceivertransmitter)24.2.4LIN传输层API4.3API约定3通知返回一个C布尔值指示通过静态API名字规定的标识的当前状态，即如果标识清除，函数为调度表提供时基此调用函数请求此集中连接到这个接口的从节点通过发出一个休眠命令进入总线此应用程序负责封装中断并设置正确的接口(如果中断可用)此应用程序负责封装中断并设置正确的接口(如果中断可用)此函数在从节点中使用，用于同步主节点发出的间隔场和同步字节场序列此调用函数分配所有从节点的配置NAD(节点诊断地址),匹配初始NAD,4此调用函数保存配置请求到给定配置NAD的特定从节点，或者如果设置的是广播NAD,会保存配置请求到所有从节点此调用函数序列化当前配置(配置NAD和PID)并且复制它到由应用层提供的此区域(数据指针)此调用函数请求所选的带配置NAD的从节点返回所分配此回调函数用于主节点通过标识符请求读取用此调用函数重新初始化未处理的或基于报文的接口原始API此调用函数排队一帧中数据的8字节传输，在下一次适当的主节点请求帧中发出此调用函数复制最早接收到的诊断帧到特定数据的内存中基于报文的API此调用函数让LIN诊断模块准备接收一个报文，并存储它到指定的数据缓存中此调用函数返回最后一个使用的调用函数状态给ld_sen此调用函数返回最后一个使用的调用函数状态给ld_receivd)1_u8无符号8位整型；e)1_u16无符号16位整型；表2定义了1_sys_init。5原型适用范围主节点和从节点1_sys_init执行LIN核心的初始化。初始化的范围为物理的节点，即整个节点(见ISO在使用其他API函数之前，此调用函数1_sys_init是LIN核心中首先要调用的用户应用0:如果初始化成功。a)1_bool用于1个位的信号，如果错误为0,否则非0;b)1_u8用于2位到8位的信号；c)1_ul6用于9位到16位的信号。适用范围主节点和从节点见GB/T42691.3—2023中5.1.26适用范围主节点和从节点见GB/T42691.3—2023中5.1.2动态原型1_u8*constdata);/*数据写入的位置*/静态原型适用范围主节点和从节点读取并返回信号中所选字节的当前值。起始和计数的总和不会大举例假定字节数组是6字节的长度，编号0到5,从此数组中读取字节2和3为2(跳过了字节0和1),计数为2(读取字节2和3)。此种情况下，字节3写入数据[1]1_u8start,/*写入的第一个字节*/1_u8count,/*写入的字节数量*/7适用范围主节点和从节点设置由信号名字sss规定的信号中所选字节的当前值为规定起始和计数的总和不大于字节数组长度，尽管设备驱动没有选择举例假定字节数组是7字节的长度，编号0到6,从此数组中写入字节3和4为3(跳过了字节0,1和2),计数为2(写入节3和4)。此种情况下，见GB/T42691.3—2023中5.1.2表7定义了I_flg_tst.此处的ff是标识的名字，如：1_flg_tst_RxEngineSpeed()适用范围主节点和从节点返回一个C布尔值，用于表明名为fff的标识当前的状态。如果该标识被清除了，则返回举例1_flg_tst的静态实现是：1_bool当IO_1(包含信号值位置)这一帧从该节点被成功传输后，这个标识就会被置位表8定义了1_flg_clr。8此处ff代指标识的名字，如：1_flg_clr_RxEngineSpeed()适用范围主节点和从节点表9定义了1_sch_tick。此处的iii指代接口名称和，如：1_sch_tick_MyLinIfc()适用范围仅适用于主节点1_sch_tick函数为LIN驱动提供了调度程序的时间基础。当一帧到期，它的传输就开始了。在当前进程结束后，1_sch_tick重新开始下一进程。在节点内1_sch_tick会被各个接口反复调用。该周期是时间基础，见5.3,在LDF中设置，见GB/T42691.2—2023中12.3.4.2。周期性的调用1_sch_tick,可以有效的设置时间基础，见GB/T42691.3—20保证时间基础周期最小抖动至关重要。调用1_sch_tick不仅会开始传送到期帧，还会更新前一次调用1_sch_如果下一次调用1_sch_tick没有开始传送帧，返回值为0。如果下一次调用1_sch_tick在下一调度表中开始了帧的传输，返回回值是下一个进程项在进程表中的编号(从调度表开始算起)。如果调度表中有N项，返回见GB/T42691.3—2023中5.3表10定义了1_sch_set。9GB/T42691.5—2023/ISO此处iii是接口的名称，例如：1_sch_set_MyLinIfe(MySchedulel,0)适用范围仅适用于主节点给接口ili在I_sch_tick函数后设置下一调度entry定义了新的调度表的开始进入点。如果调度表N个entry,entry的值范围是0到N。如果entry是0或1,新的调度表就会从头开始运行。存在一个提前定义好的调度表，L_NULL_SCHEDULE被用于停止所有的LIN从节点的举例entry值的一个可能的用法，是通过将其与1_sch_tick的返回值结合起来，实现临时中断当中断的地方继续运行见GB/T42691.3—2023中5.3接口管理调用对特定接口(连接总线的逻辑通道)的管理。每一个接口用唯一的接口名字来定义，由每个API调用的iii扩展名表示。如何设置接口名字(iii)不在本文件范围内。4.3.7.2I_jifc_表11定义了1_ifc_init。此处的ii指的是接口的名字，例如1_ifc_init_MyLinIfe()适用范围主节点和从节点_init默认设置的调度表是L_NULL_SCHEDULE,它不会这是用户在使用任何其他LINAPI函数前调用的第一个函数。一个关于接口概念的综述性的描述可以参考ISO17表12定义了1_ifc_goto_sleep。表12I_ifc_goto_sleep动态原型静态原型这里的l指的是接口的名字，例如I_ifc_goto_sleep_MyLinIfc()适用范围仅适用于主节点令，见GB/T42691.2—2023中5.4。当下一个调度表入口到期时，这个进入休眠状态的命令会这个1_ifc_goto_sleep函数不会影响到电源模式，它如果进入休眠模式的命令成功传输，则状态寄存器中的进入休眠位会被置位，见表13定义了1_ifc_wake_up。此处的Ⅲ指的是接口的名字，例如I_ifc_wake_up_MyLinIfc()适用范围主节点和从节点该函数传送一个唤醒信号。当该函数被调用，唤醒信号会立刻被发送。按照ISO17987-2中的唤醒队列定义，应用程序负责转发唤醒信号表14定义了1_ifc_ioctl。表14I_ifc_ioctl此处的l指的是接口的名字，例如1_ifc_ioctl_MyLinIfc(MyOp,&MyPars)适用范围主节点和从节点该函数控制了其他API调用没能覆盖的功能。它用于特定的协议参数或特定的硬件功这类功能的一个例子是打开或关闭唤醒信号检测。“i”是op中定义的操作的接口名。指针pv指向一个为该函数提供的可选参数。表15定义了1_ifc_rx。此处的il指的是接口的名字，例如1_jifc_rx_MyLinlfc()适用范围主节点和从节点应用程序负责绑定中断和设置正确的接口处理(如果使用中断).对基于UART的应用，它被一个用户定义的中断处理器调用，该中断处理收到一个字符数据后被触发。在这种情况下，该函数会对UART的控制寄存器执行必要的对于更复杂的LIN硬件，被用于表明接收到一表16定义了1_ifc_tx。这里的il指的是接口的名字，例如1_ifc_tx_MyLinlfe()适用范围主节点和从节点应用程序负责绑定中断和设置正确的接口处理(如果使用中断对基于UART的应用，它被一个用户定义的中断处理器调用，该中断处理收到一个字符数据后被触发。在这种情况下，该函数会对UART的控制寄存器执行必要的对于更复杂的LIN硬件，它被用于表明一表17定义了1_ifc_aux。表17I_ifc_aux此处的iii指的是接口的名字，例如1_ifc_aux_MyLinIfc()适用范围主节点和从节点表17I_ifc_aux(续)此函数用于从节点同步到由主节点发送的名为il接口的间隔场或同步字节场。举例来说，它是被一个用户定义的中断处理器调用的。该中断处理器是被接的硬件引脚上的边沿检测触发的。1_ifc_aux仅用于从节点。该功能是与硬件和实际实现强相关的，并且其用法是依赖于实现的表18定义了1_ifc_read_status。此处的ii是接口的名字，例如1_ifc_read_status_MyLinlfc()适用范围主节点和从节点。主节点和从节点的行为是不同的该函数返回之前的通信状态。该调用返回的状态字(1表19定义了1_ifc_read_status的返回值(bit15为MSB,bit0为LSB)。98765432100帧冲突总线溢出成功GB/T42691.5—202同时使用1_sch_tick的返回值。在从节点中，该位通常置0。如果主节点在解决冲突的过程中切换了调度表，事件触发帧冲突位会置0。下面例子可以看出该位是如何置位的。当成功接收保存配置请求时，状态字返回值会置为保存配置，参考GB/T42691.3—2023中的6.3.5。该位只会在从节点中置位，主节点中通常置0。最后一帧PID是总线上最后检测并且节点最后处理的PID。如果溢出位置1或者最后一帧PID很多值丢失，只有最新的值会保存。这会同时将发送成功或响应错误置位。发送成功和响应错误两个状态位的组合情况可以根据表20解释。表20节点内部错误解释响应错误发送成功0011间歇性通信(部分发送成功，部分失败)01完全通信10通信失败(只有失败的发送)处理个体的状态报告(见ISO17987-3)是节点应用的职责。表21事件触发帧调度表帧帧类型I0_1和I0_2无条件帧同IO_check相关联。冲突解决调度表中包含了无条件帧IO_1和IO_2(延迟设置为10ms)。冲突处理如图1所示。本例中基础时间设置为5ms。00001111000直接调用1_ife_read_status图1事件触发帧冲突解决实例表22定义了1_sys_irq_disable。原型适用范围主节点和从节点表23定义了1_sys_irq_restore。原型voidI_sys_irq_restore(l_irqm适用范围主节点和从节点该函数的用户实现将中断恢复到由之前提供的1_i表24定义了ldisready。原型适用范围仅适用于主节点表24ldisready(续)配置请求已经完成。这是一种介于配置请求和配置应答之配置请求和配置应答都已完成，即应答经过的错误配置应答图2显示了配置请求和配置响应成功完成的情况。在主节点请求帧和从节点响应帧传输完成之后1表25定义了ld_check_response。原型适用范围仅适用于主节点在参数RSID和error_code中，该调用返回最后的节值而不是error_code中的。RSID和4.4.2.3ld_assign_fram表26定义了ld_assign_frame_id_range。原型voidld_assign_frame_适用范围仅适用于主节点该调用将分配从节点中最多4帧的保护标识符，该标识符具有已配置见GB/T42691.3—2023中6.3.6.2表27定义了ld_assign_NAD。原型适用范围仅适用于主节点该调用将configured_NAD分配给同initial_NAD,supplier_id和funct节点4.4.2.5ld_save_confi表28定义了ld_save_configuration。原型适用范围仅适用于主节点通过给定的配置NAD,该调用会发送保存配置请求给特定从节见ISO17987-3中保存配置服务的定义。API调用1_ife_read_status见4.3.7.9,实例请参照4.4.2.6ld_read_confi表29定义了ld_read_configuration。原型适用范围仅适用于从节点该函数在总线上不传输任何信息。该调用将当前的配置序列化并将其复制到应用指定的区域(数据指针)。目的是当状态寄存器中保存配置请求标志置位的时候调用该函数，见4.3将数据存储在适当的内存中。在调用该函数之前，调用方在数据区域中保留长度相等的字节。函数将置的实际大小。如果数据区域太短，函数将不会有返回动作。如果之前调用ld_set_configuration时没有设置NAD或者主节点已经使用配置服务，返回数据包含了已配置的NAD及PID,每个参数占一个字节。数据结构是：先是已配置的NAD,然后是所有帧的PID。PID的顺序与LDF中的帧列表与NCF中的帧定义相如果服务是成功的。函数1_ifc_read_status见4.3.7.9,实例请参照4.64.4.2.7ld_set_confi表30定义了ld_set_configuration。原型适用范围仅适用于从节点该函数在总线上不传输任何信息。该函数根据数据给出的配置来配置NAD和PID,其目的是为了恢始配置(例如，I/0引脚编码)。该函数在调用1_ifc_init之后调用。调用者在调用该函数之前设置数据区域的长数据包含了已配置的NAD及PID,每个参数占一个字节。数据结构是：先是已配置的NAD,然后是所有帧的PID。PID的顺序与LDF中的帧列表与NCF中的帧定义相同函数1_ife_read_status见4.3.7.9,实例请参照4.6表31定义了ld_read_by_id。原型适用范围仅适用于主节点2023中表20关于ID的解释。当下一个ld_is_ready请求返回LD_SER见ISO17987-3中关于ReadByIde4.4.3.2ld_read_by_id表32定义了ld_read_by_id_callout。原型适用范围此调用是可选的，且仅在从节点中可用。如果使用了用户定义的标识点应用程序将实现此调用该id参数是用户定义区域(32到63)中的标识符，参见GB/T42691.3—2023中表18来自4.5.2原始API和基于报文的API由于ISO15765-2[4]CAN上的PDU与LIN诊断帧非常相似，所以提供了一个原表33定义了ld_init。表33ld_init原型适用范围主节点和从节点此调用(重新)初始化接口iii上的原始层或基于消息的层。所有传输层缓冲区都会被始如果有一个基于消息的或原始的消息的诊断帧正在在总线上传4.5.4原始API表34定义了ld_put_raw。原型适用范围主节点该调用在一帧中对8字节数据的传输进行排队。数据(MasterReq帧)。数据区域在调用中被复制，指针没有被记忆。原始的和基于报文的在API之外是没有区别的。传输层一般描述见ISO17987-2表35定义了ld_get_raw。原型适用范围主节点调用将最早接收到的诊断帧数据复制到数据指定的内存返回的数据从SlaveResp帧接收。如果接收队列为空，则不复制任何数据原始的和基于报文在API之外是没有区别的。传输层一般描述见ISO17987-2表36定义了ld_raw_tx_status。原型适用范围主节点该调用返回原始帧传输函数的状态传输队列为空。在之前调用ld_put_raw的情况下，队列中的所有原始的和基于报文的在API之外是没有区别的。传输层的一般描述见ISO17987-2表37定义了ld_raw_rx_status。原型适用范围主节点该调用返回原始帧接收函数的状态原始的和基于报文的在API之外是没有区别的。传输层的一般描述见ISO17987-2表38定义了ld_send_message。GB/T42691.5—2023/I原型适用范围主节点和从节点该调用将数据和数据长度指定的信息打包到一个或多个诊断帧中点应用程序，发送到从节点的帧包含地址NAD。如果此调用实现在从节点应用程序，发送到主节点的帧包含地址NAD。参数NAD不用于从节点。SID(或RSID)的值是数据区域中的第一个字节。DataLength的范围是1到4095字节。DataLength还包括SID(或RSID)值，调用是异步的，即在消息发送之前不挂起，并且只要ld_tx_status的调用返回LD_IN_GRESS,应用程序就不会更改缓冲区。数据将会在合适的帧中进行传输(主请求帧用于主节点，从响应帧用于从节点如果有一条消息正在处理中，则调用将不执行任何操作返回原始的和基于报文的在API之外是没有区别的。传输层的一般描述见ISO17987-24.5.5.3ld_receive_message表39定义了ld_receive_message。原型适用范围主节点和从节点该调用准备了一个LIN诊断模块来接收一条报文调用时，DataLength指定了允许的最大长度。接收完成后，DataLengthSID(或RSID)是数据区域中的第一个字节。DataLength的范围是1到4095字节，但不会超过调用中最初设置的值。SID(或R含在DataLength中。从节点中不使用参数NAD。调用是异步的，即在报文发送之前不挂起，并且只要ld_rx_status的调用返回GRESS,应用程序就不会更改缓冲区。如果在总线上的报文传输开始之后才进行调用(即SF或FF已经传输),则此报文将不会被接收。相反，该函数将等待下一条报文开始。数据将从后续适当的帧(主节点对从节点的主请求帧和从节点的响应帧)中接应用程序监视ld_rx_status,直到状态为LD_COMPLETED时才调用此原始的和基于报文的在API之外是没有区别的。传输层的一般描述可以在ISO17987-2中表40定义了ld_tx_status。原型适用范围主节点和从节点该调用返回最后一次调用的ld_send_messag传输已成功完成(可以发出一个新的ld_send_message调用)。此值也在化。要查明传输失败的原因，检查状态管理函数L_ifc_read_status,见4.3.7.9。原始的和基于报文的在API之外是没有区别的。传输层的一般描述见ISO17987-2表41定义了ld_rx_status。原型适用范围主节点和从节点该调用返回最后一次调用的ld_receive_message接收尚未完成。接收已成功完成，所有信息(DataLength,NAD,data)可用。(也可以产生新的ld_message调用)。此值也在传输层初始化后返回。接收以错误结束，数据只被部分接收并且不可信。在进一步处理传输层报文之前初始化。由于N_Cr超时的接收失败，参见ISO17987-2。由于意外的序列号，接收失败原始的和基于报文的在API之外是没有区别的。传输层的一般描述见ISO17987-2/**关关苦关号关暑关关关关苦关****兴兴**兴*关关兴关关关关关关关共著关共**关吴关***#defineINT_ENABLE_/*暑暑暑吴号关吴暑关罢关吴暑关吴吴吴暑吴关吴关吴号吴吴兴暑吴吴兴共兴兴☆*兴**兴*兴号兴*兴关*Description:Restorestheinterruptmasktotheonebefvoid1_sys_irq_restore(l_irqmaskpreviou{/**兴兴关暑暑*暑关关关暑兴暑号兴兴兴兴兴兴*暑兴号兴暑暑暑兴暑DisabletheUARTinterruptsd关*Returnvalue:Th***兴**关*关关关关**关关*关关*关关*关关*关**关关*关关*关关关*关关关****关关*/{*Description:UARTreceivecharacteri关关关吴号关*号*☆*兴**兴*兴**关*共兴**兴*头兴兴*兴*关关关关*兴**关关号关关***/void__INTERRUPT/*Compilerintrinsic*/lin_char_rx_handler(void)/*JustcalltheLINAPIprovidedfunctiontodotheactualwo/*共吴关关关吴关吴关关吴吴关关吴兴关关关兴*关关关吴关关关关吴*关兴兴关共关共共关关关关*关关号**Returnvalue{/*InitializetheLINin/*TheinitoftheLIN}/*InitializationoftheLINinterfacefailed-cal/*Setthenormalsc/*号吴暑关号号暑兴*兴*兴暑兴兴兴暑兴兴兴*兴*兴****暑*兴兴兴兴兴兴兴暑兴暑兴号兴*/*In/outputofsignals.Callitfirstinthetasktominimizejitter/*Dosomeapplication/*Justasmallexampleif(1_flg_tst_RxInternalLigh{/*signalreadingandwriti1_u8_wr_InternalLightsRequest(}*ThestaticLINA吴关吴吴关号兴兴兴*兴*****关**吴关兴关*兴*兴*关*关关关void__INTERRUPT/*Compilerintrinsic*/lin_char_rx_handler(void){/*JustcalltheLINAPIprovidedfunctiontodotheactualwo/**兴*兴*兴兴暑兴暑暑关暑**暑号景号关景景暑景景暑暑*暑号号景兴景景景